Appearance
简介与架构总览
这是一篇以 pi 仓库为教材的 Agent 原理教程。在进入代码之前，我们先建立一张全局地图：pi 到底由哪些部分组成，它们之间如何协作。
给初学者
如果你对 "LLM、token、工具调用、Agent、ReAct" 这些词还不熟悉，先读 预备知识：从零认识 Agent，再用大白话把这些基础概念讲透。
pi 是什么
pi 是一个分层架构的 Agent 工程。它把"Agent 应由什么组成"拆解成了几个可独立演进、独立测试的包。理解它的最佳方式，是把整个系统想象成一条从"模型调用"到"用户交互"的流水线：
┌─────────────────────────────────────────────────────────────┐
│ @pi/coding-agent 交互式编码 Agent CLI（把它串起来） │
│ 会话管理 · 内置工具 · 扩展系统 · 状态持久化 · 上下文压缩 │
├─────────────────────────────────────────────────────────────┤
│ @pi/tui 终端 UI（差分渲染） │
│ @pi/server/client 远程会话（跨进程序列化 Agent 会话） │
├─────────────────────────────────────────────────────────────┤
│ @pi/agent-core Agent 运行时（核心循环） │
│ 观察→思考→行动→观察 的循环 · 工具调用 · 状态管理 · 事件流 │
├─────────────────────────────────────────────────────────────┤
│ @pi/ai LLM 抽象层（最底层） │
│ 统一消息模型 · Model/Provider · StreamFunction · 事件流 │
└─────────────────────────────────────────────────────────────┘依赖方向是自底向上的：@pi/ai 不依赖任何上层；@pi/agent-core 依赖 @pi/ai；@pi/coding-agent 依赖前面所有包。
为什么这样分层
把"调用模型"和"构建 Agent"分开，是 pi 最核心的设计决策：
@pi/ai只关心"怎么把一份会话上下文发给模型，并流式拿到回复"。它不知道什么是工具、什么是循环。@pi/agent-core只关心"如何思考、如何调用工具、如何管理状态"。它不绑定任何具体模型厂商，通过一个StreamFunction接口与@pi/ai解耦。@pi/coding-agent把两者结合，并加上交互、会话、扩展等产品能力。
这种分层的直接收益：
- 换一家模型厂商，
@pi/agent-core的代码一行都不用改。 - 想给 Agent 加一个新工具，只需按契约实现
execute。 - 可以把同一个 Agent 运行在本地、远程、甚至通过协议串行化成字节流。
一张图看懂"一次 Agent 会话"
以编码 Agent 收到用户一句"帮我改一下 README"为例，整条链路的时序大致如下：
- cli（coding-agent）解析参数，创建
AgentSession。 AgentSession内部持有一个Agent（来自 agent-core）。Agent.prompt()进入agent-loop。- loop 把会话上下文通过
StreamFunction交给@pi/ai，流式拿到助手回复。 - 若回复里带
toolCall（例如"读取 README"），loop 找到对应工具并执行。 - 工具结果以
toolResult消息回填上下文，loop 再次调用模型。 - 如此反复，直到模型给出最终答案（
agent_end）。 - TUI 通过差分渲染把每一步的增量画到终端。
本教程的每一章，就是这条链路上的一环。
各包职责速查
| 包 | 目录 | 一句话职责 |
|---|---|---|
@pi/ai | packages/ai | 统一 LLM API，多厂商，流式事件协议 |
@pi/agent-core | packages/agent | 模型无关的 Agent 运行时与核心循环 |
@pi/protocol | packages/protocol | 远程会话的字节协议（定帧 + CBOR + Schema） |
@pi/server | packages/server | 承载远程 Agent 会话的服务端 |
@pi/client | packages/client | 连接远程会话的传输无关客户端 |
@pi/tui | packages/tui | 终端 UI 库，差分渲染 |
@pi/coding-agent | packages/coding-agent | 交互式编码 Agent CLI，缝合上层 |
@pi/storage | packages/storage | SQLite 存储（可选） |