@sokeai/cli 1.0.79 → 1.0.80

package/skills/mono/SKILL_MD_/344/274/230/345/214/226/346/226/271/346/241/210.md

@@ -0,0 +1,478 @@
+# mono/SKILL.md 优化方案
+
+> 基于《AI Skill 从零到一》01-14 课，以及当前 `skills/mono/SKILL.md`、架构指南和现有检查器设计整理。
+>
+> 文档性质：方案评审稿。当前只提出修改方案，不直接改写 `SKILL.md`。
+>
+> 目标版本建议：`mono SKILL.md v2.0`（版本号是否采用，待项目现有版本规范确认）
+
+## 1. 结论先行
+
+当前 `SKILL.md` 已具备入口路由、共享规则、高风险确认、跨模块流程和质量脚本说明，统一规则治理的主体已经完成。下一轮不建议继续增加业务细节，而应围绕四个目标优化：
+
+1. **让 Skill 更容易被正确检索和加载**：补充标准 YAML 元数据或等价的入口定位说明，description 使用真实用户原话和高密度触发词。
+2. **让模型更稳定地执行**：把散落在正文中的规则分成强制、条件、建议三档，并将关键流程改成“步骤 + 产出 + 闸门 + 失败处理”。
+3. **让错误更容易诊断和回归**：增加路由诊断、问题分类、四层测试和静默失败验证入口。
+4. **让多人能持续维护和分发**：明确唯一事实源、变更类型、owner、版本、回归和打包交付契约。
+
+总原则：
+
+```text
+SKILL.md 负责定位、路由、控制点和验收入口
+MODULE.md 负责模块职责、输入、流程和业务特例
+references/ 负责复杂规则与唯一事实源
+workflows/ 负责跨模块对象交接
+platform/adapters/ 负责平台差异
+scripts/ 负责可自动验证的规则
+```
+
+## 2. 现状评估
+
+### 2.1 已经做好的部分
+
+| 能力 | 当前状态 | 依据 |
+|---|---|---|
+| 入口路由 | 已有两套路由表和易混淆场景 | `SKILL.md` 意图路由 |
+| 全局边界 | 已有 NEVER DO / MUST DO | `SKILL.md` 第 47-63 行 |
+| 风险确认 | 已覆盖删除、发布、指派、批量写入、AI 同步 | `SKILL.md` 第 142-161 行 |
+| CLI 事实源 | 已明确 `--help` 优先 | `SKILL.md` 第 116-133 行 |
+| 跨模块链路 | 已有课程、考试、地图三条链路 | `SKILL.md` 第 163-187 行 |
+| 错误处理 | 已覆盖参数、认证、权限、重试和人工处理 | `SKILL.md` 第 189-196 行 |
+| 包级检查 | 已有 `check_package.py`，并已纳入平台一致性检查 | `scripts/check_package.py` |
+| 架构边界 | 已有六层架构、唯一来源矩阵、DoD | `ARCHITECTURE_AND_EXTENSION_GUIDE.md` |
+
+### 2.2 主要缺口
+
+| 缺口 | 表现 | 影响 |
+|---|---|---|
+| 元数据缺口 | 当前入口文件没有 YAML frontmatter / 标准 description | 依赖外部索引时可能检索不准；无法显式区分入口型和过程型 |
+| 控制模式不够显式 | 有“意图路由”和“标准流程”，但没有一句话声明“外调度、内编排” | 模型可能把所有模块都当成线性流程，或擅自跨管线 |
+| 闸门不完整 | 有确认流程，但没有统一列出触发条件、通过标准、不通过处理 | 规则存在，执行停点和失败动作不够明确 |
+| 任务产出不够明确 | 流程步骤主要描述动作，较少写出每步必须保留的对象/状态 | 多步操作时容易丢失上下文或误报完成 |
+| 诊断入口不足 | 错误处理偏“出错后处理”，没有先做问题类型分流 | 技术问题、业务问题、流程问题可能走错模块 |
+| 测试入口不足 | 有静态检查命令，但缺少功能、边界、回归、混沌四层验收定义 | `check_package.py` 通过不等于业务流程可用 |
+| 维护契约分散 | 版本、owner、变更日志、打包交付主要在架构指南中 | 仅拿到 `SKILL.md` 的维护者不一定知道发版要求 |
+| 成本控制偏声明 | 当前入口只强调按需读取，缺少“本步骤只读哪些文件”的结构化约束 | 容易重复加载、重复查询和输出过多内容 |
+
+## 3. 14 课到 SKILL.md 的映射
+
+| 课程 | 应转化的入口能力 | 在 `SKILL.md` 的落点 | 优先级 |
+|---|---|---|---|
+| 01 告别调 prompt | 用控制点和结构解决重复翻车，不继续堆提示词 | 开篇定位、失败反馈规则 | P1 |
+| 02 能力边界 | 决策四问；区分整理型、执行型、技术型任务 | 新增“任务适配判断” | P1 |
+| 03 Markdown 六要素 | 标题分区、有序步骤、并列清单、代码合同、强约束、闸门表 | 重排流程和规则表达 | P0 |
+| 04 description/YAML | 入口型 metadata、真实用户原话、最小权限 | 新增 frontmatter 或兼容说明 | P0 |
+| 05 两种主管模式 | 外部调度、内部编排；独立管线、独立闸门 | 意图流程前增加模式声明 | P0 |
+| 06 任务拆解 | 每步有产出、步间有闸门、失败有降级 | 改写意图判断与执行流程 | P0 |
+| 07 质量闸门 | 闸门四要素；内容、覆盖、来源三层验证 | 新增入口级 Gate Check | P0 |
+| 08 微调诊断 | 先分类再行动；技术问题不进业务流程 | 新增问题诊断分流 | P1 |
+| 09 测试四层 | 功能、边界、回归、混沌；静态检查不是业务验收 | 新增验收分层 | P1 |
+| 10 版本打包 | SSOT、变更日志、发版回归、打包检查 | 新增维护与交付契约 | P1 |
+| 11 创建容易落地难 | 检索、执行、拆解、闸门四关 | 新增“完成定义” | P1 |
+| 12 创建者/使用者闭环 | 用户反馈需包含场景、期望、实际 | 新增反馈格式 | P1 |
+| 13 团队协作分发 | owner、依赖、安装、教程、版本和反馈入口 | 新增多人维护规则 | P1 |
+| 14 持续优化与降本 | 声明性约束升级为结构性约束；先算账再改 | 新增加载/输出成本规则 | P1 |
+
+## 4. 建议的目标目录结构
+
+建议将入口文件收敛为以下顺序，控制在约 220-300 行，细节继续下放：
+
+```text
+# 授客AI CLI 全业务 Skill
+YAML 元数据 / 入口定位
+
+## 1. 技能定位与边界
+  - 负责什么
+  - 不负责什么
+  - 外调度 + 内编排
+
+## 2. 触发与意图路由
+  - 用户原话触发词
+  - 意图路由矩阵
+  - 易混淆场景
+  - 路由闸门
+
+## 3. 全局强制规则
+  - NEVER DO
+  - MUST DO
+  - 条件规则
+  - 建议规则
+
+## 4. 标准执行协议
+  Step 0 环境与认证
+  Step 1 意图与范围
+  Step 2 读取规则
+  Step 3 查询真实对象
+  Step 4 确认风险
+  Step 5 执行动作
+  Step 6 写后验证
+  Step 7 输出摘要
+
+## 5. 高风险操作闸门
+  - 闸门四要素
+  - 确认协议
+
+## 6. 跨模块工作流索引
+  - 课程
+  - 考试
+  - 地图
+  - AI
+
+## 7. 错误诊断与降级
+  - T 技术
+  - 参数/认证/权限
+  - 业务/流程
+  - 重试与暂停
+
+## 8. 测试、发版与反馈
+  - 静态检查
+  - 四层测试
+  - 变更日志
+  - 多人协作
+  - 用户反馈格式
+
+## 9. 按需读取索引
+```
+
+当前内容不是全部重写；现有章节可按上述目标顺序迁移并合并重复部分。
+
+## 5. 分阶段修改方案
+
+### P0：入口控制面优化
+
+#### P0-1 补充入口定位与 description
+
+建议在文件顶部增加兼容的 YAML frontmatter。具体字段是否被当前宿主识别，需要先用现有 Skill 样例或平台规范确认；若当前 Mono 包不支持 frontmatter，则保留“入口定位”正文，并在索引层维护 description。
+
+建议内容：
+
+```yaml
+---
+name: soke-cli-mono
+# description 使用用户原话，不写“这是一个 Skill”
+description: >-
+  管理授客AI课程、素材、课件、考试、题库、学习地图、学员档案、证书、培训需求、AI 教练、AI 陪练和 AI 督导；
+  支持创建、查询、更新、发布、指派、导出、同步、排障和质量检查；
+  用户可以说“帮我创建课程”“上传课件”“发布考试”“指派学习地图”“同步 AI 陪练场景”“检查同步问题”来调用。
+---
+```
+
+约束：
+
+- `name` 使用小写字母、数字和连字符，避免空格和引号。
+- description 覆盖“核心功能 + 输入类型 + 主要输出 + 用户原话”。
+- 不在 description 中堆放内部文件名、完整命令和实现细节。
+- frontmatter 变更必须同步检查索引和打包格式。
+
+#### P0-2 增加“技能定位与不负责”
+
+把入口文件从“目录说明”升级为边界合同：
+
+```markdown
+## 技能定位与边界
+
+本 Skill 是授客AI CLI 的总入口，负责：
+- 判断用户动作和目标业务对象；
+- 路由到正确模块或跨模块工作流；
+- 执行全局前置、风险确认、真实 ID、写后验证和输出脱敏规则。
+
+本 Skill 不负责：
+- 直接定义模块专属字段和完整参数；
+- 替代模块 MODULE.md；
+- 把平台适配差异写进业务模块；
+- 绕过 CLI 直接调用业务 API。
+```
+
+这样可直接落实第 01、05、10 课的“入口与细节分层”。
+
+#### P0-3 明确“外调度 + 内编排”
+
+在意图判断前增加：
+
+```markdown
+## 主管模式
+
+本 Skill 采用“外部调度 + 管线内编排”模式：
+
+- 对外：根据用户动作选择课程、考试、AI 陪练等独立管线；
+- 对内：每条管线按模块文档的步骤和闸门执行；
+- 管线之间禁止擅自串接；只有跨模块工作流明确声明对象交接时才能衔接；
+- 某条管线失败时，禁止假设其他管线已完成。
+```
+
+这解决当前“有路由但模式未声明”的问题。
+
+#### P0-4 把标准执行流程改成“步骤 + 产出 + 闸门”
+
+将当前第 105-114 行改为以下结构：
+
+| 步骤 | 必须动作 | 最小产出 | 放行条件 |
+|---|---|---|---|
+| Step 0 | 检查版本、配置、认证和权限 | 环境状态 | 阻塞项已解决 |
+| Step 1 | 判断动作、对象、范围 | 路由结果 | 只有一个主路径 |
+| Step 2 | 读取共享规则和模块入口 | 已加载规则清单 | 规则来源明确 |
+| Step 3 | 查询真实对象和 ID | 对象上下文 | ID 来自当前查询 |
+| Step 4 | 生成风险摘要并确认 | 用户明确确认 | 高风险操作才放行 |
+| Step 5 | 执行模块动作 | 命令结果/状态 | 命令真实完成 |
+| Step 6 | 读取或查询验证结果 | 写后验证结论 | 结果与预期一致 |
+| Step 7 | 输出摘要和下一步 | 用户可读结论 | 不泄露内部数据 |
+
+每个步骤必须满足：
+
+```text
+有输入 → 有动作 → 有产出 → 有放行条件；失败时有暂停或降级处理。
+```
+
+### P1：质量和诊断优化
+
+#### P1-1 增加统一路由闸门
+
+路由错误会让后续全部步骤失效，应在进入模块前增加：
+
+| 检查项 | 获取方式 | 严重度 | 不通过时处理 |
+|---|---|---|---|
+| 用户动作已识别 | 用户原话 + 动作词 | 阻塞 | 追问动作 |
+| 业务对象已识别 | 对象名/上下文 | 阻塞 | 追问对象 |
+| 目标范围已识别 | 用户、部门、课程或场景范围 | 阻塞 | 追问范围 |
+| 是否跨模块已识别 | 工作流索引 | 警告/阻塞 | 选择工作流 |
+| 是否高风险已识别 | 操作类别表 | 阻塞 | 进入确认协议 |
+
+#### P1-2 增加问题诊断分流
+
+把错误处理前增加“先分类”：
+
+```markdown
+## 问题诊断顺序
+
+1. 技术问题：unknown command、404、500、按钮、录音、ASR/TTS、权限、部署失败。
+   **禁止**进入业务内容优化；走技术排障或暂停等待接口。
+2. 输入问题：文件为空、格式不支持、缺少必要字段。
+   追问缺口，不强行生成。
+3. 路由问题：动作或业务对象判断错误。
+   回到 Step 1，重新确认。
+4. 流程问题：步骤跳过、确认缺失、写后未验证。
+   修复流程或补闸门，不只改文案。
+5. 业务内容问题：字段值、对象状态或业务规则错误。
+   进入对应模块的专项规则。
+```
+
+每次反馈建议按以下格式收集：
+
+```text
+场景：在哪个模块、哪个对象、哪一步发生
+期望：用户预期结果
+实际：实际结果、错误信息或回读结果
+```
+
+#### P1-3 增加四层测试入口
+
+在脚本说明后增加：
+
+| 层级 | 目标 | Mono 包验收方式 |
+|---|---|---|
+| 功能 | 正常路径可完成 | `check_package.py` + 一条真实模块流程 |
+| 边界 | 空值、上限、非法状态可控 | 针对新增规则补边界样例 |
+| 回归 | 改动没有破坏旧能力 | 至少 3 条稳定基准流程 |
+| 混沌 | 超时、404、500、取消、半成功可优雅处理 | 检查暂停、重试、回滚或人工接管 |
+
+明确结论：
+
+```text
+check_package.py 通过，只代表包结构和静态规则通过；不代表业务流程已验收。
+```
+
+#### P1-4 完善闸门四要素
+
+当前高风险确认只有确认步骤，建议统一写成四要素：
+
+1. 检查项：检查什么；
+2. 获取方式：从哪里查；
+3. 严重度：阻塞还是警告；
+4. 不通过处理：修正、追问、暂停或降级。
+
+高风险操作的放行条件统一为：
+
+```text
+目标对象真实 + 影响范围明确 + 用户明确确认 + 执行后验证通过
+```
+
+### P2：维护、协作和成本优化
+
+#### P2-1 增加唯一事实源规则
+
+```markdown
+## 维护规则
+
+- 通用认证、分页、确认、脱敏、重试规则只维护在 `references/shared/`；
+- 模块职责和对象边界维护在模块入口与模块矩阵；
+- 跨模块交接维护在 `references/workflows/`；
+- 平台状态维护在支持矩阵，平台差异维护在适配器；
+- `SKILL.md` 只保留导航、控制点和验收入口，不嵌入大型业务规则；
+- 同一规则出现第二份时，必须先判断是否应改为引用唯一事实源。
+```
+
+#### P2-2 增加版本和多人协作契约
+
+```markdown
+## 变更与交付契约
+
+- 小改动：更新变更日志并运行静态检查；
+- 结构重构、共享规则、平台适配和入口变更：必须记录影响范围并走评审；
+- 发版前必须通过 `check_package.py`、`git diff --check` 和至少 3 条回归流程；
+- 新增模块必须同步入口路由、模块索引、相关工作流和检查规则；
+- 新增平台必须同步适配器、支持矩阵、适配器索引和路由说明；
+- 删除平台不得删除通用降级路径；
+- 每次反馈必须能回溯到场景、期望、实际和处理结果。
+```
+
+#### P2-3 将“按需读取”升级为结构性加载规则
+
+当前“避免一次性加载”是声明性规则，建议补充结构化执行协议：
+
+```markdown
+## 加载范围
+
+- Step 0 只读取安装、环境、认证和 CLI 共用规则；
+- 路由确定前，禁止读取所有业务模块细节；
+- 路由确定后，只读取目标模块 `MODULE.md` 和当前动作直接依赖的参考文件；
+- 跨模块流程只读取工作流契约和当前模块入口，不重复读取无关模块全文；
+- 用户未要求展示时，完整 JSON、内部命令输出和调试信息只落盘或后台处理，不放入前台回复。
+```
+
+这比“尽量按需读取”更容易执行，也符合第 14 课的结构性约束原则。
+
+## 6. 建议保留、不宜直接改动的内容
+
+以下内容当前已经稳定，不建议在本轮为了形式统一而重写：
+
+1. `soke-cli` 作为唯一业务命令入口的规则；
+2. 禁止编造 UUID 和敏感凭证脱敏规则；
+3. 现有高风险操作类别及确认协议；
+4. 课程、考试、地图三条跨模块对象链路；
+5. `check_syntax.py` 避免生成 Python 缓存的说明；
+6. 详细参考文件索引；
+7. 平台适配器和支持矩阵的具体业务内容。
+
+这些属于已经完成的统一治理成果，后续只做链接和一致性维护。
+
+## 7. 不建议采用的方案
+
+| 方案 | 不采用原因 |
+|---|---|
+| 把 14 课全文塞进 `SKILL.md` | 增加常驻上下文，削弱入口信号 |
+| 为每个模块复制一套认证和分页规则 | 破坏唯一事实源，后续容易漂移 |
+| 只增加更多“必须遵守”文字 | 声明性约束无法替代结构性流程 |
+| 用一张超大表替代全部正文 | 表格适合闸门和矩阵，不适合所有业务输出 |
+| 只跑 `check_package.py` 就宣布完成 | 静态通过不等于真实流程、边界和回归通过 |
+| 一次性加入全部 YAML 高级字段 | 当前没有真实权限隔离或生命周期钩子需求，不应为完整而完整 |
+| 为降本删除关键确认和写后验证 | 降本底线是稳定性，不能以静默失败换 token |
+
+## 8. 分阶段实施顺序
+
+### 第一批：入口和控制点
+
+- [ ] 确认当前宿主是否支持 YAML frontmatter；
+- [ ] 补充 `name`、高密度 description 或等价索引说明；
+- [ ] 增加“技能定位与不负责”；
+- [ ] 增加“外调度 + 内编排”声明；
+- [ ] 重写标准执行流程为“步骤 + 产出 + 闸门”；
+- [ ] 合并两套路由表，保留一张主表和一张易混淆表。
+
+### 第二批：质量和诊断
+
+- [ ] 增加路由闸门矩阵；
+- [ ] 增加问题分类和技术优先分流；
+- [ ] 增加闸门四要素说明；
+- [ ] 增加四层测试入口；
+- [ ] 明确静态检查与真实验收的边界。
+
+### 第三批：维护和成本
+
+- [ ] 增加唯一事实源和变更归属规则；
+- [ ] 增加多人协作、版本和发版契约；
+- [ ] 将按需读取改为步骤级加载清单；
+- [ ] 补充前台/后台输出边界；
+- [ ] 运行包级检查、链接检查和至少 3 条回归流程。
+
+## 9. 验收标准
+
+### 9.1 静态验收
+
+```bash
+python3 ./scripts/check_package.py
+python3 ./scripts/check_syntax.py
+ git diff --check
+```
+
+预期：全部通过，无旧路径、无死链接、无重复认证、无重复共享规则、平台矩阵/适配器/索引一致。
+
+### 9.2 入口验收
+
+使用以下用户原话验证路由：
+
+```text
+帮我创建一门课程
+上传这个课件
+发布考试并指派给部门
+同步 AI 陪练场景
+AI 陪练同步不上，帮我排查
+查询学习地图统计
+```
+
+每条输入必须：
+
+- 命中正确模块或工作流；
+- 不读取无关模块全文；
+- 高风险操作先确认；
+- 技术问题不误进业务内容优化；
+- 输出用户可读摘要，不泄露内部调试信息。
+
+### 9.3 流程验收
+
+至少覆盖：
+
+1. 一条正常查询流程；
+2. 一条创建/写入并验证流程；
+3. 一条发布或指派确认流程；
+4. 一条跨模块对象交接流程；
+5. 一条参数或认证失败降级流程。
+
+### 9.4 回归验收
+
+入口文件变化后，至少回归：
+
+- 课程创建/发布链路；
+- 考试创建/查询链路；
+- AI 陪练创建或同步链路。
+
+如果平台能力不可用，必须记录为“未完成真实验收”，不能用静态检查替代。
+
+## 10. Definition of Done
+
+本轮 `SKILL.md` 优化只有同时满足以下条件才算完成：
+
+- [ ] 入口定位和 description 已确认；
+- [ ] 责任边界和“不负责”已写清；
+- [ ] 外部调度、内部编排模式已写清；
+- [ ] 主路由表唯一且无明显重复；
+- [ ] 标准流程每步都有最小产出；
+- [ ] 关键停点都有通过标准和失败处理；
+- [ ] 技术问题、输入问题、路由问题和业务问题能分流；
+- [ ] 四层测试入口已定义；
+- [ ] 静态检查与真实验收边界已声明；
+- [ ] 唯一事实源和多人变更契约已引用；
+- [ ] 加载范围已结构化；
+- [ ] `check_package.py`、`check_syntax.py`、`git diff --check` 通过；
+- [ ] 至少完成 3 条回归流程；
+- [ ] `CHANGELOG.md` 已记录本轮改动和原因。
+
+## 11. 需要确认的 4 个决策
+
+在真正修改 `SKILL.md` 前，建议只确认以下四点：
+
+1. 当前 Mono 包是否允许在 `SKILL.md` 使用 YAML frontmatter？若不允许，是否把 description 放入外部索引或 README？
+2. 是否将两套路由表合并为一张主路由表，以减少重复？
+3. `SKILL.md` 是否承担团队维护契约，还是只引用 `ARCHITECTURE_AND_EXTENSION_GUIDE.md`？
+4. 四层测试中的真实回归场景，是否固定为课程、考试、AI 陪练三条基准链路？
+
+默认建议：采用方案正文中的 P0 + P1，P2 以引用和最小新增规则落地；不在本轮引入未验证的高级 YAML 字段。

