@sokeai/cli 1.0.77 → 1.0.79

package/skills/mono/references/shared/cli-basics.md

@@ -0,0 +1,185 @@
+---
+name: soke-shared
+summary: 授客CLI共享基础（配置/登录/权限/错误处理/安全规则）
+version: 1.0.0
+description: "授客CLI共享基础：应用配置初始化、认证登录（auth login）、权限管理、错误处理、安全规则。当用户需要第一次配置（soke-cli auth login）、使用登录授权（soke-cli auth login）、遇到权限不足、或首次使用soke-cli时触发。"
+---
+
+# soke-cli 共享规则
+
+本技能指导你如何通过soke-cli操作授客AI资源，以及有哪些注意事项。
+
+## 配置初始化
+
+首次使用需运行 `soke-cli auth login` 完成应用配置。
+
+当你帮用户初始化配置时，引导用户按照交互式提示完成配置：
+
+```bash
+# 初始化配置
+soke-cli auth login
+```
+
+配置项包括：
+- `app_id`: 开放平台应用ID
+- `app_key`: 开放平台应用Key
+- `app_secret`: 开放平台应用Secret
+- `api_base_url`: API地址（默认: https://opendev.soke.cn）
+- `corpid`: 企业ID
+
+配置文件保存在 `~/.soke-cli/config.json`
+
+## 认证
+
+### 用户登录
+
+用户需要通过OAuth授权获取访问令牌：
+
+```bash
+# 用户登录授权
+soke-cli auth login
+```
+
+登录成功后，`access_token` 和 `refresh_token` 会自动保存到配置文件中。
+
+### Token管理
+
+- **access_token**: 用户访问令牌，用于调用API
+- **refresh_token**: 刷新令牌，用于获取新的access_token
+- Token过期后需要重新执行 `soke-cli auth login`
+
+### 查看当前配置
+
+```bash
+# 查看当前配置（不显示敏感信息）
+soke-cli config show
+```
+
+## 权限不足处理
+
+遇到权限相关错误时，通常有以下几种情况：
+
+### 1. 未登录或Token过期
+
+**错误特征**: 返回401 Unauthorized或Token无效
+
+**解决方案**:
+```bash
+soke-cli auth login
+```
+
+### 2. 缺少必要权限
+
+**错误特征**: 返回403 Forbidden或权限不足提示
+
+**解决方案**:
+- 联系管理员在开放平台后台为应用开通相应权限
+- 确认企业ID（corpid）和应用配置正确
+
+### 3. 参数错误
+
+**错误特征**: 返回400 Bad Request或参数验证失败
+
+**解决方案**:
+- 检查必需参数是否提供
+- 使用 `--help` 查看命令参数说明
+- 参考API文档确认参数格式
+
+## 命令结构
+
+### Shortcuts（推荐）
+
+Shortcuts是对常用操作的高级封装，参数友好，最适合AI Agent调用：
+
+```bash
+soke-cli <service> +<verb> [flags]
+```
+
+示例：
+```bash
+soke-cli exam +get-exam-user --exam-id exam123 --dept-user-id user456
+soke-cli course +list-courses --page 1 --page-size 10
+```
+
+### 通用API调用
+
+支持直接调用任意API：
+
+```bash
+soke-cli api <METHOD> <path> [--data <json>] [--params <json>]
+```
+
+示例：
+```bash
+soke-cli api GET /users/me
+soke-cli api POST /some/endpoint --data '{"key": "value"}'
+```
+
+## 输出格式
+
+### JSON格式（默认）
+
+所有命令默认输出JSON格式，便于程序解析：
+
+```bash
+soke-cli exam +list-exams --format json
+```
+
+### 表格格式
+
+部分命令支持表格格式输出，更易读：
+
+```bash
+soke-cli exam +list-exams --format table
+```
+
+## 安全规则
+
+- **禁止输出密钥**（app_secret、access_token）到终端明文
+- **写入/删除操作前必须确认用户意图**
+- 敏感操作建议先使用 `--dry-run`（如果支持）预览
+
+## 错误处理
+
+当命令执行失败时：
+
+1. **检查配置**: 运行 `soke-cli config show` 确认配置正确
+2. **检查登录状态**: 如果是认证错误，运行 `soke-cli auth login`
+3. **检查参数**: 使用 `soke-cli <service> <command> --help` 查看参数说明
+4. **查看错误信息**: 错误响应中通常包含详细的错误原因
+
+## 常见问题
+
+### Q: 如何获取app_key和app_secret？
+
+A: 登录授客AI开放平台（https://opendev.soke.cn），创建应用后即可获取。
+
+### Q: Token过期了怎么办？
+
+A: 重新执行 `soke-cli auth login` 进行授权。
+
+### Q: 如何切换企业？
+
+A: 运行 `soke-cli auth login` 重新配置，或直接编辑 `~/.soke-cli/config.json` 文件。
+
+### Q: 支持哪些业务模块？
+
+A: 目前支持以下模块：
+- `contact`: 组织架构（部门、用户、岗位、讲师）
+- `course`: 课程管理
+- `exam`: 考试管理
+- `training`: 培训管理
+- `learning_map`: 学习地图
+- `credit`: 学分管理
+- `point`: 积分管理
+- `news`: 资讯管理
+- `certificate`: 证书管理
+- 等等...
+
+每个模块都有对应的Skill，AI Agent会根据用户意图自动选择。
+
+## 相关链接
+
+- 授客AI开放平台: https://opendev.soke.cn
+- NPM包: @sokeai/cli
+- 代码仓库: https://codeup.aliyun.com/5edbc121d1d1abe63b55f1c7/soke/soke-cli.git

