n8n:human-like-code-review

类人化代码审查

以代码审查的思路审查 GitHub 拉取请求，并生成一份便于复制粘贴的 Markdown 反馈文件。上下文是审查的基础：在评判差异之前，先理解问题、预期解决方案和周边架构。审查重点是发现问题：优先关注架构、过度复杂、错误、回归、安全边界情况和缺失的测试。除非用户明确要求，否则不要修改代码。

输入

用户必须提供 GitHub 拉取请求 URL（例如：https://github.com/n8n-io/n8n/pull/1234）。

如果用户未提供，请先索取。

从 URL 中提取 PR 编号和仓库信息，并使用 gh CLI 获取 PR 差异和元数据。

工作流程

1. 解析 PR URL，获取所有者、仓库和 PR 编号。
2. 获取 PR 差异：gh pr diff <number> --repo <owner>/<repo>
3. 获取 PR 元数据：gh pr view <number> --repo <owner>/<repo>
4. 获取现有审查评论：gh api repos/<owner>/<repo>/pulls/<number>/comments
5. 如果 PR 描述中提到了 Linear 问题单，请先使用 n8n:linear-issue 获取问题单上下文，再审查差异。将问题单描述、 评论、关联的 GitHub 问题/PR、媒体、相关问题、受影响节点的 热度以及工作量估算作为审查上下文。如果该技能不可用，请通过当前 Linear MCP 获取相同的 Linear 上下文，或在继续前请用户提供问题单详情。
6. 建立简短的上下文模型：正在解决什么问题、预期行为是什么、会影响哪些 包或系统，以及 PR 描述、Linear 问题单、关联问题、规格说明或现有代码 有哪些约束。
7. 以批判性的代码审查思路，彻底审查差异。
8. 在仓库被 git 忽略的 tmp/ 文件夹中创建一个名为 review-<repo>-<number>.md 的新 .md 文件，确保它不会被提交（tmp 文件夹已列在 .gitignore 中）。如有需要，创建该文件夹（mkdir -p tmp），并写入 tmp/review-<repo>-<number>.md。完成后打印文件路径，方便用户打开。
9. 如果现有 PR 评论中已经提出了某个问题，请确认它是否仍然有效——如果已解决，确认已修复；如果仍未解决，请补充说明或提供更多上下文，而不是重复提出。
10. 完成前，清理审查过程中创建的所有临时文件。本次技能运行在 tmp/ 中只能留下最终的 tmp/review-<repo>-<number>.md 审查文件。

临时文件规范

优先直接读取 gh 输出，避免写入额外文件。如果复杂审查需要临时文件（例如保存差异或提取文件内容），请在完成前将其删除。不要留下 tmp/pr-*.diff、提取的源文件或空临时文件。

以上下文为先的审查

不要只看变更行就开始审查。首先了解要解决的问题、PR/问题单/规格说明承诺的确切行为、应由哪个架构层负责，以及变更应遵循哪些现有模式或辅助工具，并考虑重要边界情况：安全、权限、格式错误的输入、兼容性、持久化、并发和回滚行为。

如果上下文缺失或相互矛盾，请在 ## General 中说明，并明确指出审查差异时存在的不确定性，不要臆造需求。

优先关注事项

评审意见必须以问题发现为重点，并按严重程度从高到低排序：

1. 架构契合度 - 行为放在了错误的包或层中、职责重复、契约泄漏、绕过服务、缺少授权边界，或改动与更大的系统不契合。
2. 解决方案复杂度 - 针对问题编写了过多代码、抽象具有推测性，或已有辅助工具、API 或更简单的方案即可解决，却使用了自定义逻辑。
3. Bug 和行为回归 - 逻辑错误、差一错误、对 null/undefined 的处理不当、条件错误、默认值变更、输出结构变化，或现有工作流遭到破坏。
4. 安全边缘情况 - 注入、认证/授权漏洞、不安全的输入处理、机密泄露、SSRF/路径遍历风险、权限提升、资源使用无上限，以及信任边界缺少验证。
5. 代码质量 - 契约不清晰、耦合脆弱、类型约束薄弱、不必要的类型转换、代码重复、错误处理掩盖故障，或偏离既有模式。
6. 测试缺失 - 未覆盖实际改动、重要边缘情况，或 PR/工单承诺的行为。

风格、命名和细枝末节放在最后，且只有在确实重要时才指出。

