@sokeai/cli 1.0.76 → 1.0.77

package/skills/soke-ai-coach-director/references/exec-handbook.md

@@ -0,0 +1,621 @@
+# 执行手册（Execution Handbook）
+
+> 本手册集中定义每个 Part 的**必做操作**、**完整 JSON 模板**、**提交前断言**、**反面案例**。
+> SKILL.md 的每个 Part 行只引用本手册锚点，不重复规则。
+> 所有规则以本手册为准；sync-engine.md / partN/SOP.md 仅作为字段参考手册。
+
+---
+
+## Part1 · 基础信息（创建场景）
+
+### 必做操作清单
+
+| # | 操作 | CLI 命令 | 产物 |
+|---|------|---------|------|
+| 1 | 创建场景 | `soke-cli ai-training +create-scenario --request-file ./part1-create.json --pretty` | `scenario_id` |
+| 2 | 回读验证 | `soke-cli ai-training +get-scenario --scenario-id <id> --pretty` | name/description/key_points/tags 一致 |
+
+> Part1 走**创建链路**，不是 preview/apply 更新链路。没有 operations 数组。
+
+### 完整 JSON 模板（part1-create.json）
+
+```json
+{
+  "name": "<场景名称，1-100 字符>",
+  "description": "<场景描述全文，完整搬运不缩略>",
+  "tags": ["标签1", "标签2", "标签3"],
+  "key_points": "1) 考核点1；2) 考核点2；3) 考核点3",
+  "scene_lang": "简体中文",
+  "scenario_cover": "https://newsokeeditorcdn.soke.cn/public/ai/cover/lingshou_daogou.png"
+}
+```
+
+**字段硬规则**：
+
+| 字段 | 类型 | 固定值/约束 | 高频错误 |
+|------|------|------------|---------|
+| `name` | string | 1-100 字符，≤15 字推荐 | 空字符串 |
+| `description` | string | Part1 场景描述全文，禁缩略 | 只写首句摘要 |
+| `tags` | string[] | 3-5 个数组元素 | ❌ 逗号分隔字符串 |
+| `key_points` | **string** | 多条用分号/编号拼成**单字符串** | ❌ 写成数组（平台会接受但字段为空） |
+| `scene_lang` | string | 固定 `"简体中文"`（永不随场景变） | ❌ `"zh-CN"` / `"中文"` |
+| `scenario_cover` | string | 固定默认图 URL | ❌ 占位/本地路径 |
+
+### 提交前断言（Python 表达式）
+
+```python
+assert isinstance(data["name"], str) and 1 <= len(data["name"]) <= 100
+assert isinstance(data["description"], str) and len(data["description"]) >= 20
+assert isinstance(data["tags"], list) and 3 <= len(data["tags"]) <= 5
+assert isinstance(data["key_points"], str) and len(data["key_points"]) > 0  # 必须是字符串
+assert data["scene_lang"] == "简体中文"
+assert data["scenario_cover"] == "https://newsokeeditorcdn.soke.cn/public/ai/cover/lingshou_daogou.png"
+```
+
+或运行 `python3 scripts/validate_part1.py ./part1-create.json`。
+
+### 反面案例（真实错误样本）
+
+```json
+❌ 案例 A：key_points 写成数组（平台接受但字段为空）
+{
+  "key_points": ["快速吸引", "精准推介", "展后跟进"]
+}
+
+❌ 案例 B：tags 写成逗号分隔字符串
+{
+  "tags": "展会拓客,B2B销售,快速识别"
+}
+
+❌ 案例 C：scene_lang 写成 zh-CN
+{
+  "scene_lang": "zh-CN"
+}
+
+❌ 案例 D：封面留空或写占位 URL
+{
+  "scenario_cover": ""
+}
+```
+
+### 创建后回读校验
+
+```python
+# 执行 get-scenario 后断言
+assert result["name"] == part1_create["name"]
+assert result["description"] == part1_create["description"]
+assert result["tags"] == part1_create["tags"]
+assert result["key_points"] == part1_create["key_points"]  # 若为空，检查是否提交了数组
+assert result["scenario_id"] not in (None, "")
+```
+
+- `scenario_id` 为空 → 视为创建失败，**禁止进入 Part2**
+- `key_points` 回读为空 → 检查 part1-create.json 是否误写成数组
+
+---
+
+## Part2 · AI 角色设定（双操作同步锁）
+
+### 必做操作清单
+
+| # | operation.type | 作用 | 不可省略 |
+|---|---------------|------|---------|
+| 1 | `update_basic` | 写入 OS 整体设定 A1-A7 全文到 `ai_roles_overall_description` | ✅ 遗漏会导致平台无 OS，角色退化为普通对话 |
+| 2 | `replace_ai_roles` | 写入所有角色数据到 `ai_roles[]` | ✅ 遗漏会导致平台有 OS 无角色 |
+
+**两操作必须全部 applied=true 才算 Part2 完成**。可在同一批 operations 数组提交（OS 在前、roles 在后），也可分两次 apply。
+
+### 完整 JSON 模板（part2-operations.json）
+
+```json
+[
+  {
+    "type": "update_basic",
+    "data": {
+      "ai_roles_overall_description": "<A1-A7 OS 全文，单字符串，≥500 字符，禁摘要/禁'参见 Part2'>"
+    }
+  },
+  {
+    "type": "replace_ai_roles",
+    "data": {
+      "roles": [
+        {
+          "scenario_role_id": "role_<角色短码>",
+          "customization_level": "full",
+          "is_custom_role": true,
+          "customized_fields": ["name", "description", "communication_style", "background", "personality_type", "personality", "tags", "knowledge_level", "taboos_objections", "avatar", "voice_id", "source_type"],
+          "template_id": null,
+          "template_name": null,
+          "template_version": null,
+          "role_data": {
+            "name": "<角色名>",
+            "description": "<角色描述>",
+            "communication_style": "<沟通风格>",
+            "background": "<四段深度画像全文：我是谁/我的困扰/我的过往经历/我今天的心态>",
+            "personality_type": "<MBTI 单值，如 ISFJ>",
+            "personality": "<性格描述>",
+            "tags": ["标签1", "标签2"],
+            "knowledge_level": ["小白"],
+            "taboos_objections": ["禁忌1", "禁忌2"],
+            "avatar": "<后台资源匹配的 URL，禁手工预设>",
+            "voice_id": "<后台资源匹配的 ID，禁手工预设>",
+            "source_type": "custom"
+          }
+        }
+      ]
+    }
+  }
+]
+```
+
+### 字段硬规则
+
+| 字段 | 类型 | 约束 |
+|------|------|------|
+| `ai_roles_overall_description` | string | ≥500 字符；A1-A7 全文拼接，不摘要 |
+| `roles[]` | array | 非空，2-5 个角色 |
+| `roles[].role_data.avatar/voice_id` | string | 后台 `+list-role-avatars/+list-role-voices` 匹配；**禁手工预设** |
+| `roles[].role_data.knowledge_level` | string[] | 数组枚举（如 `["小白"]`），禁长句 |
+| `roles[].role_data.tags` | string[] | 2-4 个 |
+| `roles[].role_data.taboos_objections` | string[] | 列表项 |
+| 外壳字段位置 | - | `customization_level/is_custom_role/customized_fields/scenario_role_id/template_id/template_name/template_version` 必须在 `role_data` **外层**；⚠️ `source_type` 例外——必须在 `role_data` **内**（`role_data.source_type="custom"`），外壳写 source_type 会触发"角色数据异常"；⚠️ `created_at`/`updated_at` **禁传**——由平台自动生成，写字符串时间戳会触发"角色数据异常"（见 platform-api-pitfalls 陷阱1） |
+
+### 提交前断言
+
+```python
+# 操作 1: update_basic OS
+op_os = next(o for o in operations if o["type"] == "update_basic")
+os_text = op_os["data"]["ai_roles_overall_description"]
+assert isinstance(os_text, str) and len(os_text) >= 500
+
+# 操作 2: replace_ai_roles
+op_roles = next(o for o in operations if o["type"] == "replace_ai_roles")
+roles = op_roles["data"]["roles"]
+assert isinstance(roles, list) and len(roles) >= 1
+for r in roles:
+    # v3 必检: 外壳字段完整性（created_at/updated_at 由平台自动生成，禁传，不在此列）
+    for outer_key in ["scenario_role_id", "customization_level", "is_custom_role",
+                      "customized_fields",
+                      "template_id", "template_name", "template_version"]:
+        assert outer_key in r, f"缺少外壳字段: {outer_key}"
+    assert r["template_id"] is None and r["template_name"] is None and r["template_version"] is None
+    # customized_fields 必须是 12 个字段名，不能只写 ["role_data"]
+    assert len(r["customized_fields"]) >= 10, f"customized_fields 太少"
+    assert "name" in r["customized_fields"], "customized_fields 缺 name"
+    # 外壳不能有 source_type
+    assert "source_type" not in r, "source_type 不应在外壳"
+    # role_data 验证
+    rd = r["role_data"]
+    assert rd["avatar"] and rd["voice_id"]
+    assert isinstance(rd["knowledge_level"], list)
+    assert rd.get("source_type") == "custom", "role_data.source_type 必须为 custom"
+    # 外壳字段不能在 role_data 内
+    for shell_field in ["customization_level", "is_custom_role", "customized_fields",
+                        "scenario_role_id", "created_at", "updated_at",
+                        "template_id", "template_name", "template_version"]:
+        assert shell_field not in rd, f"{shell_field} 误入 role_data"
+```
+
+### 反面案例
+
+```json
+❌ 案例 A：遗漏操作 1（OS）—— 只提交 replace_ai_roles
+→ 平台 ai_roles_overall_description=null，角色无 OS 约束，行为退化为普通对话
+→ Step 7 闸门第 9 项不通过
+
+❌ 案例 B：外壳字段误放入 role_data
+{
+  "role_data": {
+    "customization_level": "full",   ← 错位
+    "name": "李晓琳"
+  }
+}
+→ 平台报"角色数据异常"，avatar/voice_id 均为空
+
+❌ 案例 C：avatar/voice_id 手工预设
+{
+  "role_data": {
+    "avatar": "https://xxx placeholder.png"  ← 禁手工写
+  }
+}
+→ 应该由后台 +list-role-avatars 匹配
+```
+
+---
+
+## Part3 · 流程设置
+
+### 必做操作清单
+
+| # | operation.type | 作用 |
+|---|---------------|------|
+| 1 | `update_basic` | 写入 `opening_dialogue`（开场语全文）+ `opening_dialogue_type: 1` |
+| 2 | 每环节一个 `add_conversation_step` | 写入对话 SOP 环节 |
+
+> 🔒 **原子性约束**：开场语 + 所有环节必须在**同一批 operations 数组的同一次 apply** 中提交，禁止拆分多次 apply。
+
+### 完整 JSON 模板（part3-operations.json）
+
+```json
+[
+  {
+    "type": "update_basic",
+    "data": {
+      "opening_dialogue": "<开场语完整原文>",
+      "opening_dialogue_type": 1
+    }
+  },
+  {
+    "type": "add_conversation_step",
+    "data": {
+      "step_name": "<环节名>",
+      "student_objective": "<学员目标，与 Part1 考核点一一对应>",
+      "ai_task": "<AI 任务，含 IF-THEN + 进入条件 + 角色行为 + 退出条件>",
+      "max_rounds": 5,
+      "sort_order": "1"
+    }
+  }
+]
+```
+
+### 字段硬规则
+
+| 字段 | 类型 | 约束 | 高频错误 |
+|------|------|------|---------|
+| `opening_dialogue_type` | **number** | 固定 `1`（整数，非字符串） | ❌ `"AI智能生成"` / `"1"` |
+| `opening_dialogue` | string | 开场语完整原文 | ❌ 缩略 |
+| `add_conversation_step.data.sort_order` | **string** | `"1"`、`"2"`（字符串） | ❌ 数字 1 |
+| `ai_task` | string | 含 IF-THEN + 进入条件 + 角色行为 + 退出条件 | ❌ 缺 IF-THEN / 缺退出条件 |
+| `max_rounds` | number | 整数 3-10 | ❌ 字符串 / 超范围 |
+
+### 提交前断言
+
+```python
+op_open = next(o for o in operations if o["type"] == "update_basic")
+assert op_open["data"]["opening_dialogue_type"] == 1  # 数字，不是字符串
+assert isinstance(op_open["data"]["opening_dialogue"], str) and len(op_open["data"]["opening_dialogue"]) > 20
+
+steps = [o for o in operations if o["type"] == "add_conversation_step"]
+assert 3 <= len(steps) <= 7
+for i, s in enumerate(steps):
+    d = s["data"]
+    for k in ["step_name", "student_objective", "ai_task", "max_rounds", "sort_order"]:
+        assert d.get(k) not in (None, "", []), f"step{i} missing {k}"
+    assert isinstance(d["sort_order"], str), f"step{i} sort_order 必须是字符串"
+    assert isinstance(d["max_rounds"], int) and 3 <= d["max_rounds"] <= 10
+    assert "IF" in d["ai_task"].upper() and "退出" in d["ai_task"]  # 简单断言 IF-THEN 和退出条件存在
+```
+
+### 反面案例
+
+```json
+❌ 案例 A：opening_dialogue_type 写字符串
+{ "opening_dialogue_type": "1" }
+→ 422 报错：opening_dialogue_type 必须是 1 或 2
+
+❌ 案例 B：sort_order 写数字
+{ "sort_order": 1 }
+→ 应该是 "1"（字符串）
+
+❌ 案例 C：拆分多次 apply（违反原子性）
+第 1 次 apply：只提交开场语
+第 2 次 apply：提交对话环节
+→ 违反原子性约束，应同一批 operations
+```
+
+---
+
+## Part4 · 评分标准（双层包装锁）
+
+### 必做操作清单
+
+| # | operation.type | 作用 |
+|---|---------------|------|
+| 1 | `replace_scoring_criteria_config` | 写入评分标准（含 5 维度+权重+一票否决） |
+
+### 完整 JSON 模板（part4-operations.json）
+
+```json
+[
+  {
+    "type": "replace_scoring_criteria_config",
+    "data": {
+      "config": {
+        "customization_level": "full",
+        "is_custom_criteria": true,
+        "customized_fields": ["criteria_data"],
+        "scenario_criteria_id": "criteria_<场景短码>",
+        "criteria_data": {
+          "name": "<评分标准名称，8-20 字>",
+          "description": "<评分标准描述全文>",
+          "source_type": "enterprise",
+          "total_weight": 100,
+          "tags": ["标签1", "标签2"],
+          "dimensions": [
+            {
+              "id": "dim_<code>",
+              "code": "<英文 code>",
+              "name": "<维度名>",
+              "description": "<维度描述>",
+              "weight": 25,
+              "scoring_rule": "<评分规则全文，含一票否决嵌入末尾>",
+              "criteria": ["评分点1", "评分点2"],
+              "sort_order": 1
+            }
+          ]
+        }
+      }
+    }
+  }
+]
+```
+
+### 双层包装锁
+
+| 层级 | 位置 | 字段 |
+|------|------|------|
+| **第 1 层（config 外壳）** | `data.config` | `customization_level` / `is_custom_criteria` / `customized_fields` / `scenario_criteria_id` / `criteria_data` |
+| **第 2 层（criteria_data 内核）** | `data.config.criteria_data` | `name` / `description` / `source_type` / `total_weight` / `tags` / `dimensions[]` |
+
+**双层缺一不可**。常见错误：只包 `config` 漏 `criteria_data`（平台会接受但存储结构错误，后续查询/weight 校验/同步都异常）。
+
+### 🔒 UI 展示硬要求（v2.24.1 新增）
+
+**以下字段 API 存储时不强制，但平台 UI 展示时必需——缺失会导致 UI 上看不到 Part4 数据**（2026-08-06 长龙航空中文版事故）：
+
+| 字段 | 位置 | 必需值示例 |
+|------|------|-----------|
+| `customization_level` | `criteria_data` 顶层 | `"full"` |
+| `is_custom_criteria` | `criteria_data` 顶层 | `true` |
+| `customized_fields` | `criteria_data` 顶层 | `["criteria_data"]` |
+| `scenario_criteria_id` | `criteria_data` 顶层 | `"criteria_<场景短码>_v1"` |
+| `total_weight` | `criteria_data` 顶层 | `100` |
+| `tags` | `criteria_data` 顶层 | 与 Part1 场景标签一致 |
+| `dimensions[].id` | 每个维度 | `"dim_<code>"` |
+| `dimensions[].sort_order` | 每个维度 | 数字 1、2、3... |
+
+> ⚠️ **历史教训**：API 接受只包 `criteria_data.dimensions` 的简化结构（存储成功），但平台 UI 会显示"无评分标准"。必须在 `criteria_data` 顶层补全上述 6 个字段，每个维度补 `id` 和 `sort_order`。
+
+### 字段硬规则
+
+| 字段 | 类型 | 约束 | 高频错误 |
+|------|------|------|---------|
+| `dimensions[].sort_order` | **number** | 整数 1、2、3 | ❌ 字符串（与 Part3 `sort_order` 相反） |
+| `dimensions[].weight` | number | 整数，所有维度合 = 100 | ❌ 不等于 100 |
+| `dimensions[].criteria` | string[] | 至少 2 个评分点 | ❌ 单条 / 逗号字符串 |
+| `dimensions[].scoring_rule` | string | 一票否决嵌入末尾 | ❌ 全局 one_vote_veto 字段 |
+| `dimensions[].code` | string | 英文语义编码 | ❌ 中文 |
+
+### 提交前断言
+
+```python
+op = operations[0]
+assert op["type"] == "replace_scoring_criteria_config"
+
+config = op["data"]["config"]
+assert "criteria_data" in config, "缺第 2 层 criteria_data 包装"
+
+cd = config["criteria_data"]
+for k in ["name", "description", "source_type", "total_weight", "tags", "dimensions"]:
+    assert cd.get(k) not in (None, "", []), f"criteria_data.{k} 空/缺失"
+
+assert cd["source_type"] == "enterprise"
+assert cd["total_weight"] == 100
+
+dims = cd["dimensions"]
+assert len(dims) >= 2
+assert sum(d["weight"] for d in dims) == 100, "权重总和不等于 100"
+for i, d in enumerate(dims):
+    for k in ["id", "code", "name", "description", "weight", "scoring_rule", "criteria"]:
+        assert d.get(k) not in (None, "", []), f"dim{i} missing {k}"
+    assert isinstance(d["sort_order"], int), f"dim{i} sort_order 必须是数字"
+    assert isinstance(d["criteria"], list) and len(d["criteria"]) >= 2
+    assert d["code"].isascii(), f"dim{i} code 必须是英文"
+```
+
+### 反面案例
+
+```json
+❌ 案例 A：只包 config 漏 criteria_data（平台会接受但存储错误）
+{
+  "type": "replace_scoring_criteria_config",
+  "data": {
+    "config": {
+      "name": "...",
+      "dimensions": [...]
+    }
+  }
+}
+→ 平台存为 {name, dimensions} 散在根，与正确结构不一致
+→ Step 7 闸门第 10.5 项不通过
+
+❌ 案例 B：dimensions.sort_order 写字符串
+{ "sort_order": "1" }
+→ 应该是数字 1（注意 Part3 是字符串，Part4 是数字）
+
+❌ 案例 C：一票否决写在全局
+{
+  "one_vote_veto": [...]
+}
+→ 应该嵌入各维度 scoring_rule 末尾
+```
+
+---
+
+## Part5 · 教练设置（固定模板）
+
+### 必做操作清单
+
+| # | operation.type | 作用 |
+|---|---------------|------|
+| 1 | `update_basic` | 写入 6 项固定配置 |
+
+### 完整 JSON 模板（part5-operations.json）
+
+```json
+[
+  {
+    "type": "update_basic",
+    "data": {
+      "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
+    }
+  }
+]
+```
+
+> ⚠️ **6 项固定配置禁按场景调整**。字段名以实际成功发布的版本为准。Part5 不再同步 `closing_dialogue` / `golden_dialogue_description` / `key_points`（这些已在 Part1/Part3 同步）。
+
+### 提交前断言
+
+```python
+op = operations[0]
+assert op["type"] == "update_basic"
+d = op["data"]
+assert d["min_practice_duration"] == 0
+assert d["max_practice_duration"] == 0
+assert d["max_practice_attempts"] == 10
+assert d["passing_score"] == 60
+assert d["completion_rule"] == "all_steps"
+assert d["ai_assistance_enabled"] is True
+assert d["pass_difficulty"] == 2
+```
+
+---
+
+## 通用约束
+
+### CLI 参数固定值
+
+- `--scenario-id <id>`（不是 `--scenario <id>`）
+- apply 需要 `--idempotency-key <unique>`
+- 每次 apply 后必须重新获取 `updated_at` 作为下次 `--base-updated-at`
+- **v2.37：所有 CLI 输出一律 `> /tmp/xxx.json 2>/dev/null` 重定向**，禁止 `--pretty` 直出到对话。Python 从重定向文件提取字段，不回显 JSON 原文。
+- **v2.37：apply 禁止用于验证**。验证数据用 `+get-scenario`，apply 后只从返回值提取 `updated_at`（`tail -1` 或 Python 提取），不回显 operations/snapshot_id。用 apply 回读环节会导致 `add_conversation_step` 重复添加。
+
+### 材料预处理铁律（v2.37 强化：一次成型）
+
+非结构化材料（PDF/DOCX/PPT）经 pdftotext 提取后：
+1. **一次成型写提炼稿**：pdftotext 提取到 `/tmp/` → **一次性** grep 定位 + sed 读取关键段落 → Write 落盘提炼稿到 `/tmp/xxx_refined.md`。**禁止分多轮 sed 回看**（每轮 sed 回看消耗 1-2 积分）。
+2. **原始材料全文不再进入后续 Part 上下文**——Part1-5 生成只读提炼稿
+3. 提炼稿只保留 Part1-5 所需结构化要素（业务背景/训练对象/话术/画像线索/异议/红线/评分线索）
+4. 提炼稿删除无关段落（目录/版权页/附录/重复章节）
+5. 提炼稿 ≤1500 字（硬上限），超了二次压缩只保留核心要素
+6. **提炼稿落盘后，后续 Part1-5 只 Read 这一个文件**，不再碰原始 PDF/DOCX
+
+### 后台静默规则（G1/G3）
+
+所有 CLI 错误（stderr / 非零退出 / 422 / 409）**禁止对用户展示**。AI 内部分析修正（最多 2 次重试），仍失败仅告知"Part N 同步异常"+ ≤50 字原因。
+
+### 输出过滤规则（v2.35 反压缩强化）
+
+后台 Python 脚本（build_*.py / fix_*.py / validate 等）的 print() 输出、JSON 文件大小、字符数统计、自查断言结果（"✅ xxx"）→ 🔇 后台静默，**禁止出现在对话消息中**。
+
+**CLI 输出强制静默（v2.37 三次强化）**：
+- **所有 soke-cli 命令**输出一律 `> /tmp/xxx.json 2>/dev/null` 重定向（create-scenario / list-role-avatars / list-role-voices / apply / get / publish / sync 全部重定向），**禁止 `--pretty` 直出到对话**
+- preview/apply 命令一律 `2>/dev/null | tail -3`，只看结尾 3 行状态
+- `+get-scenario` 回读一律 `> /tmp/xxx.json` 重定向，Python 只打印 `True/False` 布尔判断
+- snapshot_id / updated_at / warnings / operations 回显**一律吞掉**
+- **apply 禁止用于验证**（v2.37）：apply 是写入操作，不是读取操作。用 apply 回读环节会导致 `add_conversation_step` 重复添加 → 需快照回滚 → 浪费 3-5 积分。验证用 `+get-scenario`。
+- 仅失败时输出 ≤50 字原因
+
+替代方案：
+- 成功 → 不展示任何细节，直接进入下一步
+- 失败 → 仅展示"Part N 同步失败：≤50 字原因"
+- 需要核对 → 仅展示差异摘要，不展示完整 JSON 或 CLI 原始输出
+
+### 发布确认弹窗（v2.27 新增，v2.37 知识包复用提炼稿）
+
+Part5 同步后不直接发布。管线：Part5 apply → Step 6-8 后台验证 → Step 8.5 模板 8 弹窗"确认发布？" → 用户确认后执行 `+publish-scenario`。
+发布成功后展示完成摘要 → Step 10 模板 7 知识包弹窗（必须触发）。
+
+> **v2.37 知识包复用规则**：知识包 Markdown source 直接复用材料提炼稿（`/tmp/xxx_refined.md`），**禁止从零重写**（内容已在上下文中，重写浪费 3-5 积分）。只需按知识包 entries 格式拆条目（entry_id / entry_type / source_id / title / content / source_refs / tags）。
+
+### 确认弹窗优先（G2）+ 聊天正文承载完整内容（v2.38）
+
+所有用户确认环节优先使用 `render_ui` QuestionForm；不可用时降级为文本编号。
+
+**弹窗即时触发（v2.30）+ 聊天正文承载完整内容（v2.38）**：Part 完整内容在聊天正文中展示（编号列表组织，禁用 Markdown 表格），展示后紧接 AskUserQuestion 弹窗。弹窗仅做确认/调整选择——`question` 字段只写 ≤2 行引导语，`options` 只放「确认」「需要调整」等选择项。**禁止把 Part 完整内容塞进弹窗 question 字段**。
+
+### 沙箱绕过（G4）
+
+WorkBuddy Bash 调用 soke-cli 必须设 `dangerouslyDisableSandbox: true`。
+
+---
+
+## 平台头像库
+
+正确路径前缀：`https://newsokeeditorcdn.soke.cn/public/ai/roles_avatars/`（❌ 错误：`/public/ai/avatar/`，存进去 UI 空白）。
+头像 URL 一律通过 `soke-cli ai-training +list-role-avatars` **重定向到 /tmp/avatars.json 后 Python 按性别/年龄关键词过滤 title 字段提取 url**（v2.37：禁止 `--pretty` 直出，禁止 `--gender`/`--age-group` 参数——CLI 不支持）。声音同理重定向到 `/tmp/voices.json` 后 Python 提取 `id`。
+
+---
+
+## JSON 字段类型硬规则（平台同步必读）
+
+> 来源：`platform/sync-engine.md`（字段参考手册）。原则：**文档是什么类型，就严格按什么类型生成。**
+
+### string 字段：必须生成字符串
+
+多条内容用顿号、分号、编号或 `\n` 拼接为一个字符串，禁止写成数组。
+
+关键 string 字段：`name`、`description`、`key_points`、`role_data.name`、`role_data.description`、`role_data.avatar`、`role_data.communication_style`、`role_data.background`、`role_data.personality_type`、`role_data.personality`、`role_data.voice_id`、`ai_roles_overall_description`、`opening_dialogue`、`conversation_steps[].step_name`、`conversation_steps[].student_objective`、`conversation_steps[].ai_task`、`criteria_data.name`、`criteria_data.description`、`dimensions[].code`、`dimensions[].name`、`dimensions[].description`、`dimensions[].scoring_rule`
+
+### string[] 字段：只有明确数组字段才生成数组
+
+每条一个元素：`tags`、`conversation_knowledge_base_ids`、`scoring_knowledge_base_ids`、`role_data.tags`、`role_data.knowledge_level`、`role_data.taboos_objections`、`dimensions[].criteria`
+
+### number / boolean / null 字段
+
+- number 不加引号：`weight`、`total_weight`、`max_rounds`、`max_practice_attempts`、`passing_score`、`pass_difficulty`、`dimensions[].sort_order`
+- boolean 不加引号：`is_custom_role`、`is_custom_criteria`、`ai_assistance_enabled`
+- null 写 `null`，不写空字符串或 `"null"`
+
+### 创建/更新差异
+
+- 创建 `conversation_steps` 用 `ai_objective`；更新用 `ai_task`。
+- 创建 `conversation_steps[].sort_order` 写字符串（`"1"`）；评分维度 `sort_order` 写数字（`1`）。
+
+### 生成前自检
+
+```text
+☐ string 字段没有被写成数组或对象
+☐ string[] 字段没有被写成逗号分隔字符串
+☐ number 字段没有加引号
+☐ boolean 字段没有加引号
+☐ null 字段没有写成 "" 或 "null"
+☐ 创建/更新 sort_order 类型符合对应接口要求
+```
+
+---
+
+## 状态快照与缓存规则
+
+> 来源：`platform/sync-engine.md`。创建型内部使用，不在聊天中输出。
+
+### state-snapshot.json 结构
+
+```json
+{
+  "mode": "partwise",
+  "scenario_id": "scn_xxx",
+  "scenario_short": "b7730195",
+  "updated_at": "2026-07-10T01:40:58.216028Z",
+  "current_part": "part3",
+  "confirmed_data": { "part1": {}, "part2": {}, "part3": {}, "part4": {}, "part5": {} },
+  "applied": { "part1": true, "part2": true, "part3": false, "part4": false, "part5": false },
+  "cached": { "role_profile": {}, "scenario_type": "" }
+}
+```
+
+### 依赖与回滚规则
+
+- Part1 修改 → Part2-Part5 全部待复核
+- Part2 修改 → 至少重检 Part3 与 Part5
+- Part3 修改 → 至少重检 Part4 与 Part5
+- Part4 修改 → 重检 Part5
+- Part5 修改通常不反推前序 Part，但若改动通关分数/难度，需检查与 Part4 评分体系一致