分支与分叉
三种回到过去的方式——/tree、/fork 和 /clone——以及当一次错误的转向该留在会话里还是变成独立的工作时,该如何选择。
智能体挑了一个你不想要的 schema,改了十一个文件,并且正信心十足地在你已经决定摒弃的那条思路里推进了三步。你按下 Escape。现在怎么办?
有三个答案,而选错一个,会让你付出丢掉你真正想要的那份工作的代价。/tree 在会话内部移动。/fork 从一条更早的消息开始一个新会话。/clone 把当前分支复制进一个新会话。这个区别不是表面功夫——它决定了当你回来时,那次被放弃的尝试还在不在。
树是存储模型
“Pi 把条目存储为一棵树,所以回到一个更早的点,并不会抹掉你离开的那条分支。“每个条目都带着 id 和 parentId;分支"从一个更早的条目创建新的子条目”;当前位置是叶子。
[用户消息] ─── [助手] ─── [用户消息] ─── [助手]┬─ [用户消息] ← 当前叶子
│
└─ [branch_summary] ─── [用户消息] ← 另一条分支
最后一行是那个会改变你如何阅读会话的部分。另一条分支始于一个 branch_summary 条目,而不是一条光秃秃的用户消息。离开一条分支,可能会交给你一份关于你离开了什么的摘要。
错误:“活动分支就是会话——不在它上面的任何东西都没了。” 正确:它是穿过一棵树的一条路径。
extensions.md把后果说得很明确:从getBranch()重建状态,“而不是从每一个文件条目,因为被放弃的分支代表另类的历史。”
选择一条命令
| 操作 | 结果 | 什么时候用它 |
|---|---|---|
/tree |
在当前的会话文件内移动 | 相关的备选方案应该待在一起 |
/fork |
从一条更早的用户消息创建一个新会话 | 这个备选方案应该变成独立的工作 |
/clone |
把活动分支复制进一个新会话 | 你想要当前状态的一份单独副本 |
sessions.md 直接给出了这些用例。这张表没有说的是,它们各自对历史做了什么:
flowchart TD
P["你所在的那个条目"]
P -->|"/tree"| T["新分支,同一个文件"]
P -->|"/fork"| F["新文件,从一条更早的用户消息开始"]
P -->|"/clone"| C["新文件,从活动分支开始"]
T --> T2["你离开的那条分支会留下,并可以被摘要、带到你进入的分支"]
F --> F2["什么都不会带过去;新文件里没有它的记录"]
C --> C2["只有活动分支;被放弃的分支不会跟过来"]
只有 /tree 能留下一个指回你所离开之处的指针,而且只有在你接受摘要时才会:branch_summary 条目把它记录在 fromId 里。所以 /tree 是三者中唯一能把被放弃路径的摘要交到你手里的。如果那次尝试教给了你一些你将会用到的东西,它属于同一个文件。如果它是一个你会交给别人的任务,它就不属于。
/tree 内部
在你开始之前,这个交互有一条值得知道的规则。“在 /tree 中,选中一条用户消息,把它的文本放回编辑器。编辑并提交它,就创建出另一条分支。选中一条助手响应或另一个条目,则在该条目之后以一个空编辑器继续。”
于是有两种选中结果:
- 选中一条用户消息 → 它的文本回到你的编辑器里。改掉它,提交它,你就得到一条从那道提示词分叉出去的新分支。
- 选中一条助手响应或任何其他条目 → 你在该条目之后继续,带着一个空编辑器。
第一个是一个新问题;第二个是从一个既有点继续。settings.md 给了一个会模糊这条界线的捷径:doubleEscapeAction,取值 "tree"、"fork" 或 "none",默认 "tree"——“编辑器为空时按两次 Escape 的动作。“如果你在一个空编辑器上按两次 Escape,默认会进入 /tree。如果你的本能是开新会话,就把它改成 "fork"。
树视图打开时是经过过滤的。treeFilterMode 取 "default"、"no-tools"、"user-only"、"labeled-only" 或 "all",默认 "default"。
离开一条分支会让你付出什么
“当你离开一条分支时,Pi 可以为它做摘要,并把那份摘要附到你进入的那条分支上。这样既保留了被放弃路径上相关的工作,又不必包含它的每一条消息。”
这套机制来自 compaction.md:
- 找到共同祖先 — 旧位置与新位置共享的那个最深节点。
- 收集条目 — 从旧叶子一路走回那个祖先。
- 带着预算准备 — 在 token 预算内包含消息,从最新的开始。
- 生成摘要 — 以结构化格式调用 LLM。
- 追加条目 — 在导航点保存一个
BranchSummaryEntry。
导航之前的树:
┌─ B ─ C ─ D(旧叶子,正被放弃)
A ───┤
└─ E ─ F(目标)
共同祖先:A
要摘要的条目:B、C、D
带摘要导航之后:
┌─ B ─ C ─ D
A ───┤
└─ E ─ F ─ [B、C、D 的摘要](新叶子)
注意,被放弃的条目 B、C 和 D 在这次移动之后仍然在树里。摘要是新增,不是替换——这正是第 23 章在压缩上发现的同一个性质。
这个条目记录了两端:
interface BranchSummaryEntry<T = unknown> {
type: "branch_summary";
id: string;
parentId: string | null;
timestamp: string;
summary: string;
fromId: string; // Entry we navigated from
usage?: Usage; // LLM usage that generated the summary
fromHook?: boolean; // true if provided by extension (legacy field name)
details?: T; // implementation-specific data
}
parentId 是"新分支由之继续的那个条目”,而 fromId 是"其被放弃路径被摘要掉的前一个叶子”。两个不同的指针,正是它让你能重建出你是从哪儿跳过来的。
你可以拒绝摘要。settings.md 暴露了 branchSummary.skipPrompt(默认 false)和 branchSummary.reserveTokens(默认 16384)——“摘要分支历史时预留的 token 数。“把 skipPrompt 设为 true 会跳过提示,并默认不做摘要。如果你宁愿丢掉上下文也不想为它付费,这就是你的设置。
从程序里做这件事
同样的三个操作在 RPC 之上也存在,而响应会告诉你是否有扩展介入过。
{"type": "get_fork_messages"}
{
"type": "response",
"command": "get_fork_messages",
"success": true,
"data": {
"messages": [
{"entryId": "abc123", "text": "First prompt..."},
{"entryId": "def456", "text": "Second prompt..."}
]
}
}
从其中之一分叉:
{"type": "fork", "entryId": "abc123"}
响应会返回 "text": "The original prompt text...",以及 "cancelled": false。这段文本对一个 UI 很重要:它就是你要放回编辑器里的东西,好让用户能编辑原始提示词,而不是重新敲一遍。如果一个扩展取消了,你会得到 {"cancelled": true},并且没有会话被创建。
clone 不接受参数,并在当前位置复制活动分支。fork 和 clone 都"可能被一个 session_before_fork 扩展事件处理器取消。”
从外面读这棵树
两条命令,而它们之间的区别正是本章的实用部分。
get_entries 返回"按追加顺序排列的所有会话条目(不含会话头)。“因为会话是"一棵只追加的条目树,条目的 id 稳定,所以一个条目 id 可以当作一个耐用的游标”,你可以把最后见到的那个 id 作为 since 传入,从而得到"严格在它之后的条目,即使客户端重启过也一样”。
{"type": "get_entries", "since": "abc123"}
关键点:“与 get_messages 不同,它包含压缩前的历史和被放弃的分支。“如果你正在构建一个会话查看器,而你读的是 get_messages,你读到的就只是活动分支。当你需要一切时,用 get_entries。
响应还带有 leafId——“当前叶子条目的 id(空会话为 null),这样客户端在一个来回之内就能判断活动分支是否移动过。“如果 since 匹配不到任何条目 id,响应就是 success: false。
get_tree 给出的是形状而不是顺序:
{"type": "get_tree"}
每个节点是 {entry, children, label?, labelTimestamp?}。结果是一个数组,“因为导航 API 可能创建出多个根;父链断裂的孤立条目也会作为根出现。”
与分支相关的状态
对扩展作者来说有一个后果。ContextEditEntry 编辑是"与分支相关的:导航到该编辑之前的一个点,会让目标原本的贡献重新显现。”
这是正确的语义,而且值得为它设计。如果你的扩展在一条分支上记录了一次编辑,另一条分支不会看到它——因为从那一条分支的视角看,它从未发生过。extensions.md 把与之对应的状态规则说得明确:“在 session_start 期间从 ctx.sessionManager.getBranch() 重建对分支敏感的状态。不要从每一个文件条目重建它,因为被放弃的分支代表另类的历史。”
标签的去处不一样。一个 label 条目是"一个用户定义的、加在某个条目上的书签/标记”,而 get_tree 按节点报告 label 和 labelTimestamp。把 label 设为 undefined 会清除它。标签是你在自己几天里搭起来的一棵树里找回去的路的方式。
一套决定流程
三个问题,按顺序:你会回到那个备选方案吗,它值得拥有自己的会话列表项吗,还是你只是担心丢掉当前状态?第一个是 /tree,第二个是 /fork,第三个是 /clone。
最常见的错误,是在本该用 /tree 的时候去抓 /fork。一次分叉给你两个会话、两个名字、选择器里的两个条目,以及一份来自被放弃路径的摘要的缺失——因为新会话里没有关于你离开了什么的记录。
这里的一切都是同一个机制在三个尺度上的样子:条目、分支、会话。一条你没有选的分支会改变什么能到达模型,这使它成为一种回答一个你还没有问完的问题的方式。下一章走向另一个方向:如何改变一次仍在进行中的运行。
运行了什么
第 4、5、23、24 章在同一段共享历史上接受测试,好让这几章读起来是一个主题、是一段随时间演变的状态,而不是四个。它是一个持久化会话里的三轮:问题 A 及其回答;问题 B,它发起一次 bash 工具调用然后回答;问题 C 及其回答。examples/harness/history.ts 构建这段历史,每一章都从同一次运行中读出不同的属性。
第 24 章的问题是当历史发生分支时,什么改变了?examples/ch24-branching/ 在进程内把那段历史分支,而 /fork 和 /clone 则在随附的二进制上运行:
- 在一条用户消息上用
/tree会返回它的文本供编辑,并把叶子移到该消息的父条目上;而在一条助手响应上,它在该条目之后以一个空编辑器继续; - 提交这次编辑创建出一个兄弟节点:同一个父条目下的两个消息条目,在一个会话文件里;
- 被放弃的分支没有被发送,也没有消失;
- 在一个由扩展提供摘要的场景下,离开一条分支会写入一个
branch_summary条目,它的fromId是你离开的那片叶子,parentId是你落到的位置,而被放弃的条目仍然在树里。接着,摘要到达了新分支上的模型,而被放弃的消息仍然没有; getTree()显示出两条分支同处在它们共享的父条目之下,而一个用appendLabelChange()设置的标签出现在该节点上,并被设为undefined清除;- 通过 RPC,
get_fork_messages列出了用户提示词,fork启动了一个新的会话文件并返回原始提示词文本供编辑,而新文件的头带上了parentSession,也就是前一个文件:它来自何处的唯一耐久记录; clone把活动分支复制进了一个新的会话文件。