pi 系统学习手册 12 章 单页全本 架构图 分析报告 GitHub
Learning Notes · 2026

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

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

repo earendil-works/pi commit 531340f license MIT packages 11 TS/TSX ~42 万行(含测试) 架构图 + 时序图 已校验
00

十二章,从心智模型到动手改造

每一章都可以独立阅读,但推荐顺序是从 01 开始——后面的章节会反复用到前面的概念。 每章页脚都有上一章 / 下一章,左侧有本章目录。

01
心智模型:四层、一个循环、四个概念
先建骨架:模型层、循环层、产品层、渲染层,以及「agent 循环 / 工具 / 会话 / 扩展」四个必须分清的概念。
5 min · 2,541 行的核心
02
设计哲学:把「我不需要」写进架构
作者的三条不满(工具变飞船、上下文被偷偷注入、无法观测)与一句话取舍原则,全部配英文原文。
10 min · 16 段原文引用
03
架构图:14 个组件、2 层边界
可交互的运行时架构图,配读图指南与组件证据表——每个方块都能点到源码行。
12 min · 内嵌图 + 可全屏
04
一次提问:13 条消息走完一个 turn
从按下回车到文字上屏的完整时序,以及「为什么模型会被调用两次」。
8 min · 时序图 + 三个关键时刻
05
六个关键机制
四个 API、context handoff、工具结果的 output/details 拆分、可组装的 system prompt、最小工具集、YOLO 默认。
15 min · 6 个手风琴
06
会话与上下文:一棵树,三段算法
JSONL 会话树、分支与 leaf、三段上下文算法、compaction 与 branch summarization 的区别、消息排队。
12 min · 含 jq 分析示例
07
刻意不做:五条「不」与它们的替代方案
不做 TODO、Plan mode、后台 bash、sub-agents、MCP——以及 MCP 从「永不」到「已支持」的公开调整。
8 min · 立场 vs 原则
08
扩展与集成:五个机制、五种接入
AGENTS.md / prompt template / skill / extension / theme,以及 TUI、--print、--mode json、RPC、SDK 五条接入路径。
10 min · 附最小可运行示例
09
一年演进:博客是快照,仓库是现状
博客(2025-11-30)与仓库(531340f, 2026-10-27)之间的 8 处差异,以及三条能站得住的结论。
6 min · 差异表
10
动手练习:六个渐进任务
安装、拆会话文件、用只读工具集做审查、追加系统提示、写一个扩展、把 agent 嵌进自己的程序。
20–40 min · 命令可复制
11
延伸阅读
官方文档、作者博客原文、两张图与配套分析报告的完整索引。
3 min · 全部链接
12
作者自述:16 篇博客
harness 的四件事、极简的可检验形式、MCP→Codemode 的立场交接、compaction 的四个数字、sloppiness 的两个公式——逐条回仓库核对。
15 min · 5 条断言已核对
◈

三条路线,看你有多少时间

路线 A · 30 分钟
01 心智模型 → 03 架构图 → 07 刻意不做。
目标:能画出 pi 的分层图,并说清它和 Claude Code 的取舍差异。
路线 B · 60 分钟
02 设计哲学 → 04 一次提问 → 05 六个机制 → 06 会话。
目标:理解一次 turn 的全链路,以及上下文是怎么被精确控制的。
路线 C · 半天
全部十二章 + 10 动手练习 的六个任务。
目标:能自己写一个扩展,或用 SDK 把 pi 嵌进别的程序。
◇

这份材料的几个入口

同一份内容有不同形态,按场合选:

分章阅读(本页)——每章一页,左侧章节导航 + 本章目录,适合逐步学习。

单页全本——全部内容在一页里,适合 ⌘F 全局搜索、打印或整页分享(仍是单文件,无外部依赖)。

两张图——运行时架构图(14 组件 / 15 连接 / 4 卡片)与 单轮时序图(8 参与者 / 13 消息 / 3 片段),由 Archify 生成并通过校验。

读书指南——把开源书《深入理解 AI Agent》的 Harness 五要素与五个设计模式,落成 pi 与 dsh 的体检表(每条判断都带源码证据)。

分析报告——图之外的结构性结论、规模事实、复现方法,以及本轮没做的事。

事实基准:博客快照 2025-11-30,仓库现状 commit 531340f(2026-10-27)。 两者冲突处(最典型是 MCP)不模糊处理,会在 07 与 09 显式标注。所有源码断言都给出 GitHub blob 永久链接(带行号)。