手册/第 02 章
02
设计哲学:把「我不需要」写进架构
理解 pi 最快的路径不是读代码,而是读作者抱怨了什么。2025 年 11 月 30 日那篇 复盘长文 里,几乎所有架构决策都能对应到一条具体的不满。
不满一:工具变成了飞船
"Over the past few months, Claude Code has turned into a spaceship with 80% of functionality I have no use for. The system prompt and tools also change on every release, which breaks my workflows and changes model behavior. I hate that. Also, it flickers."
Claude Code 已经变成一艘飞船,80% 的功能我都用不上。system prompt 和工具每次发版都变,破坏我的工作流、改变模型行为。我讨厌这点。而且它会闪。
— 2025-11-30 博客
三个抱怨都非常具体:功能膨胀、接口不稳定、渲染抖动。它们分别对应 pi 的三个工程决策: 砍功能(第 07 节)、把 prompt 与工具定义做成可组装的稳定契约、自己写差分渲染的 TUI。
不满二:harness 在背后偷偷注入上下文
"In all that work, I learned that context engineering is paramount. Exactly controlling what goes into the model's context yields better outputs, especially when it's writing code. Existing harnesses make this extremely hard or impossible by injecting stuff behind your back that isn't even surfaced in the UI."
在那些工作里我学到,上下文工程是头等大事。精确控制进入模型上下文的内容,会显著提升输出质量,尤其是写代码时。而现有 harness 让这件事极难甚至不可能——它们在你背后注入一些东西,连 UI 里都看不到。
— 2025-11-30 博客
这句话解释了很多看起来「反直觉」的设计。比如为什么 pi 的 system prompt 短到只有几百 token、 为什么工具只有四个、为什么不做 sub-agent:每一项被砍掉的能力,都是一段你无法控制的隐式上下文。 能力越少,你能看见、能预测、能改写的东西就越多。
不满三:无法观测,也无法二次开发
"I want to inspect every aspect of my interactions with the model. Basically no harness allows that. I also want a cleanly documented session format I can post-process automatically, and a simple way to build alternative UIs on top of the agent core."
我想检视我与模型交互的每一个环节,几乎没有 harness 允许这么做。我还想要一个有清晰文档、可以自动后处理的会话格式,以及在 agent 核心之上构建替代 UI 的简单方式。
— 2025-11-30 博客
这三句话直接对应三个可验证的产物:
A可观测
所有事件都是类型化的流,UI 只是消费者;
--mode json 可以把整个 run 导出成事件流。B可后处理
会话就是 JSONL,一行一个 entry,
id/parentId 组成树。用 jq 就能分析。C可替换 UI
TUI / print / JSON / RPC / SDK 五种接入方式共用同一套 agent 与 session。
总纲:一句话的取舍原则
"My philosophy in all of this was: if I don't need it, it won't be built. And I don't need a lot of things."
我在整件事上的哲学是:如果我不需要它,它就不会被造出来。而我不需要的东西很多。
— 2025-11-30 博客
这句话最好和另一句放在一起读——它说明了 pi 的真实目标不是「最小」本身, 而是把控制权交回使用者:
"pi is my attempt to build myself a tool where I'm in control as much as possible."
pi 是我为自己打造的一个工具,让我尽可能地掌控一切。
— 2025-11-30 博客 · 结尾
怎么用这一节
后面每遇到一个「pi 为什么不做 X」的问题,先回到这里:X 会不会引入你看不见的上下文?
会不会让接口不稳定?会不会让 UI 与真实状态不一致?三个问题里有一个是「会」,那它就不会被做。