@sokeai/cli 1.0.76 → 1.0.78

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

@@ -0,0 +1,86 @@
+# Part1 · 基础信息（创建场景）
+
+> v2.41 从 exec-handbook.md 拆分。通用约束见 `exec-common.md`。
+
+---
+
+## 必做操作清单
+
+| # | 操作 | CLI 命令 | 产物 |
+|---|------|---------|------|
+| 1 | 创建场景 | `soke-cli +create-scenario --request-file /tmp/part1.json` | `scenario_id` |
+| 2 | 回读验证 | `soke-cli +get-scenario --scenario-id <id>` | 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
+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"
+```
+
+---
+
+## 反面案例
+
+```json
+❌ 案例 A：key_points 写成数组（平台接受但字段为空）
+{ "key_points": ["快速吸引", "精准推介", "展后跟进"] }
+
+❌ 案例 B：tags 写成逗号分隔字符串
+{ "tags": "展会拓客,B2B销售,快速识别" }
+
+❌ 案例 C：scene_lang 写成 zh-CN
+{ "scene_lang": "zh-CN" }
+
+❌ 案例 D：封面留空或写占位 URL
+{ "scenario_cover": "" }
+```
+
+---
+
+## 创建后回读校验
+
+```python
+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 是否误写成数组

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

@@ -0,0 +1,145 @@
+# Part2 · AI 角色设定（双操作同步锁）
+
+> v2.41 从 exec-handbook.md 拆分。通用约束见 `exec-common.md`。
+
+---
+
+## 必做操作清单
+
+| # | 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。
+
+---
+
+## OS（ai_roles_overall_description）写作结构（v2.42 内联，禁再读 part2-roles.md）
+
+OS 是单字符串，≥500 字符，≤3000 字符。按以下 7 段顺序拼接（A1-A7），每段一个自然段：
+
+```
+A1 核心身份：你是"高保真人类社交模拟器"兼"隐形考核官"，扮演具复杂社会属性、非理性情绪的特定角色，抛弃"乐于助人"的 AI 出厂设置，通过真实对话考核学员的沟通/销售能力。
+
+A2 动态状态机：回复前更新 Trust_Level（信任值0-100，<20冷淡/>80成交信号）、Patience_Gauge（耐心条随轮次衰减）、Fact_Anchoring（事实锚点严禁幻觉修改）。
+
+A3 双层逻辑：理性真值（后台精确算计）→感性表述（前台拟人化），永远不要轻易痛快答应。
+
+A4 行为规范：语言熵增（倒装/重复/断句/口语填充）；心理防御（面子机制/逻辑谬误/信息非对称）；禁AI式服务、禁格式化输出、禁事实漂移；学员说违规夸大词（"绝对""100%"）时触发信任崩塌反击。
+
+A5 信息挤牙膏：开场只表达表层诉求，被问才透露深层信息；学员单次回复超100字时抓核心痛点重复质疑，但明确回答过的问题不能假装没听见。
+
+A6 隐形考核：随机挖坑测试（故意说错数据）、施压测试（突变条件）。
+
+A7 导演模式：死局/结束/输入"复盘"时跳出角色，以金牌导师身份复盘，格式【关键死因/成功点】【心理揭秘】【金样板话术】。
+```
+
+按场景材料填充每段细节（话术风格/行业背景/红线），但**结构必须保持 A1-A7 顺序**。
+
+---
+
+## 完整 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` **禁传**——由平台自动生成，写字符串时间戳会触发"角色数据异常" |
+
+---
+
+## 提交前断言
+
+```python
+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
+
+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:
+    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
+    assert len(r["customized_fields"]) >= 10
+    assert "name" in r["customized_fields"]
+    assert "source_type" not in r
+    rd = r["role_data"]
+    assert rd["avatar"] and rd["voice_id"]
+    assert isinstance(rd["knowledge_level"], list)
+    assert rd.get("source_type") == "custom"
+    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 约束，行为退化为普通对话
+
+❌ 案例 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 匹配
+```

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

