@sokeai/cli 1.0.78 → 1.0.80

package/skills/mono/references/modules/soke-exam-question-pool/MODULE.md

@@ -11,11 +11,51 @@ metadata:
 
 # 可练习题库交互式练习系统
 
-核心链路全量分页选库随机逐题实时反馈
+通过全量分页拉取题库、随机逐题练习、实时判分和本地状态持久化，支持五种题型。本模块只负责可练习题库和答题会话，不负责考试创建、发布或成绩报表。
+
+## 共用前置
+
+开始前先读取 `../../shared/environment-check.md`、`../../shared/auth-check.md`、`../../shared/object-context.md`、`../../shared/pagination.md`、`../../shared/state-machine.md`、`../../shared/output-policy.md`、`../../shared/error-handling.md`。本模块只保留题库练习特有规则。
+
+## 职责
+
+负责可练习题库的选择、随机出题、实时判分和答题状态持久化；不负责考试创建、试卷发布或成绩报表。
+
+## 输入
+
+- 可练习题库列表及题目数据。
+- 用户选择的题库和题目答案。
+- 本地答题状态文件（可选）。
+
+## 流程
+
+全量分页拉取题库 → 用户选择题库 → 拉取题目并加载状态 → 随机出题与判分 → 保存状态并继续、结束或重新开始。
+
+## 业务特例
+
+- 跨页题库按 UUID 去重，题目数量以 `data.content` 实际返回为准。
+- 支持 `fill`、`determine`、`single_choice`、`choice`、`uncertain_choice` 五种题型及各自判分规则。
+- 已展示但未提交的题目不计入答题状态或本轮总结。
+- 状态文件按跨平台路径规则保存，不得写死 Windows/QClaw 路径。
+
+**失败降级**：拉题或判分时若接口返回异常/题目缺失，跳过该异常题并重新从剩余未答题池随机抽题，不要中断整轮；状态文件写入失败时，本轮仍可在内存中继续，但须明确提示用户“本次进度未能保存，退出后不保留”。已展示未提交的题不计作答、不计正确。
+
+## 输出
+
+- 展示干净的题目、判分反馈、进度和本轮小结，不向用户暴露内部 UUID 或接口字段。
+- 保留答题状态，供下次进入同一题库时恢复。
+
+**完成判定**：一轮练习“完成”当且仅当本轮所有已作答题目（uuid 已写入状态文件 `answered`）的判分与进度统计与状态文件一致，且状态文件已落盘（如可用）。仅界面显示进度、但状态文件未保存成功的，视为本轮状态未完成，应提示用户状态可能未持久化。
 
 ## 交互流程总览
 
-用户触发练习Step1全量分页拉取全部题库展示供选择Step2用户选择一个题库Step3拉取该题库全部题目加载答题状态Step4从未答题目中随机抽一道呈现判分Step5询问下一题结束重开循环Step4
+用户触发练习后，按以下顺序执行：
+
+1. 全量分页拉取题库并展示供选择。
+2. 用户选择一个题库。
+3. 拉取该题库全部题目并加载答题状态。
+4. 从未答题目中随机抽题、呈现并判分。
+5. 询问下一题、结束答题或重新开始；选择下一题时回到第 4 步。
 
 ## Step1全量分页拉取题库列表
 
@@ -47,9 +87,9 @@ soke-cli exam-question-pool +questions --pool-id UUID --format json
 
 ### 答题状态文件
 
-路径C:\Users\soke\.qclaw\workspace\.exam-state\{pool-uuid}.json
+状态文件使用跨平台本地路径：优先读取运行时 workspace 配置中的 `.exam-state/{pool-uuid}.json`；未提供 workspace 配置时，使用用户主目录下的 `.soke-cli/exam-state/{pool-uuid}.json`。不要写死 Windows、QClaw 或其他平台专用路径。首次使用时创建状态目录。
 
-格式pool_id uuid pool_title 题库名 total 5 correct 0 answered 空数组
+格式：`pool_id`（题库 UUID）、`pool_title`（题库名）、`total`（实际题目数）、`correct`（答对数）、`answered`（已提交题目的 UUID 数组）。
 
 文件不存在或pool_id不匹配新建answered为空数组
 答完一题追加uuid到answered正确则correct加1
