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

package/comate-engine/assets/skills/code-review/evals/references/cli-query-template.md

@@ -0,0 +1,114 @@
+# CLI Query Template (Full Mode)
+
+Full mode 下，每个样本通过独立的 CLI 进程运行完整 code-review skill。本文件定义 CLI 命令模板和 query 模板。
+
+## CLI 命令模板
+
+### zulu
+
+```bash
+zulu run \
+  -l "{LICENSE}" \
+  --activate-skill code-review \
+  --cwd "{REPO}" \
+  --display task \
+  -q "{QUERY}"
+```
+
+### baidu-cc
+
+```bash
+baidu-cc \
+  -p "{QUERY}" \
+  --allowedTools "Bash,Read,Write,Edit,Glob,Grep,Agent" \
+  --cwd "{REPO}"
+```
+
+> `baidu-cc` 走内部认证，不需要 license。`--allowedTools` 确保 CLI 进程拥有完整工具集以支持多 Agent pipeline。
+
+## Query 模板
+
+以下 query 用于每个 CLI 进程的 `-q` / `-p` 参数：
+
+```
+请审查以下代码变更。
+
+## 范围（已确定，跳过 Step 1）
+
+执行以下命令获取待审 diff：
+git diff {DIFF_BASE} {DIFF_TARGET} -- {SOURCE_FILES}
+
+注意：范围已确定，不需要执行 Step 1 的范围检测逻辑。直接使用上述 diff 命令获取变更内容。
+
+## 约束
+
+- 跳过 Step 1（范围检测）：审查范围已由上述 diff 命令确定
+- 跳过 Step 8（用户交互）：不要调用 ask_user_question，完成审查报告后直接结束
+- 输出格式严格按照 Step 6 的报告格式
+
+## 审查要求
+
+- 不要预设代码中存在 bug。diff 可能是 bug 修复、功能新增、重构或其他任何类型的变更
+- 从正确性、可靠性、风格、复用四个维度进行审查
+- 如果代码实现正确且合理，直接说"审查通过"，不要硬凑问题
+- 如果发现问题，按严重等级（P0-P3）分类输出
+
+请从 Step 2 开始执行审查流程。
+```
+
+## 占位符说明
+
+| 占位符 | 来源 | 说明 |
+|--------|------|------|
+| `{REPO}` | 参数 `repo` | 目标 git 仓库绝对路径 |
+| `{LICENSE}` | 参数 `license` | zulu SaaS license key，仅 `cli=zulu` 时需要 |
+| `{DIFF_BASE}` | 根据样本类型决定 | bug-fix 样本：`commit`（反转方向）；clean 样本：`parent_commit`（正常方向） |
+| `{DIFF_TARGET}` | 根据样本类型决定 | bug-fix 样本：`parent_commit`（反转方向）；clean 样本：`commit`（正常方向） |
+| `{SOURCE_FILES}` | `candidates.json` 中的 `source_files` | 空格分隔的源码文件路径列表 |
+| `{QUERY}` | 上方 Query 模板填充后的完整文本 | CLI 的 prompt 参数 |
+
+### Diff 方向规则
+
+| 样本类型 | diff 命令 | 含义 |
+|----------|-----------|------|
+| bug-fix | `git diff {COMMIT} {PARENT_COMMIT} -- {FILES}` | 反转 diff：修复后 → 修复前，模拟"引入 bug 的变更" |
+| clean | `git diff {PARENT_COMMIT} {COMMIT} -- {FILES}` | 正常 diff：修改前 → 修改后，"引入新功能的变更" |
+
+## 设计说明
+
+### 为什么跳过 Step 1
+
+生产环境中 Step 1 通过 `git status` 探测工作区变更来确定审查范围。但 eval 场景下 diff 来自历史 commit 而非工作区，Step 1 的探测逻辑会走到错误分支。因此直接提供 diff 命令，跳过范围检测。
+
+### 为什么跳过 Step 8
+
+Step 8 调用 `ask_user_question` 等待用户选择修复方案。eval 需要全自动运行数十个样本，不能每个都停下来等人交互。
+
+### 为什么反转 bug-fix diff
+
+真实的 code review 场景是审查"有人提交了一段新代码"。如果直接用 bug-fix commit 的 diff（修复前 → 修复后），skill 看到的是"有人在修 bug"，会合理地认为"修复正确，审查通过"。反转后，skill 看到的是"有人提交了引入 bug 的代码"，这才是测试 bug 检测能力的正确方式。Clean 样本本身就是"引入新功能"，不需要反转。
+
+### 信息对称
+
+Query 中**不包含** commit subject 和样本类型（bug-fix / clean），确保 skill 和 GT 生成器在相同信息条件下运行。
+
+## Shell 并发控制模板
+
+主 Agent 根据 `candidates.json` 生成完整脚本。以下是并发控制的关键模式：
+
+```bash
+MAX_PARALLEL=5
+RUNNING=0
+
+for ARGS in "${SAMPLES[@]}"; do
+  run_review $ARGS &
+  RUNNING=$((RUNNING + 1))
+  if [ "$RUNNING" -ge "$MAX_PARALLEL" ]; then
+    wait -n 2>/dev/null || wait  # bash 4.3+ 支持 wait -n，低版本回退到 wait 全部
+    RUNNING=$((RUNNING - 1))
+  fi
+done
+wait
+```
+
+> `wait -n` 在 bash 4.3+ 可用，等待任一后台进程完成。低版本 bash 可用 `wait` 等待全部完成后再启动下一批。

