企业官网建设流程全解析

Mastra 项目中的 understand-pr 技能：基于 gh CLI 的引导式 PR 审查方法论

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

导读

understand-pr是 Mastra 仓库（.mastracode/skills/understand-pr/SKILL.md）中定义的一项 AI 编码辅助技能，它把一次 PR 审查组织为从"目标认知"到"质量门禁"再到"历史考古"最后到"意见形成"的七阶段引导式流程。本文以该技能文档为主体，结合仓库中实际配套的 changeset 配置、废弃命令与姊妹技能，完整还原这套基于ghCLI 的 PR 理解方法论，并给出每条命令的用途、参数与执行顺序，让读者能直接复刻到自己的开源项目协作流程中。

understand-pr 是什么：先理解，再评论

该技能在 frontmatter 中自我定位为："Guided interactive PR review — understand the history and context before forming opinions"（引导式交互式 PR 审查——在形成观点之前先理解历史与上下文）。它面向的是仓库维护者，核心主张是：审查者在形成观点、起草评论之前，必须真正理解这个 PR 要做什么、为什么存在、以及它建立在怎样的历史之上。

这一点在 critique-pr 命令 的弃用说明中得到了印证——该命令被标记为 "Deprecated — activate the understand-pr skill instead"，理由是旧命令"鼓励把批判性思维外包给代理，而没有真正理解 PR、受影响的代码区域、架构或历史"。understand-pr 取代它的方式是让 PR 审查变得"协作式与考古式"（collaborative and archaeological）：先建立深层历史上下文，追踪架构，再与审查者一起基于证据形成观点，而不是对着 diff 表面读一遍就生成评论。

从文件组织看，understand-pr 与 understand-issue 是一对姊妹技能：前者处理"理解一个 PR 的变更"，后者处理"理解一个 Issue 的根因"，二者共享同一套gh交互式调查范式。

Setup：运行前的前置约定

技能规定了启动前的五步准备，每一步都对应明确的 CLI 命令：

1. 解析入参：从$ARGUMENTS中解析 PR 编号和可选的--working-file <path>。
2. 处理 working-file：如果传入了--working-file，先验证文件存在并读取它，把它视为调用方提供的上下文，按其交接指令执行，并把调查发现回写到同一文件；该文件不被视为最终面向用户的输出。如果文件不存在而参数被传入，直接告知用户并结束。
3. 校验分支：确认当前检出的分支与 PR 的 head 分支一致。
4. 拉取 PR 元数据：gh pr view --json title,body,commits,files,labels,number,headRefName,author
5. 拉取完整 diff：gh pr diff
6. 识别当前用户：gh api user --jq .login
7. 红线规则：未经明确批准，绝不发布任何评论。

技能文档特别提醒了一个容易踩坑的 Shell 细节：gh输出经常包含会破坏jq解析的 ANSI 颜色码，因此应优先使用gh内建的--jq标志而不是管道给jq，或者给命令加上NO_COLOR=1前缀。这也是整个技能中所有查询命令反复使用--jq的原因。

People：识别参与人及其上下文深度

在开始分析前，先弄清楚有哪些人牵涉其中：

• PR 作者：是维护者、常规贡献者，还是首次提交的社区贡献者？用gh api repos/{owner}/{repo}/collaborators/{author} --silent判断（404 表示不是 collaborator）。
• 当前审查者（即运行此命令的用户）：你是 PR 作者本人（自审）还是其他人。
• 关联 Issue 的作者：如果 PR 引用了 Issue，这些 Issue 是谁开的？是与 PR 作者同一人，还是别人报告问题、PR 声称修复？

对每个被识别的人，统计其在该仓库的合并 PR 数：gh pr list --author <login> --state merged --limit 100 --json number --jq length。对关联 Issue 的作者，额外统计其 Issue 数：gh issue list --author <login> --state all --limit 100 --json number --jq length。这一步的价值在于评估每个人的上下文深度——首次贡献者需要的审查关注度，与有 50+ 合并 PR 的常客完全不同；高产 Issue 报告者的 bug 报告权重也不同于首次报障者。