package/skills/mono/references/modules/README.md

@@ -0,0 +1,74 @@
+# 业务模块责任矩阵
+
+本文件是 Mono Skill 业务模块的导航与边界说明。共享环境、认证、命令、对象、分页、确认、脱敏、写后验证和错误处理规则，统一以 `../shared/` 为唯一来源；本文件只描述模块职责和模块间关系。
+
+## 模块矩阵
+
+| 模块 | 负责对象 | 典型动作 | 主要依赖 | 不负责 |
+|---|---|---|---|---|
+| `soke-course` | 课程 | 创建、配置、发布、查询 | `soke-material`、`soke-lesson`、`soke-assign` | 不负责素材上传、课件创建和指派实现 |
+| `soke-material` | 视频、音频、文档等素材 | 上传、查询、删除 | `file-input`、`object-context` | 不负责课程章节和课程发布 |
+| `soke-lesson` | 课程课件/章节 | 创建、查询、排序 | `soke-course`、`soke-material` | 不负责素材上传和课程发布 |
+| `soke-assign` | 用户、部门与学习资源的指派关系 | 查询对象、创建指派、查询指派 | 课程、考试或学习地图模块 | 不负责资源创建或配置 |
+| `soke-exam` | 考试、题库、试题、试卷 | 创建、管理、发布、成绩查询 | `soke-assign` | 不负责随机答题练习 |
+| `soke-exam-question-pool` | 可练习题库和答题会话 | 随机出题、作答、提交 | `soke-exam` | 不负责考试发布和成绩报表 |
+| `soke-learning-map` | 学习地图、阶段和课程路径 | 创建、配置、发布、查询 | `soke-course`、`soke-assign`、`soke-task` | 不负责课程内容创建 |
+| `soke-learning-profile` | 学员学习档案和统计 | 查询学习记录、统计和明细 | `soke-task` | 不负责课程或考试配置 |
+| `soke-task` | 统计导出和异步任务 | 创建任务、轮询状态、获取结果 | `async-task` | 不负责普通列表查询 |
+| `soke-certificate` | 证书、证书分类和获得记录 | 查询证书、分类和人员 | `pagination`、`output-policy` | 不负责证书模板设计或颁发流程以外的资源配置 |
+| `soke-photo-gallery` | 图片库图片和图片分类 | 上传、查询、删除 | `file-input`、`object-context` | 不负责课程素材和课件创建 |
+| `soke-training-demand` | 培训需求及其投票记录 | 查询、提交、投票 | `interaction`、`write-guard` | 不负责课程创建或需求自动转课程 |
+| `soke-ai-training` | AI 教练知识包、素材来源和条目 | 创建、同步、绑定、查询 | `file-input`、`write-verify`、`async-task` | 不负责 AI 陪练 Part 流程 |
+| `soke-ai-coach-director` | AI 陪练场景、角色、评分和发布状态 | 创建、微调、同步、闸门校验、发布 | `state-machine`、`write-guard`、`write-verify` | 不负责普通课程和 AI 教练知识包管理 |
+| `soke-supervisor` | AI 督导场景、评分标准和指派 | 配置、指派、发布、查询 | `soke-assign`、`write-guard` | 不负责 AI 陪练场景或普通课程发布 |
+
+## 跨模块边界
+
+### 课程链路
+
+```text
+soke-material（上传素材）
+→ soke-lesson（创建课件）
+→ soke-course（配置/发布课程）
+→ soke-assign（指派课程）
+```
+
+上传素材和创建课件是两个独立动作；素材上传成功后产生的真实素材标识，才能作为课件创建的输入。
+
+### 考试链路
+
+```text
+soke-exam（考试/题库/试卷）
+→ soke-assign（指派考试）
+→ soke-exam-question-pool（练习题库答题）
+```
+
+随机答题练习不能替代考试发布，也不能用练习会话代替考试成绩查询。
+
+### 学习地图链路
+
+```text
+soke-course（课程）
+→ soke-learning-map（地图与阶段）
+→ soke-assign（指派地图）
+→ soke-task（统计导出）
+```
+
+### AI 链路
+
+```text
+soke-ai-training（知识包）
+→ soke-ai-coach-director（陪练场景）
+
+soke-supervisor（AI 督导场景）
+```
+
+AI 教练知识包同步和 AI 陪练场景发布是不同业务动作，不能混用模块或对象 ID。
+
+## 选择规则
+
+1. 先按用户的核心动作选模块，不按名词猜模块。
+2. 涉及多个模块时，按对象依赖顺序执行，并沿用上一步返回的真实 ID。
+3. 查询、创建、发布、指派、删除的风险等级和确认要求，统一读取 `../shared/` 对应规则。
+4. 模块文档与当前 CLI 帮助冲突时，以当前 CLI 的帮助输出为准。
+5. 模块自身的 `MODULE.md` 只补充业务字段、业务状态和平台特例，不重复共享层规则。

