@sokeai/cli 1.0.77 → 1.0.78

package/skills/multi/soke-ai-coach-director/references/subs/part2/SOP.md

@@ -0,0 +1,34 @@
+# Part2 角色生成与同步子 SOP
+
+> 由 SKILL.md Step 5 调用。生成前先读 `coaching/prompt-engineer/parts/part2-roles.md` 加载内容框架。执行遵循「展示 → 自检 → 弹窗确认（模板2）→ 后台资源匹配+整包同步」。
+
+## 角色结构（1 OS + N 角色）
+
+每种顾客状态必须拆为**独立角色**（禁止单角色内部状态机切换）。每角色含：name / description / communication_style / background（四段画像）/ personality_type（单 MBTI）/ personality / tags / knowledge_level / taboos_objections。
+
+## 关键结构规则
+
+- `replace_ai_roles` 数据键 `data.roles`（非 `data.ai_roles`）— 最高频错误。
+- 外壳 10 字段（scenario_role_id / customization_level="full" / is_custom_role=true / customized_fields 列全 12 字段 / created_at / updated_at / template_id=null / template_name=null / template_version=null）在 `role_data` 外层；`source_type="custom"` 在 `role_data` 内。
+- `avatar` 写 URL（`+list-role-avatars` 的 `url`），`voice_id` 写 ID（`+list-role-voices` 的 `id`）。
+- 资源匹配后台执行（见 `role-resource-matching.md`），随整包一次写入，不二次确认。
+
+## 同步写入策略
+
+默认整包 `replace_ai_roles` 一次写全部角色 + OS（OS 用 update_basic 单独写）。整包失败降级为逐个 `add_ai_role` + 单独 update_basic 写 OS。
+
+### 异常处理：最小稳定结构降级
+
+回读出现 `name="角色数据异常"` / 字段 null 时：
+1. **字段级排雷**：personality_type 收敛单值、source_type 内外层不重复、customized_fields 与实际字段一致。
+2. **最小稳定结构重试**：仅保留 name/description/communication_style/background/avatar/voice_id，移除 knowledge_level/taboos_objections/tags/personality。
+3. **回读即准**：name≠"角色数据异常"、background 四段完整、avatar/voice_id 非空、OS 非空。
+4. **禁止带病续流**：仍有异常停在 Part2，不进 Part3。
+
+## background 强制闸门
+
+生成 JSON 后 preview 前：逐字比对 JSON 的 background 与展示文本一致 + 四段画像完整，任一不过驳回修正。
+
+## 自查清单（14 项）
+
+1. `data.roles`（非 data.ai_roles）；2. 每角色含 scenario_role_id；3. 角色数≥2；4. name 非空；5. description 非空；6. background 四段完整；7. communication_style 非空；8. personality_type 单值；9. avatar 非空 URL；10. voice_id 非空 ID；11. 外壳字段在外层、source_type 在 role_data 内；12. OS 非空；13. background 展示=JSON 一致；14. 无空 background。

package/skills/multi/soke-ai-coach-director/references/subs/part3/SOP.md

@@ -0,0 +1,27 @@
+# Part3 流程设置同步子 SOP
+
+> 由 SKILL.md Step 5 调用。生成前先读 `coaching/prompt-engineer/parts/part3-flow.md` 加载内容框架。环节数 3-7、每阶段 3-5 轮、编号连续。
+
+## 原子性约束
+
+开场语（update_basic）+ 所有环节（add_conversation_step）必须合并为**同一批 operations 一次 preview+apply**，禁止拆分多次。失败则整个 Part3 判失败，不允许部分成功静默续流。
+
+## 回读判定矩阵（preview 证据优先于 get-scenario）
+
+| preview 证据 | get-scenario 回读 | 判定 |
+|-------------|-------------------|------|
+| opening + steps 双项有 add 证据 | 双项非空 | ✅ 通过 |
+| 双项有证据 | opening 非空、steps 为空 | ✅ 通过（CLI bug 白名单） |
+| opening 无证据 | 任意 | ❌ 失败 |
+| steps 无 add 证据 | steps 为空 | ❌ 失败 |
+| preview/apply 报错 | 任意 | ❌ 失败 |
+
+核心原则：preview 确认平台接收了操作即视为原子成功；get-scenario 回读 `conversation_steps` 为空是 CLI 已知 bug（v1.0.65+），不改变成功判定。
+
+## 已知 CLI 回读口径差异
+
+`add_conversation_step` apply 返回成功但 get-scenario 回读 `conversation_steps: []`，opening_dialogue 也可能不同步反映——这是已知差异，不代表数据未写入。验收时 preview/apply 成功即默认进 Part4，记录「平台回读异常待观察」，不要求先去 Web 后台确认。仅 preview/apply 本身失败才停下排查。
+
+## 自查清单（8 项）
+
+1. opening_dialogue_type 固定整数 1；2. 每环节含 step_name/student_objective/ai_task/max_rounds；3. 编号从 1 连续；4. 无空缺；5. 字段结构正确；6. opening_dialogue 第一人称无后台痕迹；7. information 不含考核/评分信息；8. status=1。

