@sokeai/cli 1.0.77 → 1.0.78

package/skills/mono/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/README.md

@@ -0,0 +1,18 @@
+# soke-cli Multi Skills
+
+本目录按业务模块提供独立 Skill。每个一级目录都包含自己的 `SKILL.md`，其余子目录是该 Skill 的内部参考资料、示例、模板或脚本。
+
+安装全部模块：
+
+```bash
+cp -r skills/multi/soke-* ~/.claude/skills/
+```
+
+安装单个模块：
+
+```bash
+cp -r skills/multi/soke-exam ~/.claude/skills/
+```
+
+每个模块都应能够脱离原仓库独立读取；模块之间不依赖兄弟目录。
+

package/skills/multi/soke-ai-coach-director/CHANGELOG.md

@@ -0,0 +1,203 @@
+# 变更日志
+
+## v2.43.1 — 2026-08-19
+
+### exec-part5.md 并入 exec-part4.md（文件删除）
+
+**背景**：v2.43 已将 Part5 固定配置合并进 Part4 弹窗+同批 apply，exec-part5.md 仅剩向后兼容用途，创建型任务不再加载。用户要求彻底合并去掉该文件。
+
+**变更**：
+1. 删除 `references/exec-part5.md`——独有规则（6 项固定值禁按场景调整 / 字段名以实际发布版本为准 / 不同步 closing_dialogue 等已在前序 Part 同步的字段）已并入 exec-part4.md 注意事项区
+2. 删除 `references/subs/part5/`（SOP 自检清单已内联 exec-part4 断言区）
+3. 更新引用：SKILL.md（版本行/规则 34/加载清单/禁止加载清单）、interaction.md（模板 4 改为 Part4+5 合并确认，原模板 5 删除）、sync-engine.md（文件产出表+一致性扫描合并为 Part4+5 行）、adapters/workbuddy.md（按钮表合并）、README.md
+4. 加载清单不变（仍 ≤9 次读取）——exec-part5.md 本就不在加载路径上，本次是清理死文件
+
+**收益**：技能包文件数 -2，消除"发现 exec-part5.md 会不会要读"的歧义；对积分无影响（该文件已不在加载路径）。
+
+## v2.43.0 — 2026-08-19
+
+### 交付后不写日志 + 剩余 5 项优化（88.37 → 目标 ~73-77）
+
+**背景**：v2.42 实测 88.37（场景内容量更大：6 环节+803字OS+7知识条目，工具化收益真实）。用户要求：分发版同步平台后不写日志 + 继续压积分。
+
+**日志规则（规则 31，分发版核心诉求）**：
+- 创建型任务在平台同步、发布、知识包绑定成功后直接输出完成摘要并结束
+- 禁止自动编辑 SKILL.md、CHANGELOG.md、README.md、项目工作日志或新增学习条目
+- 仅用户明确要求"更新技能/记录经验/维护日志"时才执行维护写入
+- `state-snapshot.json` 仍保留断点恢复状态（每个 Part apply 后写），不作为运行日志
+
+**5 项优化（规则 32-35）**：
+1. **get 回读零上下文（规则 32）**：/tmp/scenario_get.json 只允许 gate_check.py 读取，AI 禁止 Read/tail 引入上下文；闸门结果只看脚本单行输出（省 ~3-4，Step6-8 实测 7.40 偏高，脚本校验后又人工核对是双份）
+2. **知识包条目预生成（规则 33）**：Step 0.5 写提炼稿时同步产出 /tmp/kb-entries.json，Step 10 只剩 sync+bind（省 ~2-3，Step10 实测 13.07 里拆条是二次推导）
+3. **Part4+5 合并应用（规则 34）**：Part5 固定配置不再单独弹窗+apply，并入 Part4 弹窗和同批 operations（省 1 弹窗+1 apply ≈ 2-3）
+4. **材料 sed 限流（规则 35）**：sed 抓段后接 `| head -c 6000`，防关键词密集段一次抓几万字（省 ~1-2）
+5. **交付后不写日志（规则 31）**：见上
+
+**成本结构结论**（88.37 实测）：
+- 内容生成 48.90（55.3%）是**不可压地板**——角色画像/环节/评分就是陪练质量本身
+- 可压空间只有执行浪费 ~11-15 分；再往下只能砍内容（角色 3→2、环节 6→5）或砍知识包，属产品决策非执行优化
+- 积分目标从 ≤60 修正为 **≤75**（诚实反映内容生成成本）
+
+**文件变更**：
+- 更新：SKILL.md（规则 31-35、Step 0.5/5/6-8/10 描述、加载清单 Part4+5 合并行）
+- 更新：exec-part4.md（并入 Part5 固定配置 + 合并弹窗引导语）
+- exec-part5.md 保留（向后兼容，但创建型任务不再加载）→ **v2.43.1 已删除并彻底并入 exec-part4.md**
+
+## v2.42.0 — 2026-08-19
+
+### 工具化优化（79.64 → 目标 ~62）
+
+**背景**：v2.41.1 实测 79.64 积分（较 142.19 大幅下降，加载清单生效），但离 60 目标还差 ~19.6 分。超支点全是"规则已有但没执行"：
+1. 闸门阶段 8 轮 Python 逐步探查 get-scenario 返回结构（~8 分，最大头）
+2. 材料分 4 轮 sed 逐段读手册（~4.5 分）
+3. 读取禁止加载文件 3 个（~3.5 分，其中 part2-roles.md 是被迫——exec-part2 引用 A1-A7 却没内联结构）
+4. apply 后额外校验（~3.6 分）
+
+**根因**：规则是声明性的，AI 执行时因"不知道返回结构"只能边看边猜拆轮探查。
+
+**4 项工具化修复（规则 → 现成工具）**：
+1. **闸门工具化（规则 27）**：新增 `scripts/gate_check.py`——一次跑完 Step 7+8 全部校验（4 项发布闸门 + 3 项补查），自动解包 {data:{...}} 嵌套，Part3 steps 空值告警不阻塞，Part4 权重校验。输出单行 GATE PASS/FAIL。已双路径测试通过。**禁止再用 Python 逐步探查返回结构**（省 ~8 分）
+2. **材料 sed 单命令（规则 28）**：提炼稿只允许一个 sed 命令用多模式一次抓完全部关键段落，禁止分轮读（省 ~4.5 分）
+3. **OS 结构内联（规则 29）**：A1-A7 OS 写作结构从 part2-roles.md 内联到 exec-part2.md，消除被迫读取（省 ~1.5 分）
+4. **apply 后零校验（规则 30）**：apply/publish/sync/bind 成功后只看 tail -3 状态行，禁止任何额外校验，验证统一收敛到闸门 gate_check.py（省 ~3.6 分）
+
+**预期**：79.64 - 8 - 4.5 - 1.5 - 3.6 ≈ 62 积分（接近 60 目标）
+
+**文件变更**：
+- 新增：`scripts/gate_check.py`（闸门一次性校验器，双路径测试通过）
+- 更新：`SKILL.md` 版本 v2.42.0 + 规则 27-30 + 加载清单 Step 6-8 行
+- 更新：`references/exec-part2.md` 内联 A1-A7 OS 写作结构
+
+## v2.41.1 — 2026-08-18
+
+### Bug 修复（用户反馈 3 个问题）
+
+**问题 1：弹窗仍显示完整内容**
+- 根因：`interaction.md` 仍保留 v2.37 规则（question 字段承载完整内容），与 SKILL.md v2.41 规则（摘要化展示）冲突
+- 修复：重写 interaction.md 核心规则 5 + v2.41 弹窗规则 + question 字段模板 + AskUserQuestion 调用示例 + 模板 1-5 的 question 字段，全部改为 ≤2 行引导语
+- 同步修复 SKILL.md 前台可见行和输出格式行
+
+**问题 2：创建完成后为什么要写入 gkill（state-snapshot.json）**
+- 回答：state-snapshot.json 是**断点续传**机制——记录 scenario_id / current_part / applied 标志 / confirmed_data。如果中途中断（网络断/会话超时），下次可以从断点恢复，不用从头创建。这不是浪费，是必要的容错机制。但 v2.41 已将 file_reads 计数器加入其中。
+
+**问题 3：优化后比优化前消耗更多（142.19 vs 93.19）**
+- 根因分析：
+  1. **技能文件过度加载（~27 次 Read）**：规则要求 ≤8 次，实际读了 27 次（exec-part1-5 + part1-5 框架 + 3 个子 SOP + cheatsheet + sync-engine + interaction + publish-gate + gate-matrix + 场景分类库 + soke-ai-training）。这是最大浪费源——"求稳求全"而非"按需加载"
+  2. **CLI 命令 help 探测（~6 次）**：规则明确禁止为查格式跑 --help，实际跑了 6 次
+  3. **知识包 sync 重试 1 次**：--output 参数不存在导致失败重跑
+- 根本原因：v2.41 的规则是**声明性**的——说了"≤8 次"但没有强制拦截机制。AI 在执行时"求稳求全"，把所有可能用到的文件都预读了
+- 修复方向：需要从"声明规则"转向"结构性约束"——在 SKILL.md 中加入**加载顺序清单**（精确到每个 Step 读哪个文件），让 AI 按清单执行而非自行判断
+
+## v2.41.0 — 2026-08-18
+
+### 深度结构优化（目标 60 积分）
+
+**背景**：v2.40 后实测 94 积分，用户要求控制在 60 左右。分析 94 积分构成：
+- Part1-5 生成 35 (37%) / 技能加载 15 (16%) / CLI 15 (16%) / 回读排障 13 (14%) / 材料 10 (11%) / 弹窗 6 (6%)
+- 可避免 ~14 分：Part2 重试 5 + 无关 PDF 4 + 积分排查 5
+
+**5 项结构性优化**：
+1. **exec-handbook 按 Part 拆分（规则 22）**：26KB 单文件 → 5 个 ~5KB Part 文件 + 4KB common 文件。每个 Part 只加载对应文件，总加载量 26KB → ~9KB（-65%）
+2. **Part 展示摘要化（规则 23）**：聊天正文只展示关键字段摘要，完整 JSON 直接 Write 落盘 /tmp/。中文 token 密度降低 ~60%
+3. **材料预过滤（规则 24）**：pdftotext 前先看文件名/标题，无关材料直接跳过（省 ~4 分）
+4. **apply --reason 内联（规则 25）**：apply 必须带 --reason 参数，格式内联 CLI 速查表（省 Part2 重试 ~5 分）
+5. **CLI 合并调用（规则 26）**：Part2 头像+语音列表合并为 1 次 Bash 调用（省 1 次独立调用）
+
+**预期效果**：
+- 技能加载 15 → 7（-8）：exec-handbook 拆分省 8KB token
+- Part1-5 生成 35 → 28（-7）：摘要化展示省中文 token
+- CLI 15 → 11（-4）+ 回读 13 → 8（-5）：合并调用 + --reason 防重试
+- 材料 10 → 6（-4）：预过滤省无关 PDF
+- 总计：94 - 8 - 7 - 9 - 4 = 66 积分（接近 60 目标）
+
+**文件变更**：
+- 新增：`references/exec-common.md` / `exec-part1.md` / `exec-part2.md` / `exec-part3.md` / `exec-part4.md` / `exec-part5.md`
+- 保留：`references/exec-handbook.md`（向后兼容，微调型任务仍可引用）
+- 更新：`SKILL.md` 版本 v2.40 → v2.41，规则 22-26，CLI 速查表，Step 0.5/5 描述
+
+## v2.40.0 — 2026-08-18
+
+### 结构性优化（积分增长根因修复）
+
+**问题**：v2.39 优化后积分从 126 增至 147（+21），原因：
+1. 分析阶段自身消耗 ~10 积分（读 20+ 文件 + 改 5 文件）
+2. 文件膨胀反噬 ~6 积分（SKILL +2 规则、矩阵 +列、SOP +表）
+3. 规则无强制机制 ~3 积分（规则 17/18 是声明，无计数器）
+4. 三大浪费未触及 ~2 积分（CLI 探索/标杆查找/Part3 调查）
+
+**修复**：
+- **规则 17-18 精简**：从 ~400 字缩减为 2 行指针引用，详细说明留在 `gate-check-matrix.md`
+- **规则 19 CLI 命令内联**：高频命令格式直接写入 SKILL.md「CLI 速查」表，禁止为查格式而 Read cheatsheet 文件（省 5 次文件读取）
+- **规则 20 禁止标杆查找**：创建型任务不搜索不加载标杆案例（省 2 次操作）
+- **规则 21 Part3 回读限制**：apply 后只做 1 次布尔断言，禁止多次 get 调查（省 3 次操作）
+- **文件读取计数器**：state-snapshot.json 记录 `file_reads`，超 8 次触发警告（声明→强制）
+
+**预期效果**：消除 18 次可避免操作中的 10 次（CLI 探索 5 + 标杆 2 + Part3 调查 3），预估 147 → ~125 积分。剩余 ~45 积分差距需后续版本通过管线合并（Part2 头像/语音列表合并为 1 次调用）等结构性优化解决。
+
+## v2.39.0 — 2026-08-18
+
+### 优化（积分分析驱动）
+- **闸门精简（Part 自检通过后跳过重叠项）**：分析发现 Step 7 质量闸门 12 项中 9 项与 Part1-5 自检清单完全重叠（闸门1↔Part1自检、闸门3/4/9↔Part2自检、闸门5↔Part3自检、闸门6/10↔Part4自检、闸门7↔Part5自检）。Part 自检全部通过后，闸门仅需补查 3 项（测试用例/整体字数/展示完整度），批量校验脚本从 16 个断言缩减为 7 个。
+- **技能文件按需加载一次复用**：SKILL.md / exec-handbook.md / 各 Part SOP.md / gate-check-matrix.md 在管线首次加载后全程复用，禁止后续 Part 生成时重复 Read。全流程技能文件读取控制在 ≤8 次。
+- **积分目标 ≤80 可达性确认**：基于升舱场景实测（126 积分），识别 3 大浪费源（Part3 apply 验证+回滚 28 积分、闸门重复 get-scenario 16 积分、技能文件重复读 14 积分），通过 v2.39 两条新规则可节省 ~62 积分，预期降至 ~64 积分。
+
+### 问题回答
+- **Q: Part 已检验没有问题，是否不需要再检验？** → A: 是。Part 自检通过后，Step 7 闸门中与之重叠的 9 项自动视为通过，不再重复检查。仅补查 3 项非 Part 自检覆盖的内容。
+- **Q: 质量检验和 Part 是否有冲突？** → A: 无冲突，但存在冗余。Part 自检是字段级校验（执行期），闸门是发布前汇总校验。两者检查内容 75% 重叠（9/12），v2.39 通过精简规则消除冗余。
+
+## v2.30.0 — 2026-08-17
+
+### 优化
+- **Part 展示完成 → 立即弹窗确认**：移除「先输出文字请确认 → 用户输入'确认' → 再弹出确认窗」的中间文字闸门。Part 内容在对话中完整展示后立即弹出确认窗（render_ui / AskUserQuestion），弹窗即确认环节，用户直接通过弹窗选项作答，无需先回复"确认"
+- **SKILL.md / interaction.md / prompt-engineer.md / prompt-optimizer.md / exec-handbook.md / workbuddy 适配器 / part2 SOP 同步更新**：各 Part 弹窗步骤与核心规则统一补充「展示检查通过 → 立即弹窗」时序约束；正文文字确认格式仅保留给无弹窗环境的降级场景（悟空/QClaw/Zework/纯文本）
+
+## v2.29.0 — 2026-08-17
+
+### 优化
+- **登录自动化**：Step 0 检测到未登录时，AI 自动后台执行 `soke-cli auth login`（OAuth 设备流），自动打开浏览器并输出授权链接，前台一句话引导用户扫码，授权完成后自动重检并继续管线；不再要求用户手动运行命令
+- **env-check.md 重写第 3 步**：移除「无法自动化、提示用户手动执行」的旧约定，改为「后台拉起 → 提取授权链接 → 引导扫码 → 授权完成重检」四步自动流程；补充授权链接带 `cli_redirect_uri` 回调参数不可截断的注意项
+- **字段名对齐实测输出**：登录判定统一为 `config show` 的「用户凭证」，企业绑定统一为「corpid」（原 implementation_corp_id 字段实际不存在）
+- **故障速查表更新**：登录时浏览器未打开 / 授权链接无法访问的修复方式对齐自动执行流程
+
+### 触发方式
+- 创建型 / 微调型 / 同步型任务 Step 0 检测到 `用户凭证` 为空时自动触发，无需用户干预
+
+## v2.24.2 — 2026-08-07
+
+### 重构
+- **SKILL.md 瘦身**：608 → 262 → 289 行（-57%），保留 Step 0-10 流程骨架，细节委托 exec-handbook.md
+- **sync-engine.md 精简**：1154 → 294 行（-74%），从「执行手册+字段参考」双重身份精简为纯「字段参考手册」
+- **exec-handbook.md 扩充**：521 → 588 行，新增「JSON 字段类型硬规则」和「状态快照与缓存规则」两章
+
+### 策略统一
+- Part2 同步策略全局收口为「整包 `replace_ai_roles` 优先，失败降级逐个」
+- 清理 5 个文件中的旧策略残留（platform-api-pitfalls / sync-engine / interaction / prompt-engineer / subs/part2/SOP）
+
+### 结构清理
+- 删除 3 个僵尸目录：`coaching/role-generator`、`knowledge-architect`、`script-architect`
+- 删除 5 个 `api_reference.md` 副本、10 个 example 文件、残留空目录
+- `coaching/` 精简为 4 个有效技能
+
+### 新增
+- SKILL.md 新增「参考规则」表，收录 8 个 references 文件
+- SKILL.md 新增「闸门编号与确认模板映射」表（G1-G5 ↔ 模板 1-6）
+- `references/exec-handbook.md` 新增 2 章节
+- `scripts/validate_operations.py`（396 行，operations 校验工具）
+- `references/exec-handbook.md` 新增「平台头像库 URL 对照表」
+
+### 交付准备
+- 清除回归测试产物（part2-5 operations.json / state-snapshot.json / step1-create.json / kb/ 测试数据）
+- 新增 README.md（入口说明 + 依赖清单 + 快速上手）
+- 新增 CHANGELOG.md
+
+## v2.24.1 — 2026-08-06
+
+- P0+P1 重构：部署缺失文件（exec-handbook.md / validate_operations.py）
+- Part2 同步策略冲突修复
+- 僵尸目录清理
+- SKILL.md 瘦身
+- sync-engine.md 关键段并入 exec-handbook.md
+
+## v2.24.0 — 2026-08-04
+
+- 初始版本，从历史版本整合重构