Pi Coding Agent 08：Session Runtime——树形分支历史、断点恢复与结构化上下文压缩

在真实的软件工程长程任务中，“把对话保存到文件”是非常初级的操作。真正决定一个 Agent 工业级可用性的，是它能否在经历长时间中断、程序崩溃或方案推翻重来后，恢复到一个依然能够清醒推进工作的稳健状态：

  • 用户的初始目标有没有被丢弃？
  • 已经发生的关键文件修改和失败的单元测试事实有没有保留？
  • 用户回到 5 步之前尝试了另一个分支方案，旧方案的试错证据会不会被粗暴覆盖？
  • 会话达到数十轮后，上下文窗口被撑爆时，系统如何在不丢失关键证据的前提下完成优雅压缩？

Pi 的 Session Runtime 将会话设计为一个基于父指针链接的 JSONL 事实树（DAG / Tree），并把持久历史、活动分支与模型上下文进行了彻底的工程解耦。

一、三层状态解耦：历史不动，上下文按预算重建

在深入代码之前，我们必须在认知上确立三层状态的清晰边界：

[!NOTE]
核心口诀：“历史不动，上下文按预算重建”
会话文件只做单调追加写（Append-Only），哪怕执行了上下文压缩，旧的历史事实也永远完好无损地躺在硬盘中；送给模型的上下文，永远只是从当前活动叶子节点出发、经过预算裁剪后的一次即时投影视图。

二、为什么是树而不是线性列表？

在常规的线性对话中，如果模型给出了方案 A，你测试后发现方向偏了，想回到上一步让它尝试方案 B。传统的做法要么把方案 A 彻底覆写删除，要么复制一份完整的历史文件。

Pi 将每一个 Entry（条目）赋予了全局唯一 id 与 parentId 父指针：

物理存储在一个单一的 JSONL 文件中，每一行记录一个 JSON 对象：

1
2
3
4
5
6
7
{"type":"session","version":3,"id":"sess-001","timestamp":"2026-08-24T10:00:00Z","cwd":"/workspace"}
{"type":"message","id":"u1","parentId":null,"message":{"role":"user","content":"重构队列模块"}}
{"type":"message","id":"a1","parentId":"u1","message":{"role":"assistant","content":"有两种思路..."}}
{"type":"message","id":"u2-A","parentId":"a1","message":{"role":"user","content":"先试方案 A"}}
{"type":"message","id":"a2-A","parentId":"u2-A","message":{"role":"assistant","content":"方案 A 产生死锁..."}}
{"type":"message","id":"u2-B","parentId":"a1","message":{"role":"user","content":"回到分叉点，改用方案 B"}}
{"type":"message","id":"a2-B","parentId":"u2-B","message":{"role":"assistant","content":"方案 B 成功跑通..."}}

这种树形设计的工程收益极其巨大：

  1. 试错证据永不丢失：方案 A 为什么失败被如实记录，事后审计清晰明了；
  2. 零复制分支：尝试新分支只需要挂接一个新的父指针节点，没有任何文件复制开销；
  3. 上下文干净无污染：当模型在分支 B 执行时，回溯算法只会收集 u1 -> a1 -> u2-B -> a2-B 这条祖先路径，方案 A 的冗余噪声被天然隔绝在外。

三、区分三大分支命令：/tree、/fork 与 /clone

为了在不同业务场景下管理这条事实树，Pi 提供了三个语义分明的交互命令：

操作命令 物理文件变化 节点选择范围 最佳适用场景
/tree 保持在同一个 Session 文件中 在当前事实树的任意历史节点间自由跳转 在同一个任务中探索不同实现思路，保留完整试错脉络
/fork 创建全新的独立 Session 文件 选择此前某个特定的 user 需求节点截断 发现了一个全新业务方向，以此为起点开启一段全新任务
/clone 创建全新的独立 Session 文件 完整复制当前活动祖先路径的快照 需要把当前的阶段性研发进度分发给同事或作为安全基线备份

