Zhin.js

一套代码，跑遍所有聊天平台的 TypeScript bot 框架
One codebase. Every chat platform. TypeScript.
多通道 · 按需 AI · Remote Console
_{Multi-channel · Opt-in AI · Remote Console}

Documentation · Live Demo · Remote Console · Contributing

Zhin.js 为在聊天平台做严肃 bot / 助手产品的开发者和团队而生（私聊、群聊、定时、通知、AI 对话），不是 Cursor / Claude Code 类 coding agent。三个核心词：

多通道 — 一套代码跑 20+ 平台（QQ / 微信 / Discord / Slack / 钉钉 / Telegram…），一个 bot 可同时挂多个账号、多个平台
按需 AI — 默认只是 <10MB 的 IM 框架；装上 @zhin.js/agent 就是完整 Agent（工具 / 记忆 / 编排 / MCP），装多少用多少
Remote Console — 浏览器里管 bot：发消息、改配置、看日志、管定时任务，全程不用碰代码

EN: Built for developers and teams running serious bot/assistant products on chat platforms. One codebase for 20+ platforms (QQ, WeChat, Discord, Slack, Telegram…) with multi-account support; starts as a <10MB IM framework and grows into a full agent (tools, memory, orchestration, MCP) only when you install @zhin.js/agent; manage everything from a browser console. Not a Cursor/Claude Code-style coding agent. See capability tiers.

// bot.ts — 整个机器人可以就是这一份文件
import { defineCommand } from 'zhin.js/command'
import { definePlugin } from 'zhin.js/plugin-runtime'

export default definePlugin({
  name: 'my-bot',
  setup({ addCommand }) {
    addCommand('hello', defineCommand({
      description: '打招呼',
      execute: () => 'Hello from Zhin!',
    }))
  },
})

Quick Start

三步，不用写适配器样板：

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

打开 Remote Console → Host 填 http://127.0.0.1:8086 → Sandbox 发 /hello。完事。

-y 走 IM 黄金路径：Sandbox + Host + Console，不需要任何模型 Key。

路径	适合谁	要多久
demo.zhin.dev	零安装点一点	立刻
`npm create zhin-app -y`	独立项目（推荐）	~1 分钟
`examples/single-file-bot`	看「一个 `bot.ts` 就是 bot」	克隆后 `pnpm --filter single-file-bot dev`
`examples/minimal-bot`	贡献者 / 约定目录样板	根目录 `pnpm dev`

更多：安装与启动 · 示例速览 · npx zhin setup · npx zhin doctor

要求：Node.js ^20.19.0 或 >=22.12.0（跑 Plugin Runtime 示例推荐 ≥22.6），pnpm 9+

Features

IM 优先 — 命令、组件、热重载；pnpm add zhin.js <10MB
插件化 — 文件约定 + 声明式 API（definePlugin / defineCommand / defineAdapter）
Remote Console — Host 只提供 API；UI 在 console.zhin.dev
可选 AI — @zhin.js/agent：对话、工具、MCP、安全策略
多通道 — QQ / 微信 / Discord / Telegram / Slack / GitHub 等，见 adapters
文件化创作面 — commands/、agent/tools、agent/skills（见 agent-authoring）

Stable / Advanced 能力分档

Tier	特性	说明
Stable	IM 核心	Sandbox + 命令 + Console
Stable	AI（可选）	`@zhin.js/agent` + provider
Stable	插件 / 热重载 / TypeScript	Hooks API、完整类型
Stable	安全（基础）	Bash allowlist、文件策略、审批
Advanced	多 Endpoint	IM / 邮件 / GitHub / Webhook…
Advanced	Feature / MCP / toolSearch	编排、deferred worker

Install tiers（zhin.js 4.x）

SSOT：docs/snippets/install-tiers.md · 在线：Install tiers

档位	安装	约 production 体积	能力
IM	`pnpm add zhin.js` + 适配器（如 `@zhin.js/adapter-sandbox`）；dev：`@zhin.js/cli`	<10MB（库包）	Plugin Runtime、命令/组件/适配器约定目录（Stable Features 由 `@zhin.js/core` 的 `zhin.features` 继承；Host 为 optional peer + `zhin.plugins`，见 ADR 0053）
AI	`+ @zhin.js/agent zod ai`	+~12–15MB	ZhinAgent、会话、工具、压缩
Provider	`+ @ai-sdk/openai` 等	按厂商	大模型调用
MCP	`+ @modelcontextprotocol/sdk`	+~数 MB	MCP Client / memoryMcp
Rich media	`+ @zhin.js/html-renderer`	+~数 MB	出站 `html` / `markdown` 转 PNG（未装则降级 text）
Speech	`+ @zhin.js/speech`	+~数 MB	入站 STT、出站 TTS、`segment.tts`（未装则 warn 降级）

Breaking（4.x）：import from 'zhin.js' 不再含 ZhinAgent / AIService；请 import from 'zhin.js/agent' 或 zhin.js/ai。详见 ADR 0019。

Windows：见 Windows 初始化指南。

Enable AI（optional）

pnpm add @zhin.js/agent zod ai
pnpm add @ai-sdk/openai   # 按需替换

# zhin.config.yml
ai:
  enabled: true
  providers:
    openai-main:
      sdk: openai
      apiKey: ${AI_API_KEY}
  agents:
    zhin:
      provider: openai-main
      model: gpt-4o-mini
  agent:
    execSecurity: allowlist
    execApprovalMode: ask

深入：AI 模块 · Agent 安全 · 工具与技能

Adapters

平台	包名	平台	包名
Sandbox（Stable）	`@zhin.js/adapter-sandbox`	QQ / ICQQ	`@zhin.js/adapter-icqq`
QQ 官方	`@zhin.js/adapter-qq`	NapCat	`@zhin.js/adapter-napcat`
OneBot 11 / 12	`@zhin.js/adapter-onebot11` / `onebot12`	Discord	`@zhin.js/adapter-discord`
Telegram	`@zhin.js/adapter-telegram`	Slack	`@zhin.js/adapter-slack`
KOOK / 钉钉 / 飞书	`kook` / `dingtalk` / `lark`	GitHub	`@zhin.js/adapter-github`
Email / 企微 / LINE	`email` / `wecom` / `line`	Satori / WeChat MP	`satori` / `wechat-mp`

完整说明：适配器文档 · plugins/adapters

Package Map

包	角色
`zhin.js`	IM 入口（4.x）
`@zhin.js/core`	Plugin / Adapter / Dispatcher
`@zhin.js/ai`	无 IM 的 AI 引擎
`@zhin.js/agent`	Agent 编排与安全
`@zhin.js/cli` · `create-zhin-app`	CLI / 脚手架

分层与依赖方向：架构概览 · 仓库结构

Documentation


入门	快速开始 · 路线与边界 · 稳定性承诺 · Docker · Windows
基础	核心概念 · 配置 · 命令 · 插件
进阶	AI · Agent 创作面 · 消息流
开发	插件开发 · 贡献 · 架构

站点：zhin.js.org

CLI

pnpm dev                 # 开发（本仓默认 minimal-bot；维护者回归用 pnpm dev:test）
npx zhin new my-plugin   # 插件模板
npx zhin setup           # 增量配置向导
npx zhin doctor          # 环境诊断
npx zhin search <kw>     # 搜插件

Contributing

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

见贡献指南。根目录 pnpm dev 指向 Stable 约定目录样板 minimal-bot；想看「一个文件就是 bot」用 pnpm --filter single-file-bot dev。厨房水槽用 pnpm dev:test（test-bot），非用户模板。

Repobeats

License

MIT