Linked Issues：阅读关联 Issue

如果 PR 描述或提交引用了 Issue（例如 "fixes #1234"、"closes #456" 或仅仅 "##789"），立即读取它们：

• gh issue view <number> --json title,body,labels,comments,author,state

理解最初报告了什么、由谁报告、预期的修复形态是什么，并检查 Issue 讨论中是否包含 PR 描述未提及的上下文。技能强调：这是理解 PR Goal 的关键上下文——关联 Issue 往往比 PR 描述本身更能解释"这个 PR 为什么存在"。

Phase 1: PR Goal——先对齐"要做什么"

在讲历史和质量之前，必须先让用户知道这个 PR 试图做什么。该阶段要求给出凝练的目标摘要：解决什么问题、为什么存在、预期产出是什么，并且必须落实在 PR 描述、提交消息和关联 Issue 上——"fixes a bug" 这种表述不够具体。

技能特别要求：如果 PR 改变了任何公共 API、导出的接口、CLI 命令、配置项或面向用户的行为，要展示从用户视角看的前后对比。例如开发者代码会如何变化、有哪些新选项可用、导入方式有何不同——不要只描述内部实现，要展示对使用者的影响。

然后暂停，给出字母选项让用户确认：

A) That matches my understanding — continue B) I think the goal is actually different — let me explain C) I'm not sure what this PR is solving — dig deeper

只有用户确认理解了 PR 目的后，才进入质量门禁。

Phase 2: Quality Gate——最低质量门槛

在投入历史研究前，先用gh pr checks检查 CI 状态，然后评估是否达到最低门槛：

• CI 是否通过（构建、类型检查、测试）；若 CI 仍在运行，注明并按带保留意见继续。
• 是否新增或修改了测试，从表面看是否有意义（深度分析留到 Phase 3）。
• diff 是否聚焦——是聚焦的变更，还是混入无关改动的 WIP 垃圾堆。
• Changeset 检查：如果仓库使用 changesets（查看是否存在.changeset/目录），任何改变运行时行为、修复 bug 或新增特性的 PR 都必须附带 changeset。缺失 changeset 属于质量门禁失败，必须明确标出。
• 是否满足其他仓库要求（文档更新、AGENTS.md 更新等）。
• 作者验证：PR 作者是否声明过亲自验证变更可用？查找类似 "tested locally"、"verified this fixes…"、复现证据、截图或测试输出的表述。如果描述和评论中完全没有任何作者实际运行或测试过变更的迹象，就要标记出来——若用户选择起草评论（Phase 7），这应作为提问提出。
• 明显的红旗：损坏的模式、被移除的安全检查、巨大的无关 diff。

若未达标，直接告知用户：

This PR isn't ready for detailed review yet: - [specific reasons] A) Review it anyway — I want to understand what's here B) Help me draft feedback to the author about what needs fixing C) Stop here

仓库中的 changeset 实践

