@sokeai/cli 1.0.79 → 1.0.80

package/skills/mono/references/modules/soke-training-demand/MODULE.md

@@ -17,7 +17,39 @@ metadata:
 
 # 培训需求收集
 
-**CRITICAL — 开始前 MUST 先读取 ../soke-shared/MODULE.md，其中包含认证、配置和权限处理。**
+## 共用前置
+
+开始前读取 `../../shared/README.md`，并按需加载环境检测、登录验证、对象上下文、分页、交互、写守卫、输出、写后验证和错误处理规则。本模块只保留培训需求特有规则。
+
+## 职责
+
+负责培训需求分类查询、需求提交、需求浏览和投票；不负责课程创建、考试配置或培训项目执行。
+
+## 输入
+
+- 培训需求分类及其由平台返回的标签。
+- 用户填写的需求描述和紧急程度。
+- 用户明确的浏览、提交或投票意图。
+
+## 流程
+
+浏览需求/分类 → 按严格四步收集提交信息（分类 → 标签 → 描述 → 紧急程度）→ 创建需求；投票前先查询列表并确认目标。
+
+## 业务特例
+
+- 提交需求必须严格执行四步，每步单独等待用户回复；标签为空时才自动跳过标签步骤。
+- 标签只能来自用户选定分类对象的原始 `tag` 字段，最多选择 5 个，禁止跨分类或自行创建。
+- `--category-uuid` 来自分类查询，投票 `--uuid` 来自需求列表；二者不得混用。
+- 提交成功不展示需求 UUID，`create_time` 展示时从 UTC 转为 UTC+8。
+
+**失败降级**：`+create` 报“分类无效”时，重新执行 `+list-categories` 取真实 `uuid`，不得手写；报“标签无效”时从所选分类原始 `tag` 重新选取；`+vote` 报“需求无效”时确认传入的是 `+list` 的需求 `uuid` 而非分类 `uuid`。任何一步失败都停下说明，不得跳过四步流程或强行重试。
+
+## 输出
+
+- 返回分类、需求列表、提交结果或投票结果的业务摘要。
+- 提交结果隐藏需求 UUID；输出格式和敏感信息处理遵循共享层规则。
+
+**完成判定**：需求提交完成当且仅当 `+create` 返回成功且（必要时）该需求可在 `+list` 中按标题/创建人检索到；投票完成当且仅当 `+list` 中对应需求的票数已增加。仅回显“操作成功”但 `+list` 查不到对应需求或票数未变的，视为未完成。
 
 ## 🛑 执行守卫（EXECUTION GUARD）
 
@@ -30,22 +62,11 @@ metadata:
 >
 > 5. **标签-分类严格绑定**：步骤 2 展示标签时，MUST 严格使用步骤 1 中用户选定的分类对象（通过序号从 +list-categories 的 data.list 中精确取出）的 tag 字段。NEVER 用其他分类的 tag、NEVER 凭记忆猜测、NEVER 用列表中其他位置分类的 tag。不确定时 MUST 重新调用 +list-categories 按序号精确匹配。
 
-## 核心规则
-
-- 分类、标签必须与管理后台设置完全一致，**禁止自行拓展或创造分类/标签**。标签来源仅限用户所选分类的 tag 字段。
-- 提交培训需求必须严格按以下 **4 步顺序** 引导用户，不可跳步或合并：
-  1. **选择分类**（单选） → 2. **选择标签**（选填，可多选≤5，可跳过，无标签时自动跳过） → 3. **填写培训需求**（≤200字，必填） → 4. **紧急程度**（1-5，选填）
-- 分类：从 +list-categories 返回的 data.list[].title 中选择，**仅限单选**，不可同时选多个分类。
-- 标签：从所选分类的 data.list[].tag 字段中按逗号拆分，编号列出供用户选择。**标签为选填，用户可以选择标签也可以不选直接跳过**。可多选最多5个。若该分类 tag 为空或不存在，提示"📌 该分类暂无标签"，自动跳过标签步骤进入步骤3。
-- 培训需求描述：即 --title，**必填，最多 200 字符**，纯文本输入。
-- 紧急程度：即 --level，1=普通、2=较普通、3=一般、4=较紧急、5=最紧急，**选填**，不选时默认 0（不设置等级）。
-- 投票前，先执行 +list，使用返回的培训需求 uuid。不要把分类 uuid 传给投票接口。
-- 创建和投票是写操作。用户意图不明确时，先确认要提交或投票的对象。
-- 默认用 --format json 获取结构化输出。
+## 业务特例详则
 
