@comate/zulu 1.4.0-beta.2 → 1.4.0-beta.4

package/comate-engine/assets/skills/auto-commit/scripts/logger.py

@@ -0,0 +1,32 @@
+"""smart-commit 统一日志模块
+
+日志写入 ~/.comate-engine/log/kernel-yyyy-mm-dd.log
+"""
+
+import logging
+from datetime import date
+from pathlib import Path
+
+
+def get_logger(name: str = "smart-commit") -> logging.Logger:
+    """获取 smart-commit 日志实例
+
+    Args:
+        name: 日志名称，默认 "smart-commit"
+
+    Returns:
+        配置好的 Logger 实例，写入 ~/.comate-engine/log/kernel-yyyy-mm-dd.log
+    """
+    logger = logging.getLogger(f"comate.{name}")
+    if not logger.handlers:
+        log_dir = Path.home() / ".comate-engine" / "log"
+        log_dir.mkdir(parents=True, exist_ok=True)
+        log_file = log_dir / f"kernel-{date.today().isoformat()}.log"
+        handler = logging.FileHandler(log_file, encoding="utf-8")
+        handler.setFormatter(logging.Formatter(
+            "[%(asctime)s] [smart-commit] [%(levelname)s] %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S"
+        ))
+        logger.addHandler(handler)
+        logger.setLevel(logging.DEBUG)
+    return logger

package/comate-engine/assets/skills/auto-commit/scripts/match_card_cli.py

@@ -0,0 +1,41 @@
+"""命令行工具：查询 iCafe 匹配卡片
+
+用法:
+    python3 match_card_cli.py --username "dongkexin01"
+
+输出:
+    JSON 格式的匹配结果，包含 cards、space_prefix、available_types 等字段。
+    失败时输出 {"error": "错误信息"} 或 {"disabled": true, "message": "..."}。
+"""
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from cache_manager import update_icafe_result
+from icafe.matching import find_matching_card
+
+
+def main():
+    """解析命令行参数并查询匹配卡片。"""
+    parser = argparse.ArgumentParser(description="查询 iCafe 匹配卡片")
+    parser.add_argument("--username", default=None, help="用户名，如 dongkexin01")
+    args = parser.parse_args()
+
+    try:
+        username = args.username or os.environ.get("COMATE_USERNAME")
+        result = find_matching_card(current_user=username)
+        output = json.dumps(result, ensure_ascii=False)
+        print(output)
+        if isinstance(result, dict) and "error" not in result:
+            update_icafe_result(result)
+    except Exception as e:
+        print(json.dumps({"error": f"查询匹配卡片异常: {type(e).__name__}: {e}"}))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/comate-engine/assets/skills/auto-commit/scripts/payload_validators.py

