企业官网建设流程全解析

Qwen Code /review 技能架构设计：14 个并行 Agent、分片验证与迭代反向审计如何支撑一次代码评审

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code

Qwen Code 是一个运行在终端里的开源 AI 编码代理，其内置的/review技能负责评审代码变更、PR 或指定文件。本文基于该技能随仓库发布的架构设计文档 DESIGN.md，完整还原它为什么选择「14 个并行 Agent + 分片验证 + 迭代反向审计」而非单 Agent，讲解拓扑选择、轮次上限、确定性子命令层与 effort 分级等核心机制，并结合仓库源码给出每条设计决策背后的实测证据。读完后你能掌握：一条多 Agent 评审管线的完整架构、其成本预算的构成方式，以及「判断留在 prompt、记账移进可测试子命令」这一设计哲学在真实项目中的落地形态。

1. 设计文档是什么：决策记录，不是运行时输入

/review技能由三份文件组成：SKILL.md（约 1190 行，编排器每次运行都会加载的运行时指令）、DESIGN.md（约 1240 行，面向维护者的架构决策记录）以及references/下的条件加载文档（posting.md、persistence.md、aone.md）。SKILL.md 中有明确约定：DESIGN.md 是维护者文档，不是运行时输入——评审过程中禁止read_file读取它；SKILL.md 里的规则以(measured; DESIGN.md — <title>)指针引用其中的实测事故叙述，供人类审计规则来源。

这份 DESIGN.md 的结构本身就说明了它的定位：几乎每个 H2 小节都是「Considered（备选方案）→ Decision（决策）→ 实测依据」的论证格式，从 Agent 数量选型、验证分片策略，到 worktree 隔离、CI 降级规则、甚至工具声明的 token 成本，每一条规则都能追溯到一次真实事故或一组测量数据。

2. 为什么是 14 个并行 Agent：一次逐步演进的设计史

DESIGN.md 开篇即回答了最核心的架构问题：为什么不用 1 个 Agent，而是 14 个？文档记录了完整的演进路径：

• 1 Agent（Copilot 方案）：单次 LLM 调用，成本最低，但维度覆盖完全依赖单条 prompt 的注意力——盯着安全看时容易漏掉性能问题；
• 5 并行 Agent（最初设计）：每个 Agent 负责一个维度，通过强制视角多样性提升覆盖，但 Correctness+Security 合并、且只有一轮无方向扫描，召回天花板把不少问题留到了用户后续多轮/review才被发现；
• 9 并行 Agent：6 个评审维度（Correctness、Security、Code Quality、Performance、Test Coverage、Undirected）+ Build & Test，其中无方向扫描拆成 3 个人格并行；
• 10 并行 Agent：加入 Issue Fidelity & Root-Cause Ownership，在采信客户端修复前先比对关联 issue 的证据与 PR 声称的修复；
• 12 并行 Agent：Correctness 拆成三个程序化遍历——1a 逐行扫描（含其外层函数）、1b 删除行为审计、1c 跨文件追踪器——外加最多 2 个 diff 领域专家查找器（Agent 8）；
• 14 并行 Agent（当前设计）：Code Quality 按同一份证据清单再切成三份——3a 复用与重复、3b 抽象高度与契合度、3c 一致性与清晰度。依据是 PR #6457 上的实测：一个 Agent 拿八项清单只找到 5 个缺陷中的 1 个；同一模型拆成三路则 5 个全中。

DESIGN.md 中 PR #6457 的QQChannel.ts（1551 → 2643 行、65% 重写）上有一张更完整的对照表：

关键结论是：chunk Agent 看得见这些缺陷（代码就在它的地盘里）却一个都没报——「缺的不是行，是问题」。「审查这个 diff 找 bug」和「列出每个重试计数器，再检查每个调用点的递增」不是同一条指令，只有后者能发现不可达的上限。

决策成立的理由（14x vs 1x 的边际成本可接受）：

1. 14 个 Agent 在同一条响应里一次性提交，按运行时工具调用并发上限并行（默认 10，可用QWEN_CODE_MAX_TOOL_CONCURRENCY调整），墙钟时间最坏约两波，仍远低于 14 个串行；
2. 维度聚焦带来更高召回（漏报更少）；
3. 三个无方向人格（attacker / 3am-oncall / maintainer）能抓住跨维度问题，打破单条 prompt 诱导的偏置——实测中集成度超过 3–5 个采样路径后多样性急剧下降，3 是甜蜜点；
4. Issue Fidelity 挡住一类常见的「假批准」：PR 可能内部测试完善，却只解决了作者的错误诊断，而非关联 issue 的原始故障；
5. 「沉默比噪音好」原则 + 验证环节控制精度。

