@sokeai/cli 1.0.66 → 1.0.68

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

@@ -0,0 +1,974 @@
+# 平台同步引擎
+
+> 内部规则文件,内容不进入用户聊天。负责将 `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 文件写入工作目录，只在 CLI 命令中通过文件名自然出现，不单独提示"已生成文件"
+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` 重试即可
+
+---
+
+## 文件产出规则
+
+| 模式 | 步骤 | 生成文件 | 在聊天中如何出现 |
+|---|---|---|---|
+| 创建型 | 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` |
+| 创建型 | 全流程 | `state-snapshot.json` | 完全不在聊天中出现 |
+| 微调 | 唯一 | `optimize-operations.json` | CLI 命令中 `--operations-file ./optimize-operations.json` |
+
+> 创建型默认优先直嵌知识库,不再默认生成 `knowledge-package.json`。只有知识库过大或用户明确要求知识包同步时,才进入 `soke-cli ai-training +sync` / `soke-cli ai-training +bind-scenario` 路径。
+
+---
+
+## 字段映射表
+
+### 从 Part1 → `step1-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 的取值不随用户语言、场景语种变化，始终固定为简体中文 |
+| Part1 行业 | `industry` | string | 如平台字段存在则写入 |
+| Step1 已上传封面 | `scenario_cover` | string | **必填**，先上传封面再创建。封面来源见下方「封面生成与上传」规则 |
+| 已绑定企业 ID | `implementation_corp_id` | string | 若请求体存在该字段也不能依赖其选租户 |
+
+### 从 Part2 → `replace_ai_roles`
+
+> ⚠️ **忠实搬运**：Part2 已确认的角色卡各字段原样映射，不在此阶段修改文案。
+
+| 提示词取值来源 | 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:创建场景
+
+`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 ./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 后，在创建场景前必须先完成封面生成和上传：
+  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`
+- **`key_points` 必须是字符串**，不能是数组；多条用分号或编号拼接
+- **`scene_lang` 固定为 `"简体中文"`**，永远不改为其他值
+- **`tags` 必须是数组**，不能是逗号分隔字符串
+- 自动从返回结果提取 `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,不等待用户回传
+
+### step1-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 写死**：永远不随场景语言变化，始终 `"简体中文"`。
+
+### Part2:AI角色设定
+
+先获取最新场景状态:
+
+```bash
+soke-cli ai-training +get-scenario \
+  --scenario-id <scenario_id> \
+  --pretty
+```
+
+再预览:
+
+```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角色设定" \
+  --pretty
+```
+
+预览通过后立即应用:
+
+```bash
+soke-cli ai-training +apply-scenario-update \
+  --scenario-id <scenario_id> \
+  --base-updated-at <updated_at> \
+  --operations-file ./part2-operations.json \
+  --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 首次验收不检查**：角色首次 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
+
+### Part3:流程设置
+
+先再次获取最新状态:
+
+```bash
+soke-cli ai-training +get-scenario \
+  --scenario-id <scenario_id> \
+  --pretty
+```
+
+再预览:
+
+```bash
+soke-cli ai-training +preview-scenario-update \
+  --scenario-id <scenario_id> \
+  --base-updated-at <updated_at> \
+  --operations-file ./part3-operations.json \
+  --reason "Part3: 流程设置" \
+  --pretty
+```
+
+预览通过后立即应用:
+
+```bash
+soke-cli ai-training +apply-scenario-update \
+  --scenario-id <scenario_id> \
+  --base-updated-at <updated_at> \
+  --operations-file ./part3-operations.json \
+  --idempotency-key "cli-<scenario_short>-part3-apply" \
+  --reason "Part3: 流程设置" \
+  --pretty
+```
+
+执行要求:
+- 使用最新 `updated_at`
+- 应用成功后更新状态并进入 Part4
+- **apply 后验证**：执行 `soke-cli ai-training +get-scenario --scenario-id <id> --pretty`，确认 `conversation_steps` 非空，`opening_dialogue` 非空，环节数量与 Part3 一致
+
+### Part4:评分标准
+
+先再次获取最新状态:
+
+```bash
+soke-cli ai-training +get-scenario \
+  --scenario-id <scenario_id> \
+  --pretty
+```
+
+再预览:
+
+```bash
+soke-cli ai-training +preview-scenario-update \
+  --scenario-id <scenario_id> \
+  --base-updated-at <updated_at> \
+  --operations-file ./part4-operations.json \
+  --reason "Part4: 评分标准" \
+  --pretty
+```
+
+预览通过后立即应用:
+
+```bash
+soke-cli ai-training +apply-scenario-update \
+  --scenario-id <scenario_id> \
+  --base-updated-at <updated_at> \
+  --operations-file ./part4-operations.json \
+  --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` 或等效字段存在且内容完整）
+- 验收通过后更新状态并进入 Part5
+- 若验收失败（评分字段缺失或为空），标记为同步异常，排查 `part4-operations.json` 的 `data.config` 结构是否正确
+
+### Part5:教练设置
+
+先再次获取最新状态:
+
+```bash
+soke-cli ai-training +get-scenario \
+  --scenario-id <scenario_id> \
+  --pretty
+```
+
+再预览:
+
+```bash
+soke-cli ai-training +preview-scenario-update \
+  --scenario-id <scenario_id> \
+  --base-updated-at <updated_at> \
+  --operations-file ./part5-operations.json \
+  --reason "Part5: 教练设置" \
+  --pretty
+```
+
+预览通过后立即应用:
+
+```bash
+soke-cli ai-training +apply-scenario-update \
+  --scenario-id <scenario_id> \
+  --base-updated-at <updated_at> \
+  --operations-file ./part5-operations.json \
+  --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`
+
+### 微调(optimizer)确认后
+
+```bash
+soke-cli ai-training +get-scenario \
+  --scenario-id <scenario_id> \
+  --pretty
+
+soke-cli ai-training +preview-scenario-update \
+  --scenario-id <scenario_id> \
+  --base-updated-at <updated_at> \
+  --operations-file ./optimize-operations.json \
+  --reason "优化提示词" \
+  --pretty
+
+soke-cli ai-training +apply-scenario-update \
+  --scenario-id <scenario_id> \
+  --base-updated-at <updated_at> \
+  --operations-file ./optimize-operations.json \
+  --idempotency-key "cli-<scenario_short>-opt-apply" \
+  --reason "优化提示词" \
+  --pretty
+```
+
+---
+
+## Part2 operations 结构
+
+```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 阶段留空字符串 `""`**，apply 后由资源匹配流程回填
+
+### 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 | 传资源 `id`（如 `cover_ai_role_avatar_001`） |
+| 7 | `voice_id` | 空 `""` 或声音 ID | 传 `sample_url`（如 `...mp3`） |
+| 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
+    }
+  }
+]
+```
+
+> ⚠️ **已知平台 bug**：`add_conversation_step` apply 返回 snapshot_id 但数据不持久化（CLI v1.0.66），`get-scenario` 始终返回空 steps。对话步骤需在 MentorAI Web 管理后台手动补充。
+
+### 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 前 | 每次进入 Part2 都重新 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 → `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 |
+
+> **生成后自检命令**：逐条打开 step1-create.json，对照 Part1 确认输出，确保 description 长度与 Part1 场景描述正文长度一致。
+
+---
+
+### 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` | Part2 阶段留空（""），apply 后由资源匹配回填 |
+| B8 | 语音 | ☐ | `role_data.voice_id` | Part2 阶段留空（""），apply 后由资源匹配回填 |
+| 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` |
+| `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