-### 提交成功后的展示规则
-- **不显示需求 UUID**：提交成功后向用户展示的详情表格中，不要包含 uuid 字段。UUID 仅用于内部投票等操作，不向用户暴露。
-- **时间加8小时**：API 返回的 create_time 是 UTC 时间，向用户展示时必须加 8 小时转换为 UTC+8（北京时间）。例如返回 "2026-07-23 01:56:31" 应展示为 "2026-07-23 09:56:31"。
+- 分类和标签必须与后台返回值一致；创建和投票均为写操作，意图不明确时先确认。
+- 分类单选；需求描述对应 `--title`，必填且最多 200 字符；紧急程度对应 `--level`，范围 1–5，未选择默认为 0。
+- 标签规则详见上方“业务特例”和“执行守卫”，避免在多个章节重复维护。
 
 ### 标签处理规则
 
@@ -218,4 +239,4 @@ soke-cli training-demand +vote \
 - 创建失败提示分类无效：重新执行 +list-categories，不要自行手写分类 UUID。
 - 创建失败提示标签无效：重新执行 +list-categories，从所选分类返回的 tag 中选择，不要自行编写标签。**确保 --category-tag 传的是原始完整 tag 字段值**。
 - 投票失败提示需求无效：确认传入的是培训需求 UUID，不是分类 UUID。
-- 鉴权失败：按 soke-shared 执行 soke-cli auth login 后重试。
+- 鉴权失败：按 `../../shared/auth-check.md` 的认证失败流程处理后重试。

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

@@ -0,0 +1,50 @@
+# 共享能力索引
+
+本目录存放所有业务模块共同依赖的运行规则。共享层解决“如何安全、稳定地操作 soke-cli”，不定义课程、考试、AI 陪练等具体业务字段。
+
+## 规则归属
+
+规则唯一来源矩阵见 [`rule-ownership.md`](./rule-ownership.md)。修改共享规则或模块入口前，先按矩阵判断归属，避免同一规则出现多个权威版本。
+
+## 读取原则（按需，不强制全量）
+
+共享前置文档按需加载，启动时不要遍历读完。判断原则：
+
+| 文档 | 何时才读 |
+|---|---|
+| `installation.md` | 仅首次安装、重装或需要重新授权时 |
+| `environment-check.md` | `soke-cli --version` 探测失败、版本不符或报缺失依赖时 |
+| `auth-check.md` | `soke-cli config show` 显示未登录 / 未绑定企业 / 401 时 |
+| `cli-basics.md` | 需要确认 CLI 通用安全与输出原则时（`SKILL.md`「严格禁止」已覆盖核心） |
+| `command-discovery.md` | 真正执行某条命令前，按当前版本 `--help` 核对参数时 |
+| 对象 / 分页 / 交互 / 写验证 / 异步任务等 | 命中对应操作时再读 |
+
+就绪探测通过后，直接读目标模块的 `MODULE.md`，无需先遍历共享层。
+
+## 能力清单
+
+| 文件 | 负责内容 | 不负责内容 |
+|---|---|---|
+| `installation.md` | 安装、配置和首次认证 | 业务操作流程 |
+| `environment-check.md` | 运行环境和本地依赖 | 登录态判断 |
+| `auth-check.md` | 登录、Token、企业绑定 | 业务权限申请 |
+| `cli-basics.md` | CLI 通用安全、输出和错误原则 | 具体命令参数 |
+| `command-discovery.md` | 版本、`--help`、参数发现 | 业务字段定义 |
+| `object-context.md` | 真实 ID 提取、保存和传递 | 对象业务含义 |
+| `pagination.md` | 分页、全量查询和去重 | 特定接口字段 |
+| `interaction.md` | 选择、确认和分步交互 | 模块专属话术 |
+| `write-guard.md` | 写操作风险分级和确认 | 业务审批流程 |
+| `output-policy.md` | 摘要输出、脱敏和前后台边界 | 业务结果解释 |
+| `write-verify.md` | 写入结果判断、回读和幂等 | 特定对象状态字段 |
+| `async-task.md` | 任务 ID、轮询、超时和失败 | 具体导出参数 |
+| `file-input.md` | 路径、可读性、类型和大小检查 | 材料内容分析 |
+| `state-machine.md` | 通用状态、断点和恢复语义 | 模块业务状态定义 |
+| `error-handling.md` | 错误分类、重试顺序和升级 | 平台缺陷修复 |
+
+## 边界规则
+
+- 共享文档只描述跨模块重复出现的操作能力。
+- 模块文档只描述业务对象、字段、业务流程和特有约束。
+- 共享规则与模块规则冲突时，不得静默选择；先报告冲突，再以当前 CLI 帮助和明确的模块约束为准。
+- 共享文档中的示例 ID、路径和命令参数均为示例，不得当作真实业务数据执行。
+- 修改共享规则后，必须运行 `scripts/check_package.py` 和 `scripts/check_syntax.py`。

