Zhin.js：现代化 TypeScript 聊天机器人框架全面解析

项目简介

Zhin.js 是一个现代化的 TypeScript 聊天机器人框架，自 2022 年 8 月 17 日创建以来，已在 GitHub 上积累了 126 颗 Star。项目采用 MIT License 开源，致力于为开发者提供一个AI 驱动、插件化、支持热重载、多平台的聊天机器人开发解决方案。

与传统的机器人框架不同，Zhin.js 从设计之初就拥抱了现代前端生态的开发范式——Hooks 风格的 API、AsyncLocalStorage 上下文管理以及 monorepo 架构，使其在 TypeScript 类型推导和开发体验上都表现出色。无论你是想快速搭建一个 QQ 群机器人，还是需要在多个平台上部署 AI 智能体，Zhin.js 都能满足你的需求。

核心亮点一览

核心特性详解

🤖 AI 驱动：内置智能体系统

Zhin.js 内置了 ZhinAgent 智能体系统，这是框架最引人注目的特性之一。它不仅仅是简单地调用大模型 API，而是提供了一套完整的 AI 能力框架：

• 多模型接入：原生支持 OpenAI、Ollama 等主流大语言模型，可灵活切换
• 多轮对话：内置会话管理，支持上下文记忆的多轮对话
• 工具调用（Function Calling）：AI 可以调用开发者注册的工具来完成复杂任务
• 6 层安全防御：针对 AI 执行的 Bash 命令，设计了纵深防御体系，确保安全可控
• 文件化能力：支持通过
  textCopy

  *.tool.md

  、
  textCopy

  SKILL.md

  、
  textCopy

  *.agent.md

  等 Markdown 文件声明 AI 的工具和技能

这意味着你可以轻松地将 ChatGPT 或本地部署的 Ollama 模型集成到你的机器人中，让它具备真正的"智能"。

🔌 插件化架构：Hooks 风格 API

如果你熟悉 React Hooks 或 Vue Composition API，那么 Zhin.js 的插件系统会让你感到非常亲切：

typescriptCopy
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()
})

核心设计理念：

• textCopy

  usePlugin()

  Hooks：每个插件通过
  textCopy

  usePlugin()

  获取上下文，注册命令、中间件、事件监听等
• AsyncLocalStorage 上下文管理：利用 Node.js 的 AsyncLocalStorage，在异步调用链中安全地传递插件上下文
• 零耦合组合：插件之间彼此独立，通过统一的 Feature 体系进行组合

♻️ 智能热重载

开发机器人时最烦恼的事情之一就是"改一行代码要重启整个服务"。Zhin.js 彻底解决了这个问题：

• 代码变更自动检测：监听文件系统变更，自动重新加载修改的插件
• 配置热更新：修改配置文件后自动生效，无需手动重启
• 错误自动回滚：如果新版本的插件加载出错，自动回滚到之前正常工作的版本
• 状态保持：热重载过程中，机器人的连接状态和运行数据不会丢失

这在开发阶段能极大地提升效率——你可以一边写代码，一边在聊天窗口中实时测试效果。

🌐 多平台支持

Zhin.js 通过适配器（Adapter） 模式支持 16+ 即时通讯平台，一套代码即可在多个平台上运行。详细的适配器列表见后文。

🧩 Feature 体系：统一的功能抽象

Zhin.js 抽象了一套 Feature 体系，将各种功能统一为以下几类：

• 命令（Command）：用户发送指令触发的功能
• 工具（Tool）：AI 可调用的工具
• 技能（Skill）：AI 的能力描述
• 定时任务（Schedule）：基于 cron 表达式的定时功能
• 数据库（Database）：统一的数据持久化接口

这种抽象使得功能开发高度标准化，不同类型的功能遵循统一的生命周期和注册方式。

🎯 TypeScript 原生支持

Zhin.js 从底层到上层全部使用 TypeScript 编写，提供：

• 完整的类型推导：命令参数、事件回调、中间件签名等都有严格的类型定义
• 泛型支持：适配器、消息类型等支持泛型参数
• 智能提示：在 VS Code 等编辑器中获得完善的代码补全和错误检查

🖥️ Web 控制台

内置的 Web 控制台提供了可视化的管理界面：