package/skills/multi/soke-ai-coach-director/references/subs/part4/SOP.md

@@ -0,0 +1,31 @@
+# Part4 评分配置同步子 SOP
+
+> 由 SKILL.md Step 5 调用。生成前先读 `coaching/prompt-engineer/parts/part4-scoring.md` 加载内容框架。`scoring_rule`/`criteria` 禁止示例对话，一票否决嵌入各维度 scoring_rule 末尾。
+
+## shell 字段位置铁律（v2.26 硬阻断）
+
+4 个 shell 字段必须写在 `data.config` **顶层**，不能放进 `criteria_data` 内（错放导致 UI 显示"请选择或创建评分标准"，API 不报错 warnings=[]）：
+
+| 字段 | 必须位置 |
+|------|---------|
+| `scenario_criteria_id` | `data.config` 顶层 |
+| `customization_level="full"` | `data.config` 顶层 |
+| `is_custom_criteria=true` | `data.config` 顶层 |
+| `customized_fields=["criteria_data"]` | `data.config` 顶层 |
+
+`criteria_data` 内只放业务字段：`name` / `description` / `dimensions` / `total_weight` / `source_type="enterprise"` / `status=1` / `tags`。
+
+apply 后 get-scenario 回读确认 shell 字段在 `scoring_criteria_config` 顶层全部存在，任一缺失 = 失败，调整后重新 apply。
+
+## 执行流程
+
+用户确认 → 生成 part4-operations.json → 对照自查清单 → preview → apply → get-scenario 回读验证 shell 字段位置 + 权重和 100。
+
+## 自查清单（19 项，关键项）
+
+**shell 位置**：1. config 顶层含 scenario_criteria_id；2. customization_level="full"；3. is_custom_criteria=true；4. customized_fields=["criteria_data"]（均不在 criteria_data 内）。
+**业务字段**：5. 用 replace_scoring_criteria_config；6. data.config.criteria_data 三层嵌套；7. 维度≥2；8. 权重和=100；9. 每维度含名称/权重/评分规则/评分点；10. scoring_rule 无示例对话；11. 一票否决嵌入维度末尾；12. 无全局 one_vote_veto；13. 每维度≥2 评分点；14. status=1；15. source_type="enterprise"；16. tags 非空；17. 每维度含 id（dim_{code}）；18. sort_order 数字；19. apply 后回读 shell 字段在顶层。
+
+## 评分维度设计原则
+
+维度数：简单场景 3-4、复杂 4-5；权重：沟通类 50-60%、专业类 40-50%；一票否决格式"以下行为触犯即该维度 0 分且总分不合格：…"。

package/skills/multi/soke-ai-coach-director/references/subs/publish/SOP.md

