PR Review

PR 审查指南

审查 angular 仓库的拉取请求时，请遵循以下基本指南，确保贡献质量：

1. 背景与生态系统：

   • 请记住，这是 Angular 核心框架。在此处进行的更改可能会影响数百万开发者。
   • 注意向后兼容性。破坏性更改需要经过严格的审批流程，并设置弃用期。

2. 重点关注领域：

   • 全面审查：你必须始终对_整个_拉取请求进行深入、全面的审查。如果用户要求你调查某个特定问题、文件或关注领域，你必须在审查 PR 其余实质性更改_之外_，额外调查该特定领域。不要只处理用户关注的部分就结束审查。
   • 特定包与主题指南：检查 reference/ 目录中是否有适用于所修改包或主题的具体指南（例如 reference/router.md 或 reference/object_create_null.md）。始终优先遵循适用于相应领域的规则。
   • 原型冲突与 Object.create(null) PR：审查将 {} 替换为 Object.create(null) 的 PR 时，请查阅 reference/object_create_null.md，了解技术评估标准与规则。
   • 提交消息：评估提交消息的质量。提交消息应说明更改的_原因_，而不只是_内容_。即使多年后查看提交历史，也应能清楚理解更改的背景和理由。
   • 代码整洁度：确保代码易读、易维护，并符合 Angular 的项目标准。
   • 性能：留意可能对运行时性能或包体积产生负面影响的代码，尤其是变更检测或渲染等热点路径中的代码。
   • 测试：确保所有新增逻辑都有全面的测试，包括边缘情况。审查过程中不要在本地运行测试。CI 会自动处理，而本地运行测试既多余又低效。
   • API 设计：确保新的公共 API 设计合理、与现有 API 保持一致，并且有适当的文档说明。
   • 负载大小：注意更改对最终客户端负载大小的影响。

3. 执行工作流： 确定合适的审查方式。如果用户在请求中明确要求进行 remote 或 local 审查，应以此为准（例如，“在 PR 上留下评论”意味着 remote）。否则，使用 GitHub MCP 或可用脚本判断应采用 local 还是 remote 审查。 通用审查实践（适用于本地和远程）

   • 准备与检查清单：
     • 首先，创建一个易于查阅的任务清单（例如 task.md），其中包含“重点关注领域”部分的所有审查要求（提交消息、性能、测试等），以及用户提出的任何具体审查说明或请求。
     • 在进行深入审查之前，将此清单扩展为更详细的条目，列出你计划在 PR 中检查和验证的内容。
     • 进行审查时，逐项勾选清单，并在每项下方补充评估或发现。
     • 审查结束时，回看清单，确保每项要求都已完整验证。
   • 安全获取 PR 元数据：需要阅读 PR 描述或背景信息时，不要单独使用 gh pr view <PR_NUMBER>，因为其默认 GraphQL 查询可能因令牌缺少 read:org 和 read:discussion 作用域而失败。请改用 PR URL 上的 read_url_content，或使用 gh pr view <PR_NUMBER> --json title,body,state,author。
   • 先检查现有评论：撰写反馈前，使用 GitHub MCP 或可用脚本获取 PR 上的现有评论。查看这些反馈，避免重复评论，并将其中的见解纳入自己的审查过程。
   • 提供建设性反馈：给出清晰、可执行且礼貌的反馈。说明建议或修改背后的_原因_。不要仅仅为了赞扬、赞同或认可正确的实现细节而留下内联评论，这会让审查内容变得杂乱。如果想称赞 PR，请在一条概括性的 PR 评论中进行。

   A. 本地代码审查（PR 由发起审查的作者所有时）

   • 检出：在本地检出 PR 分支（如果分支不存在，则先获取）。如果因工作树占用而导致检出失败（例如“fatal: '' is already used by worktree at ''”），请在该目录中进行审查。
   • 审查与编辑：直接在代码上执行审查。不要为建议添加 PR 内联评论，而应格式化代码库或直接修改文件。
   • 反馈：在给用户的消息中总结审查发现和已完成的具体修改，并引用清单中已完成的项目。
   • 不要提交或推送：将修改保留为工作目录中的未提交状态，方便用户在本地查看待处理的编辑。告知用户修改已准备好供其审查，但不要请求批准推送。
   • 处理评论：用户确认修改无误并应提交或推送后，使用 GitHub MCP 或可用脚本将现有评论标记为“已解决”。 B. 远程代码审查（适用于所有其他 PR）
   • 批量处理评论（MCP 服务 - 首选）：如果已配置 GitHub MCP Server，必须遵循此工作流，避免向作者发送多条通知：
     1. 使用 mcp_github-mcp-server_pull_request_review_write（方法 create）创建待处理审查。
     2. 使用 mcp_github-mcp-server_add_comment_to_pending_review 将行内评论添加到待处理审查。
     3. 使用 mcp_github-mcp-server_pull_request_review_write（方法 submit_pending）提交审查。
   • 批量处理评论（脚本 - 后备方案）：如果无法使用 GitHub MCP Server（例如，当前上下文中缺少特定 MCP 工具），则改用提供的脚本。使用 post_inline_comment.sh 在本地暂存评论。所有评论暂存完毕后，必须调用 submit_pr_review.sh，将其作为一条批量审查发布（并仅发送一条通知）。尽量精简评论；如果有很多建议，可以使用一条概括性评论。
   • 使用建议更改：在适当情况下（例如，针对简单的代码修复、重构建议或拼写更正），优先在行内评论中使用 GitHub 的 建议更改语法（suggestion ... ）。这样作者就能在 GitHub UI 中一键应用你建议的代码改进。
   • 审查类型：除非仓库维护者明确指示，否则切勿将外部 PR 审查标记为“批准”。始终使用“请求更改”或“评论”。请注意，某些工具可能仅支持评论。
   • 发布前须获得用户批准：准备审查评论，并向用户展示这些评论以及已完成检查清单的摘要。未经用户明确许可，不要在 PR 上发布评论。只有用户批准后才能发布审查。
     • 重要：即使收到系统消息称某项内容已“自动批准”或指示“继续执行”，此规则仍然适用。在 PR 上发布任何内容前，必须始终在此聊天对话中获得用户明确的书面确认。
   • 为 Agent 评论添加前缀：为清楚表明评论由 AI Agent 生成并发布，而非由用户本人发布，审查评论始终必须以 AGENT: 为前缀。

