@sokeai/cli 1.0.74 → 1.0.75

package/skills/ai-coach-director/platform/sync-engine.md

@@ -10,15 +10,21 @@
 
 ## 核心原则
 
-1. JSON 文件写入工作目录，只在 CLI 命令中通过文件名自然出现，不单独提示"已生成文件"
+1. JSON 文件写入工作目录，**严禁在对话中出现任何 `.json` 文件名或路径**；`--request-file` / `--operations-file` 参数中的文件名始终在终端命令中使用，不写入对话窗口
 2. `corp_id` / `user_id` / `created_by` 等身份字段绝对禁止写入请求文件
 3. 字段直接从 Part1-Part5 结构化数据填充，不从自然语言大段反解析
-4. **Part1 确认后强制同步**：用户在 `interaction.md` 模板 1 中选「确认，同步到平台（推荐）」后，立即执行 Step1 创建场景，不存在"跳过同步"的逃生路径
+4. **Part1 确认后强制同步**：用户在 `interaction.md` 模板 1 中选「确认，同步到平台（推荐）」后，立即执行 Step1 创建场景，不存在"跳过同步"的逃生路径。封面图的查找、生成、上传、修正全部后台自动处理，不向用户逐项确认
 5. 创建型流程采用按 Part 逐段同步：Step1 创建场景 → Part2 同步角色 → Part3 同步流程 → Part4 同步评分 → Part5 同步教练设置
 6. 每一步都先取最新平台状态，再生成 `base_updated_at` / `updated_at`，禁止依赖用户手工回传
 7. 平台真实 API 优先于历史文档示例；若文档与真实返回冲突，以已验证的 CLI / API 行为为准
 8. **JSON 内容 = Part 原文，一字不改**：生成 JSON 后、preview 前，必须逐字段与已确认的 Part 原文做 diff——JSON 中的文案与原文必须逐字相同，发现任何差异（缩略、改写、编造编号、重新排序）必须修正后再 preview。"大意相同"即违规
 9. **所有 soke-cli 命令必须绕过沙箱执行**：soke-cli 是 Go 编译二进制，在 WorkBuddy Bash 工具沙箱中会受限。调用 Bash 工具执行任何 soke-cli 命令时，必须设置 `dangerouslyDisableSandbox: true`。若命令返回 `permission denied` 或静默无输出，这是沙箱限制的预期表现，加 `dangerouslyDisableSandbox: true` 重试即可
+10. **资源匹配双通道（avatar/voice）**：Part2 内容先完整展示并由用户确认；确认后，资源匹配在生成 JSON 前后台执行。先检测 soke-cli 可用性——可用走 CLI 路径（`role-resource-matching.md`），不可用走 REST API 路径（`api-fallback.md`「资源匹配完整流程」）。**禁止因 CLI 不可用直接跳过资源匹配**——这会导致角色无头像无声音。只有 API 查询本身失败才允许标注跳过。资源匹配、写入、回读校验均不向用户二次确认
+11. **CLI 不可用时降级为 REST API**：当 soke-cli 在目标平台完全不可用（如悟空安全策略禁止、纯聊天环境），按 `api-fallback.md` 降级为 MentorAI REST API 直接调用。JSON 结构、字段映射、自查清单与 CLI 路径完全一致，差异仅在传输方式
+12. **对照最新 CLI 指南（v2.7）**：除踩坑清单外，同步执行还必须对齐《比得_AI陪练CLI创建与更新场景使用指南 2.0》的最新约定：优先使用 `--request-file` 承载完整更新请求；排障时再改用 `--operations-file` + `--base-updated-at` 组合。`preview` 不传 `idempotency_key`，`apply` 才强制要求
+13. **Part1 默认封面固定 + Part2 强制内联资源（v2.20.8）**：封面图 URL 必须在 `step1-create.json` 生成前确定，不允许先建空壳再补。**默认封面固定为** `https://newsokeeditorcdn.soke.cn/public/ai/cover/lingshou_daogou.png`，无需前台展示处理过程。只有当用户明确指定其他封面、或 `resource-finalizer.md` 兜底替换时，才允许改为其他 URL。角色头像和声音必须在 `part2-operations.json` 生成前完成匹配并写入，不允许分两次操作。`resource-finalizer.md` 降级为最后兜底补救，仅在前序流程意外遗漏时触发
+14. **Part1 创建成功硬闸门（v2.20.4）**：Part1 不是 preview/apply 更新链路，而是创建链路。用户确认后，必须立即生成 `part1-create.json` 或沿用 `step1-create.json`，并立即执行 `soke-cli ai-training +create-scenario --request-file ...`。**只有在创建返回成功、提取到非空 `scenario_id`、并完成创建后回读校验后，才允许进入 Part2。** 任一条件未满足 → 立即报错并停止，禁止静默续流。
+15. **Part2-Part5 同步成功硬闸门（v2.20.5）**：Part2、Part3、Part4、Part5 都属于更新链路。用户确认后，后台**必须先生成对应 JSON，再真实执行 preview/apply，再完成对应验收**，之后才允许进入下一 Part。若任一 Part 未生成 JSON、未执行同步、preview/apply 失败、或验收失败，必须立即报错并停止，禁止静默续流到下一 Part。
 
 ---
 
