深入解析 Zhin.js —— 一个 AI 驱动、插件化、支持热重载的现代 TypeScript 聊天机器人框架，覆盖 16+ 即时通讯平台
凉菜
作者
Zhin.js 是一个现代化的 TypeScript 聊天机器人框架，自 2022 年 8 月 17 日创建以来，已在 GitHub 上积累了 126 颗 Star。项目采用 MIT License 开源，致力于为开发者提供一个AI 驱动、插件化、支持热重载、多平台的聊天机器人开发解决方案。
与传统的机器人框架不同，Zhin.js 从设计之初就拥抱了现代前端生态的开发范式——Hooks 风格的 API、以及 ，使其在 TypeScript 类型推导和开发体验上都表现出色。无论你是想快速搭建一个 QQ 群机器人，还是需要在多个平台上部署 AI 智能体，Zhin.js 都能满足你的需求。
| 特性 | 说明 |
|---|---|
| 🤖 AI 驱动 | 内置 ZhinAgent 智能体，原生接入大语言模型 |
| 🔌 插件化架构 | Hooks 风格 API，灵活组合功能 |
| ♻️ 智能热重载 | 代码变更自动生效，无需重启服务 |
| 🌐 多平台支持 | 16+ 即时通讯平台适配器 |
| 🛡️ 安全纵深 | 6 层纵深防御体系，保障 AI 命令执行安全 |
| 🎯 TypeScript | 完整的类型推导与类型安全 |
| 🖥️ Web 控制台 | 实时监控与插件管理 |
Zhin.js 内置了 ZhinAgent 智能体系统，这是框架最引人注目的特性之一。它不仅仅是简单地调用大模型 API，而是提供了一套完整的 AI 能力框架：
*.tool.md、SKILL.md、*.agent.md 等 Markdown 文件声明 AI 的工具和技能这意味着你可以轻松地将 ChatGPT 或本地部署的 Ollama 模型集成到你的机器人中，让它具备真正的"智能"。
如果你熟悉 React Hooks 或 Vue Composition API，那么 Zhin.js 的插件系统会让你感到非常亲切：
import { usePlugin, MessageCommand } from 'zhin.js'
const { addCommand, addMiddleware } = usePlugin()
// 注册一个命令
addCommand(
new MessageCommand('echo <message:string>')
.desc('复读消息')
.action((_, result) => result.params.message)
)
// 添加中间件
addMiddleware((adapter, bot, message, next) => {
console.log(`[${adapter.name}] 收到消息: ${message.raw_message}`)
return next()
})import { usePlugin, MessageCommand } from 'zhin.js'
const { addCommand, addMiddleware } = usePlugin()
// 注册一个命令
addCommand(
new MessageCommand('echo <message:string>'
核心设计理念：
usePlugin() Hooks：每个插件通过 usePlugin() 获取上下文，注册命令、中间件、事件监听等开发机器人时最烦恼的事情之一就是"改一行代码要重启整个服务"。Zhin.js 彻底解决了这个问题：
这在开发阶段能极大地提升效率——你可以一边写代码，一边在聊天窗口中实时测试效果。
Zhin.js 通过适配器（Adapter） 模式支持 16+ 即时通讯平台，一套代码即可在多个平台上运行。详细的适配器列表见后文。
Zhin.js 抽象了一套 Feature 体系，将各种功能统一为以下几类：
这种抽象使得功能开发高度标准化，不同类型的功能遵循统一的生命周期和注册方式。
Zhin.js 从底层到上层全部使用 TypeScript 编写，提供：
内置的 Web 控制台提供了可视化的管理界面：
使用脚手架快速创建一个新项目：
npm create zhin-app my-bot
cd my-bot
pnpm devnpm create zhin-app my-bot
cd my-bot
pnpm dev执行 pnpm dev 后，机器人将以开发模式启动，并开启热重载功能。你可以立即开始开发插件。
创建的项目大致结构如下：
my-bot/
├── plugins/ # 自定义插件目录
│ └── hello.ts # 示例插件
├── zhin.config.yml # 主配置文件
├── package.json
└── tsconfig.jsonmy-bot/
├── plugins/ # 自定义插件目录
│ └── hello.ts # 示例插件
├── zhin.config.yml # 主配置文件
├── package.json
└── tsconfig.json在 zhin.config.yml 中启用插件：
plugins:
- helloplugins:
- hello下面是一个完整的命令插件示例：
import { usePlugin, MessageCommand } from 'zhin.js'
const { addCommand } = usePlugin()
addCommand(
new MessageCommand('hello <name:string>')
.desc('打个招呼')
.action((_, result) => `Hello, ${result.params.name}!`)
)import { usePlugin, MessageCommand } from 'zhin.js'
const { addCommand } = usePlugin()
addCommand(
new MessageCommand('hello <name:string>')
.desc运行后，在任何已接入的聊天平台发送 hello World，机器人将回复 Hello, World!。
import { usePlugin, MessageCommand } from 'zhin.js'
const { addCommand } = usePlugin()
addCommand(
new MessageCommand('weather <city:string>')
.desc('查询天气')
.option('-d, --detail', '显示详细信息')
.action(async (_, result) => {
const { city } = result.params
const detail = result.options.detail
// 调用天气 API
const weather = await fetchWeather(city)
if (detail) {
return `${city}天气详情：\n温度：${weather.temp}°C\n湿度：${weather.humidity}%\n风速：${weather.wind}m/s`
}
return `${city}：${weather.temp}°C，${weather.desc}`
})
)import { usePlugin, MessageCommand } from 'zhin.js'
const { addCommand } = usePlugin()
addCommand(
new MessageCommand('weather <city:string>')
.descimport { usePlugin } from 'zhin.js'
const { onEvent } = usePlugin()
// 监听群成员加入
onEvent('group.member.add', (adapter, bot, event) => {
bot.sendMessage(event.group_id, `欢迎 ${event.user_name} 加入群聊！`)
})import { usePlugin } from 'zhin.js'
const { onEvent } = usePlugin()
// 监听群成员加入
onEvent('group.member.add', (adapter, bot, event) =>Zhin.js 的 AI 系统是其最具特色的功能之一。它不仅支持简单的问答，还提供了完整的智能体编排能力。
在 zhin.config.yml 中配置 AI 模型：
ai:
enabled: true
defaultProvider: ollama
providers:
ollama:
host: "http://localhost:11434"
# models 可省略 — ModelRegistry 自动发现并选择最优模型
agent:
chatModel: '' # 留空自动选择（或指定如 qwen3:14b）
visionModel: '' # 留空自动选择视觉模型
execSecurity: allowlist # bash 执行策略：deny / allowlist / full
execPreset: network # 预设白名单：readonly / network / development
execAsk: true # 未知命令交互式审批ai:
enabled: true
defaultProvider: ollama
providers:
ollama:
host: "http://localhost:11434"
# models 可省略 — ModelRegistry 自动发现并选择最优模型
agent:
chatModel: '' 框架内置了 ModelRegistry，可以自动发现可用模型并选择最优配置，大大降低了使用门槛。
通过 addTool 注册可供 AI 调用的工具：
import { usePlugin } from 'zhin.js'
const { addTool } = usePlugin()
addTool({
name: 'get_weather',
description: '查询指定城市的天气信息',
parameters: {
city: { type: 'string', description: '城市名称', required: true }
},
execute: async ({ city }) => `${city}：晴，25°C`
})import { usePlugin } from 'zhin.js'
const { addTool } = usePlugin()
addTool({
name: 'get_weather',
description: '查询指定城市的天气信息',
parameters注册后，当用户对 AI 说"帮我查一下北京的天气"，AI 会自动识别意图并调用 get_weather 工具。
Zhin.js 支持通过 Markdown 文件来声明 AI 的能力，实现零代码/轻代码的 AI 扩展——无需编写 TypeScript，只需在约定目录放置文件，框架即可自动发现并注册。
*.tool.md — 工具定义文件
---
name: greeting
description: 向用户问好
parameters:
name:
type: string
description: 用户名称
required: true
---
你好，{{name}}！欢迎使用 Zhin.js 🎉---
name: greeting
description: 向用户问好
parameters:
name:
type: string
description: 用户名称
required: true
---
你好，{{name}}！欢迎使用 Zhin.js 🎉body 中的 {{param}} 会被参数值替换后直接作为返回。若需要更复杂的逻辑，可以在 frontmatter 中添加 handler: ./handler.ts 指向处理函数。
SKILL.md — 技能描述文件
---
name: code-review
description: 代码审查助手
keywords: [review, lint, best-practice]
tags: [dev]
tools: [read_file, grep_search]
always: false
---
你是一个代码审查专家，请对用户提供的代码进行审查……---
name: code-review
description: 代码审查助手
keywords: [review, lint, best-practice]
tags: [dev]
tools: [read_file, grep_search]
always: false
---
你是一个代码审查专家，请对用户提供的代码进行审查……*.agent.md — 智能体配置文件
---
name: translator
description: 多语翻译助手
model: gpt-4o
maxIterations: 5
tools: [web_search]
---
你是一名专业翻译，精通中英日三语互译……---
name: translator
description: 多语翻译助手
model: gpt-4o
maxIterations: 5
tools: [web_search]
---
你是一名专业翻译，精通中英日三语互译……框架按 cwd/ → ~/.zhin/ → data/ → 已加载插件包根 的顺序扫描 tools/、skills/、agents/ 目录，同名先发现者优先；工作区内的文件变更支持热重载。
这种文件化的方式让 AI 的行为可审计、可版本控制，也更便于团队协作。
@zhin.js/ai（通用引擎，与 IM 无关）
├── Provider — LLM 统一接口（OpenAI / Ollama / Anthropic / DeepSeek …）
├── Agent — 多轮 tool-calling 循环
├── Memory — 短期滑动窗口 + 长期链式摘要
├── CostTracker — Token 用量与成本追踪
└── FileStateCache / MicroCompact / ToolSearchCache — 性能优化层
@zhin.js/agent（IM 编排）
├── ExecPolicy — 6 层 bash 安全
├── FilePolicy — 文件访问策略与设备路径拦截
├── PromptBuilder — 10 段结构化系统提示词
├── 内置工具 — bash / read_file / ask_user / web_search …
└── 子任务 / 用户画像 / 定时跟进 / 引导文件@zhin.js/ai（通用引擎，与 IM 无关）
├── Provider — LLM 统一接口（OpenAI / Ollama / Anthropic / DeepSeek …）
├── Agent — 多轮 tool-calling 循环
├── Memory — 短期滑动窗口 + 长期链式摘要
├── CostTracker — Token 用量与成本追踪
└── FileStateCache / MicroCompact / ToolSearchCache — 性能优化层
@zhin.js/agent（IM 编排）
├── ExecPolicy — 6 层 bash 安全
├── FilePolicy — 文件访问策略与设备路径拦截
├── PromptBuilder — 10 段结构化系统提示词
├── 内置工具 — bash / read_file / ask_user / web_search …
└── 子任务 / 用户画像 / 定时跟进 / 引导文件整个 AI 系统分为两层：通用 AI 引擎（@zhin.js/ai）处理与大语言模型的通信，IM 编排引擎（@zhin.js/agent）则负责在聊天场景中协调 AI 的行为。这种分层设计使得 AI 引擎可以独立复用，不局限于聊天机器人场景。
Zhin.js 的多平台支持是通过适配器（Adapter） 实现的。目前已支持以下 16+ 平台：
| 适配器 | 平台 | 说明 |
|---|---|---|
| ICQQ | 基于 ICQQ 协议的 QQ 接入 | |
| QQ 官方 | 腾讯官方 QQ 机器人 API | |
| OneBot v11 | 通用 | 兼容 OneBot v11 协议（go-cqhttp 等） |
| OneBot v12 | 通用 | 兼容 OneBot v12 协议 |
| KOOK | KOOK | 原 开黑啦 语音平台 |
| Discord | Discord | Discord Bot API |
| Telegram | Telegram | Telegram Bot API |
| Slack | Slack | Slack Bot API |
| 钉钉 | 钉钉 | 钉钉机器人接入 |
| 飞书 | 飞书 | 飞书机器人接入 |
| 微信公众号 | 微信 | 微信公众号消息接入 |
这种广泛的平台覆盖意味着你可以用同一套代码逻辑，同时服务于 QQ 群、Discord 服务器、Telegram 群组、钉钉工作群等不同场景，极大地降低了多平台机器人的开发和维护成本。
Zhin.js 拥有一个活跃且不断壮大的插件生态，涵盖服务层、工具层、功能层和娱乐层。
| 插件 | 功能 |
|---|---|
| HTTP | HTTP 服务能力，为其他插件提供网络请求支持 |
| Console | Web 控制台，提供可视化管理界面 |
| MCP | Model Context Protocol 支持，扩展 AI 上下文能力 |
Zhin.js 提供了大量开箱即用的实用工具：
框架还支持交互式游戏插件，让群聊更有趣。
Zhin.js 采用 monorepo 结构组织代码，各模块职责清晰：
zhin/
├── basic/ # 基础层
│ ├── logger/ # 日志系统
│ ├── database/ # 数据库抽象层
│ ├── schema/ # 数据校验
│ └── cli/ # 命令行工具
│
├── packages/
│ ├── kernel/ # 运行时内核
│ ├── ai/ # AI 引擎
│ ├── core/ # IM 框架核心
│ ├── agent/ # Agent 编排引擎
│ ├── client/ # Web 控制台前端
│ └── zhin/ # 主入口包（zhin.js）
│
├── adapters/ # 平台适配器
│ ├── icqq/
│ ├── discord/
│ ├── telegram/
│ └── ...
│
└── plugins/ # 官方插件
├── services/
├── utils/
├── features/
└── games/zhin/
├── basic/ # 基础层
│ ├── logger/ # 日志系统
│ ├── database/ # 数据库抽象层
│ ├── schema/ # 数据校验
│ └── cli/ # 命令行工具
│
├── packages/
│ ├── kernel/ # 运行时内核
│ ├── ai/ # AI 引擎
│ ├── core/ # IM 框架核心
│ ├── agent/ # Agent 编排引擎
│ ├── client/ # Web 控制台前端
│ └── zhin/ # 主入口包（zhin.js）
│
├── adapters/ # 平台适配器
│ ├── icqq/
│ ├── discord/
│ ├── telegram/
│ └── ...
│
└── plugins/ # 官方插件
├── services/
├── utils/
├── features/
└── games/基础层（basic/）
提供框架运行所需的基础设施：
内核层（packages/kernel）
运行时内核，负责插件的加载、生命周期管理、热重载机制、事件总线等核心能力。
AI 层（packages/ai + packages/agent）
核心层（packages/core）
IM 框架核心，定义了消息、适配器、机器人等核心抽象，是连接内核与适配器的桥梁。
前端层（packages/client）
Web 控制台的前端应用，基于现代前端技术栈构建，提供可视化的管理界面。
主入口（packages/zhin）
zhin.js npm 包的入口，整合所有模块，对外暴露统一的 API。
Zhin.js 在 AI 安全方面做了深入的设计（参考 Claude Code 安全架构），尤其是针对 AI 执行 Bash 命令的场景，建立了 6 层纵深防御体系：
| 层级 | 防御机制 | 说明 |
|---|---|---|
| 第 1 层 | 危险命令黑名单 | sudo、eval、dd 等危险命令即使在 full 模式下也会被直接拦截 |
| 第 2 层 | 环境变量前缀剥离 | 识别并剥离环境变量前缀，如 FOO=bar rm 会被正确识别为 rm 命令 |
| 第 3 层 | 安全包装器剥离 | 识别并剥离 safe wrapper，如 timeout 10 rm 会被正确识别为 rm |
| 第 4 层 | 复合命令拆分检查 | 拆分复合命令逐段检查，如 ls && rm -rf / 会分别检查 ls 和 rm |
| 第 5 层 | 只读命令自动放行 | cat、、 等只读命令无需白名单即可执行 |
此外，Zhin.js 还在文件访问层面提供了文件访问策略和设备路径拦截，从多个维度保障系统安全。
ai:
agent:
execSecurity: allowlist # 执行策略：deny / allowlist / full
execPreset: network # 预设白名单：readonly / network / development
execAsk: true # 未知命令交互式审批ai:
agent:
execSecurity: allowlist # 执行策略：deny / allowlist / full
execPreset: network # 预设白名单：readonly / network / development
execAsk: true # 未知命令交互式审批这 6 层防御层层递进，形成了完整的安全闭环，确保即使 AI 被恶意利用，也无法对系统造成实质性损害。
Zhin.js 提供了丰富的 CLI 工具来简化日常操作：
# 运行
pnpm dev # 开发模式（热重载）
pnpm start # 生产模式
pnpm start -- -d # 后台守护进程
npx zhin stop # 停止后台进程
# 插件管理
npx zhin new <name> # 创建插件模板
npx zhin build # 构建插件
npx zhin pub # 发布插件到 npm
npx zhin search <keyword> # 搜索 npm 上的 Zhin 插件
npx zhin install <name> # 安装插件
# 诊断
npx zhin doctor # 检查环境和配置
npx zhin setup # 交互式配置向导# 运行
pnpm dev # 开发模式（热重载）
pnpm start # 生产模式
pnpm start -- -d # 后台守护进程
npx zhin stop # 停止后台进程
# 插件管理
npx zhin new <name> # 创建插件模板
npx zhin build # 构建插件
npx zhin pub # 发布插件到 npm
Zhin.js 仍在积极开发中，未来的方向包括：
如果你正在寻找一个现代化、功能全面的 TypeScript 聊天机器人框架，Zhin.js 绝对值得一试。
相关链接：
Conversation
使用 GitHub 账号登录即可发表评论
登录后即可发表评论
| 邮件 | 通过邮件协议收发消息 |
| Sandbox | 测试 | 本地测试沙箱 |
| Satori | 通用 | Satori 协议适配 |
| GitHub | GitHub | GitHub 事件通知 |
| Milky | Milky | Milky 平台适配 |
grepls| 第 6 层 | 交互式审批 | 开启 execAsk: true 后，未知命令会通过 ask_user 向用户确认后再执行 |