pi coding-agent 的 /pr 提示词模板：基于 GitHub CLI 的结构化 Pull Request 审查工作流

pi（AI agent toolkit）仓库自身的维护者工作流中，.pi/prompts/pr.md 定义了一个名为 /pr 的项目级提示词模板：输入一个或多个 GitHub PR 链接，Agent 即按固定流程完成打标、全量阅读、关联 issue 追溯、免检出的 diff 分析，并产出「What it does / Good / Bad / Ugly / Tests / Open questions」六段式结构化审查报告。阅读本文后，你能理解 pi 提示词模板（prompt templates）的加载与参数展开机制，掌握一套可直接迁移到自有仓库的 PR 自动化审查提示词写法。

什么是 /pr：一个放在仓库里的提示词模板

pi 的 coding agent 支持「提示词模板」：把一段 Markdown 文件放进指定目录，文件名（去掉 .md）就成为编辑器中的斜杠命令，输入 /name 时该文件会被展开成完整提示词发给 Agent。完整规则见 Prompt Templates 文档。

/pr 模板就存放在仓库根目录的 .pi/prompts/pr.md，它的前置元数据（YAML frontmatter）为：

---
description: Review PRs from URLs with structured issue and code analysis
argument-hint: "<PR-URL>"
---

正文第一行是 You are given one or more GitHub PR URLs: $@，其中 $@ 是占位符，会被替换为命令调用时传入的全部参数。也就是说，在 pi 的 TUI 编辑器中输入：

/pr https://github.com/owner/repo/pull/123 https://github.com/owner/repo/pull/124

两个 URL 会依次进入提示词，模板随即按顺序驱动 Agent 执行下面的审查流程。

argument-hint 字段用于在自动补全下拉框中提示预期参数。官方文档给出的下拉框渲染效果（来自 prompt-templates.md）恰好展示了本仓库自带的一组模板：

→ pr   <PR-URL>       — Review PRs from URLs with structured issue and code analysis
  is   <issue>        — Analyze GitHub issues (bugs or feature requests)
  wr   [instructions] — Finish the current task end-to-end
  cl   — Audit changelog entries before release

其中尖括号 <PR-URL> 表示必填参数、方括号 [instructions] 表示可选参数，这是约定而非代码解析。

模板的加载与参数展开机制（源码佐证）

要理解 /pr 为什么能这样工作，需要看 pi 加载与展开模板的两处核心源码。

加载规则（以 coding-agent 包为例，prompt-templates.ts）：

• 目录扫描是非递归的，只读取 prompts/ 目录下的直接 .md 子文件；
• name 取文件名去掉 .md 后缀，content 取 frontmatter 之后的正文；
• description 优先取 frontmatter 中的 description 字段；若缺失，则回退为正文第一个非空行并截断到 60 个字符（prompt-templates.ts 中 description = firstLine.slice(0, 60) 的逻辑）。/pr 显式写了 description，因此下拉框里显示的是那句完整的英文描述；
• 项目级模板目录 .pi/prompts/ 只在项目被信任（trusted）之后才会被加载，这是安全边界：陌生仓库里的提示词模板不能在未信任前被执行。

模板加载位置（来自 prompt-templates.md）：

