pi agent 这一年经历了哪些大的架构更新
我最近主力使用的终端 AI 编程工具是 pi。它 2025 年 11 月 25 日发布第一个公开版本，到现在（2026 年 8 月）不到九个月，版本号已经走到了 0.84。
版本号走得快，一部分原因是功能迭代密集，另一部分原因是它的架构一直在变。我平时用它写代码，也偶尔翻它的 CHANGELOG，发现 agent 核心部分大的架构更新就有九次。这篇文章按阶段整理一下，看看它从"一个终端聊天程序"走到"一个可以嵌入任何应用的 agent SDK"，中间经历了什么。
阶段一：从单体到双前端
pi 的第一个公开版本（v0.10.0）是一个典型的单体应用：TUI 界面、agent 循环、工具执行全部在一个进程里，逻辑之间没有清晰的边界。
三天之后的 v0.10.3 就做了第一次架构更新：把内部重构为"共享的 agent 逻辑 + 多个前端"的形态。当时新增了 --rpc 模式，可以通过 stdin/stdout 用 JSON 和它通信，TUI 和 RPC 共用同一套 agent 循环。这是 pi 第一次把"界面"和"大脑"分开，也决定了它后来的走向：界面只是入口，核心是一个可以被任意前端驱动的 agent。
接下来一个月里，非交互形态被补齐：-p 打印模式、上下文压缩（compaction）、会话分支（branching）陆续出现。到 2025 年 12 月底，pi 已经从"只能坐在终端里聊天"变成了"可以跑在脚本和 CI 里的工具"。
阶段二：agent 核心独立成包
2026 年 1 月 2 日的 v0.31.0 是第一次真正意义上的大手术。
在这之前，agent 循环（那个"反复调用模型、执行工具、再把结果喂回去"的循环）放在 pi-ai 这个库里，和模型、provider 的代码混在一起。这一版把整个 agent 循环迁到了独立的 @earendil-works/pi-agent-core 包，同时做了一件更彻底的事：删掉了传输抽象。
原来要自定义模型调用方式，需要实现 ProviderTransport、AppTransport 这样的接口。这一版全部移除，改成 streamFn——一个简单的函数，输入模型和上下文，输出消息流。浏览器应用想代理调用后端，也不用再实现传输接口，直接用官方提供的 streamProxy() 工具函数就行。
这个变化的思路是：与其抽象"传输"这种实现细节，不如直接抽象"流"本身。接口少了，扩展反而更容易了。
阶段三：交互模型的重塑
紧接着的 v0.32.0 改了 agent 的消息队列语义。原来的 queueMessage() 只有一个入口，语义不清晰；这一版拆成了两个方法：
steer(msg)：打断正在跑的任务，在当前工具执行完后插入新指令，跳过剩余工具。followUp(msg)：等任务自然结束后再送达，而且只在没有后续工具调用时生效。
一个是"先停一下，按我说的做"，一个是"做完这个再说"。API 名字的变化背后，是 agent 并发模型从"一个队列"变成了"两种明确的中断语义"。
v0.65.0（2026 年 4 月）又重塑了状态模型。原来 Agent 有一堆 setter 方法：setSystemPrompt、setModel、setTools……这一版全部删除，改成直接读写 agent.state 属性；订阅事件的回调也改成了 async，并带上了 AbortSignal，方便把取消信号透传给嵌套的异步操作。这实际上是把 Agent 从一个"封装好的黑盒"变成了"显式的状态机"——状态放在明面上，谁都可以读，谁都可以改。
阶段四：Harness 化和认证收口
v0.80.0（2026 年 6 月）是 pi-agent 面向"嵌入式场景"的一次重要收口。
之前 agent 的认证逻辑分散在选项里，调用方要传 getApiKeyAndHeaders 回调自己解决 API key。这一版把 Models 实例变成唯一认证路径：所有模型调用（主循环、压缩、分支摘要）都通过 Models.streamSimple() 走，认证交给 provider 自己处理。API key 的解析、刷新、OAuth 全被收进 provider 层，agent 层不再关心。
v0.82.0（2026 年 7 月）则重构了 Harness（给 agent 提供文件系统、shell 等能力的执行环境）的工具模型。原来工具是"无上下文"的，只能依赖一个全局的 ExecutionEnv；现在改成应用自己定义 toolContext，工具通过上下文感知的 AgentHarnessTool 访问环境。好处是同一个 Harness 可以针对不同应用注入不同的上下文，不用再为每个场景写一套环境。
阶段五：Session v4，会话模型换代
最近的一次大更新是 2026 年 8 月 6 日的 v0.84.0。这一版把整个会话存储模型换成了 v4：
- 新的
Session/SessionStorage/SessionRepoAPI，基于 lane（通道）的概念组织会话数据，支持持久化的操作记录、全局事实、共享序号。 - 新增
JsonlSessionRepo和InMemorySessionRepo两个实现，删除了旧的 legacy JSONL 和内存仓库 API。 - 旧的
AgentHarness实验入口被移除，v2 版本成为默认导出。
同时要求执行环境提供 FileSystem.renameFile()，让 JSONL 会话文件通过原子替换发布，避免写入中断产生半截文件。会话是 agent 的记忆，记忆的可靠性和并发模型升级之后，agent 才能安全地长时间运行、支持分支和恢复。
正在发生：client/server 拆分
v0.84.1 之后，仓库里开始出现 protocol、client、server 三个新包。7 月底已经有一个基于 Unix socket 的 client-server CLI 合入。看起来 pi 正在把"agent 进程"和"调用方"拆成独立的客户端和服务端，可能是为了支持远程会话或多客户端场景。这会是下一次大的架构更新，值得关注。
主线：从终端应用走向可嵌入 SDK
回头看这九次更新，能看出一条主线：pi 的 agent 核心一直在做"去终端化"。
- 第一阶段把界面和逻辑分开，让 agent 能被多种前端驱动；
- 第二阶段把循环从模型库里拆出来，让 agent 能脱离 pi 的 provider 体系独立使用；
- 第三、四阶段把状态、认证、环境全部显式化，让外部应用可以安全地持有和驱动一个 agent；
- 第五阶段让会话存储达到生产级，支撑长时间运行和恢复。
对普通用户来说，这些更新大部分不可见——TUI 的用法几乎没有变过。但对想在自己应用里嵌入 agent 的人来说，这个演进非常关键：从"在终端里运行的程序"到"可以嵌入任意应用的 SDK"，中间隔着的就是这九次架构更新。
AI 说明
本文的事实（版本号、更新内容、时间线）来自 pi 仓库的 CHANGELOG 和 git 历史，由我核对确认；文章的结构、段落和措辞由 AI 根据这些材料整理润色，我做了少量修改。