package/skills/mono/references/shared/async-task.md

@@ -0,0 +1,30 @@
+# soke-cli 异步任务
+
+本文件定义跨模块共用的异步任务与轮询规则。
+
+## 通用流程
+
+```text
+创建任务 → 保存 task ID → 轮询查询 → 判断完成态 → 提取文件或结果
+```
+
+## 统一规则
+
+- 创建任务后必须保存返回的任务 ID。
+- 查询状态时只使用该任务 ID，不猜测、不重建。
+- 轮询要有明确间隔和最大次数。
+- 完成、失败、超时要分开处理。
+- 任务未完成不能视为失败。
+- 任务完成后再提取文件地址、版本信息或统计结果。
+
+## 适用场景
+
+- 课程统计导出
+- 学习地图统计导出
+- 知识包编译/同步类异步动作
+- 文件处理类异步动作
+
+## 输出要求
+
+- 用户只看任务状态和结果地址。
+- 内部保留原始状态字段和时间戳。

package/skills/mono/references/shared/auth-check.md

@@ -0,0 +1,57 @@
+# soke-cli 登录与企业绑定验证
+
+本文件定义所有业务模块共用的账号就绪检查。它只处理 CLI 登录态、Token 和企业绑定，不处理具体业务对象。
+
+## 检测流程
+
+### 1. 检查登录态
+
+```bash
+soke-cli config show
+```
+
+只判断以下状态，不回显完整配置：
+
+- 用户凭证非空：登录态通过。
+- 用户凭证为空：需要执行 `soke-cli auth login`。
+- 返回 `401 Unauthorized`：先执行 `soke-cli auth logout`，再执行 `soke-cli auth login`。
+
+授权需要用户在浏览器中完成。浏览器未自动打开时，向用户提供终端输出的完整授权链接；不得截断、改写或回显 Token。
+
+### 2. 检查企业绑定
+
+再次执行：
+
+```bash
+soke-cli config show
+```
+
+- `corpid` 非空：企业绑定通过，可进入业务模块。
+- `corpid` 为空：提示账号已登录但未绑定企业；必要时引导用户执行 `soke-cli auth login --force`，仍为空则联系管理员。
+
+### 3. 切换账号或企业
+
+```bash
+soke-cli auth login --force
+```
+
+不要直接编辑配置文件修改企业或凭证。所有 ID、Token 和 Secret 都只用于内部判断，不在聊天中展示。
+
+## 统一状态
+
+模块只消费以下结果：
+
+```text
+READY              已登录且已绑定企业
+NOT_AUTHENTICATED  未登录或 Token 失效
+NO_CORP_BINDING    已登录但未绑定企业
+AUTH_PENDING       等待用户完成浏览器授权
+```
+
+`READY` 之外不得继续执行依赖平台账号的业务写操作。认证失败时报告原因和下一步，不要静默切换到未经确认的替代接口。
+
+## 共用前置顺序
+
+```text
+最小就绪探测（--version / config show）→ 读取业务模块 MODULE.md → 查询真实业务 ID → 执行业务流程
+```

package/skills/mono/references/shared/command-discovery.md

