阶段一 · 架构与核心机制
架构总览 —— 一个编码智能体由哪几层组成
同一个模型,装进聊天框就只会聊天,装进 Pi 就能读你的仓库、改代码、跑测试。差别不在模型,而在模型外面那层程序。这一章先把这个"外面那层"拆成三层,讲清每层负责什么、为什么必须分开,然后对照我们自己的单文件实现看一遍。
具体回答三个问题:能力到底是谁给的?这层程序怎么分层?为什么"高级能力"都长成工具?
学习目标
- 理解一句判断:智能来自模型,能力边界来自外面的程序。
- 能说出 Pi 的三层结构(核心、产品、界面),以及每层为什么必须独立。
- 理解"高级能力即工具":为什么子代理、MCP 这类能力都不长在循环里。
- 对照我们仓库里的单文件实现,认出这三层的对应关系。
一、同一个模型,两种命运
先用一个思想实验切入。同一个模型——同一天、同一个版本、同一个 API——装进两个产品:一个是网页聊天框,一个是 Pi。前者只会跟你聊天;后者能读你的仓库、改你的代码、跑你的测试、在删文件前停下来问你。
模型一模一样,能力天差地别。差别是谁给的?
把你以为是"模型能力"的东西逐项拆开看:
| 你看到的现象 | 实际是谁提供的 |
|---|---|
| 它记得这段对话说过什么 | 外面那层程序——消息数组是它维护的 |
| 它会读文件、跑命令 | 外面那层程序——工具是它注册的 |
| 它删文件前会先问你 | 外面那层程序——拦截发生在模型之外 |
| 聊了一下午也没失忆 | 外面那层程序——压缩是它触发的 |
| 它"学会"了新技能 | 外面那层程序——技能文件是它读进来、塞进提示词的 |
模型真正提供的只有三样:语言、推理,以及最关键的一件事——决定下一步调用哪个工具。这已经足够惊人,但仅此而已。
所以全书的第一句话是:
agent = 模型 + 工具调用
这个式子给的是核心循环的最小闭环:让循环转起来,缺一样都不成立,所以只有两项。它不试图穷尽一个 Agent 系统的全部组成——经典文献里的"规划"与"记忆"不在式子里,但在 Pi 里都有明确的承担者(见下一节)。
二、经典四件套与这个式子的关系
经典文献通常把 Agent 写成四个组件:模型 + 规划 + 记忆 + 工具。这个拆法回答"一个 Agent 系统由什么组成";而"模型 + 工具调用"回答"让循环转起来,最少需要哪些机制"。两者层次不同,并不矛盾:
| 经典组件 | 在 Pi 里由谁承担 | 为什么不进核心循环 |
|---|---|---|
| 模型 | 模型接入层(第 08 章) | — |
| 工具 | 工具系统(第 03 章) | — |
| 规划 | 模型自己在循环内完成:每一轮"决定调用哪个工具"就是一次规划动作 | Pi 刻意不内置规划器——任务分解是模型的推理能力,硬编码进框架反而把 Agent 退化成写死的流程 |
| 记忆 | 短期靠消息数组每轮重发(第 04 章);长期靠会话文件、上下文文件与压缩(第 05、07、04b 章) | 核心只保留"消息数组"这一个最小机制;持久化、压缩、注入是产品层职责,可以各自演进 |
于是完整的表述是两层:
最小闭环(核心循环): 模型 + 工具调用
完整系统(产品外壳): + 消息与记忆 + 上下文管理 + 会话 + 拦截 + 事件 ...
这个视角解释了一个常见困惑:Pi 为什么没有"记忆模块"?因为它把记忆拆成了三件具体机制——消息数组、会话文件、压缩——分别讲清楚,而不是提供一个叫 memory 的黑盒。
三、三层结构
既然能力边界由外壳决定,外壳内部又怎么组织?Pi 的做法可以概括成三句话:
- 模型无关的核心:循环、消息、工具、事件。它不依赖具体界面、具体模型服务商、具体文件布局,可以在任何前端、任何模型下复用。
- 产品环境:把核心组装成真正的编码助手——工作目录、会话、拦截策略、扩展、上下文文件。
- 界面:终端界面、一次性输出、结构化输出、进程间协议。界面只消费事件,不伸手改核心内部状态。
三个理由决定这条边界:
- 可测试性:核心不依赖界面和文件布局,就能用"脚本化的假模型"做确定性测试。我们仓库里所有的离线实验,都是靠这一点跑起来的。
- 可移植性:同一套核心可以同时驱动终端、脚本、IDE 插件,而循环代码一行不改。
- 可替换性:换模型服务商、换界面、换存储,都不需要重写 Agent 逻辑。
这里有个容易被版本变化误导的地方:"核心小"指的是循环小,不是包少。Pi 现在是多个包组成的工程,其中产品能力包(比如把工具调用编排成脚本的 code mode、接入 MCP 工具的客户端、持久化会话运行时)确实变多了;但承载循环的那个包反而被削得更薄——它现在几乎只剩循环本身和消息类型,会话、压缩、技能这些都被搬到了外层。这恰恰印证了这条边界:越往后演进,核心越小。
事件是层与层之间的粘合剂
核心和界面之间不靠函数调用,而靠类型化的事件流:核心每走一步发一个事件,界面订阅并渲染。这个设计在第 06 章展开,但它的意义现在就能看到:界面怎么变,核心不用改。
四、能力为什么长在工具上
Pi 不内置子代理,也不内置"计划模式"——每个团队的工作流不同,内置会限制灵活性。更根本的理由是:这些能力本质上都是一次工具调用。
- 子代理:外面套一个工具,调用它等于启动"另一个完整的 Agent 循环",但对当前模型来说,它就是一次普通的工具调用。
- MCP(把外部工具服务器接进来):无论接入多少服务器,呈现给模型的仍然是工具,名字带个服务器前缀而已。
- code mode(让模型写脚本调用工具):模型不再逐个调用工具,而是写一段脚本,在沙箱里连着调好几个工具、只把结果交回上下文。工具抽象没变,变的是编排发生在模型侧还是脚本侧。
所以"高级能力即工具"的准确含义是:能力可以很多,但核心只需要认识"工具"这一种扩展点。这是 Pi"极致可扩展"的真正来源——不是功能多,而是扩展面窄而清晰。
当前 Pi 行为
- 版本基线为 Pi 1.4.0(2026 年 10 月发布)。
- 运行时有四种形态,共享同一个核心:终端交互界面(默认)、一次性输出、结构化事件输出、进程间协议。区别只在外层怎么消费事件。
- 核心只负责循环与消息;会话、压缩、技能、提示词、持久化都在外层产品代码里。
- 产品层的能力包按需装载:code mode、MCP 客户端、持久化会话运行时都是独立包,主程序按需依赖。
- 历史上曾经有过一套"远程会话"实验包(二进制协议 + 服务端),它在 1.2 版本里被整体删除;现在跨进程集成就只剩命令行与 SDK 两条路。
代码里的名字
读源码时你会遇到这些名字,对照着看即可,不必记:
| 通俗说法 | 代码里的名字 |
|---|---|
| 模型无关的核心 | packages/agent(循环与消息类型) |
| 产品环境 | packages/coding-agent(会话、设置、扩展、界面) |
| 终端界面组件 | packages/tui |
| 模型接入层 | packages/ai |
| 脚本化工具调用 | packages/codemode |
| MCP 客户端 | packages/mcp |
| 持久化会话 | packages/durable |
源码位置
packages/agent/src/:循环、Agent、事件类型。整个目录不引入任何模型服务商与界面代码。packages/coding-agent/src/core/:会话、提示词、工具、扩展、设置。packages/coding-agent/src/modes/:终端、协议等界面实现。
失败与边界实验
分层边界被违反时会发生什么?三个思想实验,都可以在源码里验证"为什么做不到":
- 让核心直接调用模型接口:循环里没有任何一行指向具体服务商——它只接受调用方注入的"流式请求函数"。换模型改的是调用方,不是循环。
- 让界面直接改消息数组:界面拿到的是事件和消息的副本,没有对内部状态的引用。想高亮某条消息,只能订阅消息更新事件,不能伸手进去改。
- 把拦截检查塞进循环:循环只在"执行工具"这一步调用工具,根本不知道拦截的存在。拦截属于工具执行的外围——这正是为什么每个项目的策略可以不同,而循环代码不变。
第三个实验是最有力的证据:边界画在包之间,而不是画在 if 语句里。
python3 -m unittest tests.test_13_mini_agent -v
在 Pi 里怎么操作
pi # 交互式终端界面
pi -p "prompt" # 一次性输出后退出
pi --mode json # 把事件流输出到标准输出
pi --mode rpc # 用标准输入输出跑长驻协议
Python 实验
我们仓库里的 mini_agent.py 就是这三层的单文件缩影,一共五百多行,分五段:
| 段落 | 内容 | 对应 Pi 的哪一层 |
|---|---|---|
| 消息与工具的数据结构 | 用户消息、助手消息、工具结果、工具定义 | 核心 |
| 模型接入协议 | ModelProvider:只要求实现"流式返回一段助手消息" |
模型接入层 |
| 事件类型 | 运行开始/结束、轮次开始/结束、消息开始/结束、工具执行开始/更新/结束 | 核心 |
| 循环 | run_agent_loop:纯生成器,只吐事件、不持有状态 |
核心 |
| 外壳 | AgentHarness:持有对话历史、支持订阅、把事件广播给多个观察者 |
产品层 |
最后一段最值得看。循环本身是"无状态"的:给它一份历史、一组工具、一个模型,它就把事件一个个吐出来。真正让 Agent 能连续对话的是外面那个包装——它保存历史、把事件分发给界面:
class AgentHarness:
def subscribe(self, listener):
self._listeners.append(listener)
return lambda: self._listeners.remove(listener)
def prompt(self, content):
for event in run_agent_loop(...): # 循环不知道有多少人在听
self._listeners and [listener(event) for listener in self._listeners]
这两段的分离,就是"核心可移植"的最小证明:同一个循环,换成终端界面、换成结构化输出、换成协议模式,只需要换掉监听者。
需要说明一处版本差异:Pi 现在没有一个与 AgentHarness 同名的类——这类"有状态的包装"被拆进了产品代码与持久化会话包里。教学模型保留这个名字,是为了让"循环 / 外壳"的责任边界在一页代码里可见,而不是让你去 Pi 里找一个同名类。
Tau(Pi 的 Python 对照实现)用三个包实现同一个分层:模型接入、Agent 核心、产品外壳。它是"同一架构的另一种语言"的直接样本——读它和读 Pi,看到的是同一套设计。
python3 -m learn_pi_lab lab mini-agent
这一模块的核心代码在核心代码导览 · 架构分层有逐段解读。
验证方式
python3 -m unittest tests.test_13_mini_agent -v
python3 scripts/check_course_contract.py
边界与安全
- 分层是设计边界,不是安全边界:拦截、认证、隔离必须在产品层实现,核心不做兜底。
- 本课程的教学模型只覆盖可迁移的机制,不复制 Pi 的全部产品细节。
- 核心"不依赖具体服务商"不等于"没有网络风险":网络、凭据、超时都在接入层,出问题也去那里查。
自测三问
- 为什么说"规划"没有缺席,只是换了承担者?它在循环里具体表现成哪一步?
- 产品层的能力包变多了,为什么反而说明"核心更小"?
- 如果让你给一个只做代码审查的助手做减法,你会先砍掉哪一层、保留哪一层?
回顾
- 模型负责思考,外壳负责边界:同一个模型,能力差别全在外面那层程序。
- 最小闭环只有两项:模型 + 工具调用;规划由模型承担,记忆拆成消息、会话、压缩三件机制。
- 三层结构:核心 / 产品 / 界面,事件是粘合剂;核心小,产品包多。
- 能力长在工具上:子代理、MCP、code mode 都是工具,核心只认识这一种扩展点。
下一章进入最核心的机制——Agent Loop,看循环如何让模型真正"动起来"。