10 分钟跑通第一个 Bot
本页带你从 0 到 1 跑起一个 Zhin Bot,并直接在项目里加上带参数的命令、跨平台 JSX 互动按钮卡片和 AI 工具(1 → 2 进阶)。整个过程不需要平台账号,也不需要模型 Key。
还不清楚 Zhin.js 是做什么的?先花 5 分钟读 Zhin.js 是什么。
开始前
- 脚手架项目与编译后的 IM 库都需要 Node.js
>=22.19.0(@zhin.js/ai依赖的 undici 8 要求该版本)。 - pnpm 9 或更高版本。
1. 创建并启动
npm create zhin-app my-bot
cd my-bot
pnpm dev终端只问三件事:项目语言、项目名称、初始化令牌(默认随机生成,回车确认)。生成的是最小项目——IM 核心 + Console Host,不含数据库驱动、适配器和 AI 依赖;数据库、平台和 AI 都留到 Console 里配置。创建结束时会打印启动命令和一条 Console 链接:
✔ 项目已创建:my-bot
启动:cd my-bot && pnpm dev
然后打开 Console 完成初始化:
https://console.zhin.dev/?apiBaseUrl=http%3A%2F%2F127.0.0.1%3A8068#token=<初始化令牌>令牌只放在 # 之后,不会发送到 console.zhin.dev 的服务器。-y 表示全部接受默认值、一个问题都不问。
pnpm dev 就是 zhin start --foreground --watch source config:前台启动管理网关,网关再拉起 Zhin 实例(你的 Bot)。网关监听 HTTP 端口、负责 Console 登录与初始化;实例跑插件和适配器,改代码会热重载。Ctrl+C 同时停止两者。不想占着终端时用 npx zhin start(后台运行),再用 npx zhin status、npx zhin logs -f、npx zhin stop 管理,见 zhin start。
跳过 Console 里的适配器步骤
脚本或想直接试聊时,可以在创建时就装上 Sandbox(浏览器里的模拟聊天窗口):npm create zhin-app my-bot -- -y --adapter sandbox。--database、--adapter、--ai 等参数的完整说明见 create-zhin-app README。
2. 在 Console 里完成初始化
pnpm dev 启动后打开上面的链接(链接丢了就打开 console.zhin.dev,API Base 填 http://127.0.0.1:8068,令牌填 .env 的 HTTP_TOKEN)。端口以终端输出或 zhin.config.yml 的 http.port 为准。Console 会依次引导:
- 数据库:保持默认 SQLite 即可(文件在
.zhin/data.sqlite)。 - 所有者账号:设置用户名和密码并登录;此后初始化令牌失效,日常用账号登录。
- AI:这一页先跳过,之后再用
npx zhin setup --ai或 Console 打开。 - 聊天平台:选 Sandbox,不需要任何平台账号。
- 完成:汇总后进入首页。
每一步都可以跳过:AI 以后在「AI 与模型」设置,聊天平台在「账号与会话」的「接入新平台账号」接入。每一步用什么凭据、需要什么权限见 Console 初始化与引导。
3. 发送 /hello 验证
任选以下一种方式:
- 方式 A:Console 沙盒(推荐) 在上一步登录的 Console 里打开侧栏「会话 → 沙盒」,发送
/hello。 - 方式 B:独立 Sandbox 页面 浏览器打开
http://127.0.0.1:8068/sandbox。这个页面不走 Console 登录:完成上一步初始化(创建所有者)之后,.env里的HTTP_TOKEN已失效,需要一个 Console API 令牌——在 Console 顶栏用户名 →「个人设置」(/account)签发,粘贴到页面右上角后点「保存 Token 并重连」,状态变为connected后再发送/hello。未连接时发送按钮不可用,页面会说明原因。
收到回复即代表完整链路跑通:Sandbox 适配器收到入站消息 → 匹配到 commands/hello → 回复经统一出站链路发回。之后接入真实平台,只是在配置里挂载对应的适配器。
4. 认识刚生成的项目
想知道 Bot 当前加载了哪些指令?在会话中发送 /菜单(无命令前缀时发 菜单),会列出根插件的指令与子插件;某条指令的参数用法可通过 /hello --help 查看(详见指令菜单)。
my-bot/
├── package.json # Runtime 拓扑:entry、features
├── zhin.config.yml # Host、挂载的插件实例(plugins)与各插件配置值
├── .env # token、平台凭据、模型 Key
├── plugin.ts # 根插件入口
├── commands/ # 文件路径就是命令路由
├── components/ # 可复用消息组件
└── pages/ # 插件贡献的 Console 页面记住两点就够了:
package.json的zhin字段只描述插件自身入口与能力 Feature(entry、features);zhin.config.yml描述挂载了哪些插件以及怎么配(plugins、端口、凭据、插件配置),密钥放.env。my-bot本身就是一个 Root 插件——放进commands/、components/、middlewares/、pages/等约定目录的文件会被自动发现并注册,不需要改package.json,也不需要在plugin.ts里手写登记。
名词速查见 核心概念速览。
5. 修改并观察热重载 —— 在你的 Bot 里直接加功能 (1→2)
打开 commands/hello/index.ts,修改返回文案并保存,再发 /hello——不用重启就能看到新回复。正在处理中的消息会用旧代码跑完;如果新代码有语法或运行错误,旧版本继续服务,终端会打印错误原因。
因为 my-bot 已经是 Root 插件,日常写业务功能不需要新建子插件包,直接在约定目录里加文件即可:
① 加一个带参数的命令(commands/roll/index.ts)
新建 commands/roll/index.ts,保存后在 Sandbox 发送 /roll 20 或 /roll --help:
// commands/roll/index.ts → /roll [sides]
import { defineCommand } from 'zhin.js/command';
export default defineCommand({
description: '掷一个指定面数的骰子',
params: {
sides: { type: 'integer', min: 2, max: 100, default: 6 },
},
execute: ({ params }) => `🎲 (1-${params.sides}) 掷出了:${1 + Math.floor(Math.random() * params.sides)}`,
});② 加一个跨平台 JSX 互动卡片(commands/card/index.tsx)
新建 commands/card/index.tsx(注意 .tsx 扩展名)。支持按钮的平台直接渲染按钮,纯文本平台会自动降级为编号选项,点击或回复序号都会触发 onClick:
// commands/card/index.tsx → /card
import { defineCommand } from 'zhin.js/command';
export default defineCommand({
description: '发送一张带互动按钮的卡片',
execute: () => (
<card title="⚡ 今日状态打卡">
<text>选择你现在的状态:</text>
<button label="🔥 状态拉满" onClick={(msg) => `${msg.$sender.name} 已打卡:状态拉满!`} />
<button label="☕ 需要咖啡" onClick={(msg) => `${msg.$sender.name} 正在补充咖啡因…`} />
</card>
),
});③ 加一个给 AI 调用的工具(tools/weather/index.ts,可选)
如果你运行过 npx zhin setup --ai 启用了 AI,新建 tools/weather/index.ts 即可让大模型自动调用:
// tools/weather/index.ts
import { Schema } from 'zhin.js';
import { defineAgentTool } from '@zhin.js/tool';
export default defineAgentTool<{ city: string }>({
description: '查询城市实时天气',
parameters: Schema.object({
city: Schema.string().required().description('城市名称,例如上海'),
}),
requiresApproval: 'never',
async execute({ city }) {
const res = await fetch(`https://wttr.in/${encodeURIComponent(city)}?format=3`);
return res.text();
},
});遇到问题
npx zhin doctorDoctor 会检查 Node、pnpm、端口、HTTP_TOKEN、CORS 和项目清单。连接失败时先看终端打印的 API Base,不要默认套用其他项目的端口。
项目如何长大
| 当前需要 | 推荐形态 | 下一步 |
|---|---|---|
| 验证一个想法 | 单文件 bot.ts | single-file-bot |
| 做命令、卡片与定时通知 | Root 插件 + 约定目录 | IM Bot 路径 |
| 把功能抽成可复用/可发布的插件包 | plugins/<name> 子插件 | 编写第一个插件 |
| 增加模型与工具 | 挂载 Agent Features | AI Agent 路径 |
| 多账号与生产运维 | HTTP Host + Remote Console | Console 管理路径 |
Install tiers
| 档位 | 安装 | 约 production 体积 | 能力 |
|---|---|---|---|
| IM | pnpm add zhin.js @zhin.js/cli + 适配器(如 @zhin.js/adapter-sandbox);@zhin.js/cli 提供 zhin start 与管理网关 @zhin.js/gateway,开发与运行都需要 | <10MB(库包) | 内置命令、组件、中间件、定时任务与热重载运行时(按需在 zhin.config.yml 挂载适配器与插件,详见 插件模型) |
| AI | + @zhin.js/agent zod ai | +~12–15MB | ZhinAgent、会话、工具、压缩 |
| Provider | + @ai-sdk/openai 等 | 按厂商 | 大模型调用 |
| MCP | + @modelcontextprotocol/sdk | +~数 MB | MCP Client |
| Rich media | + @zhin.js/html-renderer | 按平台(含原生引擎) | 出站 html / markdown 转 PNG(未装则降级 text) |
| Speech | + @zhin.js/speech | +~数 MB | 入站 STT、出站 TTS、segment.tts(未装则 warn 降级) |