@@ -0,0 +1,309 @@
+"""共享 payload 验证和转换函数
+
+为 build_icafe_cards_payload.py 和 build_git_commit_payload.py 提供验证和转换逻辑。
+每个验证函数返回错误列表（list[str]），空列表表示验证通过。
+"""
+
+import json
+
+
+def _check_type(value, expected_type, path):
+    """检查值的类型，返回错误列表。"""
+    if not isinstance(value, expected_type):
+        type_name = expected_type.__name__ if isinstance(expected_type, type) else str(expected_type)
+        actual_name = type(value).__name__
+        if expected_type is str and isinstance(value, (int, float)):
+            actual_name = "数字"
+        return [f"'{path}' 应为 {type_name}，实际为 {actual_name}"]
+    return []
+
+
+def convert_icafe_cards_payload(raw):
+    """将模型传入的原始数据转换为 camelCase payload。
+
+    接受 snake_case 或 camelCase 的混合输入，完成转换和合并。
+    模型只需要把 match_card_cli.py 的输出原封传入，加上 viewMode 和 cards（排序后）。
+
+    Args:
+        raw: 模型传入的原始 dict
+
+    Returns:
+        (converted_data, errors)
+    """
+    errors = []
+
+    if not isinstance(raw, dict):
+        return None, ["输入必须是一个 JSON 对象"]
+
+    # 从 raw 中提取字段，兼容 snake_case 和 camelCase
+    cards = raw.get("cards", [])
+    space_prefix = raw.get("spacePrefix") or raw.get("space_prefix", "")
+    space_id = raw.get("spaceId") or raw.get("space_id", 0)
+    space_name = raw.get("spaceName") or raw.get("space_name", "")
+    available_spaces = raw.get("availableSpaces") or raw.get("available_spaces", [])
+    view_mode = raw.get("viewMode") or raw.get("view_mode", "")
+    defaults_raw = raw.get("defaults", {})
+
+    # 构建 defaults
+    if isinstance(defaults_raw, dict):
+        defaults = {
+            "title": defaults_raw.get("title", ""),
+            "typeId": defaults_raw.get("typeId") or defaults_raw.get("type_id", ""),
+            "typeName": defaults_raw.get("typeName") or defaults_raw.get("type_name", ""),
+            "spaceId": defaults_raw.get("spaceId") or defaults_raw.get("space_id", 0),
+        }
+    else:
+        defaults = {"title": "", "typeId": "", "typeName": "", "spaceId": 0}
+
+    # 如果模型没传 defaults 但 raw 里有顶层字段，从顶层取
+    if not defaults.get("typeId") and raw.get("available_types"):
+        defaults["typeId"] = str(raw["available_types"][0]["id"]) if raw["available_types"] else ""
+        defaults["typeName"] = raw["available_types"][0]["name"] if raw["available_types"] else ""
+    if not defaults.get("spaceId") and space_id:
+        defaults["spaceId"] = space_id
+
+    data = {
+        "cards": cards,
+        "spacePrefix": space_prefix,
+        "spaceId": space_id,
+        "spaceName": space_name,
+        "availableSpaces": available_spaces,
+        "viewMode": view_mode,
+        "defaults": defaults,
+    }
+
+    # 验证
+    errors.extend(_validate_icafe_cards(data))
+
+    return data, errors
+
+
+def _validate_icafe_cards(data):
+    """验证转换后的 icafe-cards payload。"""
+    errors = []
+
+    # cards
+    if not isinstance(data["cards"], list):
+        errors.append("'cards' 应为数组")
+    else:
+        for i, card in enumerate(data["cards"]):
+            if not isinstance(card, dict):
+                errors.append(f"'cards[{i}]' 应为对象")
+                continue
+            for key in ("sequence", "title", "type", "status"):
+                if key not in card:
+                    errors.append(f"'cards[{i}].{key}' 缺失")
+                elif not isinstance(card[key], str):
+                    # sequence 可能是数字，转成字符串
+                    if key == "sequence":
+                        card[key] = str(card[key])
+                    else:
+                        errors.append(f"'cards[{i}].{key}' 应为字符串")
+
+    # spacePrefix
+    if not isinstance(data["spacePrefix"], str):
+        errors.append("'spacePrefix' 应为字符串")
+    elif not data["spacePrefix"]:
+        errors.append("'spacePrefix' 不能为空字符串")
+
+    # spaceId
+    if not isinstance(data["spaceId"], (int, float)):
+        errors.append("'spaceId' 应为数字")
+
+    # spaceName
+    if not isinstance(data["spaceName"], str):
+        errors.append("'spaceName' 应为字符串")
+
+    # availableSpaces
+    if not isinstance(data["availableSpaces"], list):
+        errors.append("'availableSpaces' 应为数组")
+    else:
+        for i, space in enumerate(data["availableSpaces"]):
+            if not isinstance(space, dict):
+                errors.append(f"'availableSpaces[{i}]' 应为对象")
+                continue
+            for key in ("id", "prefix", "name", "types"):
+                if key not in space:
+                    errors.append(f"'availableSpaces[{i}].{key}' 缺失")
+            # types 检查（但允许为空）
+            if "types" in space and isinstance(space["types"], list):
+                for j, t in enumerate(space["types"]):
+                    if not isinstance(t, dict):
+                        errors.append(f"'availableSpaces[{i}].types[{j}]' 应为对象")
+                        continue
+                    if "id" not in t:
+                        errors.append(f"'availableSpaces[{i}].types[{j}].id' 缺失")
+                    if "name" not in t:
+                        errors.append(f"'availableSpaces[{i}].types[{j}].name' 缺失")
+
+    # viewMode
+    valid_modes = ("list", "create")
+    if not isinstance(data["viewMode"], str):
+        errors.append(f"'viewMode' 应为字符串，取值范围为 {valid_modes}")
+    elif data["viewMode"] not in valid_modes:
+        errors.append(f"'viewMode' 应为 {valid_modes} 之一，实际为 '{data['viewMode']}'")
+
+    # defaults
+    if not isinstance(data["defaults"], dict):
+        errors.append("'defaults' 应为对象")
+    else:
+        defaults = data["defaults"]
+        for key in ("title", "typeId", "typeName", "spaceId"):
+            if key not in defaults:
+                errors.append(f"'defaults.{key}' 缺失")
+        if "title" in defaults:
+            errors.extend(_check_type(defaults["title"], str, "defaults.title"))
+        if "typeId" in defaults:
+            errors.extend(_check_type(defaults["typeId"], str, "defaults.typeId"))
+        if "typeName" in defaults:
+            errors.extend(_check_type(defaults["typeName"], str, "defaults.typeName"))
+        if "spaceId" in defaults:
+            if not isinstance(defaults["spaceId"], (int, float)):
+                errors.append("'defaults.spaceId' 应为数字")
+            else:
+                defaults["spaceId"] = int(defaults["spaceId"])
+
+    # spaceId 转为 int
+    if isinstance(data["spaceId"], float):
+        data["spaceId"] = int(data["spaceId"])
+
+    return errors
+
+
+def convert_git_commit_payload(raw):
+    """将模型传入的原始数据转换为并验证 git-commit payload。
+
+    模型需要传入 commitMessage、boundCard、workspaces。
+    workspaces 中的 diffSummary 保持 snake_case（与 git_diff_cli.py 输出一致）。
+
+    Args:
+        raw: 模型传入的原始 dict
+
+    Returns:
+        (converted_data, errors)
+    """
+    errors = []
+
+    if not isinstance(raw, dict):
+        return None, ["输入必须是一个 JSON 对象"]
+
+    commit_message = raw.get("commitMessage") or raw.get("commit_message", "")
+    bound_card = raw.get("boundCard") or raw.get("boundCard") or raw.get("icafe_card")
+    workspaces = raw.get("workspaces", [])
+
+    data = {
+        "commitMessage": commit_message,
+        "boundCard": bound_card,
+        "workspaces": workspaces,
+    }
+
+    errors.extend(_validate_git_commit(data))
+
+    return data, errors
+
+
+def _validate_git_commit(data):
+    """验证转换后的 git-commit payload。"""
+    errors = []
+
+    # commitMessage
+    if not isinstance(data["commitMessage"], str):
+        errors.append("'commitMessage' 应为字符串")
+    elif not data["commitMessage"]:
+        errors.append("'commitMessage' 不能为空字符串")
+
+    # boundCard
+    bound_card = data["boundCard"]
+    if bound_card is not None and not isinstance(bound_card, dict):
+        errors.append("'boundCard' 应为对象或 null")
+    elif isinstance(bound_card, dict):
+        for key in ("sequence", "title", "type", "status", "spacePrefix"):
+            if key not in bound_card:
+                errors.append(f"'boundCard.{key}' 缺失")
+        for key in ("sequence", "title", "type", "status", "spacePrefix"):
+            if key in bound_card and not isinstance(bound_card[key], str):
+                # sequence 可能是数字
+                if key == "sequence":
+                    bound_card[key] = str(bound_card[key])
+                else:
+                    errors.append(f"'boundCard.{key}' 应为字符串")
+
+    # workspaces
+    if not isinstance(data["workspaces"], list):
+        if isinstance(data["workspaces"], str):
+            errors.append("'workspaces' 应为数组，不能是字符串")
+        else:
+            errors.append("'workspaces' 应为数组")
+    elif len(data["workspaces"]) == 0:
+        errors.append("'workspaces' 数组不能为空")
+    else:
+        for i, ws in enumerate(data["workspaces"]):
+            p = f"workspaces[{i}]"
+            if not isinstance(ws, dict):
+                errors.append(f"'{p}' 应为对象")
+                continue
+
+            ws_required = {"workspace", "repoName", "currentBranch",
+                           "remoteBranches", "hasChanges", "diffSummary"}
+            for key in ws_required:
+                if key not in ws:
+                    errors.append(f"'{p}.{key}' 缺失")
+
+            if "workspace" in ws:
+                errors.extend(_check_type(ws["workspace"], str, f"{p}.workspace"))
+            if "repoName" in ws:
+                errors.extend(_check_type(ws["repoName"], str, f"{p}.repoName"))
+            if "currentBranch" in ws:
+                errors.extend(_check_type(ws["currentBranch"], str, f"{p}.currentBranch"))
+
+            # remoteBranches
+            if "remoteBranches" in ws:
+                if not isinstance(ws["remoteBranches"], list):
+                    errors.append(f"'{p}.remoteBranches' 应为数组")
+                else:
+                    for j, branch in enumerate(ws["remoteBranches"]):
+                        bp = f"{p}.remoteBranches[{j}]"
+                        if not isinstance(branch, dict):
+                            errors.append(f"'{bp}' 应为对象")
+                            continue
+                        if "name" not in branch:
+                            errors.append(f"'{bp}.name' 缺失")
+                        elif not isinstance(branch["name"], str):
+                            errors.append(f"'{bp}.name' 应为字符串")
+                        if "isCurrent" not in branch:
+                            errors.append(f"'{bp}.isCurrent' 缺失")
+                        elif not isinstance(branch["isCurrent"], bool):
+                            errors.append(f"'{bp}.isCurrent' 应为布尔值")
+
+            # hasChanges + diffSummary 一致性
+            if "hasChanges" in ws:
+                if not isinstance(ws["hasChanges"], bool):
+                    errors.append(f"'{p}.hasChanges' 应为布尔值")
+                else:
+                    ds = ws.get("diffSummary")
+                    if not ws["hasChanges"] and ds is not None:
+                        errors.append(f"'{p}.hasChanges' 为 false 时，'{p}.diffSummary' 必须为 null")
+                    elif ws["hasChanges"] and ds is None:
+                        errors.append(f"'{p}.hasChanges' 为 true 时，'{p}.diffSummary' 不能为 null")
+                    elif ws["hasChanges"] and isinstance(ds, dict):
+                        if "changed_files" not in ds:
+                            errors.append(f"'{p}.diffSummary.changed_files' 缺失")
+                        elif not isinstance(ds["changed_files"], list):
+                            errors.append(f"'{p}.diffSummary.changed_files' 应为数组")
+                        else:
+                            for k, cf in enumerate(ds["changed_files"]):
+                                cfp = f"{p}.diffSummary.changed_files[{k}]"
+                                if not isinstance(cf, dict):
+                                    errors.append(f"'{cfp}' 应为对象")
+                                    continue
+                                for fkey, ftype in [("file", str), ("insertions", int), ("deletions", int)]:
+                                    if fkey not in cf:
+                                        errors.append(f"'{cfp}.{fkey}' 缺失")
+                                    elif not isinstance(cf[fkey], ftype):
+                                        errors.append(f"'{cfp}.{fkey}' 应为 {ftype.__name__}")
+                        if "stat_summary" not in ds:
+                            errors.append(f"'{p}.diffSummary.stat_summary' 缺失")
+                        elif not isinstance(ds["stat_summary"], str):
+                            errors.append(f"'{p}.diffSummary.stat_summary' 应为字符串")
+
+    return errors