package/comate-engine/assets/skills/code-review/evals/references/gt-schema.md

@@ -0,0 +1,77 @@
+# Semantic Ground Truth Schema
+
+每个被评估的样本对应一个 JSON 文件，存放在 `semantic_gt/` 目录下。
+
+## 文件命名
+
+`<sample_id>.json`，例如 `sample-0001.json`（bug-fix 样本）或 `clean-0001.json`（clean 样本）
+
+## Schema
+
+### 有 findings 的样本
+
+GT 生成器从 diff 中独立判断新引入代码存在问题时产出：
+
+```json
+{
+  "sample_id": "sample-0001",
+  "findings": [
+    {
+      "file": "packages/webview/src/components/Chat.tsx",
+      "line_range": [754, 765],
+      "dimension": "correctness",
+      "severity": "P1",
+      "description": "新引入的 hasAcceptedPath 是模块级单值变量，多文件采纳时只有最后一个被保护",
+      "root_cause": "变量被设计为单值字符串而非 Set，导致跨文件的采纳操作互相覆盖",
+      "expected_review": "新增的 hasAcceptedPath 守卫仅保护单一路径，多文件场景下后续采纳会覆盖先前状态；应改为 Set 或使用 Map 追踪所有已采纳路径"
+    }
+  ]
+}
+```
+
+### 无 findings 的样本
+
+GT 生成器从 diff 中独立判断新引入代码无明显问题时产出：
+
+```json
+{
+  "sample_id": "clean-0001",
+  "findings": []
+}
+```
+
+**注意**：GT 生成器不知道样本的真实类型（bug-fix 或 clean）。因此：
+- bug-fix 样本的 GT **通常**有 findings（反转 diff 中新增的 `+` 行就是有 bug 的代码），但如果 bug 非常隐蔽、仅从 diff 看不出来，GT 也可能为空
+- clean 样本的 GT **通常**为空，但如果 GT 生成器从 diff 中发现了新引入代码的真实问题，也可能有 findings
+
+这是信息对称设计的核心：GT 的质量反映的是"仅从 diff 能看出多少问题"，和 skill 的评判条件完全一致。
+
+## 字段说明
+
+### 顶层字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `sample_id` | string | 是 | 样本 ID，与 candidates.json 中的 id 一致 |
+| `findings` | array | 是 | findings 数组，有问题时至少一条，无问题时为空数组 `[]` |
+
+### Finding 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `findings[].file` | string | 是 | 相对于仓库根目录的文件路径 |
+| `findings[].line_range` | [int, int] | 是 | 问题所在的代码区域 |
+| `findings[].dimension` | string | 是 | `correctness` / `reliability` / `style` / `reuse`，与主 skill 的四个审查维度对齐 |
+| `findings[].severity` | string | 是 | `P0` / `P1` / `P2` / `P3` |
+| `findings[].description` | string | 是 | 描述**新引入的代码**存在什么问题（diff 中 `+` 行的缺陷） |
+| `findings[].root_cause` | string | 是 | 为什么存在这个问题（深层原因） |
+| `findings[].expected_review` | string | 是 | 一个优秀 reviewer 看到这个 diff 时应该指出什么（判分关键锚点） |
+
+## 核心原则
+
+- **描述新引入代码的问题**：`description` 说"新引入的代码什么地方有问题"（diff 中 `+` 行的缺陷）
+- **expected_review 是判分锚点**：它描述 reviewer 看到这个 diff 时应该说什么，和 skill 的输出最直接可比
+- **一个问题 = 一条 finding**：不要按 diff hunk 展开，按逻辑问题聚合
+- **severity 反映问题严重度**：不是修复的重要性
+- **信息对称**：GT 生成器和 code-review skill 只能看到 diff，不能利用 commit subject、样本类型等额外信息
+- **独立判断**：GT 生成器不知道样本是 bug-fix 还是 clean，必须完全依赖 diff 内容判断

