# @zhin.js/cli

Zhin **AI Agent 运行时**的全功能命令行工具，提供项目创建、Endpoint 联调、插件构建、进程管理与 Host API 访问支持。

## 核心功能

- 🧩 **插件开发**: 快速创建插件包，自动配置依赖
- 🔥 **开发模式**: 热重载开发服务器，实时代码更新
- 📦 **插件构建**: 构建独立插件包（app + client）
- 🛠️ **进程管理**: 生产环境启动、停止、重启、后台运行
- ⚙️ **多运行时**: 支持 Node.js 和 Bun 运行时

## Plugin Runtime

`zhin runtime` 是约定式 Plugin Runtime 的正式控制面：

```bash
zhin runtime init @acme/root
zhin runtime create plugin weather @acme/plugin-weather
zhin runtime inspect
zhin runtime migrate extract --check
zhin runtime migrate extract --write
zhin runtime migrate cutover --write
zhin runtime migrate status
zhin runtime start --once
zhin runtime build
zhin runtime publish
```

静态迁移器只自动转换能够证明无外部闭包的 Command、Middleware 与 Component，并直接
生成 `defineCommand`、`defineMiddleware`、`defineComponent`。不再提供 legacy compat
runtime；其余语义迁移由仓库的 `migrate-zhin-plugin-runtime` Skill 完成。

> **注意**: 新建 workspace 请用 `pnpm create zhin-app`（`create-zhin-app`）。`zhin setup` / `zhin onboard` 的 database / adapters / AI 向导与 create 共用 [`@zhin.js/scaffold-wizard`](../../packages/toolkit/scaffold-wizard/)。

## 命令详解

### new - 创建插件

创建新的插件包，自动添加到项目依赖：

```bash
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 组件
├── agent/
│   └── skills/<name>.md   # 插件 AI 技能（discoverPluginAgentSurface）
│   └── 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/`，与官方插件约定一致）
- ✅ 创建 `agent/skills/<插件名>.md` 模板（frontmatter 供 Agent 发现）
- ✅ 配置 TypeScript 编译
- ✅ 自动添加到根 `package.json` 依赖（`workspace:*`）
- ✅ 自动安装依赖
- ✅ 生成示例代码（命令、页面）

**使用示例：**
```bash
# 交互式创建
zhin new

# 直接指定名称
zhin new my-awesome-plugin

# 跳过依赖安装
zhin new my-plugin --skip-install
```

### dev - 开发模式

启动开发服务器，支持热重载和实时调试：

```bash
zhin dev [options]
```

**特性：**
- 🔥 **热模块替换 (HMR)**: 代码修改即时生效
- 🔍 **实时监控**: 自动检测文件变化
- 🛠️ **调试友好**: 详细错误信息和堆栈跟踪
- 📊 **性能监控**: 实时性能统计

**选项：**
- `-p, --port [port]`: HMR 服务端口，默认 3000
- `--verbose`: 显示详细日志输出
- `--bun`: 使用 bun 运行时（默认使用 tsx）

**环境变量：**
```bash
NODE_ENV=development
ZHIN_DEV_MODE=true
HTTP_PORT=8086
ZHIN_VERBOSE=false
```

### start - 生产启动

生产环境启动机器人，支持前台和后台运行：

```bash
zhin start [options]
```

**特性：**
- 🚀 **高性能**: 基于编译后的 JavaScript 运行
- 🔄 **自动重启**: 支持配置热更新重启 (exit code 51)
- 📝 **日志管理**: 支持日志文件输出
- 🛡️ **进程管理**: 完善的进程生命周期管理

**选项：**
- `-d, --daemon`: 后台运行模式
- `--log-file [file]`: 指定日志文件路径
- `--bun`: 使用 bun 运行时（默认使用 node）

