企业官网建设流程全解析

pi-gui 是 pi coding agent 的 Electron 桌面应用，它的单轮改动审查功能基于一个应用自有的Bare Git 检查点仓库：每一轮对话开始前自动捕获工作区快照（before tree），结束后再捕获一次（after tree），从而能精确回答"AI 这一轮到底改了哪些文件"。本文带你了解这套 Git 检查点的设计与实现，包括捕获时机、增量快照、容量预算与审查面板的消费方式。

一、单轮改动审查要解决什么问题

AI 编程助手会在一次任务中连续读写多个文件。如果你只用git diff对比 HEAD，看到的是所有未提交改动的混合：上一轮的、你手改的、甚至并行线程的，都混在一起，无法归因。

pi-gui 的 Review 面板为此提供了独立的审查范围（scope）：

• Last Turn：最新一轮对话的前后快照对比；
• Selected Turn：由会话时间线中某条消息"钉住"的特定一轮；
• Uncommitted / Staged / Unstaged / Branch：常规的工作区与分支对比。

时间线上还会为每一轮渲染一张"改动卡片"，显示本轮编辑的文件数与增删行数，点击即可跳转到对应的 diff。

范围契约定义在 contracts/review.ts，面板 UI 在 diff-panel.tsx。

二、核心设计：应用自有的 Bare Git 检查点仓库

pi-gui不在你的项目里写任何.git状态，而是在应用数据目录（userData）下维护一个独立的裸仓库，承担"检查点对象库"的角色，见 checkpoint-store.ts：

<userData>/turn-checkpoints/ objects.git/ # 应用自有的 bare 仓库，存放快照对象与 ref checkpoints.json # 每轮区间的元数据（原子写入） indexes/ # 构建 tree 时的一次性索引 capture-*/ # 捕获期间的临时 spool 目录

每个快照的 tree 都挂在一个私有 ref 上：refs/pi-gui/snapshots/<时间戳>-<uuid>（见 SNAPSHOT_REF_PREFIX），供后台维护识别与回收。

为什么用 bare 仓库？

• 检查点数据与用户仓库完全隔离：你的 index、objects、refs、HEAD 和工作文件一个字节都不碰，包括 linked worktrees；
• 快照 tree 是"整棵目录树"而非提交历史，不需要工作区，bare 仓库是最小、最不会误伤用户的形态；
• 对用户仓库只做只读 Git 调用（ls-files、rev-parse等），且通过 git-environment.ts 清掉所有继承的GIT_*环境变量，防止GIT_DIR、GIT_INDEX_FILE等把命令重定向到别处。

三、捕获时机：把快照钉在每一轮对话的边界

捕获不是轮询，而是由一个隐藏的 Pi 扩展pi-gui-turn-capture在会话生命周期钩子上触发的（packages/pi-sdk-driver/src/turn-capture.ts）：

关键点：

1. 等待式捕获（awaited boundary）：agent 的第一个工具执行前，before 快照必须落库完成。这保证 before tree 一定先于任何工具写入，Last Turn 在运行报告结束时就是最终值；
2. 交接复用同一快照：一次边界"关闭一个区间 + 打开下一个区间"共享同一棵树，避免重复读取整个工作区；
3. 可移植契约：驱动层只看到 TurnCaptureBoundary（区间 ID、转写锚点、结果状态），Git 对象库细节完全留在桌面端，不进入会话驱动契约；
4. 重叠溯源：并行线程在同一 checkout 上同时运行时，区间会互相记录overlaps，审查结果会注明"改动不能单独归因于某一个 agent"。

四、性能与容量：增量捕获、预算与后台维护

完整快照很贵，pi-gui 给每次捕获设了硬预算（DEFAULT_LIMITS）：

增量捕获是让它在大仓库里依然够快的关键：首次捕获后，store 在内存中保留该 checkout 的"清单"（inode、mode、size、mtime/ctime）。之后的边界只重新读取版本发生变化的文件，其余直接复用已存的 blob oid；2 秒内动过的文件强制重读以防时间戳"打平"。如果仓库大到第一次都装不进预算，还会在后台用 60 秒的宽松预算预热清单（失败后每 15 分钟重试），让后续轮次可用。

保留与回收策略（DEFAULT_RETENTION）：每个任务最多保留 50 个已定稿区间、全局 500 个；后台维护（约每小时、或 200 个边界后触发）删除不再被引用的 ref 并执行git gc --prune，但一小时内的对象一律保留，保护进行中的捕获不被误删。

五、从检查点到 Diff：审查面板如何消费快照

ReviewOwner是审查的总入口（review-owner.ts）：收到turn范围请求时，它先向检查点 store 解析出该轮的beforeTreeOid与afterTreeOid，再交给 Git 适配器 git-review.ts 执行两棵 tree 之间的git diff --numstat与按需取内容。

• 时间线每轮"改动卡片"来自 use-turn-changes.ts，点击文件后以{ kind: "turn", checkpointId }精确打开 diff；
• 消息气泡上的 Review 动作通过转写的原生sourceMessageId钉住那一条回复对应的确切检查点，变成 Selected Turn；
• 快照不可用时绝不回退到 HEAD 或其他轮次，只如实报告原因；
• turn 对比是只读的（不提供 Stage/Unstage），工作区范围才允许暂存操作。

六、安全边界与失败模式

这套设计的"诚实性"体现在几个明确边界上（详见 architecture.md 的Review and captured turns一节）：

• 捕获路径做严格校验：拒绝 sparse checkout、submodule 冲突与未解决冲突（整轮不可用），嵌套仓库会被跳过并标注 partial coverage；
• 读文件时反复校验父目录与 inode 是否变化，工作区在捕获中发生漂移会直接判为checkout-changing，而不是交出混合快照；
• 元数据checkpoints.json走原子写 + 备份；重启后发现"开着"的区间一律改写为 interrupted，宁可少显示也不伪造完成；
• 捕获、列表、解析三种失败状态（stale/unavailable/failed）彼此独立，UI 可区分展示。

七、关键源码入口

八、快速上手

克隆仓库阅读源码（配合 README 完成构建）：

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

打开 pi-gui 后，等 agent 跑完一轮，按⌘R（Linux/Windows 为Ctrl+R）切换 Review 面板，选择Last Turn即可看到该轮 agent 改动的前后对比。

总结：pi-gui 的单轮改动审查 = 等待式边界捕获 + 应用自有 bare Git 仓库 + 增量快照 + 有界保留。它不碰用户仓库、不产生部分 diff、失败时如实报告，让"这一轮 AI 到底改了什么"变成了一个可追溯、可钉住、可审查的确切答案。