pi-review的5种审查模式全解:uncommitted、base branch、commit、PR与folder快照怎么选

原创2026-11-17 23:59:511,894 阅读

pi-review的5种审查模式全解:uncommitted、base branch、commit、PR与folder快照怎么选

pi-review 是 Pi 编码智能体的一款代码审查(Code Review)扩展,通过 /review 命令提供 5 种审查模式:uncommitted 未提交变更、base branch 基线分支对比、commit 单个提交、PR 拉取请求、folder 目录快照。本文逐一拆解每种模式的适用场景与命令用法,帮你在不同开发阶段快速选对审查方式,拿到带优先级(P0~P3)和明确结论的结构化审查报告。

📋 5种审查模式一览:先看这张对比表

在深入之前,先用一张表建立整体认知(对应源码 review.ts 中的 REVIEW_PRESETS 预设列表):

模式 命令写法 审查对象 典型场景
uncommitted /review uncommitted 暂存区 + 未暂存 + 未跟踪文件 提交代码前的自查
base branch /review branch main 当前分支相对基线分支的差异 功能分支完成前的 PR 预演
commit /review commit abc123 指定提交的改动 审查某个已提交的历史变更
pull request /review pr 123 GitHub PR(本地检出后审查) 帮同事 review 线上 PR
folder /review folder src docs 指定目录/文件的当前内容 不看差异,审查整体代码质量

这 5 种目标类型在源码中被定义为 ReviewTarget 联合类型,见 review.ts。

⚡ 快速上手:3步安装并开始审查

安装 pi-review 只需一条命令:

pi install git:github.com/earendil-works/pi-review

也可以直接克隆源码仓库研究实现:

git clone https://gitcode.com/gh_mirrors/pi/pi-review

扩展的入口只有一个文件 review.ts,包信息见 package.json。安装后进入 Pi 的交互式会话,在 Git 仓库目录下输入 /review 即可启动。

🎯 /review 怎么用:交互式选择器与智能默认值

不带参数直接输入 /review,会弹出一个交互式选择器,列出 5 种预设 + 一个"自定义审查指令"入口。

更贴心的是智能默认值逻辑(见 review.ts 的 getSmartDefault 函数),它会根据 Git 状态自动预选:

  1. 有未提交变更 → 默认选 uncommitted
  2. 处于非默认的功能分支 → 默认选 base branch
  3. 其余情况 → 默认选 commit

也就是说,新手只需要输入 /review 然后回车,大多数时候就已经选对了模式。

🔍 5种审查模式逐一拆解

1️⃣ uncommitted:审查未提交变更,提交前最后一道防线

/review uncommitted

这是最高频的模式。它会审查当前所有未提交的代码改动,包括暂存区(staged)、未暂存(unstaged)和未跟踪(untracked)文件,提示词定义在 review.ts。

适合谁用:写了一段代码准备 git commit 之前,让 AI 先当一回"严苛的同事",把问题拦在提交之前。

2️⃣ base branch:对比基线分支,PR 的本地预演

/review branch main

它模拟 PR 的视角:先找到当前分支与 main(基线分支)的 merge-base 公共祖先提交,然后只审查"将要合并进基线"的那部分差异,避免把别人分支上的改动误算进来。这套逻辑见 review.ts 与 review.ts 的 getMergeBase 函数。

适合谁用:功能分支开发完毕、准备发 PR 之前。交互式模式下会列出所有本地分支供筛选(自动排除当前分支,并默认分支置顶),输入关键字还能模糊搜索。

3️⃣ commit:审查指定提交,历史变更的放大镜

/review commit abc123

直接审查某一个提交引入的改动。选择器会列出最近 20 个提交(见 review.ts 的 showCommitSelector),支持输入关键字过滤。

适合谁用:想复查某次提交是否埋了隐患,比如上周为修 bug 快速提交的那段代码,现在用 AI 重新审视一遍。

4️⃣ PR:本地检出线上 PR,远程协作审查

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

这是协作场景最强的模式:pi-review 会调用 GitHub CLI(gh)自动把 PR 检出到本地,然后按"PR 相对基线分支的合并差异"来审查,提示词见 review.ts。

两个前置条件(源码中有严格检查,见 review.ts 和 review.ts):

  • ✅ 已安装 gh 并完成 gh auth login 登录
  • ✅ 工作区干净——被跟踪文件不能有未提交改动,否则提示 Cannot checkout PR: you have uncommitted changes

适合谁用:需要 review 同事 PR 却不想打开浏览器,一条命令把 PR 拉到本地就能审。

5️⃣ folder:目录快照审查,不看差异看全貌

/review folder src docs

前 4 种模式审查的都是 diff(差异),而 folder 模式是快照审查(snapshot, not diff):直接读取指定目录/文件下的现有代码来评审(提示词见 review.ts)。路径支持空格分隔,也可每行一个。

适合谁用:接手一个陌生模块、审查核心目录的整体设计质量与技术债,或者某个目录下没有明显"改动"但你想知道整体健康度。

🏁 审查结束:/end-review 的3种收尾方式

审查开始后,界面会出现 Review session active 提示条,同时同一时间只能有一个审查会话。完成后输入 /end-review,会出现 3 个选项(见 review.ts):

选项 效果
Return only 只返回原来的会话位置
Return and summarize 返回,并生成结构化审查摘要(范围、结论、Findings、修复队列)
Return and fix findings 返回,并把"按 P0→P1→P2 顺序修复问题"的任务自动排入队列

推荐新手先选 Return and summarize:拿到的摘要可直接作为下一步修复的清单,实现"审查 → 总结 → 修复"的闭环。

🛠 进阶技巧:--extra 参数与 REVIEW_GUIDELINES.md

临时追加审查重点:任何模式都可以用 --extra 附加一次性的额外指令,参数解析逻辑见 review.ts:

/review branch main --extra "focus on performance and error handling"

项目级共享规范:如果项目根目录(与 .pi 同目录)存在 REVIEW_GUIDELINES.md,其内容会自动附加到每次审查的提示词中(加载逻辑见 review.ts)。团队可以把"安全红线、禁用 API 清单"写进去,让所有成员的审查标准保持一致。此外,在交互选择器中还能设置自定义审查指令,对全部 5 种模式生效。

🧭 怎么选?场景速查表

你的处境 推荐模式 一句话理由
写完代码准备提交 uncommitted 把问题拦在 commit 之前
功能分支做完,要发 PR 了 branch main 本地预演,先于 PR 发现问题
怀疑某次提交埋雷 commit <sha> 精准放大单个提交
要 review 同事的线上 PR pr 123 自动检出,差异即合并视角
接手陌生模块、评估技术债 folder <路径> 快照审查,看全貌而非差异

💡 判断不了?直接敲 /review 回车——智能默认值大概率已经帮你选对了。

写在最后

pi-review 的价值不只是"让 AI 读代码",而是把审查做成了有流程的工程动作:5 种模式覆盖从提交前自查到远程协作 PR 的完整链路,审查输出遵循内置的评分准则(review.ts 的 REVIEW_RUBRIC),强制给出 P0~P3 优先级、correct / needs attention 结论和面向人工的 Non-Blocking Callouts(数据库迁移、依赖变更、权限变更等)。装上它,你的每次 /review 得到的都是一份可直接执行的行动清单。

登录后查看全文
pi-review