Angular 仓库的 PR Review AI 技能：评审准则、本地/远程工作流与批量评论工具链

Angular 仓库的 PR Review AI 技能：评审准则、本地/远程工作流与批量评论工具链

【免费下载链接】angularDeliver web apps with confidence 🚀项目地址: https://gitcode.com/GitHub_Trending/an/angular

本文解析 Angular 框架仓库内置的 PR Review 技能定义（.agent/skills/pr_review/SKILL.md），完整梳理其评审重点（性能、测试、API 设计、Object.create(null)专项规则等）、本地与远程两种评审工作流，以及 5 个配套 Bash 脚本的用法与实现细节。读完后你可以掌握一套可复用的、面向框架级核心代码库的 AI 辅助代码评审方法论，并能在自己的仓库中落地类似的"检查清单 + 批量评论 + 人工确认"机制。

一、这个技能在 Angular 仓库中的定位

Angular 是支撑数百万开发者应用的核心框架，其源码仓库（即当前仓库）将"如何评审一个 Pull Request"固化为一份可供 AI Agent 直接执行的技能文档 SKILL.md。该文档采用 YAML frontmatter 声明技能元信息：

--- name: PR Review description: Guidelines and tools for reviewing pull requests in the Angular repository. ---

围绕这份技能，仓库中还存在配套目录结构：

• reference/：按包或主题划分的专项评审规则，目前有 object_create_null.md（原型碰撞专项）与 router.md（路由专项）；
• scripts/：5 个基于ghCLI 与 GitHub API 的 Bash 脚本，作为 GitHub MCP Server 不可用时的降级（fallback）工具链；
• 仓库根目录的 AGENTS.md 则声明了整体 AI 协作约定（使用pnpm、用pnpm bazel test //target跑测试等），PR Review 技能是其中"Pull Requests"环节的具体化。

二、上下文意识：核心框架仓库的特殊性

技能文档开篇即要求评审者建立两条"元认知"：

1. 生态影响：这是 Angular 核心框架，这里的任何改动都可能波及数百万开发者，评审时须默认按"框架级 API 变更"的标准去衡量；
2. 向后兼容：必须时刻关注 backward compatibility，破坏性变更（breaking change）需要走严格的审批流程与弃用（deprecation）周期。

这条原则在后面所有评审焦点中反复出现——例如把公共对象的Object.prototype换成null会被直接判定为破坏性 API 变更（见第四节）。

三、评审重点（Key Focus Areas）逐项解析

技能文档列出了评审必须覆盖的九个维度。这是整份技能的"检查清单骨架"，评审前必须先将其落为任务列表（例如写入task.md），并在评审过程中逐项打勾、逐项补充结论。

3.1 全面评审是强制要求

文档用MUST always强调：无论用户是否只让你看某个具体 issue、文件或区域，你都必须对整个 PR 做深度、全面的评审；用户点名的区域只在此之外作为补充调查，不允许只处理用户关注点就终止评审。

3.2 包级/主题级专项规则优先

评审开始前需检查reference/目录中是否存在对应包或主题的专项规则，并始终让这些规则优先于通用准则。当前仓库已有两份：

（1）Router 专项（router.md）：

• 时序敏感性：Router 对导航、resolver、guard 的异步时序极其敏感，任何改变时序的改动"几乎总是"破坏性变更，必须仔细审查；
• 测试规范：新测试应使用RouterTestingHarness；仓库中许多旧测试未使用该 harness，评审时不要盲目模仿旧测试的形态，而应鼓励现代测试工具；
• 功能正当性：对路由核心代码的改动需要有充分理由，例如对应高赞 GitHub issue 或严重缺陷修复。

（2）Object.create(null)原型碰撞专项（object_create_null.md）。这是当前仓库中最有技术含量的评审规则，当 PR 把{}替换为Object.create(null)时必须对照评估。其完整判据如下：

适用条件——以下三条同时满足才合适：