**使用示例：**
```bash
# 前台运行
zhin start

# 后台运行
zhin start --daemon

# 后台运行并记录日志
zhin start --daemon --log-file ./logs/bot.log

# 使用 bun 运行时
zhin start --bun
```

### 全局实例（`~/.zhin`）

全局安装 CLI 后，可在任意目录启动机器人；配置、`data/`、`.env` 集中在 `~/.zhin`：

```bash
# 首次：交互式配置并安装依赖
zhin setup --global

# 任意目录启动（无本地项目时自动使用 ~/.zhin；首次 start 也会自动初始化）
zhin start
zhin dev
zhin stop
```

当前目录已是 Zhin 项目时仍优先使用本地项目。`skills/`、`tools/`、`agents/`、`~/.zhin/packages/` 作为发现链的第二优先级与项目内路径并存。

### restart - 重启服务

重启生产模式下运行的机器人：

```bash
zhin restart
```

**功能：**
- 🔄 检测运行中的进程
- 📋 读取 PID 文件
- ⚡ 发送重启信号
- 🛠️ 自动故障处理

### stop - 停止服务

停止运行中的机器人进程：

```bash  
zhin stop
```

**功能：**
- 🛑 优雅停止进程
- 🔍 自动检测运行状态
- 🧹 清理 PID 文件
- 📝 详细停止日志

### build - 构建插件

构建 `plugins/` 目录下的插件包：

```bash
zhin build [plugin] [options]
```

**参数：**
- `[plugin]`: 可选，指定要构建的插件名称（不指定则构建所有插件）

**选项：**
- `--clean`: 构建前清理输出目录（`lib/` 和 `dist/`）
- `--production`: 生产构建，启用 Tree Shaking（默认开启）
- `--analyze`: 分析包体积

**功能：**
- 📦 构建插件的 app 代码（TypeScript → lib/）
- � 构建插件的 client 页面（TypeScript → dist/）
- �🎯 完整的类型检查
- 🗂️ 自动组织输出文件
- ⚡ 并行构建优化

**使用示例：**
```bash
# 构建所有插件
zhin build

# 只构建特定插件
zhin build my-plugin

# 清理后构建
zhin build --clean

# 清理后构建特定插件
zhin build my-plugin --clean
```

**注意：**
- ❌ 不用于构建主应用（app 本身不需要构建）
- ✅ 只构建 `plugins/` 目录下的独立插件包
- ✅ 每个插件使用自己的 `package.json` 中的 `build` 脚本

## 完整工作流程

### 1. 创建新项目

```bash
# 使用 create-zhin-app（推荐）
npm create zhin-app my-awesome-bot
# 或
pnpm create zhin-app my-awesome-bot

cd my-awesome-bot
```

### 2. 开发阶段

```bash
# 开发模式启动（支持热重载）
pnpm dev
# 或
zhin dev

# 详细日志模式
zhin dev --verbose

# 自定义端口
zhin dev --port 8080
```

### 3. 创建插件

```bash
# 创建新插件
zhin new my-awesome-plugin

# 插件会自动添加到 package.json 依赖
# 在配置文件中启用插件
# 编辑 zhin.config.yml，添加到 plugins 数组：
# plugins: ['@zhin.js/host-router', '@zhin.js/host-api', 'my-awesome-plugin']
```

### 4. 构建插件

```bash
# 构建所有插件
pnpm build
# 或
zhin build

# 只构建特定插件
zhin build my-awesome-plugin

# 清理后构建
zhin build --clean
```

### 5. 生产部署

```bash
# 确保插件已构建
pnpm build

# 前台测试
pnpm start
# 或
zhin start

# 后台部署
pnpm daemon
# 或
zhin start --daemon --log-file ./logs/production.log
```

### 6. 运维管理

```bash
# 重启服务
zhin restart

# 停止服务  
pnpm stop
# 或
zhin stop

# 重新构建插件并重启
pnpm build && zhin restart
```

## 高级配置

### 多环境配置

