pi-review的5种审查模式全解:uncommitted、base branch、commit、PR与folder快照怎么选
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 状态自动预选:
- 有未提交变更 → 默认选
uncommitted - 处于非默认的功能分支 → 默认选
base branch - 其余情况 → 默认选
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 得到的都是一份可直接执行的行动清单。