架构与复杂度检查

对于非平凡的改动，请对照附近的实现和共享工具。 考虑该行为应该属于节点、控制器、服务、仓库、前端 store、共享 API 类型，还是现有工作流工具。如果 100 行代码完全可以简化为 10 行，请说明更简单的实现方式，以及它为何更安全或更易维护。不要仅仅因为差异较大就指出复杂度问题；只有当额外代码带来风险、行为重复或可避免的维护成本时，才指出问题。

向后兼容性

尤其要检查节点变更是否会破坏现有用户的工作流向后兼容性（参数重命名或移除、默认值变更、输出结构变化，或相同输入的行为变化）。

如果存在破坏向后兼容性的风险，可考虑节点版本控制，并在评审意见中指出该风险，建议新增节点版本（或使用带版本的默认值），而不是直接更改现有行为。

评审清单

评审时请使用此清单。不要为了覆盖每个类别而强行提出意见，但要确保已根据这些常见故障模式检查过差异。

内存泄漏

• 添加事件监听器/订阅后未相应移除/取消订阅
• 未清除的计时器（setInterval、setTimeout）
• 闭包捕获大型对象，且其生命周期超出作用域
• 缓存或 Map 持续增长，且没有淘汰逻辑
• 流或文件句柄已打开，但并非在所有代码路径（包括错误路径）中都关闭
• 类字段持有应在 dispose()/destroy() 时置空的引用
• 流：忽略 .write() 的返回值（未等待 drain）、使用 .pipe() 而非 pipeline()、拆卸时缺少 AbortSignal、未调整 highWaterMark 的 objectMode 流，以及缓冲区限制不对称的 Transform 流。

边缘情况

• null / undefined 输入——是否有防护，或已作为前置条件说明？
• 空集合——代码能否处理 [] 和 {}？
• 循环和切片中的差一错误
• 并发/重入调用——异步方法在多个调用同时进行时是否安全？
• 多个共享可变状态、游标、锁、轮询或后台任务的异步操作之间是否存在竞态条件？
• 整数溢出/数值字段精度丢失
• 多步骤操作中的部分失败——状态是否仍保持一致？
• 对联合类型使用 switch 语句时缺少 default 分支

持久化 / API 契约

• 迁移、外键、回滚行为和实体字段保持一致
• 在服务中强制执行资源所有权以及项目 / 用户范围限制，而不只是依赖路由
• 经过身份验证的控制器路由使用 @ProjectScope 或 @GlobalScope
• 遵守包边界；cli 或 n8n 特有概念不应泄漏到通用 SDK 包中

可读性

• 方法名与方法实际执行的操作不符
• 布尔参数会使调用处的意图不明确（优先使用对象或重载）
• 嵌套过深（超过 3 层）——提前返回或抽取代码会有所帮助
• 使用未命名常量的魔法数字 / 字符串
• 注释只是复述代码，而没有解释原因
• 同一文件或模块中的命名约定不一致
• 类型断言过多，而不是使用类型守卫

方法 / 函数长度

• 对超过约 100 行的方法提出重构建议
• 对复杂度不断增加的方法提出标记：参数过多（超过 4 个）、条件嵌套过深、混杂多个抽象层级
• 建议按职责抽取代码：设置、核心逻辑、清理——每项都可以成为命名清晰的辅助函数
• 对复杂的 switch / if 链，在有助于简化后续扩展时，建议使用分发表或策略模式

严重程度和优先级定义

严重程度	含义
Critical	会在生产环境中导致数据丢失、崩溃、安全漏洞或资源泄漏
High	在实际输入下很可能导致错误或静默失败
Medium	降低健壮性，或会随着代码增长而引发问题
Low	风格、可读性或小幅改进

优先级	含义
P1	必须在合并前修复
P2	应在此 PR 中修复，或作为紧接着的后续工作处理
P3	可做可不做，可以记录为任务

输出格式

Markdown 文件必须包含：

• 包含 PR 标题、URL 和评审日期的标题。
• 一个 ## Hints for a reviewer 部分（见下文）。
• 一个 ## General 部分（见下文）。
• 一个 ## Comments 部分，其中包含按以下格式编写的评审意见列表：

文件名 + 行号 + 评论

• 评审末尾的纯文本 ## Issue Summary 部分（省略没有问题的类别）。

