Zhin.js

现代 TypeScript 聊天机器人框架 —— AI 驱动、插件化、热重载、多平台

核心特性

快速开始

环境要求

• Node.js 20.19.0+ 或 22.12.0+
• pnpm 9.0+（npm install -g pnpm）

创建项目

npm create zhin-app my-bot
cd my-bot
pnpm dev          # 开发模式（热重载）

脚手架会引导你选择运行时、数据库、聊天平台和 AI 提供商。

启动后可访问 Web 控制台：http://localhost:8086

Windows 用户 📌：遇到问题请参考 Windows 初始化指南。

基础用法

// src/plugins/hello.ts
import { usePlugin, MessageCommand } from 'zhin.js'

const { addCommand } = usePlugin()

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

在 zhin.config.yml 中启用插件：

plugins:
  - hello

插件开发、测试与发布

Zhin.js 提供完整的插件开发工具链：

# 创建插件
npx zhin new my-plugin        # 交互式创建插件模板

# 开发调试
pnpm dev                      # 热重载开发，终端直接输入消息测试

# 测试
pnpm test                     # 运行 Vitest 单元测试
pnpm test:watch               # 监听模式
pnpm test:coverage            # 生成覆盖率报告

# 构建与发布
npx zhin build                # 构建插件
npx zhin pub                  # 发布到 npm

其他用户安装你发布的插件：

npx zhin search <keyword>     # 搜索插件
npx zhin install <name>       # 安装插件
npx zhin info <name>          # 查看插件信息

📖 完整指南：插件开发、测试与发布

AI 智能体

Zhin.js 内置 AI 智能体系统，让机器人具备大模型对话和工具调用能力：

# zhin.config.yml
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              # 未知命令交互式审批

插件通过 addTool 注册 AI 可调用的工具：

const { addTool } = usePlugin()

addTool({
  name: 'get_weather',
  description: '查询指定城市的天气',
  parameters: {
    city: { type: 'string', description: '城市名称', required: true }
  },
  execute: async ({ city }) => `${city}：晴，25°C`
})

文件化 AI 能力（零代码 / 轻代码）

除了上述程序化注册，还可以在约定目录放置 Markdown 文件，框架自动发现并注册，无需编写 TypeScript。

Tool（*.tool.md）

tools/
├── greeting.tool.md          # 纯模板 Tool
└── weather/
    ├── weather.tool.md        # 带 handler 的 Tool
    └── handler.ts             # execute 逻辑

纯模板示例（greeting.tool.md）：

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

body 中的 {{param}} 会被参数值替换后直接作为返回。若需复杂逻辑，在 frontmatter 加 handler: ./handler.ts，指向一个默认导出函数。

Skill（SKILL.md）

skills/
└── code-review/
    └── SKILL.md

---
name: code-review
description: 代码审查助手
keywords: [review, lint, best-practice]
tags: [dev]
tools: [read_file, grep_search]
always: false          # true = 常驻注入；false = 按需激活
---
你是一个代码审查专家，请对用户提供的代码进行审查……

Agent 预设（*.agent.md）

agents/
└── translator.agent.md

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

发现顺序

框架按 cwd/ → ~/.zhin/ → data/ → 已加载插件包根 的顺序扫描 tools/、skills/、agents/ 目录，同名先发现者优先；工作区内的文件变更支持热重载。

📖 详见：AI 模块 · 工具与技能

安全模型

AI 执行 bash 命令时受 6 层纵深防御 保护（参考 Claude Code 安全架构）：

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 …
└── 子任务 / 用户画像 / 定时跟进 / 引导文件

多平台适配器

常用命令

# 运行
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 workspace 单仓多包管理（无 git submodule）：

zhin/                          # 主仓库 (github.com/zhinjs/zhin)
├── basic/                     # 基础层（独立 npm 包目录）
│   ├── cli/                   #   CLI 工具       (@zhin.js/cli)
│   ├── database/              #   数据库抽象
│   ├── logger/                #   日志系统
│   └── schema/                #   Schema 校验
├── packages/                  # 核心层
│   ├── kernel/                #   运行时内核
│   ├── ai/                    #   AI 引擎
│   ├── core/                  #   IM 框架
│   ├── agent/                 #   Agent 编排
│   ├── client/                #   Web 控制台
│   ├── satori/                #   渲染引擎
│   ├── create-zhin/           #   项目脚手架
│   └── zhin/                  #   主入口包
├── plugins/                   # 插件生态（适配器 / 服务 / 特性 / 工具）
├── docs/                      # VitePress 文档站
└── examples/                  # 示例项目

📖 详见：仓库结构与模块化约定 · 单仓库迁移说明

贡献者

git clone https://github.com/zhinjs/zhin.git
cd zhin
pnpm install && pnpm build
pnpm dev

📖 详见：贡献指南

许可证

MIT License