package/comate-engine/assets/skills/code-review/references/custom-rules/RULE_TEMPLATE.md

@@ -0,0 +1,141 @@
+# 自定义规则模板
+
+> **使用说明**
+>
+> 1. 复制此文件，重命名为你的规则集名称（如 `MY_PROJECT_RULES.md`、`TEAM_API_RULES.md`）
+> 2. 按照下方格式填写规则内容
+> 3. 将文件放在同一目录（`custom-rules/`）下，审查时会自动加载
+> 4. 本文件（`RULE_TEMPLATE.md`）本身不会被加载为规则
+
+---
+
+## 文件头（必填）
+
+```yaml
+# 规则集名称（必填）
+title: 我的项目规则
+
+# 规则集描述（选填）
+description: 针对 XX 项目的业务规范和技术约束
+
+# 适用语言（选填）。留空 = 适用所有语言
+# 可选值: js, ts, go, java, python，逗号分隔
+applies_to: js, ts
+
+# 适用路径（选填）。只扫描匹配路径下的文件，支持通配符
+# 留空 = 不限制路径
+applies_to_path: src/api/**, src/service/**
+```
+
+---
+
+## 规则格式说明
+
+每条规则包含以下字段：
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| 规则 ID | 是 | 格式建议：`前缀_序号`，如 `PROJ_01` |
+| 规则名称 | 是 | 简短描述，建议 10 字以内 |
+| 等级标记 | 是 | `[Critical]` / `[high]` / `[middle]` / `[low]` |
+| `category` | 否 | 问题分类标识，用于输出的 category 字段；留空则为 `custom-rule` |
+| `检测` | 是 | 描述触发此规则的代码模式，越具体越好 |
+| `排除` | 推荐 | 满足哪些条件时不报告此问题 |
+| `复核` | 选填 | 上报前必须额外确认的条件，避免误报 |
+| 代码示例 | 推荐 | 反例（错误写法）和正例（正确写法） |
+
+---
+
+## 规则示例
+
+以下是几条示范规则，覆盖不同等级和场景，请参照格式编写你自己的规则。
+
+---
+
+### EXAMPLE_01. 禁止直接操作 DOM 绑定事件 [high]
+- **category**: `framework-misuse`
+- **检测**：在 Vue/React 组件中使用 `document.addEventListener` 或 `element.addEventListener` 绑定事件，而非框架提供的事件机制
+- **排除**：第三方库初始化必须手动绑定；在 `componentWillUnmount` / `onUnmounted` 中已有对应的 `removeEventListener`
+- **复核**：确认组件卸载时未清理事件监听，会导致内存泄漏
+
+```javascript
+// 反例 — 未清理的 DOM 事件
+mounted() {
+  document.addEventListener('keydown', this.handleKey)
+  // 忘记在 beforeUnmount 中移除
+}
+
+// 正例 — 使用框架事件机制
+// <template><div @keydown="handleKey"></div></template>
+
+// 正例 — 如必须手动绑定，记得清理
+mounted() { document.addEventListener('keydown', this.handleKey) }
+beforeUnmount() { document.removeEventListener('keydown', this.handleKey) }
+```
+
+---
+
+### EXAMPLE_02. API 接口必须校验返回的分页参数 [middle]
+- **category**: `boundary-condition`
+- **检测**：调用分页接口后直接使用 `data.list` 进行渲染，未检查 `data.total` 或 `data.hasMore` 是否存在
+- **排除**：接口明确文档标注 `list` 永不为 null；接口已有统一的响应拦截器处理
+
+```javascript
+// 反例
+const { list } = await fetchPagedData({ page: 1 })
+this.items = list  // list 为 null 时直接崩溃
+
+// 正例
+const { list = [], total = 0 } = await fetchPagedData({ page: 1 })
+this.items = list
+this.total = total
+```
+
+---
+
+### EXAMPLE_03. 禁止在生产代码中使用 console.log [low]
+- **category**: `code-style`
+- **检测**：非测试文件中出现 `console.log(` 调用
+- **排除**：文件路径包含 `test`、`spec`、`__tests__`；注释标注了 `// dev-only`；文件是独立的调试工具脚本
+
+---
+
+### EXAMPLE_04. 用户输入必须通过 sanitize 函数处理 [Critical]
+- **category**: `reliability`
+- **检测**：将 `req.body`、`req.query`、`req.params` 中的字段直接拼入 SQL 查询字符串，或直接赋值给 `innerHTML`
+- **排除**：已通过 ORM 参数化查询；已通过 `DOMPurify.sanitize()` 或同等函数处理
+- **复核**：确认数据来源是用户可控的外部输入；确认目标是 SQL 或 HTML 上下文
+
+```javascript
+// 反例 — SQL 注入风险
+const sql = `SELECT * FROM users WHERE name = '${req.query.name}'`
+
+// 反例 — XSS 风险
+element.innerHTML = req.body.content
+
+// 正例
+const sql = 'SELECT * FROM users WHERE name = ?'
+db.query(sql, [req.query.name])
+
+// 正例
+element.innerHTML = DOMPurify.sanitize(req.body.content)
+```
+
+---
+
+## 规则编写技巧
+
+**写好「检测」的关键**：
+- 描述具体的代码模式，而非抽象原则。"在 `if` 条件中使用 `=`" 比 "避免赋值运算符" 更好
+- 如果依赖上下文（如"在循环内"、"未 await"），明确说明上下文范围
+- 可以引用具体的函数名、API 名、字段名
+
+**写好「排除」的关键**：
+- 想清楚哪些情况下这个模式是合理的
+- 排除条件越明确，误报越少
+
+**等级选择参考**：
+- `[Critical]`：必报、Meta-Review 不得降级，用于安全漏洞、数据损坏等
+- `[high]`：高概率有实际影响的问题
+- `[middle]`：影响可维护性或稳定性，但不紧急
+- `[low]`：纯规范/偏好类，可忽略

