← Pi Agents

分支与分叉

三种回到过去的方式——/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:

  1. 找到共同祖先 — 旧位置与新位置共享的那个最深节点。
  2. 收集条目 — 从旧叶子一路走回那个祖先。
  3. 带着预算准备 — 在 token 预算内包含消息,从最新的开始。
  4. 生成摘要 — 以结构化格式调用 LLM。
  5. 追加条目 — 在导航点保存一个 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 把活动分支复制进了一个新的会话文件。