pi 系统学习手册 第 04 / 12 章 总目录 单页全本 架构图 GitHub

手册/第 04 章

04

一次提问:13 条消息走完一个 turn

架构图回答「有哪些零件」,时序图回答「它们按什么顺序说话」。 下面这张图从用户敲下回车开始,到文本渲染上屏为止。

pi 单轮时序 · 8 participants / 13 messages / 3 fragments 新窗口 ↗

阅读顺序:自上而下三条时间线——① 用户输入到模型请求,② 工具调用与结果回填, ③ 再次请求到渲染上屏。虚线段表示落盘,斜跨的粗箭头是一次模型调用。 这张图画布较窄(952px),1× 下最小字号约 6px、2× 即可到 12px,通常不必开到 3×。

三个关键时刻

Ⅰ模型调用是唯一的出口
整个仓库里,模型请求只经过 streamFn(model, context) 这一个函数。 换 provider、换模型、走代理、加 trace,都只需要在这一层做。
Ⅱ工具执行是唯一的信任边界
prepare → validate → beforeToolCall → execute → afterToolCall。 参数校验、权限策略、审计、扩展挂钩,全都在这一条链上。
Ⅲ落盘发生在渲染之前
assistant 消息先追加进 JSONL,再交给 UI。 所以进程被 kill 也不会丢掉已完成的 turn——这正是可恢复性的前提。

为什么模型被调用两次?

因为工具结果也是「消息」。第一次 streamFn 返回的是「我要调用 bash」; 工具跑完后,结果作为一条 toolResult 追加进活动分支, 然后必须带着新历史再请求一次模型,它才知道命令输出了什么。 这个「再请求」就是 turn 的循环条件:只要还有工具调用,就再起一个 turn;否则 run 结束。

"The loop just loops until the agent says it's done."
这个循环就一直循环,直到 agent 说它做完了。
— 2025-11-30 博客 · 没有 max steps 这个旋钮

docs/how-pi-works.md · Agent loop agent-loop.ts:842 · tool.execute stream-fn.ts:15

本章学习记录

记录仅保存在当前浏览器。