手册/第 12 章
作者自述:16 篇博客里的 pi 为什么长这样
仓库告诉你 pi 是什么,博客告诉你它为什么是这个形状。 earendil.com/posts 从 2026-01-18 到 2026-10-16 共 16 篇, 前四篇是信件体宣言(1–4 月),后十二篇转为工程笔记与产品发布(7 月起)。 这一章把它们整理成一条叙事线,并把其中可验证的技术断言逐条回仓库核对。
16 篇清单(按时间)
| 日期 | 标题 | 类型 | 一句话 |
|---|---|---|---|
| 2026-01-18 | An Invitation to Begin a Correspondence | 信件 | 创刊:公开建造,人在维也纳,欢迎来邮 |
| 2026-02-12 | The High Ground | 战略备忘 | 2026–2031 模型公司之外的「高地」在哪:context 与 harness |
| 2026-04-08 | Announcing Pi & Lefos | 发布 | 成立 Earendil(PBC),收购 Pi,Mario 加入;Lefos 公开 alpha |
| 2026-04-08 | A Reflection on our Announcement Today | 信件 | 同日的价值观长文:为什么是「增强人的能动性」 |
| 2026-07-22 | Prompt Caching In Agents | 技术 | 缓存要求前缀逐字不变——它决定了 agent 的成本结构 |
| 2026-07-30 | The Session You Cannot Take With You | 技术 | 会话可携带性:为什么会话格式是最该掌握的资产 |
| 2026-08-03 | Pi, Minimal and Performant | 论证 | 4 个工具、prompt + 工具定义不到 1,000 token,性能不输 |
| 2026-08-13 | How Compaction Works in Pi | 技术 | 何时压缩、留多少、摘要 prompt 长什么样、为何破坏缓存 |
| 2026-08-20 | What is a Harness? | 科普 | harness 的四件事:system prompt、工具、循环、翻译层 |
| 2026-09-01 | There are many agent harnesses, but this one is mine. | 随笔 | 一位非工程师写自己怎么把 pi 用成私人助理 |
| 2026-09-10 | Measuring the Sloppiness of Code | 度量 | verbosity / erosion 两个指标:agent 代码退化约为人类两倍 |
| 2026-09-29 | “You Said No MCP!” | 立场 | 从「永不支持 MCP」到「用 Codemode 支持 MCP」的完整交代 |
| 2026-10-01 | Pi 1.0 | 发布 | 1.0 加了七项;没加进清单的更多 |
| 2026-10-01 | Pi Durable | 发布 | 为长时运行 agent 做的实验性 substrate |
| 2026-10-09 | There are many themes, but this one is yours | 设计 | 新默认主题向终端索取颜色,一切决策围绕对比度 |
| 2026-10-16 | Pi Durable on Cloudflare | 教程 | Durable Objects 做多人聊天 agent:能休眠、能定时唤醒 |
阅读建议:想懂设计取舍读 09-29、10-01;想懂内部机制读 08-13、07-22; 想懂它想成为什么读 08-20、02-12。
深读一:harness 的四件事,正好是 pi 的四层
《What is a Harness?》给了一个可以直接背下来的定义——harness 只做四件事:
把这句话和第 01 章的四层对照,会发现两者是同一张图: system prompt → 提示层、tools → 工具层、agentic loop → 循环层、translation layer → 模型层。 博客的第四条尤其值得注意,它是「能动性」论点的技术落点——作者说翻译层把议价能力从模型厂转移到用户手里:
这条在仓库里是可验证的:模型层被单独抽成一个包 packages/ai, 连 DeepSeek 官方的 harness 都直接把它当依赖用(见第 09 章)。
深读二:「最小」的操作定义,不是口号
《Pi, Minimal and Performant》把极简写成了可检验的数字:出厂只有 4 个工具,system prompt 加工具定义合计不到 1,000 token。这条能直接查:
| 博客说法 | 仓库证据 | 结论 |
|---|---|---|
| 「comes out of the box with only 4 tools」 | read.ts:94 · write.ts:50 · edit.ts:149 · bash.ts:418 | 一致:内置工具就是 read / write / edit / bash 四个 |
| 「prompt + 工具定义 < 1,000 token」 | 本次未独立测量 token 数(依赖分词器与具体模型),只确认了工具定义本身极短 | 未复核:数字可由作者自测,但口径(哪个分词器)未公开 |
这里有一处必须说清的不矛盾:博客说「小」指的是 prompt 与工具集,
而第 09 章统计的 21.8 万行(不含测试)是整个产品外壳。
两句话都对——小的是入口,大的是让入口在真实终端里活下来所需的工程。
这也解释了第 01 章那个反差:循环本体只有 6 个源文件 2,541 行,而 coding-agent 整包 164,445 行。
深读三:MCP 那一篇,是一次完整的立场交接
第 07 章记过 pi 从「永不支持 MCP」到「已支持」的转向。《“You Said No MCP!”》是作者把这件事一次讲完: 不讲「我们错了」,而讲哪些条件变了、以及变化本身带来了什么副产品。
| 博客里的论证 | 原文要点 |
|---|---|
| 为什么不是「外部变了就跟着变」 | MCP 本身变了,但「这不足以成为放进内核的理由」——因为 MCP 本来就可以是一个扩展,而且它曾经就是。 |
| 真正的理由是副产品 | 为 MCP 做的改动同时让 Jev(分类器/非 LLM 模型)在 pi 里更好用:两者需要的都是「一个可以玩耍的沙箱解释器」。 |
| Codemode 是什么 | 工具执行有两侧:bash 那侧(沙箱、不太可信)与 agent loop 那侧(可信)。Codemode 跑在 agent loop 那侧,本质是编排与组合工具调用的沙箱;状态因此存在于 session transcript,而不是文件系统。 |
| 为什么必须是 JS | 小体积的 JS 可以编译成 WASM 二进制,从而获得合理程度的隔离。 |
| 对 MCP 生态的评价 | 最大的问题仍是难以组合;许多 server 仍为「把工具全塞进上下文」的 harness 而设计,返回文本以省 token。作者认为 MCP 应更接近 OpenAPI + 智能工具发现:返回结构化数据、能被文档检索到。 |
| 为什么不干脆只要 Codemode | pi 近期支持了延迟工具加载、会话中 system message、推理档位;但工具装载的元数据还没跟上——普通 MCP 扩展拿不到足够元数据去判断「这个工具该给模型看,还是只在 codemode 里可用」。 |
最后这条在仓库里有直接对应物——MCP 工具的暴露方式被做成了可选模式:
// - `codemode`: tools are callable from codemode scripts but neither declared // to the model nor listed in the codemode description, which lists only the // server's namespace. Scripts find them with `searchTools()`.
而 Codemode 在设置里默认就是开的:
settings-defaults.ts:57-59
(codemode: { mode: "on", inlineBudget: 3000 })。
深读四:压缩那一篇,四个数字逐条核对
《How Compaction Works in Pi》是全部 16 篇里最适合「读一篇就懂一个机制」的。它给出的每个数字都能在仓库里找到:
| 博客说法 | 仓库证据 | 核对结果 |
|---|---|---|
| 「Pi 保留若干条最近消息不变……当前默认的 20 thousand tokens 大约相当于 5–20 轮」 | settings-defaults.ts:12 | 一致:keepRecentTokens: 20000(易误记为 reserveTokens,那是 16,384,见 :11) |
| 压缩请求换一个 system prompt:「you are a context summarization assistant」 | compaction/utils.ts:161 | 逐字一致:SUMMARIZATION_SYSTEM_PROMPT = "You are a context summarization assistant…" |
| 用户消息请求「a structured summary of this conversation branch for context when returning later」 | branch-summarization.ts:258 | 逐字一致:该字符串是 BRANCH_SUMMARY_PROMPT(分支摘要,与 compaction 相邻但不同路径) |
「也可以手动用 /compact 触发」 |
slash-commands.ts:40 | 一致:{ name: "compact", description: "Manually compact the session context" } |
这篇还有一个容易被忽略的结论,值得单独记住——压缩必然打断 prompt 缓存:
这解释了第 06 章里 compaction 与 caching 为什么总是一起出现: pi 的策略是「一轮结束才检查是否自动压缩,在那之前每个请求都复用同一前缀」—— 把缓存友好的时机和压缩的时机对齐,而不是有需要就立刻压。
深读五:怎么量化「代码垃圾化」
《Measuring the Sloppiness of Code》是 16 篇里唯一带公式的。作者(物理背景)先否掉了业界最常用的两种评法: 让 AI 打分(「基本等价于随机数生成器」)、让 AI 在 A/B 里选优(换个名字偏好就会变), 再给出两个能量化的指标:
| 指标 | 定义 | 含义与实测 |
|---|---|---|
| Verbosity 啰嗦度 |
|AST-Grep 标记行 ∪ 克隆行| / LOC |
重复与无谓冗长的占比。成熟仓库 0.15 ± 0.06,agent 生成代码 0.33 ± 0.10 |
| Erosion 侵蚀度 |
mass(f) = CC(f)·√SLOC(f);Erosion = ΣCC>10 mass / Σ mass |
复杂度集中在少数巨型函数里的比例。成熟仓库 0.31 ± 0.17,agent 代码 0.68 ± 0.20 |
一句话结论:agent 代码平均比人类代码啰嗦约 2 倍、侵蚀约 2 倍。更值得警惕的是 SlopCodeBench 的评测设计——多轮指令与测试,中间清空上下文,模拟真实迭代;结果在最严格口径(每个检查点都要全过)下,连 SOTA 模型也是 0% 通过率。
这篇对我们自己的分析也有约束力:第 09 章只比了「行数」,而行数恰恰是作者自己引用的那句讽刺—— 「用代码行数衡量编程进度,就像用重量衡量造飞机的进度」。行数只能证明规模,不能证明质量。 若要更进一步,应该对两个仓库跑 verbosity / erosion,而不是再加一行行数。
把 16 篇映射回本手册
| 博客 | 对应章节 | 读它能补什么 |
|---|---|---|
| What is a Harness? | 第 01 章 心智模型 | 四层的「为什么是这四个」,以及翻译层的能动性论点 |
| The High Ground | 第 02 章 设计哲学 | 为什么护城河在 context 与 harness,而不在模型 |
| Pi, Minimal and Performant | 第 02 / 07 章 | 极简的可检验形式:4 个工具、<1,000 token |
| How Compaction Works in Pi | 第 06 章 会话与上下文 | 压缩的触发时机、保留预算、摘要 prompt、与缓存的冲突 |
| Prompt Caching In Agents | 第 06 章 | 为什么「前缀不变」是成本设计的硬约束 |
| The Session You Cannot Take With You | 第 06 章 | 会话可携带性为什么是自由度问题 |
| “You Said No MCP!” | 第 07 章 刻意不做 | 立场转向的完整论证,以及 codemode 的真实动机 |
| Pi 1.0 / Pi Durable | 第 09 章 演进 | 1.0 加了哪七项、为什么把长时运行拆成新包 |
| Measuring the Sloppiness of Code | 第 09 章(口径警示) | 为什么「行数对比」只能说明规模 |
| There are many agent harnesses, but this one is mine. | 第 02 / 10 章 | 非工程师视角:malleable 到底是什么意思 |
keepRecentTokens,不是 reserveTokens。