@sokeai/cli 1.0.76 → 1.0.78

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

@@ -0,0 +1,103 @@
+# 弹窗交互规则
+
+定义 Part1-Part5 及发布/知识包/微调的确认契约（标题/问题/选项/分支路由）。跨平台：WorkBuddy 用 AskUserQuestion，WebChat 用 render_ui QuestionForm，纯文本平台降级为编号选项（见 `platform/adapters/`）。
+
+## 核心规则
+
+1. **Part1 确认后强制同步**：模板 1 无"取消/跳过同步"选项，确认即创建场景。
+2. Part2-Part5 确认后自动 preview + apply，立即进下一 Part，不等二次确认。
+3. Part1 封面写入、Part2 头像/语音匹配、整包写角色、回读校验均后台自动，失败才提示。
+4. 若 Part3 apply 后回读 conversation_steps 仍为空，提示"CLI/平台版本限制，改走 Web 后台补录"。
+5. **弹窗即时触发（v2.30）+ 弹窗仅做确认（v2.41）**：Part **关键字段摘要**在聊天正文展示后立即弹窗。**弹窗 question 字段只写 ≤2 行引导语**（如「以上是 Part2 的 3 个角色设定，是否确认同步？」），**禁止把 Part 完整内容塞进 question 字段**。
+6. **选项文案与分支路由不因渲染方式变化**：所有平台完全一致，用户回复编号或选项文字均可。
+
+## v2.41 弹窗规则（核心变更，替代 v2.37 弹窗承载完整内容）
+
+**弹窗 question 字段只做确认引导，不承载 Part 内容。** 格式要求：
+
+1. **question 字段**：≤2 行引导语（如「以上是 Part2 的 3 个角色设定，是否确认同步？」）。**禁止把 Part 完整字段值写入 question**。
+2. **options**：只放「确认」「需要调整」等选择项。
+3. **options 的 description 字段**：可放 ≤15 字摘要（如「确认后同步到平台」），帮助用户快速判断。
+4. **聊天正文**：展示 Part 关键字段摘要（场景名/角色名+关键词/环节名+目标/维度名+权重/固定值确认），完整 JSON 直接 Write 落盘 /tmp/。
+
+### question 字段内容模板（v2.41 精简）
+
+**Part1**：`以上是 Part1 基础信息（场景名/描述/标签/考核点），是否确认创建？`
+**Part2**：`以上是 Part2 的 3 个角色设定（<角色1名>/<角色2名>/<角色3名>），是否确认同步？`
+**Part3**：`以上是 Part3 流程设置（<环节1名>/<环节2名>/...共 N 个环节），是否确认写入？`
+**Part4+5**（v2.43 合并）：`以上是 Part4 评分标准 + Part5 教练配置（6 项固定值），是否确认写入？`
+
+## AskUserQuestion 调用形式（WorkBuddy，v2.41 精简）
+
+```
+AskUserQuestion(
+  questions=[{
+    "question": "以上是 Part1 基础信息（场景名/描述/标签/考核点），是否确认创建？",
+    "header": "Part1 确认",
+    "options": [
+      {"label": "确认创建（推荐）", "description": "按上述内容创建场景"},
+      {"label": "需要调整", "description": "告诉我需要修改的地方"}
+    ]
+  }]
+)
+```
+
+选项顺序与正文模板一致（推荐操作第一位），模糊匹配优先选项 1。
+
+---
+
+## 确认契约
+
+### 模板 1：Part1 基础信息确认（强制同步）
+- **header**：Part1 确认
+- **question 字段（≤2 行引导语）**：`以上是 Part1 基础信息（场景名/描述/标签/考核点），是否确认创建？`
+- **options**：① 确认创建（推荐），description="按上述内容创建场景"；② 需要调整，description="告诉我需要修改的地方"
+- ⚠️ 无"取消"逃生路径。确认后立即 `+create-scenario`。
+
+### 模板 2：Part2 AI角色设定确认
+- **header**：Part2 确认
+- **question 字段（≤2 行引导语）**：`以上是 Part2 的 3 个角色设定（<角色1名>/<角色2名>/<角色3名>），是否确认同步？`
+- **options**：① 确认写入（推荐），description="<角色1名>/<角色2名>/<角色3名> 3个角色"；② 需要调整，description="告诉我需要修改的角色或性格"
+
+### 模板 3：Part3 流程设置确认
+- **header**：Part3 确认
+- **question 字段（≤2 行引导语）**：`以上是 Part3 流程设置（<环节1名>/<环节2名>/...共 N 个环节），是否确认写入？`
+- **options**：① 确认写入（推荐），description="<环节1名>/<环节2名>/... N个环节"；② 需要调整，description="告诉我需要调整的环节"
+
+### 模板 4：Part4 评分标准 + Part5 教练配置合并确认（v2.43）
+- **header**：Part4+5 确认
+- **question 字段（≤2 行引导语）**：`以上是 Part4 评分标准 + Part5 教练配置（6 项固定值），是否确认写入？`
+- **options**：① 确认写入（推荐），description="<维度1名><weight>分/... 权重合计100+6项固定配置"；② 需要调整，description="告诉我需要调整的维度或权重"
+- ⚠️ 聊天正文需完整展示 Part4（维度权重表）+ Part5（6 项编号列表）两段内容，禁止只给一行摘要。原模板 5（Part5 单独确认）已随 exec-part5.md 删除（v2.43.1）。
+
+### 模板 6：微调诊断确认
+- **标题**：诊断确认 ｜ **问题**：诊断结果和修改方案是否采纳？
+- **选项**：① 确认修改（推荐）→ 生成 optimize JSON → CLI 同步；② 保持原样 → 退出微调；③ 调整诊断 → 重诊。
+
+### 模板 7：知识包同步确认
+- **标题**：知识包同步确认 ｜ **问题**：场景已发布成功，是否同步知识包到平台？
+- **选项**：① 确认，同步知识包（推荐）→ `+sync` → `+bind-scenario`；② 跳过，暂不同步 → 仅输出摘要。
+
+### 模板 8：发布确认（v2.27）
+- **标题**：发布确认 ｜ **问题**：所有配置已完整同步到平台，确认发布场景吗？
+- **选项**：① 确认，发布场景（推荐）→ `+publish-scenario` → 完成摘要 → 弹模板 7；② 暂不发布 → 保持草稿。
+- 🚦 不可跳过或静默执行。
+
+### 模板 9：微调改动清单确认（v2.28）
+- **标题**：微调改动清单确认 ｜ **问题**：以下改动清单，确认后执行同步。
+- **选项**：① 确认，全部同步（推荐）；② 仅同步部分改动 → 模板 9.1；③ 调整优化方案。
+- ⚠️ 未过此闸门禁止生成 operations JSON 或 apply。
+
+### 模板 9.1：字段级同步范围确认（v2.31，多选）
+- 选项文案禁止用后台字段名，须用业务人员能懂的内容项描述（如「沟通风格与话术样例」而非 `communication_style`）。
+- 映射：`style/tone`→语气风格；`personality/trait`→性格特征；`taboo/objection/red_line`→禁忌底线；`background/story/mindset`→角色背景；`knowledge/fact`→知识水平；`step/flow/opening`→流程环节；`criteria/dimension/scoring`→评分维度。
+- 多选后用 AskUserQuestion `multiSelect=true`，返回选中项映射回字段 → 生成 operations → 模板 6。
+
+---
+
+## 通用规则
+
+- 正向操作带「（推荐）」；选项用业务语言，禁后台字段名。
+- 回复解析：精确匹配编号或完整选项文案；模糊匹配优先选项 1。
+- **状态快照**：每 Part 确认后记录 `state-snapshot.json`（scenario_id/current_part/confirmed_data/applied），仅内部断点续传用，不对用户展示。
+- **回退链路**：模板 2/3/4/5 的「重设」→ 回到内容层重新生成该 Part；「调整」→ 局部修改重确认。

