阶段一 · 架构与核心机制

消息与记忆 —— 模型眼里的"历史"长什么样

模型没有记忆。它每次看到的"历史",只是你这一轮重新喂给它的一串消息;而这串消息是你维护的。这一章讲清这串消息怎么组织、工具调用和结果为什么必须成对、以及"长期记忆"和对话历史到底是什么关系。

具体回答三个问题:模型怎么分清谁说的?调用和结果为什么必须成对?保存下来的历史怎么不被害?

学习目标

  • 理解"记忆 = 每轮重发的一串消息",以及为什么每条消息要标明来源。
  • 理解工具调用与结果的配对规则,以及不配对时会怎么被兜底。
  • 分清两类记忆:对话历史,和跨会话记忆。
  • 看懂我们实验里的消息结构,以及它为什么能容忍"不认识的记录"。

一、问题:模型的记忆从哪来

模型每次推理都是一次独立的调用,它不记得上一次说了什么。所谓"记忆",是外壳在每次请求时把整串消息重新喂给模型。

既然是重发,就必须让模型分得清:谁说的、说了什么。

  • 谁说的 → 每条消息有一个"角色"标记。
  • 说了什么 → 消息里按顺序排列若干"内容块":文字、图片、思考过程、工具调用请求。

二、四种基本角色

角色 谁写的 里面装什么
系统 外壳 人设、规则、工具清单(详见 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:一手参考。

失败与边界实验

消息数组是循环的命脉,经典失败几乎都发生在"配对"上:

  1. 只填了一半。 模型发起三个调用,执行器抛异常后只填了两条结果——下一次请求直接被拒。修法:循环层保证"每个调用必有结果",异常转成错误结果。
  2. 编号配错。 结果填给了错误的调用编号,模型会把 B 的结果当成 A 的。串行时不易发现,并行时是真实风险——这也是并行调度要求工具作者声明"是否可并发"的原因之一。
  3. 截断消息直接存档。 被截断的助手消息若原样保存,其残缺调用会在下次恢复时引爆。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 在请求前还有合成兜底。
  • 两类记忆:对话历史由外壳维护;跨会话记忆的价值在筛选不在积累。
  • 未知记录要保留:这是解析器的兼容性底线。

消息越积越长——窗口装不下时怎么办?先看会话管理讲历史怎么落盘,再看上下文压缩讲怎么瘦身。