package/skills/mono/references/modules/soke-ai-coach-director/CHANGELOG.md

@@ -149,7 +149,7 @@
 
 ### 优化
 - **Part 展示完成 → 立即弹窗确认**：移除「先输出文字请确认 → 用户输入'确认' → 再弹出确认窗」的中间文字闸门。Part 内容在对话中完整展示后立即弹出确认窗（render_ui / AskUserQuestion），弹窗即确认环节，用户直接通过弹窗选项作答，无需先回复"确认"
-- **SKILL.md / interaction.md / prompt-engineer.md / prompt-optimizer.md / exec-handbook.md / workbuddy 适配器 / part2 SOP 同步更新**：各 Part 弹窗步骤与核心规则统一补充「展示检查通过 → 立即弹窗」时序约束；正文文字确认格式仅保留给无弹窗环境的降级场景（悟空/QClaw/Zework/纯文本）
+- **SKILL.md / interaction.md / prompt-engineer.md / prompt-optimizer.md / exec-handbook.md / workbuddy 适配器 / part2 SOP 同步更新**：各 Part 弹窗步骤与核心规则统一补充「展示检查通过 → 立即弹窗」时序约束；正文文字确认格式仅保留给无弹窗环境的降级场景（千问/QClaw/Zework/纯文本）
 
 ## v2.29.0 — 2026-08-17
 

