@sokeai/cli 1.0.76 → 1.0.78

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

@@ -1,1101 +0,0 @@
-# 平台同步引擎
-
-> 内部规则文件,内容不进入用户聊天。负责将 `prompt-engineer` / `prompt-optimizer` 的输出自动映射为 MentorAI 平台 JSON 和 CLI 命令。
-
-> 执行前先对照 `../references/platform-api-pitfalls.md`;当本文件示例、旧经验和真实 CLI 返回冲突时,以踩坑清单和最新实证为准。
-
-> 本文件在被 `interaction.md` 的 QuestionForm 确认选项触发后进入执行。确认即进入 CLI 同步链，不提供二次确认。
-
-> 需要复制标准命令时，优先参考 `../references/verified-cli-cheatsheet.md`；不要从零手写顶层 `soke-cli +...`。
-
-## 核心原则
-
-1. JSON 文件写入工作目录，**严禁在对话中出现任何 `.json` 文件名或路径**；`--request-file` / `--operations-file` 参数中的文件名始终在终端命令中使用，不写入对话窗口
-2. `corp_id` / `user_id` / `created_by` 等身份字段绝对禁止写入请求文件
-3. 字段直接从 Part1-Part5 结构化数据填充，不从自然语言大段反解析
-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。
-
----
-
-## 文件产出规则
-
-| 模式 | 步骤 | 生成文件 | 在聊天中如何出现 |
-|---|---|---|---|
-| 创建型 | 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` + `optimize-update.json` | 优先 `--request-file ./optimize-update.json`；排障时再退回 operations 模式 |
-
-> 创建型默认优先直嵌知识库,不再默认生成 `knowledge-package.json`。只有知识库过大或用户明确要求知识包同步时,才进入 `soke-cli ai-training +sync` / `soke-cli ai-training +bind-scenario` 路径。
-
----
-
-## 字段映射表
-
-### 从 Part1 → `part1-create.json` / `step1-create.json`
-
-> ⚠️ **核心规则：`part1-create.json` 或 `step1-create.json` 的每个字段必须是已确认 Part1 的 1:1 忠实搬运，禁止在此阶段重新缩略、改写、扩写或重组内容。** 用户已确认的是哪个版本的 Part1，JSON 就用哪个版本。
-
-| 提示词取值来源 | JSON 字段 | 类型 | 搬运规则 |
-|---|---|---|---|
-| Part1 场景名称 | `name` | string | 原样照搬，1-100 字符 |
-| Part1 场景描述（全文） | `description` | string | **完整搬运，不缩略不改写**；Part1 \"场景描述\"下的全部正文就是 description 的值 |
-| Part1 标签 | `tags` | string[] | 逐项映射为数组元素，顺序保持一致 |
-| Part1 考核关键点 | `key_points` | string | **必填**，将考核关键点各条拼接为单字符串（分号或编号分隔），不能是数组 |
-| **固定值 `简体中文`** | `scene_lang` | string | **必填，写死 `"简体中文"`，永远不改为其他值**。scene_lang 的取值不随用户语言、场景语种变化，始终固定为简体中文；即使材料中写“中文”“普通话”“zh-CN”或其他表述，创建请求里也只能写 `简体中文` |
-| Part1 行业 | `industry` | string | 如平台字段存在则写入 |
-| Step1 已上传封面 | `scenario_cover` | string | **必填**，先上传封面再创建。封面来源见下方「封面生成与上传」规则 |
-| 已绑定企业 ID | `implementation_corp_id` | string | 若请求体存在该字段也不能依赖其选租户 |
-
-### 从 Part2 → `replace_ai_roles`
-
-> ⚠️ **忠实搬运**：Part2 已确认的角色卡各字段原样映射，不在此阶段修改文案。
-
-> ⚠️ **默认策略变更（v2.8）**：Part2 首次写入默认不要整包 `replace_ai_roles`。应优先按“单角色 `add_ai_role` → 回读验证 → 继续追加下一个角色 → 全部角色完成后再单独 `update_basic` 写 OS”的顺序执行。只有目标平台已被实证验证对整包角色替换稳定时，才允许改回 `replace_ai_roles`。
-
-| 提示词取值来源 | JSON 字段 |
-|---|---|
-| 角色卡.名称 | `ai_roles[].role_data.name` |
-| 角色卡.描述（全文） | `ai_roles[].role_data.description` |
-| 角色卡.头像资源URL（⚠️ 是 `+list-role-avatars` 返回的 `url`，不是 `id`） | `ai_roles[].role_data.avatar` |
-| 角色卡.沟通风格（全文） | `ai_roles[].role_data.communication_style` |
-| 角色卡.背景（直接复制四段深度画像全文，不压缩） | `ai_roles[].role_data.background` |
-| 角色卡.MBTI | `ai_roles[].role_data.personality_type` |
-| 角色卡.性格 | `ai_roles[].role_data.personality` |
-| 角色卡.语音资源ID | `ai_roles[].role_data.voice_id` |
-| 角色卡.标签 | `ai_roles[].role_data.tags` |
-| 角色卡.来源 | `ai_roles[].role_data.source_type` |
-| 角色卡.知识水平 | `ai_roles[].role_data.knowledge_level` |
-| 角色卡.禁忌 | `ai_roles[].role_data.taboos_objections` |
-| Part2 整体设定全文 | `update_basic.ai_roles_overall_description` |
-
-#### ⚠️ 平台外壳字段（外层，与 `role_data` / `scenario_role_id` 同级）
-
-以下字段**不可**写入 `role_data` 内部，否则触发"角色数据异常"：
-
-| 字段 | JSON 路径 | 取值 |
-|------|----------|------|
-| 自定义等级 | `ai_roles[].customization_level` | 固定 `"full"` |
-| 是否自定义角色 | `ai_roles[].is_custom_role` | 固定 `true` |
-| 自定义字段列表 | `ai_roles[].customized_fields` | 与 `role_data` 实际写入字段对应 |
-| 来源类型 | `ai_roles[].source_type` | `"custom"` |
-| 创建时间 | `ai_roles[].created_at` | ISO 8601，建议当前时间 |
-| 更新时间 | `ai_roles[].updated_at` | ISO 8601，与 created_at 相同 |
-
-> 判断规则：描述"角色业务属性"的字段（名称/头像/声音/性格…）→ `role_data` 内；描述"这个角色数据本身的元信息"（自定义等级/来源/时间戳）→ 外层。
-
-> 已实证的 Part2 最小稳定结构:
-> 1. `replace_ai_roles` 可用，但必须使用完整 custom role 外壳，且数据键为 `data.roles`（非 `data.ai_roles`）
-> 2. `ai_roles[].role_data.avatar` 输入必须使用头像资源 **URL**（来自 `+list-role-avatars` 的 `url` 字段，如 `https://newsokeeditorcdn.soke.cn/public/ai/roles_avatars/lnf2.png`），**严禁**使用资源 `id`
-> 3. `ai_roles[].role_data.voice_id` 输入必须使用声音资源 **ID**（来自 `+list-role-voices` 的 `id` 字段）
-> 4. `ai_roles[].role_data.knowledge_level` 必须是 **string[]**,不能写成单个字符串
-> 5. 必须提供 `scenario_role_id`（如 `role_kong_dajie`），便于后续 `patch_ai_role` / `remove_ai_role` 定位——此字段在**外层**，不在 `role_data` 内
-> 6. `customization_level`、`is_custom_role`、`customized_fields`、`source_type`、`created_at`、`updated_at` 在**外层**（与 `role_data` 同级），不可写入 `role_data` 内部，否则角色回读显示"角色数据异常"
-> 7. 若平台对整卡 `replace_ai_roles` 结构仍不稳定,再降级到 `add_ai_role` / `patch_ai_role` 细粒度写入
-
-### 从 Part3 → `conversation_steps` / `update_basic`
-
-> ⚠️ **忠实搬运**：Part3 已确认的每个环节字段原样映射，不在此阶段修改文案。
-
-| 提示词取值来源 | JSON 字段 | 备注 |
-|---|---|---|
-| 开场语（全文） | `update_basic.opening_dialogue` | 原样搬运，不缩略 |
-| 开场语类型 | `update_basic.opening_dialogue_type` | |
-| 环节.环节名 | `add_conversation_step.data.step_name` | 不是 `name` |
-| 环节.学员目标（全文） | `add_conversation_step.data.student_objective` | 原样搬运 |
-| 环节.AI任务（全文） | `add_conversation_step.data.ai_task` | 原样搬运，必须包含环节进入条件 + AI角色行为指令 + 环节退出条件三段 |
-| 环节.最大轮次 | `add_conversation_step.data.max_rounds` | 整数 |
-
-> 已验证:平台不接受 `replace_conversation_steps`,应改用 `add_conversation_step` / `patch_conversation_step` / `remove_conversation_step` / `reorder_conversation_steps`。
-
-### 从 Part4 → `replace_scoring_criteria_config`
-
-> ⚠️ **忠实搬运**：Part4 已确认的评分标准名称、描述、评分维度和一票否决原样映射，不在此阶段改权重、改措辞、改维度数量。
-
-**`config` 层级字段（必填）：**
-
-| 提示词取值来源 | JSON 字段 | 说明 |
-|---|---|---|
-| 评分标准 ID（固定生成） | `data.config.scenario_criteria_id` | 场景内评分标准唯一标识，格式 `criteria_{场景短码}` |
-| **固定值 `"full"`** | `data.config.customization_level` | 纯自定义评分标准固定为 `"full"` |
-| **固定值 `true`** | `data.config.is_custom_criteria` | 纯自定义评分标准固定为 `true` |
-| **固定值 `["criteria_data"]`** | `data.config.customized_fields` | 固定为 `["criteria_data"]` |
-
-**`criteria_data` 层级字段（必填）：**
-
-| 提示词取值来源 | JSON 字段 | 说明 |
-|---|---|---|
-| 评分标准名称 | `data.config.criteria_data.name` | 8-20 字 |
-| 评分标准描述（全文） | `data.config.criteria_data.description` | 完整原文 |
-| **固定值 `"enterprise"`** | `data.config.criteria_data.source_type` | 固定为 `"enterprise"` |
-| **固定值 `100`** | `data.config.criteria_data.total_weight` | 总权重固定为 100 |
-| Part1 标签（取前 4 个） | `data.config.criteria_data.tags` | 数组，关联场景标签 |
-
-**维度层级字段（必填）：**
-
-| 提示词取值来源 | JSON 字段 | 说明 |
-|---|---|---|
-| 维度 ID（固定生成） | `data.config.criteria_data.dimensions[].id` | 格式 `dim_{code}`，用于定位/更新 |
-| 维度.code | `data.config.criteria_data.dimensions[].code` | 英文语义编码 |
-| 维度.名称 | `data.config.criteria_data.dimensions[].name` | 原样 |
-| 维度.描述（全文） | `data.config.criteria_data.dimensions[].description` | 完整原文 |
-| 维度.权重 | `data.config.criteria_data.dimensions[].weight` | 整数 |
-| 维度.评分规则（全文） | `data.config.criteria_data.dimensions[].scoring_rule` | 完整原文，含分档标准和红线 |
-| 维度.评分点列表 | `data.config.criteria_data.dimensions[].criteria[]` | 每条一个元素 |
-| 维度.排序号 | `data.config.criteria_data.dimensions[].sort_order` | 从 1 开始递增 |
-
-> ⚠️ **一票否决已嵌入评分维度**：不再保留全局 `one_vote_veto` 字段。每个维度的一票否决条件直接写入该维度的 `scoring_rule` 字段中（如"以下任一行为触犯即该维度直接0分且总分不合格：…"），由维度自身携带否决规则。
-
-> 已验证:`replace_scoring_criteria_config` 请求要求 `data.config` 包裹，且必须包含 `scenario_criteria_id`、`customization_level`、`is_custom_criteria`、`customized_fields` 四个外壳字段。`criteria_data` 内部需含 `source_type`、`total_weight`、`tags`。每个维度须有 `id` 和 `sort_order`。`criteria_data` 必须被 `config` 直接包裹（`data.config.criteria_data`），不可省略中间层级。缺少任一字段可能导致平台 UI 无法渲染评分配置。
-
-### 从 Part5 → `update_basic`
-
-> ⚠️ **Part5 练习配置已写死**：所有场景统一使用以下固定值，不按场景调整。
-
-| 提示词取值来源 | JSON 字段 | 固定值 | 说明 |
-|---|---|---|---|
-| Part5 练习时间 | `min_practice_duration` / `max_practice_duration` | `0` / `0` | 默认关闭，写死 |
-| Part5 最大练习次数 | `max_practice_attempts` | `10` | 写死 |
-| Part5 通关分数 | `passing_score` | `60` | 写死 |
-| Part5 完成规则 | `completion_rule` | `"all_steps"` | 全环节完成，写死 |
-| Part5 AI助答开关 | `ai_assistance_enabled` | `true` | 开启，写死 |
-| Part5 通关难度 | `pass_difficulty` | `2` | 中，写死 |
-
-> ⚠️ Part5 不再同步收尾话术（`closing_dialogue`）、SOP 流程摘要（`golden_dialogue_description`）、考核关键点摘要（`key_points`）。这些字段已在创建场景（step1-create.json）或其他 Part 中设置，Part5 仅负责练习配置。
-
----
-
-## CLI 命令模板
-
-### Step 1:创建场景
-
-`part1-create.json` 或 `step1-create.json` 必须包含以下字段（全部必填）：
-`name`, `description`, `tags`, `key_points`, `scene_lang`, `scenario_cover`。
-
-示例（完整六字段）：
-
-```json
-{
-  "name": "大自然-展会现场极限沟通",
-  "description": "训练对象：大自然外贸业务员/展会销售代表。业务情境：在国际户外用品展（如ISPO、Outdoor Retailer）的嘈杂展会现场，学员在展位前面对络绎不绝的人流，需要在极致压缩的时间窗口内（通常30秒-3分钟）完成从\"吸引路过客户驻足\"到\"锁定展后跟进\"的全链路沟通。环境噪音大、客户注意力分散、竞争展位环绕，对学员的快速判断力和精准表达能力提出极高要求。训练目标：解决业务员在展会上\"只会发画册、不敢问身份、讲不清核心优势、留不住有效线索\"的通病，训练其在极限条件下完成快速吸引→身份识别→USP推介→留资锁定的完整动作。必须遵守的边界：• 不得泄露其他大客户（特别是国际品牌）的定制新品信息 • 不得在现场贬低同行或隔壁展位 • 不得单向灌输式推销而不了解客户背景 • 留资必须是\"有温度的约定\"而非\"强塞名片\"",
-  "tags": ["展会拓客", "B2B销售", "快速识别", "户外用品", "外贸", "留资转化"],
-  "key_points": "1) 快速吸引与身份识别：能否在3句话内用核心新品/技术让客户驻足，并通过自然提问快速探明对方的品牌背景、采购角色与真实意向，区分水客与大客户；2) 核心卖点精准推介：能否脱口而出硬核差异化数据，用FAB逻辑建立专业信任，而非只塞给客户一本画册；3) 展后跟进锁定：是否准确记录了客户的痛点需求（至少1项），并约定了具体的展后动作——寄样、报价、打样或明确的联系时间；4) 合规红线：全程不泄露其他大客户定制信息、不贬低同行竞品、不做出未经技术评估的产能/交期承诺",
-  "scene_lang": "简体中文",
-  "scenario_cover": "https://newsokeeditorcdn.soke.cn/public/ai/scenario-covers/2026/07/cover_xxx.png"
-}
-```
-
-```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 \
-  --pretty
-```
-
-等价的单独参数模式（排障时可用）：
-
-```bash
-soke-cli ai-training +create-scenario \
-  --name "<场景名称>" \
-  --description "<场景描述>" \
-  --tags "<标签1>,<标签2>" \
-  --key-points "<考核关键点>" \
-  --scene-lang 简体中文 \
-  --scenario-cover "<封面CDN URL>" \
-  --pretty
-```
-
-执行要求:
-- **封面确定规则**：用户确认 Part1 后，在生成 `part1-create.json` 或 `step1-create.json` 前，默认直接写入固定封面 URL：`https://newsokeeditorcdn.soke.cn/public/ai/cover/lingshou_daogou.png`。仅当用户明确指定其他封面、或发布前资源补救流程主动替换时，才允许改用其他 URL。
-- **`key_points` 必须是字符串**，不能是数组；多条用分号或编号拼接
-- **`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` 字段非空且内容与 `part1-create.json` 或 `step1-create.json` 一致。若 `key_points` 为空或缺失，检查创建请求文件中 `key_points` 字段是否为字符串格式
-- **只有创建命令成功 + `scenario_id` 非空 + 创建后验证通过，才允许进入 Part2**
-- 若任一步失败：立即向用户报错，停止流程，严禁静默进入 Part2
-
-### part1-create.json / step1-create.json 自查清单
-
-> ⚠️ 生成 `part1-create.json` 或 `step1-create.json` 后、创建场景前，**必须逐项核对**。
-
-| # | 检查项 | 正确 | 错误示例 |
-|---|---|---|---|
-| 1 | `name` | 场景名称，1-100 字符，非空 | 空字符串 |
-| 2 | `description` | 完整原文，不缩略不改写 | 只写首句或摘要 |
-| 3 | `tags` | **数组** `["标签1", "标签2"]` | 逗号分隔字符串 `"标签1,标签2"` |
-| 4 | `key_points` | **字符串**，分号或编号拼接 | 数组 `["点1", "点2"]` |
-| 5 | `scene_lang` | 固定 `"简体中文"` | 写成 `"zh-CN"` |
-| 6 | `scenario_cover` | 真实的 CDN URL | 占位 URL 或本地路径 |
-| 7 | JSON 写入方式 | Python `json.dump` | shell heredoc / echo |
-
-> 🔴 **#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
-soke-cli ai-training +get-scenario \
-  --scenario-id <scenario_id> \
-  --pretty
-```
-
-再预览（默认 request-file 模式）:
-
-```bash
-soke-cli ai-training +preview-scenario-update \
-  --scenario-id <scenario_id> \
-  --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
-```
-
-执行要求:
-- 使用 `soke-cli ai-training +get-scenario` 返回的最新 `updated_at` 作为 `base_updated_at`
-- 应用成功后刷新并更新 `state-snapshot.json`
-- **apply 后验证**：执行 `soke-cli ai-training +get-scenario --scenario-id <id> --pretty`，逐字段对比验收：
-  1. `ai_roles` 数组长度与 `part2-operations.json` 角色数一致
-  2. 每个角色逐字段内容对比（name/description/communication_style/background/personality_type/personality/tags/knowledge_level/taboos_objections）——与 `part2-operations.json` 对应字段逐字一致。**任一字��不一致 → 判定同步失败，回退检查 JSON 结构后重试。**
-  3. `ai_roles_overall_description` 非空，且前 100 字符与 Part2 OS 原文前 100 字符一致——确保 OS 整体设定完整写入而非丢失
-  4. `role_data.name` ≠ `"角色数据异常"`——若出现此值，检查外壳字段是否误放入 `role_data` 内部
-  5. 每个角色的 `role_data.background` 包含四段深度画像（我是谁/我的困扰/我的过往经历/我今天的心态），四段全部非空
-  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
-soke-cli ai-training +get-scenario \
-  --scenario-id <scenario_id> \
-  --pretty
-```
-
-再预览（默认 request-file 模式）:
-
-```bash
-soke-cli ai-training +preview-scenario-update \
-  --scenario-id <scenario_id> \
-  --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
-```
-
-执行要求:
-- 使用最新 `updated_at`
-- 应用成功后更新状态并进入 Part4
-- **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
-soke-cli ai-training +get-scenario \
-  --scenario-id <scenario_id> \
-  --pretty
-```
-
-再预览（默认 request-file 模式）:
-
-```bash
-soke-cli ai-training +preview-scenario-update \
-  --scenario-id <scenario_id> \
-  --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
-```
-
-执行要求:
-- 使用最新 `updated_at`
-- apply 成功后**立即验收**：执行 `soke-cli ai-training +get-scenario --scenario-id <id> --raw --pretty`
-- 优先验证返回结果中评分配置非空（确认 `scoring_criteria` 或等效字段存在且内容完整）
-- **已知回读异常白名单（v2.20.7）**：若 `preview`/`apply` 已成功，但 `get-scenario` 仍表现为 `scoring_criteria_config: null`，且平台实际已展示评分标准，则按已知平台回读口径异常记账通过，不再判定失败。
-- 验收通过后更新状态并进入 Part5
-- 若验收失败（评分字段缺失或为空，且平台侧也未展示），标记为同步异常，排查 `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
-soke-cli ai-training +get-scenario \
-  --scenario-id <scenario_id> \
-  --pretty
-```
-
-再预览（默认 request-file 模式）:
-
-```bash
-soke-cli ai-training +preview-scenario-update \
-  --scenario-id <scenario_id> \
-  --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
-```
-
-执行要求:
-- 使用最新 `updated_at`
-- 应用成功后输出完成摘要
-- **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)确认后
-
-```bash
-soke-cli ai-training +get-scenario \
-  --scenario-id <scenario_id> \
-  --pretty
-
-soke-cli ai-training +preview-scenario-update \
-  --scenario-id <scenario_id> \
-  --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> \
-  --operations-file ./optimize-operations.json \
-  --base-updated-at <updated_at> \
-  --idempotency-key "cli-<scenario_short>-opt-apply" \
-  --reason "优化提示词" \
-  --pretty
-```
-
----
-
-## Part2 operations 结构（默认推荐：逐个 add_ai_role）
-
-```json
-[
-  {
-    "type": "replace_ai_roles",
-    "data": {
-      "roles": [
-        {
-          "scenario_role_id": "role_doctor_li",
-          "template_id": null,
-          "template_version": null,
-          "template_name": null,
-          "customization_level": "full",
-          "is_custom_role": true,
-          "role_data": {
-            "name": "李振国",
-            "description": "三甲医院骨科主治医师,兼科室合理用药小组成员。",
-            "avatar": "https://newsokeeditorcdn.soke.cn/public/ai/roles_avatars/doctor_male.png",
-            "communication_style": "理性直接,重证据,善用追问。",
-            "background": "长期参与院内药品准入评审,对说明书与循证边界高度敏感。",
-            "personality_type": "ISTJ",
-            "personality": "谨慎、理性、重证据、重流程。",
-            "voice_id": "zh_male_calm_01",
-            "tags": ["骨科", "合理用药", "高合规敏感"],
-            "source_type": "custom",
-            "knowledge_level": ["专家级"],
-            "taboos_objections": [
-              "严禁夸大疗效",
-              "严禁超适应症暗示",
-              "必须完整覆盖禁忌与注意事项"
-            ]
-          },
-          "customized_fields": [
-            "name",
-            "description",
-            "avatar",
-            "communication_style",
-            "background",
-            "personality_type",
-            "personality",
-            "voice_id",
-            "tags",
-            "source_type",
-            "knowledge_level",
-            "taboos_objections"
-          ],
-          "created_at": "2026-07-10T07:40:28Z",
-          "updated_at": "2026-07-10T07:40:28Z"
-        }
-      ]
-    }
-  },
-  {
-    "type": "update_basic",
-    "data": {
-      "ai_roles_overall_description": "..."
-    }
-  }
-]
-```
-
-补充约束:
-- **⚠️ 不要把 `avatar` 写成资源 ID**；必须写头像资源 URL（来自 `+list-role-avatars` 的 `url` 字段）
-- **⚠️ `voice_id` 必须写声音资源 ID**（来自 `+list-role-voices` 的 `id` 字段），不是 `sample_url`
-- **⚠️ `replace_ai_roles` 的数据键是 `data.roles`（非 `data.ai_roles`）**
-- **⚠️ 必须为每个角色提供稳定的 `scenario_role_id`**（如 `role_kong_dajie`），便于后续 `patch_ai_role` / `remove_ai_role`
-- 不要把 `knowledge_level` 写成字符串;必须是数组
-- `customized_fields` 应与 `role_data` 中真实写入的自定义字段逐项对齐
-- `created_at` / `updated_at` 建议使用 UTC ISO8601 时间字符串
-- **`avatar` / `voice_id` 在 Part2 阶段必须写入真实值**：生成 `part2-operations.json` 前先执行 `+list-role-avatars` 和 `+list-role-voices` 完成资源匹配。头像和声音不允许在 JSON 中留空 `""`。若某个角色资源匹配失败，允许该角色留空并标注待补，但不能三个角色都留空
-
-### Part2 replace_ai_roles 自查清单
-
-> ⚠️ 生成 `part2-operations.json` 后、preview 前，**必须逐项核对**。任一项不通过，禁止 preview，必须修正后重检。
-
-| # | 检查项 | 正确 | 错误示例 |
-|---|---|---|---|
-| 1 | `data` 键名 | `"roles"` | `"ai_roles"` |
-| 2 | `scenario_role_id` 存在且在外层 | 与 `role_data` 同级 | 缺失或写入 `role_data` 内 |
-| 3 | `customization_level` | `"full"`，外层 | 写入 `role_data` 内 |
-| 4 | `is_custom_role` | `true`，外层 | 写入 `role_data` 内 |
-| 5 | `customized_fields` | 外层数组，与 `role_data` 字段逐项对齐 | 写入 `role_data` 内 |
-| 6 | `avatar` | 头像 URL 或「匹配失败暂时为空」| 多个角色全部为空 |
-| 7 | `voice_id` | 声音 ID 或「匹配失败暂时为空」| 多个角色全部为空 |
-| 8 | `knowledge_level` | 数组 `["专家级"]` | 字符串 `"专家级"` |
-| 9 | `taboos_objections` | 数组 `["禁止A", "禁止B"]` | 单个长字符串 |
-| 10 | `background` | 四段深度画像全文，非空 | `null` 或只写一句话 |
-| 11 | `template_id/version/name` | `null`，外层 | 非 `null`（自定义角色） |
-| 12 | `created_at` / `updated_at` | UTC ISO8601，外层 | 缺失或格式错误 |
-| 13 | operations 文件格式 | 裸数组 `[{...}]` | 套一层 `{"operations": [...]}` |
-| 14 | JSON 写入方式 | Python `json.dump` | shell heredoc / echo |
-
-> 🔴 **自查不过绝不 preview**。最常见的写入失败根因是 #1（`data.roles` 错写成 `data.ai_roles`），占 80%+ 的 replace_ai_roles 同步失败。
-> 🔴 **外壳字段层级错误**（#2-#5）会导致回读 `name: "角色数据异常"`，全部字段 null。
-
-## Part3 operations 结构
-
-```json
-[
-  {
-    "type": "update_basic",
-    "data": {
-      "opening_dialogue": "...",
-      "opening_dialogue_type": 1
-    }
-  },
-  {
-    "type": "add_conversation_step",
-    "data": {
-      "step_name": "需求摸排",
-      "student_objective": "...",
-      "ai_task": "...",
-      "max_rounds": 5
-    }
-  }
-]
-```
-
-> ⚠️ **已知平台限制（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 自查清单
-
-> ⚠️ 生成 `part3-operations.json` 后、preview 前，**必须逐项核对**。
-
-| # | 检查项 | 正确 | 错误示例 |
-|---|---|---|---|
-| 1 | 开场语 | `update_basic.opening_dialogue`，完整原文 | 只写首句 |
-| 2 | 开场语类型 | `update_basic.opening_dialogue_type`，整数 1 或 2 | 字符串 `"1"` |
-| 3 | 环节字段名 | `step_name`（非 `name`） | `"name": "需求摸排"` |
-| 4 | 学员目标 | `student_objective`，完整原文 | 只写标题 |
-| 5 | AI 任务 | `ai_task`，完整原文含进入/退出条件 | 只写概括 |
-| 6 | 最大轮次 | `max_rounds`，整数 1-50 | 字符串 `"5"` |
-| 7 | 环节数量 | `add_conversation_step` 操作数 = Part3 环节数 | 漏掉某个环节 |
-| 8 | operations 文件格式 | 裸数组 `[{...}]` | 套一层 `{"operations": [...]}` |
-
-> 🔴 **#2 类型错误**：`opening_dialogue_type` 必须是整数，不能是字符串 `"1"` 或 `"customer_first"`。
-> 🔴 **#5 内容截断**：`ai_task` 被缩略后平台环节信息不完整，学员端看不到完整 AI 行为指令。
-
-## Part4 operations 结构
-
-```json
-[
-  {
-    "type": "replace_scoring_criteria_config",
-    "data": {
-      "config": {
-        "scenario_criteria_id": "criteria_phone_appointment",
-        "customization_level": "full",
-        "is_custom_criteria": true,
-        "criteria_data": {
-          "name": "电话约访能力评分标准",
-          "description": "本评分标准用于评估学员在电话约访场景中的综合表现……",
-          "source_type": "enterprise",
-          "dimensions": [
-            {
-              "id": "dim_ice_breaking",
-              "code": "ice_breaking",
-              "name": "破冰与信任建立",
-              "description": "评估学员在通话开场能否快速建立信任……",
-              "weight": 25,
-              "scoring_rule": "满分25分。1-3分：开场生硬…… 4-6分：有基本自我介绍…… 7-10分：自然破冰……",
-              "criteria": ["评分点1", "评分点2"],
-              "sort_order": 1
-            }
-          ],
-          "tags": ["电话约访", "银行", "客户经理"],
-          "total_weight": 100
-        },
-        "customized_fields": ["criteria_data"]
-      }
-    }
-  }
-]
-```
-补充约束：
-- **⚠️ `data.config` 三层嵌套**：`data.config.criteria_data`，不可跳过 `config` 层
-- **⚠️ config 外壳字段必填**：`scenario_criteria_id`、`customization_level`（`"full"`）、`is_custom_criteria`（`true`）、`customized_fields`（`["criteria_data"]`）缺少任一 → API apply 成功但 UI 不显示
-- **⚠️ criteria_data 元数据字段必填**：`source_type`（`"enterprise"`）、`total_weight`（`100`）、`tags`（数组，取 Part1 标签前 4 个）缺少任一 → 数据存储但 UI 不完整
-- **⚠️ 维度必填字段**：`id`（格式 `dim_{code}`）、`sort_order`（从 1 递增）；所有权重之和 = 100
-- **⚠️ 一票否决嵌入维度**：不再使用全局 `one_vote_veto`，改为写入每个维度的 `scoring_rule` 中
-
-### Part4 replace_scoring_criteria_config 自查清单
-
-> ⚠️ 生成 `part4-operations.json` 后、preview 前，**必须逐项核对**。任一项不通过，禁止 preview，必须修正后重检。
-
-| # | 检查项 | 正确 | 错误示例 |
-|---|---|---|---|
-| 1 | 层级嵌套 | `data.config.criteria_data` | `data.criteria_data`（少了 config 层） |
-| 2 | `scenario_criteria_id` | `config` 下，格式 `criteria_{场景短码}` | 缺失或放错层级 |
-| 3 | `customization_level` | `"full"`，`config` 下 | 缺失或放 `criteria_data` 内 |
-| 4 | `is_custom_criteria` | `true`，`config` 下 | 缺失或放 `criteria_data` 内 |
-| 5 | `customized_fields` | `["criteria_data"]`，`config` 下 | 缺失或写成空数组 |
-| 6 | `criteria_data.source_type` | `"enterprise"` | 缺失 |
-| 7 | `criteria_data.total_weight` | `100` | 缺失或与实际维度权重和不一致 |
-| 8 | `criteria_data.tags` | 数组，取 Part1 标签前 4 个 | 缺失或写成字符串 |
-| 9 | 每个维度有 `id` | `dim_{code}` 格式 | 缺失 |
-| 10 | 每个维度有 `sort_order` | 从 1 递增 | 缺失或重复 |
-| 11 | 权重之和 | 所有维度 `weight` 相加 = 100 | 不等于 100 |
-| 12 | 一票否决 | 嵌入各维度 `scoring_rule` 末尾 | 使用全局 `one_vote_veto` 字段 |
-| 13 | operations 文件格式 | 裸数组 `[{...}]` | 套一层 `{"operations": [...]}` |
-
-> 🔴 **#1 是最高频错误**：`criteria_data` 直接放 `data` 下，漏掉 `config` 包裹层，导致 `必须提供 config` 校验失败。
-> 🔴 **#2-#5 外壳字段缺失**：API apply 返回成功但平台 UI 不渲染，静默失败。
-
-## Part5 operations 结构
-
-> ⚠️ **全部写死**：以下固定值适用于所有场景，生成 `part5-operations.json` 时直接复制此结构，不做任何修改。
-
-```json
-[
-  {
-    "type": "update_basic",
-    "data": {
-      "min_practice_duration": 0,
-      "max_practice_duration": 0,
-      "max_practice_attempts": 10,
-      "passing_score": 60,
-      "pass_difficulty": 2,
-      "completion_rule": "all_steps",
-      "ai_assistance_enabled": true
-    }
-  }
-]
-```
-
-> `min_practice_duration` / `max_practice_duration` 为 0 表示练习时间默认关闭。
-
-### Part5 operations 自查清单
-
-> ⚠️ 生成 `part5-operations.json` 后、preview 前，**必须逐项核对**。Part5 全部写死，任何值与固定模板不一致必须驳回。
-
-| # | 检查项 | 固定值 | 错误示例 |
-|---|---|---|---|
-| 1 | `min_practice_duration` | `0` | `null` 或不传 |
-| 2 | `max_practice_duration` | `0` | `null` 或不传 |
-| 3 | `max_practice_attempts` | `10` | `5`（被调整） |
-| 4 | `passing_score` | `60` | `80`（被调整） |
-| 5 | `pass_difficulty` | `2` | `1` 或 `3`（被调整） |
-| 6 | `completion_rule` | `"all_steps"` | `"score_based"` |
-| 7 | `ai_assistance_enabled` | `true` | `false` |
-| 8 | 不含额外字段 | 仅含上述 7 项 | 混入 `closing_dialogue`/`key_points`/`golden_dialogue_description` |
-| 9 | operations 文件格式 | 裸数组 `[{...}]` | 套一层 `{"operations": [...]}` |
-
-> 🔴 **#8 字段污染**：Part5 混入收尾话术、SOP 摘要或考核关键点（这些已在 Part1/Part3 同步），重复写入可能导致覆盖或冲突。
-
----
-
-## 状态快照
-
-创建型内部使用,不在聊天中输出。每个 Part 成功后更新。
-
-```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": ""
-  }
-}
-```
-
-### 缓存规则
-
-| 缓存项 | 生成时机 | 重跑条件 |
-|---|---|---|
-| role-profiler 按需画像(仅按需) | Part2 | 已启用按需画像模式,且 Part1 行业/场景描述/角色背景被修改 |
-| 场景类型判定 | Part1 | Part1 标签/行业被修改 |
-| Part2 预览基线 | Part2 前 | 仅在 `scenario_id` 已成功写入 state-snapshot 后，才允许进入并重新 GET |
-| Part3 预览基线 | Part3 前 | 每次进入 Part3 都重新 GET |
-| Part4 预览基线 | Part4 前 | 每次进入 Part4 都重新 GET |
-| Part5 预览基线 | Part5 前 | 每次进入 Part5 都重新 GET |
-
-### 依赖与回滚规则
-
-- Part1 修改后,默认视为 Part2-Part5 全部待复核
-- Part2 修改后,至少重检 Part3 与 Part5
-- Part3 修改后,至少重检 Part4 与 Part5
-- Part4 修改后,重检 Part5
-- Part5 修改通常不反推前序 Part,但若改动通关分数/难度，需检查是否与 Part4 评分体系一致
-
----
-
-## 一致性扫描
-
-每个 Part 确认后自动执行。无告警不在聊天中输出;有告警才提示。
-
-### Part2 扫描项
-
-- 若启用了 `role-profiler`,检查按需画像是否与 Part1 行业、场景类型一致;未启用则直接检查角色卡与 Part1 是否一致
-- 每个 AI 角色的 `taboos_objections` 是否完整、可执行、非空话
-- 角色整体设定是否与信息释放规则、口语化要求一致
-- **⚠️ background 四维完整性**：每个角色的 background 是否复制了四段深度画像的全部完整原文（我是谁/我的困扰/我的过往经历/我今天的心态）。缺少任一段 → 告警「⚠️ {角色名} background 维度缺失：缺少[维度名]」，驳回重新补充
-- **⚠️ background 展示对齐**：JSON 中的 `role_data.background` 是否与 Part2 确认弹窗中展示的「角色背景」文本逐字一致。不一致 → 告警「⚠️ {角色名} background 与展示文本不一致」，驳回重新对齐
-
-### Part3 扫描项
-
-- Part1 key_points 是否全部在 Part3 学员目标中有对应环节
-- 每个 AI 角色的 `taboos_objections` 是否在 Part3 AI 任务中有触发逻辑
-- `opening_dialogue` 是否与 Part2 的信息释放规则一致
-- 所有环节是否都包含 `step_name` / `student_objective` / `ai_task` / `max_rounds`
-
-### Part4 扫描项
-
-- 评分标准名称是否已输出（非空，8-20 字）
-- 评分标准描述是否已输出（完整原文，非空）
-- Part4 评分维度是否与 Part1 key_points 一一对应
-- Part4 总权重是否等于 100
-- 每个维度 `scoring_rule` 中是否包含一票否决条件（如"以下行为触犯即该维度0分且总分不合格"）
-- 评分描述是否能映射到 Part3 的可观察行为
-- `criteria_data` 是否直接位于 `config` 下（`data.config.criteria_data`），中间无缺失层级
-
-### Part5 扫描项
-
-- Part5 operations 是否仅包含练习配置（不含收尾话术、SOP 摘要、考核关键点摘要）
-- 所有练习配置值是否与固定模板完全一致：练习时间默认关闭（`min_practice_duration`=0, `max_practice_duration`=0）、`max_practice_attempts`=10、`passing_score`=60、`completion_rule`="all_steps"、`ai_assistance_enabled`=true、`pass_difficulty`=2
-- 若任何值与固定模板不一致 → 告警「⚠️ Part5 配置值与固定模板不一致」，驳回修正
-
----
-
-## 逐 Part 内容搬运检查清单
-
-> ⚠️ **强制使用**：每次生成 Part JSON 后、preview 前，必须逐段对照此清单，确认每个内容块都已 1:1 复制到对应 JSON 字段。禁止摘要化、禁止改写、禁止遗漏任何一段。
-
-### Part1 → `part1-create.json` / `step1-create.json` 搬运清单
-
-Part1 输出包含以下内容块，每块都必须映射到 JSON：
-
-| # | Part1 内容块 | 检查项 | JSON 字段 | 搬运要求 |
-|---|------------|--------|-----------|---------|
-| 1 | 场景名称 | ☐ | `name` | 原样搬运，一字不改 |
-| 2 | 标签列表 | ☐ | `tags` | 逐项转为数组元素，顺序一致 |
-| 3 | 场景描述（全文） | ☐ | `description` | 完整搬运，包括训练对象/业务情境/训练目标/边界条件，不缩略一字 |
-| 4 | 考核关键点（全文） | ☐ | `key_points` | 拼接为单字符串，分号或编号分隔，不能是数组 |
-| 5 | 场景语言 | ☐ | `scene_lang` | 固定写死 `"简体中文"` |
-| 6 | 封面图 CDN URL | ☐ | `scenario_cover` | 已上传封面的 CDN URL |
-
-> **生成后自检命令**：逐条打开 `part1-create.json` 或 `step1-create.json`，对照 Part1 确认输出，确保 description 长度与 Part1 场景描述正文长度一致；随后必须执行 `+create-scenario` 并确认拿到 `scenario_id`，否则不得进入 Part2。
-
----
-
-### Part2 → `part2-operations.json` 搬运清单
-
-Part2 由两大部分组成：**AI角色整体设定（OS）** 和 **具体角色卡**。两部分都必须 1:1 复制。
-
-#### A 部分：AI角色整体设定（OS）→ `update_basic`
-
-| # | Part2 OS 内容块 | 检查项 | JSON 字段 | 搬运要求 |
-|---|---------------|--------|-----------|---------|
-| A1 | 核心输出协议（全文） | ☐ | `update_basic.ai_roles_overall_description` | 全文包含：禁止括号动作、纯净口语输出、舌象格式、信息挤牙膏原则——四段全部搬运，一字不减 |
-| A2 | 核心身份定义 | ☐ | `update_basic.ai_roles_overall_description`（追加） | 完整 System Role 描述 |
-| A3 | 核心铁律 | ☐ | `update_basic.ai_roles_overall_description`（追加） | 全局规则全文 |
-| A4 | 内核运行机制（全文） | ☐ | `update_basic.ai_roles_overall_description`（追加） | 含：动态状态机(Trust_Level/Patience_Gauge/Fact_Anchoring)、双层逻辑处理、行为模拟规范(语言熵增/心理防御/环境干扰)、信息过载与回旋机制 |
-| A5 | 知识库与合规约束（全文） | ☐ | `update_basic.ai_roles_overall_description`（追加） | 含：禁语与红线、行业常识 |
-| A6 | 业务场景专属规则模板库（全文） | ☐ | `update_basic.ai_roles_overall_description`（追加） | 含：生理反应静默原则、术语屏蔽原则、口感中立原则……等全部已选用的规则 |
-| A7 | 关键结束规则 | ☐ | `update_basic.ai_roles_overall_description`（追加） | Meta-Rule for Ending 全文 |
-
-> ⚠️ **OS 搬运关键**：`ai_roles_overall_description` 是一个字符串字段。必须将 A1-A7 全部内容拼接为**完整长文本**写入，严禁只写"参见 Part2 整体设定"或做任何形式的摘要。**目标：这份 JSON 能在平台重建完整的 OS。**
-
-#### B 部分：具体角色卡 → `replace_ai_roles`
-
-| # | 角色卡字段 | 检查项 | JSON 字段 | 搬运要求 |
-|---|-----------|--------|-----------|---------|
-| B1 | 角色名称 | ☐ | `role_data.name` | 原样 |
-| B2 | 角色描述 | ☐ | `role_data.description` | 原样全文（年龄、职业、外貌、生活状态） |
-| B3 | 沟通风格 | ☐ | `role_data.communication_style` | 原样全文 |
-| B4 | 角色背景（直接复制四段全文） | ☐ | `role_data.background` | **⚠️ 强制逐字对齐**：JSON 中的 background 文本必须与 Part2 确认弹窗中展示的「角色背景」文本逐字一致（含标点、措辞、空格）。不得在 JSON 生成阶段重新缩略、改写、或替换措辞。违反此项 → 驳回，必须在修正后重新预览。 |
-| B4.1 | 背景四维完整性验证 | ☐ | — | 每个角色的 background 必须包含「我是谁/我的困扰/我的过往经历/我今天的心态」全部四段的完整原文。任一段缺失 → 判定为「维度缺失」，驳回。此检查须在 B4 逐字对齐之前完成。 |
-| B5 | MBTI | ☐ | `role_data.personality_type` | 代码+名称，如 "ISTJ" |
-| B6 | 性格 | ☐ | `role_data.personality` | 原样 |
-| 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` | 数组，如 ["专家级"] |
-| B12 | 角色禁忌 | ☐ | `role_data.taboos_objections` | 转为数组，每条一个元素 |
-| B13 | 完整 custom role 外壳 | ☐ | `scenario_role_id` / `customization_level` / `is_custom_role` / `customized_fields` / `created_at` / `updated_at` | 按已验证结构完整写入 |
-
-> **生成后自检命令**：读完 part2-operations.json，确认 `ai_roles_overall_description` 字符串包含 Part2 OS 全部 A1-A7 内容（通过字数比对：OS 原文约 X 字，JSON 中该字段字数也应接近 X）；确认每个角色卡 B1-B13 全部有值（B7/B8 除外）；**⚠️ 逐字比对每个角色的 `role_data.background` 与 Part2 展示文本是否完全一致**，同时执行 B4.1 四维完整性检查（我是谁/我的困扰/我的过往经历/我今天的心态）。
-
----
-
-### Part3 → `part3-operations.json` 搬运清单
-
-| # | Part3 内容块 | 检查项 | JSON 字段 | 搬运要求 |
-|---|------------|--------|-----------|---------|
-| 1 | 开场引导语（全文） | ☐ | `update_basic.opening_dialogue` | 完整原文，一字不改 |
-| 2 | 开场语类型 | ☐ | `update_basic.opening_dialogue_type` | 数字 1 或 2 |
-| 3 | 环节1: 环节名 | ☐ | `add_conversation_step.data.step_name` | 原样，注意字段名是 `step_name` |
-| 4 | 环节1: 学员目标（全文） | ☐ | `add_conversation_step.data.student_objective` | 完整原文，一字不改 |
-| 5 | 环节1: AI任务（全文） | ☐ | `add_conversation_step.data.ai_task` | 完整原文，含环节进入条件 + IF-THEN 逻辑 + 环节退出条件，一字不改 |
-| 6 | 环节1: 最大轮次 | ☐ | `add_conversation_step.data.max_rounds` | 整数 |
-| 7-N | 环节2-N: 同上 4 项 | ☐ | 同环节1结构 | 每环节一个 `add_conversation_step` 操作 |
-
-> **生成后自检命令**：JSON 中 `add_conversation_step` 操作数量 = Part3 环节数；每个环节的 `student_objective` 和 `ai_task` 长度与 Part3 原文一致；`opening_dialogue` 长度与 Part3 开场语一致。
-
----
-
-### Part4 → `part4-operations.json` 搬运清单
-
-> **生成顺序**：评分标准名称 → 评分标准描述 → 然后才是各评分维度。
-
-| # | Part4 内容块 | 检查项 | JSON 字段 | 搬运要求 |
-|---|------------|--------|-----------|---------|
-| 0a | **评分标准 ID** | ☐ | `config.scenario_criteria_id` | 固定生成，格式 `criteria_{场景短码}` |
-| 0b | **customization_level** | ☐ | `config.customization_level` | 固定写死 `"full"` |
-| 0c | **is_custom_criteria** | ☐ | `config.is_custom_criteria` | 固定写死 `true` |
-| 0d | **评分标准名称** | ☐ | `config.criteria_data.name` | 原样，8-20 字 |
-| 0e | **评分标准描述（全文）** | ☐ | `config.criteria_data.description` | 完整原文，一字不改 |
-| 0f | **source_type** | ☐ | `config.criteria_data.source_type` | 固定写死 `"enterprise"` |
-| 0g | **total_weight** | ☐ | `config.criteria_data.total_weight` | 固定写死 `100` |
-| 0h | **tags** | ☐ | `config.criteria_data.tags` | 取 Part1 标签前 4 个 |
-| 0i | **customized_fields** | ☐ | `config.customized_fields` | 固定写死 `["criteria_data"]` |
-| 1 | 维度1: ID | ☐ | `config.criteria_data.dimensions[0].id` | 格式 `dim_{code}` |
-| 2 | 维度1: 名称 | ☐ | `config.criteria_data.dimensions[0].name` | 原样 |
-| 3 | 维度1: code | ☐ | `config.criteria_data.dimensions[0].code` | 英文 code |
-| 4 | 维度1: 描述（全文） | ☐ | `config.criteria_data.dimensions[0].description` | 完整原文，一字不改 |
-| 5 | 维度1: 权重 | ☐ | `config.criteria_data.dimensions[0].weight` | 整数 |
-| 6 | 维度1: 评分规则（全文） | ☐ | `config.criteria_data.dimensions[0].scoring_rule` | 完整原文，含分档标准和红线描述 |
-| 7 | 维度1: 评分点列表 | ☐ | `config.criteria_data.dimensions[0].criteria[]` | 每条一个元素 |
-| 8 | 维度1: 排序号 | ☐ | `config.criteria_data.dimensions[0].sort_order` | 从 1 开始递增 |
-| 9-N | 维度2-N: 同上 8 项 | ☐ | 同维度1结构 | 每维度独立 |
-| 10 | 权重之和 | ☐ | — | 所有维度 weight 求和 = 100 |
-
-> **生成后自检命令**：JSON 中维度数 = Part4 维度数；检查 `scenario_criteria_id`、`customization_level`、`is_custom_criteria`、`customized_fields`、`source_type`、`total_weight`、`tags` 是否齐全；随机抽查 1-2 个维度的 `id` 和 `sort_order` 是否存在；确认 `data.config.criteria_data` 层级完整无缺失；确认不再包含全局 `one_vote_veto` 字段（一票否决规则已嵌入各维度 `scoring_rule`）。
-
----
-
-### Part5 → `part5-operations.json` 搬运清单
-
-> ⚠️ **全部写死**：以下 7 项均为固定值，生成 JSON 时直接使用，不做任何调整。
-
-| # | Part5 内容块 | 固定值 | JSON 字段 | 搬运要求 |
-|---|------------|--------|-----------|---------|
-| 1 | 练习时间 | **默认关闭** | `update_basic.min_practice_duration` / `update_basic.max_practice_duration` | 写死 0 / 0 |
-| 2 | 最大练习次数 | **10** | `update_basic.max_practice_attempts` | 写死 10 |
-| 3 | 通关分数 | **60** | `update_basic.passing_score` | 写死 60 |
-| 4 | 完成规则 | **all_steps** | `update_basic.completion_rule` | 写死 "all_steps" |
-| 5 | AI助答开关 | **true** | `update_basic.ai_assistance_enabled` | 开启，写死 true |
-| 6 | 通关难度 | **2** | `update_basic.pass_difficulty` | 中，写死 2 |
-
-> **生成后自检命令**：逐项核对 `part5-operations.json` 中每个字段值是否与上表固定值完全一致（特别是 `min_practice_duration`/`max_practice_duration` 必须为 0 表示默认关闭、`passing_score` 必须为 60）。确认不含收尾话术、SOP 摘要或考核关键点摘要。
-
----
-
-## 跨 Part 内容交接规则
-
-### Part2 行为模式 → Part3 参考（不写入 JSON）
-
-Part2 角色卡中的「我的行为模式」（共鸣触发/关键台词/防御机制/决策逻辑）标记为 "Part3 素材，不写入 Part2 JSON"。这部分内容在 Part3 生成 AI 任务时作为参考输入，但不需逐字写入 part3-operations.json。
-
----
-
-## JSON 生成硬约束
-
-所有 JSON 文件（`step1-create.json`、`part2-operations.json` 等）必须通过以下方式生成：
-
-```python
-python3 -c "
-import json
-data = ...  # 构建数据结构
-with open('file.json', 'w', encoding='utf-8') as f:
-    json.dump(data, f, ensure_ascii=False, indent=2)
-"
-```
-
-**禁止的方式：**
-- ❌ shell heredoc（`cat > file.json << 'EOF'`）——含中文引号 `""` 时会触发 `invalid character` 错误
-- ❌ shell echo 拼接——引号逃逸不可控
-- ❌ 手工粘贴到编辑器——空格/换行不一致
-
-**原因：** 中文双引号 `""`（U+201C/U+201D）在 shell 中被误解析为语法结构，唯一可靠的方式是 Python `json.dump` 单步写入。
-
-## 编码与错误处理
-
-| 问题 | 原因 | 解决方法 |
-|---|---|---|
-| 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` |
-| 学员端看不到步骤 | 仅更新 `conversation_steps` 不够 | 将 SOP 摘要同步写入 `golden_dialogue_description` 和 `key_points` |
-| 角色数据异常 | `replace_ai_roles` 缺少完整 custom role 外壳，或 `data` 键用了 `ai_roles` 而非 `roles`，或 `avatar`/`knowledge_level`/`customized_fields` 结构不符 | 优先改成已验证结构：`data.roles` 键、`avatar` 用头像资源 URL（`+list-role-avatars` 的 `url` 字段）、`knowledge_level` 用数组、补齐 `scenario_role_id`/`customization_level`/`is_custom_role`/`customized_fields`/时间戳；仍失败再拆成 `add_ai_role`/`patch_ai_role` |
-| 评分标准 UI 不渲染 | `criteria_data` 内缺少 `source_type`/`total_weight`/`tags`，或维度缺少 `id`/`sort_order` | 补齐 criteria_data 内部元数据字段和维度 ID/排序号 |
-| 头像回填后平台不显示 | `patch_ai_role` 中缺少 `customized_fields`，或 `avatar` 用了资源 ID 而非 URL | 确认 patch 中包含 `"customized_fields": ["avatar"]`；确认 avatar 值为 `+list-role-avatars` 返回的 `url` 字段 |
-
----
-
-## 与 interaction.md 的边界
-
-- `interaction.md` 负责:弹窗确认、按钮分支、回退链路
-- `sync-engine.md` 负责:确认后的 JSON 生成、CLI 执行、状态快照更新
-- interaction 确认后调用 sync-engine 对应模板,sync-engine 执行完成后回到 interaction 继续下一 Part