几个维度的拆分理由同样值得注意：Correctness 与 Security 拆分，是因为单一 Agent 两维分心时实测一个维度会主导输出、另一个流于表面，且两者心智模式不同（correctness 问「它做它想做的了吗」，security 问「敌对者能让它做什么它没想做的事」）；Test Coverage 单列，是因为「这个 diff 有哪些场景没测试」是系统性的盲区，专注新代码 bug 的 Agent 几乎不会主动去看。

Issue Fidelity Agent 还有一个刻意的工程分工：issue 的发现、抓取与渲染放在已测试的子命令qwen review issue-context里（它会解析 GitHub 的关闭 issue 元数据，抓取每个 issue 的标题、正文与完整评论线程，且来自 issue 自己所在的仓库——因为 PR 可以关闭另一个仓库的 issue），而相关性判断（哪些引用是目标 issue、哪些只是背景事件）留在 Agent 里，判断永远不写进 TypeScript。该 Agent 只跑 PR 目标——本地 diff 或文件路径评审没有 PR 和关联 issue，此时是 13 个 Agent 而非 14 个。它还执行根因归属门禁：针对上游畸形输出的客户端侧 parser/sanitizer 绕行，除非维护者明确要求这种防御性缓解，否则不能算根因修复。

3. 拓扑决策：3A 维度扇出 vs 3B 领地扇出，为什么按源码行数而非 diff 行数

DESIGN.md 用整整两节解释拓扑门控，实现落在 budget.ts：

// packages/cli/src/commands/review/lib/budget.ts const FAN_OUT_SRC_FLOOR = 500; const FAN_OUT_TOTAL_FLOOR = 3200; export function isTerritoryFanOut(plan: DiffSize): boolean { const src = Number(plan?.srcDiffLines ?? 0); const total = Number(plan?.diffLines ?? 0); return !(src <= FAN_OUT_SRC_FLOOR && total <= FAN_OUT_TOTAL_FLOOR); }

即srcDiffLines ≤ 500 且 diffLines ≤ 3200走Step 3A 维度扇出（14 个维度 Agent 各自读完整 diff），否则走Step 3B 领地扇出（每 400 行一个 chunk Agent，各读各的地盘）。门控为什么数源码行而不是 diff 行？DESIGN.md 给出的数据是：该仓库最近 40 个已合并 PR 的中位数 diff41% 是测试代码，40 个里有 14 个超过一半是测试。若按原始 diff 行数门控，一个 173 行生产代码 + 489 行新测试的变更会被送进领地扇出，生产代码反而只被一个 chunk Agent 负责；而在维度扇出下它会被 12 个读 diff 的维度透镜读到。第二个子句diffLines > 3200是注意力上限：超过该值后让 13 个维度 Agent 各自吞下整个 diff 会稀释所有透镜。实测中重新门控把 40 个样本里的 6 个 PR 从 3B 挪回 3A，总成本约增加 5%–10%，换来这 6 个 PR 的生产代码从 1 个读者变成 12 个透镜。

docs/**与根级 markdown 归类为docs，不计入srcDiffLines（翻译类 PR 没有运行时风险）；但源码树里的 markdown 仍算 source——本仓库捆绑的技能 prompt 就是packages/core/src/skills/**/SKILL.md，那是可执行行为。

4. 成本预算：LLM 调用次数怎么算

DESIGN.md 的「LLM call budget」一节给出了完整的成本模型。小 diff（3A，high effort）约17–28 次调用（典型 17–19）：

大 diff（3B）为ceil(diffLines / 400)个 chunk Agent + 5–7 个全 diff Agent +3H个不变量 Agent（H = 重写严重的文件数）+ceil(F/8)验证 +rounds × chunks反向审计。反向审计占大头：PR #6457（5801 行、19 chunks、1 个 heavy 文件）首波约 27–29 次，反向审计19 × (2..5) = 38–95个，总计约 66–126 次。文档强调：与 Copilot（1 次）、Gemini（2 次）、Claude /ultrareview（云端 5–20 次）相比，本设计偏向高召回——前提是「每漏一个 issue 都会迫使用户再来一轮/review」，所以每轮多找问题比压低单次成本更值钱。