package/skills/mono/references/modules/soke-ai-coach-director/MODULE.md

@@ -6,6 +6,14 @@ agent_created: true
 
 # 授客AI平台同步技能
 
+## 共用前置
+
+开始平台操作前，先读取 `../../shared/environment-check.md`、`../../shared/auth-check.md`、`../../shared/object-context.md`、`../../shared/output-policy.md`、`../../shared/write-verify.md`、`../../shared/async-task.md`、`../../shared/state-machine.md` 和 `../../shared/error-handling.md`。本模块只补充 AI 陪练专属依赖与流程规则。
+
+## 业务产出与完成判定
+
+本模块产出已创建或更新的 AI 陪练场景、角色/评分/流程配置、知识包绑定记录及发布状态。只有对应 Part 同步成功、质量闸门通过、发布状态和必要绑定关系可验证时，才能报告完成；具体闸门由本模块执行文件和 `gate-check-matrix.md` 定义。
+
 ## 版本
 v2.43.1 — 交付后不写日志 / get 回读零上下文 / 知识包条目预生成 / Part4+5 合并应用（exec-part5.md 已删除，规则并入 exec-part4.md）/ sed 输出限流 / 工具化闸门（gate_check.py）/ OS 结构内联 / 材料 sed 单命令 / 积分目标 ≤75（内容生成为不可压地板 ~49）/ 弹窗仅做确认（question ≤2 行）/ 加载顺序清单 / CLI 全静默重定向 / apply 禁止用于验证 / 提炼稿一次成型 / 知识包复用提炼稿
 