@@ -0,0 +1,91 @@
+# Part3 · 流程设置
+
+> v2.41 从 exec-handbook.md 拆分。通用约束见 `exec-common.md`。
+
+---
+
+## 必做操作清单
+
+| # | 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"]
+```
+
+---
+
+## 反面案例
+
+```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
+```

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

@@ -0,0 +1,187 @@
+# Part4 · 评分标准（双层包装锁）+ Part5 合并应用（v2.43）
+
+> v2.41 从 exec-handbook.md 拆分。通用约束见 `exec-common.md`。
+> **v2.43 变更**：Part5 固定配置不再单独确认/apply——Part4 弹窗确认后，Part4+Part5 两个 operation **合并一批 apply**（part4-operations.json 数组含两个元素）。**exec-part5.md 已删除，Part5 全部规则并入本文件（v2.43.1）。**
+> **展示规则**：聊天正文必须**完整展示 Part4 + Part5 两段**——Part4 展示维度名+权重+一票否决，紧接 Part5 用编号列表完整展示 6 项固定配置。**禁止把 Part5 压缩成一行摘要省略展示**。
+
+---
+
+## 必做操作清单
+
+| # | operation.type | 作用 |
+|---|---------------|------|
+| 1 | `replace_scoring_criteria_config` | 写入评分标准（含 5 维度+权重+一票否决） |
+| 2 | `update_basic`（Part5 固定配置，v2.43 并入同批） | 6 项固定值：min/max_practice_duration=0 / max_practice_attempts=10 / passing_score=60 / completion_rule="all_steps" / ai_assistance_enabled=true / pass_difficulty=2 |
+
+**弹窗引导语**（≤2 行）：`以上是 Part4 评分标准 + Part5 教练配置（6 项固定值），是否确认写入？`
+
+**聊天正文展示模板**（Part4 之后紧接 Part5，编号列表，不可省略）：
+
+```
+**Part4 评分标准**（合计 100 分）
+| 维度 | 权重 | 一票否决 |
+|---|---|---|
+| <维度1> | <w1> | 有/无 |
+| ... | ... | ... |
+
+**Part5 教练配置**（6 项固定值）
+1. 练习时长：不限
+2. 最大练习次数：10 次
+3. 通关分数：60 分
+4. 完成规则：全环节完成
+5. AI 辅助：开启
+6. 通关难度：2
+```
+
+> ⚠️ **6 项固定配置禁按场景调整**（原 exec-part5.md 规则，v2.43.1 并入）。字段名以实际成功发布的版本为准。Part5 不再同步 `closing_dialogue` / `golden_dialogue_description` / `key_points`（这些已在 Part1/Part3 同步）。
+
+---
+
+## 完整 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
+            }
+          ]
+        }
+      }
+    }
+  },
+  {
+    "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
+    }
+  }
+]
+```
+
+---
+
+## 双层包装锁
+
+| 层级 | 位置 | 字段 |
+|------|------|------|
+| **第 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 展示硬要求
+
+**以下字段 API 存储时不强制，但平台 UI 展示时必需——缺失会导致 UI 上看不到 Part4 数据**：
+
+| 字段 | 位置 | 必需值示例 |
+|------|------|-----------|
+| `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 必须是英文"
+
+# Part5 固定配置（v2.43 并入同批）
+op5 = operations[1]
+assert op5["type"] == "update_basic"
+d5 = op5["data"]
+assert d5["min_practice_duration"] == 0 and d5["max_practice_duration"] == 0
+assert d5["max_practice_attempts"] == 10
+assert d5["passing_score"] == 60
+assert d5["completion_rule"] == "all_steps"
+assert d5["ai_assistance_enabled"] is True
+assert d5["pass_difficulty"] == 2
+```
+
+---
+
+## 反面案例
+
+```json
+❌ 案例 A：只包 config 漏 criteria_data（平台会接受但存储错误）
+{ "type": "replace_scoring_criteria_config", "data": { "config": { "name": "...", "dimensions": [...] } } }
+→ 平台存为 {name, dimensions} 散在根，与正确结构不一致
+
+❌ 案例 B：dimensions.sort_order 写字符串
+{ "sort_order": "1" }
+→ 应该是数字 1（注意 Part3 是字符串，Part4 是数字）
+
+❌ 案例 C：一票否决写在全局
+{ "one_vote_veto": [...] }
+→ 应该嵌入各维度 scoring_rule 末尾
+```

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