反向审计的轮次上限是按拓扑取值的，实现在 budget.ts：

export const SMALL_REVERSE_AUDIT_ROUNDS = 10; // 3A：一轮 = 1 个审计者 export const LARGE_REVERSE_AUDIT_ROUNDS = 5; // 3B：一轮 = 每个未退役 chunk 一个审计者 export const HUGE_REVERSE_AUDIT_ROUNDS = 3; // 巨大 diff 且运行带 deadline 时

三个数字背后的论证链是 DESIGN.md 的精华之一：

• 为什么停点是「两轮连续空轮」而不是一轮：PR #6457 八轮评审的每轮 Critical 产出是2, 2, 7, 0, 0, 5, 3, 1——评审两次返回「无阻塞」，下一轮又浮出 5 个 Critical，其中 3 个在从第一个 commit 就存在的代码里。「零产出只说明那一轮的 Agent 怎么样，不说明代码怎么样」。
• 为什么上限按拓扑：一个 round 在 3A 上是一个 Agent，在巨大 diff 上是约 90 分钟——相差两个数量级，单一数字必然在某端出错。
• 为什么 huge 缩减需要时钟：3 比下面一层更低，读作「巨大 diff 更不值得审计」是反的——它缺陷更多、地盘更大、收敛更晚。这是关于「墙」的论断：4000 行 PR 上五轮审计是 450 分钟，六小时 CI 天花板装不下；实测一个窗口内 26 个评审任务超时、约 122 小时算力、零发布。「有上报的 3 轮胜过丢失的 5 轮」。因此缩减只对带QWEN_REVIEW_DEADLINE_EPOCH的运行生效：有时钟取 3，无时钟的巨大 diff 按普通 3B 取 5。
• 算子只能降不能升：review.reverseAuditRounds设置项只能下调各层的轮次上限（cappedRoundTier拒绝operatorCap >= tier），因为一个算子选定的数字正是分层机制移除的东西——设 8 对小 diff 是合理话，对大 diff 是危险话。

5. diff 是文件，不是命令：截断陷阱与 chunk 平面剖分

这是 DESIGN.md 中证据密度最高的章节之一。旧做法是告诉 Agent 运行git diff main...HEAD。实测（PR #6457 的 211 000 字符 diff）：

写文件是必要但不充分：read_file单次仍受 25 000 字符上限约束并截断分页。真正的解法是chunk 计划：qwen review fetch-pr把 diff 写入.qwen/tmp/qwen-review-pr-<n>-diff.txt并产出分块计划，chunk 同时受行数预算（注意力）与字符预算（MAX_CHUNK_CHARS= 20 000，低于 25 000 读上限，保证 chunk 不会被读短）约束，且精确平铺整个 diff（chunksCoverDiff断言无间隙无重叠）——正是精确平铺让 Step 3B 的「覆盖收据」可检查：没有收据的 chunk = 没人审过的领地。chunk 边界尽量落在 hunk 边界上；超过目标的 hunk 只在「空行前面的列 0 源码行」（顶层声明处）拆分，找不到这样的边界则整块保留并标记oversized。

本地 diff 与跨仓库轻量模式同样需要 chunk 计划，因此存在qwen review plan-diff <diff-file>子命令：读入捕获好的 diff，产出与fetch-pr相同的chunks[]、files[]与拓扑计数，四条评审路径共享一条代码路径。它无法判定heavy（需要读变更后的文件树），所以裸 diff 有 chunk Agent 但没有不变量 Agent。

6. 验证与反向审计：分片、空轮与收据

分片验证：原始设计是「一个 finding 一个验证 Agent」，成本随 finding 数线性增长（15 个 finding = 15 次调用）；后来改为单 Agent 批量验证，又在大 PR 上出现 30–60 个 finding 时单上下文尾部质量劣化。最终选择分片：ceil(F/8)个验证 Agent 一起启动（VERIFY_SHARD = 8也是 budget.ts 中的单一出处）。拒绝 Critical 必须给出引用级反证——验证者只能引用具体代码来反驳该 claim，否则一律降级为 low confidence，绝不删除。不对称性是设计根基：误报（噪音）和误删真阳性（放一个 bug 出厂 + 再一轮/review）代价不同，所以拒绝的门槛是引用证据而非判断。