@@ -83,6 +91,10 @@ v2.43.1 — 交付后不写日志 / get 回读零上下文 / 知识包条目预
 
 ---
 
+## 输入
+
+按任务类型接收用户目标、已有场景或材料提炼稿、需要修改的对象范围，以及平台同步所需的真实场景/知识包上下文。各任务的必需输入和缺口处理以对应管线为准。
+
 ## 标准任务类型
 
 1. **创建型**：搭建新陪练。→ 严格顺序管线 Step 0→10，🔒 不得跳步。

package/skills/mono/references/modules/soke-ai-coach-director/README.md

@@ -84,7 +84,7 @@ soke-ai-coach-director/
 │   ├── adapters/                # 跨平台适配器
 │   └── soke-ai-training/        # 知识包同步
 ├── references/                  # 参考规则
-│   ├── exec-handbook.md         # 唯一执行事实源
+│   ├── exec-handbook.md         # 历史兼容参考（非当前事实源）
 │   ├── env-check.md             # 环境检测协议
 │   ├── verified-cli-cheatsheet.md # CLI 速查
 │   ├── role-resource-matching.md  # 资源匹配规则

package/skills/mono/references/modules/soke-ai-coach-director/coaching/prompt-optimizer/prompt-optimizer.md

@@ -352,9 +352,9 @@ Step 6.5 改动清单确认通过后，按 `../../platform/interaction.md` 的
 **选「确认修改（推荐）」** → 根据 `../../platform/sync-engine.md` 生成 `optimize-operations.json`，执行自动同步链：
 
 ```bash
-soke-cli ai-training +get-scenario --scenario-id <scenario_id> --pretty
-soke-cli ai-training +preview-scenario-update --scenario-id <scenario_id> --base-updated-at <updated_at> --operations-file ./optimize-operations.json --idempotency-key "cli-<scenario_short>-opt-preview" --reason "优化提示词" --pretty
-soke-cli ai-training +apply-scenario-update --scenario-id <scenario_id> --base-updated-at <updated_at> --operations-file ./optimize-operations.json --idempotency-key "cli-<scenario_short>-opt-apply" --reason "优化提示词" --pretty
+soke-cli ai-training +get-scenario --scenario-id <scenario_id> --raw > /tmp/opt_get.json 2>/dev/null
+soke-cli ai-training +preview-scenario-update --scenario-id <scenario_id> --base-updated-at <updated_at> --operations-file ./optimize-operations.json --idempotency-key "cli-<scenario_short>-opt-preview" --reason "优化提示词" > /tmp/opt_preview.json 2>/dev/null
+soke-cli ai-training +apply-scenario-update --scenario-id <scenario_id> --base-updated-at <updated_at> --operations-file ./optimize-operations.json --idempotency-key "cli-<scenario_short>-opt-apply" --reason "优化提示词" > /tmp/opt_apply.json 2>/dev/null
 ```
 
 `<scenario_id>` 取当前任务上下文中已存在的场景 ID；`<updated_at>` 通过 `soke-cli ai-training +get-scenario` 自动获取，不要求用户手工回传。