package/comate-engine/assets/skills/auto-commit/scripts/recognize_card_cli.py

@@ -0,0 +1,63 @@
+"""命令行工具：通过链接或卡片 ID 识别并获取 iCafe 卡片详情
+
+用法:
+    python3 recognize_card_cli.py --link "DevOps-iScan-35835"
+    python3 recognize_card_cli.py --link "https://console.cloud.baidu-int.com/devops/icafe/issue/xxxx/show"
+
+输出:
+    JSON 格式的卡片详情，包含 sequence、title、type、status、spacePrefix 等字段。
+    失败时输出 {"error": "错误信息"}。
+"""
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from icafe.client import ICafeQueryClient
+from icafe.matching import parse_card_id_from_link
+
+
+def main():
+    """识别 iCafe 卡片的主函数"""
+    parser = argparse.ArgumentParser(description="识别 iCafe 卡片")
+    parser.add_argument("--link", required=True,
+                        help="卡片链接或卡片 ID，示例: "
+                        "'DevOps-iScan-35835' 或 "
+                        "'https://console.cloud.baidu-int.com/devops/icafe/issue/DevOps-iScan-35835/show'")
+    args = parser.parse_args()
+
+    try:
+        parsed = parse_card_id_from_link(args.link)
+        if not parsed:
+            print(json.dumps({"error": "无法解析卡片链接或 ID，请检查格式"}))
+            sys.exit(1)
+
+        space_prefix = parsed["space_prefix"]
+        card_id = parsed["card_id"]
+
+        client = ICafeQueryClient()
+        card_detail = client.get_card_by_id(space_id=space_prefix, card_id=card_id)
+
+        if card_detail and card_detail.get("cards"):
+            card = card_detail["cards"][0]
+            print(json.dumps({
+                "success": True,
+                "sequence": card_id,
+                "title": card.get("title", ""),
+                "type": card.get("type", ""),
+                "status": card.get("status", ""),
+                "spacePrefix": space_prefix,
+            }))
+        else:
+            print(json.dumps({"error": "无法获取卡片信息，请检查链接或 ID 是否正确"}))
+            sys.exit(1)
+    except Exception as e:
+        print(json.dumps({"error": f"识别卡片异常: {type(e).__name__}: {e}"}))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/comate-engine/assets/skills/{automation-browser-comate → automation-browser}/SKILL.md

