快速开始

5 分钟在本地跑通首个机器人：创建项目 → 启动 Host → 连接 Remote Console → 在 Sandbox 发出 hello。可选再写第一个插件或接入真实平台。

TypeScript 多通道 IM Bot 框架 + 可选 Agent 栈。完整资源见 生态与资源。

三种入口（任选）

路径	说明
demo.zhin.dev	零安装在线 Sandbox
npm create zhin-app -y	独立项目（本页下方步骤）
minimal-bot	monorepo 贡献者调试

前置要求

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

node -v   # v20.19.0+
pnpm -v   # 9.0+

没有 pnpm？npm install -g pnpm

1. 创建项目

npm create zhin-app my-bot -y

-y 使用首跑黄金路径：Node.js + YAML + Host API + Sandbox。默认不启用 AI，因此不需要 Ollama 或任何云模型 Key。

2. 启动

cd my-bot
pnpm dev

看到类似输出说明启动成功：

[INFO] 数据库已连接
[INFO] HTTP 服务启动在 http://127.0.0.1:8086
[INFO] 适配器 sandbox 已就绪

3. 打开 Console 并发送第一条消息

打开 console.zhin.dev：

1. API Base 填 http://127.0.0.1:8086
2. Token 填 .env 里的 HTTP_TOKEN
3. 进入 Sandbox / 沙盒 页，连接后发送 hello，再试 card

收到回复说明一切正常。hello 回复会提示如何启用 AI（npx zhin setup --ai）。

如果 Console 连不上，先在项目根运行：

npx zhin doctor

常见问题见 疑难排查。

4. 写你的第一个插件

在 src/plugins/ 下创建 hello.ts：

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

const { addCommand } = usePlugin()

addCommand(new MessageCommand("hello").desc("打招呼").action(() => "你好！🤖"))

addCommand(new MessageCommand("echo <text>").desc("复读").action((_, r) => r.params.text))

保存文件，机器人自动热重载。在沙盒发送 hello 或 echo 测试，立刻收到回复。

注意：usePlugin() 必须在文件顶层调用，不能放在函数或回调里。详见 常见陷阱。

下一步任务

目标	入口
更完整的首跑截图式说明	5 分钟首跑
安装并启用插件	安装插件
开发、测试、发布插件	插件生命周期
接入 QQ / Discord / Telegram 等平台	平台适配器
启用 AI 对话与工具调用	AI 模块
解决安装、Console、Token、端口问题	疑难排查

接入真实平台

Sandbox 只是调试用。接入真实平台只需两步：

1. 安装并启用适配器：npx zhin install @zhin.js/adapter-discord
2. 创建 Endpoint：npx zhin setup --adapters

所有平台的配置方式见 平台适配器。

启用 AI（可选）

npx zhin setup --ai
pnpm install
pnpm dev

重启后按向导里的触发方式对话。详见 AI 模块。

常见陷阱

陷阱	说明
usePlugin() 放在函数里	❌ 必须在文件顶层调用，否则 AsyncLocalStorage 上下文丢失
getPlugin() 在运行时调用	❌ 只能在插件初始化时调用，不能在命令回调、中间件里调用
导入路径没加 .js	❌ TypeScript 本地导入必须写 import { x } from './y.js'
直接调 bot.$sendMessage()	❌ 必须走 Message.$reply 或 Adapter.sendMessage 发送链路

下一步

• 插件开发完整指南 — 命令、数据库、AI 工具、测试、发布
• 消息如何流转 — 一页搞清消息进出
• 配置文件 — 所有配置项
• 平台适配器 — QQ、Discord、Telegram 等各平台配置

Install tiers（zhin.js 4.x）

| 档位 | 安装 | 约 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` / `ModelRegistry`；请 `import from 'zhin.js/agent'` 或 `zhin.js/ai`。详见 [ADR 0019](/adr/0019-install-size-layering)。

| 用途 | 包 / 子路径 |
|------|-------------|
| Plugin、命令、`MessageCommand` | `zhin.js` |
| `ZhinAgent`、`AIService`、`registerAIHook`、`initAgentModule` | `zhin.js/agent` 或 `@zhin.js/agent` |
| `ModelRegistry`、`agentLoop`、`AIProvider` 类型 | `zhin.js/ai` 或 `@zhin.js/ai` |