Zhin 机器人框架的全功能命令行工具，提供项目创建、开发调试、插件构建、进程管理等完整开发流程支持。
- 🧩 插件开发: 快速创建插件包，自动配置依赖
- 🔥 开发模式: 热重载开发服务器，实时代码更新
- 📦 插件构建: 构建独立插件包（app + client）
- 🛠️ 进程管理: 生产环境启动、停止、重启、后台运行
- ⚙️ 多运行时: 支持 Node.js 和 Bun 运行时
注意: 项目初始化功能已移至
create-zhin-app，请使用npm create zhin-app创建新项目。
创建新的插件包，自动添加到项目依赖：
zhin new [plugin-name] [options]选项：
--type <type>: 插件类型（normal|service|adapter），默认normal--is-official: 是否为官方插件（使用@zhin.js/前缀）--skip-install: 跳过依赖安装
生成的插件结构：
plugins/my-plugin/
├── src/ # 插件逻辑代码
│ └── index.ts # 插件入口
├── client/ # 控制台客户端页面
│ ├── index.tsx # 页面入口
│ ├── tsconfig.json
│ └── pages/ # React 组件
├── skills/my-plugin/ # 文件化 AI 技能（随包发布）
│ └── SKILL.md
├── tests/ # Vitest 测试
├── lib/ # Node 端构建输出（tsc）
├── dist/ # client 构建输出
├── package.json # 含 npm files：src/lib/client/dist/skills/README.md/CHANGELOG.md
├── tsconfig.json
├── README.md
└── CHANGELOG.md
自动配置：
- ✅ 创建完整的 npm 包结构（
files白名单含skills/，与官方插件约定一致） - ✅ 生成
skills/<插件名>/SKILL.md模板（frontmatter 供 Agent 扫描） - ✅ 配置 TypeScript 编译
- ✅ 自动添加到根
package.json依赖（workspace:*） - ✅ 自动安装依赖
- ✅ 生成示例代码（命令、页面）
使用示例：
# 交互式创建
zhin new
# 直接指定名称
zhin new my-awesome-plugin
# 跳过依赖安装
zhin new my-plugin --skip-install启动开发服务器，支持热重载和实时调试：
zhin dev [options]特性：
- 🔥 热模块替换 (HMR): 代码修改即时生效
- 🔍 实时监控: 自动检测文件变化
- 🛠️ 调试友好: 详细错误信息和堆栈跟踪
- 📊 性能监控: 实时性能统计
选项：
-p, --port [port]: HMR 服务端口，默认 3000--verbose: 显示详细日志输出--bun: 使用 bun 运行时（默认使用 tsx）
环境变量：
NODE_ENV=development
ZHIN_DEV_MODE=true
HTTP_PORT=8086
ZHIN_VERBOSE=false生产环境启动机器人，支持前台和后台运行：
zhin start [options]特性：
- 🚀 高性能: 基于编译后的 JavaScript 运行
- 🔄 自动重启: 支持配置热更新重启 (exit code 51)
- 📝 日志管理: 支持日志文件输出
- 🛡️ 进程管理: 完善的进程生命周期管理
选项：
-d, --daemon: 后台运行模式--log-file [file]: 指定日志文件路径--bun: 使用 bun 运行时（默认使用 node）
使用示例：
# 前台运行
zhin start
# 后台运行
zhin start --daemon
# 后台运行并记录日志
zhin start --daemon --log-file ./logs/bot.log
# 使用 bun 运行时
zhin start --bun重启生产模式下运行的机器人：
zhin restart功能：
- 🔄 检测运行中的进程
- 📋 读取 PID 文件
- ⚡ 发送重启信号
- 🛠️ 自动故障处理
停止运行中的机器人进程：
zhin stop功能：
- 🛑 优雅停止进程
- 🔍 自动检测运行状态
- 🧹 清理 PID 文件
- 📝 详细停止日志
构建 plugins/ 目录下的插件包：
zhin build [plugin] [options]参数：
[plugin]: 可选，指定要构建的插件名称（不指定则构建所有插件）
选项：
--clean: 构建前清理输出目录（lib/和dist/）--production: 生产构建，启用 Tree Shaking（默认开启）--analyze: 分析包体积
功能：
- 📦 构建插件的 app 代码（TypeScript → lib/）
- � 构建插件的 client 页面（TypeScript → dist/）
- �🎯 完整的类型检查
- 🗂️ 自动组织输出文件
- ⚡ 并行构建优化
使用示例：
# 构建所有插件
zhin build
# 只构建特定插件
zhin build my-plugin
# 清理后构建
zhin build --clean
# 清理后构建特定插件
zhin build my-plugin --clean注意：
- ❌ 不用于构建主应用（app 本身不需要构建）
- ✅ 只构建
plugins/目录下的独立插件包 - ✅ 每个插件使用自己的
package.json中的build脚本
# 使用 create-zhin-app（推荐）
npm create zhin-app my-awesome-bot
# 或
pnpm create zhin-app my-awesome-bot
cd my-awesome-bot# 开发模式启动（支持热重载）
pnpm dev
# 或
zhin dev
# 详细日志模式
zhin dev --verbose
# 自定义端口
zhin dev --port 8080# 创建新插件
zhin new my-awesome-plugin
# 插件会自动添加到 package.json 依赖
# 在配置文件中启用插件
# 编辑 zhin.config.yml，添加到 plugins 数组：
# plugins: ['adapter-process', 'http', 'console', 'my-awesome-plugin']# 构建所有插件
pnpm build
# 或
zhin build
# 只构建特定插件
zhin build my-awesome-plugin
# 清理后构建
zhin build --clean# 确保插件已构建
pnpm build
# 前台测试
pnpm start
# 或
zhin start
# 后台部署
pnpm daemon
# 或
zhin start --daemon --log-file ./logs/production.log# 重启服务
zhin restart
# 停止服务
pnpm stop
# 或
zhin stop
# 重新构建插件并重启
pnpm build && zhin restart// zhin.config.ts
import { defineConfig } from 'zhin.js';
export default defineConfig(async (env) => {
const isProduction = env.NODE_ENV === 'production';
return {
bots: [
{
context: 'process',
name: `${process.pid}`,
}
],
plugin_dirs: [
'./src/plugins',
...(isProduction ? [] : ['./dev-plugins'])
],
plugins: [
'adapter-process',
'http',
'console',
'test-plugin'
],
debug: !isProduction
};
});支持自动加载环境变量文件：
.env- 通用环境变量.env.development- 开发环境专用.env.production- 生产环境专用
自动重启机制：
// 在插件中触发重启
process.exit(51); // 特殊退出码，会触发自动重启PID 文件管理：
- 开发模式：
.zhin-dev.pid - 生产模式：
.zhin.pid
将插件包发布到 npm：
zhin pub [plugin-name] [options]选项：
--tag <tag>: 发布标签，默认latest--access <access>: 访问级别（public|restricted），默认public--registry <url>: 自定义 npm registry--dry-run: 试运行，不实际发布--skip-build: 跳过构建步骤
使用示例：
# 交互式选择要发布的插件
zhin pub
# 指定插件发布
zhin pub my-plugin
# 试运行（不实际发布）
zhin pub my-plugin --dry-run
# 使用自定义 registry
zhin pub my-plugin --registry https://registry.npmmirror.com安装插件包（npm 或 git 仓库）：
zhin install [plugin] [options]
zhin add [plugin] [options] # 别名选项：
-S, --save: 安装到 dependencies（默认）-D, --save-dev: 安装到 devDependencies-g, --global: 全局安装
支持的安装来源：
- npm 包：
zhin install @zhin.js/adapter-kook - GitHub 仓库：
zhin install github:user/repo - Git URL：
zhin install git+https://github.com/user/repo.git
在 npm 上搜索 Zhin.js 插件：
zhin search [keyword] [options]选项：
-c, --category <category>: 按分类搜索（utility|service|game|adapter|admin|ai）-l, --limit <number>: 限制结果数量，默认 20--official: 仅显示官方插件
使用示例：
# 搜索所有 Zhin 插件
zhin search
# 按关键词搜索
zhin search music
# 仅显示官方插件
zhin search --official
# 按分类搜索，限制 5 个结果
zhin search -c adapter -l 5查看 npm 上某个插件的详细信息：
zhin info <package>显示内容包括：名称、版本、描述、作者、发布时间、标签、主页、仓库地址、依赖等。
检查系统环境和项目配置，诊断常见问题：
zhin doctor [options]别名： zhin health
选项：
--fix: 自动修复可修复的问题（如创建默认配置文件、引导文件、.env文件等）
检查项目：
- Node.js 版本（>= 18）
- pnpm 安装
- 配置文件（
zhin.config.yml等） - 引导文件（
SOUL.md、TOOLS.md、AGENTS.md） package.json中是否安装zhin.jsnode_modules目录- 端口 8086 占用
- TypeScript 安装
- 环境变量文件
交互式引导配置项目：
zhin setup [options]选项：
--bootstrap: 仅配置引导文件（SOUL.md、TOOLS.md、AGENTS.md）--database: 仅配置数据库（SQLite / MySQL / PostgreSQL）--adapters: 仅配置适配器（Sandbox、QQ、KOOK、Discord 等）--ai: 仅配置 AI（Ollama、OpenAI、DeepSeek 等）
不带选项时，运行完整配置向导。
命令行管理配置文件（支持 YAML / JSON）：
zhin config <subcommand>子命令：
| 子命令 | 说明 |
|---|---|
config list |
显示所有配置（别名 ls） |
config get <key> |
获取配置项（支持嵌套路径，如 ai.enabled） |
config set <key> <value> |
设置配置项（值支持 JSON 格式） |
config delete <key> |
删除配置项（别名 del） |
config path |
显示配置文件路径 |
使用示例：
# 查看所有配置
zhin config list
# 获取某项
zhin config get ai.enabled
# 修改配置
zhin config set http.port 3000
zhin config set ai.enabled true
# 删除配置
zhin config del ai.trigger.prefixes
# 查看配置文件路径
zhin config path借鉴 OpenClaw onboard：在项目内检测现有配置，可选择保持 / 重新配置（复用当前配置与 .env、data）/ 重置；非项目内可创建新项目或仅查看快速开始。
zhin onboard [options]选项：
-q, --quick: 仅显示快速开始步骤，不进入向导--flow <flow>: 配置流程，可选quickstart|full（默认）
项目内流程： 环境检查 → 若存在配置则显示摘要 → 选择「保持 / 重新配置 / 重置」→ 重新配置或重置时启动 zhin setup，复用现有配置文件、环境变量与 data 目录 → 可选运行 zhin doctor。
在 daemon 运行时，通过 HTTP API 向指定适配器/场景发送一条消息（需启用 @zhin.js/http，借鉴 OpenClaw message send）。
zhin send <scene_id> [内容...] [options]参数：
scene_id: 场景 ID（私聊为用户 ID，群聊为群号等）内容: 消息正文，可多个词用空格连接；不传则从 stdin 读取（如echo "hi" | zhin send 123）
选项：
-s, --scene <type>: 场景类型，private|group|channel，默认private-a, --adapter <name>: 适配器名称（如icqq、discord、process），默认process-b, --bot <id>: 指定 Bot ID；不传则使用该适配器下第一个在线 Bot
示例：
zhin send 1659488338 你好啊
zhin send 123456 --scene group --adapter icqq 群发一条
echo "长内容" | zhin send 1659488338 --adapter process将老版本 Zhin 项目依赖与结构升级到最新，见上文「migrate」说明。
将机器人注册为系统服务，实现开机自启和守护进程监督：
zhin install-service [options]
zhin uninstall-service选项：
--user: 以用户模式安装（仅 systemd）
支持平台：
- Linux: systemd（用户模式 / 系统模式）
- macOS: launchd
- Windows: NSSM
-
tsx/bun 未安装
# 安装 tsx (Node.js 运行时) npm install -D tsx # 安装 bun curl -fsSL https://bun.sh/install | bash
-
端口占用
# 检查端口占用 lsof -i :8086 # 使用不同端口 zhin dev --port 8087
-
权限问题
# 确保项目目录权限 chmod -R 755 ./my-bot
commander- 命令行参数解析inquirer- 交互式命令行界面fs-extra- 增强文件系统操作chalk- 彩色终端输出ora- 优雅的加载指示器cross-spawn- 跨平台进程管理dotenv- 环境变量管理
typescript- TypeScript 编译器@types/*- TypeScript 类型定义
MIT License