@@ -26,13 +32,13 @@
 
 | 模式 | 步骤 | 生成文件 | 在聊天中如何出现 |
 |---|---|---|---|
-| 创建型 | Step 1 | `step1-create.json` | CLI 命令中 `--request-file ./step1-create.json` |
-| 创建型 | Part2 | `part2-operations.json` | CLI 命令中 `--operations-file ./part2-operations.json` |
-| 创建型 | Part3 | `part3-operations.json` | CLI 命令中 `--operations-file ./part3-operations.json` |
-| 创建型 | Part4 | `part4-operations.json` | CLI 命令中 `--operations-file ./part4-operations.json` |
-| 创建型 | Part5 | `part5-operations.json` | CLI 命令中 `--operations-file ./part5-operations.json` |
+| 创建型 | Step 1 | `part1-create.json` 或 `step1-create.json` | CLI 命令中 `--request-file ./part1-create.json` 或 `--request-file ./step1-create.json` |
+| 创建型 | Part2 | `part2-operations.json` + `part2-update.json` + `part2-role-01.json` + `part2-role-02.json` + `part2-role-03.json` + `part2-os.json` | 用户确认后后台自动拆分并逐个同步；默认不直接执行整包 Part2 |
+| 创建型 | Part3 | `part3-operations.json` + `part3-update.json` | 优先在 CLI 命令中用 `--request-file ./part3-update.json`；排障时可退回 `--operations-file ./part3-operations.json` |
+| 创建型 | Part4 | `part4-operations.json` + `part4-update.json` | 优先在 CLI 命令中用 `--request-file ./part4-update.json`；排障时可退回 `--operations-file ./part4-operations.json` |
+| 创建型 | Part5 | `part5-operations.json` + `part5-update.json` | 优先在 CLI 命令中用 `--request-file ./part5-update.json`；排障时可退回 `--operations-file ./part5-operations.json` |
 | 创建型 | 全流程 | `state-snapshot.json` | 完全不在聊天中出现 |
-| 微调 | 唯一 | `optimize-operations.json` | CLI 命令中 `--operations-file ./optimize-operations.json` |
+| 微调 | 唯一 | `optimize-operations.json` + `optimize-update.json` | 优先 `--request-file ./optimize-update.json`；排障时再退回 operations 模式 |
 
 > 创建型默认优先直嵌知识库,不再默认生成 `knowledge-package.json`。只有知识库过大或用户明确要求知识包同步时,才进入 `soke-cli ai-training +sync` / `soke-cli ai-training +bind-scenario` 路径。
 
@@ -40,9 +46,9 @@
 
 ## 字段映射表
 
-### 从 Part1 → `step1-create.json`
+### 从 Part1 → `part1-create.json` / `step1-create.json`
 
-> ⚠️ **核心规则：`step1-create.json` 的每个字段必须是已确认 Part1 的 1:1 忠实搬运，禁止在此阶段重新缩略、改写、扩写或重组内容。** 用户已确认的是哪个版本的 Part1，JSON 就用哪个版本。
+> ⚠️ **核心规则：`part1-create.json` 或 `step1-create.json` 的每个字段必须是已确认 Part1 的 1:1 忠实搬运，禁止在此阶段重新缩略、改写、扩写或重组内容。** 用户已确认的是哪个版本的 Part1，JSON 就用哪个版本。
 
 | 提示词取值来源 | JSON 字段 | 类型 | 搬运规则 |
 |---|---|---|---|
@@ -50,7 +56,7 @@
 | Part1 场景描述（全文） | `description` | string | **完整搬运，不缩略不改写**；Part1 \"场景描述\"下的全部正文就是 description 的值 |
 | Part1 标签 | `tags` | string[] | 逐项映射为数组元素，顺序保持一致 |
 | Part1 考核关键点 | `key_points` | string | **必填**，将考核关键点各条拼接为单字符串（分号或编号分隔），不能是数组 |
-| **固定值 `简体中文`** | `scene_lang` | string | **必填，写死 `"简体中文"`，永远不改为其他值**。scene_lang 的取值不随用户语言、场景语种变化，始终固定为简体中文 |
+| **固定值 `简体中文`** | `scene_lang` | string | **必填，写死 `"简体中文"`，永远不改为其他值**。scene_lang 的取值不随用户语言、场景语种变化，始终固定为简体中文；即使材料中写“中文”“普通话”“zh-CN”或其他表述，创建请求里也只能写 `简体中文` |
 | Part1 行业 | `industry` | string | 如平台字段存在则写入 |
 | Step1 已上传封面 | `scenario_cover` | string | **必填**，先上传封面再创建。封面来源见下方「封面生成与上传」规则 |
 | 已绑定企业 ID | `implementation_corp_id` | string | 若请求体存在该字段也不能依赖其选租户 |
@@ -59,6 +65,8 @@
 
 > ⚠️ **忠实搬运**：Part2 已确认的角色卡各字段原样映射，不在此阶段修改文案。
 
+> ⚠️ **默认策略变更（v2.8）**：Part2 首次写入默认不要整包 `replace_ai_roles`。应优先按“单角色 `add_ai_role` → 回读验证 → 继续追加下一个角色 → 全部角色完成后再单独 `update_basic` 写 OS”的顺序执行。只有目标平台已被实证验证对整包角色替换稳定时，才允许改回 `replace_ai_roles`。
+
 | 提示词取值来源 | JSON 字段 |
 |---|---|
 | 角色卡.名称 | `ai_roles[].role_data.name` |