来源	路径
全局	~/.pi/agent/prompts/*.md
项目	.pi/prompts/*.md（仅项目受信任后）
包	包内 prompts/ 目录或 package.json 的 pi.prompts 字段
配置	settings 中 prompts 数组（文件或目录）
命令行	--prompt-template <path>（可重复）

可用 --no-prompt-templates 完全禁用发现。

参数展开由 substituteArgs 实现，支持：$1、$2 等位置参数；$@ 或 $ARGUMENTS 表示所有参数以空格连接；${1:-default} 在参数缺失或为空时回退默认值；${@:N}、${@:N:L} 做 bash 风格切片。命令行的参数串先经过 parseCommandArgs 按 bash 风格单/双引号切分，因此带引号的多词参数也是安全的。/pr 只用了最通用的 $@，所以无论传入几个 URL 都能整体落入提示词。agent 包中另有一份面向通用 harness 的等价实现 prompt-templates.ts，加载侧还会输出 parse_failed、read_failed 等诊断信息，保证单个模板损坏不影响其他模板。

/pr 的七步审查流程：逐条解读

下面是 pr.md 定义的核心流程。它本质上是用自然语言为 Agent 编写的一份带硬性约束的 SOP，每一步都针对 LLM 审查代码时常见的失误模式做了防御。

第 1 步：先打 inprogress 标签，失败也不中断

Add the `inprogress` label to the PR via GitHub CLI before analysis starts.
If adding the label fails, report that explicitly and continue.

分析开始前先用 GitHub CLI 给 PR 打上 inprogress 标签，向其他协作者宣告「此 PR 正在被审查」。注意容错语义：加标签失败时必须显式报告，然后继续分析——即外部副作用失败不应阻塞主流程，但也不能静默吞掉。这一「失败显式上报 + 继续」的模式在同目录的 is.md（issue 分析模板）中同样出现，是本仓库维护者提示词的通用写法。

第 2 步：全量阅读 PR 页面

Read the PR page in full. Include description, all comments, all commits, and all changed files.

要求覆盖四个维度：描述、全部评论、全部提交、全部变更文件。这防的是 LLM 常见的「只看 diff 摘要就下结论」问题——PR 评论里往往藏着设计意图和作者对边界的说明。

第 3 步：追溯到 PR 引用的 issue 并全量阅读

Identify any linked issues referenced in the PR body, comments, commit messages, or cross links.
Read each issue in full, including all comments.

审查不能只看代码本身，还要看代码声称要解决的问题。来源包括 PR 正文、评论、commit message 和交叉引用，每个关联 issue 都要连评论一起读完，这样后续判断「修复是否覆盖原始问题」才有依据。

第 4 步：免检出的 diff 分析（技术约束最重的一步）

Analyze the PR diff without checking out or switching to the PR branch. Use `gh pr diff`,
`gh pr view`, `gh api`, and local main-branch files; if PR file contents are needed, use
fetched refs with `git show <ref>:<path>` or temporary files. Read all relevant code files
in full with no truncation and compare against the diff. Do not fetch PR file blobs unless
a file is missing on main or the diff context is insufficient. Include related code paths
that are not in the diff but are required to validate behavior.

这一步包含多条精心设计的约束，值得逐条拆解：

• 禁止 checkout/切换分支：审查期间本地工作区保持 main 分支不动，避免污染正在进行的开发状态。这也是为什么本流程依赖 gh 远程命令而非本地 git 分支操作；
• 工具白名单：gh pr diff、gh pr view、gh api 加本地 main 分支文件。gh pr diff 给出变更上下文，本地 main 文件提供「变更前」的完整代码，两者对比即可还原改动语义；
• git show <ref>:<path> 作为兜底：当需要 PR 分支上某个文件的完整内容时（例如 diff 上下文不足以判断行为），用已 fetch 的 PR ref 按路径取文件内容，或落到临时文件，而不切换工作区；
• 按需取 blob 的阈值：只有当文件在 main 上不存在，或 diff 上下文不足时才拉取 PR 侧完整 blob——控制网络请求与上下文膨胀；
• 完整性要求：所有相关代码文件「完整阅读、不得截断」，并且必须包含 diff 之外、但验证行为所必需的关联代码路径（如被调用方、共享工具函数），防止只看变更行导致的误判。

对照同目录的 is.md 可以发现同一理念：issue 分析模板明确要求「忽略 issue 里写的根因分析，独立阅读全部相关代码文件（no truncation），自己推演代码路径」。pi 的维护者把「LLM 不可轻信已有结论」这条经验固化进了每一个提示词。

第 5 步：明确不检查 changelog

Do not check for a changelog entry. Per CONTRIBUTING.md, contributor PRs must not
edit `CHANGELOG.md` — the maintainer adds the entry when merging.

这是一条反向约束：很多通用代码审查清单都会要求检查「是否更新了 changelog」，但 pi 的 CONTRIBUTING.md 明确规定（第 69 行）：

Do not edit CHANGELOG.md. Changelog entries are added by maintainers.

贡献者 PR 不应编辑 changelog，条目由维护者合并时添加。若 /pr 不写明「不要检查」，Agent 大概率会按通用惯例把「缺少 changelog 条目」当成一条 Bad/Ugly 意见输出，产生噪音。这个细节说明：提示词不仅要写「做什么」，还要显式排除与本仓库规则冲突的默认行为。与之呼应的是同目录的 cl.md（changelog 审计模板），它专门负责在发版前核对各包 CHANGELOG.md 的 [Unreleased] 条目——changelog 职责被有意从 PR 审查中剥离到了独立流程。

第 6 步：检查文档是否需要同步修改

Check if packages/coding-agent/README.md, packages/coding-agent/docs/*.md,
packages/coding-agent/examples/**/*.md require modification. This is usually the case
when existing features have been changed, or new features have been added.

文档同步是 pi 审查关注点之一，且范围被精确限定到三个位置：