package/skills/{ai-coach-director → mono/references/modules/soke-ai-coach-director}/platform/publish-gate.md

@@ -11,7 +11,7 @@
 - Part5 固定配置有效
 
 ### 资源验收
-- `scenario_cover` 非默认图
+- `scenario_cover` 等于固定默认图 `https://newsokeeditorcdn.soke.cn/public/ai/cover/lingshou_daogou.png`
 - 每个角色 `avatar` 非空 URL
 - 每个角色 `voice_id` 非空 ID
 
@@ -22,7 +22,7 @@
 ## 阻断规则
 
 以下情况任一成立，禁止发布：
-- 默认封面未替换
+- 固定默认封面缺失或不正确
 - 任一角色头像为空
 - 任一角色声音为空
 - 任一角色回读为 `角色数据异常`
@@ -37,7 +37,7 @@
 
 ### 不可发布
 输出缺口清单，例如：
-- 封面未补齐
+- 固定默认封面缺失或不正确
 - 角色何女士缺少 voice_id
 - 角色陆先生缺少 avatar
 

package/skills/{ai-coach-director → mono/references/modules/soke-ai-coach-director}/platform/resource-finalizer.md

@@ -1,14 +1,14 @@
 # 资源完善器（resource-finalizer）
 
-> 内部规则文件。作为**最后兜底补救**，仅在 Part1/Part2 的主流程未能写入真实封面/头像/声音时触发。
-> 正常流程下，封面在 Part1 确定、头像和声音在 Part2 与角色一起写入，不需要进入本模块。
+> 内部规则文件。作为**最后兜底补救**，仅在 Part1/Part2 的主流程未能写入固定封面/头像/声音时触发。
+> 正常流程下，封面在 Part1 固定写入默认图、头像和声音在 Part2 与角色一起写入，不需要进入本模块。
 > 本模块默认后台执行，除非修复失败，不向用户暴露执行细节。