@@ -15,6 +15,7 @@ description: |
     - API documentation, blog posts, or articles
     - Quick content lookup without interaction
     For complex tasks or information-heavy pages, use `delegate_subtask` to invoke a subagent with this skill.
+hidden: true
 ---
 
 # Comate Automation Browser

package/comate-engine/assets/skills/{cnap-comate → cnap}/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: cnap
 description: Deploy, inspect and operate K8s-based applications on CNAP (Cloud-Native Application Platform).
+disable-model-invocation: true
 license: Apache-2.0
 metadata:
   author: dongshuzhao@baidu.com

package/comate-engine/assets/skills/code-review/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: code-review
+description: >-
+  使用此 skill 审查代码变更（git diff、暂存区改动、分支差异或指定 commit），检查 bug、安全风险、性能问题和代码质量。当用户想要审查、检视或检查代码改动时触发——包括"code review"、"review my changes"、"帮我审查代码"、"看看改动有没有问题"、"review HEAD~N"、"check my PR"、"CR"、"帮我过一遍"、"这段改动有没有问题"，或任何在合入/推送前评估代码变更是否正确安全的请求。此 skill 检查 diff 并输出按优先级排序的问题清单与修复建议。
+---
+
+# Code Review
+
+此 skill 用于对当前代码变更进行结构化审查。默认遵循 **review-first** 工作流：先收集范围、执行审查、输出报告，只有在用户明确要求后才进入修复阶段。
+
+## 核心原则
+
+1. **范围优先于结论**：先确认要审什么，再开始审查，避免误把"看当前改动"扩大成"审整个分支"。
+2. **风险优先于规模**：文件数和行数只用于粗分级，真实模式由风险特征决定。
+3. **证据优先于偏好**：只报告有明确代码证据的问题，不输出纯风格偏好建议。
+4. **简洁优先于详尽**：每条 finding 用 1-2 句话说清风险和建议，不堆砌文字。用户需要快速扫描，不是阅读论文。
+5. **上下文按需加载**：默认读取 diff 和局部上下文，只有在判断需要时才扩展到调用链、类型定义和相邻文件。
+6. **结果可执行**：每个 finding 都要说明影响、触发场景或证据，并给出具体建议。
+7. **失败可降级**：并行审查失败时要自动降级，而不是中断整次 review。
+
+## SubAgent 调用规范
+
+本 skill 通过 `delegate_subtask` 工具启动审查 SubAgent。每个 SubAgent 是独立的 Agent 实例，拥有只读工具集，能够自行获取 diff、搜索代码库、读取文件。
+
+- **agent_type 固定为 `"Explore"`**
+- **query**：只传递路径和范围，**不注入文件原文**——让 SubAgent 自行读取指令文件
+- 深度审查模式下，所有 `delegate_subtask` 调用**必须在同一轮响应中并行发起**，不要串行等待
+
+> Query 构建模板和各模式的完整调用示例见 `{SKILL_DIR}/references/dispatch-template.md`。主 Agent 执行 Step 3/4/5 时须读取该文件获取模板。
+
+## 工作流程
+
+### Step 1：确定审查范围与审查模式
+
+本步骤需要在**一轮响应中**完成以下全部决策：确认范围 → 输出统计 → 风险分级 → 选择审查模式。
+
+#### 1a：确定范围
+
+**用户显式指定范围时**：直接使用用户给出的范围（如 `review HEAD~3`、`review main..feature`）。
+
+**用户未指定范围时**：通过 git 命令探测当前变更状态，按以下优先级选择范围：
+1. **工作区变更优先**：staged、unstaged、untracked 中只要有任意变更，就以工作区内容为审查范围，不要扩大到整个分支
+2. **分支级审查**：仅当工作区无变更时，回退到当前分支相对于目标分支的变更
+3. **最近一次提交**：如果以上都没有内容，回退到最近一次提交的变更
+4. 如果仍没有内容，提示用户手动指定审查范围
+
+> **重要**：
+> - 尽量通过**一次 `run_command`** 完成探测，避免多轮串行调用
+> - 主 Agent 只需获取变更文件列表和统计信息即可做决策，**不要获取完整 diff 原文**，完整 diff 由 SubAgent 自行获取
+> - 确定范围后，记录下对应的 **基准 git diff 命令**（如 `git diff --cached`、`git diff <merge-base> HEAD`），后续写入每个 SubAgent 的 query 中，确保所有 SubAgent 基于同一个基准变更
+
+对于 untracked 文件：小文件直接读取全文并标记为 `[新文件]`；大文件只读取关键片段并在报告里说明为局部审查。
+
+#### 1b：范围过滤
+
+默认跳过以下低价值输入，除非用户明确要求或这些文件正是问题核心：
+- lockfile
+- 构建产物、snapshot、minified 文件
+- 二进制文件
+- 纯格式化噪音变更
+
+以下类型的变更即使很小，也应保留并提高风险等级：
+- 权限、鉴权、token、配置下发
+- 命令执行、文件读写、路径拼接
+- 网络请求、序列化/反序列化、持久化存储
+- 应用启动或初始化入口、事件分发链路、共享状态
+
+> **过滤结果必须体现在 diff 命令中**：将过滤后的文件列表写入 git diff 的路径参数（如 `git diff --cached -- src/a.ts src/b.ts`），或用 `:(exclude)` 排除低价值文件（如 `git diff --cached -- . ':(exclude)package-lock.json'`）。
+
+#### 1c：统计信息与风险分级
+
+向用户展示变更概览：变更文件数、新增/删除行数（如已获取）、是否包含新文件、是否命中高风险目录或关键词。
+
+结合以下风险信号做分级（不要只看文件数和行数）：
+- 是否命中高风险目录、模块或文件类型
+- 是否修改公共 API、类型定义、协议、持久化结构
+- 是否涉及异步流程、状态同步、缓存、并发
+- 是否涉及命令执行、路径、网络、鉴权、输入校验
+- 是否引入新文件或新增较大逻辑块
+
+#### 1d：选择审查模式
+
+**常规审查**：满足以下条件时使用单 Agent 综合审查。
+- 文件数 <= 5
+- 变更总行数 <= 200
+- 未命中高风险模块
+- 没有显著的新流程、新协议或新持久化结构
+
+**深度审查**：出现任一条件时使用 4 个 SubAgent 并行审查。
+- 文件数 > 5
+- 变更总行数 > 200
+- 命中高风险模块或边界能力
+- 存在新增文件、新主流程或明显跨模块改动
+
+**超大变更降级**：当变更非常大（例如 > 20 个文件或 > 800 行）时，不要一次性把所有上下文塞给所有 Agent。应按文件组或风险模块拆分，优先审查高风险部分，并在报告中说明存在"分批审查"或"抽样审查"。
+
+### Step 2：加载审查知识
+
+主 Agent 只需处理**业务规则**：如果仓库中存在 `.comate/rules/`、`CLAUDE.md`、`.cursorrules`、`.github/copilot-instructions.md` 等规则文件，只读取与本次变更直接相关的规则，提取 1-2 句话摘要写入 SubAgent query。与当前改动无关的规则不要注入。
+
+#### 自定义规则探测
+
+检查 `{SKILL_DIR}/references/custom-rules/` 目录：
+- 如果存在**非模板**的 `.md` 文件（`RULE_TEMPLATE.md` 不算）→ 标记 `HAS_CUSTOM_RULES = true`
+- 如果目录不存在、为空或只有 `RULE_TEMPLATE.md` → 标记 `HAS_CUSTOM_RULES = false`
+
+> 探测方式：一次 glob 或 ls 即可确认，无需读取规则文件内容。此标记用于 Step 3/4 决定是否追加 custom-reviewer SubAgent。
+
+### Step 3：发起审查
+
+读取 `{SKILL_DIR}/references/dispatch-template.md` 获取调用模板，根据 Step 1 选择的审查模式构建 query 并发起 SubAgent 调用。
+
+> SubAgent 会自行决定上下文获取策略（读取 diff 附近代码、搜索调用链、查找类型定义等），主 Agent 无需在 query 中指定上下文获取步骤。
+
+### Step 4：执行审查
+
+设 `SKILL_DIR` 为本 skill 目录的绝对路径（即 SKILL.md 所在目录）。
+
+按 `{SKILL_DIR}/references/dispatch-template.md` 中对应模式（常规/深度）的模板发起 `delegate_subtask` 调用。若 `HAS_CUSTOM_RULES = true`，在同一轮响应中追加 custom-reviewer 调用。
+
+每个 SubAgent 会自行读取对应的 reviewer 指令和输出格式，自行决定重点关注 diff 的哪些部分。
+
+### Step 5：Meta-Review 与结果归并
+
+当深度审查至少成功返回 2 个维度结果时，按 `{SKILL_DIR}/references/dispatch-template.md` 中 Meta-Review 模板发起调用。Meta-Review 的 query 中**必须包含已有的 findings 结果（JSON）**。
+
+#### 归并规则
+
+收集所有结果后，执行以下处理：
+1. **先应用 Meta-Review actions**，再追加 `missed_findings`
+2. **去重**：只有在"同一文件、重叠或相邻代码段、同一类别、同一根因"时才去重，不要机械按行号合并不同问题
+3. **合并相近问题**：同一文件的重复模式可合并为一条，但要保留所有关键位置
+4. **按严重等级排序**：`P0 > P1 > P2 > P3`
+5. **统一重新编号**：输出给用户的最终编号使用连续数字，保留来源维度作为辅助信息
+
+### Step 6：输出 Review 报告
+
+按 `{SKILL_DIR}/references/report-format.md` 中定义的模板和规则输出报告。简洁是第一优先级。
+
+### Step 7：埋点上报与收尾
+
+静默执行埋点上报（详见 `{SKILL_DIR}/references/telemetry.md`），任何失败不阻塞用户交互，不向用户展示错误信息。
+
+### Step 8：用户交互
+
+完成报告后**必须暂停**，使用 `ask_user_question` 工具向用户提供下一步选项，**不要自动执行任何修复或提交操作**。
+
+调用 `ask_user_question` 时，根据实际审查结果动态构建选项：
+
+- 如果存在 P0/P1 问题，提供以下选项：
+  1. 修复全部问题
+  2. 仅修复 P0/P1
+  3. 选择性修复（稍后指定编号）
+  4. 仅记录问题，不改代码
+
+- 如果只有 P2/P3 问题，提供以下选项：
+  1. 修复全部问题
+  2. 选择性修复（稍后指定编号）
+  3. 仅记录问题，不改代码
+
+- 如果未发现问题，跳过此步骤，直接告知用户审查通过。
+
+在用户通过 `ask_user_question` 明确选择前：
+- 不要自动修改代码
+- 不要自动提交代码
+- 不要把 review 结论当作已执行修复
+
+用户选择修复后：
+- 如果用户选择"选择性修复"，追问具体要修复的 finding 编号
+- 优先修复 P0/P1
+- 修复后可建议重新运行 review 或最小化验证
+
+## 严重等级定义
+
+| 等级 | 标记 | 含义 | 处理建议 |
+|------|------|------|----------|
+| `P0` | 🔴 | 明确的严重 bug、安全漏洞、数据损坏或崩溃风险 | 必须阻断合入 |
+| `P1` | 🟠 | 高概率逻辑问题、显著性能问题、重要边界错误 | 合入前应修复 |
+| `P2` | 🟡 | 中等可维护性或稳定性问题 | 建议本次修复或创建后续任务 |
+| `P3` | 🔵 | 低风险改进项 | 可选优化 |
+
+## 资源文件
+
+SubAgent 通过 `SKILL_DIR` 路径自行读取以下文件：
+
+- `agents/reuse-reviewer.md`、`agents/style-reviewer.md`、`agents/reliability-reviewer.md`、`agents/correctness-reviewer.md`：四个维度的审查指令
+- `agents/custom-reviewer.md`：自定义规则扫描指令（仅 `HAS_CUSTOM_RULES = true` 时被调用）
+- `agents/meta-reviewer.md`：Meta-Review 指令
+- `references/output-schema.md`：SubAgent 输出结构
+- `references/dispatch-template.md`：SubAgent 调度模板（主 Agent 读取）
+- `references/report-format.md`：报告输出格式（主 Agent 读取）
+- `references/telemetry.md`：埋点上报逻辑（主 Agent 读取）
+- `references/custom-rules/*.md`：用户自定义审查规则文件（`RULE_TEMPLATE.md` 为模板，不参与扫描）
+
+## 备注
+
+> 以下为执行底线，当流程细节与这些原则冲突时，以此为准。
+
+- 宁可漏报低风险问题，也不输出无证据的 finding
+- 上下文不足时写"不足以确认"，不强行下结论
+- 修复阶段只改被选中的 finding 对应代码，不顺带重构或添加无关改进
+- 任何埋点/工具链失败均静默跳过，不阻塞用户交互