n8n:community-pr-readiness-check

社区 PR 审查就绪度检查

给定 PR 编号或分支名称，判断它是否已准备好接受人工审查，并采取相应的后续操作。

决策树

1. 机器人作者（n8n-cat-bot / aikido-autofix）→ 仅执行清理，不进行审查。请参阅下方的“内部自动化 PR”。
2. 匹配自动拒绝筛查条件（仅修改拼写错误 / 未获批准的新节点 / 低价值）→ 操作路径 D — 关闭，并使用匹配的模板。
3. 所有检查均通过（readyForReview === true）→ 操作路径 B — 分流给团队。
4. 一项或多项检查未通过 → 操作路径 A（如果标题仅涉及小修复），然后执行 C — 发表评论。

步骤 1 — 查找 PR

如果给定的是分支名称，请先查找 PR 编号：

gh pr view <branch> --repo n8n-io/n8n --json number --jq .number

步骤 2 — 获取并预处理

gh pr view <number> --repo n8n-io/n8n \
  --json number,title,body,author,headRefName,headRefOid,files,isDraft,state,labels

内部自动化 PR（机器人作者）

如果 author.login 是 n8n 的内部机器人之一——n8n-cat-bot / app/n8n-cat-bot 或 aikido-autofix / app/aikido-autofix——请完全跳过该 PR，并执行以下清理操作。不要输出任何 JSON。

1. 重新标记 PR（两个机器人都适用）：将 community 替换为 n8n team：

   gh pr edit <number> --repo n8n-io/n8n --remove-label community --add-label "n8n team"
   

2. 更新关联的 Linear 工单（按照步骤 5 提取 GHC-XXXX）：
   • n8n-cat-bot — 取消：使用可用的 Linear MCP 工单更新工具，并设置 state: "Canceled"，不添加标签。
   • aikido-autofix — 转交给 Dev Platform：使用可用的 Linear MCP 工单更新工具，并设置 team: "Developer Platform"、state: "Triage"，不添加标签。

批量审查时，从输出中省略已跳过的 PR。单个 PR 时，输出一行说明（例如：Skipped & cleaned up #30591 (n8n-cat-bot): relabeled to n8n team, cancelled GHC-8398.）。

冲突防护

如果 PR 已带有 triage:in-progress，说明另一位审查者正在处理中——立即退出，避免重复处理。输出一行说明（例如：Skipped #30205: already has triage:in-progress），然后继续处理下一个 PR。不要运行检查，不要修改标签，也不要操作 Linear。

如果用户明确要求重新处理卡在 triage:in-progress 状态的 PR（例如，上一次运行崩溃），可以手动清除该标签后重新执行。

否则 — 标记为处理中

添加 triage:in-progress 前，移除任何现有的 triage:* 状态标签，以确保即使重新审查之前因 triage:needs-info 或 triage:tests-needed 被退回的 PR，也能满足单状态约束：

gh pr edit <number> --repo n8n-io/n8n \
  --remove-label "triage:pending" \
  --remove-label "triage:needs-info" \
  --remove-label "triage:tests-needed" \
  --remove-label "triage:complete" \
  --add-label "triage:in-progress"

实际上只会存在其中一个 triage:* 标签；标签不存在时，--remove-label 会报错，因此请将每次移除分别作为独立调用执行（或批量执行并忽略错误），然后再添加标签。PR 每次只带有一个 triage:<state> 标签；技能会在退出前将 triage:in-progress 替换为终态（参见 reference/label-flow.md）。

同时获取（并行）

# cubic-dev-ai PR review comments (for check E)
gh api --paginate "repos/n8n-io/n8n/pulls/<number>/comments" \
  --jq '.[] | select(.user.login == "cubic-dev-ai[bot]") | {body: .body, path: .path}'

# n8n-assistant issue comments (for the Linear ticket reference)
gh api --paginate "repos/n8n-io/n8n/issues/<number>/comments" \
  --jq '[.[] | select(.user.login == "n8n-assistant[bot]" or .user.login == "n8n-assistant") | .body] | join("\n")'

步骤 2.5 — 自动拒绝筛查

根据 CONTRIBUTING.md，符合以下三种模式的 PR 应直接关闭，而不是进行审查：

