阶段二 · 状态与边界

会话管理 —— 对话怎么存下来、怎么分叉

会话让 Agent 的记忆跨进程存活。Pi 的做法很朴素:一行一条记录,永远往后追加,每条只记住"我的上一条是谁"。这两个决定看起来简单,却顺手解决了三个问题:追加快、能边读边恢复、分支不需要特殊数据结构。这一章讲清这套设计,以及 1.x 新增的"只改上下文、不改历史"的编辑记录。

具体回答三个问题:对话怎么存才不怕崩?分支为什么不用专门的数据结构?"从上下文里删掉"为什么也要写一条新记录?

学习目标

  • 理解会话为什么是一行一条记录,而不是一个大数组。
  • 理解"只记父节点"为什么是"只追加"的前提。
  • 分清四个容易混淆的操作:回退、分支、按消息分叉、整份复制。
  • 理解"上下文编辑"为什么必须追加一条记录,而不是改原消息。

一、问题:进程退出后,对话去哪了

对话结束、进程退出,模型当然什么都不记得。要让记忆跨进程,必须把历史写到磁盘。两个基本问题是:存在哪、长什么样。

Pi 的答案是:默认放在用户目录下按工作目录分组的会话文件里,一行一条 JSON 记录。位置可以改,也可以用"不落盘"的模式跑一次性任务。

二、为什么是一行一条,而不是一个大数组

三个理由,都指向"追加友好":

  1. 可追加:新记录永远写在文件末尾。追加是常数时间,不需要读入整个文件、改完再写回。
  2. 可流式读:恢复时逐行读就行,不需要一次解析整个数组。很长的会话也能快速打开。
  3. 能容忍损坏:某一行坏了,跳过它,其余历史仍然可读;数组格式一处坏则整体报废。

一条典型的记录长这样:

{"type":"message","id":"a1b2c3d4","parentId":"prev1234","timestamp":"...","message":{"role":"user","content":"帮我看看这个报错"}}

每条记录都有自己的编号,和一条指向上一条的父编号。

三、只记父节点,不记子节点

会话其实是一棵树,但文件里没有任何一条记录"登记自己的孩子"。每条只写"我的父是谁"。

这不是省字段,而是只追加的前提:

  • 追加新节点时,旧节点一律不动——旧节点根本不需要知道有了新孩子。
  • 如果反过来记孩子,那么从历史中间再长出一个分支时,父节点的"孩子列表"就得被改写——一次改写就破坏了"只追加"。

于是"分支"变成了一件免费的事:回退只是把"当前末尾"挪到某个旧记录上,接着对话,新记录自然从那儿长出去。不需要"创建分支"这个动作,也不需要维护一份分支清单。

除了父子关系,文件里还有几类指向别的记录的引用,它们不参与建树,只描述语义:

记录 指向谁 说明
压缩 压缩后仍保留的第一条 压缩替换的是"模型看到的投影",不是文件
分支摘要 被放弃的那条旧末尾 离开一条分支时给它留个总结
标签 被打标记的那条 书签、重命名
上下文编辑 被编辑的那条 只改"以后怎么看待它"

所以准确的说法是:树靠父编号重建,语义靠这些指向表达。只看父编号能画出分支形状,但画不出"这里压缩过、那里改写过上下文"。

四、四个容易混淆的操作

操作 做了什么 文件层面
回退 把"当前末尾"挪到某个历史点;如果选中的是用户消息,末尾会指向它的上一条,把那句话放回编辑器 不删、不改任何记录
分支 回退之后继续对话,新记录从新末尾长出去 只追加
按消息分叉 选一条用户消息,只把"从开头到它"这条路复制成一个新会话文件 新建文件,记下"我从哪个会话来"
复制当前分支 把当前这条分支整个复制成一个新会话 新建文件
整份复制 把一个会话文件的**所有记录(含别的分支)**复制进当前目录 新建文件

两个常见混淆:

  1. "按消息分叉"和"整份复制"不是一回事。前者按一条消息切出一条路径,后者连别的分支一起搬过来。
  2. "回退只挪末尾"是简化说法。末尾本身不写在文件里(重开时取最后一条);如果用户在回退时选择"给离开的分支写个总结",系统还会追加一条分支摘要和可能的标签——依然不动旧记录。

五、跟着一条记录走一遍

假设你在会话里说到第 20 条消息时,让 Agent 重新回答第 12 条那个问题。文件里发生了什么?

