zeyiji-shared

zeyiji-cli 共享规则

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

Bootstrap（自动引导）

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

Step 1: 检查 CLI 是否可用

zeyiji-cli version

• 命令存在 → 继续 Step 2
• 命令不存在 → 执行安装：

  npx @zeyiji/cli@latest install
  

  一条命令完成：下载二进制 → 安装 AI Skills → 就绪。安装后重新验证 zeyiji-cli version

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

Step 2: 检查认证状态

zeyiji-cli auth status

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

Step 3: 执行用户任务

认证流程

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 给脚本读取时，可抑制通知：

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。

核心约束（无需读参考文件也必须知道的）：

• 内容必须是 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：

{
  "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