Pi-Harness 开源桌面工作台：让 Pi Coding Agent 运行可回放、可管控

用 Pi 这种在终端里跑的 coding agent 干活，有个问题一直挺难受的：它一跑起来就是个黑盒。改了哪些文件、调了多少次工具、token 花到哪去了、卡在哪一步失败的，终端一滚屏就过去了，事后想查都查不到。

这几天在 GitHub 上发现了一个开源项目，刚好解决了这个痛点，叫 Pi-Harness。今天来聊聊它。

简单介绍下

Pi-Harness 就是给 Pi 配的桌面工作台，今年 8 月才开源。打开项目、开会话、改文件、看 Git、配模型都在它里面，每次运行有记录能回放，还能给 agent 设规矩、设预算，出了问题能恢复，干活的还是 Pi 本身。

功能都很实用

每次运行都有记录，还能回放

这是我觉得最实用的一块。每次跑任务都会生成一条 Run 记录，token 花了多少、费用多少、调了哪些工具、跑了多久，都列在上面。跑完还能回放，跟看视频差不多，播放、暂停、单步，0.5 倍到 4 倍变速，赶时间还能一瞬间播完。时间花在模型上还是工具上，看瀑布图就知道。

失败排查也做得实在，它有个 Diagnostics，把失败原因串成一条链，比如 bash 退出码 1，然后测试阶段失败，最后评估不通过，一层层往下追。官方说这些诊断不是让模型猜的，都是从记录下来的事件和命令输出里推出来的。跑飞了可以从这次运行 fork 个新会话重跑，或者从检查点恢复。

另外它会给项目建基线，哪次运行消耗突然不对劲，比如 token 比基线高出 150%，会直接标出来是回归。

把 agent 管住：策略、预算、检查点

让 agent 跑长任务，我一般担心两个事，一个是乱动文件，一个是 token 花起来没数。

策略（Policy）按操作类型定规矩，比如 git push 和删除文件之前必须先问我，危险命令默认要确认。预算（Budget）设 token 上限和花费上限，超了自动暂停。检查点（Checkpoint）在开跑前把会话和 git 状态存个快照，出问题能退回去。

多 agent 编排

它还支持多个 agent 一起干活。在一个计划里组个团队，比如架构、前端、后端、QA、审查各一个 agent，任务之间能挂依赖关系，前面的没做完后面的先等着。每个 agent 跑在各自独立的 git worktree 里，互不干扰，两个 agent 改了同一个文件会提示冲突。产物可以在 agent 之间交接，关键节点能设审查关卡，没通过不往下走。整个团队也有总预算，超了暂停。

每个 agent 背后跑的还是真实的 Pi 会话，编排只负责协调，没有另外搞一套运行时。如果你对这种 Agent 开发 的工程化思路感兴趣，可以多关注它的编排设计。

各家 AI 的本地历史记录，收在一个地方

如果跟我一样，机器上同时装着好几个 AI 编程工具，Claude Code、Codex、Cursor、Gemini CLI、OpenCode 这些，历史记录肯定散在各处，想找以前的某次对话得一个工具一个工具去翻。Pi-Harness 能把这些工具的本地会话记录收进同一个界面，Codex 桌面端和归档的对话也包括，可以按来源、项目、时间段搜。

看到有价值的对话，可以直接在它原来的项目目录里接着聊，用我们选好的模型开一个新的 Pi 会话。浏览和翻历史完全不耗 token，只有主动点"用 AI 整理"的时候才调模型。

工作台、编辑器和主题

工作区里文件浏览、编辑、Git diff 都有。编辑器是轻量的，语法高亮、行号、撤销重做、查找这些有，官方明说它不是 IDE，没有 LSP，没有调试器，没有集成终端，以后也不打算做。写代码的主力编辑器该用啥用啥。

外观这块花的心思挺多，自带好几套主题，大明系列（雪境朝臣、雪夜笛姬、月城书姬）、星舰驾驶舱、macOS 27 Liquid Ether，设置里直接换。

自带的不够，还能用官方的 skin starter 工程，让 Codex 或者 Pi 按我们描述的风格生成一套皮肤再导入。下面这个夏日海岸就是一套自定义皮肤的效果。

安装

安装包在 GitHub Releases 直接下，macOS（Apple Silicon 和 Intel 分开）、Windows、Linux AppImage 都有，不用 clone 仓库也不用装 pnpm。

装完第一次打开，它会自己检查 Node.js、npm、PATH 和 Pi Coding Agent，缺什么在应用里直接装直接修。然后配模型服务、选模型、打开项目文件夹，就能开会话了。接的是 Pi 兼容的 provider，选择很多，Kimi For Coding 这类国内的也能直接用，按自己平时在用的配。

macOS 的社区构建包可能没签名，第一次启动被系统拦的话，到“系统设置 → 隐私与安全性”里点“仍要打开”。

安装非常简单，选好适配自己电脑的版本就行。完了我吐槽一下，默认主题真是，一言难尽啊，我贴出来大家看吧。

最后说两句

现在用 coding agent，模型强不强当然重要，可实际天天跑下来，最烦的还是看不见、管不住，出了事退不回来。Pi-Harness 没碰 Pi 的运行时，就老老实实做外面这层工程化的东西，做得还挺细。

但是可能刚开源没多久，整体使用下来，还是有略微卡顿的。

平时就在用 Pi，或者好几个 AI 编程工具的历史记录乱成一团的，可以装一个试试。这类 开源实战 项目，挺适合拿来研究桌面端工程化和 agent 工作流设计。

开源地址

https://github.com/wangmiaozero/pi-harness