package/comate-engine/assets/skills/code-review/references/dispatch-template.md

@@ -0,0 +1,142 @@
+# SubAgent 调度模板
+
+本文件定义主 Agent 构建 SubAgent query 的标准模板。主 Agent 只需按模板填入路径和 diff 命令，**不预读** agents/*.md 或 references/*.md 的内容。
+
+## Query 构建模板
+
+```
+你是代码审查专家，负责【维度名称】审查。
+
+1. 读取审查指令：<skill绝对路径>/agents/<维度>-reviewer.md
+2. 读取输出格式：<skill绝对路径>/references/output-schema.md
+3. 执行以下命令获取待审变更：
+   <git diff 命令>
+4. 根据审查指令完成审查，使用 read_file 读取变更文件上下文（±30 行），用 grep_content/codebase_search 搜索调用链和已有实现
+5. 严格按输出格式返回 JSON。未发现问题时返回空 findings 数组
+
+补充上下文：<与本次变更相关的业务规则摘要（如有，1-2 句话；无则省略此行）>
+```
+
+> **关键原则**：主 Agent 不预读 agents/*.md 和 references/*.md 的内容再注入 query。只需告知路径，SubAgent 有 read_file 能力，会自行加载。这大幅减少主 Agent 的准备工作和输出 token。
+
+---
+
+## 常规审查模式
+
+发起一个 `delegate_subtask` 调用：
+
+```
+delegate_subtask(
+  agent_type="Explore",
+  description="Code review - 综合审查",
+  query="""
+你是代码审查专家，负责对当前变更进行综合审查（正确性、可靠性、风格、复用）。
+
+1. 依次读取以下指令文件，理解各维度的审查要点：
+   - {SKILL_DIR}/agents/correctness-reviewer.md
+   - {SKILL_DIR}/agents/reliability-reviewer.md
+   - {SKILL_DIR}/agents/style-reviewer.md
+   - {SKILL_DIR}/agents/reuse-reviewer.md
+2. 读取输出格式：{SKILL_DIR}/references/output-schema.md
+3. 执行命令获取变更：{git diff 命令}
+4. 从各维度中各关注最核心的 2-3 个检查点完成审查
+5. 仅输出有证据的问题，不报纯风格偏好。未发现问题返回空 findings
+
+{业务规则摘要（如有）}
+"""
+)
+```
+
+**若 `HAS_CUSTOM_RULES = true`**，在同一轮响应中**并行**追加一个 custom-reviewer 调用：
+
+```
+delegate_subtask(
+  agent_type="Explore",
+  description="Code review - 自定义规则扫描",
+  query="你是自定义规则扫描专家。\n1. 读取审查指令：{SKILL_DIR}/agents/custom-reviewer.md\n2. 读取输出格式：{SKILL_DIR}/references/output-schema.md\n3. 执行：{git diff 命令}\n4. 完成审查并返回 JSON"
+)
+```
+
+---
+
+## 深度审查模式
+
+在**同一轮响应**中，并行发起 4 个 `delegate_subtask`。主 Agent **不需要预读**任何 agents/*.md 或 references/*.md 文件，直接按模板构建 query：
+
+```
+1. delegate_subtask(
+     agent_type="Explore",
+     description="Code review - 复用审查",
+     query="你是代码审查专家，负责复用审查。\n1. 读取审查指令：{SKILL_DIR}/agents/reuse-reviewer.md\n2. 读取输出格式：{SKILL_DIR}/references/output-schema.md\n3. 执行：{git diff 命令}\n4. 完成审查并返回 JSON\n{业务规则摘要}"
+   )
+
+2. delegate_subtask(
+     agent_type="Explore",
+     description="Code review - 风格审查",
+     query="你是代码审查专家，负责风格审查。\n1. 读取审查指令：{SKILL_DIR}/agents/style-reviewer.md\n2. 读取输出格式：{SKILL_DIR}/references/output-schema.md\n3. 执行：{git diff 命令}\n4. 完成审查并返回 JSON\n{业务规则摘要}"
+   )
+
+3. delegate_subtask(
+     agent_type="Explore",
+     description="Code review - 可靠性审查",
+     query="你是代码审查专家，负责可靠性审查（资源管理、并发安全、接口鉴权）。\n1. 读取审查指令：{SKILL_DIR}/agents/reliability-reviewer.md\n2. 读取输出格式：{SKILL_DIR}/references/output-schema.md\n3. 执行：{git diff 命令}\n4. 完成审查并返回 JSON\n{业务规则摘要}"
+   )
+
+4. delegate_subtask(
+     agent_type="Explore",
+     description="Code review - 正确性审查",
+     query="你是代码审查专家，负责正确性审查。\n1. 读取审查指令：{SKILL_DIR}/agents/correctness-reviewer.md\n2. 读取输出格式：{SKILL_DIR}/references/output-schema.md\n3. 执行：{git diff 命令}\n4. 完成审查并返回 JSON\n{业务规则摘要}"
+   )
+```
+
+**若 `HAS_CUSTOM_RULES = true`**，在上述 4 个调用的**同一轮响应**中追加第 5 个：
+
+```
+5. delegate_subtask(
+     agent_type="Explore",
+     description="Code review - 自定义规则扫描",
+     query="你是自定义规则扫描专家。\n1. 读取审查指令：{SKILL_DIR}/agents/custom-reviewer.md\n2. 读取输出格式：{SKILL_DIR}/references/output-schema.md\n3. 执行：{git diff 命令}\n4. 完成审查并返回 JSON"
+   )
+```
+
+> `HAS_CUSTOM_RULES = false` 时不发起此调用，保持原有 4 个 SubAgent 并行。
+
+---
+
+## Meta-Review 调用
+
+当深度审查至少成功返回 2 个维度结果时，发起 Meta-Review：
+
+```
+delegate_subtask(
+  agent_type="Explore",
+  description="Code review - Meta Review",
+  query="""
+你是 Meta-Reviewer，负责审查其他 Agent 的 review 结果质量。
+
+1. 读取审查指令：{SKILL_DIR}/agents/meta-reviewer.md
+2. 读取输出格式：{SKILL_DIR}/references/output-schema.md（Meta-Reviewer 输出格式部分）
+3. 执行：{git diff 命令}（用于验证 findings 的准确性）
+4. 以下是待审的 findings JSON：
+
+{所有 SubAgent 返回的 findings JSON}
+
+按指令完成 Meta-Review，返回 actions 和 missed_findings。
+"""
+)
+```
+
+> 注意：Meta-Review 的 query 中**必须包含已有的 findings 结果（JSON）**，因为 Meta-Reviewer 需要这些内容来判断质量。这是唯一需要在 query 中传递较多内容的 SubAgent 调用。
+
+---
+
+## 超大变更处理
+
+超大变更时，主 Agent 可按文件组拆分给不同 subagent（如只给复用审查传新增文件、只给正确性审查传高风险文件）。
+
+## 失败回退
+
+- 某个 `delegate_subtask` 失败或超时：继续合并剩余结果，报告中注明"部分维度降级"
+- 两个及以上失败：回退为单个综合审查（常规审查模式）
+- `delegate_subtask` 工具不可用：主 Agent 直接执行审查，报告中注明"降级为单 Agent 审查"
+- 上下文过大：缩小到高风险文件，必要时拆批执行

package/comate-engine/assets/skills/code-review/references/output-schema.md

@@ -0,0 +1,197 @@
+# SubAgent 输出格式规范
+
+所有 Review SubAgent 必须按以下 JSON 格式输出审查结果，以便主控 Agent 进行合并和去重。
+
+## JSON Schema
+
+```json
+{
+  "reviewer": "reuse | style | correctness | reliability | custom",
+  "summary": "本维度的整体评估，1-2 句话",
+  "findings": [
+    {
+      "id": "R001",
+      "severity": "P0 | P1 | P2 | P3",
+      "category": "分类标识",
+      "file": "相对路径/文件名",
+      "line": 42,
+      "endLine": 50,
+      "title": "简短标题（10字以内）",
+      "description": "问题的详细描述，说明为什么这是个问题",
+      "suggestion": "具体的修复建议，包含代码示例（如适用）",
+      "evidence": "支撑判断的证据，如已有函数的路径、调用链分析等"
+    }
+  ]
+}
+```
+
+## 字段说明
+
+### 顶层字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `reviewer` | string | 是 | 审查维度标识：`reuse` / `style` / `correctness` / `reliability` / `custom` / `meta` |
+| `summary` | string | 是 | 本维度的整体评估摘要 |
+| `findings` | array | 是 | 发现的问题列表，无问题时为空数组 `[]` |
+
+### Finding 字段
+
+| 字段 | 类型 | 必填 | 长度限制 | 说明 |
+|------|------|------|----------|------|
+| `id` | string | 是 | - | 问题编号 |
+| `severity` | string | 是 | - | 严重等级：`P0` / `P1` / `P2` / `P3` |
+| `locked` | boolean | 否 | - | `true` 表示该 finding 来自 `[Critical]` 标记规则，Meta-Review **禁止**对其执行 `adjust_severity` 操作；缺省或 `false` 时 Meta-Review 可自由调整 |
+| `category` | string | 是 | - | 问题分类，见下方分类表 |
+| `file` | string | 是 | - | 问题所在文件的相对路径 |
+| `line` | number | 是 | - | 问题起始行号 |
+| `endLine` | number | 否 | - | 问题结束行号（跨多行时提供） |
+| `title` | string | 是 | ≤15字 | 简短标题，一目了然 |
+| `description` | string | 是 | 1-2句话 | 说明风险和触发条件，不展开论证 |
+| `suggestion` | string | 是 | 1-2句话 | 修复方向，只在关键处给代码片段 |
+| `evidence` | string | 否 | 1句话 | 支撑证据（已有函数路径、调用链等） |
+
+**长度要求**：SubAgent 输出的每个 finding 应尽量精简。`description` 和 `suggestion` 各控制在 1-2 句话以内，避免大段文字。主控 Agent 在最终报告中会进一步压缩为表格单行。
+
+### Category 分类表
+
+#### 复用审查 (reuse)
+| category | 含义 |
+|----------|------|
+| `duplicate-function` | 与已有函数功能重复 |
+| `inline-reimplementation` | 内联逻辑可用已有工具函数替代 |
+| `similar-pattern` | 存在近似实现，建议考虑复用 |
+
+#### 风格审查 (style)
+| category | 含义 |
+|----------|------|
+| `code-format` | 格式类规则（空格、缩进、行长、分号、引号等） |
+| `naming-convention` | 命名规范（类名、方法名、常量名、包名等） |
+| `code-style` | 代码结构风格（花括号要求、操作符换行、箭头函数括号等） |
+| `comment-style` | 注释规范（Docstring、Javadoc、注释空格等） |
+| `vue-style` | Vue 模板专属规范（属性命名、插值空格、模板根元素等） |
+| `react-style` | React/JSX 专属规范（JSX 缩进等） |
+
+#### 正确性审查 (correctness)
+| category | 含义 |
+|----------|------|
+| `null-safety` | 空值与类型安全（空指针、None 访问、空集合越界等） |
+| `type-error` | 类型不匹配运算（字符串+数字、不可哈希对象等） |
+| `data-structure` | 数据结构操作错误（迭代时修改、可变默认参数等） |
+| `exception-handling` | 异常处理错误（吞异常、finally return、资源泄漏等） |
+| `variable-param` | 变量/参数错误（未定义变量、参数数量不符、重复参数等） |
+| `string-format` | 格式化字符串错误（占位符数量不符、不支持的格式符等） |
+| `control-flow` | 控制流错误（break/continue 在循环外、return 在函数外等） |
+| `oop-error` | OOP 错误（实例化抽象类、MRO 冲突、方法缺少 self 等） |
+| `framework-bug` | 框架特定缺陷（Vue/React 生命周期、Hook 规则、双向数据流等） |
+
+#### 可靠性审查 (reliability)
+| category | 含义 |
+|----------|------|
+| `resource-leak` | 资源泄漏（文件/连接/锁未关闭释放） |
+| `concurrency-race` | 并发竞态（无锁共享变量、死锁、WaitGroup 误用等） |
+| `thread-safety` | 线程安全（非线程安全集合共享、SimpleDateFormat 等） |
+| `db-operation` | 数据库操作（N+1、大批量未分批、事务失效、免密/明文密码） |
+| `async-issue` | 异步问题（未 await、事件循环阻塞、Task GC 等） |
+| `auth-missing` | 鉴权缺失（对外接口无鉴权） |
+| `auth-bypass` | 越权访问（未校验资源归属、垂直越权） |
+| `auth-logic-error` | 鉴权逻辑错误（校验变量来源错误、宽松比较） |
+| `performance-issue` | 性能问题（线程池无界、ReDoS、循环字符串拼接等） |
+
+## 输出示例
+
+```json
+{
+  "reviewer": "correctness",
+  "summary": "发现 2 个正确性问题：一个空指针风险和一处异常被吞",
+  "findings": [
+    {
+      "id": "001",
+      "severity": "P0",
+      "category": "null-safety",
+      "file": "src/api/user.ts",
+      "line": 42,
+      "endLine": 48,
+      "title": "空指针访问",
+      "description": "data.user 可能为 null，直接访问 data.user.name 会在运行时崩溃",
+      "suggestion": "添加空值检查：if (data.user) { ... }",
+      "locked": true
+    },
+    {
+      "id": "002",
+      "severity": "P1",
+      "category": "exception-handling",
+      "file": "src/service/init.ts",
+      "line": 20,
+      "endLine": 23,
+      "title": "异常被吞",
+      "description": "catch 块中只有 console.log，异常未向上传播，调用方无法感知失败",
+      "suggestion": "catch 后重新抛出或返回错误状态"
+    }
+  ]
+}
+```
+
+## 合并规则
+
+主控 Agent 在收集到所有 SubAgent 的输出后，按以下规则合并：
+
+1. **去重**：`file` + `line`（±5行范围内）+ `category` 相同的视为重复，保留 description 最详细的
+2. **合并相近**：同一文件中多个同类问题（如多处硬编码字符串）合并为一条，在 description 中列出所有位置
+3. **重新编号**：合并后按 severity 排序，分配连续编号（1, 2, 3...）
+4. **统计汇总**：计算各等级的数量，生成总体评估
+
+---
+
+## Meta-Reviewer 输出格式
+
+Meta-Reviewer 的输出格式与审查 Agent 不同，它不直接产出 findings，而是对已有 findings 进行修正和补充。
+
+### JSON Schema
+
+```json
+{
+  "reviewer": "meta",
+  "summary": "Meta-Review 整体评估",
+  "actions": [
+    {
+      "action": "remove | adjust_severity | supplement | refine_suggestion",
+      "target_id": "E001",
+      "reason": "为什么要做这个调整",
+      "new_severity": "P2",
+      "new_suggestion": "更具体的建议"
+    }
+  ],
+  "missed_findings": [
+    {
+      "id": "001",
+      "severity": "P1",
+      "category": "分类标识",
+      "file": "相对路径/文件名",
+      "line": 42,
+      "title": "遗漏的问题",
+      "description": "描述",
+      "suggestion": "建议"
+    }
+  ]
+}
+```
+
+### Action 字段说明
+
+| action | 含义 | 必填字段 |
+|--------|------|---------|
+| `remove` | 移除误报 | `target_id`, `reason` |
+| `adjust_severity` | 调整严重等级 | `target_id`, `reason`, `new_severity` |
+| `refine_suggestion` | 细化修复建议 | `target_id`, `reason`, `new_suggestion` |
+| `supplement` | 补充已有 finding 的信息 | `target_id`, `reason` |
+
+### missed_findings
+
+遗漏的问题使用标准 finding 格式。这些条目在合并阶段会被追加到 findings 列表中。
+
+### 合并时应用 Meta-Review 的顺序
+
+1. 先应用 `actions`（remove → adjust_severity → refine_suggestion → supplement）
+2. 再追加 `missed_findings`
+3. 最后执行去重、合并、排序、编号