@@ -0,0 +1,81 @@
+# 场景发布与交付子 SOP
+
+> 由 SKILL.md Step 6-9 调用。执行前已通过 Step 5 全部 Part 验收。
+
+## Step 6: 平台同步验证
+
+1. 读取 `state-snapshot.json`，验证所有 Part 的 `applied` 均为 `true`
+2. 执行 `soke-cli ai-training +get-scenario --scenario-id <id> --pretty`
+3. 逐字段验证：
+   - `key_points`、`description`、`name` → 与 `step1-create.json` 一致
+   - `ai_roles` 非空 + `role_data.name` ≠ "角色数据异常"
+   - `scoring_criteria_config` 维度数/名称/权重与 part4-operations.json 一致
+   - 练习配置与 part5-operations.json 一致
+4. 记录 `scenario_id` 和平台 URL
+
+> 🚦 闸门：所有 Part `applied: true` + 关键字段一致。
+
+---
+
+## Step 7: 创建质量闸门（v2.39 精简：12 项 → 3 项补查）
+
+内部检查，不在对话窗展示逐项明细。通过后仅输出 `✅ 质量闸门全部通过`。
+
+> **v2.39 精简规则**：Part1-5 自检全部通过后，12 项中 9 项自动视为通过（与 Part 自检重叠）。仅补查以下 3 项：
+
+| # | 检查项 | 来源步骤 | 不通过处理 | v2.39 |
+|---|--------|---------|-----------|--------|
+| 1 | 材料完整 | Step 1 | 返回 Step 1 | ↔Part1自检（跳过） |
+| 2 | 场景拆解合理 | Step 2 | 返回 Step 2 | ↔Step2确认（跳过） |
+| 3 | 角色行为化 | Part2 | 返回 Part2 | ↔Part2自检（跳过） |
+| 4 | 信息释放规则明确 | Part2 | 返回 Part2 | ↔Part2自检（跳过） |
+| 5 | 每阶段进入/退出条件 | Part3 | 返回 Part3 | ↔Part3自检（跳过） |
+| 6 | 评分可识别（一票否决嵌入） | Part4 | 返回 Part4 | ↔Part4自检（跳过） |
+| 7 | 练习配置匹配固定模板 | Part5 | 返回 Part5 | ↔Part5自检（跳过） |
+| 8 | 有测试用例 | - | 补充 | ⚡仅闸门（🟡可选） |
+| 9 | 整体设定 ≤ 3000 字 | Part2 | 压缩 | ⚡仅闸门 |
+| 10 | 每个 Part 已完整展示 | Step 5 | 重展示 | ⚡仅闸门 |
+| 11 | Part2-Part5 完整度 ≥ Part1 | Step 5 | 补展示 | ↔Part自检（跳过） |
+| 12 | 封面/图片未前台展示 | - | 修正 | ↔Part1自检（跳过） |
+
+---
+
+## Step 8: 发布闸门（资源兜底）
+
+1. 资源收官：`platform/resource-finalizer.md`
+   - 固定封面存在
+   - 所有角色头像补齐
+   - 所有角色语音补齐
+2. 发布验门：`platform/publish-gate.md`
+   - 封面非空
+   - avatar 全部非空 URL
+   - voice_id 全部非空 ID
+   - 无"角色数据异常"
+3. 任一失败 → 停止发布 → 输出缺口清单
+4. 全部通过 → Step 9
+
+---
+
+## Step 9: 场景发布
+
+```bash
+soke-cli ai-training +publish-scenario \
+  --scenario-id <scenario_id> \
+  --version 1 \
+  --version-description "CLI发布" \
+  --pretty
+```
+
+发布后验收：`+get-scenario --scenario-id <id> --pretty` 确认状态。
+
+> 🚦 闸门：发布成功后方可交付。
+
+---
+
+## 发布后：知识打包（🚦 v2.27 强制弹窗，用户可选跳过）
+
+🚦 **强制闸门**：发布成功后必须触发知识包确认弹窗（模板 7），不可静默跳过。
+
+触发条件：所有创建型流程均须弹出模板 7。资料含"话术/SOP/障碍应对/标准提问"时，弹窗额外提示"检测到话术素材，建议同步知识包"。
+
+流程：发布成功 → 弹模板 7 → 用户选择 → 确认则 `knowledge-packager` 提炼 → `+sync` → `+bind-scenario` → 回读验收；跳过则记录状态并输出"知识包可到平台后台手动上传"提示。

