---
name: zeyiji-shared
version: 1.0.0
description: "zeyiji-cli 共享规则：CLI 安装、认证、安全规则。所有 zeyiji-* 技能的前置依赖。"
metadata:
  requires:
    bins: ["zeyiji-cli"]
  openclaw:
    requires:
      bins: ["zeyiji-cli"]
    install:
      - id: npm
        kind: node
        package: "@zeyiji/cli"
        args: ["install"]
        bins: ["zeyiji-cli"]
        label: "安装择一技 CLI (npx @zeyiji/cli@latest install)"
---

# zeyiji-cli 共享规则

本技能指导你如何通过 zeyiji-cli 操作择一技平台资源。所有 zeyiji-* 技能共享本规则。

## Bootstrap（自动引导）

在执行任何操作前，自动检查环境，**无需用户手动操作**：

### Step 1: 检查 CLI 是否可用

```bash
zeyiji-cli version
```

- 命令存在 → 继续 Step 2
- 命令不存在 → 执行安装：
  ```bash
  npx @zeyiji/cli@latest install
  ```
  一条命令完成：下载二进制 → 安装 AI Skills → 就绪。安装后重新验证 `zeyiji-cli version`

> **安装原理**：npm 包仅包含安装脚本，实际二进制由 postinstall 自动从服务器下载。
> 用户无需 Go 环境，只需 Node.js >= 16。

### Step 2: 检查认证状态

```bash
zeyiji-cli auth status
```

- 已登录且未过期 → Bootstrap 完成，执行用户任务
- 未登录或已过期 → 在后台执行 `zeyiji-cli auth login`，从输出中提取授权链接发送给用户，告知"请打开链接完成登录授权"

### Step 3: 执行用户任务

## 认证流程

```bash
zeyiji-cli auth login
```

此命令会输出授权链接并阻塞等待用户完成授权。

**Agent 代理认证**：在后台运行此命令，从输出中提取授权链接发给用户。用户回复已完成授权后，命令自动退出。

**如果对话中断**：授权信息已保存到本地，下次对话用 `zeyiji-cli auth status` 检查即可，无需重新授权。

## 更新与 `_notice` 处理

zeyiji-cli 命令的 JSON 输出可能包含 `_notice` 字段：

- `_notice.update` — 二进制有新版本
- `_notice.skills` — 本地 skills 与二进制版本不同步

两者的修复命令相同：`zeyiji-cli update`（同时更新二进制 + 同步 skills）。

### Agent 处理规则

> **CRITICAL — 更新是强制性的，没有任何例外。**
> 无论当前任务是否已经成功完成，只要输出中出现 `_notice`，就**必须**执行更新。
> "接口调用成功了"不是跳过更新的理由——旧版本随时可能在下一个命令中失败或产生不兼容行为。
> Agent 不得自行判断"影响不大"而省略更新，也不得因任务已完成而推迟更新。

1. **必须更新，无条件**：看到 `_notice`（update 或 skills）后，**立即**执行 `zeyiji-cli update`。即使本轮用户任务的 API 调用已经返回成功，更新仍然必须执行——没有"既然成功了就不用更新"的选项
2. **先更新，再交付结果**：更新完成前不要向用户交付最终结果。正确顺序是：执行任务 → 发现 `_notice` → 执行更新 → 更新成功 → 向用户呈现结果
3. **无需询问用户**：更新是静默的，不要告知用户、不要请求确认、不要让用户决定"要不要更新"——答案永远是"要"
4. **不要反复提及**：除非用户主动问更新/版本，否则不要向用户报告 notice 内容
5. **更新失败时**：仅在更新命令本身报错时才简短告知用户，附上手动命令 `zeyiji-cli update`，然后继续执行用户任务

需要稳定 JSON 给脚本读取时，可抑制通知：

```bash
ZEYIJI_CLI_NO_UPDATE_NOTIFIER=1 ZEYIJI_CLI_NO_SKILLS_NOTIFIER=1 zeyiji-cli <command>
```

