@sokeai/cli 1.0.73 → 1.0.75

package/skills/ai-coach-director/platform/api-fallback.md

@@ -0,0 +1,262 @@
+# MentorAI REST API Fallback
+
+> 内部规则文件。当 soke-cli 在目标平台不可用或受限时，降级为直接调用 MentorAI REST API 完成平台同步。
+>
+> soke-cli 本质是 MentorAI REST API 的命令行封装。本文件记录 API 的直接调用方式，作为跨平台兜底方案。
+
+## 使用条件
+
+以下任一情况触发 API fallback：
+- soke-cli 未安装且无法安装（受限制的企业环境）
+- soke-cli 执行持续失败（沙箱限制、权限问题）
+- 平台不支持 CLI 执行（纯聊天/IM 环境）
+- 用户明确要求使用 API 方式
+
+## API 基础信息
+
+| 项目 | 值 |
+|------|-----|
+| Base URL | `https://api.soke.cn` |
+| 认证方式 | Bearer Token（从 `soke-cli config show` 获取 `user_token`） |
+| Content-Type | `application/json` |
+
+### 获取 Token
+
+若 soke-cli 可用（即使受限无法执行业务命令）：
+```bash
+soke-cli config show
+# 提取 user_token 字段
+```
+
+若 soke-cli 完全不可用：引导用户从授客AI开放平台获取 API Token。
+
+## API 接口映射
+
+soke-cli 命令与 REST API 的对应关系：
+
+### 场景创建 (Part1)
+
+**CLI**: `soke-cli ai-training +create-scenario --request-file ./step1-create.json`
+
+**API**:
+```
+POST /api/v1/ai-training/scenarios
+Headers:
+  Authorization: Bearer <token>
+  Content-Type: application/json
+Body: step1-create.json 内容
+```
+
+**关键字段**: `name`, `description`, `tags`, `key_points`, `language`
+
+### 场景查询
+
+**CLI**: `soke-cli ai-training +get-scenario --scenario-id <id> --pretty`
+
+**API**:
+```
+GET /api/v1/ai-training/scenarios/<scenario_id>
+Headers:
+  Authorization: Bearer <token>
+```
+
+### 场景更新 (Part2-5)
+
+每个 Part 对应一个 operations 文件 (`partN-operations.json`)。
+
+**CLI**: `soke-cli ai-training +preview-scenario-update ...` → `soke-cli ai-training +apply-scenario-update ...`
+
+**API** (两步合一):
+```
+PATCH /api/v1/ai-training/scenarios/<scenario_id>
+Headers:
+  Authorization: Bearer <token>
+  Content-Type: application/json
+Body: operations JSON 内容
+```
+
+> ⚠️ operations JSON 中的 `base_updated_at` 必须先通过 GET 查询获取最新平台状态，再填入。禁止使用过期的时间戳。
+
+### 角色头像列表
+
+**CLI**: `soke-cli ai-training +list-role-avatars [--gender <gender>] [--age-group <age>]`
+
+**API**:
+```
+GET /api/v1/ai-training/role-avatars?gender=<gender>&age_group=<age>
+Headers:
+  Authorization: Bearer <token>
+```
+
+### 角色语音列表
+
+**CLI**: `soke-cli ai-training +list-role-voices [--gender <gender>] [--age-group <age>]`
+
+**API**:
+```
+GET /api/v1/ai-training/role-voices?gender=<gender>&age_group=<age>
+Headers:
+  Authorization: Bearer <token>
+```
+
+### 场景发布
+
+**CLI**: `soke-cli ai-training +publish-scenario --scenario-id <id> --version 1`
+
+**API**:
+```
+POST /api/v1/ai-training/scenarios/<scenario_id>/publish
+Headers:
+  Authorization: Bearer <token>
+  Content-Type: application/json
+Body: {"version": 1, "version_description": "CLI发布"}
+```
+
+## 资源匹配完整流程（头像 + 声音）
+
+> ⚠️ **跨平台关键**：Avatar/voice 匹配在 soke-cli 可用时走 CLI（`role-resource-matching.md`），CLI 不可用时走本节的 REST API 路径。**禁止因 CLI 不可用直接跳过资源匹配**——这会导致角色上线后无头像无声音。
+
+### 匹配时机
+
+Part2 完整内容已展示并由用户确认 → 立即执行资源匹配 → 将 avatar URL 与 voice_id 写入角色级 JSON → 逐个角色 PATCH/apply 并回读验证。整个过程不等待用户触发，也不向用户二次确认。与 CLI 路径的时机完全一致。
+
+### 步骤 1：获取 Token
+
+```bash
+soke-cli config show 2>/dev/null | grep user_token
+# 若 soke-cli 完全不可用，引导用户从授客AI开放平台获取
+```
+
+### 步骤 2：查询头像库
+
+```bash
+# 一阶精准查询（性别+年龄）
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "https://api.soke.cn/api/v1/ai-training/role-avatars?gender=female&age_group=middle-aged&lang=zh"
+
+# 降级：仅按性别
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "https://api.soke.cn/api/v1/ai-training/role-avatars?gender=female&lang=zh"
+
+# 降级：无过滤全量
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "https://api.soke.cn/api/v1/ai-training/role-avatars?lang=zh"
+```
+
+**返回字段**：`id`（资源 ID，不用于回填）、`url`（头像 CDN URL，**回填时用这个**）、`gender`、`age_group`、`sort`。
+
+### 步骤 3：查询语音库
+
+```bash
+# 一阶精准查询
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "https://api.soke.cn/api/v1/ai-training/role-voices?gender=female&age_group=middle-aged&lang=zh"
+
+# 降级链路同头像
+```
+
+**返回字段**：`id`（语音资源 ID，**回填时用这个**）、`name`、`gender`、`age_group`、`sample_url`。
+
+### 步骤 4：特征匹配（与 CLI 路径相同的匹配规则）
+
+性别映射 → `../references/role-resource-matching.md`「性别映射表」
+年龄段映射 → `../references/role-resource-matching.md`「年龄段映射表」
+匹配优先级 → `../references/role-resource-matching.md` P0-P3 降级链路
+
+### 步骤 5：写入 avatar + voice_id 到角色级 JSON
+
+> ⚠️ **必须随角色主体单次写入**，禁止先写角色再分两次补 avatar/voice_id（分开调用导致 updated_at 竞态，第二次可能覆盖第一次结果）。REST API 兜底路径如需 PATCH，也必须把 avatar 与 voice_id 放在同一个角色级操作里。
+
+```bash
+# 1. 先获取最新 updated_at
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "https://api.soke.cn/api/v1/ai-training/scenarios/<scenario_id>" \
+  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['data']['updated_at'])"
+
+# 2. 写入含 avatar + voice_id 的角色级操作
+curl -s -X PATCH \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "operations": [
+      {
+        "type": "patch_ai_role",
+        "data": {
+          "scenario_role_id": "<角色ID>",
+          "patch": {
+            "role_data": {
+              "avatar": "<头像URL>",
+              "voice_id": "<语音ID>"
+            },
+            "customized_fields": ["avatar", "voice_id"]
+          }
+        }
+      }
+    ],
+    "base_updated_at": "<updated_at>",
+    "idempotency_key": "api-<scenario_short>-part2-resources",
+    "reason": "Part2: 头像声音资源匹配 (REST API)"
+  }' \
+  "https://api.soke.cn/api/v1/ai-training/scenarios/<scenario_id>"
+```
+
+### 步骤 6：强制验证
+
+```bash
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "https://api.soke.cn/api/v1/ai-training/scenarios/<scenario_id>" \
+  | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+for r in d['data']['ai_roles']:
+    rd = r.get('role_data', {})
+    avatar = rd.get('avatar', '')
+    voice = rd.get('voice_id', '')
+    status = 'OK' if (avatar.startswith('http') and voice) else 'MISSING'
+    print(f'{r[\"name\"]}: avatar={avatar[:50]}... voice_id={voice} [{status}]')
+"
+# 期望输出：每个角色 avatar 以 https:// 开头，voice_id 非空
+```
+
+### 步骤 7：重试与降级
+
+- 验证发现 avatar/voice_id 为空 → 重新 GET `updated_at` → 重试 1 次
+- 重试仍失败 → 标注「⚠️ {角色名} 资源匹配未完成 (REST API)」，不阻断 Part3
+- 头像/语音库 API 查询失败（网络/认证错误）→ 跳过资源匹配，标注「资源匹配未完成」
+
+## 执行规则
+
+### 安全规则
+
+1. **Token 安全**：`user_token` 只在内部使用，严禁写入对话窗口、JSON 文件或日志
+2. **请求验证**：每次 API 调用前，先 GET 获取最新 `updated_at`，避免并发冲突
+3. **错误处理**：4xx 检查字段格式 → 5xx 重试 1 次 → 仍失败则标注并记录
+
+### API fallback 执行流程
+
+```
+检测 soke-cli 不可用
+  → 获取 Token (soke-cli config show 或引导用户获取)
+  → 确认 Token 有效 (GET /api/v1/auth/verify)
+  → 按原管线顺序执行:
+    Part1: POST 创建场景 → 获取 scenario_id
+    Part2: 头像语音匹配（走「资源匹配完整流程」）→ PATCH 更新角色并回读
+    Part3: PATCH 更新流程
+    Part4: PATCH 更新评分
+    Part5: PATCH 更新教练设置
+  → Step 6: GET 验证同步完整性
+  → Step 7: 质量闸门
+  → Step 8: POST 发布场景
+```
+
+### 与 soke-cli 的差异
+
+| 项目 | soke-cli | REST API fallback |
+|------|----------|-------------------|
+| preview 预览 | `+preview-scenario-update` 输出 diff | 无 preview，直接 PATCH（可在 PATCH 前 GET 对比） |
+| 沙箱绕过 | `dangerouslyDisableSandbox: true` | 不适用（HTTP 请求不受沙箱限制） |
+| 命令速查 | `verified-cli-cheatsheet.md` | 本文件 |
+| 字段映射 | `sync-engine.md` 字段映射表 | 相同映射表，JSON 结构一致 |
+| 头像语音查询 | CLI `+list-role-avatars/voices` | GET API 端点 |
+
+> API fallback 路径下，JSON 文件结构、字段映射、自查清单与 soke-cli 路径完全一致。差异仅在传输方式：CLI 命令行 vs HTTP 请求。