```javascript
// zhin.config.ts
import { defineConfig } from 'zhin.js';

export default defineConfig(async (env) => {
  const isProduction = env.NODE_ENV === 'production';
  
  return {
    endpoints: [
      {
        context: 'sandbox',
        name: 'sandbox-bot',
      },
    ],
    plugin_dirs: [
      './src/plugins',
      ...(isProduction ? [] : ['./dev-plugins'])
    ],
    plugins: [
      '@zhin.js/adapter-sandbox',
      '@zhin.js/host-router',
      '@zhin.js/host-api',
      'test-plugin',
    ],
    debug: !isProduction
  };
});
```

### 环境变量文件

支持自动加载环境变量文件：
- `.env` - 通用环境变量
- `.env.development` - 开发环境专用
- `.env.production` - 生产环境专用

### 进程管理

**自动重启机制：**
```typescript
// 在插件中触发重启
process.exit(51); // 特殊退出码，会触发自动重启
```

**PID 文件管理：**
- 开发模式：`.zhin-dev.pid`
- 生产模式：`.zhin.pid`

### pub - 发布插件

将插件包发布到 npm：

```bash
zhin pub [plugin-name] [options]
```

**选项：**
- `--tag <tag>`: 发布标签，默认 `latest`
- `--access <access>`: 访问级别（`public` | `restricted`），默认 `public`
- `--registry <url>`: 自定义 npm registry
- `--dry-run`: 试运行，不实际发布
- `--skip-build`: 跳过构建步骤

**说明：** 会递归扫描 `plugins/` 下含 `package.json` 的包，并筛选 `zhin.js-*`、`@zhin.js/*` 或 `keywords` 含 `zhin.js` 的目录（支持 `plugins/my-plugin` 与 `plugins/adapters/icqq` 等嵌套路径）。

**使用示例：**
```bash
# 交互式选择要发布的插件
zhin pub

# 指定插件发布（相对 plugins/ 的路径，或唯一时可用最后一级目录名）
zhin pub my-plugin
zhin pub adapters/icqq
zhin pub icqq

# 试运行（不实际发布）
zhin pub my-plugin --dry-run

# 使用自定义 registry
zhin pub my-plugin --registry https://registry.npmmirror.com
```

### install / add - 安装插件

安装插件包（npm 或 git 仓库），默认会在本地项目的 `zhin.config.yml` / `zhin.config.yaml` / `zhin.config.json` 中启用插件：

```bash
zhin install [plugin] [options]
zhin add [plugin] [options]   # 别名
```

**选项：**
- `-S, --save`: 安装到 dependencies（默认）
- `-D, --save-dev`: 安装到 devDependencies
- `-g, --global`: 全局安装
- `--dry-run`: 只展示依赖安装命令和配置改动，不写入文件
- `--no-enable`: 只安装依赖，不自动写入 `plugins`

**支持的安装来源：**
- npm 包：`zhin install @zhin.js/adapter-kook`
- GitHub 仓库：`zhin install github:user/repo`
- Git URL：`zhin install git+https://github.com/user/repo.git`

**使用示例：**

```bash
zhin install @zhin.js/adapter-telegram --dry-run
zhin install @zhin.js/adapter-telegram
zhin install @scope/plugin --no-enable
```

安装官方 `@zhin.js/adapter-*` 后，CLI 会提示继续运行 `zhin setup --adapters` 或通过 Console / IM 命令创建 Endpoint。

### search - 搜索插件

在 npm 上搜索 Zhin.js 插件：

```bash
zhin search [keyword] [options]
```

**选项：**
- `-c, --category <category>`: 按分类搜索（`utility` | `service` | `game` | `adapter` | `admin` | `ai`）
- `-l, --limit <number>`: 限制结果数量，默认 20
- `--official`: 仅显示官方插件