@@ -175,7 +183,7 @@
 
 ### Step 1:创建场景
 
-`step1-create.json` 必须包含以下字段（全部必填）：
+`part1-create.json` 或 `step1-create.json` 必须包含以下字段（全部必填）：
 `name`, `description`, `tags`, `key_points`, `scene_lang`, `scenario_cover`。
 
 示例（完整六字段）：
@@ -191,6 +199,14 @@
 }
 ```
 
+```bash
+soke-cli ai-training +create-scenario \
+  --request-file ./part1-create.json \
+  --pretty
+```
+
+若当前实现仍沿用旧文件名，也允许：
+
 ```bash
 soke-cli ai-training +create-scenario \
   --request-file ./step1-create.json \
@@ -211,23 +227,20 @@ soke-cli ai-training +create-scenario \
 ```
 
 执行要求:
-- **封面生成与上传**：用户确认 Part1 后，在创建场景前必须先完成封面生成和上传：
-  1. **生成封面**：将场景名称 + 标签 + 行业信息作为 prompt，调用大模型图片生成，生成一张 4:3 比例场景封面图（如 1200×900），保存为本地 PNG（`./scenario-cover.png`）。
-     - prompt 示例：`"生成一张AI陪练场景封面图，主题：{场景名称}，行业：{行业}，风格：{行业匹配风格}，4:3比例，专业商务风格，适合培训场景使用"`
-     - 风格匹配：展会/培训 → 明亮商务、医药 → 学术医疗、销售/谈判 → 高压剧集感、餐饮/服务 → 温馨生活、金融 → 专业稳重
-  2. **上传封面**：执行 `soke-cli ai-training +upload-scenario-cover --file ./scenario-cover.png --pretty`
-  3. **写入 URL**：从返回结果提取 CDN URL，写入 `step1-create.json.scenario_cover`
+- **封面确定规则**：用户确认 Part1 后，在生成 `part1-create.json` 或 `step1-create.json` 前，默认直接写入固定封面 URL：`https://newsokeeditorcdn.soke.cn/public/ai/cover/lingshou_daogou.png`。仅当用户明确指定其他封面、或发布前资源补救流程主动替换时，才允许改用其他 URL。
 - **`key_points` 必须是字符串**，不能是数组；多条用分号或编号拼接
-- **`scene_lang` 固定为 `"简体中文"`**，永远不改为其他值
+- **`scene_lang` 固定为 `"简体中文"`**，永远不改为其他值；生成请求时如果出现“中文”“zh-CN”“普通话”等值，必须在写文件前纠正为 `简体中文`
 - **`tags` 必须是数组**，不能是逗号分隔字符串
 - 自动从返回结果提取 `scenario_id`
+- **`scenario_id` 必须非空**：若创建命令返回成功但未提取到 `scenario_id`，按创建失败处理，立即报错并停止
 - 将 `scenario_id` 写入 `state-snapshot.json`
-- **创建后验证**：执行 `soke-cli ai-training +get-scenario --scenario-id <id> --pretty`，确认返回中 `key_points`、`description`、`name`、`tags` 字段非空且内容与 `step1-create.json` 一致。若 `key_points` 为空或缺失，检查 `step1-create.json` 中 `key_points` 字段是否为字符串格式
-- 立即进入 Part2,不等待用户回传
+- **创建后验证**：执行 `soke-cli ai-training +get-scenario --scenario-id <id> --pretty`，确认返回中 `key_points`、`description`、`name`、`tags` 字段非空且内容与 `part1-create.json` 或 `step1-create.json` 一致。若 `key_points` 为空或缺失，检查创建请求文件中 `key_points` 字段是否为字符串格式
+- **只有创建命令成功 + `scenario_id` 非空 + 创建后验证通过，才允许进入 Part2**
+- 若任一步失败：立即向用户报错，停止流程，严禁静默进入 Part2
 
-### step1-create.json 自查清单
+### part1-create.json / step1-create.json 自查清单
 
-> ⚠️ 生成 `step1-create.json` 后、创建场景前，**必须逐项核对**。
+> ⚠️ 生成 `part1-create.json` 或 `step1-create.json` 后、创建场景前，**必须逐项核对**。
 
 | # | 检查项 | 正确 | 错误示例 |
 |---|---|---|---|
@@ -241,9 +254,38 @@ soke-cli ai-training +create-scenario \
 
 > 🔴 **#4 是最高频错误**：`key_points` 写成数组而非字符串，导致创建成功但字段为空。
 > 🔴 **#5 scene_lang 写死**：永远不随场景语言变化，始终 `"简体中文"`。
+> 🔴 **#6 默认封面固定**：若无特别指定，`scenario_cover` 直接写固定平台图 `https://newsokeeditorcdn.soke.cn/public/ai/cover/lingshou_daogou.png`。
+> 🔴 **创建成功闸门**：没有 `scenario_id`，或 `get-scenario` 校验不通过，均视为 Part1 未完成，绝不进入 Part2。
 
 ### Part2:AI角色设定
 