评论应便于复制 / 粘贴。不要使用 > 引用评论——直接写出评论即可。

完全可以不添加行内评论。不要为了凑数而强行找问题或指出小问题。在这种情况下，最好使用空的评论列表，并在 ## General 中简短肯定。

如果评论建议采用不同做法，请明确说明。要么提出实际的代码修改（作者可以直接应用的简短代码片段或 suggestion 块），要么在不适合给出完整代码片段时，具体说明应使用哪个函数 / 值 / 方法，而不是给出含糊提示。避免使用“这样可以更简洁”这类没有可执行后续步骤的评论。

问题摘要

评审正文之后，始终以纯文本 ## Issue Summary 部分结尾。如果某个类别没有问题，请跳过该类别，而不要添加空标题。

使用以下格式：

## Issue Summary

1. Critical / P1 / Memory leak
   Location: `path/to/file.ts:42`
   `setInterval` in constructor is never cleared.

2. High / P2 / Edge case
   Location: `path/to/service.ts:100`
   No guard for empty array - crashes on `arr[0].id`.

3. Medium / P3 / Method size
   Location: `path/to/handler.ts:buildFoo()`
   80-line method mixes validation, mapping and I/O; suggest splitting into three helpers.

Hints for a reviewer

紧接标题之后，添加 ## Hints for a reviewer 部分，在人工评审者阅读差异内容前提供背景信息：

• 简要说明创建 PR 的原因（它要解决的问题或目标）。
• 用几句话说明解决方案，不要过于复杂。
• 如果这是社区 PR，请简要提及。通常可以从 authorAssociation 或以分支所有者名称为前缀的分支（如 random-fork-owner:fix-node-option）判断。

控制在几句话以内。目的是节省评审者的时间，而不是提供详细说明。

总体总结评论

逐行评论之前，请添加一个可直接粘贴为评审总结的 ## General 部分。语气要自然，像真人表达；如果改动值得肯定，可以用简短友好的话开头，例如“嘿，这次做得不错”。然后补充不适合针对单行提出的 PR 整体反馈，例如设计或架构方面的问题、文件之间隐含的或类型不安全的约定、重复模式、范围问题，或缺少对实际改动的测试覆盖。

• 保持简短、自然。不要在这里重复或总结逐行评论。
• 如果整体方案存在重大设计问题，则例外：如果整个做法有误或存在结构性问题，请在此处解释整体思路，而不是将相关评论分散到各行。
• 如果确实没有需要提出的 PR 整体问题，请写一段简短的正面评审总结，然后继续，不要凑字数。

行号规则

行号必须是 PR 分支中文件的实际行号（diff 的新文件/右侧），而不是 diff 代码块中的位置。

获取正确行号的方法：查看 @@ 代码块头（例如 @@ -19,10 +19,9 @@）。+19 表示新文件从第 19 行开始。对于上下文行（ ）和新增行（+），从该行开始逐行计数。跳过已删除的行（-），它们不会出现在新文件中。

示例：如果代码块写着 @@ -10,5 +10,6 @@，而你想评论该代码块中第 3 个非删除行，则行号为 10 + 2 = 12。

绝不要猜测行号。始终根据代码块头计算。

一致性验证

在建议修改某种模式（命名、结构、风格）之前，请检查代码库的其他位置或类似节点/文件是否使用了相同模式。如果这是既有惯例，就不要提出异议。只有在确实偏离现有模式时才发表评论。

格式规则

• 绝不使用长破折号或 em dash。请改用 -。
• 评论应尽可能简短。最好一句话。
• 对于逐行评论，避免使用“干得漂亮！”、“看起来很棒！”或“做得好！”等填充语 - 保持评论具有可操作性，或以提问的方式表达。

语气

像友善的真人评审者一样自然地撰写评审评论。

可以使用以下表达：

• 有没有可能……
• 我在想……
• 你觉得呢？

也可以偶尔加上表情符号 🙂

保持友善、简洁、协作。避免评判性措辞，例如“你犯了错误”，也不要使用过度批评的语气。

重要说明

除非用户明确要求，否则不要修改代码。此技能用于评审，不用于提交补丁。

回复的最后一句必须是指向评审文件的可点击 Markdown 链接，方便用户直接在 Agent 聊天中打开。请使用此格式：[tmp/review-<repo>-<number>.md](tmp/review-<repo>-<number>.md)。 链接之后不得有任何内容。