反向审计是独立步骤且迭代进行：验证是定向的（在特定位置检查特定 claim），反向审计是无边界的（重读整个 diff 找遗漏），合并进同一个 Agent 会让两者互相劣化。每轮收到之前所有轮的累计 finding 清单，聚焦「还没发现的」。反向审计在 3B 下按 chunk 扇出——每轮每个 chunk 一个审计者，各自持完整累计清单但只重读自己的地盘；在 5800 行 diff 上，把整个 diff 加一份不断变长的清单交给一个 Agent，恰是全管线里上下文最饥饿的 Agent。反向审计的发现不再跳过验证：过去「审计者已有完整上下文，输出天然高置信」的前提在 diff 大时恰好为假——思考空间最少的 Agent 其输出反而没人查。

低置信而非拒绝：不确定时的旧行为是直接拒绝（偏向精度），但实测不确定的 finding 经人工检查后常为真。现行行为是「confirmed (low confidence)」：出现在终端的 "Needs Human Review" 下、被过滤出 PR 行内评论（保住 PR 侧「沉默比噪音好」）、不影响 verdict。彻底的拒绝只保留给：与代码事实不符、命中排除准则（既有问题、格式吹毛求疵等）、无具体代码引用的模糊怀疑。

整 diff Agent 的实质返回检查：Step 3B 的覆盖收据只覆盖 chunk Agent；整 diff Agent（Issue Fidelity、1b、1c、不变量 Agent、测试矩阵、Agent 8）拥有的是「关切」而非「领地」，没有收据。Dogfooding 中一个不变量 Agent 11 秒返回约 370 token（其兄弟 Agent 跑了几分钟几千 token），它负责的清单半区恰好持有本轮最严重的发现，而它的沉默被编排器折叠成「该维度无问题」。对策是不引入新机器：Step 4 之前检查每个无收据 Agent 的返回是否描述了它走过的路（枚举的字段/调用点/行），「点名什么都没查过的返回无论多长都是没返回」；当有疑问就重跑——误重跑花一次调用，漏掉 whiff 花一个出厂 bug。

7. 确定性子命令层：判断留在 prompt，记账移进 TypeScript

DESIGN.md 反复出现的结论是：技能里写成散文的确定性逻辑一再带着 bug 出厂，而判断形状的东西（什么算 Critical、验证、放行授权语义、评审角度）应该留在 prompt。于是确定性逻辑全部沉淀为qwen review的 TypeScript 子命令，位于 packages/cli/src/commands/review/。从源码目录可见完整的命令面（每个命令基本都带同名测试文件）：

• parse-args：拥有参数语法。raw 字符串走stdin传递（--stdin），从不做位置参数——以 flag 开头的 raw 字符串（/review --effort low）会被 CLI 自己的严格解析器先行吃掉，位置参数还会被引号和 shell 元字符破坏。纯函数测试看不到这类 bug（文档化调用方式只在对着构建好的二进制运行时才失败），所以测试套件在表驱动测试外还包含 yargs 层接线测试。
• compose-review：拥有事件选择与正文合成——C/S 计数表（计 body Critical 与被丢弃的 Suggestion）、事件上限（cannot-tell 的既有 Critical、不可覆盖 chunk、未评审维度、上下文不可用）、降级豁免条款与子句合成。输入在边界处校验：模型写的 JSON 缺字段时缺省计数归零、畸形值抛类型化错误——此前一个被省略的计数意味着undefined + 1 = NaN，会击穿所有事件比较、在只有 body blocker 的情况下返回 APPROVE。422 恢复不再手工重推：它就是同一次调用加更新后的--comments文件（行内计数从草稿评论数出来，永不手输）。
• pr-context：终结「用散文描述抓取程序」的链条——review 正文与所有带 blocker 的正文完整渲染，带 blocker 的线程被隔离进 "Blockers to re-check" 小节（一条回复本身不能退役一个 blocker）；gh包装器的maxBuffer提到 64 MiB，堵住了在评论繁重的 PR 上杀掉两个子命令的 ENOBUFS。
• presubmit <pr> <sha> <owner/repo> <out>：一次发出包含isSelfPr、ciStatus、existingComments（5 个桶）、downgradeApprove、downgradeRequestChanges、downgradeReasons、blockOnExistingComments的 JSON 报告。SKILL.md 只描述 schema 与如何应用。
• cleanup <target>：移除 worktree、分支引用与每目标临时文件，幂等。
• comment-status：故意对同一 endpoint 做第二次分页抓取——pr-context是纯 GitHub API（要在无 worktree 的跨仓库轻量模式里跑），而comment-status存在的原因就是把 API 的锚定事实与 worktree 的 git 历史（changedSinceComment、touchedBy）做连接。分类谓词（carriesBlockerSignal、findRootId）从pr-context导入而非拷贝，两个面不可能在分类上不一致。它替代的是在一个真实 72 评论 PR 上实测的 20+ 次单评论抓取（每次是一个完整模型轮次）。
• 其余执行类命令：test-efficacy、revert-hunk、test-delta、base-tree、scratch-tree、extract-step、ab-drive、drive、dedup-candidates、script-lint、test-plan、check-coverage、agent-prompt、recover-findings等，各自对应 DESIGN.md 中一节「为什么它是子命令」的论证。

选择子命令而非.mjs脚本的理由：.mjs需要改打包器（copy_files.js只捆绑.md/.json/.sb）且脚本孤立于qwen的 CLI 表面之外；yargs 子命令走同一tsc构建管线；LLM 调用qwen review presubmit …与任何 shell 命令无异，不需要{SKILL_DIR}模板或npx间接层；跨平台路径处理（os.tmpdir与/tmp的分歧曾在清理逻辑里爆过）落在带类型的 TypeScript 模块里。代价是逻辑变更需随 CLI 一起重发——但在同一 monorepo 里 SKILL.md 与子命令一起版本化，这反而是收益：单次发布内二者不可能漂移。

Step 7 开头的硬性放行门禁

发布是唯一不可逆、公开、向外的动作。Dogfooding 实测：4 个并发且无--comment的评审里，3 个正确 withheld，1 个自行提交了一个 COMMENT review——「四次里一次违规是模型遵从失败，不是逻辑错误：规则是对的，它的效力不对」。修复是把门禁提到 Step 7 的第一条，并把它重构为算术而非判断：仅当 Step 1 解析出--comment或用户本会话明确要求发布时才允许写reviewsAPI，与 verdict 或终端上印出的 "Tip: post comments" 文本无关。这镜像了event/body不变量的同一对策——「停止推理，改为计数」。

既有 Qwen 评论的分类而非一律询问

原行为：PR 上存在任何 Qwen Code 评审评论就要求用户确认。实测发现真实场景中既有评论多落在三种「无真实冲突」情形：commit 已过时（stale by commit）、已被回复解决（resolved by reply）、锚点不重叠（no anchor overlap）。新行为按优先级分类：Stale by commit > Resolved by reply > Overlap（与新 finding 同path + line）> No conflict，首个匹配胜出，只有 Overlap 阻断，其余记入终端日志并继续。选基于行的分类是因为它确定、便宜，且精准命中真正的 UX 失败（同一行的视觉重复）；语义重叠检测需要额外一次 LLM 调用去处理实践中罕见的边缘情况。代价也写明：不共行的概念性重叠（559 行与 1352 行的缓存生命周期讨论）会被判 No conflict——行级启发式无法检测「同根因、不同锚点」。

CI 非绿时降级 APPROVE，以及「skipped 看起来像 passed」

LLM 评审管线静态读 diff 与周边代码，不跑测试、看不到运行时故障——CI 看得到。红 CI 且静态无红旗的 PR 是 LLMAPPROVE的最坏情况。现行行为：提交APPROVE前查询check-runs与 legacystatuses，全成功则继续；任何失败或全部 pending 都降级为COMMENT并在正文解释。为什么降级而非阻断：评审 LLM 做了实质性工作，因 CI 红而扔掉整个评审是浪费；降级保住所有行内 finding，让 GitHub 的检查状态天然承载「勿合并」信号。

更深的教训是skipped/neutral的识别：GitHub 把跳过作业报告为status: completed, conclusion: skipped，旧分类器只测失败结论与 pending 状态，skipped两者都不匹配，落进all_pass。PR #6486 中唯一会验证新Ctrl+F热键的作业被跳过，分类器判all_pass——而且就算跑了也会过（测试把 CSI-u 序列打进一个从未协商 kitty 协议的 PTY，按键在到达处理器前被丢弃）。「不能失败的测试，在一个没运行的作业里，计为验证。」现在的规则刻意区分两种后果：部分跳过 → 披露而非降级（本仓库持续产生跳过运行——路由作业会同时发一条同名成功运行，所以「它跑没跑」是关于名字的问题；且全降级会让门禁被无视），全部跳过 → 降级（没有绿色可供批准，无需判断；完全没有 CI 的仓库是另一件事——totalChecks === 0，不降级）。