① 找到第 12 条(用户消息)
② 把"当前末尾"挪到第 11 条——不是第 12 条,因为要把第 12 条那句话放回输入框
③ 你重新编辑后发送,新用户消息的父编号 = 第 11 条
④ 模型回复,父编号 = 新用户消息

文件末尾变成:

... 第 11 条
    第 12 条  ← 原来的分支,仍然在,但不在当前路径上
    ...
    第 20 条
    新用户消息(父 = 第 11 条)   ← 分叉点在这里
    新助手回复

关键点:没有一条旧记录被修改或删除。第 12 条到第 20 条还在文件里,只是不再属于"当前路径"。你随时可以再挪回去。

如果此时用户选择"给离开的分支留个总结",文件末尾会再多一条摘要记录和一条标签记录——依然是追加。

六、记录有几类

除去开头的会话头(版本、编号、时间、工作目录、可选的血缘信息),正文有十一类记录,按用途分四组:

分组 记录 作用
元信息 会话信息、标签 重命名、书签
对话内容 消息、压缩、分支摘要 模型看得到的上下文
操作痕迹 切换模型、切换思考强度、扩展自定义数据、扩展自定义消息 回退到任一历史点都能还原当时状态
计量与改写 使用量、上下文编辑 计费记录;只改未来上下文的编辑

其中三类值得单独认识:

  • 使用量:记录那些不是助手回复、但也花钱的调用(比如缓存预热)。它计入 token 与成本,但不进模型上下文,在会话树视图里也不显示。
  • 上下文编辑:它不改目标记录,只追加一条"以后请这样看它"的说明:可以从上下文里省略它,也可以替换它的内容。同一个目标以当前分支上最新的一条为准——换句话说,编辑是分支相对的:换个分支,看到的可能就是原样。
  • 压缩:除了摘要本身,还带一份完整的系统消息检查点,并把"压缩后仍保留的第一条"记下来;如果它指向自己,意思是"一条旧消息都不保留"。

至于"切换模型"也占一条记录,是为了回退时能还原当时的完整状态:当时用哪个模型、什么思考强度、系统提示词是哪一版。系统提示词本身不单独存一条,而是存在系统消息记录里,按段名打补丁——回放这些补丁,就得到当时的提示词。

七、上下文编辑:连"改上下文"都不许改历史

这是新版本里最能体现设计一致性的机制。

需求很普通:某条历史消息现在不该让模型看见了(过期了、敏感了、被纠正了)。最直接的做法是改那条消息,或者删掉它。但那样就违反了"只追加",历史也就不再可审计。

Pi 的做法是:原样保留,另外追加一条编辑记录。读取方在重建上下文时,按当前分支把编辑应用上去,得到一个"投影"——模型看到的是投影,磁盘上仍是原文。

代价是每个读取方都要实现这层投影;收益是任何历史版本都能重放、能审计、能对比。连"省略"这件事本身都留下了痕迹。

当前 Pi 行为

  • 会话默认存在用户目录下,按工作目录分组,一行一条记录;位置可配置,也可完全不落盘。
  • 记录版本为 v3;旧版本会话在加载时自动迁移,并把迁移结果写回文件。
  • 回退、分支、按消息分叉、复制当前分支、整份复制是五个不同操作;分叉与复制都会在新文件里留下血缘信息。
  • 导出有两种格式:给人类看的网页,和给程序读的原始记录——按导出路径的后缀决定。
  • 存储后端可以替换:除了内置实现,还有一个独立的持久化包提供内存、浏览器数据库、SQLite、追加式文件四种后端。
  • 扩展可以在"一轮结束"或"运行即将结算"的边界上,把自定义记录、上下文编辑、压缩草案按序落盘。

代码里的名字

通俗说法 代码里的名字
一行一条记录 JSONL,当前格式版本 v3
记录编号 / 父编号 id / parentId
上下文编辑 context_edit(replacement 为空表示省略)
使用量记录 usage
压缩后保留的第一条 firstKeptEntryId
分支摘要的来源 fromId
血缘信息 会话头里的 parentSession
可替换存储 @earendil-works/pi-durable

源码位置

  • packages/coding-agent/src/core/session-manager.ts:读写、索引、迁移、投影。
  • packages/coding-agent/docs/session-format.md:逐字段的格式说明。
  • packages/coding-agent/docs/sessions.md:会话相关命令与行为。
  • packages/durable/:可替换的存储后端。

失败与边界实验

只追加的存储会遇到哪些失败?lab session-tree 与对应测试覆盖了四类:

