没有 PR 也能审:pulls.review 粘贴与上传 Diff 的轻量审查用法指南
没有 PR 也能审:pulls.review 粘贴与上传 Diff 的轻量审查用法指南
pulls.review 是一款把 GitHub Pull Request 审查做得更简单的开源工具,除了打开 PR 链接之外,它还支持一种更轻量的用法:粘贴 Diff 或上传 .diff / .patch 文件即可审查,无需创建 PR、无需配置仓库。本文带你 3 种方式快速上手,并解释背后从粘贴文本到分组展示的完整流程。
什么场景适合"没有 PR 也审"?
传统的 diff 查看体验(网页端 PR 页面、终端 git diff)在面对大改动时常常信息过载。而 pulls.review 的粘贴 / 上传模式,特别适合这几类场景:
- 📋 拿到一段 patch 就想看:同事邮件里发来的
.patch、CI 生成的补丁、代码片段合集 - 🚫 改动还没有提 PR:本地
git diff输出后先自查一遍,比提交后别人来审更从容 - 🔍 临时评估某次改动:不想 clone 仓库,只想快速看清"到底改了哪些文件、改了什么"
- 🧩 跨仓库/跨平台审查:diff 本身就是文本,从哪来都能审
它的入口文案说得直白:"Review a diff without a PR"(审阅一个没有 PR 的 diff)。首页下方的上传卡片描述为:上传或粘贴 unified diff,或把一个 .diff / .patch 文件拖到页面的任意位置。
方式一:粘贴 unified diff 文本
最直接的用法。打开 pulls.review 首页,点击「Upload a diff / 上传 diff」按钮,会弹出「Load a diff」对话框:
- 在文本框中直接粘贴 unified diff 文本(占位提示为
diff --git a/foo b/foo…) - 点击 Load diff(加载 diff)
- 页面跳转到
/upload路由,显示「Parsing diff…」(正在解析 diff…),随后呈现分组视图
粘贴文本的格式支持:
- Git diff 输出(
git diff、git format-patch生成的内容,含diff --git头) - 纯 POSIX
diff -u输出(无 git 扩展头也能解析,只是失去重命名检测等能力)
一个典型的输入长这样(无需完整 PR,文件头 + hunk 即可):
diff --git a/src/app.ts b/src/app.ts
index 1234567..89abcde 100644
--- a/src/app.ts
+++ b/src/app.ts
@@ -10,3 +10,4 @@
- const x = 1
+ const x = 1
+ const y = 2
解析逻辑位于 patch-parser.ts,它优先识别 diff --git 分隔的文件块,并自动处理 git 的 C 风格路径引用(含中文、引号等特殊字符的路径);找不到 git 头时会回退到按 --- 行切分的宽松模式。
方式二:选择 .diff / .patch 文件
如果你本地已经有补丁文件,不必复制粘贴:
- 在同一个「Load a diff」对话框中,点击「Or choose a .diff/.patch file」(或选择 .diff/.patch 文件)
- 选择文件后,文件内容自动读入文本框(文件名会作为标题带入)
- 点击 Load diff 完成加载
对应的文件选择逻辑在 LoadDiffPanel.vue 中,accept 属性限定了 .diff、.patch、text/plain 三类文件。
方式三:把文件直接拖进页面
这是最省事的操作——不需要先打开对话框:
- 在首页任意位置,把
.diff/.patch文件拖入浏览器窗口 - 页面会出现一个虚线高亮的拖放提示框("Drop to load your diff / .patch file")
- 松手即完成加载,直接跳转到审查页面
首页对整个页面注册了 dragenter / dragover / drop 事件(见 index.vue),内部还处理了子元素交叉导致的拖放框闪烁问题;对话框内的文本框也单独支持拖放(见 LoadDiffPanel.vue 的 onDrop)。
加载之后:你会得到什么?
粘贴 / 上传的 diff 和打开一个真实 PR 一样,享受完整的审查体验:
- 📂 按目录分组:所有变更文件按路径分组折叠,可以逐组展开,避免"一个巨大 diff 从头滚到尾"
- ✅ 逐文件标记已审阅:用勾选框跟踪审查进度,头部显示"x / y 已审阅"
- ✨ AI 分析与聊天:配置模型后,可对 diff 做 AI 摘要分析,并针对具体代码行提问
- 🪟 侧边栏导航:宽屏下左侧有分组目录,点击可跳转到对应分组
审查页面主体是 DiffsPage.vue,它同时服务于 PR 视图、粘贴 diff 视图和嵌入模式,所以两种入口的体验完全一致。
背后发生了什么:从文本到缓存键
粘贴 / 上传的 diff 在项目内部被建模为一种独立的 diff 来源(provider):
- createPasteSource 接收你粘贴或上传的文本
- 计算文本的 SHA-256 内容哈希,生成
paste:<hash>形式的缓存键——内容相同则命中缓存,无需重复解析 - 标题默认显示为
Pasted diff(拖文件时则用文件名),没有 PR 描述,也没有过期检查——因为粘贴的内容没有"活着的上游"可对比,注释里写得很清楚:no live source, so no staleness check - 交给 patch-parser.ts 解析为文件变更列表,进入分组、摘要、审查流程
这种"无源"设计也意味着:粘贴模式不写回 GitHub,你无法对别人的 PR 提交 review 或评论——它定位就是只读的轻量审查,这也让审查敏感代码库的改动时更安心。
数据来源的设计思路可参考 plans/01-data-structure-and-provider.md,它定义了 github / paste / local 等多种来源如何统一为一套 diff 数据结构。
常见问题(FAQ)
Q:为什么点了加载后提示"Couldn't parse this diff"(无法解析此 diff)?
A:通常是因为粘贴的内容不是 unified diff 格式。确认文本以 diff --git 或 --- /+++ 开头;仅含纯说明、commit message 而没有 hunk 的内容会解析失败。空内容也会触发"尚未加载 diff"的空状态,按提示回首页重新上传即可。
Q:粘贴的内容会上传到服务器吗?
A:解析(createPasteSource 与 patch-parser)在前端完成;文本本身通过 uploadSession.ts 存入 sessionStorage(键为 diffs:pending-upload),用于刷新后恢复当前审查会话,随浏览器会话结束而消失。
Q:同一个 diff 反复加载会重复解析吗? A:不会。内容哈希相同的文本会命中本地缓存(见 cache.ts 相关逻辑),第二次打开几乎是瞬时的。
Q:能审查二进制文件或超大 diff 吗?
A:可以。解析器支持 Binary files differ 标记(文件会被标记为二进制),超大文件也有虚拟滚动支撑,滚动不卡顿。项目还准备了 huge-file.json、binary-file.json 等合成用例来验证这些边界情况(见 fixtures/synthetic/)。
总结
| 操作 | 适用场景 | 入口 |
|---|---|---|
| 粘贴 unified diff | 已有文本片段 | 首页「Upload a diff」按钮 → 文本框 |
| 选择 .diff/.patch 文件 | 本地已有补丁文件 | 同一对话框 → 文件选择 |
| 拖放文件到页面 | 最快,一步到位 | 首页任意位置直接拖入 |
pulls.review 的粘贴 / 上传 Diff 模式,把"审查一段改动"从依赖 PR 系统变成了复制、粘贴、开始看的三步动作。下次当你手里只有一段 patch 时,不妨试试这种轻量的审查方式。
