Windmill 分支差异审查 Agentbranch-diff-reviewer实战指南基于 AI 的 PR 前置代码审查体系【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill导读本指南围绕 Windmill 开源仓库中的 branch-diff-reviewer Agent 定义 展开系统讲解这套「以 AI 子代理方式对当前分支与 main 分支差异进行全方位代码审查」的机制。读者可以从中掌握该 Agent 的定位与触发时机、六类审查维度的具体内容、针对 Rust 后端与 Svelte 5 前端的项目级审查规则、标准化的审查输出格式以及它与仓库内 REVIEW.md、AGENTS.md、local-review 技能 共同构成的完整代码评审闭环。读完即可在 Windmill 仓库或借鉴其模式中在合并代码或提交 PR 之前获得一份可执行、可落地的 AI 审查报告。一、Agent 定位为 PR 前置审查而生的专用子代理1.1 它是谁branch-diff-reviewer是 Windmill 仓库在.claude/agents/branch-diff-reviewer.md中定义的一个Claude Code 专用子代理subagent其元数据头frontmatter给出了它的完整契约字段定义值说明namebranch-diff-reviewerAgent 的唯一标识description对当前分支相比 main 的全部变更进行全面的代码审查覆盖 bug、优化机会、代码风格、潜在错误、对项目约定的遵循度toolsGlob, Grep, Read, WebFetch, TodoWrite, WebSearch, ListMcpResourcesTool, ReadMcpResourceTool, mcp__svelte__* , mcp__ide__* , Bash, Skill以只读类工具为主Glob/Grep/Read/Bash 获取 diff并接入 Svelte 官方 MCP文档查询、语法修正与 IDE MCP诊断、执行代码不包含任何写文件工具modelinherit继承调用方当前配置的模型从工具清单可以看出这是一个read-only 的审查型 Agent——它只能读取、搜索和执行命令来获取信息不能修改任何文件这从机制上保证了审查的客观性关于这一点local-review SKILL 有更深入的阐述见第六节。1.2 何时触发description中明确了三个典型触发场景并配有用例对话示例功能分支开发完成后用户完成了某个新功能例如kafka trigger的实现并希望在合并前获得反馈创建 PR 之前用户准备提交 PR希望先做一次质量把关实现模式存疑时用户不确定自己的实现是否遵循了项目既有模式希望对照 main 检查模式一致性。在上述场景下调用方主会话应通过任务工具启动branch-diff-reviewer子代理让它以「冷启动」的独立上下文分析当前分支与 main 的差异并提供详细反馈。在 local-review SKILL 中这一点被明确写为规范动作subagent_type: branch-diff-reviewer并强调「审查必须在全新的上下文中运行而不是在当前会话内联执行」——因为主会话在迭代 diff 的过程中会吸收开发者的推理与合理化解释容易产生锚定效应而漏掉 CI 能发现的问题子代理像 CI 一样从零开始恰好能补上这一盲区。二、审查流程先拿 diff再逐文件分析Agent 被唤醒后的第一步是收集变更全貌流程如下# 1. 获取当前分支相对 main 的完整差异含未合并的提交 git diff main...HEAD # 2. 查看提交历史理解变更脉络 git log main..HEAD --oneline # 3. 识别所有修改、新增、删除的文件拿到 diff 之后对每一个变更文件展开三问是否符合项目既有模式检查 CLAUDE.md 及仓库根目录的 AGENTS.md 约定该文件的职责是什么、在整个代码库中扮演什么角色依赖关系如何——这些改动会不会影响系统的其他部分注意git diff main...HEAD使用三点语法three-dot它计算的是main与HEAD的共同祖先到HEAD的差异能准确反映本分支相对于 main 引入的全部变更是分支级审查的正确姿势。三、六大审查维度从 Bug 到测试全覆盖对每个显著变更Agent 必须从以下六个维度逐一评估并汇报。 Bugs Correctness正确性逻辑错误或未处理的边界情况Null/undefined 处理问题异步代码中的竞态条件race condition错误的错误处理路径类型不匹配或不安全的类型转换⚡ Performance性能低效的算法或数据结构数据库代码中的 N1 查询问题前端代码中不必要的重渲染数据库查询缺少索引异步上下文中执行阻塞操作内存泄漏或过度分配针对 Rust检查不必要的clone、低效的 serde 用法、异步中的阻塞操作针对 Svelte检查低效的响应式逻辑、循环中缺失key、过多的effect Security安全SQL 注入漏洞缺少输入校验敏感数据泄露认证/授权缺口不安全的反序列化 Code Quality Style代码质量是否遵循项目约定CLAUDE.md / AGENTS.md 准则应重构的代码重复含糊或误导性的命名缺失或不充分的文档过度复杂、可简化的逻辑死代码或未使用的 import️ Architecture Design架构设计关注点分离是否恰当是复用了既有工具还是新造轮子与既有模式的一致性错误传播是否正确API 设计问题 Testing Considerations测试考量为新功能建议测试用例识别未覆盖的边界情况指出变更是否破坏既有测试假设这六个维度与仓库根目录 REVIEW.md 的共享评审策略一脉相承REVIEW.md强调「只报告你有信心是真实存在、且由本次 PR 引入的问题」并聚焦于 bug、安全问题、性能和明确的AGENTS.md违规——与本 Agent 的维度划分互为表里。四、项目特定规则Windmill 的 Rust Svelte 5 双栈审查清单这是branch-diff-reviewer最体现项目定制性的部分。Windmill 是「Rust 后端 Svelte 5 前端」架构见 AGENTS.md因此 Agent 内置了两套专用检查清单。4.1 Rust 后端backend/ 目录SELECT语句必须显式列出列名worker 代码中严禁出现SELECT *正确使用sqlx参数化查询防止 SQL 注入错误必须使用windmill-common::error中自定义的Error枚举异步代码不得阻塞 tokio 运行时检查 serde 属性以获得最优序列化例如避免不必要的Serialize/Deserialize派生API 变更必须同步更新openapi.yaml。第 3 条在源码中有直接佐证——backend/windmill-common/src/error.rs 定义了全仓库统一的结果类型与错误枚举pub type ResultT std::result::ResultT, Error; pub type JsonResultT std::result::ResultJsonT, Error; #[derive(Debug, Error)] pub enum Error { #[error(Bad gateway: {0})] BadGateway(String), #[error(Not found: {0})] NotFound(String), #[error(Not authorized: {0})] NotAuthorized(String), #[error(Permission denied: {0})] PermissionDenied(String), #[error(Require Admin privileges for {0})] RequireAdmin(String), #[error(Bad request: {0})] BadRequest(String), #[error(Internal: {0})] InternalErr(String), // ... 共 512 行的完整枚举定义 }该枚举基于thiserror派生覆盖了数据库连接、SQL 执行、JSON 序列化、UUID 解析、IO 等常见失败类型并携带Location信息例如IoErr { error, location }便于定位。Agent 在审查中若发现新代码直接使用anyhow::Error或裸Boxdyn Error即可依据这条规则判定为违反项目约定。第 1 条同样有据可查在 backend/windmill-worker/src/duckdb_executor.rs 与 backend/windmill-worker/src/sql_utils.rs 中仍存在若干SELECT *的 SQL 文本这正是该审查规则要盯防的典型模式动态 SQL 拼接场景尤其需要显式列名以保证 schema 变更可控。4.2 Svelte 5 前端frontend/ 目录Svelte 5 文件须正确使用 Runes$state、$derived、$effect{#each}块中须有key属性事件处理器使用新语法onclick而非on:clickSvelte 5 中用 snippets 替代 slots使用$props()进行正确的 props 声明。这些规则与仓库对前端的技术选型完全一致AGENTS.md 明确要求「编写 Svelte 代码前必须先阅读svelte-frontend技能」并规定前端代码不得直接调用crypto.randomUUID()而应导入$lib/utils/uuid中的randomUUID——这些都是审查时对照项目约定的具体抓手。五、标准化的审查输出格式Agent 的输出遵循固定模板确保每份报告结构一致、可被快速消费## Summary [变更概述与整体评估] ## Critical Issues [合并前必须修复的问题] ## Recommendations [能显著提升代码质量的改进] ## Minor Suggestions [锦上添花与风格改进] ## Positive Observations ✅ [值得肯定的做得好的部分] ## File-by-File Details [按文件组织的详细反馈]针对每一个问题必须提供四项信息Location文件路径与行号Issue问题的清晰描述Impact为什么这个问题重要影响面Suggestion具体的修复方案必要时附代码示例这套「位置—问题—影响—建议」四元组结构与仓库 REVIEW.md 中「P0/P1/P2 严重度分级 明确结论行Good to merge / Mergeable but… / Should address…」的评审策略互相补充子代理负责产出细节与证据REVIEW.md负责裁决与分级二者共同构成完整的评审语言。六、行为准则与生态联动6.1 行为准则Behavioral Guidelines抓大放小全面但分优先级聚焦关键问题建设性批评每条批评都要附建议具体可执行含糊的反馈没有价值肯定优点正反馈同样重要考虑上下文理解决策背后的原因而非机械挑错意图不明时提问变更意图不清楚时主动澄清引用项目文档指出约定违规时引用 AGENTS.md、REVIEW.md 等文档原文REVIEW.md明确要求「引用AGENTS.md中确切的规则原文」。6.2 与仓库审查生态的联动该 Agent 并不是孤立的而是 Windmill「本地审查」体系的一环完整链路如下触发主会话或用户判断需要审查 → 按 local-review SKILL 用subagent_type: branch-diff-reviewer启动冷上下文子代理策略子代理先读根目录 REVIEW.md严重度分级、公共表面检查清单、测试覆盖评估再读 diff 涉及目录的AGENTS.md执行子代理产出一份符合第六节格式的报告原样转达给用户不做二次总结或过滤这正是冷启动的意义所在落地若需要主会话通过gh pr review --comment --body ...或gh api repos/{owner}/{repo}/pulls/{pr}/reviews将报告含行级 inline 评论 JSON发布到 GitHub PR 上。此外仓库的.claude/hooks/中还配置了 guard-main-branch.sh 等守卫钩子配合 Agent 在合并前把守 main 分支——「先审查、后合入」是 Windmill 开发流程的一贯原则AGENTS.md 中 Workflow 的第 4 步 Validate 也强调类型检查通过不等于验证完成必须实际运行改动路径。6.3 通用化价值虽然本 Agent 面向 Windmill 仓库定制但其方法论diff 收集 → 逐文件分析 → 六维审查 → 结构化输出完全可移植任何「Rust 后端 Svelte 前端」或类似多语言栈的团队都可以仿照.claude/agents/branch-diff-reviewer.md的结构替换项目特定规则段第四节的 Rust/Svelte 清单快速得到一套贴合自身技术栈的 AI 分支审查工具。七、小结branch-diff-reviewer是 Windmill 将 AI 深度嵌入工程流程的代表作它以只读子代理形态运行保证了审查独立性以六个维度系统覆盖正确性、性能、安全、质量、架构与测试以项目特定规则让审查真正懂 Rust 与 Svelte 5 的技术细节以结构化输出保证结论可执行、可发布。结合 REVIEW.md 的严重度分级与 local-review SKILL 的编排规范它构成了一个从「写完代码」到「合并 main」之间完整的 AI 质量闸门。【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Windmill 分支差异审查 Agent（branch-diff-reviewer）实战指南：基于 AI 的 PR 前置代码审查体系
Windmill 分支差异审查 Agentbranch-diff-reviewer实战指南基于 AI 的 PR 前置代码审查体系【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill导读本指南围绕 Windmill 开源仓库中的 branch-diff-reviewer Agent 定义 展开系统讲解这套「以 AI 子代理方式对当前分支与 main 分支差异进行全方位代码审查」的机制。读者可以从中掌握该 Agent 的定位与触发时机、六类审查维度的具体内容、针对 Rust 后端与 Svelte 5 前端的项目级审查规则、标准化的审查输出格式以及它与仓库内 REVIEW.md、AGENTS.md、local-review 技能 共同构成的完整代码评审闭环。读完即可在 Windmill 仓库或借鉴其模式中在合并代码或提交 PR 之前获得一份可执行、可落地的 AI 审查报告。一、Agent 定位为 PR 前置审查而生的专用子代理1.1 它是谁branch-diff-reviewer是 Windmill 仓库在.claude/agents/branch-diff-reviewer.md中定义的一个Claude Code 专用子代理subagent其元数据头frontmatter给出了它的完整契约字段定义值说明namebranch-diff-reviewerAgent 的唯一标识description对当前分支相比 main 的全部变更进行全面的代码审查覆盖 bug、优化机会、代码风格、潜在错误、对项目约定的遵循度toolsGlob, Grep, Read, WebFetch, TodoWrite, WebSearch, ListMcpResourcesTool, ReadMcpResourceTool, mcp__svelte__* , mcp__ide__* , Bash, Skill以只读类工具为主Glob/Grep/Read/Bash 获取 diff并接入 Svelte 官方 MCP文档查询、语法修正与 IDE MCP诊断、执行代码不包含任何写文件工具modelinherit继承调用方当前配置的模型从工具清单可以看出这是一个read-only 的审查型 Agent——它只能读取、搜索和执行命令来获取信息不能修改任何文件这从机制上保证了审查的客观性关于这一点local-review SKILL 有更深入的阐述见第六节。1.2 何时触发description中明确了三个典型触发场景并配有用例对话示例功能分支开发完成后用户完成了某个新功能例如kafka trigger的实现并希望在合并前获得反馈创建 PR 之前用户准备提交 PR希望先做一次质量把关实现模式存疑时用户不确定自己的实现是否遵循了项目既有模式希望对照 main 检查模式一致性。在上述场景下调用方主会话应通过任务工具启动branch-diff-reviewer子代理让它以「冷启动」的独立上下文分析当前分支与 main 的差异并提供详细反馈。在 local-review SKILL 中这一点被明确写为规范动作subagent_type: branch-diff-reviewer并强调「审查必须在全新的上下文中运行而不是在当前会话内联执行」——因为主会话在迭代 diff 的过程中会吸收开发者的推理与合理化解释容易产生锚定效应而漏掉 CI 能发现的问题子代理像 CI 一样从零开始恰好能补上这一盲区。二、审查流程先拿 diff再逐文件分析Agent 被唤醒后的第一步是收集变更全貌流程如下# 1. 获取当前分支相对 main 的完整差异含未合并的提交 git diff main...HEAD # 2. 查看提交历史理解变更脉络 git log main..HEAD --oneline # 3. 识别所有修改、新增、删除的文件拿到 diff 之后对每一个变更文件展开三问是否符合项目既有模式检查 CLAUDE.md 及仓库根目录的 AGENTS.md 约定该文件的职责是什么、在整个代码库中扮演什么角色依赖关系如何——这些改动会不会影响系统的其他部分注意git diff main...HEAD使用三点语法three-dot它计算的是main与HEAD的共同祖先到HEAD的差异能准确反映本分支相对于 main 引入的全部变更是分支级审查的正确姿势。三、六大审查维度从 Bug 到测试全覆盖对每个显著变更Agent 必须从以下六个维度逐一评估并汇报。 Bugs Correctness正确性逻辑错误或未处理的边界情况Null/undefined 处理问题异步代码中的竞态条件race condition错误的错误处理路径类型不匹配或不安全的类型转换⚡ Performance性能低效的算法或数据结构数据库代码中的 N1 查询问题前端代码中不必要的重渲染数据库查询缺少索引异步上下文中执行阻塞操作内存泄漏或过度分配针对 Rust检查不必要的clone、低效的 serde 用法、异步中的阻塞操作针对 Svelte检查低效的响应式逻辑、循环中缺失key、过多的effect Security安全SQL 注入漏洞缺少输入校验敏感数据泄露认证/授权缺口不安全的反序列化 Code Quality Style代码质量是否遵循项目约定CLAUDE.md / AGENTS.md 准则应重构的代码重复含糊或误导性的命名缺失或不充分的文档过度复杂、可简化的逻辑死代码或未使用的 import️ Architecture Design架构设计关注点分离是否恰当是复用了既有工具还是新造轮子与既有模式的一致性错误传播是否正确API 设计问题 Testing Considerations测试考量为新功能建议测试用例识别未覆盖的边界情况指出变更是否破坏既有测试假设这六个维度与仓库根目录 REVIEW.md 的共享评审策略一脉相承REVIEW.md强调「只报告你有信心是真实存在、且由本次 PR 引入的问题」并聚焦于 bug、安全问题、性能和明确的AGENTS.md违规——与本 Agent 的维度划分互为表里。四、项目特定规则Windmill 的 Rust Svelte 5 双栈审查清单这是branch-diff-reviewer最体现项目定制性的部分。Windmill 是「Rust 后端 Svelte 5 前端」架构见 AGENTS.md因此 Agent 内置了两套专用检查清单。4.1 Rust 后端backend/ 目录SELECT语句必须显式列出列名worker 代码中严禁出现SELECT *正确使用sqlx参数化查询防止 SQL 注入错误必须使用windmill-common::error中自定义的Error枚举异步代码不得阻塞 tokio 运行时检查 serde 属性以获得最优序列化例如避免不必要的Serialize/Deserialize派生API 变更必须同步更新openapi.yaml。第 3 条在源码中有直接佐证——backend/windmill-common/src/error.rs 定义了全仓库统一的结果类型与错误枚举pub type ResultT std::result::ResultT, Error; pub type JsonResultT std::result::ResultJsonT, Error; #[derive(Debug, Error)] pub enum Error { #[error(Bad gateway: {0})] BadGateway(String), #[error(Not found: {0})] NotFound(String), #[error(Not authorized: {0})] NotAuthorized(String), #[error(Permission denied: {0})] PermissionDenied(String), #[error(Require Admin privileges for {0})] RequireAdmin(String), #[error(Bad request: {0})] BadRequest(String), #[error(Internal: {0})] InternalErr(String), // ... 共 512 行的完整枚举定义 }该枚举基于thiserror派生覆盖了数据库连接、SQL 执行、JSON 序列化、UUID 解析、IO 等常见失败类型并携带Location信息例如IoErr { error, location }便于定位。Agent 在审查中若发现新代码直接使用anyhow::Error或裸Boxdyn Error即可依据这条规则判定为违反项目约定。第 1 条同样有据可查在 backend/windmill-worker/src/duckdb_executor.rs 与 backend/windmill-worker/src/sql_utils.rs 中仍存在若干SELECT *的 SQL 文本这正是该审查规则要盯防的典型模式动态 SQL 拼接场景尤其需要显式列名以保证 schema 变更可控。4.2 Svelte 5 前端frontend/ 目录Svelte 5 文件须正确使用 Runes$state、$derived、$effect{#each}块中须有key属性事件处理器使用新语法onclick而非on:clickSvelte 5 中用 snippets 替代 slots使用$props()进行正确的 props 声明。这些规则与仓库对前端的技术选型完全一致AGENTS.md 明确要求「编写 Svelte 代码前必须先阅读svelte-frontend技能」并规定前端代码不得直接调用crypto.randomUUID()而应导入$lib/utils/uuid中的randomUUID——这些都是审查时对照项目约定的具体抓手。五、标准化的审查输出格式Agent 的输出遵循固定模板确保每份报告结构一致、可被快速消费## Summary [变更概述与整体评估] ## Critical Issues [合并前必须修复的问题] ## Recommendations [能显著提升代码质量的改进] ## Minor Suggestions [锦上添花与风格改进] ## Positive Observations ✅ [值得肯定的做得好的部分] ## File-by-File Details [按文件组织的详细反馈]针对每一个问题必须提供四项信息Location文件路径与行号Issue问题的清晰描述Impact为什么这个问题重要影响面Suggestion具体的修复方案必要时附代码示例这套「位置—问题—影响—建议」四元组结构与仓库 REVIEW.md 中「P0/P1/P2 严重度分级 明确结论行Good to merge / Mergeable but… / Should address…」的评审策略互相补充子代理负责产出细节与证据REVIEW.md负责裁决与分级二者共同构成完整的评审语言。六、行为准则与生态联动6.1 行为准则Behavioral Guidelines抓大放小全面但分优先级聚焦关键问题建设性批评每条批评都要附建议具体可执行含糊的反馈没有价值肯定优点正反馈同样重要考虑上下文理解决策背后的原因而非机械挑错意图不明时提问变更意图不清楚时主动澄清引用项目文档指出约定违规时引用 AGENTS.md、REVIEW.md 等文档原文REVIEW.md明确要求「引用AGENTS.md中确切的规则原文」。6.2 与仓库审查生态的联动该 Agent 并不是孤立的而是 Windmill「本地审查」体系的一环完整链路如下触发主会话或用户判断需要审查 → 按 local-review SKILL 用subagent_type: branch-diff-reviewer启动冷上下文子代理策略子代理先读根目录 REVIEW.md严重度分级、公共表面检查清单、测试覆盖评估再读 diff 涉及目录的AGENTS.md执行子代理产出一份符合第六节格式的报告原样转达给用户不做二次总结或过滤这正是冷启动的意义所在落地若需要主会话通过gh pr review --comment --body ...或gh api repos/{owner}/{repo}/pulls/{pr}/reviews将报告含行级 inline 评论 JSON发布到 GitHub PR 上。此外仓库的.claude/hooks/中还配置了 guard-main-branch.sh 等守卫钩子配合 Agent 在合并前把守 main 分支——「先审查、后合入」是 Windmill 开发流程的一贯原则AGENTS.md 中 Workflow 的第 4 步 Validate 也强调类型检查通过不等于验证完成必须实际运行改动路径。6.3 通用化价值虽然本 Agent 面向 Windmill 仓库定制但其方法论diff 收集 → 逐文件分析 → 六维审查 → 结构化输出完全可移植任何「Rust 后端 Svelte 前端」或类似多语言栈的团队都可以仿照.claude/agents/branch-diff-reviewer.md的结构替换项目特定规则段第四节的 Rust/Svelte 清单快速得到一套贴合自身技术栈的 AI 分支审查工具。七、小结branch-diff-reviewer是 Windmill 将 AI 深度嵌入工程流程的代表作它以只读子代理形态运行保证了审查独立性以六个维度系统覆盖正确性、性能、安全、质量、架构与测试以项目特定规则让审查真正懂 Rust 与 Svelte 5 的技术细节以结构化输出保证结论可执行、可发布。结合 REVIEW.md 的严重度分级与 local-review SKILL 的编排规范它构成了一个从「写完代码」到「合并 main」之间完整的 AI 质量闸门。【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考