• 实时监控：查看机器人的运行状态、消息吞吐量、内存使用等
• 插件管理：在线启用/禁用/配置插件
• 日志查看：实时查看运行日志，快速定位问题

快速开始

环境要求

• Node.js: 20.19.0+ 或 22.12.0+
• pnpm: 9.0+

创建项目

使用脚手架快速创建一个新项目：

bashCopy
npm create zhin-app my-bot
cd my-bot
pnpm dev

执行

pnpm dev

目录结构

创建的项目大致结构如下：

textCopy
my-bot/
├── plugins/          # 自定义插件目录
│   └── hello.ts      # 示例插件
├── zhin.config.yml   # 主配置文件
├── package.json
└── tsconfig.json

在

zhin.config.yml

yamlCopy
plugins:
  - hello

插件开发示例

基础命令插件

下面是一个完整的命令插件示例：

typescriptCopy
import { usePlugin, MessageCommand } from 'zhin.js'

const { addCommand } = usePlugin()

addCommand(
  new MessageCommand('hello <name:string>')
    .desc('打个招呼')
    .action((_, result) => `Hello, ${result.params.name}!`)
)

运行后，在任何已接入的聊天平台发送

hello World

Hello, World!

带选项的命令

typescriptCopy
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}`
    })
)

事件监听

typescriptCopy
import { usePlugin } from 'zhin.js'

const { onEvent } = usePlugin()

// 监听群成员加入
onEvent('group.member.add', (adapter, bot, event) => {
  bot.sendMessage(event.group_id, `欢迎 ${event.user_name} 加入群聊！`)
})

AI 智能体系统

Zhin.js 的 AI 系统是其最具特色的功能之一。它不仅支持简单的问答，还提供了完整的智能体编排能力。

配置 AI 引擎

在

zhin.config.yml

yamlCopy
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              # 未知命令交互式审批

框架内置了 ModelRegistry，可以自动发现可用模型并选择最优配置，大大降低了使用门槛。

注册 AI 工具

通过

addTool

typescriptCopy
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`
})

注册后，当用户对 AI 说"帮我查一下北京的天气"，AI 会自动识别意图并调用

get_weather

文件化能力声明

Zhin.js 支持通过 Markdown 文件来声明 AI 的能力，实现零代码/轻代码的 AI 扩展——无需编写 TypeScript，只需在约定目录放置文件，框架即可自动发现并注册。

*.tool.md

markdownCopy
---
name: greeting
description: 向用户问好
parameters:
  name:
    type: string
    description: 用户名称
    required: true
---
你好，{{name}}！欢迎使用 Zhin.js 🎉

body 中的

{{param}}

handler: ./handler.ts

SKILL.md

markdownCopy
---
name: code-review
description: 代码审查助手
keywords: [review, lint, best-practice]
tags: [dev]
tools: [read_file, grep_search]
always: false
---
你是一个代码审查专家，请对用户提供的代码进行审查……

*.agent.md

markdownCopy
---
name: translator
description: 多语翻译助手
model: gpt-4o
maxIterations: 5
tools: [web_search]
---
你是一名专业翻译，精通中英日三语互译……

框架按

cwd/

~/.zhin/

data/

tools/

skills/

agents/

这种文件化的方式让 AI 的行为可审计、可版本控制，也更便于团队协作。

AI 引擎架构概览

textCopy
@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

@zhin.js/agent

多平台适配器一览

Zhin.js 的多平台支持是通过适配器（Adapter） 实现的。目前已支持以下 16+ 平台：

这种广泛的平台覆盖意味着你可以用同一套代码逻辑，同时服务于 QQ 群、Discord 服务器、Telegram 群组、钉钉工作群等不同场景，极大地降低了多平台机器人的开发和维护成本。

丰富的插件生态

Zhin.js 拥有一个活跃且不断壮大的插件生态，涵盖服务层、工具层、功能层和娱乐层。

服务类插件（Services）

实用工具插件（Utils）

Zhin.js 提供了大量开箱即用的实用工具：