@@ -0,0 +1,46 @@
+# AI 陪练 Gate Check 矩阵
+
+> 各阶段/Part 结束时对照检查。🔴 阻塞（必须修复）/ 🟡 警告（建议修复）。Part1-5 逐项字段校验已在各 Part SOP 自查清单与 exec-handbook 断言中定义，本文件聚焦发布前汇总闸门。
+>
+> **v2.39 闸门精简规则**：Step 7 的 12 项中，9 项与 Part1-5 自检清单完全重叠（标注「↔PartN自检」）。Part 自检全部通过后，这 9 项**自动视为通过**，不再重复检查。闸门仅补查 3 项（标注「⚡仅闸门」）。
+
+## Step 7 创建质量闸门（12 项，全部通过才进 Step 8）
+
+| # | 检查项 | 严重度 | v2.39 精简 |
+|---|--------|--------|------------|
+| 1 | 材料完整（含业务场景+话术素材） | 🔴 | ↔Part1自检（自检通过则跳过） |
+| 2 | 场景类型判定已确认 | 🔴 | ↔Step2确认（已确认则跳过） |
+| 3 | 角色行为化（无空泛画像） | 🔴 | ↔Part2自检（自检通过则跳过） |
+| 4 | 信息释放规则明确 | 🔴 | ↔Part2自检（自检通过则跳过） |
+| 5 | 每环节含进入/退出条件 | 🔴 | ↔Part3自检（自检通过则跳过） |
+| 6 | 评分可识别（维度↔考核点对应） | 🔴 | ↔Part4自检（自检通过则跳过） |
+| 7 | 练习配置匹配固定模板 | 🔴 | ↔Part4+5 合并自检（v2.43.1，exec-part4.md 断言区） |
+| 8 | Part 内容完整展示 | 🔴 | ⚡仅闸门（需检查展示记录） |
+| 9 | Part2 角色 background 四段完整 | 🔴 | ↔Part2自检（自检通过则跳过） |
+| 10 | Part4 权重和 = 100 | 🔴 | ↔Part4自检（自检通过则跳过） |
+| 11 | 测试用例 | 🟡 | ⚡仅闸门（可选，不阻塞） |
+| 12 | 整体设定 ≤ 3000 字 | 🟡 | ⚡仅闸门（需统计字数） |
+
+> **v2.39 批量校验脚本缩减**：Part 自检全部通过后，闸门批量校验从 16 个断言缩减为 7 个（4 项发布闸门 + 3 项补查项）。
+
+## Step 8 发布闸门（资源兜底，任一缺失禁止发布）
+
+| # | 检查项 | 严重度 |
+|---|--------|--------|
+| 1 | 封面 = 固定默认图 | 🔴 |
+| 2 | 全部 avatar 非空 URL | 🔴 |
+| 3 | 全部 voice_id 非空 ID | 🔴 |
+| 4 | 无"角色数据异常" | 🔴 |
+
+## 微调闸门（8 项）
+
+| # | 检查项 | 严重度 |
+|---|--------|--------|
+| 1 | 有证据 | 🟡 |
+| 2 | 已技术分流 | 🔴 |
+| 3 | 已打标签（F/I/O/L/E/S/R/K/T/D） | 🔴 |
+| 4 | 修改决策 | 🔴 |
+| 5 | 标注改稿 | 🔴 |
+| 6 | 复测方案 | 🔴 |
+| 7 | 版本记录建议 | 🟡 |
+| 8 | 整体设定 ≤ 3000 字 | 🟡 |

