English reading guide
pi Coding Agent Source Code Guide: From Agent Loop to Runtime
A source-based guide to earendil-works/pi at a pinned version. Explore how provider adapters, an agent loop, tool execution, a session tree, extensions, and a terminal interface fit together. The guide distinguishes behavior implemented in the repository from the separate Harness v2 design.
Source version: v0.83.0
What you will learn
- Follow provider adapters and the agent loop from input to response.
- Explore tool execution, session trees, and context management.
- Understand extensions and the terminal interface as parts of the runtime.
- Compare implemented behavior with proposed Harness v2 mechanisms.
The complete chapters are written in Chinese and include source references, implementation walkthroughs, and failure cases. This page is an English introduction, not a translation of the full book.
Chapters in Chinese
- 先固定版本，再谈 Pi 的架构
- 一个 pi 命令，四种运行方式
- 启动阶段到底组装了什么
- 配置、信任与资源从哪里进入
- `createAgentSession()` 怎样交出一个可运行会话
- AgentMessage 为什么不能直接发给模型
- 模型目录与 Provider Registry 各管什么
- 密钥与 OAuth 怎样落到一次请求
- 请求发出前，Context 还会经历什么
- 流式响应怎样变成可消费事件
- 不同模型 API 怎样被压到同一接口
- 重试、溢出与中止在哪一层收口
- `Agent` 怎样把事件还原成状态
- 两层循环为什么缺一不可
- Steering 与 Follow-up 不是同一种排队
- 工具执行前先经过哪些检查
- 并行工具为什么仍要保留原始顺序
- 一次 Run 怎样停止、失败与继续
- `AgentHarness` 为什么没有包住 `Agent`
- 一轮请求为什么需要快照与保存点
- 运行中改配置，什么时候才真正生效
- Session 保存的是树，不是一串消息
- 压缩与回到旧分支怎样改变上下文
- 持久会话为什么还不等于持久运行
- `AgentSession` 如何成为 Coding Agent 的控制面
- 一条 Prompt 在调用模型前还要过多少关
- JSONL 会话文件怎样记录一棵树
- 恢复、分叉与切换会话不是同一个动作
- 模型切换与设置热更新怎样保持一致
- 自动压缩、重试与用量统计怎样协作
- 七个内置工具为什么默认只开四个
- 读写文件时，Pi 怎样避免相互踩踏
- Bash 输出太长时，完整结果去了哪里
- AGENTS.md、Skills 与 Prompt 模板怎样被发现
- 扩展代码从哪里加载，信任边界在哪里
- Extension Runner 怎样串起事件与变换
- 自定义工具、Provider 与渲染器谁覆盖谁
- 不启动 TUI，怎样把 Pi 嵌进自己的程序
- 同一场运行怎样投影成文本与 JSON
- RPC 模式如何把会话变成可控制进程
- `pi-server` 管的是进程，还是 Agent
- Evals 怎样把 Agent 行为变成可检查结果
- TUI 组件、焦点与覆盖层怎样配合
- 键盘输入怎样穿过终端协议到达编辑器
- Pi 为什么不用每次重画整个终端
- 流式消息与工具结果怎样出现在屏幕上
- Pi 没有内置沙箱，这意味着什么
- 怎样验证本册结论，并看清 Harness v2 的边界