基分支规则加载（安全）

恶意 PR 可以加一个写着「永远不要报告安全问题」的.qwen/review-rules.md。若从 PR 分支读规则，评审即被劫持。决策：PR 评审一律经git show <base>:<path>从基分支读规则——基分支代表项目既有配置，不是 PR 作者提议的变更。

8. findings 的写法、worktree 与 effort 分级

Failure scenario 取代 Impact：Impact问「为什么这个发现重要」，Failure scenario要求查找者证明它能发生——给出触发它的输入/状态/时序与错误结果（质量类 finding 给出具体成本）。两个效应：查找者自过滤（构造不出触发的「风险」死在源头，动机是 PR #6612 上 dogfood 曾自动发布两个幻觉 Critical——两者都写不出具体触发）；验证者得到可测的 claim（Step 4 的 verdict 变成把声称的触发在真实代码里走一遍的结果，而非对 prose 的可信度投票）。报告门是严重度不对称的：无 scenario 无成本的 Suggestion 在源头丢弃；触发不确定的疑似 Critical 以Confidence: low保留给验证者裁决。丢弃一个 Suggestion 损失的是客套话，丢弃一个 Critical 损失的是出厂 bug。

worktree 而非 stash + checkout：git stash→gh pr checkout→ 评审 → 切回 →stash pop的方案脆弱——中断会孤儿化 stash、恢复失败会错分支、多条早退路径都要清理。git worktree add→ 评审 →git worktree remove让用户的树从未被触碰，消除一整类 bug；代价是 worktree 里要npm ci（额外时间），被隔离收益抵消。Step 1 在创建新 worktree 前先清理上次中断运行留下的陈旧 worktree。

effort 三级 + minimal 拓扑（SKILL.md 的 argument-hint 即其命令行面：/review [pr|file] [--effort low|medium|high] [--severity-floor …] [--topology minimal] [--comment] [--fix] [--resume]）：

• low= 编排器自身上下文里按plan.budget.inlineAngles（3–6 个，按 diff 大小缩放）的定向角度加一次缺口扫描，仅 hunk 可见的 bug，≤10 个未验证 finding；
• medium= high 管线去掉最贵的通道：减维度集（无对抗人格、无 Agent 8）的并行查找扇出 + build & test + 单次验证——finding 是验证过的，但 Approve 上限为 Comment，无反向审计。实测约为 high 的三分之一到一半时间/token；
• high= 完整管线。
• --topology minimal是另一根轴（A/B 对比臂）：编排器上下文里单次仔细走查，≤15 个 finding，0 个 subagent，存在意义是让完整管线与最小 prompt 跑同一组 PR 按模型比较质量。

护栏（因为未验证的通道天生召回受限）：low 与 minimal 标注 unverified、不产出 Approve/Request-changes verdict；永不发 PR（--comment在 low 上强制升 high，minimal 臂上解析器直接把comment.effective强制为 false）；永不读写增量缓存（否则 medium 运行的 SHA 会让后续 high 运行误报「无新变更」）。各等级的 diff 获取机制（worktree、diff 捕获、chunk 计划）完全一致——等级改变谁读 diff 与之后跑什么，从不改变 diff 怎么拿到。默认：PR 目标 high（产品是公开 verdict），本地/文件目标 medium。