package/skills/mono/references/modules/soke-ai-coach-director/references/micro-tune-labels.md

@@ -0,0 +1,30 @@
+# 微调诊断标签完整定义
+
+> 由 SKILL.md「微调诊断标签」节引用。微调型任务必须打标签后才能进入修改建议。
+> 核心原则：**没有标签，不进入修改建议。**
+
+| 标签 | 含义 | 判定要点 |
+|------|------|---------|
+| **F** | 格式违规 | 括号动作、Markdown语法、后台痕迹外显 |
+| **I** | 信息释放违规 | 开场透露全部症状/底线/背景 |
+| **O** | 角色OOC | 太热情/太攻击/说出不该说的术语 |
+| **P** | 指令执行度违规 | AI实际行为与提示词行为指令不一致 |
+| **N** | 对话自然度违规 | 模板化、万能回应、句式单一、过渡生硬 |
+| **L** | 逻辑违规 | 信任值异常、价格防线过早松动 |
+| **E** | 结束违规 | 提前结束、成交后继续追问 |
+| **S** | 场景规则违规 | 违反药房/合规/B2B场景规则 |
+| **R** | 评分规则问题 | 评分项抽象、目标错位、无法识别间接达成 |
+| **K** | 知识/合规问题 | 产品知识错误、禁用话术未触发 |
+| **T** | 技术/体验问题 | ASR/TTS/权限/跳转 |
+| **D** | 数据/看板问题 | 指标口径错误、数据污染 |
+
+## 诊断分析顺序
+
+必须严格按此顺序执行：
+
+```
+T排障 → O拟真 → P指令执行 → N自然度 → I信息释放/K知识 → E结束/S场景 → L逻辑/F格式 → R评分
+```
+
+- **P 在第 3 位**：先确认角色没崩(O)，再查指令执行度(P)，避免角色OOC导致P误判
+- **N 在第 4 位**：先确认行为指令合规(P)，再查表达是否自然(N)。模板化"好的""了解了"等万能回应属于 N 违规而非 O 或 F 问题

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