• 仅修改拼写错误的 PR — 差异内容完全是拼写或语法修正，不涉及逻辑或测试。
• 新增节点的 PR — 添加全新节点，除非 n8n 团队已明确同意接收。
• 低价值 / 自动化 PR — 差异内容完全是空白字符、格式或顺序调整，或是缺乏解释的大规模重命名或依赖项升级、仅修改徽章或注释，或批量脚本提交，且没有功能变更或理由。筛查时应保守判断。

如果匹配任一模式，请设置 checks.AutoReject，并直接跳转到操作 D。完整规则及各模式的验证方法请参阅 reference/checks.md。

第 3 步 — 运行就绪检查

当 AutoReject 为 null 时运行。各项检查的完整规则见 reference/checks.md：

• A. CLA — 存在 cla-signed 标签。
• B. 标题 — 符合 conventional commit 正则表达式。权威规则见 .github/pull_request_title_conventions.md。
• C. 描述 — PR 正文包含 .github/pull_request_template.md 中的每个章节标题和清单项。检查时会读取模板，因此模板更改会自动生效。
• D. 测试 — 源代码逻辑更改有对应的测试文件（fix 需要包含覆盖该错误的回归测试）。docs/ci/chore/build PR 跳过此项。
• E. cubic-dev-ai — 没有未解决的评论（已解决 = 带有 "Addressed in commit" 标记）。
• F. 关联的 issue 或论坛讨论 — fix PR 关联 GitHub issue；feat/refactor/perf PR 关联 issue 或 community.n8n.io 主题。docs/ci/chore/build/test PR 跳过此项。
• G. 规模 — files 中各文件 additions 的总和（跳过锁文件/生成文件）≤ 1000，且仅包含一个逻辑更改；设置 Oversized。

第 4 步 — 确定负责团队

针对更改文件列表运行 node .github/scripts/owners/owners.mjs，并将胜出的 GitHub 团队映射到 Linear 团队。完整映射表、子 Agent 后备流程和标签规则见 reference/teams.md。

第 5 步 — 提取 Linear 工单

n8n-assistant 会在每个社区 PR 下发表评论，其中包含 This PR has been added to our internal tracker as "GHC-XXXX"。搜索拼接后的 n8n-assistant 评论正文，查找 \bGHC-\d+\b，并取第一个匹配项。

如果不存在 n8n-assistant 评论（即自动化推出前的旧 PR），则 linearTicket 为 null。

第 5b 步 — 查找相关 issue 工单并检测重复项

PR 正文通常会写明 Fixes #NNNN / Closes #NNNN / Resolves #NNNN（或链接到 https://github.com/n8n-io/n8n/issues/NNNN）。每个此类 issue 通常都有自己的 GHC 工单（或者已分流给某个团队）。PR 引用 issue 时，该 issue 工单 即为事实来源：操作流程会将 PR 关联到该工单，并在适当时取消 PR 自身的审核工单。请在此列出相关工单和任何重复 PR，以便操作流程据此处理。

相关 issue 工单

1. 从 PR 正文中提取所有匹配 \b(?:fix(?:es)?|close[sd]?|resolve[sd]?)\s+#?(\d+)\b（不区分大小写）或匹配 github\.com/n8n-io/n8n/issues/(\d+) 的 URL 的 issue 编号。去重。
2. 对每个 issue 编号，使用可用的 Linear MCP issue 搜索工具搜索 Linear（查询 github.com/n8n-io/n8n/issues/<num>，上限 50），并筛选出 description 包含精确 URL https://github.com/n8n-io/n8n/issues/<num> 的 issue。n8n-assistant 机器人会在其创建的每个社区 issue 工单的描述中嵌入此 URL，因此匹配结果可靠。使用默认上限 50（不要使用更小的值）：query 是按 updatedAt 排序的子字符串搜索，因此 issues/<num> 也会匹配更长的 issue 编号（例如，搜索 123 会匹配 1234），准确的工单可能出现在结果集的任意位置；上限过小会导致该工单被静默漏掉。如果 50 条结果已满，请使用 cursor 翻页，直到找到准确匹配项或结果耗尽。
3. 收集匹配的工单 ID（例如 GHC-1234，或工单后来被转交至的 ID，如 NODE-5678、CAT-3338）。已取消/重复的工单也要包括在内——该链接仍有助于追溯。