Suggestion 与 Critical 同为行内评论：曾被「可更新的 issue 评论汇总」方案替代过又回退，原因有二：GitHub 在作者编辑锚定行后把行内线程标记 Outdated 并折叠——已处理的行内 finding 自动消失，issue 评论没有这种生命周期，PATCH 成「全部已处理」也删不掉评论本身；​```suggestion围栏只在 diff 行上的 review 评论里渲染为可一键应用，在 issue 评论里退化为普通代码块——最需要一键应用的恰好是机械的、局部的 Suggestion。残余问题（作者拒收且未改行的 Suggestion 会在后续运行里近似重复）由 presubmit 的 Overlap 检查兜住。

9. review-agent：一次被测量的 60% token 节省

DESIGN.md 最后的大型实测记录「The inherited tool surface」给出了一个具体而可复算的优化。问题：AgentCore.prepareTools有两分支——声明tools列表的 subagent 类型走getFunctionDeclarationsFiltered，不声明的继承一切（含延迟工具）。general-purpose是唯一不声明tools的内置类型，于是评审 Agent 每轮携带 51 个工具 schema。实测（6 文件 / 115 行 diff，同一启动 prompt、同一隔离QWEN_HOME，仅subagent_type不同）：

51 个工具里 35 个是computer_use__*桌面自动化 schema，单独就是每轮 11,011 token；跨 13 个 Agent 的名册，第一行与末行的差约 1.08M prompt token（115 行的变更）。83,116 token 的差距可精确分解：工具声明 4 × 17,731 = 70,924、技能目录 4 × 3,119 = 12,476（15%，是二阶项——不带 SKILL 工具时启动技能目录不再注入首条用户消息，且首条消息每轮重发）、系统 prompt −284。中间行（deferral）被测量后拒绝：deferral 不为低于核心工具集而设计，显式列表才能穿过那个地板，且改动面更小。

该内置类型在 builtin-agents.ts 中声明（REVIEW_BUILTIN_SUBAGENT_TYPE = 'review-agent'），注释直接引用 DESIGN.md 的这节数据。文档同时记录了两点诚实的代价与一个命名后果：闭包列表放弃的能力是真实的（web_fetch、MCP 工具、嵌套agent），且SubagentManager.loadSubagent的解析顺序是 session > project > user > extension > builtin，用户自写的.qwen/agents/review-agent.md会遮蔽该内置项——若其不声明tools，全部节省无声消失而无诊断。文档还附上完整复现方法（含为什么测试文件也要一并回退：它 import 了被回退的导出，留下它会让build:packages报 TS2724 并被&&吞掉后续步骤）。

10. 跨仓库轻量模式与构建/测试命令自动发现

CLI 工具本质上是仓库本地的：worktree、build/test、跨文件分析都需要本地代码。DESIGN.md 指出竞品（Copilot CLI、Claude Code、Gemini CLI）完全不支持跨仓库 PR 评审；本技能的轻量模式是 CLI 能做到的最好形态：GitHub API 天然跨仓库（gh pr diff <url>、gh pr view <url>、gh api .../comments），LLM 评审与 PR 评论发布照常工作，需要本地文件的部分全部跳过——严格优于「不支持」。关键实现细节：Step 7 必须用 URL 解析出的 owner/repo，而不是gh repo view（它返回当前仓库）。

构建/测试命令的发现选了从 CI 配置自动发现而非让用户写.qwen/review-tools.md：每个项目已在 CI 配置（.github/workflows/*.yml、Makefile等）里定义了工具链，读这些文件零用户成本且无需用户重复维护；LLM 足以解析 YAML workflow 提取相关命令。优雅降级：没有 CI 配置时跳过发现，LLM Agent 照常评审 diff。

11. 事故日志：规则的每一处都有出处

DESIGN.md 后半部分（「Measured incidents behind the SKILL.md rules」）是 30 余条实测事故的汇编，每条都对应 SKILL.md 中一条规则的由来。挑几类代表：

• 转录类：模型被要求逐字转发的 4 652 字符 roster prompt 实际只交付 2 893 字符——保留头部、自加前言、砍掉中段 1900 字符，然后它读完覆盖检查的拒绝后得出「Agent 显然做了工作」、全程没调用compose-review、打印了自己合成的高置信Review complete — Approve。同类还有 23/23 chunk Agent 拿到不点名 diff 文件的 prompt、全部零工具调用、齐声说出 prompt 递给它们的句子——「收据」本身就写在启动它们的 prompt 里。
• 门禁类：/review 6771（评审自己）无--comment却自动发布了 COMMENT review，正文还宣称有未发布的行内建议；同一门被以「phantom APPROVE posted 行」的形式二次违反——门禁正确阻断了一切写操作，完成行却说 APPROVE 已发布。
• 验证类：PR #6486 的Ctrl+F双发 blocker——作者在 diff 里加的 guard「读起来像修复」但什么都没改变，第二个处理器在未触碰的text-buffer.ts:2663，独立订阅无传播中止的KeypressContext.broadcast()。由此确立「fixed by this diff」是最贵的 verdict：三个 verdict 里唯一免费且无人记录的，正是唯一能放出 bug 的；且判定栏必须让验证者去读 diff 之外、blocker 正文点名过的代码（pr-context的extractCodeRefs现在会把带路径的 blocker 渲染成 Referenced code 列表）。
• 并发类：验证者的探针残留在共享 worktree 里，被反向审计者差点作为 Critical 上报（#9118，filed as #9207）——审计者靠自行发明git show HEAD:兜底才恢复。修复拆两半：scratch-tree给每个验证分片一次性兄弟 worktree（每次调用返回干净树、标签即分片的记录键、隔离失败则判 inconclusive 而非回退共享树），同时硬化所有读码方——「不在 diff 也不在 commit 里的代码不是 finding，可疑之处对照git show HEAD:<path>判定」。
• 收敛类：#9659 第 17–23 轮每轮 7/5/3/5/4/1/6 个新 Critical、近零误报地稳定振荡——因为收敛姿态的地板读的是Critical这一个 bit，而它编码了三个正交决策。修复（#10291）让 finding 携带direction（certifies-falselyvsfails-closed）与baseline（regressionvsnew-surface）两轴，且仅当fails-closed且new-surface时 Critical 才被延期——那是唯一「合并既不认证错误结果、也不回归任何东西」的组合；缺失或矛盾的轴一律按「在任何地板都发布」处理，宁可多报不可错删。
• 成本类：同一 14 Agent 扇出的两次实测分别 11.7 与 41 分钟，差在个别 Agent 花 40–100 次模型调用逛树（健康 Agent 25–45 次）——agentToolBudget（budget.ts 中 30–60 的软上限）因此是软预算：到达上限时停止探索、按手头证据出 finding、用Budget gap: <check>行披露没做完的检查，披露喂给 whiff/收据机器，未披露的漫游只喂墙钟。该披露格式在 budget.ts 里有完整的解析器（含中文「预算缺口」双语形态、占位符分类器、危险码点清洗）——因为本仓库评审自己的 PR，引用这些字符串的行必须与使用它们的行为区分开。

12. 被拒绝的备选方案与未来优化

DESIGN.md 的拒绝清单（Rejected alternatives）值得单列，因为每条都有具体理由：

Fork Subagent是文档点名的未来优化：当前 17–28 次调用每个都从零创建 subagent，按每个约 52K（50K 系统 + 2K 任务）计约 880K–1.5M 输入 token、冗余巨大；若 fork 当前会话、共享 prompt 缓存前缀，每个 fork 只付约 2K delta，估计节省 90–93%（880K–1.5M → 84–106K）且零质量影响——fork 的 Agent 天然继承 PR 上下文与评审规则、验证与反向审计 Agent 天然继承之前所有 finding。未实现的原因：需要改 Qwen Code 核心（AgentTool、forkSubagent.ts、CacheSafeParams），属平台级功能（约 400 行、约 5 天），不是/review特定的改动。

13. 总结：一条可引用的设计原则

通读 DESIGN.md，贯穿全文的主线可以压缩成一句反复出现的判据：

确定性拥有证据，判断拥有裁决（determinism owns the evidence, judgment owns the ruling）。

参数解析、CI 分类、评论分桶、事件选择、轮次上限、覆盖收据、blocker 识别、ledger 解析——所有可判定、可测试的部分都移进了 packages/cli/src/commands/review/ 下带测试的 TypeScript 子命令，与 SKILL.md 在同一 monorepo 里版本化、不可能漂移；而什么算 Critical、验证的裁决、放行授权语义、评审角度——所有判断形状的部分留在 prompt。文档中每一条「散文规则」背后都有一次实测事故（转录、漂移、幻觉、门禁失守），每一条「子命令化」决策都对应一类散文承载的 bug 谱系。对于任何在用 LLM Agent 构建多阶段工作流的团队，这份设计文档提供了两种可迁移资产：一套多 Agent 评审管线的完整架构参数（14 Agent 名册、ceil(F/8)分片、双空轮停点、按拓扑的轮次上限、diff-as-file + 精确平铺 chunk 计划），以及一份用真实事故写成、可逐条核对的设计决策审计。

延伸阅读：运行时行为见 SKILL.md 与条件参考 references/posting.md、references/persistence.md；预算与轮次上限的完整实现（含中文预算缺口披露的解析器）见 budget.ts；评审专用内置 subagent 的声明与测量注释见 builtin-agents.ts。

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code