@@ -118,6 +158,6 @@ questions获取题库全部题目
 
 data.content数量可能与all_count不一致过滤题以实际返回为准
 填空show_answer是string二维数组每空可能有多个可接受值
-状态文件路径C:\Users\soke\.qclaw\workspace\.exam-state\uuid.json先确保目录存在
+状态文件目录必须先确保存在；路径按上面的跨平台解析规则确定，不得写死 Windows 或 QClaw 路径
 每次出题前根据当前状态重新计算未答题池保证随机性
 填空题提示示例不能泄露正确答案统一用答案1答案2答案3占位

package/skills/mono/references/modules/soke-learning-map/MODULE.md

@@ -12,18 +12,59 @@ metadata:
 
 # 学习地图管理 (soke-learning-map)
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../../../references/installation.md`](../../../references/installation.md)，其中包含认证、配置、权限处理**
+## 共享前置
 
-## 使用前提
+开始前按需读取：
 
-1. 已安装 `soke-cli`
-2. 已登录授权：`soke-cli auth login`
+- `../../../shared/environment-check.md`
+- `../../../shared/auth-check.md`
+- `../../../shared/command-discovery.md`
+- `../../../shared/object-context.md`
+- `../../../shared/pagination.md`
+- `../../../shared/interaction.md`
+- `../../../shared/write-guard.md`
+- `../../../shared/write-verify.md`
+- `../../../shared/async-task.md`
+- `../../../shared/output-policy.md`
+- `../../../shared/error-handling.md`
 
-```bash
-soke-cli auth login
-soke-cli config show  # 验证登录状态
+本模块只保留学习地图业务规则；通用规则统一由共享层维护。
+
+## 职责
+
+负责学习地图的分类、创建、课程阶段、发布、指派衔接、详情和学习进度查询；不负责课程内容创建，也不负责统计导出任务的实现。
+
+## 输入
+
+- 地图标题、地图分类和阶段配置
+- 已发布且可加入地图的课程真实 ID
+- 用户明确的创建、发布、查询或指派动作
+- 需要跨模块衔接时的真实地图、课程、阶段和用户/部门 ID
+
+## 流程
+
+```text
+查询地图分类 → 创建学习地图 → 查询课程分类与课程
+→ 检查课程可用性 → 创建阶段 → 发布地图
+→ 可选指派 → 查询详情/进度 → 可选创建统计任务
 ```
 
+指派调用 `../soke-assign/MODULE.md`，统计导出调用 `../soke-task/MODULE.md`。
+
+## 业务特例
+
+- 地图分类 UUID、课程分类 UUID、地图 UUID、阶段 UUID 和课程 UUID 不可混用。
+- 创建阶段只能传入课程可用性检查返回的 `availabelIds`。
+- 发布前至少需要一个有效阶段；统计导出属于独立异步任务流程。
+
+**失败降级**：发布若报“无阶段/阶段无内容”，先确认已用 `+create-stage` 创建至少一个含课程且 `availabelIds` 内的阶段，再用 `+detail` 回读 `status`；创建阶段若传入了 `check-item-status` 未返回的 UUID，按接口错误停下并改正，不要继续发布。跨模块指派失败以 `assign` 模块的真实返回为准。
+
+## 输出
+
+返回地图、阶段、发布状态和学习进度的业务摘要；跨模块只传递 CLI 返回的真实 ID，输出边界遵循 `../../../shared/output-policy.md`。
+
+**完成判定**：创建地图完成当且仅当返回 `map-uuid`；创建阶段完成当且仅当返回 `stage-uuid`；发布完成当且仅当 `+detail`（或 `+list-maps`）查到 `status=1`；指派完成当且仅当 `assign +list` 能查到记录。仅 CLI 回显“发布成功”但 `+detail` 仍 `status=0` 的，视为未发布。
+
 ---
 
 ## 端到端创建工作流
@@ -408,11 +449,10 @@ soke-cli learning-map +detail --uuid "MAP-UUID" --format json
 
 ### 调试检查清单
 
-```bash
-# 1. 认证状态
-soke-cli config show
+认证状态按 `../../../shared/auth-check.md` 检查。其余检查仅验证学习地图对象和阶段数据：
 
-# 2. 确认地图存在
+```bash
+# 1. 确认地图存在
 soke-cli learning-map +list-maps \
   --start-time 1700000000000 --end-time 1800000000000 --format json | \
   jq '.data.list[] | select(.uuid=="MAP-UUID")'