@@ -0,0 +1,34 @@
+# soke-cli 命令发现
+
+本文件定义所有业务模块共用的命令发现和版本兼容规则。它只解决“当前 CLI 怎么叫、参数怎么写”，不包含业务字段说明。
+
+## 命令发现顺序
+
+1. 先读父命令 `--help`。
+2. 再读叶子命令 `--help`。
+3. 如果有明确匹配用户意图的 `+verb` shortcut，优先用 shortcut。
+4. 文档示例仅用于理解，不可替代当前 `--help`。
+
+## 统一规则
+
+- 所有实际命令统一使用 `soke-cli` 前缀。
+- 不凭旧文档猜测参数名、flag 名或命令层级。
+- 文档和当前 CLI `--help` 不一致时，以当前 CLI 为准。
+- 写操作前如果支持 `--dry-run`，先用预览模式。
+- 不把列表响应、详情响应或 `--help` 输出误认为已完成业务操作。
+
+## 推荐检查模板
+
+```bash
+soke-cli --help
+soke-cli course --help
+soke-cli exam --help
+soke-cli task --help
+```
+
+## 使用场景
+
+- 新模块接入
+- 命令改名或参数升级
+- 旧文档迁移
+- 需要判断 shortcut 是否存在

package/skills/mono/references/shared/environment-check.md

@@ -0,0 +1,31 @@
+# soke-cli 环境检测
+
+本文件定义所有业务模块共用的本机环境检查。它只判断运行依赖，不处理登录和企业绑定。
+
+## 检测顺序
+
+1. Node.js：`node --version`，要求 >= 14.0.0。
+2. soke-cli：先 `which soke-cli`；若返回 `command not found`（常见于 WorkBuddy 沙箱 PATH 不含 `/usr/local/bin`），改用绝对路径探测 `/usr/local/bin/soke-cli --version`，仍失败再试 `~/.nvm/versions/node/*/bin/soke-cli --version`。**命令已安装但 PATH 未含其目录时，一律用绝对路径调用，不得误判为「未安装」**。真实安装位置参考：`/usr/local/bin/soke-cli`（软链 → `~/.nvm/versions/node/v22.22.1/bin/soke-cli` → `@sokeai/cli/scripts/run.js`）。
+3. Python 3：仅执行 Python 辅助脚本的模块需要，建议 >= 3.10。
+4. pdftotext：仅处理 PDF 材料的模块需要。
+5. 网络：需要调用平台时运行 `soke-cli doctor`；离线检查使用 `soke-cli doctor --offline`。
+
+任一必需依赖缺失时停止业务流程，先报告缺失项和修复方式；不要继续执行创建、更新、发布或同步。
+
+## 统一入口
+
+```bash
+python3 scripts/check_readiness.py --environment-only
+```
+
+如果当前版本脚本不支持该参数，则按上面的顺序逐项检查，并以 CLI `--help` 和 `doctor` 的实际结果为准。检测输出不得包含 Token、Secret 或完整配置。
+
+## 模块额外依赖
+
+| 依赖 | 适用模块 | 缺失时处理 |
+|---|---|---|
+| Python 3 | 使用校验脚本的模块 | 安装 Python 后重试 |
+| pdftotext | AI 陪练材料提炼 | 只阻断 PDF 提炼，不阻断纯文本流程 |
+| 浏览器 | OAuth 授权 | 提示用户手动打开授权链接 |
+
+环境检测通过后，再读取 `auth-check.md` 验证登录状态。

package/skills/mono/references/shared/error-handling.md

@@ -0,0 +1,27 @@
+# soke-cli 错误处理
+
+本文件定义跨模块共用的错误分类和修复顺序。
+
+## 错误分类
+
+- 认证错误：未登录、Token 失效、企业未绑定。
+- 权限错误：无权访问、无权写入、无权发布。
+- 参数错误：缺少必填项、类型错误、范围错误。
+- 业务冲突：重复创建、状态不允许、资源不存在。
+- 平台问题：接口异常、超时、网络失败。
+
+## 处理顺序
+
+1. 先确认是否是认证问题。
+2. 再确认是否是权限问题。
+3. 再检查参数和输入格式。
+4. 再判断是否是重复写入或状态冲突。
+5. 最后才考虑平台故障或重试。
+
+## 规则
+
+- 参数错误时先看当前命令 `--help`。
+- 认证失败时优先 `auth login` 或 `auth login --force`。
+- 权限不足时提示管理员开通，不要绕过权限。
+- 重试前先确认上一步是否已经成功。
+- 错误信息对用户要简洁，对内部要保留细节。

package/skills/mono/references/shared/file-input.md

