Appearance
4.17 极简 Harness 解剖：Pi 的设计哲学
4.8讲了 Harness 的七个零件，Claude Code 是"出厂全配齐"的代表。这一节解剖另一个极端——Pi（pi.dev），一个刻意极简的开源 Agent Harness。
研究它的价值不在于"你要不要换工具"，而在于：Pi 把"Harness 到底该内置什么、不该内置什么"这个问题推到了极限，它的答案会反过来改变你对 Claude Code 乃至所有 Agent 工具的理解。
Pi 是什么
一句话：Pi 是一个极简的 Agent Harness（minimal agent harness），官方定位是"Adapt Pi to your workflows, not the other way around"——让工具适应你的工作流，而不是反过来。
事实速览：
- 开源（MIT），代码在 earendil-works/pi monorepo（原
badlogic/pi-mono），分层清晰：pi-ai（多模型统一 API）→pi-agent-core（Agent 运行时：工具调用 + 状态管理）→pi-coding-agent（交互式 CLI） - 支持 30+ 模型提供商（Anthropic、OpenAI、Google、Bedrock、Ollama 等，v0.81 源码
KnownProvider枚举有 38 个），会话中用/model随时切换 - 默认不带 Sub-agents、Plan mode 这类"高级功能"——想要？自己造，或者装别人造好的包
💡 类比：Claude Code 是精装房——拎包入住，格局动不了；Pi 是户型极佳的毛坯房——水电承重都设计好了，但墙刷什么色、要不要隔一间书房，全由你定。两种路线没有优劣，服务的是两种用户。
核心哲学：Primitives, not features（给零件，不给成品）
Pi 最重要的一句设计宣言：别的 Agent 内置的功能，Pi 给你造出这些功能的零件。
它的扩展（Extension）是一个 TypeScript 模块，能访问：工具、命令、键盘快捷键、事件、乃至整个终端 UI。于是这些"本该官方内置"的东西，全都可以用扩展实现：
Sub-agents、Plan mode、权限门禁、路径保护、
SSH 执行、沙箱、MCP 集成、自定义编辑器、状态栏……不想自己造？两条路：直接叫 Pi 给自己造一个（见下一条），或者 pi install 一个别人打包好的（npm 或 git 分发）。
💡 这和 4.8 的视角正好互补：4.8 说 Harness 有七个零件，好的工具把它们做扎实；Pi 追问的是——哪些零件该焊死，哪些该留成接口？ Pi 的答案是：焊死的越少越好，但留出的接口必须是一流的。
⚠️ 常见误解："不内置 = 功能少 = 弱。" 这是把"功能"和"能力"混为一谈。Pi 赌的是：内置的工作流决策越多，不适配的场景就越多；把决策权交给用户，天花板反而更高。代价也很直白——默认体验不如精装房，动手的成本转移给了用户。
解剖一：自我改造——Harness 本身也是可编程对象
Pi 最"激进"的一点：你可以直接让 Pi 修改它自己的代码。
想要一个新命令、一个新工具、改一处 UI？在会话里直接说，Pi 会改动自身源码，你敲一下 /reload，改动当场生效，接着干活。
这标志着一个范式变化：传统工具里，"用户"和"开发者"是两个角色，不满官方设计只能提 issue 等排期；在 Pi 里，Harness 本身成了 Agent 的工作对象——Agent 既是使用者，也是改造者。
💡 回头看 4.15 的角色光谱，这其实是 Loop Engineer 的一个新场景：让 AI 参与的循环，改造的对象是 AI 自己的工具。你设计的循环不仅产出代码，还产出"更好用的循环本身"。
解剖二：能力即文件——统一的分发模型
Pi 把"给 Agent 加能力"统一成了几种文件级的载体，且都能打包分享：
| 载体 | 是什么 | 对应你学过的 |
|---|---|---|
| Extension | TypeScript 模块，挂钩工具/命令/事件/UI | Harness 零件的可编程接口 |
| Skill | 带说明和工具的能力包，按需加载 | 5.10 Skill 机制 的渐进披露 |
| Prompt Template | Markdown 文件，输入 /名字 即展开 | 第 6 章 模板的工程化 |
| Package | 把上面几样打包，npm / git 一键安装 | 能力的版本化分发 |
Skills 这一条尤其值得注意：Pi 刻意让 Skills 按需加载、渐进披露，理由和 4.9 的"按需注入"一字不差——全程挂着所有能力说明，会打爆上下文、还会让模型分心（同时避免破坏 Prompt Caching，呼应 1.16）。
解剖三：树状会话历史——承认"探索-回退"是常态
普通 Agent 工具的会话历史是一条线：说错一句话、走错一个方向，只能将错就错或从头再来。Pi 的会话是一棵树：
/tree查看整棵会话树，跳到任意历史节点从那里继续——自动分叉，旧分支不丢- 所有分支存在一个文件里，可按消息类型过滤、给节点加书签
/export导出 HTML，/share生成可分享的链接
为什么这件事重要？因为真实工作里，"试一条路 → 发现不对 → 退回分叉点 → 换条路"是常态而不是异常。线性历史强迫你污染上下文（错误探索的过程全留在对话里，正是 2.4 上下文污染），树状历史让"回退"成为一等公民——本质上，它把 4.9 的"隔离"手法用在了时间轴上。
💡 还有一个工程视角的收益：会话即数据。会话是结构化的单文件，可以导出、可以分享、可以拿去复盘和评估（呼应 2.18 数据飞轮）——Pi 社区甚至在专门收集公开会话来改进编码 Agent。
解剖四：四种运行模式——Harness 不止是人用的
同一个 Pi，四种用法：
| 模式 | 形态 | 典型用途 |
|---|---|---|
| Interactive | 完整终端 UI | 人日常用 |
| Print / JSON | pi -p "..."，可输出事件流 | 脚本、CI、管道组合 |
| RPC | stdin/stdout 上的 JSON 协议 | 给非 Node 系统当后端 |
| SDK | 作为库嵌入你的应用 | 把 Agent 能力装进自己的产品 |
这条的设计含义很容易被低估：好的 Harness 应该既能当"工具"（人直接用），也能当"组件"（被系统调用）。 一个只能交互使用的 Agent，没法进 CI、没法被编排；而一个支持 Print/RPC/SDK 的 Harness，可以变成 4.12 工作流里的一个节点，甚至变成 4.6 多 Agent 系统里的一个成员。
解剖五：上下文工程的教科书式落地
Pi 把 4.9 的四个手法几乎全部做成了显式机制，对照看：
| 4.9 的手法 | Pi 的对应机制 |
|---|---|
| 按需注入 | Extensions 可以在每一轮前动态注入/过滤消息（做 RAG、做长期记忆都靠这个钩子） |
| 压缩 | 接近上下文上限时自动 Compaction，且压缩策略本身可用扩展替换（按主题压缩、换摘要模型都行） |
| 隔离 | 树状分支 + Sub-agent（需扩展实现） |
| 外部记忆 | AGENTS.md（项目指令，从用户目录到项目目录分层加载）、SYSTEM.md（替换或追加默认系统提示） |
💡 注意
AGENTS.md/SYSTEM.md和 4.7 里 CLAUDE.md 是同一个思想：把反复交代的上下文固化成文件，让 Harness 每次自动加载。Pi 把这条路走到了"每一层都可替换"的程度——这就是"上下文工程"从理念变成机制的样子。
Pi vs Claude Code：两种设计路线对照
| Claude Code | Pi | |
|---|---|---|
| 设计哲学 | Batteries included（全配齐） | Primitives, not features（给零件） |
| Sub-agents / Plan mode | 内置 | 不内置，用扩展造 |
| 默认体验 | 开箱即用，决策已被做好 | 毛坯，需要自己配置 |
| 定制方式 | 配置 + Hooks + Skills | 直接改 Harness 本身，TS 扩展 |
| 会话历史 | 线性 | 树状（可回退分叉） |
| 嵌入系统 | 主要靠 CLI/SDK | Print / RPC / SDK 全有 |
| 适合谁 | 想把活干完的人 | 想打造自己工具的人 |
什么时候学它，什么时候不学
值得深入的情况：
- 你在做 Agent 工具/平台——Pi 的源码是一份"Harness 该怎么分层"的优秀教材（
pi-ai/pi-agent-core/pi-coding-agent三层，职责干净） - 你的工作流很特殊，现成工具的内置决策总碍事
- 你想研究"上下文工程""能力分发""会话管理"的工程实现——Pi 全做成了可读的机制
不必折腾的情况：
- 你只想把日常开发活干完——精装房就是为你设计的，Claude Code 的开箱体验更好
- 团队没有精力维护一层自建扩展——毛坯房的自由度是有维护账单的
🛠️ 实战练习：解剖一只"极简挽具"
- 装起来：全局安装 CLI（
npm i -g @earendil-works/pi-coding-agent），配一个你已有的模型 Key，随便让它改个小文件，跑通最小闭环 - 体验树状历史：在会话里故意制造一个分叉（比如让它试两种实现方案），用
/tree跳回分叉点走另一条路，观察旧分支还在不在 - 造一个零件：写一个最小 Prompt Template（一个 Markdown 文件）或 Extension，让它出现在你的会话里，体会"能力即文件"
- 对照打分：拿出 4.8 的七个零件清单，逐个判断 Pi 是"内置了"、"留成接口了"、还是"完全没有"——写成一张两列对照表
期望结果：完成第 4 步后，你会对"Harness 该内置什么"形成自己的判断标准——这个标准对评估任何 Agent 工具都适用。
进阶挑战：用 Pi 的 Print 模式（pi -p）把它嵌进一个 shell 脚本，作为 4.12 工作流里的一个节点被调用，体会"Harness 即组件"。
📌 关键结论
- Pi 是一个刻意极简的开源 Agent Harness，核心哲学是 Primitives, not features——不内置工作流决策，只给一流的零件
- 它让"Harness 本身"成为 Agent 可改造的对象：会话里说改就改，
/reload生效——工具从"产品"变成了"可编程底座" - 树状会话历史把"探索-回退"变成一等公民，从时间轴上解决了上下文污染，还让会话成为可分享、可评估的数据
- 四种运行模式说明：好 Harness 既能当人用的工具，也能当被系统调用的组件
- 精装房与毛坯房没有优劣：想干活选全配齐，想打造工具选可编程底座——理解两条路线，你就有了评估一切 Agent 工具的标尺
这一节讲的是"Pi 为什么这么设计"。如果你想知道这些设计在代码里长什么样——Agent Loop 几百行代码怎么写、树状会话在磁盘上怎么存、扩展热重载怎么实现——接下来的源码解剖系列（4.18–4.22）会带你逐层走读 Pi v0.81 的真实源码。