package/skills/mono/references/modules/soke-learning-profile/MODULE.md

@@ -9,7 +9,50 @@ metadata:
   cliHelp: "soke-cli learning-profile --help"
 ---
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/MODULE.md`](../soke-shared/MODULE.md)，其中包含认证、配置、权限处理**
+## 共享前置
+
+开始前按需读取：
+
+- `../../shared/environment-check.md`
+- `../../shared/auth-check.md`
+- `../../shared/command-discovery.md`
+- `../../shared/object-context.md`
+- `../../shared/pagination.md`
+- `../../shared/output-policy.md`
+- `../../shared/error-handling.md`
+
+本模块只保留学习档案业务规则；通用规则统一由共享层维护。
+
+## 职责
+
+负责查询学员的课程学习、考试成绩、证书、学分积分和培训等综合档案；不负责修改课程、考试或证书资源。
+
+## 输入
+
+- 学员或部门的真实 ID
+- 新员工筛选条件和分页条件
+- 用户明确的档案查询、明细查询或统计动作
+
+## 流程
+
+```text
+确认学员/部门范围 → 查询学习档案 → 按需分页拉取
+→ 汇总课程、考试、证书和积分字段 → 输出业务摘要
+```
+
+## 业务特例
+
+- 学员使用 `dept_user_id`，部门使用 `dept_id`，两类 ID 不可混用。
+- 学习时长需格式化为用户可读的小时和分钟。
+- 完整 JSON 只用于内部解析，前台只展示与查询目标相关的字段。
+
+**失败降级**：若查询返回错误或为空，先核对 `dept_user_ids`/`dept_ids` 是否来自 `contact` 模块真实返回（学习档案不支持按姓名直查），不要猜测 ID；姓名查询须先经 `contact +search-user` 获取 `dept_user_id` 再查，缺失该前置时停下来说明，不要跳过或用占位 ID。
+
+## 输出
+
+返回姓名、部门、课程完成、考试通过、证书、学习时长、学分和积分等业务摘要；输出边界遵循 `../../shared/output-policy.md`。
+
+**完成判定**：查询“完成”当且仅当返回数据覆盖所请求的学员/部门范围，且 `dept_user_id`/`dept_id` 与请求一致、关键字段（必修/选修完成、考试通过、证书数、学分/积分）已正确聚合；结果为空时如实报告“无学习记录”，不得臆造数据。
 
 ## 核心概念
 
@@ -125,7 +168,7 @@ soke-cli learning-profile +list --dept-ids dept456,dept789
 # 查询新员工的学习档案
 soke-cli learning-profile +list --is-new 1 --page-size 50
 
-# 分页查询（使用 offset）
+# 模块查询示例（分页参数）
 soke-cli learning-profile +list --offset 0 --page-size 10   # 第1页
 soke-cli learning-profile +list --offset 10 --page-size 10  # 第2页
 soke-cli learning-profile +list --offset 20 --page-size 10  # 第3页
@@ -196,7 +239,7 @@ soke-cli learning-profile +list --page-size 100 --format json > learning_profile
 ## 注意事项
 
 1. **时间格式**: `learn_time`, `class_length` 等时长字段单位为秒，表格输出时会自动格式化为"X小时Y分钟"
-2. **分页**: 使用 `offset` 和 `page_size` 进行分页，默认每页10条，最大100条
+2. 该接口的分页参数为 `offset` 和 `page_size`，默认每页10条、最大100条；全量查询和去重规则以 `../../shared/pagination.md` 为准。
 3. **数组参数**: `dept_user_ids` 和 `dept_ids` 是数组类型，多个ID用逗号分隔
 4. **姓名查询**: 学习档案接口不支持按姓名查询，需要先通过 `contact +search-user` 获取 dept_user_id
 5. **权限**: 需要 `learningProfile:readonly` 权限，如遇权限错误参考 soke-shared

package/skills/mono/references/modules/soke-lesson/MODULE.md

@@ -7,9 +7,27 @@ tags: [soke, lesson, courseware, chapter, video, audio, document]
 
 # 课件管理
 
-## 触发描述
+## 共享前置
 
-用户已有课程（course）且完成素材上传后，需要将素材添加为课程的章节课件时触发本技能。支持创建课件、列表查询、详情查询和排序，仅支持 `video | audio | document` 三种类型的课件。
+开始前按需读取：
+
+- `../../shared/environment-check.md`
+- `../../shared/auth-check.md`
+- `../../shared/object-context.md`
+- `../../shared/write-verify.md`
+- `../../shared/output-policy.md`
+
+本模块只保留课件业务规则；通用认证、对象 ID、写后验证和输出脱敏不在此重复定义。
+
+## 职责
+
+本模块负责将已上传素材创建为课程课件，并提供课件查询、详情和排序；不负责素材上传或课程发布。
+
+## 输入
+
+- 已存在的目标课程真实 ID
+- `soke-material` 返回的完整素材对象
+- 课件标题和可选学习时长
 
 ## 输入要求
 
@@ -31,12 +49,12 @@ tags: [soke, lesson, courseware, chapter, video, audio, document]
 
 > ⚠️ `uuid` `filename` `type` `ext` `filesize` `object` 六个字段必须严格从素材上传返回结果中取值，不可自行构造或编造。
 
-## 执行流程
+## 流程
 
 ### 1. 创建课件 `course +lesson-create`
 
 ```bash
-soke course +lesson-create \
+soke-cli course +lesson-create \
   --course-id <courseId> \
   --title "<课件标题>" \
   --type <video|audio|document> \
@@ -65,7 +83,7 @@ soke course +lesson-create \
 ### 2. 课件列表 `course +lesson-list`
 
 ```bash
-soke course +lesson-list --course-id <courseId>
+soke-cli course +lesson-list --course-id <courseId>
 ```
 
 返回指定课程下所有课件的列表，包含课件 ID、标题、类型、排序序号。
@@ -73,7 +91,7 @@ soke course +lesson-list --course-id <courseId>
 ### 3. 课件详情 `course +lesson-get`
 
 ```bash
-soke course +lesson-get --lesson-id <lessonId>
+soke-cli course +lesson-get --lesson-id <lessonId>
 ```
 
 返回单个课件的完整信息（标题、类型、素材引用、时长、转码状态等）。
@@ -81,25 +99,19 @@ soke course +lesson-get --lesson-id <lessonId>
 ### 4. 课件排序 `course +lesson-sort`
 
 ```bash
-soke course +lesson-sort --course-id <courseId> --order "<lessonId1>,<lessonId2>,<lessonId3>"
+soke-cli course +lesson-sort --course-id <courseId> --order "<lessonId1>,<lessonId2>,<lessonId3>"
 ```
 
 调整课程内课件的展示顺序，`--order` 为逗号分隔的课件 ID 列表，按先后顺序排列。
 
-## 输出标准
+## 输出
 
-创建课件成功后输出摘要：
+- 创建课件成功后输出课程、课件标题、类型、时长和处理状态等业务摘要。
+- 课件 ID 只在后续排序或查询确实需要时传递。
+- 排序完成后输出更新后的课件列表。
+- 输出边界遵循 `../../shared/output-policy.md`。
 
-```
-✅ 课件创建成功
-- 课程: {courseTitle} (ID: {courseId})
-- 课件: {title}
-- 类型: {type}
-- 时长: {duration}s
-- 课件 ID: {lessonId}
-```
-
-排序完成后输出更新后的课件列表。
+**完成判定**：课件创建完成当且仅当 `course +lesson-list` 能查到该课件（标题、类型与素材 `uuid` 对应）；排序完成当且仅当 `course +lesson-list` 返回顺序与请求的 `--order` 一致。仅 `+lesson-create` 回显成功、但 `+lesson-list` 查不到的，视为未完成。
 
 ## 注意事项
 
@@ -109,6 +121,8 @@ soke course +lesson-sort --course-id <courseId> --order "<lessonId1>,<lessonId2>
 4. 排序使用课件 ID 列表，未在列表中的课件保持在末尾，不丢失
 5. 课件删除、批量导入等操作不在 CLI 范围，如有需求引导至后台操作
 