package/skills/multi/soke-ai-coach-director/references/subs/tune/SOP.md

@@ -0,0 +1,92 @@
+# 微调任务子 SOP
+
+> 由 SKILL.md「微调型任务流程」调用。
+
+## 执行流程
+
+### 1. 收集微调输入包
+
+必须尽量收集：
+- 当前提示词
+- 原始对话记录
+- 用户反馈原话
+- 期望表现
+- 场景类型
+- 当前评分结果
+- 音频/转写文本（如涉及语音）
+- 设备/账号/操作路径（如涉及技术）
+
+### 2. 🚨 确认分析对象
+
+在陪练对话中，"AI"和"学员"是两个不同角色。诊断前必须先声明：
+- 本次分析对象是 **AI（客户角色）** 还是 **学员**
+- AI 模拟客户让学员练习的场景中，诊断对象为 AI（客户角色）
+
+### 3. 技术分流
+
+凡涉及以下问题，优先按技术处理，**不直接改提示词**：
+- ASR 识别错误
+- 语音尾字丢失
+- TTS 声音不符
+- 播报未结束就跳评分页
+- 授权不同步
+- 部门同步失败
+- 按钮报错
+- iOS 录音权限
+- 评分等待无提示
+
+### 4. 诊断标签
+
+按严格顺序打标签：
+
+```
+T排障 → O拟真 → P指令执行 → N自然度 → I信息释放/K知识 → E结束/S场景 → L逻辑/F格式 → R评分
+```
+
+| 标签 | 含义 | 判定要点 |
+|------|------|---------|
+| T | 技术/体验 | ASR/TTS/权限/跳转 |
+| O | 角色OOC | 太热情/太攻击/不该说的术语 |
+| P | 指令执行度 | AI 行为与提示词指令不一致 |
+| N | 自然度 | 模板化、万能回应、句式单一 |
+| I | 信息释放 | 开场透露全部症状/底线 |
+| K | 知识/合规 | 产品知识错误、禁用话术 |
+| E | 结束违规 | 提前结束、成交后追问 |
+| S | 场景规则 | 药房/合规/B2B 场景规则 |
+| L | 逻辑违规 | 信任值异常、价格防线 |
+| F | 格式违规 | 括号动作、Markdown、后台痕迹 |
+| R | 评分规则 | 评分项抽象、目标错位 |
+| D | 数据/看板 | 指标口径、数据污染 |
+
+**没有标签，不进入修改建议。**
+
+### 5. 匹配资产库
+
+按需选读 `references/cases/` 下对应资产。
+
+### 6. 调度 prompt-optimizer
+
+输出标注版改稿、复测方案、版本记录建议。
+
+---
+
+## 缺失规则
+
+| 缺失项 | 处理方式 |
+|--------|---------|
+| 无原始对话 | 只能做结构审查，不断言具体行为偏差 |
+| 无当前提示词 | 只能给优化方向，不输出最终修改版 |
+| 只有"感觉不像" | 追问具体对话片段或期望表现 |
+
+---
+
+## 微调闸门（8 项）
+
+1. 有证据
+2. 已技术分流
+3. 已打标签
+4. 有修改决策
+5. 有标注改稿
+6. 有复测方案
+7. 有版本记录建议
+8. 微调后「整体设定」节去空白字符 ≤ 3000

package/skills/multi/soke-ai-coach-director/references/verified-cli-cheatsheet.md