• packages/coding-agent/README.md
• packages/coding-agent/docs/ 下的全部 md 文件（如 prompt-templates.md、sessions.md 等）
• packages/coding-agent/examples/ 下的示例文档

触发条件也写清楚了：现有功能被修改、或新增了功能，通常就意味着文档要改。这等于把「文档漂移」这一最常见的开源仓库腐化信号写进了审查清单。

第 7 步：产出六段式结构化审查报告

Provide a structured review with these sections:
- What it does: one short paragraph describing the change and its intent.
- Good: solid choices or improvements.
- Bad: concrete issues, regressions, missing tests, or risks.
- Ugly: subtle or high impact problems.
- Tests: what is covered, what is missing, and whether existing tests are adequate.
- Open questions for you: only things blocking a merge decision that need the user's input.
  Omit the section entirely if there are none.

六个小节的分工非常讲究：

• What it does：一段话说明变更内容与设计意图，是后续所有判断的锚点；
• Good：明确列出值得肯定的选择——结构化「先扬后抑」，也让报告具备可信度校准；
• Bad：具体的问题、回归、缺失测试、风险，要求可指认而非泛泛而谈；
• Ugly：专门留给「隐蔽但高影响」的问题（如竞态、隐含假设、性能悬崖），与 Bad 的「显性问题」分层；
• Tests：三段式评估——覆盖了什么、缺什么、现有测试是否够用；
• Open questions for you：只收「阻塞合并决策、需要用户拍板」的问题；没有问题就整节省略，避免制造形式化噪音。

固定的输出格式

模板对每个 PR 的输出格式做了硬约束，保证多次审查、多个 PR 之间的报告结构一致、可对比：

PR: <url>
What it does:
- ...
Good:
- ...
Bad:
- ...
Ugly:
- ...
Tests:
- ...
Open questions for you:
- ...

并有一条兜底规则：如果没发现问题，必须在 Bad 和 Ugly 下明确说明「没有发现问题」（If no issues are found, say so under Bad and Ugly）。这消除了「空段落」的歧义——读者能区分「Agent 检查过且无发现」和「Agent 漏检」。

/pr 在整个维护者提示词体系中的位置

.pi/prompts/ 目录下的五个模板构成了一条维护者工作流链，/pr 处于「审查」环节：

模板	职责	与 /pr 的关系
/is	分析 GitHub issue（bug/需求），只分析不实现	与 /pr 共享「全量读代码、不轻信已有结论」的方法论
/pr	结构化审查 PR	本文主题；审查通过后进入实现/收尾
/wr	端到端收尾：changelog、提交、推送、关闭 issue	/wr 显式声明「如果工作来自 /is 或 /pr，直接复用会话中已知的 issue/PR 上下文」
/cl	发版前审计各包 changelog	承接 /pr 第 5 步剥离出去的 changelog 职责
/sa	GitHub 安全公告（advisory）更新与发布准备	独立的安全发布流程

其中 wr.md 的上下文探测规则（「If the work came from /is or /pr, assume the issue or PR context is already known from the conversation and from the analysis work already done」）从侧面印证了这套模板是按「/is 分析 → 实现 → /pr 审查 → /wr 收尾」的顺序协作设计的。

如何在自己的项目复用这套模式

pi 仓库的做法可以低成本迁移：

1. 在你的仓库新建 .pi/prompts/pr.md（或全局目录 ~/.pi/agent/prompts/pr.md），frontmatter 写明 description 与 argument-hint: "<PR-URL>"；
2. 正文用 $@ 接收多个 PR 链接，把审查流程写成编号步骤，每步一条可执行约束；
3. 关键技巧都来自 pi 的原文档，值得照搬：
   • 外部副作用（打标签）失败时「显式报告 + 继续」；
   • 工具白名单 + 免检出策略（gh pr diff / git show <ref>:<path>）保护本地工作区；
   • 用反向约束排除与你仓库规则冲突的通用审查项（pi 排除 changelog 检查，你可按自己的 CONTRIBUTING 规则调整）;
   • 固定输出骨架 + 「无问题也要显式声明」兜底，让报告可对比、无歧义。
4. 注意项目级模板只在项目被信任后加载；想禁用整个机制时用 --no-prompt-templates；prompts/ 扫描非递归，子目录模板需要通过 settings 的 prompts 数组或包清单显式声明（详见 prompt-templates.md）。

这套模板的测试与实现可进一步参考 prompt-templates 测试 与 agent 包的 harness 实现，其中覆盖了 frontmatter 解析、描述回退、诊断输出等边界行为。