-> ⚠️ 本地生成或复用的封面/图片均为后台资源，不得在前台展示图片预览，不得主动输出本地图片路径。只有用户明确要求查看/预览/导出图片时，才可提供路径或展示。
+> ⚠️ 封面与图片资源均为后台资源，不得在前台展示图片预览，不得主动输出本地图片路径。只有用户明确要求查看/预览/导出图片时，才可提供路径或展示。
 
 ## 目标
 
 避免以下半成品状态进入发布：
-- `scenario_cover` 仍为默认封面或为空
+- `scenario_cover` 为空或不是固定默认封面
 - 任一角色 `avatar` 为空
 - 任一角色 `voice_id` 为空
 
@@ -32,7 +32,7 @@ Part1-Part5 主体完成
 以下任一情况判定为未完成：
 - `scenario_cover` 为空
 - `scenario_cover` 为 `null`
-- URL 包含 `default.png`
+- `scenario_cover` 不等于 `https://newsokeeditorcdn.soke.cn/public/ai/cover/lingshou_daogou.png`
 
 ### Avatar Gate
 对每个角色检查：
@@ -50,44 +50,19 @@ Part1-Part5 主体完成
 ## 封面补齐规则
 
 ### 标准流程
-1. 检查 `scenario_cover` 是否为默认图或为空
+1. 检查 `scenario_cover` 是否为固定默认图或为空
 2. 若是，按以下优先级补齐：
 
-**优先级 0：默认固定封面回填**
+**唯一规则：默认固定封面回填**
 - 默认使用：`https://newsokeeditorcdn.soke.cn/public/ai/cover/lingshou_daogou.png`
 - 直接用 `update_basic.scenario_cover` 回填该真实 URL
 - `get-scenario` 验证不再为空且为该固定封面
-
-**优先级 1：从平台图片库/已有真实封面库择图**
-- 若业务明确要求替换默认图，再按行业、业务环节、场景气质筛选图片库素材
-- 若当前环境只有场景封面库能力，则执行 `soke-cli ai-training +list-scenarios --page 1 --page-size 50 --status published --pretty`
-- 从结果中筛出非 `default.png` 的 `scenario_cover`，选择与当前场景最匹配的一条
-- 使用 `update_basic.scenario_cover` 回填该真实 URL
-- `get-scenario` 验证不再为空且非默认图
-
-**优先级 2：复用工作区已有本地封面文件**
-- 按顺序检查：`./scenario-cover.png` → `./scenario-cover.jpg` → `./cover.png` → `./cover.jpg`
-- 若存在，执行 `soke-cli ai-training +upload-scenario-cover --file <本地文件> --pretty`
-- 使用 `update_basic.scenario_cover` 回填真实 CDN URL
-- `get-scenario` 验证不再是默认图
-
-**优先级 3：本地生成封面**
-- 仅当默认图、平台图库/封面库和本地现成图都不可用时，再生成本地封面图 `scenario-cover.png`
-- 生成后仅做后台内部检查，不调用前台图片预览，不向用户展示图片
-- 执行 `soke-cli ai-training +upload-scenario-cover --file ./scenario-cover.png --pretty`
-- 使用 `update_basic.scenario_cover` 回填真实 CDN URL
-- `get-scenario` 验证不再是默认图
-- 若上传失败、未拿到真实 CDN URL、或平台回读仍为空/默认图，则视为“封面未补齐”，禁止发布，不得把“本地已生成文件”误判为已完成
-
-**优先级 3：最终兜底**
-若以上均不可行：
+若固定默认封面回填后仍失败：
 - 标注 `cover_pending`
 - 禁止发布
-- 在交付摘要中提醒用户手动补封面
 
 ### 失败处理
-- 上传失败或平台图库不可用 → 降级到下一优先级
-- 全部降级链路失败 → 标注 `cover_pending`，禁止发布
+- 固定默认封面回填失败 → 标注 `cover_pending`，禁止发布
 
 ## 头像补齐规则
 
@@ -120,7 +95,7 @@ Part1-Part5 主体完成
 ## 发布前最终判定
 
 只有以下全部满足时，才允许执行 `+publish-scenario`：
-- 封面非默认图
+- 封面为固定默认图
 - 所有角色头像非空 URL
 - 所有角色声音非空 ID
 - 无“角色数据异常”

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

