Zhin.js

TypeScript 多通道 IM Bot 框架
插件热重载 · Sandbox · Remote Console · 可选 Agent 栈

Documentation · Live Demo · Remote Console · Contributing

---

多通道 生活 / 工作助手 Bot 框架（私聊、群聊、记忆、定时、通知）——不是 Cursor / Claude Code 类 coding agent。默认仅 IM 核心（<10MB）；AI 按需加装。详见 能力分档。

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

const { addCommand } = usePlugin()

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

Quick Start

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

-y 走 IM-only 黄金路径：Sandbox + Host API + Remote Console，无需云模型 Key。

路径	适合谁
demo.zhin.dev	零安装体验
npm create zhin-app -y	独立项目（推荐）
examples/minimal-bot	贡献者 / monorepo 调试

然后打开 Remote Console，填 Host http://127.0.0.1:8086 与 .env 中的 HTTP_TOKEN，在 Sandbox 发 hello / card。

更多：5 分钟首跑 · npx zhin setup · npx zhin doctor

要求：Node.js ^20.19.0 或 >=22.12.0，pnpm 9+

Features

• IM 优先 — Plugin / Adapter / Endpoint、命令、热重载；pnpm add zhin.js <10MB
• 插件化 — usePlugin() Hooks + AsyncLocalStorage 上下文
• Remote Console — Host 只提供 API；UI 在 console.zhin.dev
• 可选 AI — @zhin.js/agent：对话、工具、MCP、安全 harness
• 多通道 — QQ / Discord / Telegram / Slack / GitHub 等，见 adapters
• 文件化创作面 — agent/tools、agent/skills、workspace agents（见 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	<10MB	Plugin、Adapter、Endpoint、命令、Sandbox
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                 # 开发（本仓默认 test-bot；用户项目用 create 生成物）
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 指向维护者厨房水槽 test-bot，非用户模板。

License

MIT