场景 表现 为什么安全
最后一行写一半就崩了 读取时丢弃不完整行,之前的历完好 只追加:坏只坏最后一条
同一条被追加两次 重建时按编号去重或报诊断 编号是幂等键
引用了不存在的父节点 报错而不是静默丢分支 孤儿记录可见,不会悄悄消失
从中间回退后继续写 新记录指向那个旧节点,形成分支 只记父节点:重建由子向父

对比一个反例:如果会话用"整文件重写"存储(读取—修改—写回),第一种失败会损坏全部历史,第四种还需要显式的分支数据结构。只追加 + 父编号把这两个问题都消解在格式层。

而上下文编辑反过来证明了这条原则有多硬:连"改上下文"都不允许改写历史,只能再追加一条。代价是读取方要会做投影,收益是任何时候都能重放与审计。

python3 -m learn_pi_lab lab session-tree
python3 -m unittest tests.test_04_session_tree -v

在 Pi 里怎么操作

  • 开新会话、恢复历史会话、浏览并选择。
  • 在会话树里导航,从任意历史点继续;离开的分支可以选择是否留下摘要。
  • 按消息分叉、复制当前分支、整份复制,各有对应命令。
  • 导出为网页或原始记录;分享会生成链接。
  • 导入一个会话文件接着跑;也可以给会话改名。

Python 实验

session_tree.py 用不到一百行实现"只追加 + 父指针"的会话树。它先校验,再查询:

for entry in self._entries:
    if entry.id in entries_by_id:                  # ① 编号不能重复
        raise MalformedTranscript(...)
for entry in self._entries:
    if entry.parent_id == entry.id:                # ② 不能自己当自己的父
        raise MalformedTranscript(...)
    if entry.parent_id is not None and entry.parent_id not in entries_by_id:
        raise MalformedTranscript(...)             # ③ 父节点必须存在

而"重建一条分支"只有一层循环:

def path_to(self, leaf_id):
    current = self._entries_by_id[leaf_id]
    branch = []
    while True:
        branch.append(current)
        if current.parent_id is None:
            break
        current = self._entries_by_id[current.parent_id]
    return tuple(reversed(branch))

设计点:分支不是数据结构,是查询结果。从任意末尾沿父指针走到底,就是一条分支。没有"分支列表"要维护,自然也就没有分支不一致的 bug。校验放在构造时做,意味着损坏的快照根本进不来,而不是等查询时才炸。

需要说明它没做什么:这个教学模型没有实现上下文编辑的投影、使用量计量、压缩检查点——这三样是新版本的真实增量,需要按上一节的记录表自己补。补的时候你会发现,投影逻辑必须"按当前分支应用",否则跨分支就会串味。

session_inspector.py 则是只读的一方:逐行读记录、统计角色与压缩次数,不执行内容、不修改文件。它对不认识的记录类型选择忽略而非报错——这正是兼容新旧版本的关键。

python3 -m learn_pi_lab lab session-tree   # 打印一条从开头到末尾的分支

这一模块的核心代码在核心代码导览 · 会话树有逐段解读。

验证方式

python3 -m unittest tests.test_04_session_tree tests.test_11_projects -v

边界与安全

  • 不要用第三方工具直接改写正在使用的会话文件:保留备份、写入前验证版本、恢复后审计工具调用记录。
  • 解析器应保留不认识的记录,而不是静默重写——版本演进时旧记录仍可能被读到。
  • 上下文编辑只影响模型看到的上下文,不是删除数据:原文仍在文件里,导出或审计时照样可见。真要清除敏感信息,得清理文件本身。

自测三问

  • 回退到一条用户消息时,"当前末尾"指向它还是它的上一条?为什么?
  • 按消息分叉和整份复制,对新文件内容的影响有什么本质区别?
  • 为什么"从上下文里省略某条消息"也要写一条新记录,而不是直接删掉?

回顾

  • 一行一条记录:追加快、能流式读、能容忍损坏。
  • 只记父节点:建树靠父编号,压缩、摘要、标签、编辑靠各自的指向表达语义。
  • 回退 = 挪末尾;分支 = 回退后继续写的自然结果;分叉、复制、整份复制是三件事。
  • 操作痕迹也上树:回退能还原完整会话状态。
  • 上下文编辑:连改上下文都靠追加,历史永不改写。

会话会越来越长——上下文压缩讲窗口装不下时怎么办;在那之前,先看事件驱动与扩展,理解界面如何观察这一切。