pi 系统学习手册 第 12 / 12 章 总目录 单页全本 架构图 GitHub

手册/第 12 章

12

作者自述:16 篇博客里的 pi 为什么长这样

仓库告诉你 pi 是什么,博客告诉你它为什么是这个形状。 earendil.com/posts 从 2026-01-18 到 2026-10-16 共 16 篇, 前四篇是信件体宣言(1–4 月),后十二篇转为工程笔记与产品发布(7 月起)。 这一章把它们整理成一条叙事线,并把其中可验证的技术断言逐条回仓库核对。

16 篇清单(按时间)

日期标题类型一句话
2026-01-18An Invitation to Begin a Correspondence信件创刊:公开建造,人在维也纳,欢迎来邮
2026-02-12The High Ground战略备忘2026–2031 模型公司之外的「高地」在哪:context 与 harness
2026-04-08Announcing Pi & Lefos发布成立 Earendil(PBC),收购 Pi,Mario 加入;Lefos 公开 alpha
2026-04-08A Reflection on our Announcement Today信件同日的价值观长文:为什么是「增强人的能动性」
2026-07-22Prompt Caching In Agents技术缓存要求前缀逐字不变——它决定了 agent 的成本结构
2026-07-30The Session You Cannot Take With You技术会话可携带性:为什么会话格式是最该掌握的资产
2026-08-03Pi, Minimal and Performant论证4 个工具、prompt + 工具定义不到 1,000 token,性能不输
2026-08-13How Compaction Works in Pi技术何时压缩、留多少、摘要 prompt 长什么样、为何破坏缓存
2026-08-20What is a Harness?科普harness 的四件事:system prompt、工具、循环、翻译层
2026-09-01There are many agent harnesses, but this one is mine.随笔一位非工程师写自己怎么把 pi 用成私人助理
2026-09-10Measuring the Sloppiness of Code度量verbosity / erosion 两个指标:agent 代码退化约为人类两倍
2026-09-29“You Said No MCP!”立场从「永不支持 MCP」到「用 Codemode 支持 MCP」的完整交代
2026-10-01Pi 1.0发布1.0 加了七项;没加进清单的更多
2026-10-01Pi Durable发布为长时运行 agent 做的实验性 substrate
2026-10-09There are many themes, but this one is yours设计新默认主题向终端索取颜色,一切决策围绕对比度
2026-10-16Pi 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 只做四件事:

“Firstly, they provide a set of instructions … typically called a "system prompt". Secondly, they describe and provide a set of tools … Thirdly, the harness establishes a framework that governs how the model behaves … establish the "agentic loop". Finally, most harnesses provide a crucial translation layer that enables the harness to work with a variety of different AI models.”
其一,提供一组指令,也就是「system prompt」;其二,描述并提供一组工具;其三,建立一个支配模型行为的框架,其中最主要的是「agentic loop」;最后,提供关键的翻译层,让同一个 harness 能配多种模型。
— What is a Harness?(2026-08-20)

把这句话和第 01 章的四层对照,会发现两者是同一张图: system prompt → 提示层、tools → 工具层、agentic loop → 循环层、translation layer → 模型层。 博客的第四条尤其值得注意,它是「能动性」论点的技术落点——作者说翻译层把议价能力从模型厂转移到用户手里:

“This translation layer helps take power and leverage away from the AI labs and into the hands of end users.”
这一层翻译把权力与杠杆从 AI 实验室转移到终端用户手中。
— What is a Harness?

这条在仓库里是可验证的:模型层被单独抽成一个包 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 + 智能工具发现:返回结构化数据、能被文档检索到。
为什么不干脆只要 Codemodepi 近期支持了延迟工具加载、会话中 system message、推理档位;但工具装载的元数据还没跟上——普通 MCP 扩展拿不到足够元数据去判断「这个工具该给模型看,还是只在 codemode 里可用」。

最后这条在仓库里有直接对应物——MCP 工具的暴露方式被做成了可选模式:

mcp-servers.ts:44-46
// - `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 缓存:

“This caching requires an exact prefix match, so compacting a session will break the prompt cache. … The retained turns contain the same tokens, but they now follow a different prefix.”
缓存要求前缀精确匹配,因此压缩会话会打断缓存。……被保留的轮次 token 没变,但它们跟随的前缀变了。
— How Compaction Works in Pi(2026-08-13)

这解释了第 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 到底是什么意思
使用方法上的一条提醒:这批文本里,信件与发布稿(前四篇、两篇 1.0)是立场文本, 数字多为对外口径、不带口径说明;技术深潜(compaction / caching / session / sloppiness / MCP)才适合当事实来源。 本章把后者逐条回仓库核对,共 5 条断言:4 条一致,1 条未能复核(<1,000 token,因为分词器口径未公开)。 其中 1 条需要换算才对齐:博客的「20k 默认预算」指 keepRecentTokens,不是 reserveTokens。

本章学习记录

记录仅保存在当前浏览器。