@@ -0,0 +1,123 @@
+---
+name: soke-ai-training
+summary: AI教练知识包同步、source管理、场景绑定和知识计划查询
+version: 1.0.0
+description: "用于本地Agent通过soke-cli调用开放平台AI教练知识包接口，完成Markdown source上传、结构化entries同步、source管理、场景知识包版本绑定和知识计划编译查询。"
+metadata:
+  requires:
+    bins: ["soke-cli"]
+  cliHelp: "soke-cli ai-training --help"
+---
+
+# AI教练知识包
+
+**CRITICAL — 开始前 MUST 先读取 [`../../../soke-shared/MODULE.md`](../../../soke-shared/MODULE.md)，其中包含认证、配置和权限处理。**
+
+## 使用前提
+
+1. 运行 `soke-cli auth login` 完成用户授权。
+2. 确认 `soke-cli config show` 中有 `APIBaseURL`、`AppKey`、`AppSecret`、`CorpID` 和用户 token。
+3. 客户原始 PDF、Word、Excel、网页等资料必须先由本地 Agent/Skills 提炼为 Markdown sources 和结构化 entries JSON。
+
+## 推荐同步
+
+```bash
+soke-cli ai-training +sync \
+  --manifest ./knowledge-package.json \
+  --idempotency-key cli-rcb-loan-products-20260610-001
+```
+
+`+sync` 会完成：
+
+1. 读取 manifest 和 entries。
+2. 校验 Markdown 文件、source_refs、entry_id/source_id 唯一性。
+3. 调用 `/skills/ai-training/knowledge-packages/upload-tokens`。
+4. 直传 Markdown 到服务端返回的 `upload_url`。
+5. 调用 `/skills/ai-training/knowledge-packages/sync`。
+6. 写入 `.mentorai-sync-state.json`。
+
+## Manifest 示例
+
+```json
+{
+  "package": {
+    "package_id": "rcb-loan-products",
+    "name": "农商银行贷款产品知识包",
+    "domain": "banking_loan",
+    "tags": ["贷款产品"]
+  },
+  "sources": [
+    {
+      "source_id": "src_manual",
+      "path": "./sources/manual.md",
+      "display_name": "贷款产品手册",
+      "origin_type": "pdf",
+      "origin_filename": "loan-manual.pdf"
+    }
+  ],
+  "entries_path": "./knowledge-package.entries.json"
+}
+```
+
+## entries 格式（2026-08-18 实测补全）
+
+`entries_path` 指向的 JSON 是数组，每项字段：
+
+- `entry_id`：条目唯一 ID（如 `e_upgrade_super`）
+- `entry_type`：**必填枚举**，只能是 `customer_topic` / `disclosure_step` / `advisor_golden_script` / `evaluation_rubric_evidence` / `business_fact`（传其他值会 422）
+- `source_id`：来源 source 的 ID
+- `title`：条目标题
+- `content`：条目正文
+- `source_refs`：**对象数组**（不是字符串数组），形如 `[{"source_id": "src_manual"}]`（传字符串数组会 422）
+- `tags`：标签数组
+
+```json
+[
+  {
+    "entry_id": "e_001",
+    "entry_type": "business_fact",
+    "source_id": "src_manual",
+    "title": "产品权益",
+    "content": "……",
+    "source_refs": [{"source_id": "src_manual"}],
+    "tags": ["产品"]
+  }
+]
+```
+
+## 查询和管理
+
+```bash
+soke-cli ai-training +list-packages --format json
+soke-cli ai-training +list-versions --package-id rcb-loan-products
+soke-cli ai-training +list-sources --package-id rcb-loan-products
+soke-cli ai-training +rename-source --package-id rcb-loan-products --source-id src_manual --display-name "贷款产品手册2026Q2"
+soke-cli ai-training +delete-source --package-id rcb-loan-products --source-id src_manual
+```
+
+## 场景绑定
+
+```bash
+soke-cli ai-training +bind-scenario \
+  --scenario-id scenario_micro_loan_sales \
+  --version-ids 8ed4c1c4-5b3c-4d44-ae8e-d5b064bf1e12 \
+  --compile-plan
+
+soke-cli ai-training +compile-plan \
+  --scenario-id scenario_micro_loan_sales \
+  --version-ids 8ed4c1c4-5b3c-4d44-ae8e-d5b064bf1e12 \
+  --force
+
+soke-cli ai-training +get-plan --scenario-id scenario_micro_loan_sales --format json
+```
+
+## 注意
+
+- 不要在 manifest 或 entries 中伪造 `corp_id`、`user_id` 或 `object_key`。
+- `object_key` 必须使用 upload-token 返回值。
+- 不要把客户原始资料、token、app_secret 或 OSS 签名写入仓库。
+- `advisor_golden_script` 不应进入 AI 客户角色可见知识。
+- ⚠️ `+sync` **不支持 `--pretty`** 参数（加了会报 unknown flag，用 `--format json` 替代）。
+- ⚠️ `origin_filename` 用**纯 ASCII**（如 `manual.pdf`），中文文件名会触发 500「生成知识包上传凭证失败」（2026-08-18 实测）。
+- ⚠️ **v2.37 知识包复用提炼稿**：知识包 Markdown source 直接复用材料提炼稿（`/tmp/xxx_refined.md`），**禁止从零重写**（内容已在上下文中，重写浪费 3-5 积分）。只需按 entries 格式拆条目。
+- ⚠️ **v2.37 CLI 全重定向**：`+sync` / `+bind-scenario` 输出一律 `> /tmp/xxx.json 2>/dev/null`，Python 从重定向文件提取 `version_id` / `package_id`，**禁止 `--format json` 直出到对话**。

package/skills/mono/references/modules/soke-ai-coach-director/platform/sync-engine.md

@@ -0,0 +1,39 @@
+# 平台同步引擎（字段参考手册）
+
+> ⚠️ **本文件已降级为字段参考手册**。执行规则、JSON 模板、字段硬规则、断言均以 `../references/exec-handbook.md` 为唯一事实源。本文件只保留 exec-handbook 未覆盖的：文件产出命名、一致性扫描、跨 Part 交接。
+
+## 核心原则（补充 exec-handbook）
+
+1. JSON 文件写入工作目录，**严禁在对话中出现任何 `.json` 文件名或路径**；文件名只在终端命令中使用。
+2. `corp_id` / `user_id` / `created_by` 等身份字段禁止写入请求文件。
+3. **JSON 内容 = Part 原文，一字不改**：生成 JSON 后、preview 前必须逐字段与已确认 Part 原文 diff，发现缩略/改写/重排序即修正。
+4. 每步先 `+get-scenario` 取最新 `updated_at` 作基线，禁止沿用上一个 Part 的旧值。
+5. CLI 不可用时按 `api-fallback.md` 降级 REST，JSON 结构/字段映射/自查清单与 CLI 完全一致。
+
+## 文件产出规则
+
+| 步骤 | 生成文件 | 使用方式 |
+|------|---------|---------|
+| Step1 | `part1-create.json`（或 `step1-create.json`） | `--request-file ./part1-create.json` |
+| Part2 | `part2-operations.json`（+`part2-update.json`） | 整包 `replace_ai_roles`；排障退 operations |
+| Part3 | `part3-operations.json`（+`part3-update.json`） | 默认 request-file；排障退 operations |
+| Part4+5 | `part4-operations.json`（数组含评分+update_basic 两个元素，v2.43 合并） | 默认 request-file；排障退 operations |
+| 全流程 | `state-snapshot.json` | 完全不出现在聊天 |
+
+> 默认优先直嵌知识库，不默认生成 `knowledge-package.json`；仅知识库过大或用户要求时才走 `+sync` / `+bind-scenario`。
+
+## 一致性扫描（每个 Part 确认后自动执行，无告警不输出）
+
+- **Part2**：background 是否复制四段画像完整原文（我是谁/我的困扰/我的过往经历/我今天的心态），缺一段即告警；JSON 的 background 与确认弹窗展示文本是否逐字一致。
+- **Part3**：Part1 key_points 是否全部在学员目标中有对应环节；每个环节是否含 step_name/student_objective/ai_task/max_rounds；ai_task 是否含进入条件+角色行为+退出条件。
+- **Part4+5**：维度是否与 Part1 key_points 一一对应；总权重是否=100；每个维度 scoring_rule 是否含一票否决；criteria_data 是否在 config 下（`data.config.criteria_data`）；第二个 operation 是否为 update_basic 且 6 项配置值与固定模板完全一致（不含收尾话术/SOP 摘要/考核点摘要）。
+
+## 跨 Part 交接
+
+Part2 角色卡的「我的行为模式」（共鸣触发/关键台词/防御机制/决策逻辑）标记为 Part3 素材，不写入 Part2 JSON，仅作 Part3 生成 AI 任务的参考输入。
+
+## 边界
+
+- `interaction.md` 负责：弹窗确认、按钮分支、回退链路。
+- `exec-handbook.md` 负责：确认后的 JSON 生成、CLI 模板、断言、状态快照更新（唯一事实源）。
+- 本文件负责：字段参考、文件命名、一致性扫描。

package/skills/{ai-coach-director → mono/references/modules/soke-ai-coach-director}/references/change-log-partwise-refactor.md

@@ -25,7 +25,7 @@
 ### Step1 创建
 - 历史误区：只传基础字段即可创建
 - 实证结论：缺少 `scenario_cover` 会直接失败
-- 当前规范：先上传封面，再写入 `step1-create.json`
+- 当前规范：直接写入固定默认封面到 `step1-create.json`
 
 ## 3. Part2 角色结构升级
 

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

@@ -0,0 +1,146 @@
+# soke-cli 环境检测
+
+独立于页面/创作管线，仅在需要调用平台接口时执行。
+
+---
+
+## 依赖清单
+
+| 依赖 | 最低版本 | 用途 | 安装方式 |
+|------|----------|------|----------|
+| Node.js | v14+ | 运行时 | https://nodejs.org/ |
+| soke-cli | 1.0.67+ | 平台 CLI | 平台提供安装包 |
+| Python 3 | 3.10+ | 脚本执行 | https://www.python.org/ |
+| pdftotext | 系统自带 | PDF 文本提取 | macOS: `brew install poppler` · Linux: `apt install poppler-utils` |
+
+> ✅ `soke-cli auth login` 采用 **OAuth 设备流**：命令启动后自动尝试打开浏览器，同时输出授权链接，阻塞等待扫码授权。检测到未登录时，**由 AI 自动执行**（后台拉起 → 提取授权链接 → 前台引导用户扫码 → 授权完成后自动重检继续），**不要求用户手动运行命令**。
+
+---
+
+## 检测流程
+
+按顺序执行，任一步不通过则停止并引导修复。
+
+### 1. Node.js 版本
+
+```bash
+node --version
+```
+
+- ✅ >= 14.0.0 → 通过
+- ❌ 未安装或版本过低 → 提示：`需要 Node.js >= 14.0.0，请先安装或升级`
+- ❌ `command not found` → 提示安装 Node.js
+
+---
+
+### 2. soke-cli 安装
+
+```bash
+which soke-cli && soke-cli --version
+```
+
+- ✅ 输出版本号 → 通过
+- ❌ `command not found` → 执行安装：
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+npm install -g @sokeai/cli@latest
+```
+
+安装后重新执行 `which soke-cli && soke-cli --version` 验证。
+
+> Windows：将 `~/.zshrc` 替换为 PowerShell profile 路径，PATH 追加方式不同（见安装指南 Q2）。
+
+---
+
+### 3. 登录状态
+
+```bash
+soke-cli config show
+```
+
+判定字段：`用户凭证`（非空即已登录）。
+
+- ✅ 输出含 `用户凭证` 且非空 → 通过，进入下一步企业绑定检查
+- ❌ `用户凭证` 为空 → **AI 自动执行登录**（🔇 后台，无需用户手动跑命令）：
+
+```bash
+# Bash 工具参数：run_in_background=true, dangerouslyDisableSandbox=true
+soke-cli auth login
+```
+
+自动执行流程：
+
+1. 后台启动 `soke-cli auth login`，命令阻塞等待授权（OAuth 设备流，不会自行退出）
+2. 读取命令输出，提取授权链接（形如 `https://saas.soke.cn/...?cli_redirect_uri=http%3A%2F%2F127.0.0.1%3A<port>%2Fcallback`）
+3. 📺 前台告知用户（一句话）：「浏览器已自动打开，请扫码完成授权；若未自动打开，请访问：<授权链接>」
+4. 等待命令退出（用户在浏览器完成授权后进程自动结束）→ 重新执行 `soke-cli config show` 确认 `用户凭证` 已存在
+5. 授权完成 → 静默继续下一步企业绑定检查；若用户放弃/超时 → 停掉后台任务，提示用户随时说「继续」重新拉起登录
+
+> ⏳ 授权链接带 `cli_redirect_uri` 回调参数，必须完整复制、不可截断；浏览器未自动打开时用户手动访问该链接即可。
+
+- ❌ 返回 `401 Unauthorized` → Token 过期，自动重新登录：
+
+```bash
+soke-cli auth logout
+soke-cli auth login   # 按上述自动执行流程（后台拉起 + 引导扫码）
+```
+
+登录成功后重新执行 `soke-cli config show`，确认 `用户凭证` 已恢复。
+
+---
+
+### 4. 企业绑定（corp binding）
+
+```bash
+soke-cli config show
+```
+
+判定字段：`corpid`（非空即已绑定企业）。
+
+- ✅ `corpid` 非空 → 通过，记录企业 ID 供后续使用
+- ❌ `corpid` 为空 → 提示用户：
+  > 已登录，但当前账号未绑定企业。请先在授客AI平台完成企业绑定，再重新执行 `soke-cli auth login --force`
+
+如需强制刷新企业绑定信息，执行：
+
+```bash
+soke-cli auth login --force   # 自动执行流程同上（后台拉起 + 引导扫码）
+```
+
+完成后重新执行 `soke-cli config show`，确认 `corpid` 非空。
+
+如果仍为空，说明当前账号未加入任何企业，需联系管理员添加。
+
+---
+
+## 常见故障速查
+
+| 现象 | 原因 | 修复 |
+|------|------|------|
+| `which soke-cli` 无输出但已安装 | PATH 未生效 | `source ~/.zshrc` 或新开终端 |
+| `401 Unauthorized` | Token 过期 | `soke-cli auth logout && soke-cli auth login`（后者自动执行） |
+| 登录时浏览器未打开 | 系统无默认浏览器 | 用户手动访问 AI 提供的授权链接（完整复制含 `cli_redirect_uri`） |
+| 授权链接无法访问 | 链接被截断/过期 | 停掉当前后台任务，重新 `soke-cli auth login` 生成新链接 |
+| `npm: command not found` | Node.js 未安装 | 安装 Node.js >= 14 |
+| `EACCES` 权限错误 | npm 全局安装需要 sudo | 使用 `~/.npm-global` 方案（见步骤2） |
+| `corpid` 为空 | 未绑定企业 | `soke-cli auth login --force` 重新授权，或联系管理员 |
+
+---
+
+## 使用方式
+
+```
+# 在 ai-coach-director 中
+read references/env-check.md
+按顺序执行 4 步检测：
+  1. node --version
+  2. which soke-cli && soke-cli --version
+  3. soke-cli config show → 确认「用户凭证」非空；为空则自动执行 soke-cli auth login（后台拉起 + 引导扫码）
+  4. soke-cli config show → 确认 corpid 非空
+全部通过 → 记录企业 ID，继续调度
+任一步失败 → 按修复流程处理（登录类自动拉起授权），不进入内容生成/同步
+```

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

@@ -0,0 +1,126 @@
+# 通用执行约束（Common Execution Rules）
+
+> v2.41 从 exec-handbook.md 拆分。所有 Part 共享的 CLI 参数、材料铁律、字段类型硬规则、状态快照规则。
+> 各 Part 专属模板/断言/反面案例见 `exec-partN.md`。
+
+---
+
+## CLI 参数固定值
+
+- `--scenario-id <id>`（不是 `--scenario <id>`）
+- apply 需要 `--idempotency-key <unique>` 和 `--reason "PartN同步"`（v2.41：省略 --reason 会导致 422）
+- 每次 apply 后必须重新获取 `updated_at` 作为下次 `--base-updated-at`
+- **所有 CLI 输出一律 `> /tmp/xxx.json 2>/dev/null` 重定向**，禁止 `--pretty` 直出到对话。Python 从重定向文件提取字段，不回显 JSON 原文。
+- **apply 禁止用于验证**。验证数据用 `+get-scenario`，apply 后只从返回值提取 `updated_at`（`tail -1` 或 Python 提取），不回显 operations/snapshot_id。用 apply 回读环节会导致 `add_conversation_step` 重复添加。
+
+---
+
+## 材料预处理铁律（v2.41 强化：预过滤）
+
+非结构化材料（PDF/DOCX/PPT）处理流程：
+1. **预过滤（v2.41 新增）**：先看文件名/标题，只对与场景直接相关的材料做 pdftotext。无关材料直接标注「已跳过：与场景无关」。
+2. **一次成型写提炼稿**：pdftotext 提取到 `/tmp/` → **一次性** grep 定位 + sed 读取关键段落 → Write 落盘提炼稿到 `/tmp/xxx_refined.md`。**禁止分多轮 sed 回看**。
+3. **原始材料全文不再进入后续 Part 上下文**——Part1-5 生成只读提炼稿
+4. 提炼稿只保留 Part1-5 所需结构化要素（业务背景/训练对象/话术/画像线索/异议/红线/评分线索）
+5. 提炼稿删除无关段落（目录/版权页/附录/重复章节）
+6. 提炼稿 ≤1500 字（硬上限），超了二次压缩只保留核心要素
+7. **提炼稿落盘后，后续 Part1-5 只 Read 这一个文件**，不再碰原始 PDF/DOCX
+
+---
+
+## 后台静默规则（G1/G3）
+
+所有 CLI 错误（stderr / 非零退出 / 422 / 409）**禁止对用户展示**。AI 内部分析修正（最多 2 次重试），仍失败仅告知"Part N 同步异常"+ ≤50 字原因。
+
+---
+
+## 输出过滤规则（v2.35 反压缩强化）
+
+后台 Python 脚本的 print() 输出、JSON 文件大小、字符数统计、自查断言结果（"✅ xxx"）→ 🔇 后台静默，**禁止出现在对话消息中**。
+
+**CLI 输出强制静默**：
+- 所有 soke-cli 命令输出一律 `> /tmp/xxx.json 2>/dev/null` 重定向
+- preview/apply 命令一律 `2>/dev/null | tail -3`，只看结尾 3 行状态
+- `+get-scenario` 回读一律 `> /tmp/xxx.json` 重定向，Python 只打印 `True/False` 布尔判断
+- snapshot_id / updated_at / warnings / operations 回显**一律吞掉**
+- **apply 禁止用于验证**：apply 是写入操作，不是读取操作。用 apply 回读环节会导致 `add_conversation_step` 重复添加 → 需快照回滚 → 浪费 3-5 积分。验证用 `+get-scenario`。
+- 仅失败时输出 ≤50 字原因
+
+---
+
+## 平台头像库
+
+正确路径前缀：`https://newsokeeditorcdn.soke.cn/public/ai/roles_avatars/`（❌ 错误：`/public/ai/avatar/`，存进去 UI 空白）。
+头像 URL 一律通过 `soke-cli ai-training +list-role-avatars` **重定向到 /tmp/avatars.json 后 Python 按性别/年龄关键词过滤 title 字段提取 url**（禁止 `--pretty` 直出，禁止 `--gender`/`--age-group` 参数——CLI 不支持）。声音同理重定向到 `/tmp/voices.json` 后 Python 提取 `id`。
+
+---
+
+## JSON 字段类型硬规则
+
+> 原则：**文档是什么类型，就严格按什么类型生成。**
+
+### string 字段：必须生成字符串
+
+多条内容用顿号、分号、编号或 `\n` 拼接为一个字符串，禁止写成数组。
+
+关键 string 字段：`name`、`description`、`key_points`、`role_data.name`、`role_data.description`、`role_data.avatar`、`role_data.communication_style`、`role_data.background`、`role_data.personality_type`、`role_data.personality`、`role_data.voice_id`、`ai_roles_overall_description`、`opening_dialogue`、`conversation_steps[].step_name`、`conversation_steps[].student_objective`、`conversation_steps[].ai_task`、`criteria_data.name`、`criteria_data.description`、`dimensions[].code`、`dimensions[].name`、`dimensions[].description`、`dimensions[].scoring_rule`
+
+### string[] 字段：只有明确数组字段才生成数组
+
+每条一个元素：`tags`、`conversation_knowledge_base_ids`、`scoring_knowledge_base_ids`、`role_data.tags`、`role_data.knowledge_level`、`role_data.taboos_objections`、`dimensions[].criteria`
+
+### number / boolean / null 字段
+
+- number 不加引号：`weight`、`total_weight`、`max_rounds`、`max_practice_attempts`、`passing_score`、`pass_difficulty`、`dimensions[].sort_order`
+- boolean 不加引号：`is_custom_role`、`is_custom_criteria`、`ai_assistance_enabled`
+- null 写 `null`，不写空字符串或 `"null"`
+
+### 创建/更新差异
+
+- 创建 `conversation_steps` 用 `ai_objective`；更新用 `ai_task`。
+- 创建 `conversation_steps[].sort_order` 写字符串（`"1"`）；评分维度 `sort_order` 写数字（`1`）。
+
+### 生成前自检
+
+```text
+☐ string 字段没有被写成数组或对象
+☐ string[] 字段没有被写成逗号分隔字符串
+☐ number 字段没有加引号
+☐ boolean 字段没有加引号
+☐ null 字段没有写成 "" 或 "null"
+☐ 创建/更新 sort_order 类型符合对应接口要求
+```
+
+---
+
+## 状态快照与缓存规则
+
+### state-snapshot.json 结构
+
+```json
+{
+  "mode": "partwise",
+  "scenario_id": "scn_xxx",
+  "scenario_short": "b7730195",
+  "updated_at": "2026-07-10T01:40:58.216028Z",
+  "current_part": "part3",
+  "confirmed_data": { "part1": {}, "part2": {}, "part3": {}, "part4": {}, "part5": {} },
+  "applied": { "part1": true, "part2": true, "part3": false, "part4": false, "part5": false },
+  "cached": { "role_profile": {}, "scenario_type": "" },
+  "file_reads": 0
+}
+```
+
+### 依赖与回滚规则
+
+- Part1 修改 → Part2-Part5 全部待复核
+- Part2 修改 → 至少重检 Part3 与 Part5
+- Part3 修改 → 至少重检 Part4 与 Part5
+- Part4 修改 → 重检 Part5
+- Part5 修改通常不反推前序 Part，但若改动通关分数/难度，需检查与 Part4 评分体系一致
+
+---
+
+## 沙箱绕过（G4）
+
+WorkBuddy Bash 调用 soke-cli 必须设 `dangerouslyDisableSandbox: true`。