**使用示例：**
```bash
# 搜索所有 Zhin 插件
zhin search

# 按关键词搜索
zhin search music

# 仅显示官方插件
zhin search --official

# 按分类搜索，限制 5 个结果
zhin search -c adapter -l 5
```

### info - 查看插件信息

查看 npm 上某个插件的详细信息：

```bash
zhin info <package>
```

显示内容包括：名称、版本、描述、作者、发布时间、标签、主页、仓库地址、依赖等。

### doctor - 健康检查

检查系统环境和项目配置，诊断常见问题：

```bash
zhin doctor [options]
```

**别名：** `zhin health`

**选项：**
- `--fix`: 自动修复可修复的问题（如创建默认配置文件、引导文件、`.env` 文件等）

**检查项目：**
- Node.js 版本（^20.19.0 或 >=22.12.0，与 create-zhin-app 一致）
- pnpm 安装
- 配置文件（`zhin.config.yml` 等）
- 引导文件（`SOUL.md`、`TOOLS.md`、`AGENTS.md`）
- `package.json` 中是否安装 `zhin.js`
- `node_modules` 目录
- 端口 8086 占用
- TypeScript 安装
- 环境变量文件

### setup - 配置向导

交互式引导配置已有项目（database / adapters / AI / bootstrap）。database、adapters、AI 三步与 `pnpm create zhin-app` 共用 `@zhin.js/scaffold-wizard`，行为一致。

```bash
zhin setup [options]
```

**选项：**
- `--global`: 在 `~/.zhin` 初始化并配置全局实例（任意目录 `zhin start` 可用）
- `--bootstrap`: 仅配置引导文件（SOUL.md、TOOLS.md、AGENTS.md）
- `--database`: 仅配置数据库（SQLite / MySQL / PostgreSQL 等）
- `--adapters`: 仅配置适配器（Sandbox、Telegram、Discord、GitHub 等）
- `--ai`: 仅配置 AI（Ollama、OpenAI、DeepSeek 等）

不带选项时，运行完整配置向导。

### config - 配置管理

命令行管理配置文件（支持 YAML / JSON）：

```bash
zhin config <subcommand>
```

**子命令：**

| 子命令            | 说明                                           |
| ----------------- | ---------------------------------------------- |
| `config list`     | 显示所有配置（别名 `ls`）                      |
| `config get <key>`| 获取配置项（支持嵌套路径，如 `ai.enabled`）    |
| `config set <key> <value>` | 设置配置项（值支持 JSON 格式）       |
| `config delete <key>` | 删除配置项（别名 `del`）                   |
| `config path`     | 显示配置文件路径                               |

**使用示例：**
```bash
# 查看所有配置
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
```

### onboard - 引导与配置向导

借鉴 OpenClaw onboard：在项目内检测现有配置，可选择保持 / 重新配置（复用当前配置与 .env、data）/ 重置；非项目内可创建新项目或仅查看快速开始。

```bash
zhin onboard [options]
```

**选项：**
- `-q, --quick`: 仅显示快速开始步骤，不进入向导
- `--flow <flow>`: 配置流程，可选 `quickstart` | `full`（默认）

**项目内流程：** 环境检查 → 若存在配置则显示摘要 → 选择「保持 / 重新配置 / 重置」→ 重新配置或重置时启动 `zhin setup`（共用 scaffold-wizard）→ 可选运行 `zhin doctor`。

**项目外：** 引导执行 `pnpm create zhin-app` 创建新项目（Node ^20.19.0 或 >=22.12.0）。

### send - 向运行中的机器人发送消息

在 daemon 运行时，通过 HTTP API 向指定适配器/场景发送一条消息（需启用 `@zhin.js/host-router`，借鉴 OpenClaw `message send`）。

```bash
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>`: 适配器名称（如 `sandbox`、`icqq`、`discord`），默认 `sandbox`
- `-e, --endpoint <id>`: 指定 Endpoint ID；不传则使用该适配器下第一个在线 Endpoint