package/skills/mono/references/modules/soke-ai-coach-director/platform/adapters/README.md

@@ -1,6 +1,8 @@
 # 平台交互适配器
 
 > 内部规则文件。定义不同 AI Agent 平台的交互适配策略，确保业务逻辑层（Part1-5 管线）在不同平台上行为一致。
+>
+> 适配器属于可选兼容层，不是业务管线依赖。未部署某个平台时，可移除对应适配器，但必须同步更新本索引、`interaction.md` 的平台路由说明和变更日志；通用降级路径必须保留。
 
 ## 适配器接口（统一契约）
 
@@ -17,7 +19,7 @@
 ```
 检测运行环境 → 匹配平台 → 加载对应适配器
   ├─ WorkBuddy (AskUserQuestion / render_ui) → workbuddy.md
-  ├─ 悟空 (钉钉 IM 对话) → wukong.md
+  ├─ 千问 (Qwen 对话) → qwen.md
   ├─ QClaw (ClawHub 技能) → qclaw.md
   └─ Zework (内部平台) → zework.md
 ```
@@ -29,7 +31,7 @@
 | 平台 | 文件 | 交互机制 | CLI 执行 |
 |------|------|---------|---------|
 | WorkBuddy | `workbuddy.md` | `AskUserQuestion` / `render_ui` | `dangerouslyDisableSandbox: true` |