+优先生成两个文件：
+- `part2-operations.json`：完整 Part2 operations 裸数组（总定义）
+- `part2-update.json`：完整更新请求（仅供总调试，不作为默认执行入口）
+
+然后后台自动拆分为角色级同步单元：
+- `part2-role-01.json`
+- `part2-role-02.json`
+- `part2-role-03.json`
+- `part2-os.json`
+
+默认后台执行顺序：
+1. Part2 已按「OS → 角色1 → 角色2 → 角色3...」完整展示并通过用户确认
+2. 自动查询头像库与语音库
+3. 为第1个角色匹配 avatar 与 voice_id
+4. 生成 `part2-role-01.json` → preview + apply → `get-scenario` 回读验证
+5. 为第2个角色匹配 avatar 与 voice_id
+6. 生成 `part2-role-02.json` → preview + apply → 回读验证
+7. 为第3个角色匹配 avatar 与 voice_id
+8. 生成 `part2-role-03.json` → preview + apply → 回读验证
+9. 生成 `part2-os.json` → preview + apply → 回读验证
+10. 全部同步成功后更新 state-snapshot，并把控制权交回 prompt-engineer **立即自动输出 Part3**
+11. 如平台已实证稳定，才允许整包 `replace_ai_roles` 作为特殊模式
+
+除非失败，以上过程不向用户展示细节，也不向用户请求任何中间确认。用户只确认完整 Part2 内容；角色资源匹配、角色1/角色2/角色3写入、OS写入和回读验证全部自动执行。**同步成功后不得停在中间态等待用户再次输入，必须自动续流输出 Part3。**
+
+> ⚠️ **禁止中间态阻塞（v2.20.1）**：如前台已输出“Part2 已确认，正在后台同步角色设定”或等价提示，后台同步成功后必须在同一轮中继续输出 Part3，禁止把这条提示当成需要用户再次回复“继续”的断点。只有在 apply/回读失败或出现必须人工介入的异常时，才允许停下并提示用户。
+
 先获取最新场景状态:
 
 ```bash
@@ -252,24 +294,38 @@ soke-cli ai-training +get-scenario \
   --pretty
 ```
 
-再预览:
+再预览（默认 request-file 模式）:
 
 ```bash
 soke-cli ai-training +preview-scenario-update \
   --scenario-id <scenario_id> \
-  --base-updated-at <updated_at> \
-  --operations-file ./part2-operations.json \
-  --reason "Part2: AI角色设定" \
+  --request-file ./part2-update.json \
   --pretty
 ```
 
-预览通过后立即应用:
+预览通过后立即应用（默认 request-file 模式）:
 
 ```bash
 soke-cli ai-training +apply-scenario-update \
   --scenario-id <scenario_id> \
+  --request-file ./part2-update.json \
+  --pretty
+```
+
+如需排障，再退回 operations 模式：
+
+```bash
+soke-cli ai-training +preview-scenario-update \
+  --scenario-id <scenario_id> \
+  --operations-file ./part2-operations.json \
   --base-updated-at <updated_at> \
+  --reason "Part2: AI角色设定" \
+  --pretty
+
+soke-cli ai-training +apply-scenario-update \
+  --scenario-id <scenario_id> \
   --operations-file ./part2-operations.json \
+  --base-updated-at <updated_at> \
   --idempotency-key "cli-<scenario_short>-part2-apply" \
   --reason "Part2: AI角色设定" \
   --pretty
@@ -284,41 +340,24 @@ soke-cli ai-training +apply-scenario-update \
   3. `ai_roles_overall_description` 非空，且前 100 字符与 Part2 OS 原文前 100 字符一致——确保 OS 整体设定完整写入而非丢失
   4. `role_data.name` ≠ `"角色数据异常"`——若出现此值，检查外壳字段是否误放入 `role_data` 内部
   5. 每个角色的 `role_data.background` 包含四段深度画像（我是谁/我的困扰/我的过往经历/我今天的心态），四段全部非空
-  6. **⚠️ avatar/voice_id 首次验收不检查**：角色首次 apply 时 `avatar`/`voice_id` 应为空 `""`，此阶段验收不要求 avatar/voice_id 非空。验收通过后进入下方资源回填流程。
-
-- **立即触发头像和语音资源自动匹配**（按 `../references/role-resource-matching.md` 执行）：
-  1. **提取角色特征**：从角色卡提取性别(gender) + 年龄(age_group)，映射为 CLI `--gender` / `--age-group` 过滤参数
-  2. **并行查询**：同时发起 `+list-role-avatars` 和 `+list-role-voices`（带过滤参数），节省往返时间
-  3. **合并写入**：头像和语音**必须在同一个 `patch_ai_role` 操作中写入**，不可分两次——分开调用会导致第二次 patch 后 `updated_at` 变化，后续验收时误判第一次写入丢失
-     ```json
-     [
-       {
-         "type": "patch_ai_role",
-         "data": {
-           "scenario_role_id": "<角色ID>",
-           "patch": {
-             "role_data": {
-               "avatar": "<头像URL>",
-               "voice_id": "<声音ID>"
-             },
-             "customized_fields": ["avatar", "voice_id"]
-           }
-         }
-       }
-     ]
-     ```
-     - `avatar` 值：头像资源 **URL**（来自 `+list-role-avatars` 的 `url` 字段），严禁用 `id`
-     - `voice_id` 值：声音资源 **ID**（来自 `+list-role-voices` 的 `id` 字段）
-     - `customized_fields` 必须包含 `["avatar", "voice_id"]`，两者都写
-  4. **强制验证**：patch apply 后立即执行 `soke-cli ai-training +get-scenario --scenario-id <id> --pretty`，确认每个角色的 `ai_roles[].role_data.avatar` 为非空 URL（不是资源 ID），`ai_roles[].role_data.voice_id` 为非空 ID（不是 sample_url）
-  5. **重试机制**：任一角色 avatar/voice_id 为空 → 重新读取场景 `updated_at` → 重新生成 patch → 重试 1 次
-  6. **降级处理**：重试后仍失败 → 标注「⚠️ {角色名} 资源匹配未完成」，**不阻断 Part3**，但必须在最终交付摘要中提醒用户手动补充
-- 匹配结果在聊天中只显示一行摘要（如「张总 → 威严中年男性头像 + 沉稳男中音」）
-- 资源匹配完成后再进入 Part3
-- 若角色信息不足以支撑匹配（无姓名/性别/年龄暗示），标注「⚠️ 角色信息不足，无法执行资源匹配」，询问用户补充后再进入 Part3
+  6. **⚠️ avatar/voice_id 验收**：随着 v2.11 资源前置，角色首次 apply 时 `avatar`/`voice_id` 应为真实值。验收时必须确认 avatar 为非空 URL、voice_id 为非空 ID。若个别角色资源匹配失败保留空值，不阻断流程但需在摘要中标注。
+  7. **已知回读异常白名单（v2.20.6）**：若 `preview`/`apply` 已成功，但 `get-scenario` 仍表现为 `ai_roles: []`、`ai_roles_overall_description: null`，且平台实际已展示角色与 OS，则按已知平台回读口径异常记账通过，不再判定失败。
+
+- **只有以下全部满足，才允许进入 Part3**：
+  1. 已生成 `part2-operations.json` 与 `part2-update.json`
+  2. 已执行真实 preview/apply
+  3. 角色逐字段回读验收通过，**或**命中已知回读异常白名单且平台实际已展示
+  4. OS 回读验收通过，**或**命中已知回读异常白名单且平台实际已展示
+- 若任一步失败：立即向用户报错，停止流程，严禁静默进入 Part3
+
+- **头像和语音资源匹配前置（v2.11）**：生成 `part2-operations.json` 之前已完成匹配并写入 avatar/voice_id。若因角色信息不足导致匹配失败，允许该角色保留空值并标注;若 CLI/API 查询失败且是临时性错误，可在 apply 后按 `role-resource-matching.md` 修复流程单独 patch 该角色的 avatar/voice_id
 
 ### Part3:流程设置
 
+优先生成两个文件：
+- `part3-operations.json`：operations 裸数组
+- `part3-update.json`：完整更新请求
+
 先再次获取最新状态:
 
 ```bash