**示例：**
```bash
zhin send 1659488338 你好啊
zhin send 123456 --scene group --adapter icqq 群发一条
echo "长内容" | zhin send 1659488338 --adapter sandbox
```

### watch - 监视运行中实例

连接 Host API，展示 runtime / bots / assistant jobs（需 `zhin dev` 或 `zhin start` 且启用 host-router + host-api）。

```bash
zhin watch              # TTY 下每 3 秒刷新
zhin watch --once       # 单次快照
zhin watch --json       # JSON（脚本友好，默认单次）
zhin watch -i 5         # 5 秒刷新间隔
```

数据来源：`GET /api/stats`、`GET /api/system/status`（进程 rss/heap + 主机 freeMem/totalMem）、`/api/endpoints`、`/api/assistant/jobs`。

### packages - zhin-package 包管理（ADR 0010）

```bash
zhin packages install npm:@scope/pkg   # 全局 ~/.zhin/packages/
zhin packages install git:user/repo -l # 项目 .zhin/packages/
zhin packages list
zhin packages remove <name>
zhin packages update [name]
```

安装的技能目录纳入 Agent 发现链（与 `.agents/skills` 并列）。

### migrate - 项目升级

将老版本 Zhin 项目依赖与结构升级到最新（`src/commands/migrate.ts`）。

```bash
zhin migrate [options]
```

**步骤：**
1. 将 `package.json` 中 `zhin.js` 与所有 `@zhin.js/*` 依赖升级到 `latest`（monorepo 内保留 `workspace:*`）
2. 补全推荐 `scripts`（`dev` / `start` / `daemon` / `stop` / `build`）与 `engines.node`
3. 确保 `data/`、`plugins/` 等目录存在
4. 升级引导文件（`SOUL.md`、`TOOLS.md`、`AGENTS.md`）
5. 执行 `pnpm install`（可用 `--no-install` 跳过）

**选项：**
- `--dry-run`: 仅打印将要执行的操作，不写入文件也不安装依赖
- `--no-install`: 跳过最后一步依赖安装

**示例：**
```bash
zhin migrate --dry-run   # 预览变更
zhin migrate             # 升级并安装
zhin migrate --no-install
```

### install-service / uninstall-service - 系统服务

将机器人注册为系统服务，实现开机自启和守护进程监督：

```bash
zhin install-service [options]
zhin uninstall-service
```

**选项：**
- `--user`: 以用户模式安装（仅 systemd）

**支持平台：**
- Linux: systemd（用户模式 / 系统模式）
- macOS: launchd
- Windows: NSSM

## 故障排查

### 常见问题

1. **tsx/bun 未安装**
   ```bash
   # 安装 tsx (Node.js 运行时)
   npm install -D tsx
   
   # 安装 bun
   curl -fsSL https://bun.sh/install | bash
   ```

2. **端口占用**
   ```bash
   # 检查端口占用
   lsof -i :8086
   
   # 使用不同端口
   zhin dev --port 8087
   ```

3. **权限问题**
   ```bash
   # 确保项目目录权限
   chmod -R 755 ./my-bot
   ```

## 环境要求

- **Node.js**: `^20.19.0 || >=22.12.0`（与 `src/utils/node-requirements.ts`、create-zhin-app 一致）
- **pnpm**: 推荐 9+（workspace 项目）
- **操作系统**: Windows 10+、macOS 10.15+、现代 Linux

## 依赖项

### 核心依赖
- `commander` - 命令行参数解析
- `inquirer` - 交互式命令行界面  
- `fs-extra` - 增强文件系统操作
- `chalk` - 彩色终端输出
- `ora` - 优雅的加载指示器
- `cross-spawn` - 跨平台进程管理
- `dotenv` - 环境变量管理

### 开发依赖  
- `typescript` - TypeScript 编译器
- `@types/*` - TypeScript 类型定义

## 许可证

MIT License