将结果作为 relatedIssueTickets 写入 JSON。如果不存在 Fixes/Closes/Resolves 引用，则返回 relatedIssueTickets: []。关联操作本身位于第 7 步（见“将 PR 关联到其 issue 工单”）。

重复 PR

当 PR 引用了某个 issue 时，其他贡献者可能已经为同一个 issue 开了 PR。根据以下三种信号收集候选重复项——只要命中任意一项，操作路径就应询问是否关闭此 PR（路径 D，重复项模板）。针对每个被引用的 issue 编号运行：

# Other open PRs mentioning the same issue
gh pr list --repo n8n-io/n8n --state open \
  --search "#<num> in:body" --json number,title,author

# PRs cross-referenced / linked on the GitHub issue itself
gh api --paginate "repos/n8n-io/n8n/issues/<num>/timeline" \
  --jq '[.[] | select(.event=="cross-referenced") | .source.issue
         | select(.pull_request) | {number, title}]'

还要检查匹配到的 Linear issue 工单（来自上述搜索），查看其 links/附件中是否已附有 PR 链接。所有信号均排除正在审核的 PR，按 PR 编号去重，并将结果作为 duplicatePRs 输出到 JSON 中（若没有则为 []）。

Step 6 — 输出 JSON

{
  "readyForReview": <true if all passing checks allow merge, false otherwise>,
  "messageForUser": "<Short message to the contributor listing what they need to address. 'N/A' if ready.>",
  "team": "<Linear team name (from reference/teams.md), or 'Engineering' as fallback>",
  "linearTicket": "<GHC-XXXX or null>",
  "relatedIssueTickets": [<"GHC-1234" | "NODE-5678" | ...>],
  "duplicatePRs": [<{ "number": <int>, "title": "<string>" }, ...>],
  "checks": {
    "AutoReject": <"typo-only" | "new-node" | "low-value" | null>,
    "CLA": <bool>,
    "Title": <bool>,
    "Description": <bool>,
    "TestsNeeded": <bool>,
    "TestsIncluded": <bool>,
    "CubicIssues": <true if unresolved cubic issues exist, false otherwise>,
    "LinkedIssueOrDiscussion": <true if the §1 issue/forum link is present or the type is skipped>,
    "Oversized": <true if the filtered per-file additions sum > 1000 and the work is separable>
  }
}

只有当以下条件全部满足时，readyForReview 才为 true：AutoReject 为 null；CLA、Title、Description 和 LinkedIssueOrDiscussion 均为 true；CubicIssues 和 Oversized 均为 false；并且 TestsNeeded 为 false，或 TestsIncluded 为 true。如果设置了 AutoReject，readyForReview 始终为 false。

先输出 JSON，然后执行下方相应的操作路径。

Step 7 — 操作路径

针对每个提示询问用户（按所列选项呈现）。仅用于分析的子 Agent 应在第 6 步后停止，由调用方负责执行第 7 步。

将 PR 关联到其 issue 工单

当 relatedIssueTickets 不为空时，从 B 和 C 调用。引用的 issue 工单是信息的唯一来源；通过 Linear 的链接功能将 PR 附加到该工单。对于 relatedIssueTickets 中的每个工单，调用 Linear MCP issue-update 工具：

id    = <issue ticket>
links = [{ url: "https://github.com/n8n-io/n8n/pull/<pr>",
           title: "Community PR #<pr>" }]   # append-only — existing links are preserved

然后发布评论（使用 Linear MCP 评论工具，issueId = <issue ticket>），根据 PR 是否已准备就绪选择评论内容：

• 已就绪 + 分配（路径 B）： "关联的社区 PR # 可能会解决此 issue。"
• 尚未就绪（路径 C）： "有一个正在进行中的社区 PR（#）可能会解决此问题，但目前仍在分流处理中。"

状态和工单关闭处理因路径而异，具体说明见下方的 B 和 C。

A — 轻微标题修正

如果标题问题可通过确定性转换修正，则属于轻微问题：