@@ -327,24 +366,38 @@ soke-cli ai-training +get-scenario \
   --pretty
 ```
 
-再预览:
+再预览（默认 request-file 模式）:
 
 ```bash
 soke-cli ai-training +preview-scenario-update \
   --scenario-id <scenario_id> \
-  --base-updated-at <updated_at> \
-  --operations-file ./part3-operations.json \
-  --reason "Part3: 流程设置" \
+  --request-file ./part3-update.json \
   --pretty
 ```
 
-预览通过后立即应用:
+预览通过后立即应用（默认 request-file 模式）:
 
 ```bash
 soke-cli ai-training +apply-scenario-update \
   --scenario-id <scenario_id> \
+  --request-file ./part3-update.json \
+  --pretty
+```
+
+如需排障，再退回 operations 模式：
+
+```bash
+soke-cli ai-training +preview-scenario-update \
+  --scenario-id <scenario_id> \
+  --operations-file ./part3-operations.json \
   --base-updated-at <updated_at> \
+  --reason "Part3: 流程设置" \
+  --pretty
+
+soke-cli ai-training +apply-scenario-update \
+  --scenario-id <scenario_id> \
   --operations-file ./part3-operations.json \
+  --base-updated-at <updated_at> \
   --idempotency-key "cli-<scenario_short>-part3-apply" \
   --reason "Part3: 流程设置" \
   --pretty
@@ -353,10 +406,18 @@ soke-cli ai-training +apply-scenario-update \
 执行要求:
 - 使用最新 `updated_at`
 - 应用成功后更新状态并进入 Part4
-- **apply 后验证**：执行 `soke-cli ai-training +get-scenario --scenario-id <id> --pretty`，确认 `conversation_steps` 非空，`opening_dialogue` 非空，环节数量与 Part3 一致
+- **apply 后验证（v2.20.3）**：执行 `soke-cli ai-training +get-scenario --scenario-id <id> --pretty`。
+  - ✅ `conversation_steps` 非空、`opening_dialogue` 非空 → 直接通过，进入 Part4。
+  - ⚠️ `conversation_steps` 为空，或 `conversation_steps` / `opening_dialogue` 在回读中均未反映，但 `preview` 与 `apply` 已成功 → 视为已知平台回读口径异常，记录到 `state-snapshot.json`，**直接继续 Part4**。
+  - 🔴 仅当 `preview`/`apply` 本身失败，或后续 Part4/Part5 因读取 Part3 平台字段出现明确阻塞证据时，才判定同步失败并回退排查。
+- **若未生成 `part3-operations.json` / `part3-update.json`，或 `preview`/`apply` 根本未成功执行**：立即向用户报错，停止流程，严禁静默进入 Part4
 
 ### Part4:评分标准
 
