阶段一 · 架构与核心机制
消息与记忆 —— 模型眼里的"历史"长什么样
模型没有记忆。它每次看到的"历史",只是你这一轮重新喂给它的一串消息;而这串消息是你维护的。这一章讲清这串消息怎么组织、工具调用和结果为什么必须成对、以及"长期记忆"和对话历史到底是什么关系。
具体回答三个问题:模型怎么分清谁说的?调用和结果为什么必须成对?保存下来的历史怎么不被害?
学习目标
- 理解"记忆 = 每轮重发的一串消息",以及为什么每条消息要标明来源。
- 理解工具调用与结果的配对规则,以及不配对时会怎么被兜底。
- 分清两类记忆:对话历史,和跨会话记忆。
- 看懂我们实验里的消息结构,以及它为什么能容忍"不认识的记录"。
一、问题:模型的记忆从哪来
模型每次推理都是一次独立的调用,它不记得上一次说了什么。所谓"记忆",是外壳在每次请求时把整串消息重新喂给模型。
既然是重发,就必须让模型分得清:谁说的、说了什么。
- 谁说的 → 每条消息有一个"角色"标记。
- 说了什么 → 消息里按顺序排列若干"内容块":文字、图片、思考过程、工具调用请求。
二、四种基本角色
| 角色 | 谁写的 | 里面装什么 |
|---|---|---|
| 系统 | 外壳 | 人设、规则、工具清单(详见 04b 章) |
| 用户 | 用户 | 文字,或文字 + 图片 |
| 助手 | 模型 | 文字、思考块,或"我要调用某个工具"的请求 |
| 工具结果 | 被调用的工具 | 执行结果(文字或图片),带调用编号 |
四种之外,产品层还会加几种"专属消息",用来承载产品自己的状态:
| 角色 | 来源 | 会不会进模型上下文 |
|---|---|---|
| 命令记录 | 用户在终端里直接跑的命令(不经过模型) | 默认会,转成一段用户文本 |
| 自定义消息 | 扩展塞进来的 | 由扩展决定 |
| 分支摘要 | 在会话树里切走时生成的摘要 | 会,用标签包起来 |
| 压缩摘要 | 压缩历史生成的摘要 | 会,替代被压掉的那段历史 |
后两者的意义是保住因果:摘要不是旁注,而是模型后续推理的一部分。这也解释了为什么它们必须和普通消息走同一条管线——存档、渲染、回放都按角色分发,压缩和分支才不需要在每个前端各写一套。
这里有个容易混的点:用户在终端里直接跑的命令,和模型调用命令工具,是两种记录。前者是一条"命令记录"消息,后者是一条普通的"工具结果",两者长得像,来源完全不同。
三、成对:调用与结果
助手说"我要调用工具",会带一个唯一编号;工具执行完,回填一条带同样编号的结果。两者必须成对出现——这是模型服务商的硬要求,缺一半,下一次请求就不合法。
这个约束的影响贯穿全书:压缩时"成对不拆"(第 07 章)、恢复会话时审计工具记录(第 05 章)、截断时整批作废(第 02 章)——根子都在这里。
Pi 还在请求发出去之前的最后一步做了兜底:发现某个调用没有对应结果,就补一条"没有返回结果"的合成错误结果,而不是把残缺上下文直接发出去。兜底能救急,但它意味着模型会看到一条自己没执行过的失败——真正的修法仍然是在循环里保证每个调用都有结果。
四、两类记忆
| 记忆 | 存在哪 | 活多久 | 职责 |
|---|---|---|---|
| 对话历史 | 消息数组 / 会话文件 | 一次会话内 | 模型推理的完整上下文 |
| 跨会话记忆 | 单独的库(通常是扩展实现) | 跨会话 | 事实、偏好、教训,按需筛选注入 |
跨会话记忆的价值在筛选,不在积累:不是把所有历史都存下来,而是把值得复用的事实挑出来,在需要时注入。存储是次要问题,筛选策略才是记忆系统的核心——这也是社区记忆类扩展真正的着力点。
当前 Pi 行为
- 消息只追加,不改写历史;连"改上下文"也不动原消息,而是追加一条编辑记录(见 05 章)。
- 工具结果靠调用编号配对;存档时消息被序列化进会话文件。
- 角色是显式判别:四种基本角色,加上产品层用声明合并扩展的四种专属角色。消费方必须能容忍不认识的追加角色。
- 系统消息承载分节提示词:后续更新只发"哪一节变了",删除一节用空值表示。
- 消息有开始、流式更新、结束三个事件;流式更新只对助手消息发。
- 输出被长度截断时,整批工具调用会作废并回填错误,保证调用与结果仍然成对。
代码里的名字
| 通俗说法 | 代码里的名字 |
|---|---|
| 四种基本角色 | system / user / assistant / toolResult |
| 命令记录 | bashExecution |
| 自定义消息 | custom |
| 分支摘要 / 压缩摘要 | branchSummary / compactionSummary |
| 调用编号 | toolCallId |
| 分节提示词 | 系统消息里的 sections |
源码位置
packages/ai/src/types.ts:内容块与四种基本消息。packages/coding-agent/src/core/messages.ts:四种产品消息。packages/coding-agent/docs/message-types.md:一手参考。
失败与边界实验
消息数组是循环的命脉,经典失败几乎都发生在"配对"上:
- 只填了一半。 模型发起三个调用,执行器抛异常后只填了两条结果——下一次请求直接被拒。修法:循环层保证"每个调用必有结果",异常转成错误结果。
- 编号配错。 结果填给了错误的调用编号,模型会把 B 的结果当成 A 的。串行时不易发现,并行时是真实风险——这也是并行调度要求工具作者声明"是否可并发"的原因之一。
- 截断消息直接存档。 被截断的助手消息若原样保存,其残缺调用会在下次恢复时引爆。Pi 的做法是在入列前就把这批调用作废化,保证任何进入历史的消息都是成对完整的。
python3 -m unittest tests.test_13_mini_agent -v
在 Pi 里怎么操作
- 会话文件就是消息序列化的产物,可以用第 11 章的只读统计工具看。
- 跨会话记忆要装记忆类扩展,不在核心里。
Python 实验
mini_agent.py 用 dataclass 实现同一套判别结构,角色是默认字段:
@dataclass(frozen=True)
class ToolResultMessage:
role: str = "toolResult"
tool_call_id: str = "" # 与助手的调用请求配对
tool_name: str = ""
content: str = ""
is_error: bool = False
更值得看的是它的存取往返。dump_messages 把消息写成一串 JSON 记录,load_messages 按角色重建——遇到不认识的记录就原样保留成一个字典,而不是丢掉或改写:
def _from_record(record):
role = record.get("role")
if role == "user": return UserMessage(...)
if role == "assistant": return AssistantMessage(...)
if role == "toolResult": return ToolResultMessage(...)
return record # 不认识的记录:原样保留
这一行 return record 是整份实现里最重要的兼容性决定。消息模型会演进,新版本可能加新角色;一个只认识旧角色的解析器如果遇到新记录就崩,或者"顺手"把它重写成空消息,用户的会话就毁了。保留未知记录,意味着旧工具读新会话不会破坏数据。
python3 -m learn_pi_lab lab mini-agent # 输出含 loaded_roles:JSONL 往返后的角色序列
Tau 用 Pydantic 的判别字段实现同一模型,思路一致。
这一模块的核心代码在核心代码导览 · 消息回填有逐段解读。
验证方式
python3 -m unittest tests.test_13_mini_agent -v
边界与安全
- 消息里可能有敏感数据(密钥、日志):存档与日志输出都应脱敏。
- 不要无条件信任历史里的工具结果:恢复会话后应审计工具调用记录。
- 消息模型是兼容性契约:新增角色必须向后兼容,不认识的记录要保留而不是丢弃。
自测三问
- 为什么"改上下文"不能直接改那条消息?
- 模型调用工具失败时,回填的结果应该长什么样?为什么不能直接把异常抛出去?
- 一个只认识旧角色的解析器,读到新角色的记录时最稳妥的做法是什么?
回顾
- 记忆 = 每轮重发的一串消息:角色标明来源,内容块按顺序排列。
- 成对回填:调用与结果靠编号配对,模型服务商要求成对;Pi 在请求前还有合成兜底。
- 两类记忆:对话历史由外壳维护;跨会话记忆的价值在筛选不在积累。
- 未知记录要保留:这是解析器的兼容性底线。