Repomix 代码质量评审 Agent 设计指南从 Severity 分级到八大聚焦领域的工程化评审体系【免费下载链接】repomix Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix导读本文以 .agents/agents/reviewer-code-quality.md 为核心系统拆解 Repomix 项目中代码质量评审 Agent的完整设计如何为 diff 中的每个问题标注严重级别与置信度、如何在 8 个聚焦领域Bug、异步并发、资源管理、错误处理、API 契约、类型安全、代码坏味道、测试质量内做有证据的评审、以及如何按结构化模板输出可被 orchestrator 直接分诊的评审报告。读完本文你将掌握一套可复用的AI 代码评审提示词范式并看到它如何与 Repomix 的源码实践错误处理、worker 并发、资源清理相互印证。一、角色定位只做质量评审绝不越界该文档定义的角色是一个代码质量评审者code quality reviewer。它的核心职责是Analyze the provided diff and reporteveryfinding you have concrete evidence for, each labeled with severity and a confidence level.即分析传入的 diff报告每一条有具体证据支持的发现并为每条发现标注严重级别和置信度。有两条硬性纪律贯穿全文不预过滤边缘发现Do not pre-filter borderline findings。文档明确解释了原因the orchestrator triages your report and drops what it disagrees with, so a finding you suppress is lost while one it rejects costs a line.——协调者orchestrator会做最终分诊你压下的发现就永久丢失了而它拒绝的发现只是多花一行文字。这条设计在 .agents/commands/code/review-loop.md 中得到了呼应评审循环会并行派出 6 个评审 Agent然后由 orchestrator 充当过滤器you are the filter只保留自己也认为值得注意的问题并分类为Fix必须修或Skip风格、吹毛求疵、范围蔓延。范围限制Scope limits。评审者只能停留在代码质量范畴即下文八大聚焦领域绝不虚构问题never invent issues不评论风格、格式、命名约定——除非它们引入了歧义或风险。这保证了评审输出是高信噪比的工程结论而不是机械的 lint 复读。二、Severity 分级体系四级量化责任对等文档定义了严格的四级严重级别每一级都绑定是否必须在合并前修复的行动语义级别定义处理策略Critical会导致崩溃、数据丢失或静默数据损坏合并前必须修复High在真实条件下行为不正确、资源泄漏、竞态条件合并前应当修复Medium防御性改进、潜在未来问题、可维护性担忧建议处理Low不影响正确性的建议作者可自行取舍这套分级的关键在于严重级别必须结合代码运行环境校准。文档在Context matters中明确要求Hot path or library API demands higher rigor than one-shot CLI scripts or test helpers.——热路径或库 API 的评审严格度要求高于一次性 CLI 脚本或测试辅助代码。这正是严重级别是上下文敏感的工程常识的形式化。三、八大聚焦领域详解3.1 Bugs and Logic ErrorsBug 与逻辑错误评审者需要按四类数据流逐项排查控制流差一错误off-by-one、错误的循环边界、不可达代码、switch 中缺少 break 导致的 fallthrough、对判别联合discriminated union不穷尽的条件分支数据流使用未初始化或过期变量、错误的变量遮蔽shadowing、对共享状态的修改、复制粘贴导致的错用变量Null/undefined在无守卫的情况下解引用可空值可选链静默产生undefined但调用方需要值使用逻辑或||给假值但有意义的默认值如0或做兜底——文档明确推荐优先使用空值合并运算符??运算符宽松相等引发的强制类型转换 Bug、与||混用、运算符优先级错误类型强制转换绕过运行时检查的不安全as断言、算术/字符串拼接中的隐式强制转换、无校验的JSON.parse。这一领域在 Repomix 源码中能找到大量正面与反面案例的印证。例如 src/shared/errorHandle.ts 中的isError类型守卫const isError (error: unknown): error is Error { if (error instanceof Error) return true; if (typeof error ! object || error null) return false; const obj error as Recordstring, unknown; return ( typeof obj.message string (!(stack in obj) || typeof obj.stack string) (!(name in obj) || typeof obj.name string) ); };这正是对unknown先收窄再使用的正确示范先用typeof/null检查排除基本类型再用in操作符逐字段校验结构as断言只发生在结构校验通过之后。3.2 Async and Concurrency异步与并发Floating promises没有await、.catch()或void标注的异步调用——错误被静默吞掉竞态条件跨异步操作共享可变状态、文件 I/O 的 TOCTOUtime-of-check-to-time-of-use、并发修改集合错误传播异步回调中错误未向上传播、.catch()里return而不是重新抛出、Promise.all与Promise.allSettled的误用串行 vs 并行本可独立的操作在循环里被无谓地串行await或者顺序敏感时却做了不安全的并行执行。Repomix 的 src/core/security/securityCheck.ts 是一个教科书级的正例批量任务通过Promise.all并行提交给 worker 线程池同时用try/catch/finally保证taskRunner.cleanup()在任何路径成功、失败、异常下都被执行try { // ...提交批次、统计进度、聚合结果 return batchResults.flat().filter(...); } catch (error) { logger.error(Error during security check:, error); throw error; // 捕获后重新抛出绝不吞掉 } finally { await taskRunner.cleanup(); // 无论成败都回收线程池 }注意三处细节恰好命中聚焦领域错误被logger.error记录后重新抛出对应错误传播、finally保证资源回收对应资源管理、并行度被显式封顶Math.min(2, deps.getProcessConcurrency())避免与并发运行的 metrics worker 池争抢 CPU对应共享资源下的并发控制。3.3 Resource Management资源管理泄漏错误路径中未关闭的流、文件句柄、socket添加后从未移除的事件监听器清理时未清除的定时器清理模式缺少try/finally或usingSymbol.dispose来保证确定性清理内存闭包不必要地捕获大作用域无边界或无限期增长、无驱逐策略的集合。src/core/file/fileProcessorRun.ts 展示了 Repomix 如何把资源上限变成显式常量export const DEFAULT_FILE_PROCESSOR_TIMEOUT_MS 60_000; // 单命令超时 const FILE_PROCESSOR_MAX_BUFFER 64 * 1024 * 1024; // stdout 上限 64MB const FILE_PROCESSOR_CONCURRENCY Math.min(8, Math.max(1, os.cpus().length)); // 并发进程上限注释还解释了每个阈值的工程理由超时取 60 秒而非 30 秒是因为npx tool {file}在冷缓存时可能花近一分钟下载包execFile默认约 1MB 的 stdout 上限会在较大输出上静默硬失败所以主动提高并把溢出转成明确的处理器错误——这同时是错误路径清晰化聚焦领域 4的实践。3.4 Error Handling错误处理吞错Swallowed errors空catch块catch只打日志不重抛、不返回错误状态包装错误时丢失原始堆栈错误类型化错误捕获unknown却不做窄化就当作特定类型处理模式不一致回调风格与 Promise 风格混用有的地方返回null、有的地方抛异常缺失错误路径对现实失败场景网络、文件不存在、权限拒绝、超时完全没有处理。Repomix 的 src/shared/errorHandle.ts 是这一领域的完整样板handleError用三个分支区分预期的 RepomixError只展示消息堆栈进 debug 日志、意外 Error默认展示堆栈、未知错误通过inspect安全序列化且用内层try/catch兜底无法序列化的极端情况。更精细的是rethrowValidationErrorIfSchemaErrorsrc/shared/errorHandle.ts它通过duck typing鸭子类型识别 ZodError 与 ValiError从而既不用急切导入任一校验库又能跨 worker 边界识别只保留了{ name, message, issues }普通对象的错误——注释明确写道这与isError/isRepomixError保持一致正是跨进程边界保持错误类型语义的工程实践。3.5 API Contract ViolationsAPI 契约违背前置条件假设Precondition函数假设输入已校验但调用方并未保证或函数文档声明了接受范围却不强制后置条件破坏Postcondition改动后返回值或副作用不再匹配调用方的预期不变式违背Invariant循环不变式、类不变式或模块级不变式被改动破坏。src/core/file/workers/fileProcessWorker.ts 中有个值得一提的正面例子FileProcessTask中的level文件包含级别被注释明确说明是在主线程预计算Precomputed in the main thread这样 worker 不必重复做 glob 匹配来解析包含级别。把前置条件在契约层面显式化接口注释 预计算正是避免函数假设输入有效但调用方不保证这一 API 契约反模式的直接手段。3.6 Type SafetyTypeScript 类型安全any泄漏显式或隐式any关闭了下游的类型检查不安全断言无运行时校验的as强转对确实可空的值使用非空断言!不完整联合对联合类型的 switch/if-else 缺少穷尽性检查泛型误用约束过宽、未使用的类型参数、本应具体的类型却用泛型。对照上文isError的实现可以看出Repomix 的准则是先收窄、再断言。as Recordstring, unknown这类断言只出现在结构校验typeof、in、name匹配通过之后这与文档Unsafe assertions: as casts without runtime validation的警告形成直接呼应。类似地rethrowValidationErrorIfSchemaError中先Array.isArray(err.issues)再进入as转型也是同一原则的延续。3.7 Code Smells代码坏味道臃肿Bloaters函数职责过多、参数列表过长超过 3~4 个参数应提示改用 options 对象、基本类型痴迷primitive obsession耦合Coupling特性依恋feature envy、霰弹式修改shotgun surgery、访问其他模块的私有/内部细节可丢弃物Dispensables死代码、不可达分支、未使用的导出、投机性泛化speculative generality、重复逻辑。Repomix 项目规范 .agents/rules/base.md 也给出了配套约定保持每个文件聚焦单一职责把约 250 行视为需要检查内聚性的信号——但这不是强制拆分令当文件因单一内聚关注点如大型数据/配置表而长时保持原样。这为评审者判断长文件是否是坏味道提供了项目级上下文依据避免机械地按行数开药。3.8 Test Quality测试质量当 diff 含测试时虚假信心False confidence测试断言实现细节而非行为、同义反复断言、mock 复刻了实现本身脆弱测试Fragile tests耦合执行顺序、测试间共享可变状态、依赖时序。关于可测试性.agents/rules/base.md 中的依赖注入模式值得引用——它把依赖收进deps参数默认值测试通过传入测试替身test doublemock 依赖仅在依赖注入不可行时才使用vi.mock()。这把可测性从评审口号变成了仓库级强制约定export const functionName async ( param1: Type1, param2: Type2, deps { defaultFunction1, defaultFunction2 }, ) { // Use deps.defaultFunction1() instead of direct call };四、输出格式结构化、可分诊、可追溯每条发现必须严格按如下模板输出**[SEVERITY]** Brief title - **Location**: File and line/function - **Confidence**: High / Medium / Low -- and what the Medium/Low ones hinge on - **Issue**: What is wrong - **Risk**: Why it matters in practice - **Suggestion**: How to fix it (be specific)然后按严重级别分组Critical 优先空类别直接省略。这份模板的设计意图清晰Location 要求精确到文件与行/函数——评审必须可追溯Confidence 要求说明 Medium/Low 依赖什么前提——把不确定性的赌注显式摊开方便 orchestrator 判断Issue/Risk/Suggestion 三段式——先讲错在哪、再讲实际危害、最后给具体修法保证每条报告自包含、可直接决策。对比同目录下的其他评审 Agent 可以发现这是 Repomix 的统一输出规范.agents/agents/reviewer-security.md 要求 Security 评审标注 Category CWE如Command Injection (CWE-78).agents/agents/reviewer-conventions.md 则要求标注deviation破坏现有约定或discussion更优但不一致类型。也就是说六个评审 Agent 共享证据 严重级别 置信度的骨架各自扩展领域专属字段这正是多 Agent 评审体系能并行产出、统一分诊的关键。五、评审指导原则不确定时报告而不是沉默文档最后的 Guidelines 是该角色的职业守则不确定也要报告Include the finding with a confidence note (High / Medium / Low) rather than dropping it. If nothing found, say so -- dont invent issues.——拿不准就带上置信度上报什么都找不到就明说绝不虚构尊重既有约定If a pattern is used intentionally and consistently elsewhere, dont flag it.——某模式若在项目其他位置被有意且一致地使用不要标记明确不标记清单格式化、风格、导入顺序、命名约定除非确实误导、TODO除非表明存在未完成的代码路径、自动生成代码必须具体Consider error handling is not useful -- name which call can fail and what the consequence is.——要指出哪个调用可能失败、后果是什么上下文校准按代码运行环境调整严重级别前文已述。第 1 条与第 3 条看似矛盾实则互补不虚构约束的是事实边界不确定也报告约束的是风险覆盖——两者的平衡点是置信度这个显式字段。这一设计保证了评审者在召回率与精确率之间不会顾此失彼。六、在 Repomix 评审流水线中的位置该评审 Agent 不是孤立存在而是 .agents/commands/code/review-loop.md 定义的迭代评审-修复循环最多 3 轮中的一环Review——对当前分支相对main的改动并行派出 6 个评审 Agentreviewer-code-quality、reviewer-security、reviewer-performance、reviewer-test-coverage、reviewer-conventions、reviewer-holisticTriage——Agent 不做预过滤本文第 1 节orchestrator 是过滤器把存活发现分为Fix明确缺陷必须修或Skip风格、吹毛求疵、范围蔓延动手前先展示一个简短的分类表Fix——只修 Fix 项改动保持最小Verify——运行npm run lint与npm run test修复回归直至全部通过Re-review——只复查新改动的行不重复提出已跳过项。当没有 Fix 项剩余或达到 3 轮时停止输出修了什么、跳过了什么的摘要。这一循环把本文的评审 Agent 从单次输出升级为闭环质量门禁并与项目规范 .agents/rules/base.md 的验证命令npm run lint/npm run test对应 CONTRIBUTING.md 中的开发流程无缝衔接。七、总结一份可复用的 AI 代码评审规格回顾全文.agents/agents/reviewer-code-quality.md 本质上是一份高度工程化的 LLM 评审提示词规格其可复用要点可浓缩为明确角色与纪律只评审质量、只报告有证据的发现、不预过滤、不越界量化严重级别四级定义绑定合并门禁决策且按运行上下文校准穷尽聚焦领域8 个领域覆盖 Bug、并发、资源、错误、契约、类型、坏味道、测试每个领域给出可执行的具体检查清单结构化输出Location / Confidence / Issue / Risk / Suggestion 五字段按严重级别分组供 orchestrator 直接分诊不确定性的显式管理置信度字段 报告而非沉默原则在召回与精确之间取得平衡流水线闭环通过多 Agent 并行 orchestrator triage 迭代修复循环落地为实际质量门禁。而对 Repomix 自身的源码src/shared/errorHandle.ts、src/core/security/securityCheck.ts、src/core/file/fileProcessorRun.ts的对照阅读可以确认这份评审规格并非纸面文章——仓库代码本身就是其聚焦领域清单的忠实执行者。无论是unknown收窄、try/finally清理、错误重抛还是并发上限与超时防护评审 Agent 要检查的每一项最佳实践Repomix 都已在自己最核心的代码路径上落地。【免费下载链接】repomix Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考