@@ -0,0 +1,31 @@
+# soke-cli 文件输入校验
+
+本文件定义跨模块共用的本地文件输入规则。
+
+## 通用检查
+
+- 路径是否存在。
+- 文件是否可读。
+- 扩展名是否支持。
+- 文件大小是否合理。
+- 实际文件类型是否与扩展名一致。
+
+## 适用场景
+
+- 素材上传
+- 图片上传
+- PDF / Word / Excel / PPT 提炼
+- 知识包材料整理
+
+## 规则
+
+- 不要把目录当成文件上传。
+- 不要把不支持的扩展名误传给上传接口。
+- 先检查再上传，不要依赖接口报错兜底。
+- 大文件、无关文件和非目标文件应提前过滤。
+
+## 业务差异
+
+- 素材模块处理视频、音频、文档。
+- 图片库模块处理图片。
+- AI 陪练和知识包模块还需要做内容相关性筛选和提炼。

package/skills/mono/references/shared/interaction.md

@@ -0,0 +1,39 @@
+# soke-cli 交互与确认
+
+本文件定义跨模块共用的用户交互规则。
+
+## 交互类型
+
+### 1. 选择型
+
+用户需要从有限选项中选择分类、素材、题库、对象或模板时使用。
+
+规则：
+- 只展示业务名称，不展示内部 ID。
+- 用户选择后，立即保存真实 ID。
+- 若选项过多，分页展示并保留当前上下文。
+
+### 2. 确认型
+
+用户需要确认发布、删除、指派、绑定、更新等高风险动作时使用。
+
+规则：
+- 先展示目标、范围、影响和不可逆性。
+- 再等待明确确认。
+- 未确认前不执行写操作。
+
+### 3. 分步型
+
+像培训需求、AI 陪练这种固定步骤流程使用。
+
+规则：
+- 每一步单独输出。
+- 每一步都要等用户回复。
+- 不跳步，不合并。
+- 前一步未完成时，不进入下一步。
+
+## 输出要求
+
+- 文本尽量使用业务语言，不要输出内部字段名。
+- 需要固定选项时，优先使用结构化选择而不是让用户手打编号。
+- 需要继续时，保留当前上下文里的真实 ID 和已确认内容。

package/skills/mono/references/shared/object-context.md

@@ -0,0 +1,51 @@
+# soke-cli 对象上下文
+
+本文件定义跨模块共用的对象 ID 管理规则。它只解决“查询到什么、后续用什么”，不定义具体业务对象字段。
+
+## 核心原则
+
+- 查询、创建、上传或生成成功后，必须提取并保存真实 ID。
+- 后续操作只能使用真实 ID，不能用名称、序号、标题或猜测值代替。
+- 不要把不同对象类型的 ID 混用。
+
+## 对象类型示例
+
+- course-id
+- media uuid
+- lesson-id
+- department-id
+- user-id
+- exam-id
+- paper-id
+- map-id
+- task-id
+- certificate uuid
+- scenario-id
+- package version id
+
+## 上下文记录建议
+
+```json
+{
+  "type": "course",
+  "id": "真实ID",
+  "name": "对象名称",
+  "source": "soke-cli course +create",
+  "status": "draft"
+}
+```
+
+## 典型流程
+
+```text
+创建 / 查询 / 上传
+→ 提取真实 ID
+→ 保存上下文
+→ 执行依赖该 ID 的下一步
+```
+
+## 规则
+
+- 一次只处理一个对象上下文，避免混用。
+- 若前一步未成功，不得提前生成后续对象 ID。
+- 需要回读时，用当前对象真实 ID 再查一次，不要重新猜。

package/skills/mono/references/shared/output-policy.md

@@ -0,0 +1,39 @@
+# soke-cli 输出与脱敏
+
+本文件定义所有模块共用的输出边界。
+
+## 输出分层
+
+### 用户摘要
+
+给用户看的内容，只保留业务结论、状态和下一步。
+
+### 内部状态
+
+给 Agent 和脚本使用，保存真实 ID、返回码、分页游标和任务状态。
+
+### 失败诊断
+
+只在失败时保留，记录模块、命令、错误摘要和下一步修复建议。
+
+## 脱敏要求
+
+- 不输出 access_token、refresh_token、app_secret。
+- 不输出内部 UUID、部门用户 ID、任务 ID、场景 ID、知识包版本 ID 的完整集合，除非业务确实需要且用户已明确要求。
+- 不输出完整 JSON、回读快照或调试堆栈到前台。
+- 旧接口返回字段名中带有敏感含义时，前台只展示业务名称和状态。
+
+## 推荐输出形式
+
+```text
+✅ 已完成
+- 对象：课程名称
+- 状态：已发布
+- 下一步：可指派学员
+```
+
+## 规则
+
+- 前台简洁，后台完整。
+- 机器读数和人类摘要分开。
+- 没有必要时不要暴露技术字段。

