pi 系统学习手册 commit 531340f 分章阅读 架构图 时序图 GitHub
Learning Notes · 2026

pi 系统学习手册
最小,但不简单

pi 是一个刻意做小的 coding agent harness:核心只有 6 个源文件 2,541 行,却要驱动 95 个 provider 文件、43 个 API 适配文件、一棵可分支的会话树、一套完整的终端 UI 和可插拔的扩展系统。 这份手册把官方文档、仓库源码与作者本人写的复盘博客交叉对齐, 回答一个问题:它凭什么用这么少的代码做到这件事,代价又是什么。

repo earendil-works/pi node ≥22.19 license MIT packages 11 TS/TSX ~42 万行(含测试) 架构图 + 时序图 已校验
① 建立心智模型
四层、一个循环、四个概念,先有骨架再填肉。
5 min
② 读设计哲学
为什么作者要重写一个 agent,以及他砍掉了什么。
10 min
③ 顺着两张图走代码
每个方块都有 path:line,点到 GitHub 看真实实现。
20 min
④ 动手改造它
六个渐进练习:读会话、限工具、加指令、写扩展。
40 min
01

心智模型:四层、一个循环、四个概念

如果把 pi 压缩成一句话:它把「模型调用」收敛成一个函数,把「工具执行」收敛成一个循环, 把「界面」收敛成一个事件消费者。剩下的全是这三种东西的外围工程。

入口 终端输入 · --print · --mode json · RPC · SDK
▼输入 / 命令
④
渲染层pi-tui
保留模式组件树 + 差分渲染 + 同步输出。只消费事件,不改状态。
4.0 万行
tui.ts:506
▲事件流 text_delta · tool_call · toolResult
③
产品层pi-coding-agent
模式分发、AgentSession、会话树、工具集、扩展运行时、设置。
16.4 万行
agent-session.ts:379
▼prompt() / abort / 排队消息
②
循环层pi-agent-core
runAgentLoop:请求 → 工具 → 再请求,直到没有工具调用。
6 个源文件 / 2,541 行
agent-loop.ts:251
▼streamFn(model, context)
①
模型层pi-ai
4 个 HTTP 协议 → 1 个统一事件流;上下文可序列化、可跨厂商交接。
8.0 万行
95 provider / 43 API

反直觉的地方在于层数与体量的错位:真正决定 agent 行为的循环层只有 6 个源文件、2,541 行; 而产品层有 16.4 万行、模型层有 8 万行。也就是说,复杂度几乎全部堆在「协议翻译」和「产品外壳」上, 而不是「agent 智能」上。这也是作者反复强调的判断:agent 的智力来自模型本身, harness 的职责是把上下文组织好、把工具跑对、把过程显示清楚。

6
循环层源文件数
2,541
循环层 src 行数
164,445
产品层行数
79,996
模型层行数
4
需要统一的 HTTP 协议

四个必须先记住的概念

1一次请求由什么组成
system prompt + 活动分支的历史 + 可用工具定义 + 模型设置。 没有隐藏注入:你在 UI 里看到的,就是发给模型的。
2一个 turn 是什么
assistant 消息 +(可能的)工具调用与工具结果。 只要还有工具调用或排队消息,就再起一个 turn。
3一个 session 是什么
一棵树,不是一个数组。每条 entry 有 id/parentId, 从任意历史节点继续会在同一文件里长出新分支。
4一个界面是什么
事件流的消费者。交互式 TUI、--print、JSON 事件流、RPC、SDK 共用同一套 agent 与会话机制。

docs/how-pi-works.md agent-loop.ts:251 session-manager.ts:1187

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 与真实状态不一致?三个问题里有一个是「会」,那它就不会被做。
03

架构图:14 个组件、2 层边界

下面这张图是可校验的:每个组件的职责都绑定到具体的 path:line, 生成时通过了 schema 校验、布局校验与浏览器渲染校验。可以缩放、拖拽、切换明暗主题。

pi 运行时架构 · 14 components / 15 connections / 4 cards 新窗口 ↗