• 开头或结尾有空格。
• 摘要首字母大小写错误。
• 末尾有句点。
• revert: 大小写混用，需要改为小写（无需更改，只需标记）。

如果唯一未通过的检查是 Title（或 Title + CubicIssues），且问题较轻微，则提出修正方案并询问 Apply proposed / Edit before applying / Skip`。使用以下方式应用：

gh pr edit <number> --repo n8n-io/n8n --title "<new title>"

然后重新评估 Title（此时应通过），并继续执行 B 或 C。非轻微的标题问题（类型错误或缺失、没有冒号、范围部分带连字符）需要贡献者提供意见——跳过 A，转到 C。

B — 将问题分流给团队（readyForReview === true）

先检查重复项。 如果 duplicatePRs 不为空，显示这些 PR（编号 + 标题），并询问是否将当前 PR 作为重复项关闭。选择 Yes 后，转到 D（重复项模板）。选择 No 后，继续执行下方的 B。

目标状态：NODES 为 Review，其他团队均为 Triage — 根据 PR 解析出的负责人 team 确定。标签组合：参见 reference/teams.md。

如果 relatedIssueTickets 不为空 — 以问题工单为准。 询问：“PR 已准备好进行审查。将其关联到问题工单 <relatedIssueTickets>，将这些工单移至 ，并取消 PR 自己的工单 <linearTicket>？” 选项：Yes, link and triage / No, leave as-is。选择 Yes 后：

1. 对每个相关工单运行“将 PR 关联到其问题工单”（ready 变体）。
2. 使用 Linear MCP 问题更新工具更新每个相关问题工单的状态（id = <issue ticket>，state = <destination>）— NODES 为 Review，其他团队为 Triage。
3. 取消 PR 自己的审查工单：使用 Linear MCP 问题更新工具，设置 id = linearTicket、state = "Canceled"（如果 linearTicket 为 null，则跳过）。
4. 应用 GitHub PR 标签（仅当 Linear 更新成功时），以便审查者仍能找到该 PR：

   gh pr edit <number> --repo n8n-io/n8n \
     --remove-label "triage:in-progress" \
     --remove-label "status:pending-assignment" \
     --add-label "team:<slug>" \
     --add-label "status:team-assigned" \
     --add-label "triage:complete"
   

否则（没有相关问题工单）— 使用经典流程，不变。 询问：“PR 已准备好进行审查。将 Linear 工单 <linearTicket> 分配给团队 <team> 并移至 ？” 选项：Yes, assign and triage / No, leave as-is。选择 Yes 后：

# 1. Linear — call the available Linear MCP issue-update tool with:
#      id     = linearTicket
#      team   = <team>
#      state  = <destination>
#      labels = <computed labels>
# 2. GitHub (only if Linear succeeded) — see reference/label-flow.md
gh pr edit <number> --repo n8n-io/n8n \
  --remove-label "triage:in-progress" \
  --remove-label "status:pending-assignment" \
  --add-label "team:<slug>" \
  --add-label "status:team-assigned" \
  --add-label "triage:complete"

在经典流程中，PR 自己的审查工单不会被取消 — 它仍是跟踪工单。如果 linearTicket 为 null，询问是否要在分流前创建新的 Linear 工单（适用于早于 n8n-assistant 的 PR）。否则跳过 B 并询问用户。

C — 发布贡献者评论（readyForReview === false，不自动拒绝）

如果 relatedIssueTickets 不为空，运行“将 PR 关联到其问题工单”（not-ready 变体）：添加 PR 链接，并发布“正在进行中，仍在分流”评论。保持每个问题工单的状态不变，也不要取消 PR 自己的审查工单 — PR 尚未准备就绪，因此我们只标记正在进行的工作。（可选：向用户显示 duplicatePRs，但不要在此处关闭 — 关闭属于由 B 触发的 D 路径操作。）

messageForUser 应列出贡献者必须处理的每一项未通过检查，包括缺少关联问题 / 论坛主题（检查 F — 对于 fix，请他们新建或关联 GitHub issue；对于 feat / refactor，请他们新建 community.n8n.io 主题）以及PR 规模过大（检查 G — 如果工作可以拆分，请他们拆分为多个目标明确的 PR）。

显示 messageForUser 并询问 Post as-is / Edit before posting / Skip。发布时：

gh pr comment <number> --repo n8n-io/n8n --body "<final message>"

然后应用正确的终态分流标签 — 恰好一个，优先级为 triage:tests-needed > triage:needs-info（缺少关联问题 / 论坛主题或 PR 规模过大时，使用 triage:needs-info）。参见 reference/label-flow.md。选择 Skip 后，将 PR 保留在 triage:in-progress，以便下一轮处理。

如果 A 已处理唯一未通过的检查且 PR 现在已准备就绪，则完全跳过 C — 改为运行 B。

D — 关闭 PR

当 PR 应关闭而不是审查时使用。常见的三种触发情况：

1. 自动拒绝（已设置 AutoReject）——仅修正拼写、未经批准的新节点，或价值较低／自动生成的内容。
2. 重复——duplicatePRs 非空（另一个未关闭的 PR 已涉及相同更改），并已通过路径 B 中的重复项检查确认。在模板中使用 duplicatePRs 中的 #<other-pr>。
3. 超出范围／打包提交——包含多个互不相关、应该拆分的修复，或 n8n 团队已决定不纳入范围。

询问「关闭并评论 / 关闭前编辑 / 跳过」。以下是模板；选择一个，并根据贡献者和具体情况进行调整。

仅修正拼写：

感谢你抽出时间提交这个 PR！根据我们的贡献指南，我们不接受仅修正拼写的 PR——这会增加审查负担，却不会改变功能，而且我们的拼写检查规则会自动覆盖大多数情况。暂时关闭此 PR；欢迎提交一个将拼写修正与相关逻辑更改相结合的 PR。🙏

新节点：

感谢贡献！除非团队已明确同意将新节点纳入范围，否则 n8n 不再接受直接合并到核心单体仓库的新节点。请改为将其发布为社区节点——这样你可以完全掌控它，也能避免在这里长时间排队等待审查。根据我们的贡献指南，关闭此 PR。

价值较低／自动生成：

感谢你抽出时间提交这个 PR！我们会手动审查每个 PR，因此根据我们的贡献指南，我们只接受具有明确功能价值的更改。此更改不会改变行为（或者没有提供我们可以据以采取行动的理由），因此我们将关闭它，以便集中处理审查队列。如果背后确实有需要修复或改进的问题，请先开一个 issue 或论坛主题描述问题，我们很乐意查看。🙏

与另一个 PR 重复：

感谢贡献！这项更改已在 # 中处理，该 PR 的审查进展更快。为保持队列整洁，我们将关闭此 PR，优先处理那个 PR；如果有任何遗漏，欢迎到那里补充。

打包提交／超出范围：

感谢贡献！根据我们的贡献指南，每个 PR 应只包含一项明确的更改。此 PR 打包了 项互不相关的修复——请将它们拆分为单独、聚焦的 PR，每个 PR 都填写模板，并添加一个能锁定回归问题的单元测试。在此期间，我们将关闭此 PR。🙏

关闭操作（所有原因均相同）：

gh pr comment <number> --repo n8n-io/n8n --body "<final message>"
gh pr close <number> --repo n8n-io/n8n
gh pr edit <number> --repo n8n-io/n8n \
  --remove-label "triage:in-progress" \
  --remove-label "status:pending-assignment" \
  --add-label "status:internal-closed" \
  --add-label "triage:complete"

如果已设置 linearTicket，还需使用可用的 Linear MCP issue-update 工具取消它（id=linearTicket，state="Canceled"）。如果 gh pr close 报告 PR 已关闭（贡献者抢先关闭），仍需继续执行评论、添加标签和取消工单。

备注

• 草稿 PR——报告所有发现，但注明该 PR 是草稿。
• 已合并或已关闭——说明这一点并跳过检查（不要应用分流标签）。
• 重新审查此前已经评论过的 PR——使用 GitHub Timeline API 检测自上次技能触达以来贡献者是否有新活动。参见 reference/re-review.md。
• 标签状态机——任意时刻只保留一个 triage:<state> 标签；状态转换见 reference/label-flow.md。