+优先生成两个文件：
+- `part4-operations.json`：operations 裸数组
+- `part4-update.json`：完整更新请求
+
 先再次获取最新状态:
 
 ```bash
@@ -365,24 +426,38 @@ soke-cli ai-training +get-scenario \
   --pretty
 ```
 
-再预览:
+再预览（默认 request-file 模式）:
 
 ```bash
 soke-cli ai-training +preview-scenario-update \
   --scenario-id <scenario_id> \
-  --base-updated-at <updated_at> \
-  --operations-file ./part4-operations.json \
-  --reason "Part4: 评分标准" \
+  --request-file ./part4-update.json \
   --pretty
 ```
 
-预览通过后立即应用:
+预览通过后立即应用（默认 request-file 模式）:
 
 ```bash
 soke-cli ai-training +apply-scenario-update \
   --scenario-id <scenario_id> \
+  --request-file ./part4-update.json \
+  --pretty
+```
+
+如需排障，再退回 operations 模式：
+
+```bash
+soke-cli ai-training +preview-scenario-update \
+  --scenario-id <scenario_id> \
+  --operations-file ./part4-operations.json \
   --base-updated-at <updated_at> \
+  --reason "Part4: 评分标准" \
+  --pretty
+
+soke-cli ai-training +apply-scenario-update \
+  --scenario-id <scenario_id> \
   --operations-file ./part4-operations.json \
+  --base-updated-at <updated_at> \
   --idempotency-key "cli-<scenario_short>-part4-apply" \
   --reason "Part4: 评分标准" \
   --pretty
@@ -391,12 +466,33 @@ soke-cli ai-training +apply-scenario-update \
 执行要求:
 - 使用最新 `updated_at`
 - apply 成功后**立即验收**：执行 `soke-cli ai-training +get-scenario --scenario-id <id> --raw --pretty`
-- 验证返回结果中评分配置非空（确认 `scoring_criteria` 或等效字段存在且内容完整）
+- 优先验证返回结果中评分配置非空（确认 `scoring_criteria` 或等效字段存在且内容完整）
+- **已知回读异常白名单（v2.20.7）**：若 `preview`/`apply` 已成功，但 `get-scenario` 仍表现为 `scoring_criteria_config: null`，且平台实际已展示评分标准，则按已知平台回读口径异常记账通过，不再判定失败。
 - 验收通过后更新状态并进入 Part5
-- 若验收失败（评分字段缺失或为空），标记为同步异常，排查 `part4-operations.json` 的 `data.config` 结构是否正确
+- 若验收失败（评分字段缺失或为空，且平台侧也未展示），标记为同步异常，排查 `part4-operations.json` 的 `data.config` 结构是否正确
+- **只有以下全部满足，才允许进入 Part5**：
+  1. 已生成 `part4-operations.json` 与 `part4-update.json`
+  2. 已执行真实 preview/apply
+  3. 评分配置回读验收通过，**或**命中已知回读异常白名单且平台实际已展示
+- 若任一步失败：立即向用户报错，停止流程，严禁静默进入 Part5
+
+### 发布前资源闸门
+
+在 Part5 完成后，执行 `publish-gate.md` 做验收。正常流程下封面/头像/声音已在前序 Part 中写入，应直接通过。
+
+若发现资源缺口，按优先级处理：
+1. 能自动补齐的 → 后台自动补齐
+2. 需兜底修复的 → 调用 `resource-finalizer.md`
+3. 无法补齐的 → 停止发布，输出缺口清单
+
+除非失败，不向用户展示补齐细节。
 
 ### Part5:教练设置
 
+优先生成两个文件：
+- `part5-operations.json`：operations 裸数组
+- `part5-update.json`：完整更新请求
+
 先再次获取最新状态:
 
 ```bash
@@ -405,24 +501,38 @@ soke-cli ai-training +get-scenario \
   --pretty
 ```
 
-再预览:
+再预览（默认 request-file 模式）:
 
 ```bash
 soke-cli ai-training +preview-scenario-update \
   --scenario-id <scenario_id> \
-  --base-updated-at <updated_at> \
-  --operations-file ./part5-operations.json \
-  --reason "Part5: 教练设置" \
+  --request-file ./part5-update.json \
   --pretty
 ```
 
-预览通过后立即应用:
+预览通过后立即应用（默认 request-file 模式）:
 
 ```bash
 soke-cli ai-training +apply-scenario-update \
   --scenario-id <scenario_id> \
+  --request-file ./part5-update.json \
+  --pretty
+```
+
+如需排障，再退回 operations 模式：
+
+```bash
+soke-cli ai-training +preview-scenario-update \
+  --scenario-id <scenario_id> \
+  --operations-file ./part5-operations.json \
   --base-updated-at <updated_at> \
+  --reason "Part5: 教练设置" \
+  --pretty
+
+soke-cli ai-training +apply-scenario-update \
+  --scenario-id <scenario_id> \
   --operations-file ./part5-operations.json \
+  --base-updated-at <updated_at> \
   --idempotency-key "cli-<scenario_short>-part5-apply" \
   --reason "Part5: 教练设置" \
   --pretty