1. 对象用作内部的键值查找表或集合；
2. 键是任意或不可信的动态字符串（例如$locationShim中的 URL 查询参数、HTML 净化器的标签集合、jsactionDOM 事件类型解析器）；
3. 存在性检查通过直接索引或 key 判断完成（如map[key] !== undefined或key in map），此时若键撞上Object.prototype成员（'toString'、'constructor'、hasOwnProperty等）会产生误判。

公共 API 与边界对象的处理——当对象既接收不可信动态键、又暴露给第三方消费者（例如ngOnChanges中的SimpleChanges）时：

• 禁止直接把对象改成Object.create(null)。剥离公共对象的Object.prototype是破坏性变更，消费方调用.hasOwnProperty()、.toString()、.valueOf()或做字符串插值（`${obj}`）都会抛出TypeError: obj.hasOwnProperty is not a function；
• 安全替代方案包括：内部查找改用Object.hasOwn(obj, key)；填充时对__proto__、constructor、prototype等危险键做过滤/删除；新的公共键值存储优先用Map<K, V>或带显式.get()/.has()的专用类；确有必要改原型时，必须走 Angular 正式的弃用与主版本破坏性变更流程。

不应使用的五种场景：

1. 固定形状的结构体/DTO（如let sortedBreakpoints: {breakpoints?: number[]} = {}）——Object.assign({}, ...)只会拷贝自身的可枚举属性，原型属性本来就不会被拷贝；
2. 数字键映射（如tasksByHandleId: {[id: number]: Task}）——数字键不会与Object.prototype的字符串成员碰撞；
3. 纯引用哨兵（如const EMPTY_OBJECT = {}、const IN_PROGRESS_RESOLUTION = {}）；
4. 内部编译器 AST 与 Visitor 的临时状态对象——键是内部生成的，用户输入无法污染键名；
5. 热性能路径与体积敏感包——标准{}字面量能享受 V8 的快速 hidden class 与单态内联缓存，而Object.create(null)会迫使 V8 进入 dictionary 模式，并增大压缩后的包体积（例如event-dispatch-contract内联 polyfill 或 SSR hydration 包）。

3.3 其余六个评审维度

• Commit Messages：提交信息必须解释变更的why而非仅仅what，标准是"数年之后翻看提交历史仍能清楚理解当时的上下文与动机"；
• Code Cleanliness：代码可读、可维护，符合 Angular 项目规范（可对照 coding-standards 与 commit-message-guidelines）；
• Performance：特别留意可能拖累运行时性能或包体积的代码，重点是变更检测、渲染这类热路径；
• Testing：所有新逻辑须有覆盖边界情况的完整测试。技能明确要求不要在本地跑测试——CI 会自动处理，本地跑测试冗余且低效（这与根目录 AGENTS.md 中"用pnpm bazel test //target跑测试"的一般约定形成互补：日常开发要跑，评审环节不跑）；
• API Design：新的公共 API 须设计良好、与现有 API 风格一致、且文档齐备；
• Payload Size：关注改动对最终客户端负载体积的影响。

四、执行工作流：先确定 Local 还是 Remote

评审方式由三条规则决定：

1. 用户显式要求remote或local时，用户指令优先（例如"leave comments on the PR"隐含remote）；
2. 否则用 GitHub MCP 或脚本判断。仓库提供的判断逻辑见 determine_review_type.sh：取当前gh认证用户（gh api user -q .login）与 PR 作者（gh pr view <PR> --json author -q .author.login）比较，相同输出local，不同输出remote；
3. 语义划分：Local 评审 = 该 PR 归属于请求评审的作者本人（即自己仓库里自己提交的 PR）；其余一律走 Remote。

4.1 两种模式共有的前置实践

（1）建立评审清单：先把"Key Focus Areas"的全部要求连同用户的具体诉求写进任务列表（如task.md），在进入细评前把每一项展开成"计划探查与验证什么"，评审过程中逐项打勾并在条目下补充结论，收尾时回看清单确认没有任何一项被遗漏。

