@sokeai/cli 1.0.76 → 1.0.77

package/skills/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())