@@ -433,6 +543,11 @@ soke-cli ai-training +apply-scenario-update \
 - 应用成功后输出完成摘要
 - **apply 后验证**：执行 `soke-cli ai-training +get-scenario --scenario-id <id> --pretty`，确认练习配置字段（`passing_score`、`pass_difficulty`、`max_practice_attempts`、`completion_rule`、`ai_assistance_enabled` 等）已全部同步
 - 仅在知识库超长或用户明确要求知识包绑定时,追加 `soke-cli ai-training +sync` / `soke-cli ai-training +bind-scenario`
+- **只有以下全部满足，才允许输出完成摘要/进入发布闸门**：
+  1. 已生成 `part5-operations.json` 与 `part5-update.json`
+  2. 已执行真实 preview/apply
+  3. 练习配置字段回读验收通过
+- 若任一步失败：立即向用户报错，停止流程，严禁静默输出“完成创建”或继续发布
 
 ### 微调(optimizer)确认后
 
@@ -443,15 +558,26 @@ soke-cli ai-training +get-scenario \
 
 soke-cli ai-training +preview-scenario-update \
   --scenario-id <scenario_id> \
-  --base-updated-at <updated_at> \
+  --request-file ./optimize-update.json \
+  --pretty
+
+soke-cli ai-training +apply-scenario-update \
+  --scenario-id <scenario_id> \
+  --request-file ./optimize-update.json \
+  --pretty
+
+# 排障时再退回 operations 模式
+soke-cli ai-training +preview-scenario-update \
+  --scenario-id <scenario_id> \
   --operations-file ./optimize-operations.json \
+  --base-updated-at <updated_at> \
   --reason "优化提示词" \
   --pretty
 
 soke-cli ai-training +apply-scenario-update \
   --scenario-id <scenario_id> \
-  --base-updated-at <updated_at> \
   --operations-file ./optimize-operations.json \
+  --base-updated-at <updated_at> \
   --idempotency-key "cli-<scenario_short>-opt-apply" \
   --reason "优化提示词" \
   --pretty
@@ -459,7 +585,7 @@ soke-cli ai-training +apply-scenario-update \
 
 ---
 
-## Part2 operations 结构
+## Part2 operations 结构（默认推荐：逐个 add_ai_role）
 
 ```json
 [
@@ -529,7 +655,7 @@ soke-cli ai-training +apply-scenario-update \
 - 不要把 `knowledge_level` 写成字符串;必须是数组
 - `customized_fields` 应与 `role_data` 中真实写入的自定义字段逐项对齐
 - `created_at` / `updated_at` 建议使用 UTC ISO8601 时间字符串
-- **`avatar` / `voice_id` 在 Part2 阶段留空字符串 `""`**，apply 后由资源匹配流程回填
+- **`avatar` / `voice_id` 在 Part2 阶段必须写入真实值**：生成 `part2-operations.json` 前先执行 `+list-role-avatars` 和 `+list-role-voices` 完成资源匹配。头像和声音不允许在 JSON 中留空 `""`。若某个角色资源匹配失败，允许该角色留空并标注待补，但不能三个角色都留空
 
 ### Part2 replace_ai_roles 自查清单
 
@@ -542,8 +668,8 @@ soke-cli ai-training +apply-scenario-update \
 | 3 | `customization_level` | `"full"`，外层 | 写入 `role_data` 内 |
 | 4 | `is_custom_role` | `true`，外层 | 写入 `role_data` 内 |
 | 5 | `customized_fields` | 外层数组，与 `role_data` 字段逐项对齐 | 写入 `role_data` 内 |
-| 6 | `avatar` | 空 `""` 或头像 URL | 传资源 `id`（如 `cover_ai_role_avatar_001`） |
-| 7 | `voice_id` | 空 `""` 或声音 ID | 传 `sample_url`（如 `...mp3`） |
+| 6 | `avatar` | 头像 URL 或「匹配失败暂时为空」| 多个角色全部为空 |
+| 7 | `voice_id` | 声音 ID 或「匹配失败暂时为空」| 多个角色全部为空 |
 | 8 | `knowledge_level` | 数组 `["专家级"]` | 字符串 `"专家级"` |
 | 9 | `taboos_objections` | 数组 `["禁止A", "禁止B"]` | 单个长字符串 |
 | 10 | `background` | 四段深度画像全文，非空 | `null` 或只写一句话 |
@@ -578,7 +704,7 @@ soke-cli ai-training +apply-scenario-update \
 ]
 ```
 
-> ⚠️ **已知平台 bug**：`add_conversation_step` apply 返回 snapshot_id 但数据不持久化（CLI v1.0.66），`get-scenario` 始终返回空 steps。对话步骤需在 MentorAI Web 管理后台手动补充。
+> ⚠️ **已知平台限制（v2.20.3 修订）**：最新官方指南仍推荐用 `add_conversation_step` / `patch_conversation_step` / `remove_conversation_step` / `reorder_conversation_steps` 维护流程步骤；但当前部分 CLI 版本实测仍可能出现 apply 成功而 `get-scenario` 回读 `conversation_steps` 为空，甚至 `opening_dialogue` 也不及时反映。执行策略应为：先按标准语义操作生成并执行 Part3；若 `get-scenario` 回读异常，**默认按平台回读问题处理并直接续流 Part4**，不再要求用户先去 Web 后台确认。仅当 preview/apply 本身失败，或后续步骤出现明确阻塞证据时才回退排查。严禁因 CLI 回读异常直接阻断流程。
 
 ### Part3 operations 自查清单
 
