@sokeai/cli 1.0.79 → 1.0.80

package/skills/mono/SKILL.md

@@ -1,43 +1,65 @@
 ---
-name: soke-cli
-description: "授客AI CLI 全业务 Mono Skill。通过 soke-cli 管理课程、考试、题库、素材、课件、指派、学习地图、学习档案、证书、图片库、培训需求、AI 教练和 AI 督导。当用户需要从自然语言执行或了解上述业务操作时使用。"
-metadata:
-  requires:
-    bins:
-      - soke-cli
+name: soke-cli-mono
+description: >-
+  管理授客AI课程、素材、课件、考试、题库、学习地图、学员档案、证书、培训需求、AI教练、AI陪练和AI督导；
+  支持创建、查询、更新、发布、指派、导出、同步、排障和质量检查；
+  用户可以说“帮我创建课程”“上传课件”“发布考试”“指派学习地图”“同步AI陪练场景”“检查同步问题”来调用。
 ---
 
 # 授客AI CLI 全业务 Skill
 
-本目录是可独立复制和安装的 Mono 发布包。所有参考文档、工作流、案例和脚本均位于本目录内，不依赖原始代码仓库。
+本 Skill 是授客AI CLI 的总入口，负责意图识别、模块路由、全局前置检查、风险确认、真实 ID 管理、写后验证和结果汇报。所有参考文档、工作流、案例和脚本均位于本目录内，不依赖原始代码仓库。
+
+## 技能定位与边界
+
+负责：
+
+- 判断用户动作、目标业务对象和影响范围；
+- 路由到正确模块或已声明的跨模块工作流；
+- 执行全局认证、权限、风险确认、真实 ID、写后验证和输出脱敏规则。
+
+不负责：
+
+- 直接定义模块专属字段、完整参数、业务检查项和评分规则；
+- 替代模块 `MODULE.md` 或专项参考资料；
+- 在总入口统一规定不同业务的完成条件和质量闸门；
+- 把平台适配差异写入业务模块；
+- 绕过 `soke-cli` 直接调用业务 API。
+
+质量与诊断采用分层治理：通用故障分类和控制协议放在共享层；业务诊断、检查项和质量闸门放在对应模块；可自动验证的规则放在 `scripts/`。`SKILL.md` 只保留索引和通用阻塞条件。
+
+## 主管模式
+
+本 Skill 采用“外部调度 + 管线内编排”模式：
+
+- 对外：依据用户动作选择课程、考试、AI陪练等独立管线；
+- 对内：每条管线按对应模块文档的步骤、输入和闸门执行；
+- 管线之间禁止擅自串接，只有跨模块工作流明确声明对象交接时才能衔接；
+- 某条管线失败时，禁止假设其他管线已完成，必须保留失败阶段和实际状态。
 
 ## 前置条件
 