1× 是缩略总览——这张图画布宽 1750px,塞进 898px 的栏位里最小字号只剩约 3px,看不清是正常的。工具栏的 2× / 3× 会按比例放大并可在框内拖动: 实测最小字号依次为 3.2px → 6.7px → 10.3px。也可点 ⤢ 放大 全屏, 或 新窗口 ↗ 用图自身的缩放控件浏览。

怎么读这张图

  1. 从左到右是主路径:用户 → CLI → 模式外壳 → 会话核心 → agent 循环 → 模型层 → 厂商 API。
  2. 向下是副作用:工具执行落到工作区、会话落到磁盘、扩展挂钩到循环。
  3. 两个边界框不是装饰:外层 region 是「pi 进程内、可信核心」;内层 security-group 是 「用户代码沙箱边界」。扩展运行在同一个进程、同一套操作系统权限里,所以它被单独圈出来。
  4. 颜色即类型:进程内逻辑 / 渲染 / 持久化 / 用户代码 / 外部云服务 / 人,六种角色不混用。
组件职责证据(path:line)
cli解析参数、加载配置、按模式分发main.ts:623 main.ts:950
mode-interactive交互式 TUI 会话(7,110 行的热点)interactive-mode.ts:453
mode-headless--print / --mode json / RPCprint-mode.ts:33 rpc-mode.ts:54
tui保留模式组件树 + 差分渲染tui.ts:506
session一次会话的全部状态与编排agent-session.ts:379
loop请求 → 工具 → 再请求,直到结束agent-loop.ts:251 :737
ai / providers统一事件流 + 95 个 provider 文件stream-fn.ts:15 models.ts:1077
toolsread / write / edit / bash 等工具实现tools/index.ts:1 bash.ts:434
extensionsTypeScript 钩子:工具、命令、事件、UIloader.ts:831 runner.ts:364
storeJSONL 会话文件 + 设置session-manager.ts:1187 settings-manager.ts:272
注意这个不对称 核心小,外围厚。真正决定一次 run 走向的 agent-loop.ts 只有 6 个源文件; 而 interactive-mode.ts(7,110 行)和 agent-session.ts(4,458 行)是体量最大的两个热点。 读懂 pi 的难点从来不是 agent 算法,而是产品外壳的状态编排。
04

一次提问:13 条消息走完一个 turn

架构图回答「有哪些零件」,时序图回答「它们按什么顺序说话」。 下面这张图从用户敲下回车开始,到文本渲染上屏为止。

pi 单轮时序 · 8 participants / 13 messages / 3 fragments 新窗口 ↗

阅读顺序:自上而下三条时间线——① 用户输入到模型请求,② 工具调用与结果回填, ③ 再次请求到渲染上屏。虚线段表示落盘,斜跨的粗箭头是一次模型调用。 这张图画布较窄(952px),1× 下最小字号约 6px、2× 即可到 12px,通常不必开到 3×。

三个关键时刻

Ⅰ模型调用是唯一的出口
整个仓库里,模型请求只经过 streamFn(model, context) 这一个函数。 换 provider、换模型、走代理、加 trace,都只需要在这一层做。
Ⅱ工具执行是唯一的信任边界
prepare → validate → beforeToolCall → execute → afterToolCall。 参数校验、权限策略、审计、扩展挂钩,全都在这一条链上。
Ⅲ落盘发生在渲染之前
assistant 消息先追加进 JSONL,再交给 UI。 所以进程被 kill 也不会丢掉已完成的 turn——这正是可恢复性的前提。

为什么模型被调用两次?

因为工具结果也是「消息」。第一次 streamFn 返回的是「我要调用 bash」; 工具跑完后,结果作为一条 toolResult 追加进活动分支, 然后必须带着新历史再请求一次模型,它才知道命令输出了什么。 这个「再请求」就是 turn 的循环条件:只要还有工具调用,就再起一个 turn;否则 run 结束。

"The loop just loops until the agent says it's done."
这个循环就一直循环,直到 agent 说它做完了。
— 2025-11-30 博客 · 没有 max steps 这个旋钮

docs/how-pi-works.md · Agent loop agent-loop.ts:842 · tool.execute stream-fn.ts:15

05

六个关键机制

下面每一条都是「一个真实的问题 → 一个被验证过的解法」。 建议按顺序读,因为它们从协议层一路爬到产品层。点击标题展开。