package/skills/mono/scripts/check_readiness.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+"""Check prerequisites for the standalone Mono Skill package."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    package = Path(__file__).resolve().parent.parent
+    guide = package / "references" / "installation.md"
+    executable = shutil.which("soke-cli")
+    print("🔍 soke-cli Mono Skill — 环境检查")
+    print(f"  {'✅' if guide.is_file() else '❌'} 安装指南")
+    if not executable:
+        print("  ❌ soke-cli 未安装")
+        return 1
+    result = subprocess.run([executable, "--version"], capture_output=True, text=True, check=False)
+    print(f"  ✅ soke-cli: {result.stdout.strip() or '已找到'}")
+    print("✅ 环境检查完成")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/{soke-ai-coach-director → mono}/scripts/validate_operations.py

@@ -54,8 +54,8 @@ def validate_part1(data: dict) -> list[str]:
         errors.append("key_points: ❌ 被写成数组，平台会接受但字段为空。改为分号拼接的单字符串")
 
     # scene_lang
-    if data.get("scene_lang") != "简体中文":
-        errors.append(f"scene_lang: 必须固定为 '简体中文'，当前 {data.get('scene_lang')!r}")
+    if data.get("scene_lang") not in {"zh", "tw", "en"}:
+        errors.append(f"scene_lang: 必须是 zh、tw 或 en，当前 {data.get('scene_lang')!r}")
 
     # scenario_cover 或 cover_url（CLI 接受两者）
     cover = data.get("scenario_cover") or data.get("cover_url")

package/skills/multi/README.md

@@ -0,0 +1,18 @@
+# soke-cli Multi Skills
+
+本目录按业务模块提供独立 Skill。每个一级目录都包含自己的 `SKILL.md`，其余子目录是该 Skill 的内部参考资料、示例、模板或脚本。
+
+安装全部模块：
+
+```bash
+cp -r skills/multi/soke-* ~/.claude/skills/
+```
+
+安装单个模块：
+
+```bash
+cp -r skills/multi/soke-exam ~/.claude/skills/
+```
+
+每个模块都应能够脱离原仓库独立读取；模块之间不依赖兄弟目录。
+

package/skills/multi/soke-ai-coach-director/CHANGELOG.md

@@ -0,0 +1,203 @@
+# 变更日志
+
+## v2.43.1 — 2026-08-19
+
+### exec-part5.md 并入 exec-part4.md（文件删除）
+
+**背景**：v2.43 已将 Part5 固定配置合并进 Part4 弹窗+同批 apply，exec-part5.md 仅剩向后兼容用途，创建型任务不再加载。用户要求彻底合并去掉该文件。
+
+**变更**：
+1. 删除 `references/exec-part5.md`——独有规则（6 项固定值禁按场景调整 / 字段名以实际发布版本为准 / 不同步 closing_dialogue 等已在前序 Part 同步的字段）已并入 exec-part4.md 注意事项区
+2. 删除 `references/subs/part5/`（SOP 自检清单已内联 exec-part4 断言区）
+3. 更新引用：SKILL.md（版本行/规则 34/加载清单/禁止加载清单）、interaction.md（模板 4 改为 Part4+5 合并确认，原模板 5 删除）、sync-engine.md（文件产出表+一致性扫描合并为 Part4+5 行）、adapters/workbuddy.md（按钮表合并）、README.md
+4. 加载清单不变（仍 ≤9 次读取）——exec-part5.md 本就不在加载路径上，本次是清理死文件
+
+**收益**：技能包文件数 -2，消除"发现 exec-part5.md 会不会要读"的歧义；对积分无影响（该文件已不在加载路径）。
+
+## v2.43.0 — 2026-08-19
+
+### 交付后不写日志 + 剩余 5 项优化（88.37 → 目标 ~73-77）
+
+**背景**：v2.42 实测 88.37（场景内容量更大：6 环节+803字OS+7知识条目，工具化收益真实）。用户要求：分发版同步平台后不写日志 + 继续压积分。
+
+**日志规则（规则 31，分发版核心诉求）**：
+- 创建型任务在平台同步、发布、知识包绑定成功后直接输出完成摘要并结束
+- 禁止自动编辑 SKILL.md、CHANGELOG.md、README.md、项目工作日志或新增学习条目
+- 仅用户明确要求"更新技能/记录经验/维护日志"时才执行维护写入
+- `state-snapshot.json` 仍保留断点恢复状态（每个 Part apply 后写），不作为运行日志
+
+**5 项优化（规则 32-35）**：
+1. **get 回读零上下文（规则 32）**：/tmp/scenario_get.json 只允许 gate_check.py 读取，AI 禁止 Read/tail 引入上下文；闸门结果只看脚本单行输出（省 ~3-4，Step6-8 实测 7.40 偏高，脚本校验后又人工核对是双份）
+2. **知识包条目预生成（规则 33）**：Step 0.5 写提炼稿时同步产出 /tmp/kb-entries.json，Step 10 只剩 sync+bind（省 ~2-3，Step10 实测 13.07 里拆条是二次推导）
+3. **Part4+5 合并应用（规则 34）**：Part5 固定配置不再单独弹窗+apply，并入 Part4 弹窗和同批 operations（省 1 弹窗+1 apply ≈ 2-3）
+4. **材料 sed 限流（规则 35）**：sed 抓段后接 `| head -c 6000`，防关键词密集段一次抓几万字（省 ~1-2）
+5. **交付后不写日志（规则 31）**：见上
+
+**成本结构结论**（88.37 实测）：
+- 内容生成 48.90（55.3%）是**不可压地板**——角色画像/环节/评分就是陪练质量本身
+- 可压空间只有执行浪费 ~11-15 分；再往下只能砍内容（角色 3→2、环节 6→5）或砍知识包，属产品决策非执行优化
+- 积分目标从 ≤60 修正为 **≤75**（诚实反映内容生成成本）
+
+**文件变更**：
+- 更新：SKILL.md（规则 31-35、Step 0.5/5/6-8/10 描述、加载清单 Part4+5 合并行）
+- 更新：exec-part4.md（并入 Part5 固定配置 + 合并弹窗引导语）
+- exec-part5.md 保留（向后兼容，但创建型任务不再加载）→ **v2.43.1 已删除并彻底并入 exec-part4.md**
+
+## v2.42.0 — 2026-08-19
+
+### 工具化优化（79.64 → 目标 ~62）
+
+**背景**：v2.41.1 实测 79.64 积分（较 142.19 大幅下降，加载清单生效），但离 60 目标还差 ~19.6 分。超支点全是"规则已有但没执行"：
+1. 闸门阶段 8 轮 Python 逐步探查 get-scenario 返回结构（~8 分，最大头）
+2. 材料分 4 轮 sed 逐段读手册（~4.5 分）
+3. 读取禁止加载文件 3 个（~3.5 分，其中 part2-roles.md 是被迫——exec-part2 引用 A1-A7 却没内联结构）
+4. apply 后额外校验（~3.6 分）
+
+**根因**：规则是声明性的，AI 执行时因"不知道返回结构"只能边看边猜拆轮探查。
+
+**4 项工具化修复（规则 → 现成工具）**：
+1. **闸门工具化（规则 27）**：新增 `scripts/gate_check.py`——一次跑完 Step 7+8 全部校验（4 项发布闸门 + 3 项补查），自动解包 {data:{...}} 嵌套，Part3 steps 空值告警不阻塞，Part4 权重校验。输出单行 GATE PASS/FAIL。已双路径测试通过。**禁止再用 Python 逐步探查返回结构**（省 ~8 分）
+2. **材料 sed 单命令（规则 28）**：提炼稿只允许一个 sed 命令用多模式一次抓完全部关键段落，禁止分轮读（省 ~4.5 分）
+3. **OS 结构内联（规则 29）**：A1-A7 OS 写作结构从 part2-roles.md 内联到 exec-part2.md，消除被迫读取（省 ~1.5 分）
+4. **apply 后零校验（规则 30）**：apply/publish/sync/bind 成功后只看 tail -3 状态行，禁止任何额外校验，验证统一收敛到闸门 gate_check.py（省 ~3.6 分）
+
+**预期**：79.64 - 8 - 4.5 - 1.5 - 3.6 ≈ 62 积分（接近 60 目标）
+
+**文件变更**：
+- 新增：`scripts/gate_check.py`（闸门一次性校验器，双路径测试通过）
+- 更新：`SKILL.md` 版本 v2.42.0 + 规则 27-30 + 加载清单 Step 6-8 行
+- 更新：`references/exec-part2.md` 内联 A1-A7 OS 写作结构
+
+## v2.41.1 — 2026-08-18
+
+### Bug 修复（用户反馈 3 个问题）
+
+**问题 1：弹窗仍显示完整内容**
+- 根因：`interaction.md` 仍保留 v2.37 规则（question 字段承载完整内容），与 SKILL.md v2.41 规则（摘要化展示）冲突
+- 修复：重写 interaction.md 核心规则 5 + v2.41 弹窗规则 + question 字段模板 + AskUserQuestion 调用示例 + 模板 1-5 的 question 字段，全部改为 ≤2 行引导语
+- 同步修复 SKILL.md 前台可见行和输出格式行
+
+**问题 2：创建完成后为什么要写入 gkill（state-snapshot.json）**
+- 回答：state-snapshot.json 是**断点续传**机制——记录 scenario_id / current_part / applied 标志 / confirmed_data。如果中途中断（网络断/会话超时），下次可以从断点恢复，不用从头创建。这不是浪费，是必要的容错机制。但 v2.41 已将 file_reads 计数器加入其中。
+
+**问题 3：优化后比优化前消耗更多（142.19 vs 93.19）**
+- 根因分析：
+  1. **技能文件过度加载（~27 次 Read）**：规则要求 ≤8 次，实际读了 27 次（exec-part1-5 + part1-5 框架 + 3 个子 SOP + cheatsheet + sync-engine + interaction + publish-gate + gate-matrix + 场景分类库 + soke-ai-training）。这是最大浪费源——"求稳求全"而非"按需加载"
+  2. **CLI 命令 help 探测（~6 次）**：规则明确禁止为查格式跑 --help，实际跑了 6 次
+  3. **知识包 sync 重试 1 次**：--output 参数不存在导致失败重跑
+- 根本原因：v2.41 的规则是**声明性**的——说了"≤8 次"但没有强制拦截机制。AI 在执行时"求稳求全"，把所有可能用到的文件都预读了
+- 修复方向：需要从"声明规则"转向"结构性约束"——在 SKILL.md 中加入**加载顺序清单**（精确到每个 Step 读哪个文件），让 AI 按清单执行而非自行判断
+
+## v2.41.0 — 2026-08-18
+
+### 深度结构优化（目标 60 积分）
+
+**背景**：v2.40 后实测 94 积分，用户要求控制在 60 左右。分析 94 积分构成：
+- Part1-5 生成 35 (37%) / 技能加载 15 (16%) / CLI 15 (16%) / 回读排障 13 (14%) / 材料 10 (11%) / 弹窗 6 (6%)
+- 可避免 ~14 分：Part2 重试 5 + 无关 PDF 4 + 积分排查 5
+
+**5 项结构性优化**：
+1. **exec-handbook 按 Part 拆分（规则 22）**：26KB 单文件 → 5 个 ~5KB Part 文件 + 4KB common 文件。每个 Part 只加载对应文件，总加载量 26KB → ~9KB（-65%）
+2. **Part 展示摘要化（规则 23）**：聊天正文只展示关键字段摘要，完整 JSON 直接 Write 落盘 /tmp/。中文 token 密度降低 ~60%
+3. **材料预过滤（规则 24）**：pdftotext 前先看文件名/标题，无关材料直接跳过（省 ~4 分）
+4. **apply --reason 内联（规则 25）**：apply 必须带 --reason 参数，格式内联 CLI 速查表（省 Part2 重试 ~5 分）
+5. **CLI 合并调用（规则 26）**：Part2 头像+语音列表合并为 1 次 Bash 调用（省 1 次独立调用）
+
+**预期效果**：
+- 技能加载 15 → 7（-8）：exec-handbook 拆分省 8KB token
+- Part1-5 生成 35 → 28（-7）：摘要化展示省中文 token
+- CLI 15 → 11（-4）+ 回读 13 → 8（-5）：合并调用 + --reason 防重试
+- 材料 10 → 6（-4）：预过滤省无关 PDF
+- 总计：94 - 8 - 7 - 9 - 4 = 66 积分（接近 60 目标）
+
+**文件变更**：
+- 新增：`references/exec-common.md` / `exec-part1.md` / `exec-part2.md` / `exec-part3.md` / `exec-part4.md` / `exec-part5.md`
+- 保留：`references/exec-handbook.md`（向后兼容，微调型任务仍可引用）
+- 更新：`SKILL.md` 版本 v2.40 → v2.41，规则 22-26，CLI 速查表，Step 0.5/5 描述
+
+## v2.40.0 — 2026-08-18
+
+### 结构性优化（积分增长根因修复）
+
+**问题**：v2.39 优化后积分从 126 增至 147（+21），原因：
+1. 分析阶段自身消耗 ~10 积分（读 20+ 文件 + 改 5 文件）
+2. 文件膨胀反噬 ~6 积分（SKILL +2 规则、矩阵 +列、SOP +表）
+3. 规则无强制机制 ~3 积分（规则 17/18 是声明，无计数器）
+4. 三大浪费未触及 ~2 积分（CLI 探索/标杆查找/Part3 调查）
+
+**修复**：
+- **规则 17-18 精简**：从 ~400 字缩减为 2 行指针引用，详细说明留在 `gate-check-matrix.md`
+- **规则 19 CLI 命令内联**：高频命令格式直接写入 SKILL.md「CLI 速查」表，禁止为查格式而 Read cheatsheet 文件（省 5 次文件读取）
+- **规则 20 禁止标杆查找**：创建型任务不搜索不加载标杆案例（省 2 次操作）
+- **规则 21 Part3 回读限制**：apply 后只做 1 次布尔断言，禁止多次 get 调查（省 3 次操作）
+- **文件读取计数器**：state-snapshot.json 记录 `file_reads`，超 8 次触发警告（声明→强制）
+
+**预期效果**：消除 18 次可避免操作中的 10 次（CLI 探索 5 + 标杆 2 + Part3 调查 3），预估 147 → ~125 积分。剩余 ~45 积分差距需后续版本通过管线合并（Part2 头像/语音列表合并为 1 次调用）等结构性优化解决。
+
+## v2.39.0 — 2026-08-18
+
+### 优化（积分分析驱动）
+- **闸门精简（Part 自检通过后跳过重叠项）**：分析发现 Step 7 质量闸门 12 项中 9 项与 Part1-5 自检清单完全重叠（闸门1↔Part1自检、闸门3/4/9↔Part2自检、闸门5↔Part3自检、闸门6/10↔Part4自检、闸门7↔Part5自检）。Part 自检全部通过后，闸门仅需补查 3 项（测试用例/整体字数/展示完整度），批量校验脚本从 16 个断言缩减为 7 个。
+- **技能文件按需加载一次复用**：SKILL.md / exec-handbook.md / 各 Part SOP.md / gate-check-matrix.md 在管线首次加载后全程复用，禁止后续 Part 生成时重复 Read。全流程技能文件读取控制在 ≤8 次。
+- **积分目标 ≤80 可达性确认**：基于升舱场景实测（126 积分），识别 3 大浪费源（Part3 apply 验证+回滚 28 积分、闸门重复 get-scenario 16 积分、技能文件重复读 14 积分），通过 v2.39 两条新规则可节省 ~62 积分，预期降至 ~64 积分。
+
+### 问题回答
+- **Q: Part 已检验没有问题，是否不需要再检验？** → A: 是。Part 自检通过后，Step 7 闸门中与之重叠的 9 项自动视为通过，不再重复检查。仅补查 3 项非 Part 自检覆盖的内容。
+- **Q: 质量检验和 Part 是否有冲突？** → A: 无冲突，但存在冗余。Part 自检是字段级校验（执行期），闸门是发布前汇总校验。两者检查内容 75% 重叠（9/12），v2.39 通过精简规则消除冗余。
+
+## v2.30.0 — 2026-08-17
+
+### 优化
+- **Part 展示完成 → 立即弹窗确认**：移除「先输出文字请确认 → 用户输入'确认' → 再弹出确认窗」的中间文字闸门。Part 内容在对话中完整展示后立即弹出确认窗（render_ui / AskUserQuestion），弹窗即确认环节，用户直接通过弹窗选项作答，无需先回复"确认"
+- **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
+
+### 优化
+- **登录自动化**：Step 0 检测到未登录时，AI 自动后台执行 `soke-cli auth login`（OAuth 设备流），自动打开浏览器并输出授权链接，前台一句话引导用户扫码，授权完成后自动重检并继续管线；不再要求用户手动运行命令
+- **env-check.md 重写第 3 步**：移除「无法自动化、提示用户手动执行」的旧约定，改为「后台拉起 → 提取授权链接 → 引导扫码 → 授权完成重检」四步自动流程；补充授权链接带 `cli_redirect_uri` 回调参数不可截断的注意项
+- **字段名对齐实测输出**：登录判定统一为 `config show` 的「用户凭证」，企业绑定统一为「corpid」（原 implementation_corp_id 字段实际不存在）
+- **故障速查表更新**：登录时浏览器未打开 / 授权链接无法访问的修复方式对齐自动执行流程
+
+### 触发方式
+- 创建型 / 微调型 / 同步型任务 Step 0 检测到 `用户凭证` 为空时自动触发，无需用户干预
+
+## v2.24.2 — 2026-08-07
+
+### 重构
+- **SKILL.md 瘦身**：608 → 262 → 289 行（-57%），保留 Step 0-10 流程骨架，细节委托 exec-handbook.md
+- **sync-engine.md 精简**：1154 → 294 行（-74%），从「执行手册+字段参考」双重身份精简为纯「字段参考手册」
+- **exec-handbook.md 扩充**：521 → 588 行，新增「JSON 字段类型硬规则」和「状态快照与缓存规则」两章
+
+### 策略统一
+- Part2 同步策略全局收口为「整包 `replace_ai_roles` 优先，失败降级逐个」
+- 清理 5 个文件中的旧策略残留（platform-api-pitfalls / sync-engine / interaction / prompt-engineer / subs/part2/SOP）
+
+### 结构清理
+- 删除 3 个僵尸目录：`coaching/role-generator`、`knowledge-architect`、`script-architect`
+- 删除 5 个 `api_reference.md` 副本、10 个 example 文件、残留空目录
+- `coaching/` 精简为 4 个有效技能
+
+### 新增
+- SKILL.md 新增「参考规则」表，收录 8 个 references 文件
+- SKILL.md 新增「闸门编号与确认模板映射」表（G1-G5 ↔ 模板 1-6）
+- `references/exec-handbook.md` 新增 2 章节
+- `scripts/validate_operations.py`（396 行，operations 校验工具）
+- `references/exec-handbook.md` 新增「平台头像库 URL 对照表」
+
+### 交付准备
+- 清除回归测试产物（part2-5 operations.json / state-snapshot.json / step1-create.json / kb/ 测试数据）
+- 新增 README.md（入口说明 + 依赖清单 + 快速上手）
+- 新增 CHANGELOG.md
+
+## v2.24.1 — 2026-08-06
+
+- P0+P1 重构：部署缺失文件（exec-handbook.md / validate_operations.py）
+- Part2 同步策略冲突修复
+- 僵尸目录清理
+- SKILL.md 瘦身
+- sync-engine.md 关键段并入 exec-handbook.md
+
+## v2.24.0 — 2026-08-04
+
+- 初始版本，从历史版本整合重构

package/skills/multi/soke-ai-coach-director/README.md

@@ -0,0 +1,124 @@
+# soke-ai-coach-director
+
+> 授客 AI 陪练场景创建与微调技能包 · v2.43.1
+
+## 这是什么
+
+面向授客 AI 平台的陪练场景全流程技能包，覆盖从客户材料到场景上线全链路：
+
+- **创建型**：PDF/Word/Excel 等非结构化材料 → 提炼 → Part1-5 五段式生成 → 平台同步 → 发布
+- **微调型**：已有陪练提示词 → 诊断（F/I/O/L/E/S/R/K/T/D 十标签）→ 优化改稿 → 复测方案
+- **技术排障**：ASR/TTS/权限/跳转等平台问题分流处理
+
+适用对象：AI 陪练运营人员、场景设计师、技术对接人员。
+
+## 环境依赖
+
+| 依赖 | 最低版本 | 用途 |
+|------|----------|------|
+| Node.js | v22+ | 运行时 |
+| Python 3 | 3.10+ | 脚本执行（validate_operations.py 等） |
+| soke-cli | 1.0.76+ | 平台 CLI（场景创建/同步/发布） |
+| pdftotext | 系统自带 | PDF 材料文本提取 |
+
+### soke-cli 安装与登录
+
+```bash
+# 安装（如平台已提供安装包，按平台指引安装）
+soke-cli --version  # 确认安装成功
+
+# 登录（必须人工执行，无法自动化）
+soke-cli auth login
+```
+
+> ⚠️ `auth login` 需要用户在浏览器中手动授权，这是平台安全设计，不可跳过。详见 `references/env-check.md`。
+
+## 快速上手
+
+### 创建一个新陪练
+
+1. **准备材料**：客户提供的 PDF/Word/Excel/URL 等非结构化材料
+2. **发起请求**：在 OpenClaw 对话中说「帮我搭建一个 [行业] [场景] AI 陪练」
+3. **跟随流程**：技能包会自动执行 Step 0-10 管线，你只需在确认闸门做决策
+
+```
+Step 0    平台就绪检测        🔇 后台
+Step 0.5  材料格式分流         🔇 后台
+Step 1    材料完整性检查       📺 仅缺口
+Step 2    场景类型判定         📺 前台确认
+Step 3    链路需求判定         📺 前台判定
+Step 4    7项清单确认          📺 仅 ⚠️ 项
+Step 5    Part1-3 逐段生成     📺 摘要+弹窗确认（Part4+5 合并一个弹窗，v2.43）
+Step 6    平台同步验证         🔇 后台（get 结果仅 gate_check.py 读取）
+Step 7    质量闸门(精简)     🔇 后台（gate_check.py 单行输出 PASS/FAIL）
+Step 8    发布闸门(资源)       🔇 后台（同一脚本内含资源校验）
+Step 9    场景发布            🔇 后台
+Step 10   知识包绑定           📺 弹窗询问（条目用预生成 kb-entries.json）
+```
+
+### 微调一个已有陪练
+
+1. **准备材料**：当前提示词原文 + 对话样本 + 反馈
+2. **发起请求**：「帮我微调 [陪练名称]」
+3. **诊断输出**：自动匹配标签 → 优化改稿 → 复测方案
+
+## 目录结构
+
+```
+soke-ai-coach-director/
+├── SKILL.md                      # 技能入口（调度表+管线总览）
+├── README.md                     # 本文件
+├── CHANGELOG.md                 # 变更日志
+├── assets/                       # 模板文件
+├── coaching/                    # 子技能
+│   ├── knowledge-packager/      # 材料提炼
+│   ├── prompt-engineer/         # Part1-5 生成
+│   ├── prompt-optimizer/         # 微调诊断
+│   └── role-profiler/           # 按需角色画像
+├── platform/                    # 平台层
+│   ├── sync-engine.md           # 字段参考手册
+│   ├── interaction.md           # 弹窗交互规则
+│   ├── api-fallback.md          # REST API 降级
+│   ├── resource-finalizer.md    # 资源回填
+│   ├── publish-gate.md          # 发布闸门
+│   ├── adapters/                # 跨平台适配器
+│   └── soke-ai-training/        # 知识包同步
+├── references/                  # 参考规则
+│   ├── exec-handbook.md         # 唯一执行事实源
+│   ├── env-check.md             # 环境检测协议
+│   ├── verified-cli-cheatsheet.md # CLI 速查
+│   ├── role-resource-matching.md  # 资源匹配规则
+│   ├── platform-api-pitfalls.md   # 平台 API 陷阱
+│   ├── gate-check-matrix.md     # 闸门矩阵
+│   ├── micro-tune-labels.md    # 微调标签
+│   ├── self-learning-engine.md # 自主学习
+│   ├── cases/                   # 案例库
+│   └── subs/                    # 分段 SOP
+└── scripts/                     # 工具脚本
+    ├── validate_operations.py
+    ├── extract-skill.sh
+    ├── error-detector.sh
+    ├── activator.sh
+    └── gate_check.py
+```
+
+## 关键规则速查
+
+- **创建型管线锁**：Step 0→10 严格串行，禁止跳步
+- **Part2 同步策略**：整包 `replace_ai_roles` 优先，失败降级逐个
+- **JSON 硬规则**：string 字段禁写数组；number 不加引号；boolean 不加引号；null 写 null 不写 ""
+- **头像库**：前缀 `https://newsokeeditorcdn.soke.cn/public/ai/roles_avatars/`
+- **Part5 固定配置**：6 项写死值，禁止按场景调整（v2.43.1 起规则并入 exec-part4.md，exec-part5.md 已删除）
+- **积分优化（v2.43.1）**：交付后不写日志 / get 回读零上下文（gate_check.py 专读）/ 知识包条目预生成 / Part4+5 合并应用 / 加载顺序清单 / 材料预过滤+限流
+- **交付边界**：平台同步+发布+知识包绑定完成后直接结束，不写技能日志（仅用户明确要求维护时才写）
+
+> 完整执行规则见 `references/exec-partN.md`（按 Part 加载）+ `references/exec-common.md`（通用约束）。
+
+## 版本
+
+- **当前版本**：v2.43.1（2026-08-19）
+- **变更日志**：`CHANGELOG.md`
+
+## 反馈
+
+问题或建议请通过 OpenClaw 对话反馈。