阶段一 · 架构与核心机制

架构总览 —— 一个编码智能体由哪几层组成

同一个模型,装进聊天框就只会聊天,装进 Pi 就能读你的仓库、改代码、跑测试。差别不在模型,而在模型外面那层程序。这一章先把这个"外面那层"拆成三层,讲清每层负责什么、为什么必须分开,然后对照我们自己的单文件实现看一遍。

具体回答三个问题:能力到底是谁给的?这层程序怎么分层?为什么"高级能力"都长成工具?

学习目标

  • 理解一句判断:智能来自模型,能力边界来自外面的程序。
  • 能说出 Pi 的三层结构(核心、产品、界面),以及每层为什么必须独立。
  • 理解"高级能力即工具":为什么子代理、MCP 这类能力都不长在循环里。
  • 对照我们仓库里的单文件实现,认出这三层的对应关系。

一、同一个模型,两种命运

先用一个思想实验切入。同一个模型——同一天、同一个版本、同一个 API——装进两个产品:一个是网页聊天框,一个是 Pi。前者只会跟你聊天;后者能读你的仓库、改你的代码、跑你的测试、在删文件前停下来问你。

模型一模一样,能力天差地别。差别是谁给的?

把你以为是"模型能力"的东西逐项拆开看:

你看到的现象 实际是谁提供的
它记得这段对话说过什么 外面那层程序——消息数组是它维护的
它会读文件、跑命令 外面那层程序——工具是它注册的
它删文件前会先问你 外面那层程序——拦截发生在模型之外
聊了一下午也没失忆 外面那层程序——压缩是它触发的
它"学会"了新技能 外面那层程序——技能文件是它读进来、塞进提示词的

模型真正提供的只有三样:语言、推理,以及最关键的一件事——决定下一步调用哪个工具。这已经足够惊人,但仅此而已。

所以全书的第一句话是:

agent = 模型 + 工具调用

这个式子给的是核心循环的最小闭环:让循环转起来,缺一样都不成立,所以只有两项。它不试图穷尽一个 Agent 系统的全部组成——经典文献里的"规划"与"记忆"不在式子里,但在 Pi 里都有明确的承担者(见下一节)。

二、经典四件套与这个式子的关系

经典文献通常把 Agent 写成四个组件:模型 + 规划 + 记忆 + 工具。这个拆法回答"一个 Agent 系统由什么组成";而"模型 + 工具调用"回答"让循环转起来,最少需要哪些机制"。两者层次不同,并不矛盾:

经典组件 在 Pi 里由谁承担 为什么不进核心循环
模型 模型接入层(第 08 章) —
工具 工具系统(第 03 章) —
规划 模型自己在循环内完成:每一轮"决定调用哪个工具"就是一次规划动作 Pi 刻意不内置规划器——任务分解是模型的推理能力,硬编码进框架反而把 Agent 退化成写死的流程
记忆 短期靠消息数组每轮重发(第 04 章);长期靠会话文件、上下文文件与压缩(第 05、07、04b 章) 核心只保留"消息数组"这一个最小机制;持久化、压缩、注入是产品层职责,可以各自演进

于是完整的表述是两层:

最小闭环(核心循环):  模型 + 工具调用
完整系统(产品外壳):  + 消息与记忆 + 上下文管理 + 会话 + 拦截 + 事件 ...

这个视角解释了一个常见困惑:Pi 为什么没有"记忆模块"?因为它把记忆拆成了三件具体机制——消息数组、会话文件、压缩——分别讲清楚,而不是提供一个叫 memory 的黑盒。

三、三层结构

既然能力边界由外壳决定,外壳内部又怎么组织?Pi 的做法可以概括成三句话:

  1. 模型无关的核心:循环、消息、工具、事件。它不依赖具体界面、具体模型服务商、具体文件布局,可以在任何前端、任何模型下复用。
  2. 产品环境:把核心组装成真正的编码助手——工作目录、会话、拦截策略、扩展、上下文文件。
  3. 界面:终端界面、一次性输出、结构化输出、进程间协议。界面只消费事件,不伸手改核心内部状态。

三个理由决定这条边界:

  • 可测试性:核心不依赖界面和文件布局,就能用"脚本化的假模型"做确定性测试。我们仓库里所有的离线实验,都是靠这一点跑起来的。
  • 可移植性:同一套核心可以同时驱动终端、脚本、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/:终端、协议等界面实现。

失败与边界实验

分层边界被违反时会发生什么?三个思想实验,都可以在源码里验证"为什么做不到":

  1. 让核心直接调用模型接口:循环里没有任何一行指向具体服务商——它只接受调用方注入的"流式请求函数"。换模型改的是调用方,不是循环。
  2. 让界面直接改消息数组:界面拿到的是事件和消息的副本,没有对内部状态的引用。想高亮某条消息,只能订阅消息更新事件,不能伸手进去改。
  3. 把拦截检查塞进循环:循环只在"执行工具"这一步调用工具,根本不知道拦截的存在。拦截属于工具执行的外围——这正是为什么每个项目的策略可以不同,而循环代码不变。

第三个实验是最有力的证据:边界画在包之间,而不是画在 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,看循环如何让模型真正"动起来"。