① 四个 API 统一成一个事件流 pi-ai
"There's really only four APIs you need to speak to talk to pretty much any LLM provider: OpenAI's Completions API, their newer Responses API, Anthropic's Messages API, and Google's Generative AI API."
要和几乎所有 LLM 厂商对话,你其实只需要说四种 API:OpenAI 的 Completions、OpenAI 的 Responses、Anthropic 的 Messages、Google 的 Generative AI。

这个判断是整个模型层的地基。它意味着 pi-ai 不需要为每一家厂商写一套逻辑, 只需要写四个 HTTP 适配器,再用「模型描述」把厂商差异声明出来。

但四个协议只是起点,真正的成本在厂商各自的「方言」上。作者列过一份很实在的清单:

  • Cerebras、xAI、Mistral、Chutes 不喜欢 store 字段
  • Mistral、Chutes 用 max_tokens 而不是 max_completion_tokens
  • Cerebras、xAI、Mistral、Chutes 不支持 system prompt 用 developer 角色
  • Grok 系列不喜欢 reasoning_effort
  • 不同厂商把推理内容放在不同字段:reasoning_content vs reasoning

值得注意的是现在仓库里的处理方式变了:不是硬编码厂商名,而是做运行时归一化与字段回退 ——例如 OPENAI_COMPLETIONS_REASONING_FIELDS 依次尝试 reasoning / reasoning_content / reasoning_text, max_tokens 与 max_completion_tokens 统一收口到一个上限计算函数。 这是从「补丁」走向「契约」的典型演进。

还有两个作者点名的问题,值得所有做统一 API 的人记住:

!token 与缓存计量是狂野西部
有的厂商在 SSE 开头就报 token,有的只在结尾报;请求一旦 abort 就永远拿不到准确值。pi-ai 只能做 best-effort 统计。
!Google 至今不支持工具调用流式
作者的原话是一句冷笑话级的吐槽:"extremely Google"。

openai-completions.ts:279 anthropic-messages.ts:660 models.ts:1077 · createProvider

② 跨 provider 的上下文交接 handoff
"Context handoff between providers was a feature pi-ai was designed for from the start."
跨 provider 的上下文交接,是 pi-ai 从一开始就设计好的能力。

这是 pi 相对多数 harness 的一个明显差异化能力:会话中途换模型,历史不丢。 代价是必须做一层有损转换——每家厂商对「工具调用」和「思维链」的表示都不同。

  • 从 Anthropic 切到 OpenAI 时,Anthropic 的 thinking trace 会被转成 <thinking>...</thinking> 包裹的内容块
  • 厂商还会往事件流里插入签名 blob,后续带相同消息的请求必须原样回放; 同厂商内换模型也一样
  • 所以这是一条「尽力而为」的转换管线,语义上并不保证等价
工程含义 这解释了一个常见困惑:为什么 pi 的 message 类型看起来比 SDK 更「胖」。 因为它必须能同时容纳四家厂商的私有表示,才能在序列化后仍然可交接。 JSON.stringify(context) 之后换任何模型都能继续—— 这是把「会话」当一等公民的直接结果。

同一条设计线还带来两个能力:全链路 abort(连工具调用阶段也能中断, 并返回部分结果与 stopReason: 'aborted'),以及 浏览器内可用(Anthropic 与 xAI 支持 CORS)。

docs/models.md docs/message-types.md

③ 工具结果拆成「给模型的」和「给界面的」 tool result

这是作者认为「所有统一 LLM API 都缺」的一个抽象。通常工具只能返回一段文本, 于是 UI 想要漂亮地展示结果,就得去 parse 那段文本再重新结构化——既脆弱又浪费。

pi 的做法是让工具同时返回两个东西:

typescript
const weatherTool: AgentTool<typeof weatherSchema, { temp: number }> = {
  name: 'get_weather',
  execute: async (toolCallId, args) => ({
    // 给模型看的:文本或 JSON
    output: `Temperature in ${args.city}: ${temp}°C`,
    // 给 UI 看的:结构化数据,不用再解析文本
    details: { temp },
  }),
};
  • 参数用 TypeBox schema + AJV 自动校验,失败时给出详细错误信息
  • 工具还能返回图片等附件,并按各 provider 的原生格式附着
  • 这条设计让「模型看到的内容」和「人看到的内容」可以解耦, 也让 TUI 渲染不需要理解业务语义