+**失败降级**：若 `+lesson-create` 报素材 `uuid`/`object` 无效或类型非 video/audio/document，立即停下并说明原因，不得用占位或编造的素材字段继续；创建后务必用 `course +lesson-list` 回读确认课件已存在，查不到则视为未创建成功。
+
 ## 检查清单
 
 - [ ] 素材已完成上传，持有完整返回对象
@@ -116,4 +130,4 @@ soke course +lesson-sort --course-id <courseId> --order "<lessonId1>,<lessonId2>
 - [ ] type 仅限 video / audio / document
 - [ ] uuid / filename / type / ext / filesize / object 六个字段均来自上传返回
 - [ ] duration 已按类型默认规则或用户指定设定
-- [ ] 课件创建完成后能通过 lesson-list 验证
+- [ ] 课件创建完成后通过 course +lesson-list 回读验证（查不到＝未完成）

package/skills/mono/references/modules/soke-material/MODULE.md

@@ -7,15 +7,29 @@ tags: [soke, material, upload, video, audio, document]
 
 # 素材库管理
 
-## 触发描述
+## 共享前置
 
-用户需要上传课程素材（视频、音频、文档）到素材库，或从已有素材库中选择素材时触发本技能。
+开始前按需读取：
 
-本技能支持两条路径：
-- **本地上传**：上传本地文件到素材库，返回标准资产信息
-- **素材库选择**：从已有素材库中搜索、浏览、选择已上传的素材
+- `../../shared/environment-check.md`
+- `../../shared/auth-check.md`
+- `../../shared/file-input.md`
+- `../../shared/object-context.md`
+- `../../shared/write-verify.md`
+- `../../shared/output-policy.md`
 
-## 输入要求
+本模块只保留素材业务规则；通用认证、文件校验、对象 ID、写后验证和输出脱敏不在此重复定义。
+
+## 职责
+
+本模块负责视频、音频和文档素材的上传、查询与选择，不负责课程章节创建或课程发布。
+
+## 输入
+
+- 本地上传：绝对文件路径。
+- 素材库选择：用户明确选择的素材。
+
+### 输入要求
 
 **本地上传：**
 - **文件路径**：本地文件的绝对路径
@@ -31,7 +45,7 @@ tags: [soke, material, upload, video, audio, document]
 - 由调度方（soke-course）通过弹窗选定素材
 - 素材库中的文件已是上传态，直接返回复用即可
 
-## 执行流程
+## 流程
 
 ### 第一步：确认文件有效性
 
@@ -44,7 +58,7 @@ tags: [soke, material, upload, video, audio, document]
 使用 CLI 命令上传素材：
 
 ```bash
-soke file +upload --path "/absolute/path/to/file"
+soke-cli file +upload --path "/absolute/path/to/file"
 ```
 
 ### 第三步：解析返回结果
@@ -74,19 +88,19 @@ soke file +upload --path "/absolute/path/to/file"
 
 > 视频和音频实际时长以文件元数据为准；文档类不计时可设 0。
 
-## 输出标准
+## 业务特例
 
-完成上传后向用户输出摘要：
+- 仅支持视频、音频和文档，不支持图片作为课程素材。
+- 上传结果中的 `uuid`、`object` 等字段是后续课件创建的真实输入，不得手动构造。
+- 视频、音频和文档的默认时长规则以本模块为准。
 
-```
-✅ 素材上传成功
-- 文件名: {filename}
-- 类型: {type}
-- 大小: {filesize} bytes
-- UUID: {uuid}
-```
+**失败降级**：上传若报格式不支持、文件不存在或存储失败，立即停止并说明原因，不进入课件创建；返回对象缺 `uuid`/`object` 时视为不可用，提示用户重试上传，不得凭记忆或占位值向下游（soke-lesson）传递。
+
+## 输出
+
+完成上传或选择后，返回标准素材对象供后续课件流程使用；用户侧摘要遵循共享输出脱敏规则。
 
-可将完整返回对象缓存在上下文中，供后续 `soke-lesson` 创建课件时直接引用。
+**完成判定**：上传“完成”当且仅当返回对象同时包含 `uuid`、`filename`、`type`、`ext`、`filesize`、`object` 六个字段且 `uuid` 非空。缺字段（尤其是 `uuid`/`object`）即视为上传未成功，不得把“已调用命令”当作“素材可用”，也不得手动补齐缺失字段。
 
 ## 注意事项
 
@@ -102,4 +116,4 @@ soke file +upload --path "/absolute/path/to/file"
 - [ ] 扩展名在 `.mp4|.avi|.mov|.mp3|.wav|.pdf|.ppt|.pptx|.doc|.docx` 中
 - [ ] 上传完成，获取到完整返回对象（uuid / filename / type / ext / filesize / object）
 - [ ] 默认时长按类型正确设定
-- [ ] 返回数据完整传递给后续课件创建流程
+- [ ] 返回对象含完整 uuid/object 等六字段，完整传递给后续课件创建流程（缺 uuid＝未完成）

package/skills/mono/references/modules/soke-photo-gallery/MODULE.md

@@ -11,17 +11,38 @@ metadata:
 
 # 图片库管理 (soke-photo-gallery)
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/MODULE.md`](../soke-shared/MODULE.md)，其中包含认证、配置、权限处理**
+## 共用前置
 
-## 使用前提
+开始前读取 `../../shared/README.md`，并按需加载其中的环境检测、登录验证、文件输入、对象上下文、分页、写后验证和错误处理规则。本模块只保留图片库特有规则。
 
-1. 已安装 `soke-cli`
-2. 已登录授权: `soke-cli auth login`
+## 职责
 
-```bash
-soke-cli auth login
-soke-cli config show  # 验证登录状态
-```
+负责图片分类查询、图片上传、图片列表与详情查询及批量删除；不负责课程素材上传、课件创建或 AI 场景封面流程。
+
+## 输入
+
+- 本地图片文件路径、图片标题和可选分类 ID。
+- 通过 CLI 查询获得的分类 ID、图片 UUID。
+- 用户明确的删除目标和操作确认。
+
+## 流程
+
+查询分类（可选） → 上传图片（本地文件到 OSS，再创建图片库记录） → 查询列表验证 → 查询详情获取 URL → 按需批量删除。
+
+## 业务特例
+
+- 仅支持 jpg、jpeg、png，单张最大 5 MB。
+- 上传是 OSS 上传和图片库登记两步操作，两步都成功才算完成。
+- 删除不可恢复，图片 UUID 必须来自 CLI 返回结果并经过用户确认。
+
+**失败降级**：上传是 OSS 与图片库登记两步，若 OSS 成功但登记失败，图片不会出现在 `+list`，视为未完成——应回读 `+list`/`+get` 确认 `uuid` 存在后再向用户报成功；删除前必须基于 `+list` 拿到的真实 `uuid` 并经用户确认，删除后仍用 `+list` 回读确认已消失。
+
+## 输出
+
+- 返回图片上传、列表、详情或删除的业务摘要。
+- 图片 URL 仅在用户需要访问地址时展示；内部响应和敏感信息遵循共享输出规则。
+
+**完成判定**：上传完成当且仅当 `+list`（或 `+get`）能查到该图片且返回 `uuid` 与非空 `photoUri`；删除完成当且仅当 `+list` 中对应 `uuid` 不再出现。两步上传（OSS+登记）任一步失败、或 `+list` 查不到新图片的，视为未完成。
 
 ## 核心概念
 
@@ -36,8 +57,8 @@ soke-cli config show  # 验证登录状态
 │ 1. (可选) 查询分类  →  获取 category-id                      │
 │ 2. 上传图片        →  本地文件 → OSS → 图片库记录             │
 │ 3. 查询图片列表    →  验证上传结果                            │
-│ 3.1 查询图片详情   →  获取单张图片完整 URL                     │
-│ 4. (可选) 批量删除 →  清理图片                                │
+│ 4. 查询图片详情    →  获取单张图片完整 URL                     │
+│ 5. (可选) 批量删除  →  清理图片                                │
 └──────────────────────────────────────────────────────────────┘
 ```
 
@@ -120,7 +141,7 @@ soke-cli photo-gallery +list --category-id "CATEGORY-UUID"
 # 按文件名关键词搜索
 soke-cli photo-gallery +list --file-keyword "banner"
 
-# 分页
+# 图片列表分页参数
 soke-cli photo-gallery +list --page 1 --limit 20
 
 # JSON 输出
