pi 系统学习手册
最小,但不简单
pi 是一个刻意做小的 coding agent harness:核心只有 6 个源文件 2,541 行,却要驱动 95 个 provider 文件、43 个 API 适配文件、一棵可分支的会话树、一套完整的终端 UI 和可插拔的扩展系统。 这份手册把官方文档、仓库源码与作者本人写的复盘博客交叉对齐, 回答一个问题:它凭什么用这么少的代码做到这件事,代价又是什么。
心智模型:四层、一个循环、四个概念
如果把 pi 压缩成一句话:它把「模型调用」收敛成一个函数,把「工具执行」收敛成一个循环, 把「界面」收敛成一个事件消费者。剩下的全是这三种东西的外围工程。
--print · --mode json · RPC · SDKtui.ts:506
agent-session.ts:379
agent-loop.ts:251
95 provider / 43 API
反直觉的地方在于层数与体量的错位:真正决定 agent 行为的循环层只有 6 个源文件、2,541 行; 而产品层有 16.4 万行、模型层有 8 万行。也就是说,复杂度几乎全部堆在「协议翻译」和「产品外壳」上, 而不是「agent 智能」上。这也是作者反复强调的判断:agent 的智力来自模型本身, harness 的职责是把上下文组织好、把工具跑对、把过程显示清楚。
四个必须先记住的概念
id/parentId,
从任意历史节点继续会在同一文件里长出新分支。--print、JSON 事件流、RPC、SDK
共用同一套 agent 与会话机制。docs/how-pi-works.md agent-loop.ts:251 session-manager.ts:1187
设计哲学:把「我不需要」写进架构
理解 pi 最快的路径不是读代码,而是读作者抱怨了什么。2025 年 11 月 30 日那篇 复盘长文 里,几乎所有架构决策都能对应到一条具体的不满。
不满一:工具变成了飞船
三个抱怨都非常具体:功能膨胀、接口不稳定、渲染抖动。它们分别对应 pi 的三个工程决策: 砍功能(第 07 节)、把 prompt 与工具定义做成可组装的稳定契约、自己写差分渲染的 TUI。
不满二:harness 在背后偷偷注入上下文
这句话解释了很多看起来「反直觉」的设计。比如为什么 pi 的 system prompt 短到只有几百 token、 为什么工具只有四个、为什么不做 sub-agent:每一项被砍掉的能力,都是一段你无法控制的隐式上下文。 能力越少,你能看见、能预测、能改写的东西就越多。
不满三:无法观测,也无法二次开发
这三句话直接对应三个可验证的产物:
--mode json 可以把整个 run 导出成事件流。id/parentId 组成树。用 jq 就能分析。总纲:一句话的取舍原则
这句话最好和另一句放在一起读——它说明了 pi 的真实目标不是「最小」本身, 而是把控制权交回使用者:
架构图:14 个组件、2 层边界
下面这张图是可校验的:每个组件的职责都绑定到具体的 path:line,
生成时通过了 schema 校验、布局校验与浏览器渲染校验。可以缩放、拖拽、切换明暗主题。
1× 是缩略总览——这张图画布宽 1750px,塞进 898px 的栏位里最小字号只剩约 3px,看不清是正常的。工具栏的 2× / 3× 会按比例放大并可在框内拖动: 实测最小字号依次为 3.2px → 6.7px → 10.3px。也可点 ⤢ 放大 全屏, 或 新窗口 ↗ 用图自身的缩放控件浏览。
怎么读这张图
- 从左到右是主路径:用户 → CLI → 模式外壳 → 会话核心 → agent 循环 → 模型层 → 厂商 API。
- 向下是副作用:工具执行落到工作区、会话落到磁盘、扩展挂钩到循环。
- 两个边界框不是装饰:外层 region 是「pi 进程内、可信核心」;内层 security-group 是 「用户代码沙箱边界」。扩展运行在同一个进程、同一套操作系统权限里,所以它被单独圈出来。
- 颜色即类型:进程内逻辑 / 渲染 / 持久化 / 用户代码 / 外部云服务 / 人,六种角色不混用。
| 组件 | 职责 | 证据(path:line) |
|---|---|---|
| cli | 解析参数、加载配置、按模式分发 | main.ts:623 main.ts:950 |
| mode-interactive | 交互式 TUI 会话(7,110 行的热点) | interactive-mode.ts:453 |
| mode-headless | --print / --mode json / RPC | print-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 |
| tools | read / write / edit / bash 等工具实现 | tools/index.ts:1 bash.ts:434 |
| extensions | TypeScript 钩子:工具、命令、事件、UI | loader.ts:831 runner.ts:364 |
| store | JSONL 会话文件 + 设置 | session-manager.ts:1187 settings-manager.ts:272 |
agent-loop.ts 只有 6 个源文件;
而 interactive-mode.ts(7,110 行)和 agent-session.ts(4,458 行)是体量最大的两个热点。
读懂 pi 的难点从来不是 agent 算法,而是产品外壳的状态编排。
一次提问:13 条消息走完一个 turn
架构图回答「有哪些零件」,时序图回答「它们按什么顺序说话」。 下面这张图从用户敲下回车开始,到文本渲染上屏为止。
阅读顺序:自上而下三条时间线——① 用户输入到模型请求,② 工具调用与结果回填, ③ 再次请求到渲染上屏。虚线段表示落盘,斜跨的粗箭头是一次模型调用。 这张图画布较窄(952px),1× 下最小字号约 6px、2× 即可到 12px,通常不必开到 3×。
三个关键时刻
streamFn(model, context) 这一个函数。
换 provider、换模型、走代理、加 trace,都只需要在这一层做。prepare → validate → beforeToolCall → execute → afterToolCall。
参数校验、权限策略、审计、扩展挂钩,全都在这一条链上。为什么模型被调用两次?
因为工具结果也是「消息」。第一次 streamFn 返回的是「我要调用 bash」;
工具跑完后,结果作为一条 toolResult 追加进活动分支,
然后必须带着新历史再请求一次模型,它才知道命令输出了什么。
这个「再请求」就是 turn 的循环条件:只要还有工具调用,就再起一个 turn;否则 run 结束。
docs/how-pi-works.md · Agent loop agent-loop.ts:842 · tool.execute stream-fn.ts:15
六个关键机制
下面每一条都是「一个真实的问题 → 一个被验证过的解法」。 建议按顺序读,因为它们从协议层一路爬到产品层。点击标题展开。
① 四个 API 统一成一个事件流 pi-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_contentvsreasoning
值得注意的是现在仓库里的处理方式变了:不是硬编码厂商名,而是做运行时归一化与字段回退
——例如 OPENAI_COMPLETIONS_REASONING_FIELDS 依次尝试
reasoning / reasoning_content / reasoning_text,
max_tokens 与 max_completion_tokens 统一收口到一个上限计算函数。
这是从「补丁」走向「契约」的典型演进。
还有两个作者点名的问题,值得所有做统一 API 的人记住:
openai-completions.ts:279 anthropic-messages.ts:660 models.ts:1077 · createProvider
② 跨 provider 的上下文交接 handoff
这是 pi 相对多数 harness 的一个明显差异化能力:会话中途换模型,历史不丢。 代价是必须做一层有损转换——每家厂商对「工具调用」和「思维链」的表示都不同。
- 从 Anthropic 切到 OpenAI 时,Anthropic 的 thinking trace 会被转成
<thinking>...</thinking>包裹的内容块 - 厂商还会往事件流里插入签名 blob,后续带相同消息的请求必须原样回放; 同厂商内换模型也一样
- 所以这是一条「尽力而为」的转换管线,语义上并不保证等价
JSON.stringify(context) 之后换任何模型都能继续——
这是把「会话」当一等公民的直接结果。
同一条设计线还带来两个能力:全链路 abort(连工具调用阶段也能中断,
并返回部分结果与 stopReason: 'aborted'),以及
浏览器内可用(Anthropic 与 xAI 支持 CORS)。
③ 工具结果拆成「给模型的」和「给界面的」 tool result
这是作者认为「所有统一 LLM API 都缺」的一个抽象。通常工具只能返回一段文本, 于是 UI 想要漂亮地展示结果,就得去 parse 那段文本再重新结构化——既脆弱又浪费。
pi 的做法是让工具同时返回两个东西:
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 渲染不需要理解业务语义
④ system prompt:从一段文本变成可组装的契约 prompt
博客里给出的原始 system prompt 非常短,核心只有三部分:角色、工具清单、行为准则。
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 ...
而仓库现状已经演进了:prompt 不再是硬编码字符串,而是由
buildSystemPromptSections() 组装出的若干可独立替换的 section。
| section | 内容 | 谁决定 |
|---|---|---|
preamble | 角色定义;若提供 customPrompt 则整段替换 | 内置默认 / 用户 |
tools | 仅列出实际可见的工具及其一行说明 | 当前工具选择 |
rules | 按启用工具动态生成(有 bash 无 grep 才提示用 bash 找文件) | 工具集 + 扩展 |
docs | 指向 README / docs / examples 的按需阅读索引 | 内置 |
project_context | AGENTS.md 等项目上下文文件 | 项目目录 |
skills | 可用 skill 的描述(完整指令按需加载) | 发现结果 |
addendum | --append-system-prompt 追加内容 | 命令行 / 扩展 |
这个演进很关键:它把「prompt 稳定性」从作者的自我约束变成了结构保证。 工具增删不会污染无关段落,扩展可以只改自己那一节,用户甚至可以整段替换 preamble。 这正好回应了他对「每次发版 prompt 都变」的抱怨。
system-prompt.ts:124 · buildSystemPromptSections :156 · 默认 preamble
⑤ 最小工具集:四个就够 tools
另外还有 grep / find / ls 三个只读工具,
以及 Windows 上的 powershell;这些默认关闭,只在需要限制 agent 写权限时启用。
--tools 参数可以精确控制暴露哪些工具,包括按命名空间通配(如 'mcp__radius__*')。
⑥ 默认 YOLO:不做权限系统,改做隔离 security
作者给出的论证是一个三段论,很值得完整理解:
- 只要能读私有数据、执行代码、访问网络,数据外泄就无法用提示层拦住了
- 要真正拦住,只能切断网络——但那样 agent 基本没用;域名白名单也能被绕过
- 所以大多数 harness 的权限提示是安全剧场:反正大家为了干活都会一路点同意
结论不是「不安全没关系」,而是把安全边界从「提示」下移到「隔离」。官方文档把可选方案列得很清楚:
| 运行方式 | 被保护的是什么 | 强度 |
|---|---|---|
| 直接用当前 OS 用户运行 | 只有该用户访问不到的东西 | 最弱 |
| 整个 pi 跑在容器 / VM / 沙箱里 | 未暴露进环境的主机文件与进程 | 最强实用选项 |
| pi 在外,只有内置工具进沙箱 | 仅工具侧动作受限;pi 自身与扩展仍在边界外 | 折中 |
会话与上下文:一棵树,三段算法
这是 pi 最值得抄走的设计。多数 agent 把会话存成「消息数组」, pi 存成一棵可分支的树,于是「回到某个节点重新试一次」不需要复制文件, 只需要在同一个文件里长出一个新分支。
存储形态:一行一个 entry 的 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]← 当前 leaf(active branch 末端)
- [branch_summary]─[user]← 另一条分支,文件里一直保留
切分支不是「回退删除」,而是把 leaf 移到另一个节点。 被放弃的分支仍在文件里,随时可以切回去。这一点和 git 的心智模型几乎一致。
三段算法:从文件到「要发给模型的 messages」
firstKeptEntryId 到压缩条目之间的非系统条目,
最后放压缩条目之后的全部条目。非消息条目被保留,因为 UI 还要渲染它们。context_edit:被省略的目标不产生消息,
被替换的目标只改内容、保留原有 role 与元数据。原始条目永不被修改。message → 原样;compaction → 完整 checkpoint + 摘要;
branch_summary → branchSummary;context_edit / usage / custom → 不产生上下文消息。context 事件里改写投影,
而不破坏磁盘上的历史。
两种摘要机制,别混用
| 机制 | 触发 | 目的 |
|---|---|---|
| Compaction | 上下文超过阈值,或手动 /compact | 把旧消息压缩成摘要,腾出上下文窗口 |
| Branch summarization | 用 /tree 切换分支时 | 保留旧分支的要点,避免切过去后完全失忆 |
两者共享同一套结构化格式,并且都会累积追踪文件操作。 一个很细但重要的实现细节:摘要请求会禁用 prompt-cache 写入, 因为这是一次性 prompt,写缓存纯属浪费。
消息排队:steering 与 follow-up
这是交互体验的关键差异点,也是很多人第一次用 pi 会困惑的地方:
- Steering message:你在 agent 干活时插话,它会在当前 assistant turn 之后立刻进入上下文,用来中途纠偏
- Follow-up message:排队等 agent 把手头的事做完再进来
- Abort:停止当前 run,并把还没消费的排队消息退回编辑器——不丢你的输入
用 jq 直接读会话
因为格式就是 JSONL,你可以不写一行代码就做分析:
# 最近一个会话文件 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
刻意不做:五条「不」与它们的替代方案
这一节是 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:一次公开的立场调整
博客里写得很绝对:
他给出的数字很有说服力:Playwright MCP 有 21 个工具、约 13.7k token;Chrome DevTools MCP 有 26 个工具、约 18k token。 也就是开工前 7–9% 的上下文窗口就没了,而其中大部分工具这次会话根本用不到。
但在当前仓库(commit 531340f,2026-10-27)里,MCP 已经是一等公民:
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:不是否定,而是归位
作者真正的观点比「不要 sub-agent」更锐利:在会话中途用 sub-agent 收集上下文,说明你没有提前规划。 正确做法是先在独立会话里把上下文收集好、产出成一份可复用的工件(artifact), 再开新会话带着它干活。这样既有完整可观测性,工件还能给下一个需求复用。
扩展与集成:五个机制、五种接入
pi 砍掉了内置功能,但把「加功能」做得很便宜。官方文档的建议是 选满足需求的最小机制——从纯文本到可执行代码,一共五档。
| 机制 | 是什么 | 成本 / 边界 |
|---|---|---|
| AGENTS.md | 项目上下文文件,自动注入 system prompt 的 project_context | 零成本,纯文本;最该先试的一档 |
| Prompt template | 斜杠命令模板,在输入变 user message 前展开 | 纯文本;适合固定流程 |
| Skill | 专门指令集,只有描述常驻,完整内容按需加载 | 渐进披露,省 token |
| Extension | TypeScript 模块:注册工具、命令、快捷键、provider、事件钩子、状态栏、UI | 与 pi 同权限;能改上下文与拦截工具调用 |
| Theme | 终端配色与样式 | 纯展示 |
其中 Extension 是唯一有执行权限的一档,所以它也是唯一被单独圈进 security-group 的一档。最小例子:
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"); }, }); }
pi --extension ./hello.ts # 开发期直接加载,jiti 免编译 # 会话内输入 /hello 触发
五种接入方式,一套核心
这是「渲染是纯消费者」这一架构带来的直接好处:
| 方式 | 场景 | 入口 |
|---|---|---|
| 交互式 TUI | 日常开发 | pi |
| 脚本 / CI / 一次性任务 | pi --print "..." | |
| JSON 事件流 | 结构化消费、自己的 UI | pi --mode json |
| RPC | 控制一个独立 pi 进程(跨语言) | stdin/stdout JSON 协议 |
| TypeScript SDK | 嵌入到 Node/Bun 应用里 | createAgentSession() |
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 不会改变持久化上下文,这一点在文档里被特别强调。
一年演进:博客是快照,仓库是现状
这是把两个素材源交叉验证后最有价值的产出。只看博客会学到过时的结论,只看代码会不知道设计意图。 下面每一行都能在仓库里找到对应证据。
| 主题 | 博客(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 |
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 打平。
这句话其实是整份手册的论点小结:能力来自模型,harness 的职责是不挡路。
动手练习:六个渐进任务
每个练习都能在 5–15 分钟内完成,并且刻意对应前面某一节。 建议按顺序做,因为它们从「观察」逐步走到「改造」。
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 "用三句话说明这个仓库是做什么的"
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 也在其中。
pi --tools read,grep,find,ls --print "审查 packages/agent,列出三个设计风险" # 没有 bash / write / edit,agent 物理上无法改文件
cat > /tmp/strict.md <<'EOF' - 任何修改前,先用 read 完整读完目标文件 - 报告里必须给出 file:line 证据 EOF pi --append-system-prompt /tmp/strict.md --print "检查 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 命令,就能自己造审计日志。
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() })。
延伸阅读
按「先建立模型,再看细节,最后看动机」的顺序排的。
官方文档(仓库内)
作者博客(设计动机)
官方博客(Earendil,16 篇,2026-01 → 2026-10)
本仓库里的配套产物
一句话总结
读到这里再回看整份手册,你会发现 pi 的所有设计都在服务同一件事: 让你能准确说出「模型这一刻到底看到了什么」,并且能改它。 如果你只带走一句话,就带这句。
作者自述: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。