总结与层级关系

到这里，你已经把 pi 从最底层读到最顶层。这一页把全书浓缩成一张图、一张表、一句话。

一张图：完整层级

编码 Agent CLI  /coding-agent/
   ├──► TUI                /tui/
   └──► 远程会话           /server/ + /client/
            ├──► 协议      /protocol/
            └──► Agent 运行时 /agent-core/ ──► LLM 抽象层 /ai/

一张表：每个包的"核心问题"

包	回答的问题	最小心智模型
@pi/ai	怎么统一调用多家 LLM？	StreamFunction(model, context) → 事件流
@pi/agent-core	怎么让模型"用工具思考"？	循环：调模型→看 toolCall→执行→回填
@pi/protocol	怎么在字节流里表达会话？	定帧 + CBOR + Schema
@pi/server+client	怎么远程连接一个会话？	握手 + 请求/响应 + 快照/增量
@pi/tui	怎么高效画终端界面？	组件 render + 布局 + 差分
@pi/coding-agent	怎么把它变成可用产品？	会话持久化 + 工具 + 扩展 + 多模式

一条主线：无状态内核 + 有状态 UI

全书反复出现的核心设计：

内层只发事件，不渲染；外层只渲染，不驱动逻辑。

• @pi/ai 的事件流 → 内核数据。
• @pi/agent-core 的 AgentEvent → 会话事件。
• @pi/coding-agent 的 UI（TUI / print / rpc / json）→ 事件消费者。

所以你可以：换 UI（不改内核）、换模型（不改循环）、换传输（不改会话）。分层即解耦，事件即接口。

一条主线：从字节到 Agent

想象一条数据从最低层流到最高层：

用户敲下"帮我改 README"
  → coding-agent 创建 AgentSession
  → Agent.prompt → agent-loop
  → 调 StreamFunction → @pi/ai 把消息发给模型 → 事件流回来
  → 模型说"要读 README"（toolCall）
  → 循环执行 read 工具 → toolResult 回填
  → 再调模型 → 模型给出改动 → message_end
  → AgentSession 把消息写进会话日志（持久化）
  → TUI 差分渲染出每一步
  （若远程：SessionSnapshot 经 @pi/protocol 定帧 → 推到 @pi/client → 远端 UI）

Demo 的定位

所有 Demo 都是工程化项目（pi-principles/），源码在 pi-principles/src/<模块>/。两种运行方式：

cd pi-principles

# ① CLI（推荐）：chat/agent/app/repl，有 .env 走真实 OpenAI，无则离线假模型
bun cli.ts chat "你好"
bun cli.ts agent "请计算 123 + 456"
bun cli.ts app "请计算 3 + 4"      # 全打通：server ⇄ client ⇄ tui
bun cli.ts repl                   # 交互式多轮对话

# ② 模块化 play 入口（教学用，离线）
bun play/ai.ts                    # 事件流 + StreamFunction 契约
bun play/mini-agent.ts            # ReAct 循环 + steer/followUp（假模型）
bun play/protocol.ts              # 定帧 + 黏包/半包
bun play/transport.ts             # 远程会话协议流
bun play/tui.ts                   # 组件 + 差分渲染
bun play/app.ts                   # 全打通（等价于 cli app）

入口	复现自	验证的核心
cli chat / play/chat.ts	@pi/ai + OpenAI 协议	单轮流式对话（真实模型）
cli agent / play/agent.ts	@pi/agent-core	循环 + 真实工具调用
cli app / play/app.ts	server+client+tui	全打通：会话 → 协议 → 渲染
cli repl	全部	交互式多轮对话
play/ai.ts	@pi/ai	事件流 + StreamFunction 契约（离线）
play/mini-agent.ts	@pi/agent-core	循环 + 工具 + steer/followUp（离线）
play/protocol.ts	@pi/protocol	定帧 + 黏包/半包（离线）
play/transport.ts	/server+/client	握手 + 请求响应 + 事件（离线）
play/tui.ts	@pi/tui	组件 + 差分渲染（离线）

最后一句话

pi 的精华，是把"Agent"这个抽象概念，拆成可独立演进、可逐步扩展的工程模块。 读完这本书，你不仅能看懂 pi，更能用 pi-principles/ 动手搭出属于自己的 Agent —— 从消息模型到真实 OpenAI 接入，再到 server ⇄ client ⇄ tui 全打通。

---

感谢阅读。源码对照：github.com/earendil-works/pi。祝你构建出属于自己的 Agent。