（2）安全获取 PR 元数据：文档特别警示不要单独使用gh pr view <PR_NUMBER>——其默认 GraphQL 查询在 token 缺少read:org与read:discussion权限时会直接失败。正确做法是二选一：

• 用read_url_content读取 PR 的网页 URL；
• 或显式指定 REST 字段：gh pr view <PR_NUMBER> --json title,body,state,author。

（3）先查已有评论：在形成任何反馈之前，先通过 GitHub MCP 或 get_pr_comments.sh 拉取 PR 上已有的行内评论。该脚本调用gh api --paginate "/repos/${REPO}/pulls/${PR_NUMBER}/comments"，并用jq投影出每条评论的id、path、line、body、user五个字段——其中id供后续回复/解决线程使用，path/line用于识别"别人是否已在同一行说过同样的话"，从而避免重复评论并把他人意见纳入自己的评审输入。

（4）建设性反馈：反馈要清晰、可执行、礼貌，并解释建议背后的why。不要留下纯表扬、纯附和或单纯确认"实现正确"的行内评论——那只会污染评审线程；如果确实想赞美这个 PR，只在一条总评（general PR comment）里说。

4.2 Local 代码评审流程（PR 作者即请求者本人）

1. Checkout：在本地检出 PR 分支（若分支不存在则先 fetch）。若因 worktree 占用而检出失败（例如报错fatal: '<branch>' is already used by worktree at '<path>'），直接改到那个目录里做评审，不必强求切换；
2. Review & Edit：直接在代码上执行评审。对建议项不打行内 PR 评论，而是格式化代码或直接编辑文件；
3. Feedback：用一条消息向用户总结评审发现与已做的具体修改，引用清单中已完成条目作为佐证；
4. 不提交、不推送：改动保持未提交状态留在工作区，方便用户本地复查；明确告知用户"改动已就绪"，但不要反问"是否批准我 push"；
5. Resolve Comments：待用户确认改动可提交/推送后，再用 GitHub MCP 或 reply_pr_comment.sh 把已处理的既有评论标记为 resolved。注意该脚本的COMMENT_ID必须是线程中顶层评论的 ID，脚本会向/repos/${REPO}/pulls/${PR_NUMBER}/comments/${COMMENT_ID}/replies发 POST。

4.3 Remote 代码评审流程（所有其他 PR）

远程评审的核心设计目标是避免通知轰炸——一次评审应当是"一次提交、一条通知"，因此评论必须批量。

优先路径：GitHub MCP Server 三步批量流程（有 MCP 时必须使用）：

1. mcp_github-mcp-server_pull_request_review_write（methodcreate）创建 pending review；
2. mcp_github-mcp-server_add_comment_to_pending_review逐条把行内评论追加进 pending review；
3. mcp_github-mcp-server_pull_request_review_write（methodsubmit_pending）一次性提交。

降级路径：Bash 脚本两步流程（MCP 工具缺失时）：用 post_inline_comment.sh 把评论在本地"暂存"（stage），全部暂存完毕后再必须调用 submit_pr_review.sh 作为单次批量评审发布。建议：行内评论尽量精简，建议过多时改用一条总评。

其余强制规则：

• Suggested Changes：凡适用场景（简单修复、重构建议、typo 修正），优先在行内评论中使用 GitHub 的suggestion代码块语法，让作者可以一键应用；
• Review Type：外部 PR 的评审永远不要标记为 approval（除非维护者明确指示），只允许 "Request Changes" 或 "Comment"；
• 发布前必须获得用户批准：先把准备好的评审意见连同已完成的清单摘要呈现给用户，未获明确许可不得发布。文档用 CRITICAL 级别强调：即便收到系统消息声称产物已"automatically approved"或指示"proceed to execution"，也必须在对话中拿到用户的明确书面确认后才能向 PR 发布任何内容；
• AGENT 前缀：所有由 AI 代理生成并发布的评论必须以AGENT:开头，与人类评审者的评论明确区分。