-开始任何业务操作前，先读取 [安装与认证](./references/installation.md) 和 [共享 CLI 规则](./references/shared/cli-basics.md)。
+先做最小就绪探测，不要启动即遍历共享文档：
+
+- 命令位置：先 `which soke-cli`；沙箱 PATH 可能不含 `/usr/local/bin`，裸 `soke-cli` 报 `command not found` 时改用绝对路径 `/usr/local/bin/soke-cli`（软链 → `~/.nvm/versions/node/v22.22.1/bin/soke-cli`）。命令已安装但 PATH 未含其目录时**不得误判为未安装**。
+- 环境与版本：运行 `soke-cli --version`（或上述绝对路径）判断可用；失败或版本不符时才读 `environment-check.md`。
+- 登录与企业：运行 `soke-cli config show` 判断登录态与 `corpid`；未登录、未绑定或 401 时才读 `auth-check.md`。
+
+探测通过即进入[意图路由](#意图路由)，直接读目标模块 `MODULE.md`。其余共享规则按需从[共享能力索引](./references/shared/README.md)加载，规则归属以[共享规则唯一来源矩阵](./references/shared/rule-ownership.md)为准。
 
 ## 意图路由
 
-按用户意图选择对应模块，并按需读取该模块的 `MODULE.md`：
+根据用户动作和目标对象选择唯一主模块；跨模块操作只进入已声明的工作流。完整路由矩阵见下表，模块细节按需读取。
 
-| 场景 | 模块 |
-|---|---|
-| 课程、课程发布、学习记录 | [soke-course](./references/modules/soke-course/MODULE.md) |
-| 考试、题库、试卷、成绩 | [soke-exam](./references/modules/soke-exam/MODULE.md) |
-| 题库答题练习 | [soke-exam-question-pool](./references/modules/soke-exam-question-pool/MODULE.md) |
-| 素材上传与管理 | [soke-material](./references/modules/soke-material/MODULE.md) |
-| 课件与课程章节 | [soke-lesson](./references/modules/soke-lesson/MODULE.md) |
-| 课程/考试/地图指派 | [soke-assign](./references/modules/soke-assign/MODULE.md) |
-| 学习地图 | [soke-learning-map](./references/modules/soke-learning-map/MODULE.md) |
-| 学员学习档案 | [soke-learning-profile](./references/modules/soke-learning-profile/MODULE.md) |
-| 证书、图片库、培训需求 | 对应模块目录 |
-| AI 教练、AI 督导 | 对应模块目录 |
+## 入口硬边界
 
-## 共享规则
+以下规则由总入口负责拦截，其余通用规则从[共享能力索引](./references/shared/README.md)按需加载：
 
-- 所有命令使用 `soke-cli`，不要绕过 CLI 直接调用 HTTP API。
-- 不编造 UUID、用户 ID、课程 ID 等标识符，必须先通过命令查询。
-- 写入、删除、发布等高风险操作遵循模块文档中的确认要求。
-- 详细资料按需读取，避免一次性加载整个参考目录。
+- 只通过 `soke-cli` 执行业务操作，不绕过 CLI 调用业务接口；
+- 业务对象和 ID 必须来自当前真实查询，不使用示例值或猜测值；
+- 高风险写操作必须先确认目标、范围和影响；
+- 管线失败或缺少必要返回值时立即停止，不把部分完成报告为成功；
+- 输出必须脱敏，禁止泄露凭证和无关内部响应。
 
 ## 目录说明
 
@@ -56,45 +78,38 @@ metadata:
 - 不要在未确认目标对象、影响范围和用户意图时执行删除、发布、指派或其他写操作。
 - 不要把 `soke-cli api` 当作绕过业务 Skill 约束的替代方案；只有模块文档明确要求时才使用。
 
-## 必须执行（MUST DO）
-
-- 开始任何业务操作前，先读取 [安装与认证](./references/installation.md) 和 [共享 CLI 规则](./references/shared/cli-basics.md)。
-- 先判断用户的核心动作，再选择业务模块；名词相似时不能仅凭关键词猜测。
-- 执行命令前使用对应命令的 `--help` 核对当前版本真实可用的参数，不要凭旧文档猜 flag。
-- 需要机器解析时优先使用 `--format json`；展示给用户时提炼关键字段，不回显大段原始 JSON。
-- 查询得到真实 ID 后才能执行后续依赖该 ID 的操作，并在多步流程中沿用同一对象。
-- 写操作完成后，根据模块文档要求报告结果；失败时保留具体错误，不静默改用未经验证的替代命令。
+## 标准控制点
 
-## 前置检查
+按[共享能力索引](./references/shared/README.md)和所选模块入口执行：
 
-```bash
-soke-cli --version
-soke-cli config show
-soke-cli auth login       # 首次使用或认证失效时执行
-soke-cli doctor           # 当前版本支持时执行健康检查
-```
+1. 先完成最小就绪探测（版本、登录态、企业绑定），失败才读对应共享文档；
+2. 再确认唯一主路由和模块输入；
+3. 执行前按当前版本 `--help` 发现命令参数；
+4. 写操作前完成通用风险确认和模块专项确认；
+5. 执行后按共享写后验证规则和模块验收标准复核；
+6. 仅报告已验证、已脱敏的结果。
 
-认证、Token、权限和通用错误处理以 [共享 CLI 规则](./references/shared/cli-basics.md) 为准。
+入口不重复展开共享命令、参数、认证、分页、脱敏、重试和轮询规则。
 
 ## 完整意图路由
 
-| 用户意图 | 模块参考 |
-|---|---|
-| 创建、发布、查询课程，配置课程设置 | [soke-course](./references/modules/soke-course/MODULE.md) |
-| 上传或查询视频、音频、文档素材 | [soke-material](./references/modules/soke-material/MODULE.md) |
-| 创建、查询、排序课程课件 | [soke-lesson](./references/modules/soke-lesson/MODULE.md) |
-| 将课程、考试或学习地图指派给用户/部门 | [soke-assign](./references/modules/soke-assign/MODULE.md) |
-| 创建、管理、发布、查询考试/题库/试卷 | [soke-exam](./references/modules/soke-exam/MODULE.md) |
-| 进行可练习题库的随机答题 | [soke-exam-question-pool](./references/modules/soke-exam-question-pool/MODULE.md) |
-| 创建、发布、查询学习地图 | [soke-learning-map](./references/modules/soke-learning-map/MODULE.md) |
-| 查询学员学习档案和学习统计 | [soke-learning-profile](./references/modules/soke-learning-profile/MODULE.md) |
-| 查询证书、证书分类和获得人员 | [soke-certificate](./references/modules/soke-certificate/MODULE.md) |
-| 上传、查询或删除图片库图片 | [soke-photo-gallery](./references/modules/soke-photo-gallery/MODULE.md) |
-| 创建统计导出任务、查询任务状态 | [soke-task](./references/modules/soke-task/MODULE.md) |
-| 查询、提交或投票培训需求 | [soke-training-demand](./references/modules/soke-training-demand/MODULE.md) |
-| AI 教练知识包、场景和知识计划 | [soke-ai-training](./references/modules/soke-ai-training/MODULE.md) |
-| AI 陪练创建、微调、平台同步和质量闸门 | [soke-ai-coach-director](./references/modules/soke-ai-coach-director/MODULE.md) |
-| AI 督导场景、评分标准、指派和发布 | [soke-supervisor](./references/modules/soke-supervisor/MODULE.md) |
+| 用户意图                 | 模块参考                                                                              |
+| -------------------- | --------------------------------------------------------------------------------- |
+| 创建、发布、查询课程，配置课程设置    | [soke-course](./references/modules/soke-course/MODULE.md)                         |
+| 上传或查询视频、音频、文档素材      | [soke-material](./references/modules/soke-material/MODULE.md)                     |
+| 创建、查询、排序课程课件         | [soke-lesson](./references/modules/soke-lesson/MODULE.md)                         |
+| 将课程、考试或学习地图指派给用户/部门  | [soke-assign](./references/modules/soke-assign/MODULE.md)                         |
+| 创建、管理、发布、查询考试/题库/试卷  | [soke-exam](./references/modules/soke-exam/MODULE.md)                             |
+| 进行可练习题库的随机答题         | [soke-exam-question-pool](./references/modules/soke-exam-question-pool/MODULE.md) |
+| 创建、发布、查询学习地图         | [soke-learning-map](./references/modules/soke-learning-map/MODULE.md)             |
+| 查询学员学习档案和学习统计        | [soke-learning-profile](./references/modules/soke-learning-profile/MODULE.md)     |
+| 查询证书、证书分类和获得人员       | [soke-certificate](./references/modules/soke-certificate/MODULE.md)               |
+| 上传、查询或删除图片库图片        | [soke-photo-gallery](./references/modules/soke-photo-gallery/MODULE.md)           |
+| 创建统计导出任务、查询任务状态      | [soke-task](./references/modules/soke-task/MODULE.md)                             |
+| 查询、提交或投票培训需求         | [soke-training-demand](./references/modules/soke-training-demand/MODULE.md)       |
+| AI 教练知识包、场景和知识计划     | [soke-ai-training](./references/modules/soke-ai-training/MODULE.md)               |
+| AI 陪练创建、微调、平台同步和质量闸门 | [soke-ai-coach-director](./references/modules/soke-ai-coach-director/MODULE.md)   |
+| AI 督导场景、评分标准、指派和发布   | [soke-supervisor](./references/modules/soke-supervisor/MODULE.md)                 |
 
 ### 易混淆场景
 
@@ -105,54 +120,58 @@ soke-cli doctor           # 当前版本支持时执行健康检查
 - AI 教练知识包同步 → `soke-ai-training`；陪练创建、微调、资源匹配和发布闸门 → `soke-ai-coach-director`。
 - AI 督导场景管理 → `soke-supervisor`，不要与普通课程指派混用。
 
-## 意图判断与执行流程
-
-1. **识别动作**：区分查询、创建、更新、发布、指派、删除、导出、同步或答题练习。
-2. **确认范围**：明确模块、目标对象、组织/用户范围和输出要求；存在歧义时先询问。
-3. **读取规则**：读取本入口、共享规则和对应模块 `MODULE.md`；复杂场景再读取专项参考资料。
-4. **发现命令**：先运行父级帮助，再运行叶子命令 `--help` 核对参数。
-5. **查询前置数据**：先获取分类、对象或用户的真实 ID，禁止猜测。
-6. **执行与衔接**：按模块定义顺序执行，每一步返回值作为下一步输入。
-7. **确认高风险操作**：发布、指派、删除和批量写入前展示摘要并等待明确确认。
-8. **汇报结果**：只报告相关结果、ID、状态和下一步，不泄露凭证或无关调试输出。
+## 标准执行协议（通用控制面）
 
-## 命令发现与参数边界
+本协议只定义所有业务都适用的控制点，不定义业务检查项、评分标准或领域完成条件。具体模块必须在自己的 `MODULE.md` 或专项参考中声明业务输入、步骤、闸门和验收标准。
 
-`soke-cli` 的命令帮助是当前二进制的最终事实源。文档示例用于理解流程，不能替代实际帮助输出。
+通用控制点如下：
 
-```bash
-soke-cli --help
-soke-cli course --help
-soke-cli exam --help
-soke-cli course +list-courses --help
-soke-cli exam +get-exam-user --help
-soke-cli course +list-courses --format json
-```
+| 控制点 | 入口层要求 | 业务层补充 |
+|---|---|---|
+| 环境 | 版本、配置、认证和权限可用 | 模块所需的额外环境或平台条件 |
+| 路由 | 动作、对象、范围和主管线唯一 | 模块内子场景与业务分支 |
+| 规则 | 共享规则和模块入口已加载 | 领域规则、字段约束和专项参考 |
+| 查询 | 依赖对象使用当前查询得到的真实 ID | 业务对象关系、状态和数据完整性 |
+| 风险 | 高风险动作完成通用确认 | 业务特有影响、发布条件和审批要求 |
+| 执行 | 按模块或工作流顺序执行，保留实际状态 | 业务步骤、检查项和完成判定 |
+| 验证 | 写后查询或读取，结果符合用户目标 | 业务质量闸门和领域验收 |
+| 汇报 | 结果准确、脱敏、说明状态和下一步 | 业务报告格式与专业结论 |
 
-- 有精确覆盖用户意图的 `+verb` shortcut 时，优先使用该 shortcut。
-- shortcut 不存在或不能覆盖完整流程时，按模块文档使用标准命令或 `api` 命令。
-- 文档与 `--help` 不一致时，以当前 `--help` 为准，并说明差异。
-- 不要为了验证参数而执行实际写操作；命令支持 `--dry-run` 时先使用预览模式。
-- 不要把列表响应、详情响应或 `--help` 输出误认为业务操作已经成功。
+每个业务模块至少应补齐：`输入 → 业务动作 → 业务产出 → 业务放行条件 → 失败降级`。入口层只检查这些字段是否已由模块声明，不替模块编写内容。
 
-## 输出与交互规范
+### 路由与执行判定
 
-- 列表结果应说明分页、筛选条件和结果数量，不能把第一页当作全量结果。
-- 需要用户从固定选项中选择时，使用当前 Agent 可用的选择交互，不要求用户重新输入长编号列表。
-- 多步骤流程中，前一步未获得必要结果或用户选择时，不得擅自推进下一步。
-- AI 陪练主管流程必须遵循其前台/后台输出边界，不回显中间 JSON 或调试输出。
+1. **识别动作**：区分查询、创建、更新、发布、指派、删除、导出、同步或答题练习。
+2. **确认范围**：明确模块、目标对象、组织/用户范围和输出要求；存在歧义时先询问。
+3. **选择管线**：先选一个主模块；只有工作流索引明确声明对象交接时才跨模块。
+4. **读取规则**：按“共享规则 → 模块入口 → 专项参考”的顺序按需加载，记录实际读取来源。
+5. **发现命令**：先运行父级帮助，再运行叶子命令 `--help` 核对当前版本参数。
+6. **查询前置数据**：先获取真实 ID，禁止猜测或沿用未经当前查询验证的旧 ID。
+7. **执行与衔接**：每一步的实际返回值作为下一步输入；缺少返回值时停止。
+8. **确认高风险操作**：发布、指派、删除、批量写入和 AI 平台同步前展示摘要并等待明确确认。
+9. **写后验证与汇报**：验证结果后再报告完成；失败必须说明阶段、状态和下一步。
+
+## 通用能力索引
+
+- 命令与参数发现：[command-discovery.md](./references/shared/command-discovery.md)
+- 对象和真实 ID：[object-context.md](./references/shared/object-context.md)
+- 分页与去重：[pagination.md](./references/shared/pagination.md)
+- 交互与确认：[interaction.md](./references/shared/interaction.md)
+- 输出与脱敏：[output-policy.md](./references/shared/output-policy.md)
+- 写后验证：[write-verify.md](./references/shared/write-verify.md)
+- 通用错误处理：[error-handling.md](./references/shared/error-handling.md)
 
 ## 高风险操作确认
 
 以下操作执行前必须展示操作摘要，并获得明确同意：
 
-| 操作类别 | 示例 | 必须说明 |
-|---|---|---|
-| 删除 | 删除课程、考试、证书、图片或任务 | 目标对象和不可逆影响 |
-| 发布/上线 | 发布课程、试卷、考试、学习地图、AI 场景 | 发布对象和可见范围 |
-| 指派 | 给部门或批量用户指派课程、考试、学习地图 | 资源、对象范围和必修/选修属性 |
-| 批量写入 | 批量创建或更新记录 | 数量、字段和失败处理方式 |
-| AI 平台同步 | 应用场景、绑定知识包、发布或关闭场景 | 将要修改的场景和配置摘要 |
+| 操作类别    | 示例                    | 必须说明            |
+| ------- | --------------------- | --------------- |
+| 删除      | 删除课程、考试、证书、图片或任务      | 目标对象和不可逆影响      |
+| 发布/上线   | 发布课程、试卷、考试、学习地图、AI 场景 | 发布对象和可见范围       |
+| 指派      | 给部门或批量用户指派课程、考试、学习地图  | 资源、对象范围和必修/选修属性 |
+| 批量写入    | 批量创建或更新记录             | 数量、字段和失败处理方式    |
+| AI 平台同步 | 应用场景、绑定知识包、发布或关闭场景    | 将要修改的场景和配置摘要    |
 
 确认流程：
 
@@ -191,33 +210,20 @@ Step 4 → 返回执行结果和真实对象 ID
 
 ## 错误处理
 
-1. 记录失败命令、模块、参数摘要和完整错误信息，敏感字段必须脱敏。
-2. 参数错误时运行同一叶子命令的 `--help`，修正后再试；不要换成猜测的命令。
-3. 认证错误时检查配置并执行 `soke-cli auth login`。
-4. 权限错误时告知缺失权限或需要管理员开通的范围，不要绕过权限。
-5. 写操作重试前确认是否可能已经成功，避免重复创建或重复指派。
-6. 仍无法解决时报告失败阶段、错误摘要和建议的人工处理动作。
+通用错误分类、重试顺序、认证恢复和升级规则统一读取[错误处理](./references/shared/error-handling.md)。业务错误码和业务修复动作由对应模块声明；跨模块交接问题由对应工作流声明。
 
-## 随附脚本
+## 检查与索引
 
-发布包只保留有实际职责的 Python 辅助脚本：
+修改发布包后运行：
 
-- AI 陪练质量闸门：[gate_check.py](./references/modules/soke-ai-coach-director/scripts/gate_check.py)
-- AI 陪练操作校验：[validate_operations.py](./references/modules/soke-ai-coach-director/scripts/validate_operations.py)
-- Mono 环境检查：[check_readiness.py](./scripts/check_readiness.py)
-
-使用脚本前先阅读对应模块说明，并使用 `python3` 执行。脚本输出中的凭证、完整响应和调试数据不得直接回显给用户。
+```bash
+python3 ./scripts/check_package.py
+```
 
-## 详细参考（按需读取）
+专项脚本由对应模块声明；入口只维护以下三级索引：
 
-- [安装与认证](./references/installation.md)
-- [共享 CLI 规则](./references/shared/cli-basics.md)
-- [课程模块](./references/modules/soke-course/)
-- [考试模块](./references/modules/soke-exam/)
-- [AI 陪练主管](./references/modules/soke-ai-coach-director/)
-- [AI 教练知识包](./references/modules/soke-ai-training/)
-- [学习地图](./references/modules/soke-learning-map/)
-- [培训需求](./references/modules/soke-training-demand/)
-- [案例库](./references/cases/)
+- [共享能力索引](./references/shared/README.md)
+- [模块责任矩阵](./references/modules/README.md)
+- [跨模块工作流](./references/workflows/)
 
 除非用户明确要求全量内容，否则只读取与当前意图直接相关的模块和参考文件。