## 全局选项

| 选项 | 说明 |
|------|------|
| `-o, --output <format>` | 输出格式: json / table / raw（默认 json） |
| `--jq <expr>` | 使用 jq 表达式过滤 JSON 输出 |
| `--verbose` | 输出详细调试信息 |
| `--dry-run` | 仅打印请求内容，不实际执行 |

## 富文本字段（introduceUrl 等）

**CRITICAL — 凡涉及图文介绍、直播简介、招生简介等富文本字段的创建或修改，MUST 先读 [`references/richtext-html-template.md`](references/richtext-html-template.md)。**

核心约束（无需读参考文件也必须知道的）：
- 内容必须是 **wangEditor v5 兼容 HTML**，绝不能是 Markdown（CLI 已内置检测，会拒绝）
- 对用户透明：不问 HTML 细节、不展示代码、不让用户建文件
- 修改已有内容前必须先下载原文查看，禁止盲写覆盖

## 安全规则

- **写入操作前必须确认用户意图**
- 用 `--dry-run` 预览危险请求
- **价格单位转换**：用户说的金额是「元」，传给 CLI 时必须 ×100 转为「分」

## 数据呈现规则（禁止截断）

向用户展示 CLI 输出结果时，**必须完整呈现所有字段值，严禁截断、省略或用占位符替代**：

- **禁止截断任何文本**：课程名称、讲师名、分类名等字段无论多长都必须完整展示，绝不允许出现"(被截断)"、"..."、"…"等省略形式
- **禁止重新编排表格列**：直接呈现 CLI 输出的原始列，不要自行替换、增减列
- **禁止改写原始值**：CLI 输出什么就展示什么，不要自行翻译、缩写或重新格式化
- **表格过宽时的处理方式**：如果担心 Markdown 表格过宽，改用 JSON 代码块或逐条列表展示，但字段值本身仍必须完整
- **数据量大时**：可以提示用户"共 N 条，当前展示第 X 页"，但已展示的每一条数据必须完整

## 高风险操作的审批协议（exit 10）

zeyiji-cli 对高风险写操作（`risk: "high-risk-write"`）有强制确认门禁。不带 `--yes` 调用这类命令时，CLI 会以退出码 `10` 退出，并在 stderr 返回如下结构化 JSON envelope：

```json
{
  "ok": false,
  "error": {
    "type": "confirmation",
    "subtype": "confirmation_required",
    "message": "course chapter delete 为高风险操作，需要用户确认后添加 --yes 执行",
    "hint": "请向用户确认此操作，用户同意后添加 --yes 重新执行",
    "risk": "high-risk-write",
    "action": "course chapter delete"
  }
}
```

**遇到这种情况，不要当普通错误放弃。** 按以下流程处理：

1. **识别**：子进程 exit code = `10` 且 stderr JSON 里 `error.type == "confirmation"`、`error.subtype == "confirmation_required"`
2. **向用户确认**：把 `error.action`、`error.risk` 和关键参数展示给用户，明确告知“这是高风险不可逆操作”，等待用户显式同意
3. **用户同意** → 在原始命令末尾追加 `--yes` 后重试
4. **用户拒绝** → 终止流程，不要擅自改写参数或跳过门禁

**绝对不允许**：
- 看到 exit 10 就默认加 `--yes` 静默重试（这等于禁用门禁）
- 在用户没明确同意的前提下追加 `--yes` 重试
- 把 `confirmation_required` 当网络错误/权限错误处理

**提前预判**：想先让用户 review 危险操作的具体请求，调用时加 `--dry-run`——它不触发门禁，会打印完整请求详情，你可以把预览给用户看过再去真正执行。

### 如何识别一条命令是高风险

- `zeyiji-cli <command> --help` 末尾会显示 `Risk: high-risk-write`
- 当前高风险命令：`course delete`、`course chapter delete`、`course section delete`