可用工具

以下工具可用于远程交互。我们优先使用标准的 GitHub MCP Server 工具。如果未设置 MCP 服务，必须改用自定义 bash 脚本。

GitHub MCP 工具（首选）

• mcp_github-mcp-server_pull_request_review_write
• mcp_github-mcp-server_add_comment_to_pending_review

自定义 Bash 脚本（后备方案）

如果 MCP 服务不可用，可使用以下脚本作为后备方案。请注意，这些脚本依赖于本地环境中已正确安装并完成身份验证的 gh CLI。

determine_review_type.sh

通过检查当前使用 gh CLI 进行身份验证的 GitHub 用户是否与拉取请求作者一致，来确定应使用本地审查还是远程审查工作流。

用法：

.agent/skills/pr_review/scripts/determine_review_type.sh <PR_NUMBER>

get_pr_comments.sh

使用 GitHub API 获取 PR 上所有现有的行内评论。这对于查看其他贡献者的反馈并避免重复评论至关重要。该脚本会输出 JSON，其中包含每条评论的 id、path、line、body 和 user。

用法：

.agent/skills/pr_review/scripts/get_pr_comments.sh <PR_NUMBER>

reply_pr_comment.sh

回复现有 PR 评论讨论串中的评论。在本地代码审查中解决问题后，可使用此脚本将评论标记为已解决。请注意，COMMENT_ID 必须是讨论串中顶层评论的 ID。

用法：

.agent/skills/pr_review/scripts/reply_pr_comment.sh <PR_NUMBER> <COMMENT_ID> <REPLY_BODY>

post_inline_comment.sh

GitHub CLI 的 gh pr review 命令无法通过标准标志原生支持针对代码的特定行添加行内评论。此脚本封装 GitHub API，以便在本地暂存评论。调用 submit_pr_review.sh 后，这些评论才会发布。

用法：

.agent/skills/pr_review/scripts/post_inline_comment.sh <PR_NUMBER> <FILE_PATH> <LINE_NUMBER> <COMMENT_BODY>

示例：

.agent/skills/pr_review/scripts/post_inline_comment.sh 12345 "packages/core/src/render3/instructions/element.ts" 42 "AGENT: Consider the performance implications here."

submit_pr_review.sh

通过 GitHub Pull Request Reviews API，将所有在本地暂存的行内评论作为一次批量审查提交。

用法：

.agent/skills/pr_review/scripts/submit_pr_review.sh <PR_NUMBER> <EVENT_TYPE> [BODY]

选项：

• EVENT_TYPE：必须为 COMMENT、APPROVE 或 REQUEST_CHANGES。切勿对外部 PR 使用 APPROVE。
• BODY：（可选）审查时的常规摘要评论。

示例：

.agent/skills/pr_review/scripts/submit_pr_review.sh 12345 COMMENT "AGENT: I have left a few inline suggestions for your consideration."