package/skills/mono/references/shared/pagination.md

@@ -0,0 +1,41 @@
+# soke-cli 分页与去重
+
+本文件定义跨模块的列表分页、全量拉取和去重规则。
+
+## 通用流程
+
+1. 从第一页开始。
+2. 读取当前页的列表数据。
+3. 判断是否还有下一页或是否已到末页。
+4. 如果会跨页重复，按 `uuid` 或 `id` 去重。
+5. 最后再做用户展示或内部筛选。
+
+## 统一规则
+
+- 当前页不等于全量结果。
+- 用户看到的列表可以截断，内部检索需要按业务决定是否拉全。
+- 如果接口返回 `hasMore`、`total` 或类似字段，优先按接口字段判断分页结束。
+- 如果出现跨页重叠，必须去重后再继续处理。
+- 展示给用户时说明页码、页大小、筛选条件和结果数量。
+
+## 适用场景
+
+- 题库/试卷/考试列表
+- 学习地图列表
+- 学员档案列表
+- 图片库列表
+- 证书列表
+- 培训需求列表
+- 异步任务列表
+- 部门/用户列表
+
+## 典型模板
+
+```text
+page = 1
+→ 请求列表
+→ 合并 data.list
+→ 根据 hasMore/total 决定是否继续
+→ 以 uuid/id 去重
+→ 输出最终结果
+```

package/skills/mono/references/shared/rule-ownership.md

@@ -0,0 +1,57 @@
+# 共享规则唯一来源矩阵
+
+本文件是 Mono Skill 的规则归属契约。新增或修改规则前，先判断它属于共享层还是业务模块；同一条规则只能有一个权威来源。
+
+## 归属矩阵
+
+| 规则主题 | 唯一来源 | 模块可保留 | 模块不得重复维护 |
+|---|---|---|---|
+| 安装与配置 | `installation.md` | 模块额外依赖 | 完整安装步骤、配置字段说明 |
+| 运行环境 | `environment-check.md` | 模块额外二进制/文件依赖 | Node、CLI、网络等通用检查 |
+| 登录与企业绑定 | `auth-check.md` | 业务权限或平台特有权限提示 | `auth login`、`config show` 通用流程 |
+| CLI 安全与输出 | `cli-basics.md` | 业务命令示例 | 绕过 CLI、凭证泄露等总则 |
+| 命令和参数发现 | `command-discovery.md` | 当前模块叶子命令清单 | 版本兼容和 `--help` 总则 |
+| 真实 ID | `object-context.md` | 对象之间 ID 不可混用的业务语义 | “ID 必须来自返回值”的通则 |
+| 分页与去重 | `pagination.md` | 特定接口的字段和已知缺陷 | 通用分页、全量和去重流程 |
+| 选择与确认 | `interaction.md` | 严格业务步骤和专属提示词 | 通用选择/确认机制 |
+| 写入风险 | `write-guard.md` | 业务特有影响范围 | 风险分级和确认总则 |
+| 输出脱敏 | `output-policy.md` | 业务结果字段解释 | Token、UUID、完整响应的通用脱敏规则 |
+| 写后验证 | `write-verify.md` | 特定对象回读字段 | 通用成功判断、重试前检查 |
+| 异步任务 | `async-task.md` | 任务类型和业务结果字段 | 通用轮询、超时、任务状态语义 |
+| 文件输入 | `file-input.md` | 文件格式和业务内容要求 | 路径、可读性、大小等通用校验 |
+| 状态与恢复 | `state-machine.md` | 模块状态映射和步骤限制 | 通用状态转换和恢复原则 |
+| 错误处理 | `error-handling.md` | 模块特有错误码和修复动作 | 通用错误分类和重试顺序 |
+
+## 模块写作规则
+
+每个 `MODULE.md` 的共享前置只需要链接共享索引，并按需列出本模块实际使用的能力：
+
+```markdown
+## 共用前置
+
+开始前读取 `../../shared/README.md`，并按需加载环境检测、登录验证、命令发现和本模块需要的共享规则。本模块只保留业务特有规则。
+```
+
+模块中允许出现以下内容：
+
+- 某个对象的业务字段和状态含义；
+- 某类 UUID 与另一类 UUID 不能混用的具体原因；
+- 某个业务流程必须逐步执行的约束；
+- 某个接口独有的分页字段或平台缺陷；
+- 某个模块特有的确认范围和失败处理。
+
+模块中不应出现以下内容：
+
+- 独立的 `auth login` / `config show` 前置流程；
+- 再次解释所有模块都适用的 ID、分页、脱敏或重试规则；
+- 与共享层不同的通用风险等级；
+- 把共享规则复制后改写成另一套话术。
+
+## 修改流程
+
+1. 先搜索共享主题在全包中的现有表述。
+2. 判断是通用规则还是业务特例。
+3. 通用规则只修改对应共享文档。
+4. 业务特例只修改对应模块，并链接共享规则。
+5. 运行 `scripts/check_package.py` 和 `scripts/check_syntax.py`。
+6. 检查失败时先修复规则归属或引用，不要绕过检查。