docs/extensions.md tools/write.ts:82

④ system prompt:从一段文本变成可组装的契约 prompt

博客里给出的原始 system prompt 非常短,核心只有三部分:角色、工具清单、行为准则。

system prompt(2025-11 博客原文节选)
You are an expert coding assistant. You help users with coding tasks by
reading files, executing commands, editing code, and writing new files.

Available tools:
- read: Read file contents
- bash: Execute bash commands
- edit: Make surgical edits to files
- write: Create or overwrite files

Guidelines:
- Use bash for file operations like ls, grep, find
- Use read to examine files before editing
...
"pi's system prompt and tool definitions together come in below 1000 tokens."
pi 的 system prompt 加上工具定义,加起来不到 1000 token。

而仓库现状已经演进了:prompt 不再是硬编码字符串,而是由 buildSystemPromptSections() 组装出的若干可独立替换的 section。

section内容谁决定
preamble角色定义;若提供 customPrompt 则整段替换内置默认 / 用户
tools仅列出实际可见的工具及其一行说明当前工具选择
rules按启用工具动态生成(有 bash 无 grep 才提示用 bash 找文件)工具集 + 扩展
docs指向 README / docs / examples 的按需阅读索引内置
project_contextAGENTS.md 等项目上下文文件项目目录
skills可用 skill 的描述(完整指令按需加载)发现结果
addendum--append-system-prompt 追加内容命令行 / 扩展

这个演进很关键:它把「prompt 稳定性」从作者的自我约束变成了结构保证。 工具增删不会污染无关段落,扩展可以只改自己那一节,用户甚至可以整段替换 preamble。 这正好回应了他对「每次发版 prompt 都变」的抱怨。

system-prompt.ts:124 · buildSystemPromptSections :156 · 默认 preamble

⑤ 最小工具集:四个就够 tools
"As it turns out, these four tools are all you need for an effective coding agent. Models know how to use bash and have been trained on the read, write, and edit tools with similar input schemas."
事实证明,这四个工具就是高效 coding agent 所需的全部。模型会用 bash,而且已经被训练过输入 schema 相似的 read / write / edit 工具。
rread
按行读取,支持图片附件;默认前 2000 行,用 offset/limit 翻页。
wwrite
整文件写入,不存在则创建,自动建父目录。
eedit
精确文本替换,oldText 必须完全匹配(含空白)。
$bash
在当前工作目录执行命令,返回 stdout/stderr,可选超时。

另外还有 grep / find / ls 三个只读工具, 以及 Windows 上的 powershell;这些默认关闭,只在需要限制 agent 写权限时启用。 --tools 参数可以精确控制暴露哪些工具,包括按命名空间通配(如 'mcp__radius__*')。

为什么这能成立 因为「工具描述的 token 成本」是每轮都要付的。四个工具 ≈ 几百 token, 而某些 MCP 服务器光工具定义就是 1.4 万~1.8 万 token(见第 07 节)。 在长会话里,这个差值是复利。

tools/index.ts docs/cli.md · --tools

⑥ 默认 YOLO:不做权限系统,改做隔离 security
"pi runs in full YOLO mode and assumes you know what you're doing. It has unrestricted access to your filesystem and can execute any command without permission checks or safety rails."
pi 以完全 YOLO 模式运行,并假设你知道自己在做什么。它可以不受限制地访问文件系统,执行任何命令,没有权限检查,也没有安全护栏。

作者给出的论证是一个三段论,很值得完整理解:

  1. 只要能读私有数据、执行代码、访问网络,数据外泄就无法用提示层拦住了
  2. 要真正拦住,只能切断网络——但那样 agent 基本没用;域名白名单也能被绕过
  3. 所以大多数 harness 的权限提示是安全剧场:反正大家为了干活都会一路点同意

结论不是「不安全没关系」,而是把安全边界从「提示」下移到「隔离」。官方文档把可选方案列得很清楚:

运行方式被保护的是什么强度
直接用当前 OS 用户运行只有该用户访问不到的东西最弱
整个 pi 跑在容器 / VM / 沙箱里未暴露进环境的主机文件与进程最强实用选项
pi 在外,只有内置工具进沙箱仅工具侧动作受限;pi 自身与扩展仍在边界外折中
必须知道的一点 扩展与工具运行在同一个进程、同一套操作系统权限下。 所以「装一个扩展」=「允许它读你的凭据、会话历史和任意文件」。 这条在文档里写得非常直白,也解释了为什么架构图里要把 extensions 单独圈成 security-group。

docs/security.md docs/containerization.md README · 无内置权限系统

06

会话与上下文:一棵树,三段算法

这是 pi 最值得抄走的设计。多数 agent 把会话存成「消息数组」, pi 存成一棵可分支的树,于是「回到某个节点重新试一次」不需要复制文件, 只需要在同一个文件里长出一个新分支。

存储形态:一行一个 entry 的 JSONL

~/.pi/agent/sessions/--<path>--/<timestamp>_<session-id>.jsonl
{"type":"session", "version":3, "id":"...", "parentId":null}
{"type":"message", "id":"a1", "parentId":"...", "role":"user", ...}
{"type":"message", "id":"a2", "parentId":"a1", "role":"assistant", ...}
{"type":"model_change", "id":"a3", "parentId":"a2", ...}
{"type":"usage", "id":"a4", "parentId":"a3", ...}
{"type":"compaction", "id":"a5", "parentId":"a4", "firstKeptEntryId":"a2", ...}

只有十二种 entry 类型:session、message、model_change、 thinking_level_change、usage、compaction、context_edit、 branch_summary、custom、custom_message、label、session_info。 注意其中有一半根本不是消息:换模型、改思考等级、花销统计、压缩、手动改上下文都是显式条目。 这就是作者说的「cleanly documented session format」—— 你能精确知道某个 turn 为什么用了那个模型、花了多少 token。

树结构:分支与 leaf

[user]─ [assistant]─ [user]─ [assistant]
  • [user]← 当前 leaf(active branch 末端)
  • [branch_summary]─[user]← 另一条分支,文件里一直保留

切分支不是「回退删除」,而是把 leaf 移到另一个节点。 被放弃的分支仍在文件里,随时可以切回去。这一点和 git 的心智模型几乎一致。

三段算法:从文件到「要发给模型的 messages」

1buildContextEntries()
从 leaf 向 root 回溯,得到活动路径上的条目;若路径上存在 compaction, 取最新那一个:先放压缩条目,再放 firstKeptEntryId 到压缩条目之间的非系统条目, 最后放压缩条目之后的全部条目。非消息条目被保留,因为 UI 还要渲染它们。
2buildSessionProjection()
对每个目标应用最新的 context_edit:被省略的目标不产生消息, 被替换的目标只改内容、保留原有 role 与元数据。原始条目永不被修改。
3buildSessionContext()
把选中条目转成消息:message → 原样;compaction → 完整 checkpoint + 摘要; branch_summary → branchSummary;context_edit / usage / custom → 不产生上下文消息。
这个设计的好处 「改上下文」变成了一次可审计的编辑,而不是在一个数组上原地 splice。 压缩之后你依然能回看原始条目;扩展也能在 context 事件里改写投影, 而不破坏磁盘上的历史。

两种摘要机制,别混用

机制触发目的
Compaction上下文超过阈值,或手动 /compact把旧消息压缩成摘要,腾出上下文窗口
Branch summarization用 /tree 切换分支时保留旧分支的要点,避免切过去后完全失忆

两者共享同一套结构化格式,并且都会累积追踪文件操作。 一个很细但重要的实现细节:摘要请求会禁用 prompt-cache 写入, 因为这是一次性 prompt,写缓存纯属浪费。

消息排队:steering 与 follow-up

这是交互体验的关键差异点,也是很多人第一次用 pi 会困惑的地方:

  • Steering message:你在 agent 干活时插话,它会在当前 assistant turn 之后立刻进入上下文,用来中途纠偏
  • Follow-up message:排队等 agent 把手头的事做完再进来
  • Abort:停止当前 run,并把还没消费的排队消息退回编辑器——不丢你的输入