@@ -745,7 +871,7 @@ soke-cli ai-training +apply-scenario-update \
 |---|---|---|
 | role-profiler 按需画像(仅按需) | Part2 | 已启用按需画像模式,且 Part1 行业/场景描述/角色背景被修改 |
 | 场景类型判定 | Part1 | Part1 标签/行业被修改 |
-| Part2 预览基线 | Part2 前 | 每次进入 Part2 都重新 GET |
+| Part2 预览基线 | Part2 前 | 仅在 `scenario_id` 已成功写入 state-snapshot 后，才允许进入并重新 GET |
 | Part3 预览基线 | Part3 前 | 每次进入 Part3 都重新 GET |
 | Part4 预览基线 | Part4 前 | 每次进入 Part4 都重新 GET |
 | Part5 预览基线 | Part5 前 | 每次进入 Part5 都重新 GET |
@@ -801,7 +927,7 @@ soke-cli ai-training +apply-scenario-update \
 
 > ⚠️ **强制使用**：每次生成 Part JSON 后、preview 前，必须逐段对照此清单，确认每个内容块都已 1:1 复制到对应 JSON 字段。禁止摘要化、禁止改写、禁止遗漏任何一段。
 
-### Part1 → `step1-create.json` 搬运清单
+### Part1 → `part1-create.json` / `step1-create.json` 搬运清单
 
 Part1 输出包含以下内容块，每块都必须映射到 JSON：
 
@@ -814,7 +940,7 @@ Part1 输出包含以下内容块，每块都必须映射到 JSON：
 | 5 | 场景语言 | ☐ | `scene_lang` | 固定写死 `"简体中文"` |
 | 6 | 封面图 CDN URL | ☐ | `scenario_cover` | 已上传封面的 CDN URL |
 
-> **生成后自检命令**：逐条打开 step1-create.json，对照 Part1 确认输出，确保 description 长度与 Part1 场景描述正文长度一致。
+> **生成后自检命令**：逐条打开 `part1-create.json` 或 `step1-create.json`，对照 Part1 确认输出，确保 description 长度与 Part1 场景描述正文长度一致；随后必须执行 `+create-scenario` 并确认拿到 `scenario_id`，否则不得进入 Part2。
 
 ---
 
@@ -847,8 +973,8 @@ Part2 由两大部分组成：**AI角色整体设定（OS）** 和 **具体角
 | B4.1 | 背景四维完整性验证 | ☐ | — | 每个角色的 background 必须包含「我是谁/我的困扰/我的过往经历/我今天的心态」全部四段的完整原文。任一段缺失 → 判定为「维度缺失」，驳回。此检查须在 B4 逐字对齐之前完成。 |
 | B5 | MBTI | ☐ | `role_data.personality_type` | 代码+名称，如 "ISTJ" |
 | B6 | 性格 | ☐ | `role_data.personality` | 原样 |
-| B7 | 头像 | ☐ | `role_data.avatar` | Part2 阶段留空（""），apply 后由资源匹配回填 |
-| B8 | 语音 | ☐ | `role_data.voice_id` | Part2 阶段留空（""），apply 后由资源匹配回填 |
+| B7 | 头像 | ☐ | `role_data.avatar` | 必须在生成 JSON 前查询 `+list-role-avatars` 完成匹配，写真实 URL |
+| B8 | 语音 | ☐ | `role_data.voice_id` | 必须在生成 JSON 前查询 `+list-role-voices` 完成匹配，写真实 ID |
 | B9 | 角色标签 | ☐ | `role_data.tags` | 转为数组 |
 | B10 | 来源类型 | ☐ | `role_data.source_type` | 固定 "custom" |
 | B11 | 知识水平 | ☐ | `role_data.knowledge_level` | 数组，如 ["专家级"] |
@@ -957,6 +1083,7 @@ with open('file.json', 'w', encoding='utf-8') as f:
 | JSON 解析失败 | 手工拼接中文引号/换行 | 用 Python `json.dump(..., ensure_ascii=False, indent=2)` 生成，**禁止 heredoc / echo / cat << 直接写含中文引号（``）的 JSON** |
 | operation type 422 | type 拼错或使用过时 type | 严格使用平台已验证的 type 名 |
 | `replace_conversation_steps` 422 | 平台不接受整包替换流程 | 改用 `add_conversation_step` / `patch_conversation_step` / `remove_conversation_step` / `reorder_conversation_steps` |
+| `add_conversation_step` apply 成功但回读为空 | 当前 CLI 版本存在回读口径差异，实际可能已写入 | 若 preview/apply 成功，则记录回读异常并直接继续 Part4；仅在后续出现明确阻塞证据时才回退排查 |
 | `replace_scoring_criteria_config` 校验失败 | 少了 `data.config` 外层或 `criteria_data` 层级缺失 | 使用 `data.config.criteria_data`，确保 `criteria_data` 直接在 `config` 下且不缺失中间层级 |
 | `step_name` 字段报错 | 写成 `name` | 对话环节字段固定使用 `step_name` |
 | `base_updated_at` 过期 | 并发修改 | 每次 preview/apply 前先 `soke-cli ai-training +get-scenario` |