@@ -145,7 +166,7 @@ soke-cli photo-gallery +list --format json
 
 ---
 
-## 步骤3.1: 获取图片详情
+## 步骤4: 获取图片详情
 
 ```bash
 # 获取单张图片详情（含完整访问 URL）
@@ -167,7 +188,7 @@ soke-cli photo-gallery +get --uuid "IMAGE-UUID" --format json
 
 ---
 
-## 步骤4: 批量删除图片（可选）
+## 步骤5: 批量删除图片（可选）
 
 ```bash
 # 删除单张图片
@@ -217,7 +238,7 @@ echo "图片UUID: $IMAGE_UUID"
 # === 3. 验证上传结果 ===
 soke-cli photo-gallery +list --file-keyword "logo" --format json
 
-# === 3.1 获取图片详情和访问 URL ===
+# === 4. 获取图片详情和访问 URL ===
 soke-cli photo-gallery +get --uuid "$IMAGE_UUID" --format json
 
 # === 4. 批量上传 ===
@@ -228,7 +249,7 @@ for img in banner.jpg logo.png icon.png; do
     --category-id "CATEGORY-UUID"
 done
 
-# === 5. 清理不需要的图片 ===
+# === 6. 清理不需要的图片 ===
 soke-cli photo-gallery +batch-delete --uuids "$IMAGE_UUID"
 ```
 
@@ -260,11 +281,10 @@ soke-cli photo-gallery +batch-delete --uuids "$IMAGE_UUID"
 
 ### 调试检查清单
 
-```bash
-# 1. 确认登录状态
-soke-cli config show
+登录状态按 `../../shared/auth-check.md` 检查。以下命令仅用于确认图片库记录：
 