"the loop also supports message queuing via a callback: after each turn, it asks for queued messages and injects them before the next assistant response."
循环还通过回调支持消息排队:每个 turn 之后,它去问有没有排队消息,并在下一次 assistant 回复前注入。

用 jq 直接读会话

因为格式就是 JSONL,你可以不写一行代码就做分析:

bash
# 最近一个会话文件
f=$(ls -t ~/.pi/agent/sessions/*/*.jsonl | head -1)

# 这次会话用了哪些模型、什么时候换的
jq -r 'select(.type=="model_change") | "\(.timestamp) \(.provider)/\(.modelId)"' "$f"

# 每个 turn 的 token 花销
jq -r 'select(.type=="usage") | "\(.input) in / \(.output) out"' "$f"

# 统计工具调用次数
jq -r 'select(.type=="message" and .role=="assistant") | .content[]?
        | select(.type=="toolCall") | .name' "$f" | sort | uniq -c | sort -rn

docs/session-format.md docs/compaction.md session-manager.ts:1187

07

刻意不做:五条「不」与它们的替代方案

这一节是 pi 与 Claude Code / Codex 分歧最大的地方,也是最容易被误解的地方。 每一条都不是「没做」,而是「想清楚了不做」。

不做理由(作者原话要点)替代方案
内置 TODO 列表 agent 自己写一个 TODO.md 就够了,不需要专门的工具和状态机 让模型用 write/edit 维护 md 文件
Plan mode 一个 PLAN.md 加一轮对话就是 plan mode,不需要第二套模式与状态 写 md + 人审 + 再执行
后台 bash 要进程追踪、输出缓冲、退出清理、向运行中进程发输入;且观测性差 tmux:可 attach、可列会话、可人机共调
Sub-agents 黑盒套黑盒,上下文传递不可控,出错难调 让它用 bash 再起一个 pi --print(可放 tmux 里)
MCP (已变化) 多数场景过重,工具定义常驻上下文开销大 CLI + README,按需阅读(渐进披露)

关于 MCP:一次公开的立场调整

博客里写得很绝对:

"pi does not and will not support MCP. […] MCP servers are overkill for most use cases, and they come with significant context overhead."
pi 不支持 MCP,将来也不会。……多数场景下 MCP 服务器属于杀鸡用牛刀,而且它们带来显著的上下文开销。
— 2025-11-30 博客

他给出的数字很有说服力:Playwright MCP 有 21 个工具、约 13.7k token;Chrome DevTools MCP 有 26 个工具、约 18k token。 也就是开工前 7–9% 的上下文窗口就没了,而其中大部分工具这次会话根本用不到。

但在当前仓库(commit 531340f,2026-10-27)里,MCP 已经是一等公民:

bash
pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
pi mcp add docs --url https://example.com/mcp --bearer-token-env-var DOCS_TOKEN
pi mcp list
# 会话内用 /mcp 查看连接、登录、重连、改暴露范围、启停

这个变化本身就是最好的学习材料:它说明「最小」不是教条,而是可以被真实需求推翻的假设。 值得注意的是实现方式——MCP 工具被当作工具命名空间注入(mcp__<server>__<tool>), 因此仍然服从统一的工具管线与 --tools 过滤,而不是另开一套机制。 这与「保持单一信任边界」的原则是一致的。

关于 sub-agent:不是否定,而是归位

"I'm not dismissing sub-agents entirely." / "models are still poor at finding all the context needed for implementing a new feature or fixing a bug."
我并不完全否定 sub-agent。/模型至今仍然不擅长找齐「实现新功能或修 bug」所需的全部上下文。

作者真正的观点比「不要 sub-agent」更锐利:在会话中途用 sub-agent 收集上下文,说明你没有提前规划。 正确做法是先在独立会话里把上下文收集好、产出成一份可复用的工件(artifact), 再开新会话带着它干活。这样既有完整可观测性,工件还能给下一个需求复用。

诚实提示 博客是 2025-11-30 的快照,仓库是 2026-10-27 的状态。两者有约 11 个月的差距。 本文所有「博客说」都标注了出处;涉及现状的都用源码或文档佐证。第 09 节专门列了差异表。
08

扩展与集成:五个机制、五种接入

pi 砍掉了内置功能,但把「加功能」做得很便宜。官方文档的建议是 选满足需求的最小机制——从纯文本到可执行代码,一共五档。

机制是什么成本 / 边界
AGENTS.md项目上下文文件,自动注入 system prompt 的 project_context零成本,纯文本;最该先试的一档
Prompt template斜杠命令模板,在输入变 user message 前展开纯文本;适合固定流程
Skill专门指令集,只有描述常驻,完整内容按需加载渐进披露,省 token
ExtensionTypeScript 模块:注册工具、命令、快捷键、provider、事件钩子、状态栏、UI与 pi 同权限;能改上下文与拦截工具调用
Theme终端配色与样式纯展示

其中 Extension 是唯一有执行权限的一档,所以它也是唯一被单独圈进 security-group 的一档。最小例子:

~/.pi/agent/extensions/hello.ts
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.registerCommand("hello", {
    description: "Show a greeting",
    handler: async (name, ctx) => {
      ctx.ui.notify(`Hello, ${name || "world"}!`, "info");
    },
  });
}
bash
pi --extension ./hello.ts   # 开发期直接加载,jiti 免编译
# 会话内输入 /hello 触发

五种接入方式,一套核心

这是「渲染是纯消费者」这一架构带来的直接好处:

方式场景入口
交互式 TUI日常开发pi
Print脚本 / CI / 一次性任务pi --print "..."
JSON 事件流结构化消费、自己的 UIpi --mode json
RPC控制一个独立 pi 进程(跨语言)stdin/stdout JSON 协议
TypeScript SDK嵌入到 Node/Bun 应用里createAgentSession()
typescript · SDK 最小示例
import { createAgentSession } from "@earendil-works/pi-coding-agent";

const { session } = await createAgentSession();
try {
  await session.prompt("What files are in the current directory?");
  console.log(session.getLastAssistantText());
} finally {
  session.dispose();
}

session.prompt() 在整轮跑完后才 resolve;想流式取文本就订阅事件。 SessionManager 是最终上下文的唯一权威——直接改 session.agent.state.messages 不会改变持久化上下文,这一点在文档里被特别强调。

docs/extensions.md docs/sdk.md docs/packages.md

09

一年演进:博客是快照,仓库是现状

这是把两个素材源交叉验证后最有价值的产出。只看博客会学到过时的结论,只看代码会不知道设计意图。 下面每一行都能在仓库里找到对应证据。

主题博客(2025-11-30)仓库(531340f,2026-10-27)
MCP 明确不支持,且「将来也不会」 支持:pi mcp add/list/remove、/mcp、packages/mcp
system prompt 一段静态字符串,约 20 行 7 个可独立替换的 section,可按工具集动态生成 rules
工具集 默认 4 个(read/write/edit/bash) + grep / find / ls / powershell、codemode、MCP 命名空间工具
包名 @mariozechner/pi-ai 等 @earendil-works/*(含 chord、pi-telemetry 等)
仓库形态 以 coding agent 为中心 11 包 monorepo:ai / agent / tui / coding-agent / durable / chord / codemode / mcp / env / evals / telemetry
会话格式 JSONL + 树 同一思路,但已显式版本化(version 字段),entry 类型固定为 12 种
非 LLM 模型 未涉及 codemode 引入分类器 / 图像模型等非对话模型
安全表述 「权限提示是安全剧场」 保留该立场,但补了完整文档:security / containerization / project trust
从这张表里能学到什么 1. 立场会变,原则不变。MCP 从「不做」变成「做」,但实现方式仍然服从统一的工具管线与工具过滤, 没有变成第二个平行的能力系统。
2. 可观测性诉求一路加强。system prompt 从一整块变成可替换分节、会话格式加版本号, 都是为了让「模型到底看到了什么」更可解释。
3. 外围包在扩张。durable(7.4 万行)、chord(3.5 万行)这些包的体量远超 agent 核心, 说明产品化成本主要落在工作流、编排与持久化上,而不是 agent 循环本身。

顺带一个数字:基准测试

作者用 Terminal-Bench 2.0 做了完整跑测(每个任务 5 次试验,达到提交排行榜的要求), 让 pi + Claude Opus 4.5 与 Codex、Cursor、Windsurf 等 harness 各自搭配原生模型比较。 他特别提到榜单上 Terminus 2 的表现:那个 agent 只给模型一个 tmux 会话, 没有花哨工具,只靠文本命令与终端输出解析,却能和一些工具复杂得多的 agent 打平。

"More evidence that a minimal approach can do just as well."
这进一步证明,最小化的方法同样能做得一样好。

这句话其实是整份手册的论点小结:能力来自模型,harness 的职责是不挡路。

10

动手练习:六个渐进任务

每个练习都能在 5–15 分钟内完成,并且刻意对应前面某一节。 建议按顺序做,因为它们从「观察」逐步走到「改造」。

1
装上并跑通一次
对应第 01 节 · 目标是确认四层结构在你机器上真的串起来了
bash
curl -fsSL https://pi.dev/install.sh | sh
# 或: npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# 需要 Node.js 22.19+

pi            # 进入交互模式,用 /login 或 /model 配置模型
pi --print "用三句话说明这个仓库是做什么的"
2
拆开一次会话看结构
对应第 06 节 · 亲眼看到「树」而不是「数组」
bash
f=$(ls -t ~/.pi/agent/sessions/*/*.jsonl | head -1)
wc -l "$f"
jq -r '[.type, (.id//"-"), (.parentId//"ROOT")] | @tsv' "$f" | head -20

