阶段二 · 状态与边界
会话管理 —— 对话怎么存下来、怎么分叉
会话让 Agent 的记忆跨进程存活。Pi 的做法很朴素:一行一条记录,永远往后追加,每条只记住"我的上一条是谁"。这两个决定看起来简单,却顺手解决了三个问题:追加快、能边读边恢复、分支不需要特殊数据结构。这一章讲清这套设计,以及 1.x 新增的"只改上下文、不改历史"的编辑记录。
具体回答三个问题:对话怎么存才不怕崩?分支为什么不用专门的数据结构?"从上下文里删掉"为什么也要写一条新记录?
学习目标
- 理解会话为什么是一行一条记录,而不是一个大数组。
- 理解"只记父节点"为什么是"只追加"的前提。
- 分清四个容易混淆的操作:回退、分支、按消息分叉、整份复制。
- 理解"上下文编辑"为什么必须追加一条记录,而不是改原消息。
一、问题:进程退出后,对话去哪了
对话结束、进程退出,模型当然什么都不记得。要让记忆跨进程,必须把历史写到磁盘。两个基本问题是:存在哪、长什么样。
Pi 的答案是:默认放在用户目录下按工作目录分组的会话文件里,一行一条 JSON 记录。位置可以改,也可以用"不落盘"的模式跑一次性任务。
二、为什么是一行一条,而不是一个大数组
三个理由,都指向"追加友好":
- 可追加:新记录永远写在文件末尾。追加是常数时间,不需要读入整个文件、改完再写回。
- 可流式读:恢复时逐行读就行,不需要一次解析整个数组。很长的会话也能快速打开。
- 能容忍损坏:某一行坏了,跳过它,其余历史仍然可读;数组格式一处坏则整体报废。
一条典型的记录长这样:
{"type":"message","id":"a1b2c3d4","parentId":"prev1234","timestamp":"...","message":{"role":"user","content":"帮我看看这个报错"}}
每条记录都有自己的编号,和一条指向上一条的父编号。
三、只记父节点,不记子节点
会话其实是一棵树,但文件里没有任何一条记录"登记自己的孩子"。每条只写"我的父是谁"。
这不是省字段,而是只追加的前提:
- 追加新节点时,旧节点一律不动——旧节点根本不需要知道有了新孩子。
- 如果反过来记孩子,那么从历史中间再长出一个分支时,父节点的"孩子列表"就得被改写——一次改写就破坏了"只追加"。
于是"分支"变成了一件免费的事:回退只是把"当前末尾"挪到某个旧记录上,接着对话,新记录自然从那儿长出去。不需要"创建分支"这个动作,也不需要维护一份分支清单。
除了父子关系,文件里还有几类指向别的记录的引用,它们不参与建树,只描述语义:
| 记录 | 指向谁 | 说明 |
|---|---|---|
| 压缩 | 压缩后仍保留的第一条 | 压缩替换的是"模型看到的投影",不是文件 |
| 分支摘要 | 被放弃的那条旧末尾 | 离开一条分支时给它留个总结 |
| 标签 | 被打标记的那条 | 书签、重命名 |
| 上下文编辑 | 被编辑的那条 | 只改"以后怎么看待它" |
所以准确的说法是:树靠父编号重建,语义靠这些指向表达。只看父编号能画出分支形状,但画不出"这里压缩过、那里改写过上下文"。
四、四个容易混淆的操作
| 操作 | 做了什么 | 文件层面 |
|---|---|---|
| 回退 | 把"当前末尾"挪到某个历史点;如果选中的是用户消息,末尾会指向它的上一条,把那句话放回编辑器 | 不删、不改任何记录 |
| 分支 | 回退之后继续对话,新记录从新末尾长出去 | 只追加 |
| 按消息分叉 | 选一条用户消息,只把"从开头到它"这条路复制成一个新会话文件 | 新建文件,记下"我从哪个会话来" |
| 复制当前分支 | 把当前这条分支整个复制成一个新会话 | 新建文件 |
| 整份复制 | 把一个会话文件的**所有记录(含别的分支)**复制进当前目录 | 新建文件 |
两个常见混淆:
- "按消息分叉"和"整份复制"不是一回事。前者按一条消息切出一条路径,后者连别的分支一起搬过来。
- "回退只挪末尾"是简化说法。末尾本身不写在文件里(重开时取最后一条);如果用户在回退时选择"给离开的分支写个总结",系统还会追加一条分支摘要和可能的标签——依然不动旧记录。
五、跟着一条记录走一遍
假设你在会话里说到第 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
边界与安全
- 不要用第三方工具直接改写正在使用的会话文件:保留备份、写入前验证版本、恢复后审计工具调用记录。
- 解析器应保留不认识的记录,而不是静默重写——版本演进时旧记录仍可能被读到。
- 上下文编辑只影响模型看到的上下文,不是删除数据:原文仍在文件里,导出或审计时照样可见。真要清除敏感信息,得清理文件本身。
自测三问
- 回退到一条用户消息时,"当前末尾"指向它还是它的上一条?为什么?
- 按消息分叉和整份复制,对新文件内容的影响有什么本质区别?
- 为什么"从上下文里省略某条消息"也要写一条新记录,而不是直接删掉?
回顾
- 一行一条记录:追加快、能流式读、能容忍损坏。
- 只记父节点:建树靠父编号,压缩、摘要、标签、编辑靠各自的指向表达语义。
- 回退 = 挪末尾;分支 = 回退后继续写的自然结果;分叉、复制、整份复制是三件事。
- 操作痕迹也上树:回退能还原完整会话状态。
- 上下文编辑:连改上下文都靠追加,历史永不改写。