• 60s 新闻：每日推送 60 秒读懂世界新闻
• 签到：群聊签到功能，支持积分累计
• 代码运行：在聊天中执行代码片段
• 群管：群管理工具（禁言、踢人、公告等）
• 群日报：自动生成群聊每日摘要
• HTML 渲染：将 HTML 内容渲染为图片发送
• 链接海报：将网页链接生成预览海报
• 音乐：搜索并分享音乐
• 二维码：生成二维码
• 复读：智能复读机功能
• RSS：RSS 订阅推送
• 敏感词过滤：消息内容敏感词检测与过滤
• 短链接：长链接转短链接
• 统计：消息统计与数据分析
• 教学：自定义问答教学
• 语音：语音消息处理与 TTS

功能类插件（Features）

• 进程监控：监控机器人进程状态，异常自动告警

游戏插件（Games）

框架还支持交互式游戏插件，让群聊更有趣。

项目架构

Zhin.js 采用 monorepo 结构组织代码，各模块职责清晰：

textCopy
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/）

提供框架运行所需的基础设施：

• logger：统一的日志系统，支持多级别输出和格式化
• database：数据库抽象层，提供统一的数据访问接口
• schema：数据校验模块，确保配置和输入的正确性
• cli：命令行工具，提供脚手架和项目管理能力

内核层（packages/kernel）

运行时内核，负责插件的加载、生命周期管理、热重载机制、事件总线等核心能力。

AI 层（packages/ai + packages/agent）

• ai：AI 引擎，封装了与大语言模型的通信、Token 管理、流式输出等
• agent：Agent 编排引擎，支持多 Agent 协作、工具链调用、会话管理

核心层（packages/core）

IM 框架核心，定义了消息、适配器、机器人等核心抽象，是连接内核与适配器的桥梁。

前端层（packages/client）

Web 控制台的前端应用，基于现代前端技术栈构建，提供可视化的管理界面。

主入口（packages/zhin）

zhin.js

安全模型：6 层纵深防御

Zhin.js 在 AI 安全方面做了深入的设计（参考 Claude Code 安全架构），尤其是针对 AI 执行 Bash 命令的场景，建立了 6 层纵深防御体系：

sudo

eval

dd

full

FOO=bar rm

rm

timeout 10 rm

rm

ls && rm -rf /

ls

rm

cat

grep

ls

execAsk: true

ask_user

此外，Zhin.js 还在文件访问层面提供了文件访问策略和设备路径拦截，从多个维度保障系统安全。

安全配置示例

yamlCopy
ai:
  agent:
    execSecurity: allowlist    # 执行策略：deny / allowlist / full
    execPreset: network        # 预设白名单：readonly / network / development
    execAsk: true              # 未知命令交互式审批

这 6 层防御层层递进，形成了完整的安全闭环，确保即使 AI 被恶意利用，也无法对系统造成实质性损害。

常用命令速查

Zhin.js 提供了丰富的 CLI 工具来简化日常操作：

bashCopy
# 运行
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                # 交互式配置向导

总结与展望

为什么选择 Zhin.js？

1. AI 原生：不是后期"加上 AI"，而是从架构设计开始就为 AI 能力预留了空间
2. 开发体验极致：Hooks API + 热重载 + TypeScript，开发效率拉满
3. 生态丰富：16+ 平台适配器、几十个官方插件，开箱即用
4. 安全可靠：6 层纵深防御体系，让 AI 能力的使用安全可控
5. 社区活跃：持续更新迭代，积极响应社区需求

适合的场景

• 企业内部机器人：接入钉钉/飞书，打通内部工作流
• 社区运营：QQ 群/Discord 服务器的自动化管理与互动
• AI 助手：基于大语言模型的智能客服/问答系统
• 多平台消息聚合：将多个平台的消息统一管理和处理
• 个人项目：快速搭建功能丰富的个人机器人

展望

Zhin.js 仍在积极开发中，未来的方向包括：

• 更多平台适配器的接入
• AI Agent 编排能力的增强
• 插件市场的建设
• 更完善的文档和教程
• 更强大的 Web 控制台

如果你正在寻找一个现代化、功能全面的 TypeScript 聊天机器人框架，Zhin.js 绝对值得一试。

相关链接：

• 📦 GitHub 仓库：zhinjs/zhin
• 📖 官方文档：zhin.js.org
• 💬 许可证：MIT License