手册/第 01 章
01
心智模型:四层、一个循环、四个概念
如果把 pi 压缩成一句话:它把「模型调用」收敛成一个函数,把「工具执行」收敛成一个循环, 把「界面」收敛成一个事件消费者。剩下的全是这三种东西的外围工程。
入口 终端输入 ·
--print · --mode json · RPC · SDK▼输入 / 命令
④
渲染层pi-tui
保留模式组件树 + 差分渲染 + 同步输出。只消费事件,不改状态。
4.0 万行
tui.ts:506
tui.ts:506
▲事件流 text_delta · tool_call · toolResult
③
产品层pi-coding-agent
模式分发、AgentSession、会话树、工具集、扩展运行时、设置。
16.4 万行
agent-session.ts:379
agent-session.ts:379
▼prompt() / abort / 排队消息
②
循环层pi-agent-core
runAgentLoop:请求 → 工具 → 再请求,直到没有工具调用。
6 个源文件 / 2,541 行
agent-loop.ts:251
agent-loop.ts:251
▼streamFn(model, context)
①
模型层pi-ai
4 个 HTTP 协议 → 1 个统一事件流;上下文可序列化、可跨厂商交接。
8.0 万行
95 provider / 43 API
95 provider / 43 API
反直觉的地方在于层数与体量的错位:真正决定 agent 行为的循环层只有 6 个源文件、2,541 行; 而产品层有 16.4 万行、模型层有 8 万行。也就是说,复杂度几乎全部堆在「协议翻译」和「产品外壳」上, 而不是「agent 智能」上。这也是作者反复强调的判断:agent 的智力来自模型本身, harness 的职责是把上下文组织好、把工具跑对、把过程显示清楚。
6
循环层源文件数
2,541
循环层 src 行数
164,445
产品层行数
79,996
模型层行数
4
需要统一的 HTTP 协议
四个必须先记住的概念
1一次请求由什么组成
system prompt + 活动分支的历史 + 可用工具定义 + 模型设置。
没有隐藏注入:你在 UI 里看到的,就是发给模型的。
2一个 turn 是什么
assistant 消息 +(可能的)工具调用与工具结果。
只要还有工具调用或排队消息,就再起一个 turn。
3一个 session 是什么
一棵树,不是一个数组。每条 entry 有
id/parentId,
从任意历史节点继续会在同一文件里长出新分支。4一个界面是什么
事件流的消费者。交互式 TUI、
--print、JSON 事件流、RPC、SDK
共用同一套 agent 与会话机制。docs/how-pi-works.md agent-loop.ts:251 session-manager.ts:1187