手册/第 11 章
11
延伸阅读
按「先建立模型,再看细节,最后看动机」的顺序排的。
官方文档(仓库内)
How Pi Works
49 行的核心机制说明:agent loop、上下文、会话、消息类型。最该先读的一篇。
docs/how-pi-works.md
Session File Format
12 种 entry、树结构、三段上下文构建算法。想抄会话设计就读这篇。
docs/session-format.md
Extensions
生命周期、钩子、工具注册、UI 扩展、安全边界。
docs/extensions.md
Compaction
自动压缩、分支摘要、缓存写入策略、扩展钩子。
docs/compaction.md
Run Pi safely
三种运行方式的保护范围对比,以及为什么「看着点」不算安全边界。
docs/security.md
SDK
会话生命周期、SessionManager 权威性、运行时替换。
docs/sdk.md
作者博客(设计动机)
What I learned building an opinionated and minimal coding agent
本手册的主线素材:四个 API、context handoff、pi-tui 差分渲染、最小 prompt 与工具集、YOLO、五条「不做」、基准测试。
mariozechner.at · 2025-11-30
What if you don't need MCP at all?
MCP 的上下文开销分析,以及「CLI + README」替代方案。注意仓库后来加了 MCP,这篇是理解其权衡的钥匙。
mariozechner.at · 2025-11-02
Prompts are code, .json/.md files are state
为什么 prompt 应当像代码一样被版本化,而状态该落在文件里——pi 会话设计的思想前身。
mariozechner.at · 2025-06-02
官方博客(Earendil,16 篇,2026-01 → 2026-10)
第 12 章:16 篇博客的叙事线
全部 16 篇的清单与一句话,加上 5 条技术断言回仓库核对的结果。想先看摘要就读这章。
本手册 · 第 12 章
What is a Harness?
最该先读的一篇:harness 的四件事(system prompt / 工具 / 循环 / 翻译层),正好对应第 01 章的四层。
earendil.com · 2026-08-20
“You Said No MCP!”
立场转向的完整交代,以及 Codemode 的真实动机:它和 Jev 需要的是同一个沙箱解释器。
earendil.com · 2026-09-29
How Compaction Works in Pi
压缩何时触发、保留 20k token、摘要 prompt 原文、以及为什么必然打断缓存。
earendil.com · 2026-08-13
Measuring the Sloppiness of Code
verbosity 与 erosion 两个公式:agent 代码的啰嗦与侵蚀约为人类两倍。也是「别只看行数」的注脚。
earendil.com · 2026-09-10
全部文章
另有 prompt caching、session portability、Pi 1.0、Pi Durable、system theme 等 11 篇。
earendil.com/posts
本仓库里的配套产物
pi 运行时架构图
14 组件、2 层边界、每个节点带 path:line 证据,可缩放可切主题。
.archify/learn/diagrams/architecture.html
pi 单轮时序图
8 个参与者、13 条消息、3 个片段,从回车到上屏。
.archify/learn/diagrams/sequence.html
ARCHIFY-ANALYSIS.md
图表背后的方法与规模统计:为什么这么画、证据怎么取、限制在哪。
.archify/ARCHIFY-ANALYSIS.md
一句话总结
"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 的所有设计都在服务同一件事: 让你能准确说出「模型这一刻到底看到了什么」,并且能改它。 如果你只带走一句话,就带这句。