总体架构
最后更新：2026-10-10
Pi 架构最值得学习的地方，是它把「不稳定的外部世界」和「稳定的核心循环」分开了。
大模型供应商会变，工具会变，UI 会变，用户想安装的扩展也会变。但 Agent Loop 的本质相对稳定：准备上下文、请求模型、处理工具、写回结果、继续或停止。把这两类东西分开，是 Pi 能长期演进的根基，也是它「可自我扩展」名字的来源——外设可以变，内核不动。
三层分工
用户或外部系统通过终端界面、远程调用或直接 SDK 提交 prompt(text)。这一层只负责「发声」，不关心模型是谁。
Session 展开技能与模板、检查模型和认证，再把消息交给 Agent；Agent 把事件回调给 Session，Session 负责把消息与工具结果写入存储，并向上层回传 AgentSessionEvent。
核心循环调用 streamSimple(model, context) 请求模型，收到 toolCall 后执行工具得到 AgentToolResult，再继续，直到给出最终答案或停止。
一次端到端调用
UI → Session.prompt(text)
Session → 展开技能/模板，检查模型与认证
Session → Agent.prompt(messages)
Agent → AgentLoop.runAgentLoop(context, config)
AgentLoop → AI.streamSimple(model, context)
AI → message_update / toolCall
AgentLoop → Tool.execute(args)
Tool → AgentToolResult
AgentLoop → AgentEvent
Agent → 事件回调
Session → Store.appendMessage / appendToolResult
Session → AgentSessionEvent（回传 UI）pi-ai，换界面只动 SDK/TUI，核心循环始终不动——这正是 Pi 可长期演进的关键。
分层带来的工程收益
分层的价值不在术语，而在它让每一层可以独立替换、独立测试。下面是一些具体场景：
- 换模型：供应商差异被收敛在 pi-ai 内部，上层无感。
- 换界面：同一套核心可以同时驱动命令行、RPC 与 SDK，互不影响。
- 换工具：工具在运行时注册，新增能力不必改动核心循环（见 核心概念）。
- 可观测：因为事件沿核心循环向上回传，调试时可在 运行与调试 中观察每一次 message_update 与 toolCall。
这也是 Pi 能保持「可自我扩展」的原因：外设变化是常态，内核稳定是前提。想从零理解这套分层，可对照 快速上手 与上游教学版。
与「教学版」的关系
上游有一份教学版目标项目（参考 how-pi-agent-works），用最小依赖还原了同样的三层：Express 后端 + JSONL 会话存储 + MockModel + 工具注册表，帮助读者从零理解 Pi 的运行时。真实仓库在此基础上演进，增加了流式、扩展加载与多供应商适配。各层的实际代码归属，可对照 核心包 一文。
相关阅读
常见问题（FAQ）
为什么 Pi 要把系统分成三层？
因为模型供应商、工具、UI、扩展都在快速变化，而代理循环本质稳定。分层后，换供应商只动 pi-ai，换界面只动 SDK/TUI，核心循环始终不动，系统因此可以长期演进、独立测试与替换。
交互层、运行层、核心循环各自负责什么？
交互层只负责发声（TUI/RPC/SDK 提交 prompt），不关心模型是谁；运行层由 AgentSession 与 Agent 组成，展开技能模板、检查模型与认证、把消息与工具结果写入存储；核心循环调用模型、执行工具、回写结果直到给出最终答案。
换模型供应商需要改核心循环吗？
不需要。核心循环只依赖 pi-ai 的抽象，供应商差异被收敛在 pi-ai 内部。换模型通常只改配置，详见模型供应商一篇。
AgentSession 和 Agent 有什么区别？
AgentSession 处在运行层、面向用户与存储，负责展开技能模板、检查模型与认证、把消息与工具结果持久化并向上回传事件；Agent 处在运行层与核心循环之间，负责把消息交给核心循环并把事件回调给 Session。
教学版的三层和真实仓库一致吗？
一致。教学版用最小依赖还原同样的三层：Express 后端、JSONL 会话存储、MockModel 与工具注册表。真实仓库在此基础上演进，增加了流式、扩展加载与多供应商适配。
