【免费下载链接】pi-guiElectron GUI app for the pi coding agent runtime项目地址https://gitcode.com/gh_mirrors/pi/pi-gui点击查看免费下载pi-gui 是 pi coding agent 的 Electron 桌面应用它的单轮改动审查功能基于一个应用自有的Bare Git 检查点仓库每一轮对话开始前自动捕获工作区快照before tree结束后再捕获一次after tree从而能精确回答AI 这一轮到底改了哪些文件。本文带你了解这套 Git 检查点的设计与实现包括捕获时机、增量快照、容量预算与审查面板的消费方式。一、单轮改动审查要解决什么问题AI 编程助手会在一次任务中连续读写多个文件。如果你只用git diff对比 HEAD看到的是所有未提交改动的混合上一轮的、你手改的、甚至并行线程的都混在一起无法归因。pi-gui 的 Review 面板为此提供了独立的审查范围scopeLast Turn最新一轮对话的前后快照对比Selected Turn由会话时间线中某条消息钉住的特定一轮Uncommitted / Staged / Unstaged / Branch常规的工作区与分支对比。时间线上还会为每一轮渲染一张改动卡片显示本轮编辑的文件数与增删行数点击即可跳转到对应的 diff。范围契约定义在 contracts/review.ts面板 UI 在 diff-panel.tsx。二、核心设计应用自有的 Bare Git 检查点仓库pi-gui不在你的项目里写任何.git状态而是在应用数据目录userData下维护一个独立的裸仓库承担检查点对象库的角色见 checkpoint-store.tsuserData/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钩子动作agent_start打开新轮次捕获before快照message_start轮次交接关闭上一轮、用同一份快照打开新一轮agent_settled运行结束捕获after快照并定稿session_shutdown应用退出时标记为 interrupted绝不虚报完成关键点等待式捕获awaited boundaryagent 的第一个工具执行前before 快照必须落库完成。这保证 before tree 一定先于任何工具写入Last Turn 在运行报告结束时就是最终值交接复用同一快照一次边界关闭一个区间 打开下一个区间共享同一棵树避免重复读取整个工作区可移植契约驱动层只看到 TurnCaptureBoundary区间 ID、转写锚点、结果状态Git 对象库细节完全留在桌面端不进入会话驱动契约重叠溯源并行线程在同一 checkout 上同时运行时区间会互相记录overlaps审查结果会注明改动不能单独归因于某一个 agent。四、性能与容量增量捕获、预算与后台维护完整快照很贵pi-gui 给每次捕获设了硬预算DEFAULT_LIMITS参数默认值超出后的行为超时2 秒标记 unavailable不产生部分 diff文件数10,000整轮捕获不可用总大小64 MiB整轮捕获不可用单文件16 MiB整轮捕获不可用增量捕获是让它在大仓库里依然够快的关键首次捕获后store 在内存中保留该 checkout 的清单inode、mode、size、mtime/ctime。之后的边界只重新读取版本发生变化的文件其余直接复用已存的 blob oid2 秒内动过的文件强制重读以防时间戳打平。如果仓库大到第一次都装不进预算还会在后台用 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 可区分展示。七、关键源码入口模块路径检查点仓库核心checkpoint-store.ts轮次捕获扩展Pi 钩子turn-capture.ts可移植捕获契约turn-capture.ts审查所有者review-owner.tsGit 只读适配器git-review.tsGit 环境变量隔离git-environment.ts审查范围契约review.ts审查面板 UIdiff-panel.tsx每轮改动卡片turn-changes-card.tsx单元测试 / 端到端测试checkpoint-store.spec.ts · review-turns.spec.ts八、快速上手克隆仓库阅读源码配合 README 完成构建git clone https://gitcode.com/gh_mirrors/pi/pi-gui打开 pi-gui 后等 agent 跑完一轮按⌘RLinux/Windows 为CtrlR切换 Review 面板选择Last Turn即可看到该轮 agent 改动的前后对比。总结pi-gui 的单轮改动审查 等待式边界捕获 应用自有 bare Git 仓库 增量快照 有界保留。它不碰用户仓库、不产生部分 diff、失败时如实报告让这一轮 AI 到底改了什么变成了一个可追溯、可钉住、可审查的确切答案。赞分享【免费下载链接】pi-guiElectron GUI app for the pi coding agent runtime项目地址https://gitcode.com/gh_mirrors/pi/pi-gui点击查看免费下载相关推荐FastGPT 前端 React 性能审查指南四大检查点与仓库实践FastGPT 前端 React 性能审查指南四大检查点与仓库实践 本文是 FastGPT 开源仓库内 pr review 技能体系中「前端代码质量」检查清单人工智能AI AgentRAG大模型工作流自动化后端前端Databasus 仓库的 AI 审查体系reviewer 子代理如何审计计划与代码改动Databasus 仓库的 AI 审查体系reviewer 子代理如何审计计划与代码改动 Databasus 是一个以 PostgreSQL 备份为核心支持数据库灾备jsreport平台完全指南从安装到生成PDF的10分钟入门教程jsreport平台完全指南从安装到生成PDF的10分钟入门教程 jsreport是一个基于JavaScript的业务报告平台它允许开发者和企业快速生成各种后端开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考