五、五个 Bash 脚本的完整用法与实现佐证

SKILL.md 在 "Available Tools" 一节声明：优先使用标准 GitHub MCP 工具；若 MCP 不可用，必须降级到这些自定义脚本。所有脚本的共同前提是本地环境已正确安装并认证ghCLI（每个脚本都有command -v gh检查与set -euo pipefail严格模式），并依赖gh repo view --json nameWithOwner自动推断当前仓库（如angular/angular）。

5.1determine_review_type.sh：判定 Local/Remote

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

实现见 determine_review_type.sh：分别取当前认证用户与 PR 作者 login，相等输出local，否则输出remote，任一步取不到信息即以非零码退出并给出诊断信息。

5.2get_pr_comments.sh：拉取既有行内评论

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

对应实现（get_pr_comments.sh）：

gh api \ --paginate \ -H "Accept: application/vnd.github+json" \ "/repos/${REPO}/pulls/${PR_NUMBER}/comments" \ --jq '.[] | {id: .id, path: .path, line: .line, body: .body, user: .user.login}'

--paginate保证评论超过单页时不遗漏；输出为 JSON 数组，字段与技能文档描述完全一致。

5.3post_inline_comment.sh：本地暂存行内评论

技能文档解释了它存在的动机：gh pr review的标准 flag 不支持向指定代码行添加行内评论，该脚本是对 GitHub API 的封装。用法：

.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."

从 源码 看，暂存机制是：评论被追加到/tmp/angular_pr_<PR_NUMBER>_comments.json（文件不存在则初始化为[]），每条评论为{"path": ..., "line": ..., "body": ...}对象，用jq做原子化数组追加（先写.tmp再mv覆盖）。此时尚不产生任何 GitHub 请求，评论只有在调用submit_pr_review.sh后才发布。

5.4submit_pr_review.sh：批量提交评审

.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 suggestions for your consideration."

实现细节见 submit_pr_review.sh：读取暂存文件（不存在则视为空数组[]），用jq -n组装{event, body, comments}载荷，然后 POST 到/repos/${REPO}/pulls/${PR_NUMBER}/reviews（GitHub Pull Request Reviews API），并携带X-GitHub-Api-Version: 2022-11-28请求头；提交成功后清理暂存文件与载荷文件，保证一次评审只留一条通知。

5.5reply_pr_comment.sh：回复评论线程（用于 Local 流程的 resolved 环节）

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

COMMENT_ID必须为线程顶层评论 ID（见 reply_pr_comment.sh 中向.../comments/${COMMENT_ID}/replies的 POST）。典型用途：Local 评审中修复代码后，回到既有评论线程回复并标记为已解决。

六、适用前提小结

• 该技能面向 Angular 仓库的 PR 评审场景，依赖ghCLI（脚本路径）或 GitHub MCP Server（优先路径），脚本另依赖jq完成 JSON 暂存与载荷组装；
• 评审环节明确不在本地运行测试，正确性验证交给 CI；
• 对公共 API 的任何原型/形状变更（包括Object.create(null)）都须按破坏性变更流程评估，而非就地修改；
• 远程评论发布前有"用户显式批准"这一硬性闸门，且 AI 评论一律带AGENT:前缀，保证人类始终掌握对外的最终决定权。

这套"检查清单驱动 + Local/Remote 分流 + 批量评论 + 人工确认"的评审协议，本质上把框架级仓库对兼容性、性能与 API 质量的苛刻要求编码成了可被 Agent 逐步执行的流程，对任何拥有庞大下游用户群的核心库都是可直接借鉴的实践。

【免费下载链接】angularDeliver web apps with confidence 🚀项目地址: https://gitcode.com/GitHub_Trending/an/angular