@@ -0,0 +1,56 @@
+# MentorAI CLI 已验证命令清单
+
+> 标准命令速查。统一 `soke-cli ai-training +...`，不省略 `ai-training`。所有 soke-cli 命令经 Bash 执行必须设 `dangerouslyDisableSandbox: true`。
+> **v2.37：所有命令输出一律 `> /tmp/xxx.json 2>/dev/null` 重定向，禁止 `--pretty` 直出到对话。** Python 从重定向文件提取字段。
+
+## 核心命令
+
+```bash
+# 创建场景（Part1）— 重定向，Python 提取 scenario_id
+soke-cli ai-training +create-scenario --request-file ./part1-create.json > /tmp/part1_create.json 2>/dev/null
+
+# 读场景（每次 preview/apply 前先取最新 updated_at；apply 后 --raw 验收）— 重定向
+soke-cli ai-training +get-scenario --scenario-id <id> --raw > /tmp/scenario_get.json 2>/dev/null
+
+# 预览/应用（默认 request-file 模式）— 重定向，Python 提取 updated_at
+soke-cli ai-training +preview-scenario-update --scenario-id <id> --request-file ./partX-update.json > /tmp/partX_preview.json 2>/dev/null
+soke-cli ai-training +apply-scenario-update --scenario-id <id> --request-file ./partX-update.json > /tmp/partX_apply.json 2>/dev/null
+
+# 排障退回 operations 模式（apply 必传 --idempotency-key，preview 不传；两者都要 --reason）
+soke-cli ai-training +preview-scenario-update --scenario-id <id> --operations-file ./partX-operations.json --base-updated-at <updated_at> --reason "PartX: 说明" > /tmp/partX_preview.json 2>/dev/null
+soke-cli ai-training +apply-scenario-update --scenario-id <id> --operations-file ./partX-operations.json --base-updated-at <updated_at> --idempotency-key "cli-<short>-partX-apply" --reason "PartX: 说明" > /tmp/partX_apply.json 2>/dev/null
+```
+
+## 知识包 / 发布 / 快照
+
+```bash
+# 知识包同步 + 绑定 — 重定向
+soke-cli ai-training +sync --manifest ./knowledge-package.json --idempotency-key "cli-<package_id>-sync" > /tmp/kb_sync.json 2>/dev/null
+soke-cli ai-training +bind-scenario --scenario-id <id> --version-ids <version_id> --compile-plan > /tmp/kb_bind.json 2>/dev/null
+
+# 发布 — 重定向
+soke-cli ai-training +publish-scenario --scenario-id <id> --version 1 --version-description "CLI发布" > /tmp/publish.json 2>/dev/null
+
+# 快照查询 / 恢复（排障）— 重定向
+soke-cli ai-training +list-scenario-snapshots --scenario-id <id> --page 1 --page-size 20 > /tmp/snapshots.json 2>/dev/null
+soke-cli ai-training +restore-scenario-snapshot --scenario-id <id> --snapshot-id <snapshot_id> --reason "回滚本次 CLI 更新" > /tmp/restore.json 2>/dev/null
+```
+
+## 资源库查询（Part2 头像/语音）— 重定向，Python 提取 URL/ID
+
+```bash
+# 头像 — 重定向到 /tmp/avatars.json，Python 提取 url 字段
+soke-cli ai-training +list-role-avatars --lang zh --show-detail > /tmp/avatars.json 2>/dev/null
+# 声音 — 重定向到 /tmp/voices.json，Python 提取 id 字段
+soke-cli ai-training +list-role-voices --lang zh > /tmp/voices.json 2>/dev/null
+```
+
+## ⚠️ v2.37 禁止事项
+
+- **禁止 `--pretty` 直出到对话**：所有命令输出必须重定向到 `/tmp/` 文件
+- **禁止用 apply 验证数据**：apply 是写入操作，验证用 `+get-scenario`。用 apply 回读环节会导致 `add_conversation_step` 重复添加
+- **禁止分多轮 sed 回看 PDF**：pdftotext 提取后一次性 grep+sed+Write 落盘提炼稿
+
+## 各 Part 文件名
+
+Part2-5 均生成 `partX-operations.json` + `partX-update.json`；微调 `optimize-operations.json` + `optimize-update.json`；全流程 `state-snapshot.json`（不出现聊天）。