-# 2. 查询图片列表确认上传成功
+```bash
+# 1. 查询图片列表确认上传成功
 soke-cli photo-gallery +list --format json | jq '.data.list[0]'
 
 # 3. 始终使用 --format json 获取结构化输出
@@ -283,4 +303,4 @@ soke-cli photo-gallery +list --format json
 
 ## 相关文档
 
-- [`../soke-shared/MODULE.md`](../soke-shared/MODULE.md) — 认证、配置、权限
+- [`../../shared/README.md`](../../shared/README.md) — 认证、配置、权限等共享规则

package/skills/mono/references/modules/soke-shared/MODULE.md

@@ -7,6 +7,15 @@ description: "授客CLI共享基础：应用配置初始化、认证登录（aut
 
 # soke-cli 共享规则
 
+本目录的共享能力已统一归档到 Mono 包的 `../../shared/`。本兼容入口仅保留历史说明，不新增业务规则。
+
+开始操作前读取：
+
+- `../../shared/README.md`
+- `../../shared/environment-check.md`
+- `../../shared/auth-check.md`
+- `../../shared/cli-basics.md`
+
 本技能指导你如何通过soke-cli操作授客AI资源，以及有哪些注意事项。
 
 ## 配置初始化

package/skills/mono/references/modules/soke-supervisor/MODULE.md

@@ -11,7 +11,38 @@ metadata:
 
 # AI 督导模块 (supervisor)
 
-**CRITICAL — 开始前 MUST 先读取 [`../soke-shared/MODULE.md`](../soke-shared/MODULE.md)，其中包含认证、配置、权限处理。**
+## 共用前置
+
+开始前先读取 `../../shared/README.md`，并按需加载其中的环境检测、登录验证、对象上下文、分页、交互、写入守卫、写后验证和错误处理规则。本模块只保留督导业务特有规则。
+
+## 职责
+
+负责 AI 督导场景的创建、评分标准配置、用户或部门指派、发布、详情查询及关闭前资源检查；不负责 AI 陪练、知识包同步或普通课程发布。
+
+## 输入
+
+- 督导场景名称、描述、关键检查点和状态。
+- 通过 CLI 查询获得的场景 ID、评分模板 ID、部门 ID 和用户 ID。
+- 用户明确的指派、发布或关闭意图。
+
+## 流程
+
+推荐顺序为：创建草稿 → 查询评分模板 → 更新评分配置 → 指派前查重 → 查询部门/成员 → 指派 → 发布并回读；关闭前必须先执行资源检查。
+
+## 业务特例
+
+- `template_id` 和 `dimensions[]` 必须来自评分标准模板查询结果。
+- 关闭前仅当 `data.can_operate=true` 时允许关闭；否则根据阻塞信息处理关联资源。
+- `corp_id` 仅在当前 CLI `--help` 明确要求且通过配置或查询获得时传入，不得编造。
+
+**失败降级**：发布/指派/关闭等写操作若返回业务错误或回读状态不符，立即停止并说明原因，不要假设成功；关闭被 `+check-resource` 判定 `can_operate=false` 时，绝不强行关闭，应先处理 `block_message`/`bind_maps` 中的阻塞资源；`template_id`/`dimensions` 必须来自评分标准查询，缺失时停下重新查询，不得编造。
+
+## 输出
+
+- 返回场景、评分配置、指派、发布或关闭检查的业务摘要。
+- 发布后回读 `status`、`status_text` 和评分配置；不回显敏感凭证或无关原始响应。
+
+**完成判定**：创建草稿完成当且仅当返回 `data.id`；指派完成当且仅当 `+list-assigns` 能查到对应 `target_id`/`assign_type`；发布完成当且仅当 `+get-scenario` 回读到预期 `status` 与 `scoring_criteria_config`；关闭完成当且仅当 `+check-resource` 先返回 `can_operate=true` 且 `+close-scenario` 成功。仅凭“执行成功”提示但回读状态不符的，视为未完成。
 
 ## 核心概念
 

package/skills/mono/references/modules/soke-task/MODULE.md

@@ -11,7 +11,54 @@ metadata:
 
 # 异步任务管理 (soke-task)
 
-**CRITICAL — 开始前 MUST 先读取 [`../soke-shared/MODULE.md`](../soke-shared/MODULE.md)，其中包含认证、配置和权限处理。**
+## 共享前置
+
+开始前按需读取：
+
+- `../../shared/environment-check.md`
+- `../../shared/auth-check.md`
+- `../../shared/command-discovery.md`
+- `../../shared/object-context.md`
+- `../../shared/pagination.md`
+- `../../shared/async-task.md`
+- `../../shared/write-verify.md`
+- `../../shared/output-policy.md`
+- `../../shared/error-handling.md`
+
+本模块只保留异步统计任务的业务规则；通用任务状态、轮询、对象 ID 和输出规范统一由共享层维护。
+
+## 职责
+
+负责学习地图和课程学员统计任务的创建、状态查询和导出文件获取；不负责普通列表查询或课程/地图业务对象创建。
+
+## 输入
+
+- 统计任务类型和目标资源真实 ID
+- `learningMapUser` 或 `courseUser` 模块类型
+- 部门、用户、学习状态和自定义字段筛选条件
+- 用户明确的导出或统计生成动作
+
+## 流程
+
+```text
+确认目标资源 → 创建统计任务 → 保存 task ID
+→ 按 action 判断状态字段 → 轮询任务
+→ 获取报表地址或统计结果
+```
+
+## 业务特例
+
+- `learningMapUser` 的 `target-id` 是学习地图 ID，`courseUser` 的 `target-id` 是课程 ID。
+- `action=export` 查看 `data.export_status`，`action=report` 查看 `data.status`。
+- 导出文件只有在任务完成且 `filePath` 非空时才可返回。
+
+**失败降级**：创建若返回空 `data.id`，视为任务未创建，停下重试；导出查询若 `filePath` 为空，说明任务仍在进行或失败，应轮询 `task +get` 而非断言已导出；`--target-id` 与 `--module` 不匹配（地图用 `learningMapUser`、课程用 `courseUser`）会导致失败，应先确认目标资源类型再提交。
+
+## 输出
+
+返回任务状态、统计结果或导出文件名与地址等业务摘要；任务 ID 和完整响应按需保留，输出边界遵循 `../../shared/output-policy.md`。
+
+**完成判定**：任务创建完成当且仅当返回 `data.id`；`action=export` 导出完成当且仅当 `task +get` 查到 `data.export_status` 为完成态且 `data.filePath` 非空；`action=report` 统计完成当且仅当 `data.status` 为完成态。仅创建返回 ID、但后续 `+get` 始终 `filePath` 为空或状态未完成的，视为任务未产出结果，应继续轮询或报告未完成。
 
 ## 核心规则