package/skills/ai-coach-director/platform/interaction.md

@@ -26,7 +26,7 @@ AskUserQuestion(
 - 模糊匹配时优先正向操作（选项 1）
 -
 name: interaction
-description: AI 陪练弹窗交互规则。定义按 Part1-Part5 拆分的通用确认模板与微调模板。优先弹窗确认：WebChat 主会话用 render_ui 的 QuestionForm，workbuddy 子 agent 用 AskUserQuestion，纯文本平台降级结构化文本。
+description: AI 陪练弹窗交互规则。定义按 Part1-Part5 拆分的通用确认模板与微调模板。跨平台适配：WorkBuddy 用 AskUserQuestion/render_ui，悟空/QClaw/Zework 用结构化文本编号（统一路由到 platform/adapters/）。
 ---
 
 # 弹窗交互规则
@@ -46,9 +46,12 @@ description: AI 陪练弹窗交互规则。定义按 Part1-Part5 拆分的通用
 
 1. **Part1 确认后强制同步到平台**：模板 1 不提供"取消"或"跳过同步"选项；用户确认即意味着场景必须创建到平台
 2. Part2-Part5 确认后自动 preview + apply CLI，立即进入下一个 Part，不等待用户二次确认
-3. 调整/重设/微调分支由用户选择驱动，`prompt-engineer` / `prompt-optimizer` 按返回值分支处理
-4. **优先使用弹窗确认**：弹窗策略按运行环境三分层——① WebChat 主会话：使用 `render_ui` 的 QuestionForm jsonl（参考附录 A）；② workbuddy 子 agent：使用 `AskUserQuestion` 工具弹窗（参考附录 A）；③ 纯文本平台（群聊、IM 无按钮）：降级为结构化文本确认。选项文案和分支路由三平台完全一致
-5. **选项文案和分支路由不因渲染方式而变化**：渲染机制不同但选项名称和路由完全一致，用户始终只需点击按钮或回复编号做出选择
+3. Part1 封面生成/上传/修正属于后台自动处理步骤；Part2 头像/语音匹配、逐个保守写角色、回读校验也属于后台自动处理步骤。除非失败，不向用户展示过程细节
+4. Part2-Part5 默认优先走 `--request-file ./partX-update.json` 的完整请求模式；`--operations-file ./partX-operations.json` 仅作为排障/降级模式
+5. 若 Part3 按标准语义操作 apply 后回读仍为空，必须明确提示当前 CLI/平台版本限制，并引导改走 Web 管理后台补录流程步骤
+6. 调整/重设/微调分支由用户选择驱动，`prompt-engineer` / `prompt-optimizer` 按返回值分支处理
+7. **优先使用弹窗确认**：弹窗策略按运行环境自适应——① WorkBuddy：使用 `AskUserQuestion` 工具弹窗（参考附录 B）；② WebChat 主会话：使用 `render_ui` 的 QuestionForm jsonl（参考附录 A）；③ 悟空/QClaw/Zework：降级为结构化文本编号确认（参考 `adapters/` 对应平台适配器）；④ 通用降级：纯文本编号。选项文案和分支路由所有平台完全一致
+8. **选项文案和分支路由不因渲染方式而变化**：渲染机制不同但选项名称和路由完全一致——WorkBuddy 弹窗按钮、悟空钉钉编号回复、QClaw 微信编号回复、Zework 纯文本编号，用户始终只需回复编号或完整选项文案做出选择
 
 ---
 
@@ -116,7 +119,7 @@ description: AI 陪练弹窗交互规则。定义按 Part1-Part5 拆分的通用
 
 | # | 选项文案 | 分支动作 |
 |---|---------|---------|
-| 1 | 确认，同步角色（推荐） | 生成 `part2-operations.json` → 自动 preview + apply → 立即继续 Part3 |
+| 1 | 确认，同步角色（推荐） | 完整展示 Part2 后，后台自动拆分 Part2 为多个角色级同步单元（角色1/角色2/角色3/整体OS），逐个保守写入并回读校验 → 全部成功后继续 Part3 |
 | 2 | 调整角色设定 | 局部修改后重新用本模板确认 |
 | 3 | 重设角色设定 | 回到内容层重新生成 Part2，再次用本模板确认 |
 
@@ -134,7 +137,7 @@ description: AI 陪练弹窗交互规则。定义按 Part1-Part5 拆分的通用
 
 | # | 选项文案 | 分支动作 |
 |---|---------|---------|
-| 1 | 确认，同步流程设置（推荐） | 生成 `part3-operations.json` → 自动 preview + apply → 立即继续 Part4 |
+| 1 | 确认，同步流程设置（推荐） | 生成 `part3-operations.json` + `part3-update.json` → 默认用 `--request-file ./part3-update.json` 自动 preview + apply → 立即继续 Part4；若回读仍为空则提示改走 Web 管理后台补录 |
 | 2 | 调整流程设置 | 局部修改后重新用本模板确认 |
 | 3 | 重设流程设置 | 回到内容层重新生成 Part3，再次用本模板确认 |
 
@@ -152,7 +155,7 @@ description: AI 陪练弹窗交互规则。定义按 Part1-Part5 拆分的通用
 
 | # | 选项文案 | 分支动作 |
 |---|---------|---------|
-| 1 | 确认，同步评分（推荐） | 生成 `part4-operations.json` → 自动 preview + apply → 继续 Part5 |
+| 1 | 确认，同步评分（推荐） | 生成 `part4-operations.json` + `part4-update.json` → 默认用 `--request-file ./part4-update.json` 自动 preview + apply → 继续 Part5 |
 | 2 | 调整评分标准 | 局部修改后重新用本模板确认 |
 | 3 | 重设评分标准 | 回到内容层重新生成 Part4，再次用本模板确认 |
 
@@ -170,7 +173,7 @@ description: AI 陪练弹窗交互规则。定义按 Part1-Part5 拆分的通用
 
 | # | 选项文案 | 分支动作 |
 |---|---------|---------|
-| 1 | 确认，完成创建（推荐） | 生成 `part5-operations.json` → 自动 preview + apply → 输出完成摘要 |
+| 1 | 确认，完成创建（推荐） | 生成 `part5-operations.json` + `part5-update.json` → 默认用 `--request-file ./part5-update.json` 自动 preview + apply → 进入资源完善与发布闸门 → 通过后才输出完成摘要 |
 | 2 | 调整教练设置 | 局部修改后重新用本模板确认 |
 | 3 | 重设教练设置 | 回到内容层重新生成 Part5，再次用本模板确认 |
 
@@ -188,7 +191,7 @@ description: AI 陪练弹窗交互规则。定义按 Part1-Part5 拆分的通用
 
 | # | 选项文案 | 分支动作 |
 |---|---------|---------|
-| 1 | 确认修改（推荐） | 生成 `optimize-operations.json` → 执行 CLI 同步 |
+| 1 | 确认修改（推荐） | 生成 `optimize-operations.json` + `optimize-update.json` → 默认用 `--request-file ./optimize-update.json` 执行 CLI 同步 |
 | 2 | 保持原样 | 退出微调流程，记录决策到状态快照 |
 | 3 | 调整诊断 | 局部修改标签归属后重新用本模板确认 |
 
@@ -252,7 +255,7 @@ description: AI 陪练弹窗交互规则。定义按 Part1-Part5 拆分的通用
 ### 与 sync-engine.md 的边界
 
 - interaction.md：负责确认契约（问题和选项）、确认输出规范、用户响应后的分支路由
-- sync-engine.md：负责「确认后」的 JSON 生成、字段映射、CLI 命令拼接
+- sync-engine.md：负责「确认后」的 JSON 生成、字段映射、CLI 命令拼接（默认 `partX-update.json`，排障时退回 `partX-operations.json`）
 - interaction 确认后 → 调用 sync-engine 对应模板 → 执行 CLI → 返回结果
 
 ---

package/skills/ai-coach-director/platform/publish-gate.md

@@ -0,0 +1,44 @@
+# 发布闸门（publish-gate）
+
+> 内部规则文件。负责在发布前统一做结构验收、资源验收和平台限制说明。
+
+## 发布前检查清单
+
+### 结构验收
+- Part1 基础字段存在：`name/description/tags/key_points/scene_lang/scenario_cover`
+- Part2 角色回读正常：无 `角色数据异常`
+- Part4 评分配置存在：`scoring_criteria_config.criteria_data.dimensions` 非空
+- Part5 固定配置有效
+
+### 资源验收
+- `scenario_cover` 非默认图
+- 每个角色 `avatar` 非空 URL
+- 每个角色 `voice_id` 非空 ID
+
+### 平台限制说明
+- 若 `conversation_steps` 回读为空，标记：`需后台手动补录流程步骤`
+- 该项默认不阻断发布，但必须进入最终交付摘要
+
+## 阻断规则
+
+以下情况任一成立，禁止发布：
+- 默认封面未替换
+- 任一角色头像为空
+- 任一角色声音为空
+- 任一角色回读为 `角色数据异常`
+- 评分标准为空
+
+## 输出要求
+
+### 可发布
+输出：
+- `publish_ready = true`
+- 可执行 `soke-cli ai-training +publish-scenario`
+
+### 不可发布
+输出缺口清单，例如：
+- 封面未补齐
+- 角色何女士缺少 voice_id
+- 角色陆先生缺少 avatar
+
+并停止发布。

package/skills/ai-coach-director/platform/resource-finalizer.md

@@ -0,0 +1,128 @@
+# 资源完善器（resource-finalizer）
+
+> 内部规则文件。作为**最后兜底补救**，仅在 Part1/Part2 的主流程未能写入真实封面/头像/声音时触发。
+> 正常流程下，封面在 Part1 确定、头像和声音在 Part2 与角色一起写入，不需要进入本模块。
+> 本模块默认后台执行，除非修复失败，不向用户暴露执行细节。
+> ⚠️ 本地生成或复用的封面/图片均为后台资源，不得在前台展示图片预览，不得主动输出本地图片路径。只有用户明确要求查看/预览/导出图片时，才可提供路径或展示。
+
+## 目标
+
+避免以下半成品状态进入发布：
+- `scenario_cover` 仍为默认封面或为空
+- 任一角色 `avatar` 为空
+- 任一角色 `voice_id` 为空
+
+## 执行时机
+
+仅在发布闸门检测到资源缺口，且无法通过主流程自动补齐时触发。正常流程默认不进入本模块。
+
+```
+Part1-Part5 主体完成
+  → resource-finalizer
+    → cover check / fix
+    → avatar check / fix
+    → voice check / fix
+    → resource gate
+  → 通过后才允许 publish
+```
+
+## 资源闸门
+
+### Cover Gate
+以下任一情况判定为未完成：
+- `scenario_cover` 为空
+- `scenario_cover` 为 `null`
+- URL 包含 `default.png`
+
+### Avatar Gate
+对每个角色检查：
+- `role_data.avatar` 必须为非空 URL（以 `http` 开头）
+
+### Voice Gate
+对每个角色检查：
+- `role_data.voice_id` 必须为非空 ID
+
+### Role Integrity Gate
+对每个角色检查：
+- `role_data.name` 不能等于 `角色数据异常`
+- `role_data.background` 非空
+
+## 封面补齐规则
+
+### 标准流程
+1. 检查 `scenario_cover` 是否为默认图或为空
+2. 若是，按以下优先级补齐：
+
+**优先级 0：默认固定封面回填**
+- 默认使用：`https://newsokeeditorcdn.soke.cn/public/ai/cover/lingshou_daogou.png`
+- 直接用 `update_basic.scenario_cover` 回填该真实 URL
+- `get-scenario` 验证不再为空且为该固定封面
+
+**优先级 1：从平台图片库/已有真实封面库择图**
+- 若业务明确要求替换默认图，再按行业、业务环节、场景气质筛选图片库素材
+- 若当前环境只有场景封面库能力，则执行 `soke-cli ai-training +list-scenarios --page 1 --page-size 50 --status published --pretty`
+- 从结果中筛出非 `default.png` 的 `scenario_cover`，选择与当前场景最匹配的一条
+- 使用 `update_basic.scenario_cover` 回填该真实 URL
+- `get-scenario` 验证不再为空且非默认图
+
+**优先级 2：复用工作区已有本地封面文件**
+- 按顺序检查：`./scenario-cover.png` → `./scenario-cover.jpg` → `./cover.png` → `./cover.jpg`
+- 若存在，执行 `soke-cli ai-training +upload-scenario-cover --file <本地文件> --pretty`
+- 使用 `update_basic.scenario_cover` 回填真实 CDN URL
+- `get-scenario` 验证不再是默认图
+
+**优先级 3：本地生成封面**
+- 仅当默认图、平台图库/封面库和本地现成图都不可用时，再生成本地封面图 `scenario-cover.png`
+- 生成后仅做后台内部检查，不调用前台图片预览，不向用户展示图片
+- 执行 `soke-cli ai-training +upload-scenario-cover --file ./scenario-cover.png --pretty`
+- 使用 `update_basic.scenario_cover` 回填真实 CDN URL
+- `get-scenario` 验证不再是默认图
+- 若上传失败、未拿到真实 CDN URL、或平台回读仍为空/默认图，则视为“封面未补齐”，禁止发布，不得把“本地已生成文件”误判为已完成
+
+**优先级 3：最终兜底**
+若以上均不可行：
+- 标注 `cover_pending`
+- 禁止发布
+- 在交付摘要中提醒用户手动补封面
+
+### 失败处理
+- 上传失败或平台图库不可用 → 降级到下一优先级
+- 全部降级链路失败 → 标注 `cover_pending`，禁止发布
+
+## 头像补齐规则
+
+### 标准流程
+1. 对每个角色检查 `avatar`
+2. 若为空，按 `../references/role-resource-matching.md` 查询头像库并匹配
+3. 用 `patch_ai_role` 回填 `avatar`
+4. `get-scenario` 验证头像非空 URL
+
+### 失败处理
+- 查询失败或回填失败 → 标注 `avatar_pending`，禁止发布
+
+## 语音补齐规则
+
+### 标准流程
+1. 对每个角色检查 `voice_id`
+2. 若为空，按 `../references/role-resource-matching.md` 查询语音库并匹配
+3. 用 `patch_ai_role` 回填 `voice_id`
+4. `get-scenario` 验证语音非空
+
+### 失败处理
+- 查询失败或回填失败 → 标注 `voice_pending`，禁止发布
+
+## 默认回填策略
+
+- 头像和语音允许逐个角色回填
+- 若资源库查询结果不足，可使用保守默认资源
+- **宁可回填一套保守默认资源，也不要留空进入发布**
+
+## 发布前最终判定
+
+只有以下全部满足时，才允许执行 `+publish-scenario`：
+- 封面非默认图
+- 所有角色头像非空 URL
+- 所有角色声音非空 ID
+- 无“角色数据异常”
+
+否则输出缺口清单并停止在发布前。