LobeHub deep-review 技能输出契约深解多 Agent 代码评审报告如何做到严谨、控噪与范围收敛【免费下载链接】lobehub LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehubLobeHub 仓库内置的deep-reviewAgent 技能通过维度并行评审 → 对抗式验证 → 全局去重 → 结构化报告的流水线产出代码评审结论而 report-template.md 正是 Deep 模式的输出契约它规定了每条 finding 如何定级、如何渲染、哪些必须本 PR 修复、哪些移交其他责任人以及 PR 模式下如何给出 Merge verdict。读完本文你将掌握该契约的完整渲染规则、决策表与报告骨架并能结合仓库中的验证提示词与 Zod 校验脚本理解报告字段从哪里来、为什么这么设计从而在自己的多 Agent 评审流程中复用这套范围控制与降噪机制。1. 模板的定位覆盖环境默认格式的硬性输出契约原文档开篇即声明了三条定位这是理解整份模板的前提它是 deep 模式的output contract覆盖任何环境默认的报告格式Claude Code / Codex 等各 harness 自带的 review 输出习惯一律让位必须渲染完整报告严禁把结果压缩成一条纯 finding 列表报告语言跟随会话语言——下面的结构是契约措辞可以翻译。这一设计与 SKILL.md 的两条入口模式相呼应Light 模式默认由单个独立评审者按各维度的 Quick checklist 检查不使用deep 报告模板直接用环境的普通 review 格式转述见 light-review-prompt.md 中的 Write an ordinary markdown review, not JSON and not a structured deep-review report只有显式触发的 Deep 模式/deep-review才走维度评审 Agent → 流水线验证 → 全局整合 → 结构化报告 → 交互式修复的完整编排并严格套用本文模板。因此这份模板本质上是 Deep 模式最后一公里的渲染规范上游各子 Agent 返回的是结构化 JSON主 Agent 负责把它折叠成下面的人读报告。2. 渲染规则全集Rendering rules模板第一条渲染规则就规定了筛选口径只渲染verdict: confirmed的 finding外加未验证维度见下文第 6 节。排序规则是severity p0 → p1 → p2同一 severity 桶内按SKILL.md中维度表的表序分组同一维度内保持评审者顺序。以下是模板Rendering rules章节的全部规则逐条继承并展开2.1 结构强制存在标题、头部元数据Scope/Background/Execution、TL;DR、Findings、Statistics永远渲染——即使零条 confirmed findingFindings 也要写明 no confirmed findingsStatistics 照常显示各项计数。空桶空 severity 桶则相反整个小节标题直接省略。2.2 两个问题决定 finding 的命运且两个都渲染这个改动是否引入了它对应nature/exposure字段它实际触发的概率有多高对应likelihood。模板强调severity 本身永远不决定某条 finding 是否阻塞合并——这是与多数红黄绿评审报告最大的区别。具体语义由下文 Scope 规则与降级规则共同实现。2.3 Nature 行与 Likelihood 行Nature 行nature: introduced是默认值省略该行nature: exposed_legacy则必须渲染**Nature**: legacy surfaced by this change并按exposure值附加(triggered by this diff)或(bystander find)。Likelihood 行在每条 confirmed finding 上强制渲染**Likelihood**: high | medium | low永不省略——它和 severity 一起告诉用户这条问题值不值得再来一轮修复。low时还必须把scenario中的前置条件链以括号附在后面。这两个字段的合法性在上游就有硬约束review-prompt.md 要求exposed_legacy必须携带exposure与scenariolowlikelihood 必须携带scenario且校验脚本会拒绝违反者见第 7 节。2.4 Scope 规则legacy 问题不在本 PR 修复nature: exposed_legacy的 finding永不渲染Fix options永不进入Safe to fix now统一渲染到Hand off to owner小节并附一份 Linear issue 草稿draft不自动创建唯一例外exposure: triggered的 P0——是这份 diff 让老 bug 开始可触发因此它按普通 finding 进入 severity 桶并且阻塞合并。模板给出的理由很直白其余 legacy 都是别人的任务把它们拉进本 PR 正是这条规则要防的 scope creep。 这个设计在 review-prompt.md 的 Review scope (hard rules) 中有对应上游约束评审者默认只报落在 diff行上的问题顺带撞见的无关老问题bystander除非是显而易见的 P0 生产 bug否则根本不报。2.5 低 likelihood 降级Low-likelihood de-escalationconfirmed 且likelihood: low且blocks_release: false的 finding按验证后的 severity 正常渲染但永不进入Merge verdict的前置条件改入Follow-ups。若用户声明这是对同一 PR 的第 N 轮复核第二轮起则所有low 非阻塞 finding 不论 severity 一律压缩为More P2下的一行并加前缀[low likelihood]。模板解释了动机修复轮次多了以后继续追杀罕见边界的边际价值低于其带来的 churn 与回归风险——要在 TL;DR 里明说降级了多少条而不是静默丢弃。2.6 其余字段渲染细则Issue type原样渲染 finding 的issue_type字段严禁用维度名顶替。Blocks release渲染 verify 子代理返回的blocks_releaseyes/no每条 confirmed finding 必带——这是用户的 ship/no-ship 信号同一根因合并same-root的条目取其中最高合并 severity 对应的值。Existing implementations行仅reuse-architecture去重类 finding 渲染且列出全部条目。Rule source行finding 带rule_source时渲染。Override 优先级先应用fix_options_override/severity_override/nature_override/exposure_override/likelihood_override再应用全局整合映射consolidation map。这些 override 字段来自验证阶段的返回值见 verify-prompt.md 的 Optional corrections 定义。2.7 Same-root 合并Same-root merge被全局整合 pass 映射到same_root_as: X的 finding折叠进 X 的条目不再单独立编号在 X 条目末尾追加**Same root**: id (location, issue_type), ...该条目 severity 升级为合并集合中的最高值Statistics 中合并条目只计一次。上游的合并标准定义在 consolidate-prompt.md两条 finding 共享根因当且仅当一个具体修复能同时解决两者仅位置相近、主题相似或同维度都不算。该 pass 只在验证后至少剩两条 confirmed finding 时运行一次且明确不重新验证正确性禁止自映射、禁止编造 id、禁止成环、禁止合并需要分别修复的问题。2.8 P2 上限噪声控制confirmed 的 P2 数量 6 时完整渲染前 6 条其余折叠为More P2下的一行**#n** [issue_type] summary (file:line)。挑选完整渲染的 6 条时lowlikelihood 的排最后。2.9 Hand off to owner 的渲染细节每个非 triggered-P0 的exposed_legacyfinding 都在这里渲染一条不创建 Linear issue只渲染草稿由用户决定是否提交——一次 deep review 可能挖出多条 legacy 项自动建 issue 既吵又会与已有 issue 重复Culprit肇事者直接取自 verify 的culprit字段原样渲染验证者当时已打开过文件culprit: null渲染为 attribution unclear 且不给建议 assignee渲染阶段禁止重跑git blame。2.10 Release checks未验证、不计入 findingrelease_checks数组仅 release-risk 维度产出渲染在Pre-deploy checklist下位于 severity 桶之外排除在所有 finding 统计之外。模板强调它们设计上就是未验证的——它们是关于生产状态的问题而非对代码的断言永不与 finding 合并也永不成为 merge verdict 的前置条件其中blocks_deploy: true的条目排最前并在 verdict 的Basis行中作为部署时条件点出而非代码阻塞项。这一双输出形态的源头在 release-risk.md 维度文件代码或 diff 本身能证明回滚风险时发issuesfinding而安全部署依赖仓库无法回答的生产/外部状态现有行数据形状、线上配置、队列存量时发release_checks。2.11 未验证维度、缺失规则源与 Workflow 反馈Unverified dimensionsworkflow维度的 finding 渲染到Processskill-freshness的渲染到Skill updates——均在 severity 桶外、不计入 P0/P1/P2 统计。它们使用与其他 finding 相同的 JSON schema但每条只渲染一行fact summaryevidence location有scenario时附上suggested action 第一条fix_options其severity仅为参考性永不渲染。这与 SKILL.md 维度表中Verified? no的语义一致客观状态检查/建议项跳过 verify pass 直达报告。Missing sources任一评审者返回missing_sources时在报告末尾追加提示建议修复/恢复所列规则文件。Workflow feedback跨子代理合并等价建议、累积来源如sources: code-style, verify渲染在报告末尾为空则整节省略。2.12 PR 模式的触发条件当用户提供 GitHub PR URL 或无歧义的 PR 引用PR #123、pr 123、pull request 123时渲染Merge verdict裸#123仍属歧义不触发 PR 模式。3. Merge verdict 决策表PR 模式主 Agent 亲填永不委托模板给出了first match wins的决策表必须按顺序命中即止条件判定isDraft: truedo not merge yetmergeable: CONFLICTINGdo not merge yet任一 checkconclusion: FAILUREdo not merge yetin-scope P0 confirmed 0fix before mergein-scope P1 confirmed 0fix before merge其余仅 P2 / 全部 out-of-scope / 干净good to mergeIn-scope 的精确定义nature: introduced或者nature: exposed_legacy且exposure: triggered且 severity 为 P0。其余一切——任意 severity 的 bystander legacy、P0 以下的 triggered legacy——都是本 PR 的 out-of-scope永不成为前置条件一律进Hand off to owner。模板的理由我们的 diff 应当按它改变了什么来评判。一个我们只是路过撞见的老 bug不该因为我们恰好评审了附近代码就变成我们的义务——把路过问题当义务正是专注 PR 膨胀成一周五个无关修复的方式。追加降级in-scope 但likelihood: low且blocks_release: false的 finding 同样不计入 P0/P1 前置条件列入Follow-ups。回退规则Fallbacksmergeable: UNKNOWN→ 按可合并处理所有 check 都在 in progress/queued → CI pending不阻塞未配置任何 check → 视为 CI passfix before merge 列出 in-scope 未降级的 P0/P1 编号 一行摘要作为前置条件good to merge 列出 P2 与降级 finding 作为 follow-ups若判定为 good to merge 但Hand off to owner非空必须用一句话点明可以合并且留下了 N 项给其他 owner。4. 发送前自检清单Pre-send self-check模板要求发送前逐项确认缺任何一项都必须修正后重新渲染标题 头部元数据scope / background / 含裁剪维度及理由的执行模式齐全TL;DR 存在Findings 存在或显式 no confirmed findingsStatistics 存在每条渲染在 severity 桶中的 confirmed finding都带issue type、location、blocks release、likelihood、core problem、evidence、fix cost、fix options、needs test。Hand off to owner下的条目按下一条检查——Scope 规则禁止它们出现 fix options若这里强制要求两条规则将互相不可满足。每条exposed_legacyfinding 要么是以 triggered-P0 身份出现在 severity 桶中要么是Hand off to owner下的一条——两者居其一永不同时永不就地修复永不进Safe to fix nowrelease_checks以 checklist 形式渲染在Pre-deploy checklist下永不计入 finding永不作为合并前置无 out-of-scope 或 low-likelihood-non-blocking finding 出现在Merge verdict前置条件中Merge verdict 仅在 PR 模式出现。5. 报告模板骨架完整契约结构以下骨架来自 report-template.md 的模板主体占位符与省略条件均按原文保留# Deep Review Report **Scope**: {如 feat/user-batch-delete vs 本地 main8 files 240/-37含子模块 lobehub} **Background**: {第 0 步 scope 摘要的核心 1-2 句} **Execution**: {N} 个维度评审者{列表} {M} 个验证者{ 运行了全局整合时注明}; pruned: {维度 — 一行理由或 none} ## TL;DR {1-2 句X 条 confirmedP0 a / P1 b / P2 c其中 Y 条必须本 PR 修复、Z 条移交其他 owner最大单一风险一个建议的下一步动作。重复评审轮次要说明降级了几条 low-likelihood finding 而非再翻案。} 只保留与本改动相关的 finding。两个标签驱动分诊**Nature** 说明该问题是被本次改动引入、还是只是路过旧代码**Likelihood** 说明该场景实际触发的频率。既存问题列在 Hand off to owner 而不是在这里修复——这是刻意的范围控制不是疏漏。 报告末尾有 {N} 条 workflow feedback ← 仅当 workflow_feedback 非空 ## Merge verdict ← 仅 PR 模式 **Verdict**: {good to merge | fix before merge | do not merge yet} **Basis**: in-scope P0 {x} / P1 {y} / P2 {z} confirmed | CI {pass|fail|pending} | draft {yes|no} | mergeable {ok|conflicting} | out-of-scope 移交 {h} | pre-deploy checks {c}{d} 阻塞部署 **Prerequisites**: #{n} {summary} ← 仅 fix before merge只含 in-scope、未降级 finding **Follow-ups**: #{n} {summary} ← P2 降级的 low-likelihood finding --- ## Findings ### P0 ({n}) #### 1. {summary} - **Issue type**: {issue_type} - **Location**: src/api/user.ts:87 - **Blocks release**: yes - **Likelihood**: {high | medium | low}{ — low 时附前置条件链} - **Nature**: legacy surfaced by this change (triggered by this diff) ← 仅 exposed_legacy - **Existing implementations**: src/foo.ts:62-138, ... ← 仅 reuse 去重 - **Rule source**: {rule_source} ← 存在时 - **Core problem**: {core_problem} - **Scenario**: {scenario} - **Evidence**: {verify 证据} - **Fix cost**: low - **Fix options**: - Option A: ... - Option B: ... - **Needs test**: yes - **Same root**: {id} ({location}, {issue_type}) ← 仅合并条目 ### P1 ({n}) ... ### P2 ({n}) ... **More P2** ← 仅当 P2 6或重复评审轮次中降级的 low-likelihood finding - **#{n}** [{issue_type}] {summary} ({file:line}) - **#{n}** [low likelihood] [{issue_type}] {summary} ({file:line}) ← 重复评审降级 --- ## Hand off to owner ({n}) ← 不在本 PR 修复的 exposed_legacy finding为空则省略 既存问题非本次改动引入。此处刻意不修——修了就会扩大本 PR 范围。确认后我会提交 issue。 - **#{n}** [{severity}] [{likelihood}] {summary} - **Location**: file:line - **Culprit**: {commit} ({author}, {date}) ← verify 的 culprit为 null 时写 attribution unclear - **Nature**: {triggered by this diff, but below P0 | bystander find} - **Issue draft**: {title} — {一行描述 影响} - **Suggested assignee**: {author} ← 归属不明时省略 --- ## ✅ Pre-deploy checklist ({n}) ← release_checks为空则省略 不是缺陷——是本次改动依赖、但无法从代码确认的事项。部署前请核查。 - [ ] **{item}** ← blocks_deploy: true 的排最前并标 ⚠️ {why} --- ## Process ← workflow 维度 finding为空则省略 - {summary} — {location}{有 scenario 时附上}; suggested: {fix_options[0]} ## Skill updates ← skill-freshness finding为空则省略 - {location: 过时的 skill file:line 或新提议的 skill} — {summary}; suggested: {fix_options[0]} ## Statistics - Confirmed: {n}{k} 条 legacy-surfaced| False positives: {fp}含 {os} 条 over-scrutiny| Need more context: {nc} - Must-fix this round: {in-scope p0p1} | Blocks release: {n} | Handed off: {h} | Deferred as low-likelihood: {l} - Likelihood: high {a} / medium {b} / low {c} - By dimension: {dimension: count, ...} ## Safe to fix now ({n}) ← 为空则省略 单一显而易见修复、低风险、无需产品决策可一次性批量应用。仅限本次改动引入的 finding——legacy 代码永不在此自动修复。 - **#{n}** [{issue_type}] {summary} (file:line) ## Needs your input ← 仅 need_more_context为空则省略 - [ ] {summary} — missing: {missing} ## Workflow feedback ({n}) ← 为空则省略 本次运行中各子代理对评审流程本身的观察。不是行动项——用于决定是否更新 skill 文件。 - **Suggestion**: {suggestion} **Why**: {why} **Sources**: {code-style, verify}几个骨架细节值得注意Statistics 行中的 Must-fix this round 只统计in-scope 的 p0p1False positives 单独标出其中over-scrutiny校准过度审查的占比——这与 SKILL 的核心原则按代码库既有水平校准而非理想化标准形成闭环Safe to fix now只收can_auto_fix语义下的本次改动引入问题与 verify-prompt.md 中can_auto_fix: true的四条件fix_cost low、唯一显而易见修复、无需外部资源或产品决策、改动少于三个文件且不触及架构层/DB schema/外部契约/用户可见行为/路由/热键/文案/权限边界严格对应且明确release-risk与exposed_legacy永不自动修复。6. 源码印证报告字段如何从子代理 JSON 一路抵达渲染模板里的每个字段都不是凭空规定上游三段式流水线review → verify → consolidate与一个 Zod 校验脚本共同保证了渲染规则可执行。第一段评审输出 schema。review-prompt.md 规定每个评审子代理返回单个 JSON 对象每条 issue 必带id、dimension、issue_type、nature、severity、likelihood、location、summary、core_problem、fix_cost、至少一条fix_options、need_test条件字段为exposed_legacy时的exposure/scenario、low likelihood 的scenario、reuse-architecture 的existing_implementations。第二段对抗式验证。验证与评审永不共用同一 Agent防自批原则。verify-prompt.md 要求验证者对每条 finding打开位置读足上下文 → 追调用方/类型/校验/测试 →先找反例上游保证、提前返回、框架行为→ 校验nature/exposure/likelihood/severity用*_override字段纠正评审者的误标bystander 老问题除非是显而易见的 P0 生产 bug否则判false_positive且 reason 以out-of-scope legacy:开头校准过度普遍存在且未被加剧、或用永久代码标准衡量声明过期的临时代码判false_positive且 reason 以over-scrutiny:开头——这正是 Statistics 行中 over-scrutiny 计数的前缀约定来源。三分判决confirmed / false_positive / need_more_context取代了置信度百分比听起来校准过的分数不可靠blocks_release的判定标准P0 必须阻塞、P2 不得阻塞、low likelihood 除非灾难性且不可逆否则不阻塞则直接喂给模板的**Blocks release**行与 Merge verdict 的Basis行。第三段全局去重。consolidate-prompt.md 返回{same_root:[{id:style-2,same_root_as:ai-1}]}形式的映射只返回更晚出现的重复 id并以输入顺序中最早的一条为根。模板中 no separate number / severity 升级 / 统计只计一次 三条渲染规则正是该映射的消费方式。契约的机器可执行性。validate-output.ts 用 Zod 把三类输出固化成 schema 并做成 CLIvalidate-output.ts review|verify|consolidate [input-file]也支持 stdin。值得对照模板阅读的约束validate-output.ts#L12-L60severity仅允许p0/p1/p2——模板的三级桶因此不可能出现第四级exposed_legacy必须带exposure与scenariointroduced必须省略exposure——模板的 Nature 行渲染逻辑因此总能取到所需字段likelihood: low必须带scenario——模板low 时附前置条件链因此总能渲染reuse-architecture必须带existing_implementations——模板的 Existing implementations 行因此只在该维度出现时有意义verify 侧非 auto-fix 的 confirmed 必须给auto_fix_reasonsame_root映射的 id 不可重复validate-output.ts#L144-L161。validate-output.test.ts 中的测试用例如 requires exposed legacy findings to explain their exposure、rejects severity levels outside the review contract逐条验证了上述约束extractJsonPayload则保证子代理回复中的 JSON 围栏可被稳定抽取拒绝未闭合围栏、拒绝多个围栏。未验证维度的 schema 复用。workflow与skill-freshness的 finding 使用同一 schema但模板只取summary/location/fix_options[0]渲染单行、忽略 severity——这解释了为什么 SKILL 维度表中这两个维度标记为Verified? no它们是客观状态或建议项跳过验证直通报告同时被排除在 P0/P1/P2 统计之外。7. 适用前提与限制本文所有规则以当前仓库 deep-review 技能 的实际内容为准模板语言随会话语言翻译但结构小节名、字段行、决策表是契约不可裁剪。Deep 模式受逻辑需求预算约束同一需求/PR/分支默认最多跑一次 Deep后续复核走 Light 模式——模板中 重复评审轮次 的降级渲染因此只会在用户显式再触发 Deep 的场合出现。Merge verdict 仅在用户提供 PR URL 或无歧义 PR 引用时渲染本地 diff 评审无 PR 上下文不会产出该小节。渲染阶段不重跑git blame、不创建 issue、不重新验证——这些动作要么前置到 verify 阶段culprit 归因要么留给用户决策Linear issue 草稿。小结这份报告模板把多 Agent 评审中最容易失控的三件事——范围蔓延legacy 移交而非就地修、噪声P2 上限 low-likelihood 降级 same-root 合并、责任归属culprit 归因 移交草稿——全部编码成了可自检、可机器校验的渲染契约。对照 SKILL.md 的防幻觉、防自批、规则优于模型、按代码库校准、速度即特性五条核心原则可以看出模板中的每一条规则都服务于其中一个这是把工程纪律写进输出格式的典型样本。【免费下载链接】lobehub LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考