package/skills/multi/soke-ai-coach-director/scripts/gate_check.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""
+soke-ai-coach-director · 闸门一次性校验器（v2.42）
+Usage:
+    python3 scripts/gate_check.py /tmp/scenario_get.json
+
+输入：+get-scenario 重定向后的 JSON 文件（自动处理 {data:{...}} 嵌套）
+输出：单行结果 —— 全过输出 "GATE PASS"，否则 "GATE FAIL" + 逐项失败原因
+退出码：0 = 通过，1 = 失败
+
+设计目的：消除闸门阶段逐字段拆轮探查（历史实测浪费 ~8 积分）。
+AI 只需跑这一个脚本，禁止再用 Python 逐步看返回结构。
+"""
+
+import json
+import sys
+
+
+def unwrap(raw):
+    """处理 CLI 返回的可能嵌套：{data:{...}} / {code,data} / 裸对象。"""
+    if not isinstance(raw, dict):
+        return raw
+    d = raw.get("data")
+    if isinstance(d, dict):
+        return d
+    return raw
+
+
+def check(sc: dict) -> list:
+    errs = []
+
+    # ---------- Step 8 发布闸门（4 项，任一缺失禁止发布） ----------
+
+    # 1. 封面 = 固定默认图（非空且正确前缀）
+    cover = sc.get("scenario_cover") or sc.get("cover")
+    if not cover or "roles_avatars" in str(cover) or not str(cover).startswith("http"):
+        errs.append(f"[发布1] 封面缺失或非法: {cover!r:.80}")
+
+    # 2/3. 全部角色 avatar / voice_id 非空
+    roles = sc.get("ai_roles") or []
+    if not roles:
+        errs.append("[发布2] ai_roles 为空")
+    for i, r in enumerate(roles):
+        rd = r.get("role_data") or r
+        av = rd.get("avatar")
+        vi = rd.get("voice_id")
+        if not av or not str(av).startswith("http"):
+            errs.append(f"[发布2] 角色{i}({rd.get('name','?')}) avatar 非法: {av!r:.60}")
+        if not vi:
+            errs.append(f"[发布3] 角色{i}({rd.get('name','?')}) voice_id 为空")
+
+    # 4. 无"角色数据异常"：OS 存在且足够长
+    os_text = sc.get("ai_roles_overall_description") or ""
+    if len(os_text) < 500:
+        errs.append(f"[发布4] OS 过短({len(os_text)}<500)，疑似角色数据异常")
+
+    # ---------- Step 7 补查 3 项（Part 自检已过的 9 项跳过） ----------
+
+    # 8. Part 内容完整：name/key_points/tags 非空
+    if not sc.get("name"):
+        errs.append("[闸门8] 场景名为空")
+    if not sc.get("key_points"):
+        errs.append("[闸门8] key_points 为空（检查 Part1 是否误写数组）")
+    if not (sc.get("tags") and len(sc.get("tags", [])) >= 3):
+        errs.append("[闸门8] tags 少于 3 个")
+
+    # 12. 整体设定 ≤ 3000 字
+    if len(os_text) > 3000:
+        errs.append(f"[闸门12] OS 超长({len(os_text)}>3000)")
+
+    # 5. Part3 环节存在（回读 conversation_steps 非空；空则提示 CLI 限制，不阻塞）
+    steps = sc.get("conversation_steps") or []
+    if not steps:
+        print("WARN: conversation_steps 为空——已知 CLI/平台限制，发布后走 Web 后台补录（不阻塞）")
+
+    # 6. Part4 评分维度存在且权重和 = 100
+    cd = ((sc.get("scoring_criteria_config") or {}).get("criteria_data")) or sc.get("criteria_data") or {}
+    dims = cd.get("dimensions") or []
+    if not dims:
+        print("WARN: 评分维度在 get 返回中不可见——以 Part4 自检 + apply 成功为准（不阻塞）")
+    else:
+        w = sum(d.get("weight", 0) for d in dims)
+        if w != 100:
+            errs.append(f"[闸门6→发布] 维度权重和={w}≠100")
+
+    return errs
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("Usage: gate_check.py <scenario_get.json>", file=sys.stderr)
+        return 1
+    try:
+        with open(sys.argv[1], encoding="utf-8") as f:
+            raw = json.load(f)
+    except Exception as e:
+        print(f"GATE FAIL: JSON 读取失败 {e}", file=sys.stderr)
+        return 1
+
+    sc = unwrap(raw)
+    errs = check(sc)
+    if errs:
+        print("GATE FAIL")
+        for e in errs:
+            print(f"  {e}")
+        return 1
+    print("GATE PASS")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())