[!TIP]
分支离开时的 Branch Summary：使用 /tree 切换分支时，Pi 可以在离开旧分支的瞬间，自动总结该分支的重要技术发现（例如“证实了方案 A 存在死锁，需规避组件 X”），并以 branch_summary 节点的形式随父节点带入新分支，实现知识的平滑迁移。

四、Compaction：绝不切断工具调用的结构化压缩

当任务轮次极多导致当前祖先路径的 Token 数量逼近模型上下文窗口上限时，系统会自动触发上下文压缩（Context Compaction）。

1. 触发时机

1
当前上下文 Token > 模型上下文窗口 - 保留缓冲预算 (reserveTokens，默认 16384)

2. 铁律：切点绝不能落在工具交互中间

大模型发起的工具调用往往是一个闭环：toolCall 发起 $\rightarrow$ toolResult 落地。如果压缩算法机械地按照字数切断，把切点刚好选在调用发出和结果返回之间，恢复后的模型就会看到一个“发出了请求但没有回应”的悬空脏状态。
Pi 的切点算法强制要求：必须以完整的交互轮次（Turn）为单位进行安全切片，严禁拆散任何一对成对的工具事实！

3. 一份结构化压缩摘要必须保留的六大支柱

压缩绝不是调用模型写一段空洞的“前情提要”，Pi 要求的结构化摘要必须忠实承载工程状态交接：

  • Goal（终极目标）：用户最初下达的不可偏离的核心业务诉求；
  • Constraints（硬性约束）：绝对不能触碰的目录、必须遵循的代码风格；
  • Progress（当前进展）：哪些模块已重构、哪些正在进行、卡点在哪里；
  • Key Decisions（关键决策）：为什么选择了方案 B 并放弃了方案 A；
  • Next Steps（后续动作）：下一步应当运行什么测试、编辑什么文件；
  • File Ledger（文件账本）：精确记录已被读取的文件列表与已被修改的文件列表。

压缩完成后，旧的历史条目继续保留在底层 JSONL 文件中，系统只是追加了一条类型为 compaction 的节点。下一次向模型组装请求时，被压缩的旧区间被优雅遮蔽，模型以极低成本的摘要节点轻松轻装上阵。

五、编程式内嵌实战：Node.js SDK 集成

除了在终端交互，任何 Node.js 平台都可以直接利用 @earendil-works/pi-coding-agent 的 SDK 编程式操控一个具备完整 Session 树能力的 Agent：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
import {
  createAgentSession,
  ModelRuntime,
  SessionManager,
} from "@earendil-works/pi-coding-agent";

// 1. 初始化模型运行时环境
const modelRuntime = await ModelRuntime.create();

// 2. 创建具备持久化或内存管理能力的 Agent Session
const { session } = await createAgentSession({
  // 可以选择保存在磁盘文件，也可以选择完全在内存中运行 (单元测试)
  sessionManager: SessionManager.inMemory(),
  modelRuntime,
});

// 3. 订阅细粒度的流式更新事件
const unsubscribe = session.subscribe((event) => {
  if (
    event.type === "message_update" &&
    event.assistantMessageEvent.type === "text_delta"
  ) {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

// 4. 发送指令驱动任务
await session.prompt("请检查当前代码库的 ESLint 规范并修复警告");

// 5. 优雅收尾并销毁资源
unsubscribe();
session.dispose();

六、全专栏总结：极简 Harness 的工程魅力

至此，《Pi Coding Agent 核心与实战》专栏的 9 篇深度解析全部完结。

回顾整个探索历程：

Pi 给所有 Agent 架构师展示了一种令人击节赞赏的克制美学：它不盲从技术热词，坚决不把特定工作流硬塞给用户；它用最小巧、最稳固的基元，为真正需要打造个性化、嵌入式智能体系统的开发者，提供了一根无可替代的定海神针。