@sokeai/cli 1.0.76 → 1.0.77

package/skills/ai-coach-director/references/role-resource-matching.md

@@ -1,349 +0,0 @@
-# Part2 平台资源自动匹配规则
-
-> 本节是 Part2 用户确认后、角色 JSON 生成前自动执行的资源匹配流程。头像和语音不在 Part2 内容展示阶段预设或展示，而是在后台查询系统资源库自动匹配，并随角色主体一次写入。
->
-> **v2.0 升级**：匹配模式从"拉全量→文本匹配"升级为"提取角色性别/年龄特征→CLI 参数精准过滤→取结果"，利用 CLI 原生的 `--gender` / `--age-group` 服务端过滤能力，提升匹配精度和效率。
-
-## 资源匹配时机
-
-Part2 完整内容已展示（先 OS，再逐个角色）并由用户确认 → 后台立即执行资源匹配流程 → 将 avatar URL 与 voice_id 写入角色级 JSON → 逐个角色 apply + 回读验证。资源匹配、写入、回读校验不等待用户触发，也不向用户二次确认。
-
----
-
-## 前置步骤：从角色卡提取性别与年龄
-
-在执行任何 CLI 查询之前，必须先从每个角色的 `role_data` 中提取性别和年龄段特征，映射为 CLI 参数：
-
-### 性别映射表（gender）
-
-| 角色描述中的特征词 | → gender |
-|---|---|
-| 男、先生、他、男士、男性、（男性名字：建国/振国/志强/伟等） | `male` |
-| 女、女士、她、太太、小姐、女性、（女性名字：芳/丽/敏/娟/婷等） | `female` |
-| 无明显性别特征 | 不传 `--gender` |
-
-> **提取优先级**：角色名称(.name) > 角色描述(.description) > 角色背景(.background) > MBTI+沟通风格交叉推断
-
-### 年龄段映射表（age_group）
-
-| 角色描述中的特征词 | → age_group |
-|---|---|
-| 青年、年轻、刚毕业、新手、25-35、初级、新入职、小张/小李等年轻称呼 | `youth` |
-| 中年、35-50、资深、经理、主管、部门负责人、有多年经验 | `middle-aged` |
-| 老年、50+、退休、资深专家、老前辈、临近退休、老张/老李等长辈称呼 | `senior` |
-| 无明显年龄特征 | 不传 `--age-group` |
-
-> **提取优先级**：角色背景(.background) > 角色描述(.description) > 角色名称(.name)
-
----
-
-## 头像资源匹配
-
-### Step 1：CLI 精准过滤查询
-
-根据前置步骤提取的 `gender` 和 `age_group`，使用 CLI 过滤参数查询：
-
-```bash
-# 性别+年龄都明确 → 一阶精准查询
-soke-cli ai-training +list-role-avatars \
-  --gender <gender> \
-  --age-group <age_group> \
-  --lang zh \
-  --show-detail \
-  --pretty
-
-# 仅性别明确 → 仅按性别过滤
-soke-cli ai-training +list-role-avatars \
-  --gender <gender> \
-  --lang zh \
-  --show-detail \
-  --pretty
-
-# 特征信息不足 → 不传过滤参数
-soke-cli ai-training +list-role-avatars \
-  --lang zh \
-  --show-detail \
-  --pretty
-```
-
-### Step 2：从过滤结果中选最佳匹配
-
-CLI 返回的头像列表已经是服务端按 `sort` 排序的过滤结果。按以下优先级选取：
-
-| 优先级 | 匹配条件 | 选取规则 |
-|---|---|---|
-| P0 | 性别 + 年龄都吻合 | 取过滤结果中 `sort` 最小的第 1 条 |
-| P1 | 仅性别吻合（年龄无精确匹配） | 取 `--gender` 过滤结果的第 1 条 |
-| P2 | 仅年龄吻合（性别无精确匹配） | 取 `--age-group` 过滤结果的第 1 条 |
-| P3 | 性别年龄均无匹配 | 不传过滤参数，全量取第 1 条通用/中性头像，并标注「无精确匹配」 |
-
-> **降级链路**：一阶查询返回空 → 去掉 `--age-group`（仅性别）→ 仍空则去掉 `--gender`（仅年龄）→ 仍空则全量无过滤。每次降级记录一次。
-
-### Step 3：写入角色级 JSON
-
-> ⚠️ **必须与语音资源合并写入角色级同步单元**：头像和语音写入同一个角色级操作，不可分两次。
-
-将匹配到的头像资源 URL 写入该角色的 `role_data.avatar`（与 voice_id 一起进入 `part2-role-XX.json`）：
-
-```json
-[
-  {
-    "type": "patch_ai_role",
-    "data": {
-      "scenario_role_id": "<角色ID>",
-      "patch": {
-        "role_data": {
-          "avatar": "<头像资源URL>"
-        },
-        "customized_fields": ["avatar"]
-      }
-    }
-  }
-]
-```
-
-> ⚠️ `avatar` 字段传入头像资源 **URL**（如 `https://newsokeeditorcdn.soke.cn/public/ai/avatars/business_owner_female.png`），来自 `+list-role-avatars` 返回的 `url` 字段，**不能**传资源 `id`。
-> ⚠️ `patch` 中必须包含 `customized_fields`，指明被修改的字段，否则平台可能不识别该更新。
-
-匹配过程默认不在聊天中展示；只有失败且影响后续发布时，才输出最小必要异常。
-
----
-
-## 语音资源匹配
-
-### Step 1：CLI 精准过滤查询
-
-```bash
-# 性别+年龄都明确 → 一阶精准查询
-soke-cli ai-training +list-role-voices \
-  --gender <gender> \
-  --age-group <age_group> \
-  --lang zh \
-  --pretty
-
-# 降级查询（同头像降级链路）
-```
-
-### Step 2：从过滤结果中选最佳匹配
-
-| 优先级 | 匹配条件 | 选取规则 |
-|---|---|---|
-| P0 | 性别 + 年龄都吻合 | 取过滤结果的第 1 条 |
-| P1 | 仅性别吻合 | 取 `--gender` 过滤结果的第 1 条 |
-| P2 | 仅年龄吻合 | 取 `--age-group` 过滤结果的第 1 条 |
-| P3 | 性别年龄均无匹配 | 全量取第 1 条通用默认音色，标注「无精确匹配」 |
-
-> **降级链路**：同头像匹配——一阶→去年龄→去性别→全量。每次降级记录一次。
-
-### Step 3：写入角色级 JSON
-
-> ⚠️ **必须与头像资源合并写入角色级同步单元**：语音和头像写入同一个角色级操作，不可分两次。
-
-将匹配到的语音资源 ID 写入该角色的 `role_data.voice_id`（与 avatar 一起进入 `part2-role-XX.json`）：
-
-```json
-[
-  {
-    "type": "patch_ai_role",
-    "data": {
-      "scenario_role_id": "<角色ID>",
-      "patch": {
-        "role_data": {
-          "voice_id": "<语音资源ID>"
-        },
-        "customized_fields": ["voice_id"]
-      }
-    }
-  }
-]
-```
-
-> ⚠️ `voice_id` 传入声音资源 **ID**（如 `zh_female_warm_01`），来自 `+list-role-voices` 返回的 `id` 字段，**不能**传 `sample_url` 或名称字符串。
-> ⚠️ `patch` 中必须包含 `customized_fields`，指明被修改的字段。
-
-匹配过程默认不在聊天中展示；只有失败且影响后续发布时，才输出最小必要异常。
-
----
-
-## 完整流程时序
-
-```
-Part2 完整展示并由用户确认
-  → 提取每个角色的性别(gender) + 年龄(age_group)
-  → CLI 并行精准过滤查询:
-      +list-role-avatars --gender <g> --age-group <a> --lang zh --show-detail --pretty
-      +list-role-voices --gender <g> --age-group <a> --lang zh --pretty
-    → 任一返回空则降级（去年龄→去性别→全量）
-  → ⚠️ 将 avatar + voice_id 写入对应角色级 JSON
-  → 角色1 preview + apply → get-scenario 强制验证该角色 avatar 非空 URL + voice_id 非空 ID
-  → 角色2 preview + apply → get-scenario 强制验证
-  → 角色3 preview + apply → get-scenario 强制验证
-  → OS preview + apply → get-scenario 强制验证 OS 完整写入
-  → 验证失败 → 重新读取 updated_at → 重试 1 次
-  → 仍失败 → 标注「资源匹配未完成」，不阻断后续 Part
-  → 全部同步完成后，再输出 Part3
-```
-
-> **头像/语音必须在同一角色同步单元内写入**，avatar 和 voice_id 放在同一个角色的 `role_data` 中，`customized_fields` 同时包含 `avatar` 和 `voice_id`。**禁止分两次 patch**——分开调用会导致 updated_at 竞态。
-
----
-
-## 端到端示例
-
-角色卡摘要：
-- 名称：谨慎型小微企业主
-- 描述：经营农资批发门店的女性老板，40多岁，关注融资成本和审批速度。
-- 背景：经营农资批发门店十余年，旺季前需短期周转资金 30-50 万……
-
-### 特征提取
-
-| 特征 | 来源字段 | 提取结果 | CLI 参数 |
-|---|---|---|---|
-| 性别 | 描述中"女性" | female | `--gender female` |
-| 年龄 | 描述中"40多岁"、背景中"十余年" | middle-aged | `--age-group middle-aged` |
-
-### CLI 查询
-
-```bash
-# 头像
-soke-cli ai-training +list-role-avatars \
-  --gender female \
-  --age-group middle-aged \
-  --lang zh \
-  --show-detail \
-  --pretty
-
-# 声音
-soke-cli ai-training +list-role-voices \
-  --gender female \
-  --age-group middle-aged \
-  --lang zh \
-  --pretty
-```
-
-### 写入
-
-```json
-{
-  "role_data": {
-    "avatar": "https://newsokeeditorcdn.soke.cn/public/ai/avatars/business_owner_female.png",
-    "voice_id": "zh_female_warm_01"
-  }
-}
-```
-
----
-
-## 异常处理
-
-| 情况 | 处理 |
-|---|---|
-| 头像/语音库 CLI 查询失败（网络/权限） | 跳过资源匹配，标注「资源匹配未完成」，Part3 不受影响 |
-| 角色特征信息不足（无性别/年龄暗示） | 不传过滤参数，全量查询取第 1 条默认头像 + 默认音色，不标注匹配摘要 |
-| 过滤查询返回空 → 降级后仍空 | 全量查询取第 1 条，标注「无精确匹配，已使用默认资源」 |
-| patch_ai_role 失败 | 重新读取 updated_at 后重试 1 次；仍失败则标注，不阻断 Part3 |
-| patch_ai_role 返回成功但 avatar/voice_id 验证为空 | 重新读取 updated_at 后重试 1 次；仍失败则标注，不阻断 Part3 |
-
----
-
-## 合并写入模板
-
-> ⚠️ **强制规则**：头像和语音必须合并为**单次** `patch_ai_role` 操作写入。禁止分两次 patch——分两次调用会导致第二次 patch 后 `updated_at` 变化，后续验收时可能误判第一次写入丢失。
-
-### operations JSON 结构
-
-```json
-[
-  {
-    "type": "patch_ai_role",
-    "data": {
-      "scenario_role_id": "<角色ID>",
-      "patch": {
-        "role_data": {
-          "avatar": "<头像资源URL>",
-          "voice_id": "<语音资源ID>"
-        },
-        "customized_fields": ["avatar", "voice_id"]
-      }
-    }
-  }
-]
-```
-
-### 完整 CLI 命令序列
-
-```bash
-# 1. 读取最新场景状态
-soke-cli ai-training +get-scenario \
-  --scenario-id <scenario_id> \
-  --pretty
-
-# 2. 写入合并的 operations JSON（Python json.dump）
-
-# 3. 预览
-soke-cli ai-training +preview-scenario-update \
-  --scenario-id <scenario_id> \
-  --base-updated-at <updated_at> \
-  --operations-file ./part2-resources.json \
-  --reason "Part2: 头像声音资源回填" \
-  --pretty
-
-# 4. 应用
-soke-cli ai-training +apply-scenario-update \
-  --scenario-id <scenario_id> \
-  --base-updated-at <updated_at> \
-  --operations-file ./part2-resources.json \
-  --idempotency-key "cli-<scenario_short>-part2-resources" \
-  --reason "Part2: 头像声音资源回填" \
-  --pretty
-
-# 5. 强制验证
-soke-cli ai-training +get-scenario \
-  --scenario-id <scenario_id> \
-  --pretty
-# 检查每个角色的 avatar 为非空 URL、voice_id 为非空 ID
-```
-
-### 验证失败重试
-
-```bash
-# 验证失败 → 重新读取 updated_at
-soke-cli ai-training +get-scenario --scenario-id <scenario_id> --pretty
-
-# 重新生成 patch → 重新 preview + apply（新 idempotency_key）
-# 仍失败 → 标注并继续 Part3
-```
-
----
-
-## REST API 回填路径（soke-cli 不可用时）
-
-> 当 soke-cli 不可用（如悟空/QClaw/Zework 等非 WorkBuddy 平台，或企业安全策略禁止 CLI 执行），头像和语音资源回填**不得跳过**，必须降级为 REST API 路径。
-
-完整流程详见 `platform/api-fallback.md`「资源回填完整流程」，本节仅说明与 CLI 路径的差异点。
-
-### 执行条件
-
-- soke-cli 未安装、执行持续失败、或 `which soke-cli` 返回空
-- 所在平台支持 HTTP 请求（curl / Python requests）
-
-### 差异点
-
-| 步骤 | CLI 路径 | REST API 路径 |
-|------|---------|---------------|
-| 头像查询 | `soke-cli ai-training +list-role-avatars --gender <g> --age-group <a>` | `GET /api/v1/ai-training/role-avatars?gender=<g>&age_group=<a>` |
-| 语音查询 | `soke-cli ai-training +list-role-voices --gender <g> --age-group <a>` | `GET /api/v1/ai-training/role-voices?gender=<g>&age_group=<a>` |
-| 回填 | `+preview-scenario-update` → `+apply-scenario-update` | 单次 `PATCH /api/v1/ai-training/scenarios/<id>`（无 preview 步骤，PATCH 前先 GET 对比） |
-| 验证 | `soke-cli ai-training +get-scenario` | `GET /api/v1/ai-training/scenarios/<id>` |
-| 沙箱 | `dangerouslyDisableSandbox: true` | 不适用（HTTP 请求） |
-
-### 相同点（保证回填质量一致）
-
-- 性别/年龄段特征提取与映射表**完全相同**（本文件「性别映射表」「年龄段映射表」）
-- P0-P3 降级链路**完全相同**
-- 合并写入（单次 patch avatar+voice_id）规则**完全相同**
-- 写入值规范：`avatar` = URL，`voice_id` = ID，**完全相同**
-- 强制验证 + 重试 1 次 + 失败标注不阻断 Part3，**完全相同**
-- 匹配摘要一行输出（「张总 → 威严中年男性头像 + 沉稳男中音」），**完全相同**
-
-> ⚠️ **关键原则**：REST API 路径**不是简化版**——它和 CLI 路径共享完全相同的匹配规则和验证标准。唯一的区别是数据传输方式（CLI 命令 vs HTTP 请求）。头像和语音的匹配质量和写入结果必须等价。

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

@@ -1,203 +0,0 @@
-# MentorAI CLI 已验证命令清单
-
-> 用于 AI 陪练场景的标准命令速查。凡涉及场景创建、读取、预览、应用、封面上传、知识包同步，统一使用 `soke-cli ai-training +...`，不要省略 `ai-training`。
-
-## 0. 总规则
-
-- 错误写法：`soke-cli +create-scenario`
-- 正确写法：`soke-cli ai-training +create-scenario`
-- 同理，`+get-scenario`、`+preview-scenario-update`、`+apply-scenario-update`、`+upload-scenario-cover`、`+sync`、`+bind-scenario` 都必须挂在 `ai-training` 子命令下
-- 每次 `preview` / `apply` 前，先重新执行一次 `soke-cli ai-training +get-scenario`
-- 默认优先使用 `--request-file <partX-update.json>` 传完整更新请求；排障时再改用 `--operations-file <partX-operations.json>`
-- 每次 `apply` 后，立刻执行一次 `soke-cli ai-training +get-scenario --raw` 做验收
-- ⚠️ **所有 soke-cli 命令通过 Bash 工具执行时，必须设置 `dangerouslyDisableSandbox: true`**。soke-cli 是 Go 编译二进制，在沙箱中会被限制执行（`permission denied` 或静默无输出）。此规则适用于本文件中全部命令，不限于创建型流程
-
-## 1. Step1 创建场景
-
-### 1.1 上传封面
-
-```bash
-soke-cli ai-training +upload-scenario-cover \
-  --file ./scenario-cover.png \
-  --pretty
-```
-
-### 1.2 创建场景
-
-```bash
-soke-cli ai-training +create-scenario \
-  --request-file ./step1-create.json \
-  --pretty
-```
-
-### 1.3 创建后立即回读
-
-```bash
-soke-cli ai-training +get-scenario \
-  --scenario-id <scenario_id> \
-  --raw \
-  --pretty
-```
-
-## 2. Part2-Part5 通用同步模板
-
-### 2.1 先获取最新基线
-
-```bash
-soke-cli ai-training +get-scenario \
-  --scenario-id <scenario_id> \
-  --pretty
-```
-
-### 2.2 预览更新（默认 request-file 模式）
-
-```bash
-soke-cli ai-training +preview-scenario-update \
-  --scenario-id <scenario_id> \
-  --request-file ./partX-update.json \
-  --pretty
-```
-
-### 2.3 应用更新（默认 request-file 模式）
-
-```bash
-soke-cli ai-training +apply-scenario-update \
-  --scenario-id <scenario_id> \
-  --request-file ./partX-update.json \
-  --pretty
-```
-
-### 2.3A 排障时退回 operations 模式
-
-```bash
-soke-cli ai-training +preview-scenario-update \
-  --scenario-id <scenario_id> \
-  --operations-file ./partX-operations.json \
-  --base-updated-at <updated_at> \
-  --reason "PartX: 更新说明" \
-  --pretty
-
-soke-cli ai-training +apply-scenario-update \
-  --scenario-id <scenario_id> \
-  --operations-file ./partX-operations.json \
-  --base-updated-at <updated_at> \
-  --idempotency-key "cli-<scenario_short>-partX-apply" \
-  --reason "PartX: 更新说明" \
-  --pretty
-```
-
-### 2.4 应用后强制验收
-
-```bash
-soke-cli ai-training +get-scenario \
-  --scenario-id <scenario_id> \
-  --raw \
-  --pretty
-```
-
-## 3. 各 Part 推荐文件名
-
-- Part2：`./part2-operations.json` + `./part2-update.json`
-- Part3：`./part3-operations.json` + `./part3-update.json`
-- Part4：`./part4-operations.json` + `./part4-update.json`
-- Part5：`./part5-operations.json` + `./part5-update.json`
-- 微调：`./optimize-operations.json` + `./optimize-update.json`
-
-## 4. 知识包同步与场景绑定
-
-### 4.1 同步知识包
-
-```bash
-soke-cli ai-training +sync \
-  --manifest ./knowledge-package.json \
-  --idempotency-key "cli-<package_id>-sync" \
-  --pretty
-```
-
-### 4.2 绑定到场景
-
-```bash
-soke-cli ai-training +bind-scenario \
-  --scenario-id <scenario_id> \
-  --version-ids <version_id> \
-  --compile-plan
-```
-
-## 5. 发布场景
-
-### 5.1 发布
-
-```bash
-soke-cli ai-training +publish-scenario \
-  --scenario-id <scenario_id> \
-  --version 1 \
-  --version-description "CLI发布" \
-  --pretty
-```
-
-### 5.2 发布后验收
-
-```bash
-soke-cli ai-training +get-scenario \
-  --scenario-id <scenario_id> \
-  --raw \
-  --pretty
-```
-
-## 6. 快照与恢复
-
-### 6.1 查询快照
-
-```bash
-soke-cli ai-training +list-scenario-snapshots \
-  --scenario-id <scenario_id> \
-  --page 1 \
-  --page-size 20 \
-  --pretty
-```
-
-### 6.2 恢复快照
-
-```bash
-soke-cli ai-training +restore-scenario-snapshot \
-  --scenario-id <scenario_id> \
-  --snapshot-id <snapshot_id> \
-  --reason "回滚本次 CLI 更新" \
-  --pretty
-```
-
-## 7. 当前已验证可用命令
-
-- `soke-cli ai-training +upload-scenario-cover`
-- `soke-cli ai-training +create-scenario`
-- `soke-cli ai-training +get-scenario`
-- `soke-cli ai-training +list-scenarios`
-- `soke-cli ai-training +preview-scenario-update`
-- `soke-cli ai-training +apply-scenario-update`
-- `soke-cli ai-training +publish-scenario`
-- `soke-cli ai-training +list-scenario-snapshots`
-- `soke-cli ai-training +restore-scenario-snapshot`
-- `soke-cli ai-training +sync`
-- `soke-cli ai-training +bind-scenario`
-
-## 8. 常见误抄与纠正
-
-- 误抄：`soke-cli +create-scenario`
-  - 改成：`soke-cli ai-training +create-scenario`
-- 误抄：`soke-cli +get-scenario`
-  - 改成：`soke-cli ai-training +get-scenario`
-- 误抄：`soke-cli +preview-scenario-update`
-  - 改成：`soke-cli ai-training +preview-scenario-update`
-- 误抄：`soke-cli +apply-scenario-update`
-  - 改成：`soke-cli ai-training +apply-scenario-update`
-- 误抄：`soke-cli +sync`
-  - 改成：`soke-cli ai-training +sync`
-- 误抄：`soke-cli +bind-scenario`
-  - 改成：`soke-cli ai-training +bind-scenario`
-
-## 7. 推荐阅读顺序
-
-1. 先看 `platform-api-pitfalls.md`
-2. 再看 `platform/sync-engine.md`
-3. 真正执行前，按本文件复制命令模板
-4. 若平台返回与历史文档冲突，以最新 CLI 实证为准