观察点:parentId 如何串成链、usage 与 model_change 也在其中。

3
用只读工具集做一次代码审查
对应第 05 节 ⑤ · 体验「工具集就是权限边界」
bash
pi --tools read,grep,find,ls --print "审查 packages/agent,列出三个设计风险"
# 没有 bash / write / edit,agent 物理上无法改文件
4
给 system prompt 追加约束
对应第 05 节 ④ · 体验 addendum 分节
bash
cat > /tmp/strict.md <<'EOF'
- 任何修改前,先用 read 完整读完目标文件
- 报告里必须给出 file:line 证据
EOF

pi --append-system-prompt /tmp/strict.md --print "检查 bash 工具的超时处理"
5
写第一个扩展
对应第 08 节 · 从「使用者」变成「改造者」
bash
mkdir -p ~/.pi/agent/extensions
cat > ~/.pi/agent/extensions/hello.ts <<'EOF'
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.registerCommand("hello", {
    description: "Show a greeting",
    handler: async (name, ctx) => {
      ctx.ui.notify(`Hello, ${name || "world"}!`, "info");
    },
  });
}
EOF

pi --extension ~/.pi/agent/extensions/hello.ts
# 会话内输入 /hello

进阶:改成 beforeToolCall 钩子,记录每次 bash 命令,就能自己造审计日志。