Mastra 仓库确实在根目录维护了.changeset/目录，.changeset/config.json 配置了baseBranch: "main"、access: "public"、通过fixed字段将@mastra/core、@mastra/server、@mastra/deployer等包绑定在一起同步发版，并用ignore白名单只对mastra、create-mastra、create-factory、mastracode、@mastra/*等公开包生成变更记录。仓库中现存大量如all-bats-joke.md、cloudflare-sandbox-shell-command.md之类的 changeset 文件，说明"每个影响行为的 PR 都必须附带 changeset"在该仓库是真实执行的硬约束。

配套的 pr 命令 提供了创建 changeset 的标准做法：

pnpm changeset -s -m "your changeset message" (--major | --minor | --patch) pkg-name

其中-s/--skipPrompt用于非交互式运行、-m指定消息，--major/--minor/--patch分别对应破坏性变更、向后兼容的新特性、向后兼容的 bug 修复。该命令还强调了一个反模式警示：一个 changeset 文件里塞进多个包会导致多个包的 changelog 出现巨大条目，应当为逻辑分组分别创建 changeset。这与 understand-pr 质量门禁中"检查 changeset 是否存在"的规则构成了完整的闭环——先由 AI 在审查时发现缺失，再由配套命令补齐。

Phase 3: History & Context——历史考古

通过质量门禁后，进入最核心的历史挖掘阶段，目标是理解"我们如何走到这一步、当前方案是否合理"。

Git 历史

对 PR 中修改的每个文件：

1. git log --oneline -20 -- <file>——查看最近的提交历史
2. git log --oneline --all -20 -- <file>——捕捉跨分支的活动
3. 在具体变更区域（PR 之前的版本状态）上使用git blame，弄清当前代码是谁、何时写的
4. 追踪相关变更——若 PR 触及某个函数，追踪其调用方，并检查它们最近是否也有变更
5. 查看提交消息中关联的 Issue 或引用的 PR

架构与周边代码

阅读变更区域周边的代码，而不只是变更行本身，需要理解：

• 模块/包的架构，以及变更代码在其中的位置
• 与变更代码交互或依赖它的周边功能
• 变更代码参与的接口、类型与契约
• 数据在该代码区域中的流动方式
• 变更包中相关的 AGENTS.md、README 或文档文件

测试

• PR 是否新增或修改了测试？仔细阅读。
• 测试是否真正验证了声称的行为，还是仅执行了代码路径而没有有意义的断言？
• 对照代码库中相似功能的测试模式——PR 是否遵循了这些模式，还是更弱？
• 测试是否覆盖了边界情况和失败模式？
• 如果 PR 没有测试，是否应该加？

Approach：方案是否自洽

综合历史与既定目标，判断方案是否合理：是在用正确的方式解决问题，还是在与既有设计对抗？如果结合代码库历史存在更简单、更一致的方案，要指出来。

产出理解产物

如果提供了 working file，把学到的东西和交接指令要求的输出写回同一文件；否则在工作区根目录写.artifacts/understand-pr/HISTORY.md，记录：

• 每个变更文件/模块为什么存在、最初解决什么问题
• 它如何演化、塑造当前状态的关键提交
• 近期活跃度——该区域是在被积极开发还是长期休眠
• 变更代码如何融入更广阔的架构
• 可能受影响的周边功能与依赖
• 历史与代码库确立的模式或约定
• 测试质量评估——测试是否有意义
• 方案评估——PR 方案是否契合既有设计

随后逐个文件/逻辑区域交互式呈现历史，每次呈现后提供定制化的跟进选项：

A) Why was [specific thing] added originally? B) Who else has changed this recently? C) Show me the related code that depends on this D) I understand this part — move on

选项必须针对实际内容定制，禁止使用通用占位选项。直到用户看完全部主要变更区域的历史并表示就绪，才进入 Phase 4。

Phase 4: Walkthrough——逐块走读 diff

带着 Phase 3 的历史上下文，逐块走读 PR diff。对每一块：

• 展示改了什么（保持简短——用户自己能读 diff）
• 结合刚讲过的历史解释为什么重要
• 标记任何与既有模式矛盾、有风险或引发疑问的地方
• 提供跟进选项

A) What breaks if this change is wrong? B) Are there tests covering this path? C) Show me the surrounding code D) Next change

同样要求选项量身定制。保持怀疑态度：可疑之处直接说出来，扎实之处不浪费笔墨夸奖。对于改动文件很多的大 PR，按逻辑区域分组，让用户选择先探索哪个区域，而不是按字母序逐个文件过。

Phase 5: Understanding Check——理解校验

走读完成后，提供三个选择：

We've been through all the changes. Want to: A) Quick quiz to test your understanding B) Revisit a specific area C) I understand — let's move to opinions

若用户选择测验，出 3-5 道关于该 PR 的多选题——代码做什么、为何做这些决策、风险是什么。技能强调这些必须是真正检验理解的题，不是送分题；答错时要清楚解释并提议重访该区域。

Phase 6: Opinion Exchange——先听后说

在用户充分理解 PR 之后，先征求用户的意见：

I've formed my own opinion on this PR, but I'd like to hear yours first. What do you think — is this ready to merge? Any concerns?

等待用户回应，然后坦诚分享自己的意见，同意处同意、不同意处不同意，不要为了迎合而软化立场。要点出：

• 合并前应修复的事项
• 风险与未知
• 缺失的测试、文档、changeset 或其他仓库要求
• 值得肯定的地方（简要）

Phase 7: Review Comment——按需起草与发布评论

如果传入了--working-file，默认不提供 PR 评论，而是把 Review 结论写入 working file 后交还调用方处理生命周期输出。否则，在意见交换后询问是否起草评论：

Want me to draft a review comment? Options: A) Draft a full review comment B) Draft a short approval/comment C) No comment needed

起草后全文展示，并提供迭代选项（按原样发布 / 缩短 / 更详细 / 调整语气 / 编辑特定部分 / 不发布），反复迭代直到用户满意或决定不发布。未经用户明确要求绝不发布。

发布：走 REST API 避开 GraphQL 限流

技能明确建议用 REST API 发布评论以避开 GraphQL 的速率限制，并给出了完整的 Bash 片段：

cat > /tmp/pr-comment.md <<'EOF' Comment body here. EOF body=$(jq -Rs . /tmp/pr-comment.md) gh api repos/:owner/:repo/issues/<PR_NUMBER>/comments \ -X POST \ -H 'Content-Type: application/json' \ --input - <<EOF {"body":$body} EOF

发错内容时用 PATCH 修正（关键细节：把文件内容作为请求体传递，而不是把@file当作字面量 body）：

body=$(jq -Rs . /tmp/pr-comment.md) gh api repos/:owner/:repo/issues/comments/<COMMENT_ID> \ -X PATCH \ -H 'Content-Type: application/json' \ --input - <<EOF {"body":$body} EOF

遇到速率限制错误时，用gh api rate_limit --jq '.rate'检查 REST 配额。

贯穿全程的交互设计原则

understand-pr 技能文档通篇贯彻一套强约束的交互协议，这也是它与传统"一次性输出长评论"式审查工具的本质区别：

• 不产生文字墙（walls of text）：每条回复都要短、密、信息密度高。
• 一律以字母选项收尾：A/B/C/D，用户只需敲一个字母即可继续，把多轮会话的摩擦降到最低。
• 最小化废话，直接且信息密集：每个阶段都以"停下来确认"收束，确保人与代理在认知上同步，而不是让代理自顾自输出结论。
• 用户驱动：用户选择探索哪些区域、何时认为自己理解够了，代理不强行推进固定序列。

与仓库中相关命令和技能的关系

understand-pr 不是孤立存在的，Mastra 仓库的 .mastracode 目录是一个完整的 AI 辅助开发工作流体系：

• critique-pr 命令：被 understand-pr 取代的旧命令，弃用说明精确记录了这次演进的设计动机。
• understand-issue 技能：面向 Issue 调查的姊妹技能，同样包含 People 识别、Phase 化流程、working-file 机制，以及"绝不未授权发帖"的硬规则。
• selfreview 命令：面向作者自己的批判性自审（Must fix / Risks / Suggested improvements 三段式输出），与 understand-pr 形成"自审 + 他审"的互补。
• gh-pr-comments 命令：处理 PR 评论回复的配套命令，规定了与 @coderabbitai 机器人评论交互的方式。
• pr 命令：补全 changeset 创建与 PR 提交流程。

这些文件共同说明：understand-pr 是 Mastra 项目自带的、被设计为"取代粗暴评论生成器"的协作式审查标准流程，它的价值不止于单次审查，而在于让审查者（无论人还是代理）在形成意见前，真正走完"目标对齐 → 质量门禁 → 历史考古 → 逐块走读 → 理解校验 → 意见交换"的完整认知链路。对于任何在开源项目中使用ghCLI 进行代码评审的团队，这套方法论都可以直接迁移复用。

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra