@sokeai/cli 1.0.77 → 1.0.78

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

@@ -0,0 +1,403 @@
+#!/usr/bin/env python3
+"""
+soke-ai-coach-director · 执行手册验证器
+Usage:
+    python3 scripts/validate_operations.py <part> <operations.json>
+    python3 scripts/validate_operations.py part1 ./part1-create.json
+    python3 scripts/validate_operations.py part2 ./part2-operations.json
+    python3 scripts/validate_operations.py part3 ./part3-operations.json
+    python3 scripts/validate_operations.py part4 ./part4-operations.json
+    python3 scripts/validate_operations.py part5 ./part5-operations.json
+
+退出码:
+    0 = 全部通过
+    1 = 有错误（详情打印到 stderr）
+"""
+
+import json
+import sys
+import os
+from typing import Any
+
+
+# ---------- Part1: step1-create.json / part1-create.json ----------
+
+def validate_part1(data: dict) -> list[str]:
+    """Part1 不是 operations 数组，而是单个 JSON 对象。"""
+    errors = []
+
+    # name
+    name = data.get("name")
+    if not isinstance(name, str) or not (1 <= len(name) <= 100):
+        errors.append(f"name: 必须是 1-100 字符的字符串，当前 type={type(name).__name__} value={name!r}")
+
+    # description
+    desc = data.get("description")
+    if not isinstance(desc, str) or len(desc) < 20:
+        errors.append(f"description: 必须是 ≥20 字符的字符串，当前 len={len(desc) if isinstance(desc, str) else 0}")
+
+    # tags
+    tags = data.get("tags")
+    if not isinstance(tags, list):
+        errors.append(f"tags: 必须是数组，当前 type={type(tags).__name__}")
+    elif not (3 <= len(tags) <= 5):
+        errors.append(f"tags: 必须是 3-5 个元素，当前 {len(tags)}")
+    elif not all(isinstance(t, str) and t for t in tags):
+        errors.append("tags: 所有元素必须是非空字符串")
+
+    # key_points: 必须是字符串（最高频错误）
+    kp = data.get("key_points")
+    if not isinstance(kp, str) or not kp:
+        errors.append(f"key_points: 必须是非空字符串（不能是数组），当前 type={type(kp).__name__}")
+    # 回查: 如果是数组，提示
+    if isinstance(kp, list):
+        errors.append("key_points: ❌ 被写成数组，平台会接受但字段为空。改为分号拼接的单字符串")
+
+    # scene_lang
+    if data.get("scene_lang") != "简体中文":
+        errors.append(f"scene_lang: 必须固定为 '简体中文'，当前 {data.get('scene_lang')!r}")
+
+    # scenario_cover 或 cover_url（CLI 接受两者）
+    cover = data.get("scenario_cover") or data.get("cover_url")
+    if cover != "https://newsokeeditorcdn.soke.cn/public/ai/cover/lingshou_daogou.png":
+        errors.append(f"scenario_cover/cover_url: 必须使用固定默认图 URL，当前 {cover!r}")
+
+    return errors
+
+
+# ---------- Part2: operations 数组（update_basic + replace_ai_roles） ----------
+
+def validate_part2(operations: list) -> list[str]:
+    errors = []
+
+    # 操作 1: update_basic (OS)
+    os_ops = [o for o in operations if o.get("type") == "update_basic"]
+    if not os_ops:
+        errors.append("❌ 缺操作 1: update_basic（OS 整体设定）—— 会导致平台无 OS，角色行为退化")
+    else:
+        for op in os_ops:
+            os_text = op.get("data", {}).get("ai_roles_overall_description")
+            if not isinstance(os_text, str):
+                errors.append(f"ai_roles_overall_description: 必须是字符串，当前 type={type(os_text).__name__}")
+            elif len(os_text) < 500:
+                errors.append(f"ai_roles_overall_description: 必须 ≥500 字符（当前 {len(os_text)}），A1-A7 全文不摘要")
+
+    # 操作 2: replace_ai_roles
+    role_ops = [o for o in operations if o.get("type") == "replace_ai_roles"]
+    if not role_ops:
+        errors.append("❌ 缺操作 2: replace_ai_roles（角色数据）—— 会导致平台有 OS 无角色")
+    else:
+        for ri, op in enumerate(role_ops):
+            # v2.26: 检测 ai_roles_overall_description 是否被错误放入 replace_ai_roles.data
+            wrong_os = op.get("data", {}).get("ai_roles_overall_description")
+            if wrong_os is not None:
+                errors.append(
+                    "❌ ai_roles_overall_description 被错误放入 replace_ai_roles.data！"
+                    "必须移到 update_basic.data 中，否则平台静默丢弃、API 不报错。"
+                )
+            roles = op.get("data", {}).get("roles")
+            if not isinstance(roles, list) or not roles:
+                errors.append(f"replace_ai_roles.data.roles: 必须是非空数组")
+                continue
+            for i, r in enumerate(roles):
+                # 外壳字段必须在 role_data 外层（source_type 允许同时存在于两处）
+                for shell_field in ["customization_level", "is_custom_role", "customized_fields"]:
+                    if shell_field not in r:
+                        errors.append(f"roles[{i}]: 缺外壳字段 {shell_field}（必须在 role_data 外层）")
+                # source_type 是特殊情况：顶层必须有，role_data 里可以有也可以没有
+                if "source_type" not in r:
+                    errors.append(f"roles[{i}]: 缺外壳字段 source_type（必须在 role_data 外层）")
+
+                rd = r.get("role_data", {})
+                for k in ["name", "description", "communication_style", "background",
+                          "personality_type", "personality", "avatar", "voice_id"]:
+                    if not rd.get(k):
+                        errors.append(f"roles[{i}].role_data.{k}: 空/缺失")
+
+                # knowledge_level 必须是数组
+                kl = rd.get("knowledge_level")
+                if not isinstance(kl, list):
+                    errors.append(f"roles[{i}].role_data.knowledge_level: 必须是数组（如 ['小白']），当前 type={type(kl).__name__}")
+
+                # tags 必须是数组 2-4 个
+                tags = rd.get("tags")
+                if not isinstance(tags, list) or not (2 <= len(tags) <= 4):
+                    errors.append(f"roles[{i}].role_data.tags: 必须是 2-4 个元素的数组，当前 {tags!r}")
+
+                # avatar URL 必须在平台头像库中（v2.24.2 新增）
+                avatar_url = rd.get("avatar", "")
+                if avatar_url and "/public/ai/avatar/" in avatar_url:
+                    errors.append(f"roles[{i}].role_data.avatar: ❌ URL 路径错误！正确路径是 `/public/ai/roles_avatars/` 不是 `/public/ai/avatar/`（长龙航空事故）")
+                elif avatar_url and "/public/ai/roles_avatars/" not in avatar_url and "/public/ai/cover/" not in avatar_url:
+                    print(f"⚠️  roles[{i}].role_data.avatar: URL 不在平台头像库路径下（/public/ai/roles_avatars/ 或 /public/ai/cover/）", file=sys.stderr)
+                to = rd.get("taboos_objections")
+                # taboos_objections 必须是数组
+                to = rd.get("taboos_objections")
+                if not isinstance(to, list):
+                    errors.append(f"roles[{i}].role_data.taboos_objections: 必须是数组")
+
+                # background 四段完整性检查（中英文任一全套即通过）
+                bg = rd.get("background", "") or ""
+                cn_segs = ["我是谁", "我的困扰", "我的过往经历", "我今天的心态"]
+                en_segs = ["Who I am", "My concern", "My past experience", "My mindset today"]
+                cn_missing = [s for s in cn_segs if s not in bg]
+                en_missing = [s for s in en_segs if s not in bg]
+                if cn_missing and en_missing:
+                    for s in cn_missing:
+                        errors.append(f"roles[{i}].role_data.background: 缺四段画像段落 '{s}'")
+
+    return errors
+
+
+# ---------- Part3: operations 数组（update_basic + add_conversation_step） ----------
+
+def validate_part3(operations: list) -> list[str]:
+    errors = []
+
+    # 开场语
+    open_ops = [o for o in operations if o.get("type") == "update_basic"]
+    if not open_ops:
+        errors.append("缺 update_basic 操作（开场语）")
+    else:
+        d = open_ops[0].get("data", {})
+        od = d.get("opening_dialogue")
+        if not isinstance(od, str) or len(od) < 20:
+            errors.append(f"opening_dialogue: 必须 ≥20 字符，当前 len={len(od) if isinstance(od, str) else 0}")
+        odt = d.get("opening_dialogue_type")
+        if odt != 1:
+            errors.append(f"opening_dialogue_type: 必须是数字 1（不是字符串），当前 {odt!r}")
+
+    # 对话环节
+    steps = [o for o in operations if o.get("type") == "add_conversation_step"]
+    if not (3 <= len(steps) <= 7):
+        errors.append(f"对话环节数: 必须 3-7 个，当前 {len(steps)}")
+
+    for i, s in enumerate(steps):
+        d = s.get("data", {})
+        # sort_order 平台自动生成（创建时不传，更新时才传）- 不强制
+        for k in ["step_name", "student_objective", "ai_task", "max_rounds"]:
+            if d.get(k) in (None, "", []):
+                errors.append(f"step[{i}].data.{k}: 空/缺失")
+
+        # sort_order 如果传了，必须是字符串（平台创建时不传也可以）
+        so = d.get("sort_order")
+        if so is not None and not isinstance(so, str):
+            errors.append(f"step[{i}].sort_order: 必须是字符串（如 '1'），当前 type={type(so).__name__}")
+
+        # max_rounds 必须是整数 3-10
+        mr = d.get("max_rounds")
+        if not isinstance(mr, int) or not (3 <= mr <= 10):
+            errors.append(f"step[{i}].max_rounds: 必须是 3-10 的整数，当前 {mr!r}")
+
+        # ai_task 应含条件逻辑（中英文任一）和退出条件
+        at = d.get("ai_task", "") or ""
+        has_if_logic = any(kw in at for kw in ["IF", "如果", "进入条件", "行为分支"]) or "条件" in at
+        has_exit = any(kw in at for kw in ["退出", "结束", "退出条件"])
+        if not has_if_logic:
+            errors.append(f"step[{i}].ai_task: 缺条件逻辑（IF/进入条件/行为分支/如果）")
+        if not has_exit:
+            errors.append(f"step[{i}].ai_task: 缺退出条件")
+
+    # 原子性检查：开场语 + 环节应在同一批 operations
+    if open_ops and steps:
+        # 这里只能检查是否在同一数组，不能检查是否同一次 apply（由 SKILL.md 约束）
+        pass
+
+    return errors
+
+
+# ---------- Part4: operations 数组（replace_scoring_criteria_config 双层包装） ----------
+
+def validate_part4(operations: list) -> list[str]:
+    errors = []
+
+    p4_ops = [o for o in operations if o.get("type") == "replace_scoring_criteria_config"]
+    if not p4_ops:
+        errors.append("缺 replace_scoring_criteria_config 操作")
+        return errors
+
+    for ri, op in enumerate(p4_ops):
+        config = op.get("data", {}).get("config")
+        if not isinstance(config, dict):
+            errors.append(f"op[{ri}].data.config: 必须是对象")
+            continue
+
+        # v2.26 硬阻断: shell 字段必须在 config 顶层，不在 criteria_data 内
+        cd = config.get("criteria_data") or {}
+        SHELL_FIELDS = ["scenario_criteria_id", "customization_level", "is_custom_criteria", "customized_fields"]
+        for k in SHELL_FIELDS:
+            if k not in config:
+                errors.append(f"❌ op[{ri}].data.config.{k}: 缺失（v2.26 硬阻断：shell 字段必须在 config 顶层，否则 UI 不显示评分标准）")
+            if k in cd:
+                errors.append(
+                    f"❌ op[{ri}]: shell 字段 {k} 被错误放入 criteria_data 内层！"
+                    f"必须移到 data.config 顶层。错放会导致 UI 显示「请选择或创建评分标准」空状态，API 不报错。"
+                )
+
+        # 第 2 层 criteria_data 包装（必须存在）
+        if not isinstance(cd, dict) or not cd:
+            errors.append(f"op[{ri}].data.config.criteria_data: ❌ 缺第 2 层 criteria_data 包装（平台会接受但存储错误）")
+            continue
+
+        # 必填字段（实际影响平台存储和 UI 展示）
+        # name/description/dimensions 是 API 硬必填
+        for k in ["name", "description", "dimensions"]:
+            if cd.get(k) in (None, "", []):
+                errors.append(f"op[{ri}].data.config.criteria_data.{k}: 空/缺失（必填）")
+        # v2.26: criteria_data 内业务字段硬阻断
+        if cd.get("total_weight") not in (100, None):
+            errors.append(f"op[{ri}].criteria_data.total_weight: 必须 100，当前 {cd.get('total_weight')!r}")
+        for k in ["tags", "source_type", "status"]:
+            if k not in cd:
+                errors.append(f"op[{ri}].criteria_data.{k}: ❌ 缺失（v2.26 硬阻断）")
+            elif k == "tags" and (not isinstance(cd.get(k), list) or len(cd.get(k)) == 0):
+                errors.append(f"op[{ri}].criteria_data.tags: 必须是非空数组")
+            elif k == "source_type" and cd.get(k) not in ("enterprise", "custom"):
+                errors.append(f"op[{ri}].criteria_data.source_type: 必须 'enterprise'，当前 {cd.get(k)!r}")
+            elif k == "status" and cd.get(k) != 1:
+                errors.append(f"op[{ri}].criteria_data.status: 必须 1，当前 {cd.get(k)!r}")
+
+        if cd.get("source_type") not in ("enterprise", "custom"):
+            errors.append(f"op[{ri}].criteria_data.source_type: 应为 'enterprise' 或 'custom'，当前 {cd.get('source_type')!r}")
+
+        # total_weight 是警告不是错误（中文版不加也成功）
+        if "total_weight" in cd and cd.get("total_weight") != 100:
+            print(f"⚠️  op[{ri}].criteria_data.total_weight: 建议 100，当前 {cd.get('total_weight')!r}", file=sys.stderr)
+
+        dims = cd.get("dimensions", [])
+        if not isinstance(dims, list) or len(dims) < 2:
+            errors.append(f"op[{ri}].criteria_data.dimensions: 必须 ≥2 个维度")
+        else:
+            weight_sum = sum(d.get("weight", 0) for d in dims)
+            if weight_sum != 100:
+                errors.append(f"op[{ri}].dimensions weight sum: 必须 100，当前 {weight_sum}")
+
+            for i, d in enumerate(dims):
+                # 硬必填（API + UI）
+                for k in ["id", "code", "name", "weight", "scoring_rule", "criteria", "sort_order"]:
+                    if d.get(k) in (None, "", []):
+                        errors.append(f"op[{ri}].dimensions[{i}].{k}: 空/缺失（必填）")
+                # description 建议字段
+                if "description" not in d or d.get("description") in (None, "", []):
+                    print(f"⚠️  op[{ri}].dimensions[{i}].description: 建议字段", file=sys.stderr)
+
+                # sort_order 必须是数字
+                so = d.get("sort_order")
+                if not isinstance(so, int):
+                    errors.append(f"op[{ri}].dimensions[{i}].sort_order: 必须是数字（不是字符串），当前 type={type(so).__name__}")
+
+                # criteria 至少 2 个
+                crit = d.get("criteria", [])
+                if not isinstance(crit, list) or len(crit) < 2:
+                    errors.append(f"op[{ri}].dimensions[{i}].criteria: 至少 2 个评分点")
+
+                # code 必须是英文
+                code = d.get("code", "")
+                if code and not code.isascii():
+                    errors.append(f"op[{ri}].dimensions[{i}].code: 必须是英文，当前 {code!r}")
+
+    return errors
+
+
+# ---------- Part5: operations 数组（update_basic 6 项固定配置） ----------
+
+def validate_part5(operations: list) -> list[str]:
+    errors = []
+
+    ops = [o for o in operations if o.get("type") == "update_basic"]
+    if not ops:
+        errors.append("缺 update_basic 操作")
+        return errors
+
+    d = ops[0].get("data", {})
+    # Part5 固定配置（以平台实际接受值为准）
+    # min/max_practice_duration 平台允许 0 或正整数（0=不限）
+    # max_practice_attempts=10, passing_score=60, completion_rule=all_steps 是平台默认值
+    checks = {
+        "max_practice_attempts": (lambda v: isinstance(v, int) and v > 0, "正整数"),
+        "passing_score": (lambda v: isinstance(v, int) and 0 < v <= 100, "1-100 整数"),
+        "completion_rule": (lambda v: v == "all_steps", "'all_steps'"),
+        "pass_difficulty": (lambda v: isinstance(v, int) and 1 <= v <= 3, "1-3 整数"),
+    }
+    for k, (check, hint) in checks.items():
+        actual = d.get(k)
+        if actual is None:
+            errors.append(f"{k}: 缺失（Part5 必填）")
+        elif not check(actual):
+            errors.append(f"{k}: 必须为 {hint}，当前 {actual!r}")
+    # ai_assistance_enabled 应为 True
+    if d.get("ai_assistance_enabled") is not True:
+        errors.append(f"ai_assistance_enabled: 必须为 True，当前 {d.get('ai_assistance_enabled')!r}")
+    # 禁止字段（已在 Part1/Part3 同步过）
+    for forbidden in ["opening_dialogue", "opening_dialogue_type", "key_points", "name", "description", "tags", "scenario_cover"]:
+        if forbidden in d:
+            errors.append(f"{forbidden}: ❌ Part5 不应同步此字段（已在 Part1 同步）")
+
+    return errors
+
+
+# ---------- 入口 ----------
+
+def load_json(path: str) -> Any:
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def main() -> int:
+    if len(sys.argv) != 3:
+        print(__doc__, file=sys.stderr)
+        return 2
+
+    part = sys.argv[1].lower().strip()
+    path = sys.argv[2]
+
+    if not os.path.isfile(path):
+        print(f"❌ 文件不存在: {path}", file=sys.stderr)
+        return 2
+
+    try:
+        data = load_json(path)
+    except json.JSONDecodeError as e:
+        print(f"❌ JSON 解析失败: {e}", file=sys.stderr)
+        return 2
+
+    validators = {
+        "part1": (validate_part1, "dict"),
+        "part2": (validate_part2, "list"),
+        "part3": (validate_part3, "list"),
+        "part4": (validate_part4, "list"),
+        "part5": (validate_part5, "list"),
+    }
+
+    if part not in validators:
+        print(f"❌ 未知 part: {part}，支持: {list(validators.keys())}", file=sys.stderr)
+        return 2
+
+    func, expected_type = validators[part]
+    if expected_type == "dict" and not isinstance(data, dict):
+        print(f"❌ {part} 期望 JSON 对象，实际 {type(data).__name__}", file=sys.stderr)
+        return 1
+    # 支持两种格式：
+    # 1. 纯 operations 数组 [...]
+    # 2. CLI request-file 对象 {operations: [...], idempotency_key, ...}
+    if expected_type == "list":
+        if isinstance(data, dict) and "operations" in data:
+            data = data["operations"]
+        if not isinstance(data, list):
+            print(f"❌ {part} 期望 JSON 数组或 {{operations:[...]}} 对象，实际 {type(data).__name__}", file=sys.stderr)
+            return 1
+
+    errors = func(data)
+
+    if not errors:
+        print(f"✅ {part} 验证通过（{len(errors)} 个错误）")
+        return 0
+    else:
+        print(f"❌ {part} 验证失败（{len(errors)} 个错误）:", file=sys.stderr)
+        for e in errors:
+            print(f"  - {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/multi/soke-ai-training/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: soke-ai-training
+description: "用于本地Agent通过soke-cli调用开放平台AI教练接口，完成Markdown source上传、结构化entries同步、source管理、场景知识包版本绑定、知识计划编译查询、场景详情读取、系统角色资源查询和场景CLI安全更新。"
+metadata:
+  requires:
+    bins: ["soke-cli"]
+  cliHelp: "soke-cli ai-training --help"
+---
+
+# AI教练知识包与场景管理
+
+**CRITICAL — 开始前 MUST 先读取 [`./references/shared.md`](./references/shared.md)，其中包含认证、配置和权限处理。**
+
+## 使用前提
+
+1. 运行 `soke-cli auth login` 完成用户授权。
+2. 确认 `soke-cli config show` 中有 `APIBaseURL`、`AppKey`、`AppSecret`、`CorpID` 和用户 token。
+3. 客户原始 PDF、Word、Excel、网页等资料必须先由本地 Agent/Skills 提炼为 Markdown sources 和结构化 entries JSON。
+
+## 推荐同步
+
+```bash
+soke-cli ai-training +sync \
+  --manifest ./knowledge-package.json \
+  --idempotency-key cli-rcb-loan-products-20260610-001
+```
+
+`+sync` 会完成：
+
+1. 读取 manifest 和 entries。
+2. 校验 Markdown 文件、source_refs、entry_id/source_id 唯一性。
+3. 调用 `/skills/ai-training/knowledge-packages/upload-tokens`。
+4. 直传 Markdown 到服务端返回的 `upload_url`。
+5. 调用 `/skills/ai-training/knowledge-packages/sync`。
+6. 写入 `.mentorai-sync-state.json`。
+
+## Manifest 示例
+
+```json
+{
+  "package": {
+    "package_id": "rcb-loan-products",
+    "name": "农商银行贷款产品知识包",
+    "domain": "banking_loan",
+    "tags": ["贷款产品"]
+  },
+  "sources": [
+    {
+      "source_id": "src_manual",
+      "path": "./sources/manual.md",
+      "display_name": "贷款产品手册",
+      "origin_type": "pdf",
+      "origin_filename": "贷款产品手册.pdf"
+    }
+  ],
+  "entries_path": "./knowledge-package.entries.json"
+}
+```
+
+## 查询和管理
+
+```bash
+soke-cli ai-training +list-packages --format json
+soke-cli ai-training +list-versions --package-id rcb-loan-products
+soke-cli ai-training +list-sources --package-id rcb-loan-products
+soke-cli ai-training +rename-source --package-id rcb-loan-products --source-id src_manual --display-name "贷款产品手册2026Q2"
+soke-cli ai-training +delete-source --package-id rcb-loan-products --source-id src_manual
+```
+
+## 场景绑定
+
+```bash
+soke-cli ai-training +bind-scenario \
+  --scenario-id scenario_micro_loan_sales \
+  --version-ids 8ed4c1c4-5b3c-4d44-ae8e-d5b064bf1e12 \
+  --compile-plan
+
+soke-cli ai-training +compile-plan \
+  --scenario-id scenario_micro_loan_sales \
+  --version-ids 8ed4c1c4-5b3c-4d44-ae8e-d5b064bf1e12 \
+  --force
+
+soke-cli ai-training +get-plan --scenario-id scenario_micro_loan_sales --format json
+```
+
+## 场景读取与更新
+
+场景配置更新必须先读取当前场景，再基于 `updated_at` 构造 `base_updated_at`。只修改描述、角色、评分或流程时，使用 `+preview-scenario-update` 和 `+apply-scenario-update`；发布场景时才使用 `+publish-scenario`。
+
+### 创建场景
+
+如果封面图由本地智能体生成，先上传封面并拿到可写入 `scenario_cover` 的 CDN URL：
+
+```bash
+soke-cli ai-training +upload-scenario-cover \
+  --file ./cover.png
+```
+
+默认只输出 CDN URL。需要排障时可加 `--raw` 查看完整上传凭证响应；不要把 `upload_url`、OSS 签名字段、access key 或 security token 写入仓库、状态文件或对话记录。SaaS 与 MentorAI 共用 OSS/CDN，封面上传复用开放平台的 SaaS OSS 签名能力，不需要 MentorAI 端单独上传接口。
+
+最小参数创建：
+
+```bash
+soke-cli ai-training +upload-scenario-cover --file ./cover.png > cover-url.txt
+
+soke-cli ai-training +create-scenario \
+  --name "创建测试" \
+  --description "描述" \
+  --tags "" \
+  --key-points "关键点" \
+  --scene-lang zh \
+  --scenario-cover "$(cat cover-url.txt)" \
+  --pretty
+```
+
+复杂角色、评分规则、流程步骤和时间设置使用完整 JSON：
+
+```bash
+soke-cli ai-training +create-scenario \
+  --request-file scenario-create.json \
+  --pretty
+```
+
+创建命令默认输出 MentorAI `BaseResponse.data`，通常可从返回对象中读取新场景 ID。创建请求中的 `corp_id`、`company_id`、`user_id`、`implementation_corp_id` 不作为授权依据，企业和用户上下文由开放平台认证注入。
+
+### 读取和资源选择
+
+```bash
+soke-cli ai-training +list-scenarios \
+  --page 1 \
+  --page-size 20 \
+  --keyword "销售" \
+  --pretty
+
+soke-cli ai-training +get-scenario \
+  --scenario-id scenario_micro_loan_sales \
+  --pretty \
+  --output scenario.json
+
+soke-cli ai-training +list-role-avatars \
+  --lang zh \
+  --show-detail \
+  --pretty
+
+soke-cli ai-training +list-role-voices \
+  --lang zh \
+  --gender female \
+  --pretty
+```
+
+`+list-scenarios` 默认输出 MentorAI `BaseResponse.data`，用于发现可操作场景 ID。列表 query 不要伪造 `corp_id`、`company_id`、`user_id` 或 `implementation_corp_id`；可见范围由开放平台 token、用户登录态和 MentorAI 权限决定。拿到场景 ID 后，优先执行 `+get-scenario` 保存完整基准 JSON。
+
+头像更新写入 `ai_roles[].role_data.avatar` 时使用头像资源的 `url`，不是资源 `id`。声音更新写入 `ai_roles[].role_data.voice_id` 时使用声音资源的 `id`，不是 `sample_url`。
+
+### 预览和应用
+
+完整请求文件示例：
+
+```json
+{
+  "base_updated_at": "2026-07-08T10:20:00+08:00",
+  "idempotency_key": "cli-scenario-update-001",
+  "reason": "优化客户角色开场和声音",
+  "source": "cli",
+  "operations": [
+    {
+      "type": "patch_ai_role",
+      "data": {
+        "scenario_role_id": "role_customer_owner",
+        "patch": {
+          "role_data": {
+            "voice_id": "zh_female_warm_01"
+          },
+          "customized_fields": ["voice_id"]
+        }
+      }
+    }
+  ]
+}
+```
+
+```bash
+soke-cli ai-training +preview-scenario-update \
+  --scenario-id scenario_micro_loan_sales \
+  --request-file update.json \
+  --pretty
+
+soke-cli ai-training +apply-scenario-update \
+  --scenario-id scenario_micro_loan_sales \
+  --request-file update.json \
+  --pretty
+```
+
+也可以只提供 operations 数组，并用 flag 组装请求：
+
+```bash
+soke-cli ai-training +preview-scenario-update \
+  --scenario-id scenario_micro_loan_sales \
+  --operations-file operations.json \
+  --base-updated-at "2026-07-08T10:20:00+08:00" \
+  --reason "优化场景说明" \
+  --pretty
+```
+
+`+apply-scenario-update` 必须有 `idempotency_key`，可放在 `--request-file` 中，或用 `--idempotency-key` 覆盖补充。遇到 409 乐观锁冲突时，重新执行 `+get-scenario` 获取最新 `updated_at` 后再生成更新请求。
+
+### 发布场景
+
+发布场景使用独立命令：
+
+```bash
+soke-cli ai-training +publish-scenario \
+  --scenario-id scenario_micro_loan_sales \
+  --pretty
+```
+
+MentorAI `POST /api/v1/scenarios/{scenario_id}/publish` 使用路径中的 `scenario_id`，并在 body 中发送 `version` 和 `version_description`。CLI 默认 `--version 1`、`--version-description "CLI发布"`，不再提供 `--request-file`。不要用 `+publish-scenario` 做任意局部更新；如果只是修改描述、角色字段、评分项或对话步骤，继续走 preview/apply。发布接口返回 409/422 时，加 `--raw` 保留 `errorCode/errorMessage/details/traceId`。
+
+### 快照
+
+```bash
+soke-cli ai-training +list-scenario-snapshots \
+  --scenario-id scenario_micro_loan_sales \
+  --page 1 \
+  --page-size 20 \
+  --pretty
+
+soke-cli ai-training +restore-scenario-snapshot \
+  --scenario-id scenario_micro_loan_sales \
+  --snapshot-id snapshot_001 \
+  --reason "回滚错误CLI更新" \
+  --pretty
+```
+
+新增场景命令默认输出 MentorAI `BaseResponse.data`；排查错误时加 `--raw` 保留 `success/errorCode/errorMessage/details/traceId`。
+
+## 注意
+
+- 不要在 manifest 或 entries 中伪造 `corp_id`、`user_id` 或 `object_key`。
+- `object_key` 必须使用 upload-token 返回值。
+- 不要把客户原始资料、token、app_secret 或 OSS 签名写入仓库。
+- `+upload-scenario-cover` 默认只输出 `cdn_url`；只有排障时才使用 `--raw`，且不要持久化完整签名响应。
+- `advisor_golden_script` 不应进入 AI 客户角色可见知识。
+- 场景更新请求体或 query 中不要伪造 `corp_id`、`company_id`、`user_id`。
+- 场景创建请求体中的 `corp_id`、`company_id`、`user_id`、`implementation_corp_id` 会由代理剥离，不要依赖它们选择租户。
+- 场景更新前必须以 `+get-scenario` 的 `updated_at` 作为 `base_updated_at`。
+- 场景发布需要 `+publish-scenario --scenario-id <id>`，默认带 `version=1` 和 `version_description=CLI发布`；不要把它当作局部更新命令。

package/skills/{soke-cli/345/256/211/350/243/205/346/214/207/345/215/227.md → multi/soke-ai-training/references/installation.md}

@@ -434,9 +434,6 @@ npx skills add liuchenlong1111/soke-cli -y -g
 
 ### 📖 阅读详细文档
 
-- [README.md](../README.md) - 项目概览
-- [CLAUDE.md](../CLAUDE.md) - 项目架构和开发规范
-- [skills/README.md](../skills/README.md) - AI Agent Skills 详细说明
 
 ---