@@ -0,0 +1,49 @@
+# 平台 API 踩坑清单（致命陷阱速查）
+
+> 已验证的致命陷阱，优先级高于历史示例。命令速查见 `verified-cli-cheatsheet.md`。
+
+## 🔴 4 条致命陷阱（踩了必坏）
+
+### 1. Part2 角色外壳字段放错层级 → "角色数据异常"
+
+每个角色的**外壳**必须包含以下字段（与 `role_data` 同级，**不可**写进 `role_data` 内）：
+`scenario_role_id` / `customization_level="full"` / `is_custom_role=true` / `customized_fields` / `template_id=null` / `template_name=null` / `template_version=null`。
+
+> ⚠️ **`created_at`/`updated_at` 禁传（2026-08-18 实测）**：外壳若传字符串时间戳（如 `"2026-08-18T05:41:14Z"`），会触发「角色数据异常」，导致 `role_data` 全字段置空（name 变成"角色数据异常"）。这两个字段由平台自动生成，生成 `part2-operations.json` 时**一律省略**，不要写入外壳。exec-handbook 旧断言要求外壳含 created_at/updated_at 是错误结论，以本条为准。
+
+- `customized_fields` 必须列全 12 个字段名：`["name","description","communication_style","background","personality_type","personality","tags","knowledge_level","taboos_objections","avatar","voice_id","source_type"]`，只写 `["role_data"]` 会导致静默不持久化。
+- `source_type="custom"` 在 `role_data` **内**（外壳不写 source_type）。
+- `avatar` 用头像 URL（`+list-role-avatars` 的 `url`），`voice_id` 用声音 ID（`+list-role-voices` 的 `id`）。
+- `knowledge_level` 必须是数组，不是字符串。
+
+### 2. Part4 shell 字段放错层级 → UI 不显示评分
+
+`data.config` 顶层必须含 4 个 shell 字段：`scenario_criteria_id` / `customization_level="full"` / `is_custom_criteria=true` / `customized_fields=["criteria_data"]`，**不能放进 `criteria_data` 内**。`criteria_data` 内只放：`name` / `description` / `dimensions` / `total_weight` / `source_type="enterprise"` / `status=1` / `tags`。每个维度含 `id`(dim_{code}) 和 `sort_order`(数字)。
+
+### 3. add_conversation_step 数据不持久化（CLI bug）+ apply 禁止用于验证（v2.37 教训）
+
+`add_conversation_step` apply 返回成功但 `+get-scenario` 回读 `conversation_steps: []`（CLI v1.0.65+ 已知 bug，`replace_conversation_steps` 被 422 拒绝）。处理：仍按标准语义用 `add_conversation_step` 先试，回读为空则判定持久化缺陷，改走 MentorAI Web 后台手动补录。不阻断发布。
+
+> ⚠️ **v2.37 教训（2026-08-18 升舱场景事故）**：质量闸门阶段误用 `+apply-scenario-update`（operations-file=part3-operations.json）当验证用，导致 `add_conversation_step` **重复添加**（4 环节变 8 环节），不得不查快照→回滚→重新 get 验证，浪费 3-5 积分。
+> **规则**：apply 是**写入操作**，不是读取操作。验证数据用 `+get-scenario`。apply 后只从返回值提取 `updated_at`（`tail -1` 或 Python 提取），**不回显 operations/snapshot_id**，**不用 apply 回读环节**。
+
+### 4. +create-scenario 只存基础字段
+
+`+create-scenario --request-file` 仅持久化 `name/description/tags/key_points/scene_lang/scenario_cover`；`ai_roles`/`scoring_criteria_config`/`conversation_steps`/练习配置全部被忽略。必须创建后逐 Part 用 `+apply-scenario-update` 写入。
+
+## ⚠️ 高频坑（速查）
+
+- **沙箱**：所有 soke-cli 命令设 `dangerouslyDisableSandbox: true`（Go 二进制受限）。
+- **子命令**：统一 `soke-cli ai-training +...`，不省略 `ai-training`。
+- **operations 格式**：裸数组 `[{type,data},...]`，不套 `{"operations":[...]}`。
+- **apply 参数**：`--idempotency-key`（apply 必传，preview 不传）、`--reason`（两者必传）。
+- **乐观锁**：每次 preview/apply 前 `+get-scenario` 重取最新 `updated_at`。
+- **验收**：apply 后 `+get-scenario --raw` 逐字段核对目标字段；preview/apply 成功≠平台最终解析正常。
+- **JSON 中文引号**：用 Python `json.dump(ensure_ascii=False)` 写入，禁 heredoc/echo（全角双引号会报错）。
+- **类型**：Part3 `max_rounds` 整数、`sort_order` 字符串 `"1"`；Part4 `sort_order` 数字 `1`（两者相反）。
+- **Part1 必填**：`key_points` 是字符串（非数组）、`scene_lang="简体中文"`、`scenario_cover` 固定默认图 `https://newsokeeditorcdn.soke.cn/public/ai/cover/lingshou_daogou.png`。
+- **身份字段**：`corp_id/user_id/implementation_corp_id` 禁写请求体，不作选租户依据。
+
+## 推荐顺序
+
+环境检测 → Step1 写固定封面 → 每 Part 前 `get-scenario` → preview → apply → `get-scenario --raw` 验收。回读异常先查：Part2 查 avatar/外壳/customized_fields/background（background=null 最常见）；Part4 查三层嵌套与元数据字段；Part5 只查练习配置字段。