package/skills/mono/references/shared/state-machine.md

@@ -0,0 +1,35 @@
+# soke-cli 状态机
+
+本文件定义跨模块共用的状态管理思路。
+
+## 通用状态
+
+```text
+pending → running → waiting_user → applied → verified → completed
+```
+
+失败分支：
+
+```text
+failed → retryable / blocked / manual_required
+```
+
+## 规则
+
+- 状态应能表达当前是否可继续。
+- 已完成步骤不应被重复执行，除非用户明确要求重做。
+- 等待用户时必须停止，不得自动跳步。
+- 已经确认的内容应在后续步骤中保留。
+- 恢复时优先从最近的稳定状态继续，而不是从头重来。
+
+## 适用场景
+
+- AI 陪练 Part 流程
+- 题库练习状态
+- 异步任务状态
+- 课程/场景发布流程
+
+## 输出建议
+
+- 前台只展示当前状态和下一步。
+- 后台保留完整状态载荷和时间戳。

package/skills/mono/references/shared/write-guard.md

@@ -0,0 +1,34 @@
+# soke-cli 高风险写操作守卫
+
+本文件定义发布、删除、指派、绑定、批量写入等高风险操作的共用规则。
+
+## 风险等级
+
+- L0：查询、列表、详情
+- L1：创建草稿、上传素材
+- L2：更新、绑定、批量写入、分配对象
+- L3：发布、删除、关闭、批量指派、平台同步
+
+## 通用要求
+
+- L2 及以上必须先展示目标、影响范围和对象。
+- L3 必须获得明确确认。
+- 删除和关闭类操作必须明确说明不可逆影响。
+- 批量操作必须说明数量、字段和失败处理方式。
+- 平台同步必须说明将要修改的场景、知识包或配置摘要。
+
+## 确认摘要模板
+
+```text
+操作：<动作>
+目标：<对象名称>
+范围：<影响范围>
+影响：<简要说明>
+是否确认？
+```
+
+## 规则
+
+- 未确认前不执行写操作。
+- 不把预览结果当作执行结果。
+- 重试前先确认上一步是否已经成功，避免重复写入。

package/skills/mono/references/shared/write-verify.md

@@ -0,0 +1,33 @@
+# soke-cli 写操作验证与幂等
+
+本文件定义写操作后的验证、重试和幂等处理。
+
+## 统一流程
+
+1. 执行写操作。
+2. 检查退出码和返回状态。
+3. 提取真实 ID 或任务 ID。
+4. 只在必要时进行回读验证。
+5. 保存状态，供下一步使用。
+
+## 幂等原则
+
+- 能使用 idempotency-key 的地方必须使用。
+- 重试前先判断上一次是否可能已经成功。
+- 不要因为没有看到完整输出就重复创建。
+- 异步任务必须保存 task ID 或等价标识。
+
+## 回读规则
+
+- 回读只验证本次写入的关键结果，不做无意义全量复核。
+- 回读结果如与写入结果不一致，优先判断是否存在平台延迟或最终一致性问题。
+- 不要用回读替代写操作。
+
+## 适用场景
+
+- 课程创建后查课程 ID
+- 素材上传后查 uuid
+- 课件创建后查 lesson-id
+- 任务创建后查 task-id
+- 场景同步后查版本 ID
+- 发布后查状态