-| 悟空 | `wukong.md` | 钉钉 IM 结构化文本 | 悟空沙箱 CLI |
+| 千问 | `qwen.md` | Qwen 对话结构化文本 | Qwen 沙箱 CLI |
 | QClaw | `qclaw.md` | ClawHub 技能格式 | OpenClaw 框架 Bash |
 | Zework | `zework.md` | 纯文本 + 编号交互 | 内部 CLI / API fallback |
 | 通用降级 | 本文件 §通用降级 | 纯文本结构化 | REST API fallback |

package/skills/mono/references/modules/soke-ai-coach-director/platform/adapters/qclaw.md

@@ -1,6 +1,8 @@
 # QClaw 平台适配器
 
 > QClaw 是腾讯电脑管家的桌面 AI 助手，基于 OpenClaw 框架，通过 ClawHub 技能生态和微信远程操控进行交互。
+>
+> **生命周期：可选兼容层。** 仅当交付目标明确包含 QClaw/OpenClaw/ClawHub 时加载；默认 WorkBuddy 运行不依赖本文件。若产品不再支持 QClaw，可删除本文件并同步更新适配器索引、路由说明和变更日志，不得删除通用降级规则。
 
 ## 运行环境检测
 
@@ -44,7 +46,7 @@ QClaw 基于 OpenClaw 框架，可以执行系统命令。soke-cli 为 npm 全
 
 ```bash
 # QClaw 中执行 soke-cli 命令
-soke-cli ai-training +create-scenario --request-file ./step1-create.json --pretty
+soke-cli ai-training +create-scenario --request-file ./step1-create.json > /tmp/step1-create.json 2>/dev/null
 ```
 
 若 soke-cli 在 QClaw 环境中不可用，降级为 REST API 直接调用（参考 `../api-fallback.md`）。