pi 系统学习手册
最小,但不简单
pi 是一个刻意做小的 coding agent harness:核心只有 6 个源文件 2,541 行,却要驱动 95 个 provider 文件、43 个 API 适配文件、一棵可分支的会话树、一套完整的终端 UI 和可插拔的扩展系统。 这份手册把官方文档、仓库源码与作者本人写的复盘博客交叉对齐, 回答一个问题:它凭什么用这么少的代码做到这件事,代价又是什么。
十二章,从心智模型到动手改造
每一章都可以独立阅读,但推荐顺序是从 01 开始——后面的章节会反复用到前面的概念。 每章页脚都有上一章 / 下一章,左侧有本章目录。
三条路线,看你有多少时间
这份材料的几个入口
同一份内容有不同形态,按场合选:
分章阅读(本页)——每章一页,左侧章节导航 + 本章目录,适合逐步学习。
单页全本——全部内容在一页里,适合 ⌘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 永久链接(带行号)。