6
用 SDK 嵌入十行代码
对应第 08 节 · 验证「UI 是可替换的」
typescript
import { createAgentSession } from "@earendil-works/pi-coding-agent";

const { session } = await createAgentSession();
try {
  await session.prompt("列出当前目录的文件,并说明各自用途");
  console.log(session.getLastAssistantText());
} finally {
  session.dispose();
}

想做无文件会话:createAgentSession({ sessionManager: SessionManager.inMemory() })。

11

延伸阅读

按「先建立模型,再看细节,最后看动机」的顺序排的。

官方文档(仓库内)

作者博客(设计动机)

官方博客(Earendil,16 篇,2026-01 → 2026-10)

本仓库里的配套产物

一句话总结

"Twitter is full of context engineering posts and blogs, but I feel like none of the harnesses we currently have actually let you do context engineering. pi is my attempt to build myself a tool where I'm in control as much as possible."
Twitter 上全是关于上下文工程的文章,但我觉得我们现有的 harness 没有一个真正让你能做上下文工程。pi 是我为自己打造的一个工具,让我尽可能地掌控一切。

读到这里再回看整份手册,你会发现 pi 的所有设计都在服务同一件事: 让你能准确说出「模型这一刻到底看到了什么」,并且能改它。 如果你只带走一句话,就带这句。

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。