夜雨聆风学习资料网

ARTICLE · 1376050

会话树导航与分支回溯机制 - Pi 源码分析 12

会话树导航与分支回溯机制 - Pi 源码分析 12

本文是「Pi 源码分析」第 12 篇。在用 Coding Agent 处理复杂工程任务时,对话很少是一条笔直的单行道:你可能想改写三轮前的某句提问重新生成;可能在尝试某种重构方案撞南墙后,想带着踩坑教训退回岔路口换条路走;也可能只是临时插嘴问一个支线问题,问完不想让它留在主线上下文里白白消耗 Token。

在传统线性聊天工具里,你只能在“将就着把脏历史留在上下文里”和“删掉历史消息再也找不回来”之间二选一。Pi Coding Agent 用 /tree(会话树导航) 命令彻底解开了这个死结。本篇我们深入 packages/coding-agent 源码,把以下四个核心问题一次讲透:

  1. 1. /tree 命令的功能到底是什么?
  2. 2. 调用 /tree 之后:会新开一个会话吗?老会话(老分支)是如何处理的?
  3. 3. 它在底层数据结构、上下文投影、分支摘要与终端 UI 上是怎么实现的?
  4. 4. 它有哪些高频实战场景与扩展(Extension)高阶玩法?

一、核心结论先行:直面四个关键问题

在展开几千行源码之前,我们先用一张结论速查表把四个核心问题的答案钉死,建立全局直觉:

核心问题
源码级明确结论
关键源码依据
1. 它的功能是什么?
打开交互式会话树浏览器(TreeSelectorComponent),查看当前会话的全部分支历史,支持跳转到任意历史节点继续对话(原地分叉)、为离开的分支生成摘要并带入新分支、五档过滤与折叠浏览、全文检索、节点打标签(书签)以及一键复制历史消息。
interactive-mode.tsshowTreeSelector()
tree-selector.ts
2a. 调用后会新开一个会话吗?绝对不会!
 磁盘上的 .jsonl 会话文件路径不变、sessionId 不变、SessionManager 实例不变,扩展(Extension)运行时也不会经历 session_shutdown -> session_start 重启。它只是把内存里的当前叶子游标 leafId 移到了你选中的目标位置。(真正新开会话文件的是 /fork 和 /clone。)
agent-session.tsnavigateTree()
 注释:Unlike fork() which creates a new session file, this stays in the same file.
2b. 老会话(老分支)如何处理?原样保留在同一个文件里,自动脱离模型视野,可选摘要桥接:
① 物理上零删改:老分支的所有条目分毫不动地留在原 .jsonl 文件中,随时可以再次通过 /tree 切回去;② 逻辑上自动隔离:发给大模型的上下文只取“从新 leafId 沿 parentId 回溯到根节点”的那条路径,老分支不在路径上,因此消耗 0 Token,也不会干扰模型;③ 经验可跨分支传递:若导航时选择 Summarize,Pi 会提取“老分支叶子回退至最近公共祖先”之间的对话,让 LLM 浓缩成一条 branch_summary 记录挂到新分支起点,把踩坑结论带过去。
session-manager.tsbranch()
 / branchWithSummary() / buildSessionPath()branch-summarization.ts
3. 它一般是怎么实现的?
采用 “只追加树状账本(Append-Only Tree Log) + 可移动叶子游标(leafId) + 路径反向投影(Path Projection)” 架构:每条记录携带 id 与 parentId 构成有向树;分叉只是改写 leafId 指针;选中“用户消息”时回退到其父节点并将文本塞回输入框供改写,选中“助手消息”时直接停在该节点后续写。
session-manager.ts
agent-session.ts
4. 它的使用场景有哪些?
① 改写某轮提问重新生成;② 方案 A/B 试错与踩坑摘要迁移;③ 临时问支线问题后无痕切回主线;④ 模型跑偏或工具报错刷屏后一键止损回退;⑤ 给关键节点打 Label 书签;⑥ 搜索并复制早期对话片段;⑦ 扩展编程化自动导航与状态回溯。
详见本文第六章

Warning

初学者最容易踩的认知误区:/tree 管“记忆”,不管“硬盘代码”!/tree 切换的仅仅是 Pi 与大模型的对话上下文历史,它不会自动回滚工作区里的源代码文件。如果模型在老分支里调用 edit、write 或 bash 修改了 src/login.ts,当你用 /tree 切回三轮之前时,src/login.ts 依然保持修改后的状态。如果你希望代码也跟着时光倒流,需要手动执行 git checkout / git restore,或者挂载类似官方示例 git-checkpoint.ts 的扩展(后文第六章会给出完整实现)。


二、核心心智模型:追加式树状账本 + 可移动叶子游标

要真正看懂为什么 /tree 既不用新建会话文件、又不用删改历史就能实现“平行宇宙切换”,我们需要先看清 Pi 会话存储的底层模型。

1. 为什么传统线性数组搞不定会话回溯?

大多数简单的 Agent 框架把对话历史存成一个扁平数组 messages: Message[]。假设你让 Agent 给 login.ts 添加 JWT 校验,经历了以下 6 条记录:

  1. 1. E1 (user):“给 login.ts 加 JWT 校验”
  2. 2. E2 (assistant):“好的,目前有两种主流方案:方案一用 jsonwebtoken,方案二用 jose……”
  3. 3. E3 (user):“用方案一 jsonwebtoken”
  4. 4. E4 (assistant + toolCall):调用 edit 修改了 3 个文件
  5. 5. E5 (user):“跑一下单元测试”
  6. 6. E6 (assistant + toolResult):测试报错,因为项目运行在 Cloudflare Workers 边缘环境,不支持 Node 原生 crypto 模块。

此时你意识到方案一走不通,想回到 E2 之后改用方案二。在线性数组模型下,你只有两条烂路可选:

  • • 硬着头皮往下聊:“算了,改用方案二 jose 吧”。结果 E3..E6 里好几万 Token 的报错堆栈和废弃代码依然躺在数组里,每轮请求都要重新发给大模型计费,还极易误导模型写出混杂两套库的代码;
  • • 截断数组(messages.splice(2)):把 E3..E6 彻底删掉。上下文是干净了,但如果 10 分钟后你发现方案二也有坑、想回头看一眼 E6 当时的具体报错信息,数据已经灰飞烟灭了。

2. Pi 的解法:像 Git 一样用 parentId 指针种树

Pi 在会话版本 v2(当前为 CURRENT_SESSION_VERSION = 3)中彻底抛弃了“文件行号顺序 = 对话顺序”的线性假设,改用类似 Git Commit 图谱的设计:

Git 核心概念
Pi SessionManager 对应机制
作用说明
Commit 对象
SessionEntry
(JSONL 文件中的一行)
不可变的历史事件记录(只追加,永不原地修改或删除)
Commit Hash
entry.id
(8 位十六进制短 ID)
由 generateId() 截取 UUID 前 8 位并做碰撞校验生成
Parent Hash
entry.parentId
(string | null)
指向父条目的 id;若为 null 则表示树的根节点(Root)
HEAD
 游标
SessionManager.leafId
(string | null)
指向当前所在分支末端条目的内存指针
git checkout <old>
 后再提交
调用 /tree 移动 leafId 后再发消息
新消息的 parentId 指向旧节点,自然长出第 2 个子分支

与 Git 的一点细微区别:Git 有具名分支(如 main、feat-jwt),而 Pi 的会话树没有分支名——树上的每一个节点都可以直接作为下一次对话的分叉起点,树中每一条从根延伸出去的末端路径都是一个天然分支。

3. 核心数据结构逐字段拆解

打开 packages/coding-agent/src/core/session-manager.ts,所有会话记录(除文件第 1 行的元数据头 SessionHeader 外)都继承自 SessionEntryBase:

// packages/coding-agent/src/core/session-manager.tsexport interface SessionEntryBase {    type: string;    id: string;              // 当前条目唯一短 ID,例如 "a1b2c3d4"    parentId: string | null; // 父条目 ID;首条记录(或重置到根后)为 null    timestamp: string;       // ISO 8601 时间戳,用于给同一父节点下的多个子分支按时间排序}

围绕 /tree 导航,有三个专门设计的条目与节点类型至关重要:

  1. 1. BranchSummaryEntry(分支摘要条目):当你在 /tree 切换分支并选择“生成摘要”时写入账本的桥接节点:
    export interface BranchSummaryEntry<T = unknown> extends SessionEntryBase {    type: "branch_summary";    fromId: string;     // 记录这份摘要是从哪个旧叶子节点(oldLeafId)提炼过来的(若从空根来则为 "root")    summary: string;    // LLM 生成的结构化分支探索摘要(含文件操作列表)    details?: T;        // 默认存放 { readFiles: string[], modifiedFiles: string[] },供后续跨分支累积追踪文件    usage?: Usage;      // 生成本次分支摘要消耗的 Token 与费用,计入会话总账单    fromHook?: boolean; // true 表示由扩展(session_before_tree)生成,false/undefined 表示由 Pi 内置算法生成}

    注意 parentId 与 fromId 的分工:parentId 指向新分支的起点(即你要跳过去的那个分叉点),决定它在树里的位置;fromId 指向刚刚离开的老分支末端,记录摘要的血缘来源。

  2. 2. LabelEntry(书签标签条目):当你在 /tree 中按 Shift+L 给某个节点打标签时,因为 .jsonl 文件是严格只追加的,Pi 不会去改写目标节点那一行,而是追加一条 LabelEntry:
    export interface LabelEntry extends SessionEntryBase {    type: "label";    targetId: string;          // 被打标签的目标条目 ID    label: string | undefined; // 标签文本;传 undefined 或空串表示清除该节点的标签}

    SessionManager 在内存中维护 labelsById: Map<string, string>,加载文件或调用 getTree() 时会自动把最新标签解析并挂载到目标节点上。

  3. 3. SessionTreeNode(内存会话树节点):sessionManager.getTree() 将扁平条目组装成树后返回给 UI 渲染的结构:
    export interface SessionTreeNode {    entry: SessionEntry;         // 原始账本条目    children: SessionTreeNode[]; // 子节点列表(按 timestamp 从旧到新排序)    label?: string;              // 解析后的当前有效书签名称    labelTimestamp?: string;     // 最近一次修改该书签的时间戳}

4. 游标推进、原地分叉与路径投影源码实现

在 SessionManager 内部,平时正常聊天、执行 /tree 分叉、以及构造 LLM 请求上下文,本质上都围绕 this.leafId 这一个指针运转:

  • • 日常聊天追加(自动顺延游标):每次调用 appendMessage()、appendCompaction() 等写入方法时,新条目的 parentId 一律设为当前的 this.leafId,写入成功后立刻通过 _appendEntry() 把 this.leafId 更新为新条目的 id:
    // packages/coding-agent/src/core/session-manager.tsprivate _appendEntry(entry: SessionEntry): void {    const previousLeafId = this.leafId;    this.fileEntries.push(entry);    this.byId.set(entry.id, entry);    this.leafId = entry.id; // 游标自动前移到最新写入的条目    try {        this._persist(entry); // 追加一行 JSON 到当前 .jsonl 文件末尾    } catch (error) {        // 若磁盘写入失败,严格回滚内存数组、索引和 leafId,防止后续条目指向未落盘的幽灵父节点        this.fileEntries.pop();        this.byId.delete(entry.id);        this.leafId = previousLeafId;        throw error;    }}
  • • /tree 导航切换分支(只拨动游标,不删改旧数据):SessionManager 提供了三个极其轻量的分支方法:
    1. 1. branch(branchFromId: string):校验 ID 存在后,仅仅执行一行 this.leafId = branchFromId!此时甚至不需要写磁盘——等用户发出下一条消息时,新消息的 parentId 就会自动指向 branchFromId,新分支自然落盘。
    2. 2. resetLeaf():执行 this.leafId = null。用于用户选中会话的第 1 条根消息重新编辑的场景,下一条发出的消息 parentId 为 null,成为树里的第 2 个根节点。
    3. 3. branchWithSummary(branchFromId, summary, ...):先把 this.leafId 拨到 branchFromId,紧接着调用 _appendEntry 写入一条 parentId = branchFromId、fromId = 旧 leafId 的 BranchSummaryEntry,于是 this.leafId 停在这条新摘要上。
  • • 构造模型上下文(只认 leafId -> root 唯一路径):每次发请求给大模型前,buildSessionProjection() 调用 buildSessionPath(),从当前 leafId 出发,顺着 parentId 一路往上摸到根节点,最后 reverse() 翻转成时间正序:
    // packages/coding-agent/src/core/session-manager.tsfunction buildSessionPath(    entries: SessionEntry[],    leafId?: string | null,    byId?: Map<string, SessionEntry>,): SessionEntry[] {    const index = buildEntryIndex(entries, byId);    if (leafId === null) {        return []; // 游标重置到根之前时,上下文为空数组    }    let leaf = leafId ? index.get(leafId) : undefined;    leaf ??= entries[entries.length - 1];    if (!leaf) return [];    const path: SessionEntry[] = [];    let current: SessionEntry | undefined = leaf;    while (current) {        path.push(current);        current = current.parentId ? index.get(current.parentId) : undefined;    }    path.reverse();    return path;}

    这段不到 20 行的代码解释了 “老会话(老分支)是如何处理的”:老分支虽然物理上躺在 entries 数组和 .jsonl 文件里,但从新的 leafId 沿着 parentId 往回走根本不会路过它们!因此在 buildSessionPath() 眼里,旁支就像从未发生过一样,既不占用半个 Token,也无需任何删除操作。

Note

细节追问:如果执行无摘要 /tree 仅仅改了内存里的 leafId,还没发新消息就关掉终端,下次 pi -c 恢复会话时游标在哪?查看 SessionManager._buildIndex()(第 1109~1112 行)可以看到,重新加载 .jsonl 文件时,Pi 会按文件行序遍历并将 this.leafId 设为文件最后一行条目的 id。也就是说:如果你用 /tree 选了 No summary 跳到旧节点,但一句话没说就直接退出进程,由于磁盘没有新条目写入,下次重启恢复时会回到文件末尾的旧叶子;一旦你在新位置发了消息、打了标签或生成了 branch_summary,新条目被追加到文件末尾,下次重启就会精准停留在你的新分支上。

5. 端到端账本演变实例推演

回到前文给 login.ts 加 JWT 的例子。假设初始会话文件 2026-11-05_xxx.jsonl 里已经有 E1..E6 共 6 条对话记录,此时 leafId = "E6"。

现在你敲下 /tree,在树视图中选中 E3(user: "用方案一 jsonwebtoken"),并在弹窗中选择 Summarize(生成分支摘要):

  1. 1. 回退游标与回填提问:因为 E3 是一条用户消息,Pi 明白你想“撤回并改写这句话”,于是将目标挂载点定为 E3 的父节点 E2,同时把 "用方案一 jsonwebtoken" 填回底部输入框。
  2. 2. 追加分支摘要 E7:Pi 收集从老叶子 E6 回退到公共祖先 E2 之间的 E3..E6,调用大模型生成浓缩摘要,往同一个 .jsonl 文件末尾追加第 7 条记录 E7(type: "branch_summary", parentId: "E2", fromId: "E6"),此时 leafId 变为 "E7"。
  3. 3. 改写重发产生新分支 E8 -> E9:你在输入框里把文字改成 "改用方案二 jose 库,注意兼容边缘运行时" 并回车。Pi 追加 E8(parentId: "E7"),模型读取到 E7 里的踩坑摘要后顺利改完代码并通过测试,追加 E9(parentId: "E8"),最终 leafId = "E9"。

此时打开磁盘上的 .jsonl 文件,你会看到文件末尾只是平平无奇地多了 3 行(E1..E6 原封未动):

{"type":"branch_summary","id":"E7","parentId":"E2","timestamp":"...","fromId":"E6","summary":"The user explored a different conversation branch before returning here.\nSummary of that exploration:\n\n## Goal\nImplement JWT auth in login.ts using jsonwebtoken...\n\n<modified-files>\nsrc/login.ts\n</modified-files>"}{"type":"message","id":"E8","parentId":"E7","timestamp":"...","message":{"role":"user","content":"改用方案二 jose 库,注意兼容边缘运行时"}}{"type":"message","id":"E9","parentId":"E8","timestamp":"...","message":{"role":"assistant","content":[{"type":"text","text":"已完成 jose 迁移并通过全部边缘运行时测试。"}]}}

当下一轮发请求给大模型时,buildSessionPath("E9") 沿着 E9 -> E8 -> E7 -> E2 -> E1 回溯并反转,再经 convertToLlm() 将 E7 包装成一条带 <branch_summary> 标签的标准 user 消息。模型看到的完整历史是干净利落的 [E1, E2, E7(方案一踩坑摘要), E8, E9]——既甩掉了 E3..E6 的冗余报错文本,又完美继承了方案一为什么失败的宝贵记忆。

下图完整展示了这次 /tree 导航前后,物理 JSONL 树状账本的分叉结构与模型活跃上下文投影之间的映射关系:

/tree 原地分叉前后会话树结构与活跃上下文路径投影对比图

三、辨析:/tree 与 /fork、/clone 有什么本质区别?

初学者在看 Pi 的斜杠命令列表时,最容易混淆 /tree、/fork 和 /clone。这三者都跟“分支”有关,但结合 agent-session.ts 与 agent-session-runtime.ts 的源码来看,它们的职责边界泾渭分明:

对比维度
/tree
(会话树原地导航)
/fork
(从历史提问分叉新会话)
/clone
(克隆当前状态到新会话)
底层入口方法AgentSession.navigateTree(targetId)AgentSessionRuntime.fork(entryId, { position: "before" })AgentSessionRuntime.fork(leafId, { position: "at" })
是否新建 .jsonl 文件?否
(始终留在当前 .jsonl 文件内)
是
(调用 createBranchedSession() 生成全新 UUID .jsonl 文件)
是
(调用 createBranchedSession() 生成全新 UUID .jsonl 文件)
新文件 Header 血缘
无新文件(原 Header 不变)
新 Header 记录 parentSession: "<原文件路径>"
新 Header 记录 parentSession: "<原文件路径>"
可选节点范围
树上任意节点(user、assistant、toolResult、compaction 等)
仅限**用户消息(user)**列表
无需选择,固定为当前叶子(leafId)
老分支与旁支去向
全部分支保留在同一棵树里,随时可互相横跳
新文件只提取从根到分叉点的一条线性主干,剔除其余旁支;老文件留在磁盘不动(需通过 /resume 找回)
新文件只提取从根到当前叶子的线性路径(含当前叶子),老文件留在磁盘不动
离开分支摘要(Summarize)支持
(内置可选生成 BranchSummaryEntry)
不支持(直接截断提取分叉点之前的历史)
不支持(完整拷贝当前活跃分支)
扩展(Extension)生命周期不重启扩展
,仅触发 session_before_tree 与 session_tree 事件
彻底销毁并重建运行时
:依次触发 session_before_fork -> session_shutdown -> session_start(reason: "fork")
与 /fork 相同,触发完整运行时销毁与重建
输入框(Editor)行为
选 user 节点时回填其文本;选其它节点保持为空
将选中的 user 消息文本回填到输入框
清空输入框
最佳选型时机
同一个任务内的方案试错、改词重试、临时支线提问(希望相关探索留在同一个会话里随时对照)
想从半小时前的某个节点彻底劈开一个独立的新功能任务,甚至准备在两个终端窗口同时并行推进
当前上下文正好调教到最佳状态,想复制一份独立副本去做破坏性实验,确保原会话绝对干净

源码彩蛋:为什么 createBranchedSession() 抽离新文件时要专门做“标签重链(Label Re-chaining)”?在 session-manager.ts 第 1650~1679 行有一个非常精妙的细节:因为 LabelEntry 本身也是树上的一个节点(拥有 id 和 parentId),它后面追加的对话消息会把这条 LabelEntry 当作自己的 parentId。当 /fork 或 /clone 抽离线性路径并清理旧 LabelEntry 重新在文件末尾统一生成标签时,如果直接删掉中间的 LabelEntry,后面的消息就会变成找不到爸爸的“孤儿节点”,甚至可能让 CompactionEntry.firstKeptEntryId 指向一个被删掉的 LabelEntry!因此 createBranchedSession() 专门维护了 replacementByLabelId 映射表,把被摘除标签的父子链条与压缩书签严丝合缝地重新焊接起来。而在 /tree 中,因为从未删除任何节点,天然不存在断链问题。


四、源码级执行链路拆解:从敲下 /tree 到新分支就绪

清楚了底层账本结构后,我们顺着真实调用栈,一步步拆解当你触发 /tree 并按回车跳转到某个节点时,Pi 内部究竟执行了哪些操作。

1. 四大触发入口

在交互模式(InteractiveMode)与扩展体系中,共有四条路径可以唤起树导航:

  1. 1. 斜杠命令 /tree:在输入框输入 /tree 回车,命中 interactive-mode.ts 第 3366 行 if (text === "/tree") { this.showTreeSelector(); };
  2. 2. 空输入框双击 Esc(最顺手的快捷方式):当底部输入框为空且当前没有流式输出或正在运行的 bash 命令时,500ms 内连按两次 Esc,Pi 会读取 settings.json 中的 doubleEscapeAction 配置(默认值为 "tree",也可改为 "fork" 或 "none"),直接调用 this.showTreeSelector();
  3. 3. 自定义全局快捷键 app.session.tree:默认未绑定按键,用户可在 keybindings.json 中配置(如 "app.session.tree": ["ctrl+shift+t"]),触发编辑器动作回调打开树选择器;
  4. 4. 扩展 API 编程化调用 ctx.navigateTree(targetId, options):在自定义斜杠命令(ExtensionCommandContext)中无需弹出 UI,直接由代码驱动跳转到任意节点(注意 RPC 模式目前仅暴露只读的 get_tree 查询接口,尚未提供直接的 navigate_tree RPC 命令,但可通过扩展命令触发)。

2. 阶段一:UI 确认弹窗与流式并发守卫(showTreeSelector)

打开 interactive-mode.ts 第 5693~5840 行的 showTreeSelector(),当用户在 TreeSelectorComponent 中选中一个目标条目 entryId 按下回车时,Pi 并不会莽撞地立刻改指针,而是做了三层严谨的交互与并发处理:

  1. 1. 原地点击幂等短路:如果 entryId === this.sessionManager.getLeafId()(选中的就是当前所在的叶子节点),直接关闭选择器并提示 "Already at this point",什么也不做。
  2. 2. 三级摘要意愿询问(支持按 Esc 逐级回退):只要用户在 settings.json 中没有开启 branchSummary.skipPrompt: true(默认 false),界面就会弹出选择菜单:
    • • "No summary"(直接切过去,不要摘要)
    • • "Summarize"(使用内置默认模板生成分支摘要)
    • • "Summarize with custom prompt"(接着弹出多行编辑器,让你输入自定义摘要侧重点 customInstructions)人性化回退细节:如果你在二级菜单按 Esc 取消,它不会直接把你踢回主聊天界面,而是调用 this.showTreeSelector(entryId) 重新打开树选择器,且光标依然停在你刚才选中的那个节点上!如果在三级自定义指令框按 Esc,则会退回二级摘要菜单。
  3. 3. 延迟中断流式输出与互斥锁校验:注意源码第 5754~5765 行的时序设计——打开 /tree 浏览树本身不会打断后台正在流式回复的模型;只有当用户真正选好目标并确认摘要选项、决心要跳转的那一刻,如果 this.session.isStreaming 仍为真,Pi 才会先把排队的 steering/follow-up 消息退回输入框,再调用 await this.session.abort() 停掉当前生成。随后再次检查 this.session.isCompacting(涵盖自动压缩、手动压缩与另一个正在进行的分支摘要),防止两个摘要任务并发改写同一份会话账本。

3. 阶段二:最近公共祖先(LCA)定位与离开分支收集

进入核心编排方法 AgentSession.navigateTree()(第 4093~4290 行)后,第一步是调用 collectEntriesForBranchSummary(this.sessionManager, oldLeafId, targetId) 算出 “这次跳转究竟放弃了哪一段历史”。

很多初学者会问:“为什么不把 oldLeafId 整条分支从头到尾全拿来做摘要?”答案很简单:假设主干已经聊了 50 轮(E1..E50),你在 E50 分叉出去聊了 3 轮支线(E51..E53),现在想跳回主干上的另一条分支 E50 -> E60。E1..E50 本来就已经在目标节点 E60 的祖先路径上了!如果把 E1..E50 也塞进分支摘要,不仅白花冤枉钱,还会造成严重的上下文重复。

因此,collectEntriesForBranchSummary() 采用经典的树最近公共祖先(Lowest Common Ancestor, LCA)算法:

// packages/coding-agent/src/core/compaction/branch-summarization.tsexport function collectEntriesForBranchSummary(    session: ReadonlySessionManager,    oldLeafId: string | null,    targetId: string,): CollectEntriesResult {    if (!oldLeafId) {        return { entries: [], commonAncestorId: null };    }    // 1. 获取老分支完整路径集合(root -> oldLeaf)与目标分支路径数组(root -> target)    const oldPath = new Set(session.getBranch(oldLeafId).map((e) => e.id));    const targetPath = session.getBranch(targetId);    // 2. targetPath 按从根到叶排列,因此从后往前倒序找第一个出现在 oldPath 中的节点,即为最深公共祖先!    let commonAncestorId: string | null = null;    for (let i = targetPath.length - 1; i >= 0; i--) {        if (oldPath.has(targetPath[i].id)) {            commonAncestorId = targetPath[i].id;            break;        }    }    // 3. 从 oldLeafId 顺着 parentId 往回收集,一旦撞上 commonAncestorId 立即停手    const entries: SessionEntry[] = [];    let current: string | null = oldLeafId;    while (current && current !== commonAncestorId) {        const entry = session.getEntry(current);        if (!entry) break;        entries.push(entry);        current = entry.parentId;    }    // 4. 翻转为时间正序返回    entries.reverse();    return { entries, commonAncestorId };}

这里还有一个与第 11 篇上下文压缩呼应的关键细节:收集过程绝不在 CompactionEntry 处停下。如果被放弃的老分支中间曾经发生过一次上下文压缩,那条 CompactionEntry 本身也会被收集进来,并在后续 getMessageFromEntry() 中被转换成摘要消息参与提炼,确保老分支更早之前的记忆也不会断档。

4. 阶段三:前置钩子拦截与 generateBranchSummary() 分支摘要生成

拿到 entriesToSummarize 后,navigateTree() 会先构造 TreePreparation 对象并发射 session_before_tree 扩展事件(允许插件返回 { cancel: true } 取消跳转,或直接提供自定义的 summary 跳过默认 LLM 调用)。

如果用户要求生成摘要且扩展没有接管,Pi 就会绑定 AbortController(此时在 TUI 按 Esc 会触发 session.abortBranchSummary() 随时中断请求,并退回树选择器),随后调用 generateBranchSummary():

  1. 1. 按 Token 预算从新到旧倒序选取(prepareBranchEntries):分支可能很长,甚至超过当前模型的上下文窗口。Pi 计算出安全预算 tokenBudget = contextWindow - reserveTokens(branchSummary.reserveTokens 默认预留 16,384 Tokens),然后从 entries 的最后一条(最新)往第一条(最旧)倒着遍历塞入待摘要列表,一旦超出预算就停止。
    • • 跳过 toolResult 正文:代码第 167 行明确跳过 role === "toolResult" 的条目(因为助手消息里的 toolCall 参数及后续回复已足以概括动作,省去海量原始文件输出);
    • • 遵守 context_edit 裁剪:若老分支里有插件注入的 context_edit,摘要收集同样会尊重最新编辑(隐藏或替换内容);
    • • 无视预算全量提取累积文件足迹:即使某条更早的记录因超出 Token 预算没能进入文本摘要,第一遍全量扫描依然会把所有内置 branch_summary.details 以及工具调用里的 read / write / edit 文件路径全部收集到 fileOps 集合中!
  2. 2. 防续写文本序列化 + 专用结构化 Prompt:与第 11 篇讲过的上下文压缩如出一辙,Pi 绝不把分支历史直接当作多轮 messages 发给模型(否则模型会误以为自己还在那个分支里,接着往下写代码甚至调工具!),而是调用 serializeConversation(convertToLlm(messages)) 将其拍平为 <conversation>...</conversation> 纯文本剧本,再拼上 BRANCH_SUMMARY_PROMPT 要求模型严格输出 ## Goal、## Constraints & Preferences、## Progress (Done / In Progress / Blocked)、## Key Decisions、## Next Steps 五大板块。
  3. 3. 防工具调用校验与前缀/后缀拼装:通过 completeSummarization() 发起请求(自动复用 settings.retry 重试瞬时网络错误)。拿到结果后,若发现模型居然试图调用工具(block.type === "toolCall"),直接判定摘要失败报错。校验通过后,在头部加上引导语 "The user explored a different conversation branch before returning here.\nSummary of that exploration:\n\n",在尾部附上确定性的 <read-files> 和 <modified-files> 清单。

5. 阶段四:目标节点角色分流——为什么选 User 消息与选 Assistant 消息行为截然不同?

这是 navigateTree()(agent-session.ts 第 4218~4259 行)最体现产品打磨功力的地方。我们直接看源码:

// packages/coding-agent/src/core/agent-session.tslet newLeafId: string | null;let editorText: string | undefined;if (targetEntry.type === "message" && targetEntry.message.role === "user") {    // 情况 A:选中用户消息 -> 游标退到它的父节点(若是首条根消息则为 null),原提问文本提取到输入框!    newLeafId = targetEntry.parentId;    editorText = contentText(targetEntry.message.content, "");} else if (targetEntry.type === "custom_message") {    // 情况 B:选中扩展注入的 custom_message -> 同样退到父节点并提取文本到输入框    newLeafId = targetEntry.parentId;    editorText = contentText(targetEntry.content, "");} else {    // 情况 C:选中助手消息、toolResult、compaction、branch_summary 等 -> 游标直接停在该节点上,输入框留空!    newLeafId = targetId;}

为什么要做这个区分?设身处地想一下你在树里选中不同节点时的真实意图:

  • • 当你选中一条 user 消息(比如第 3 轮你问的“用方案一实现”)时:你绝不是想在“用方案一实现”这句话后面再追问一句(那样模型还没回答方案一呢,连贯性就乱了),你的真实意图是 “我想撤回第 3 轮这句话,重新改写一下再发出去”!所以 Pi 把 newLeafId 设成 targetEntry.parentId(即第 2 轮助手回复 E2),同时把第 3 轮的原话塞回你的输入框,等你改完按回车,新消息就挂在 E2 下面成为原第 3 轮的兄弟分支。
    • • 特殊边界(多根树):如果你选中的是整个会话的第 1 条用户消息(parentId === null),那么 newLeafId 就会变成 null!若没选摘要,Pi 调用 sessionManager.resetLeaf() 把会话清空回初始态,等你改完第一句话发出去,这个 .jsonl 文件里就会诞生第 2 棵独立的根树(Multiple Roots);若选了摘要,branchWithSummary(null, ...) 会创建一条 parentId: null 的根级 BranchSummaryEntry,你的新提问挂在这条根摘要下面。
  • • 当你选中一条 assistant 消息(比如第 2 轮助手给出的方案对比)或 toolResult 时:说明你认可截至这一步为止的全部对话和回答,你想 “紧接着模型这句话往后聊”。所以 newLeafId 直接等于 targetId,输入框保持为空等你输入下一句新指令。

紧接着,源码第 4238~4259 行完成游标切换与摘要挂载:

  • • 有摘要时:调用 this.sessionManager.branchWithSummary(newLeafId, summaryText, ...)。注意注释里的强调:摘要节点是挂载在目标位置 newLeafId 下面的,而不是挂在被抛弃的老分支末尾! 只有挂在 newLeafId 下面,它才能成为新分支的垫脚石,被后续新消息继承到上下文中。
  • • 无摘要时:若 newLeafId === null 调 resetLeaf(),否则调 branch(newLeafId)。

6. 阶段五:刷新上下文投影、恢复分支专属工具集与 UI 重绘

游标拨过去之后,内存里的运行时状态还停留在老分支,因此 navigateTree() 最后收尾做了三件关键同步:

  1. 1. this._refreshFinalizedContext():重新调用 sessionManager.buildSessionProjection(),把新分支路径投影出来的 AgentMessage[] 赋值给 this.agent.state.messages,彻底换掉 Agent 脑子里的对话记忆。
  2. 2. this._restoreToolsFromTranscript():这一步极易被忽略但非常关键!在 Pi 中,不同分支可能通过 tool_search 或扩展动态激活/关闭了不同的工具(记录在分支上的增量 SystemMessage.toolsAdded / toolsRemoved 中)。跳到另一个分支后,_restoreToolsFromTranscript() 会重新扫描新分支从根到叶的所有 SystemMessage,把当前激活的工具集(Active Tools)精准还原成目标分支当时的样子!

    顺带一提模型选择(Model Selection):如果你在老分支切换过模型(写入了 model_change 条目),跳回没有该条目的新分支时,Pi 并不会强行把你手头正在用的物理模型切回去;但如果你当前选了虚拟路由模型(Virtual Model),下次发消息前 _recordSelection() 会自动检查当前分支记录的模型是否一致,不一致时自动在新分支补记一条 model_change,保证后续 /resume 恢复时模型状态不丢。

  3. 3. 触发 session_tree 事件并重绘 TUI:发出后置事件通知所有扩展同步状态,返回 { editorText, cancelled: false, summaryEntry }。外层 InteractiveMode 收到后,执行 this.chatContainer.clear() 清屏,调用 this.renderInitialMessages() 把新分支的历史重新渲染到终端上,并将 editorText 填入底部编辑器(仅在编辑器当前为空时写入,避免覆盖用户草稿)。

下图完整串联了上述三个模块在三大阶段的端到端时序交互:

/tree 命令导航与分支摘要生成端到端时序图

五、终端交互层揭秘:TreeSelectorComponent 是如何把复杂会话树画出来的?

如果每次对话包含几十次工具调用、好几处分叉,直接把原始多叉树按标准缩进画在宽度有限的终端里,不出 5 层就会全部挤到屏幕最右边折行乱码。packages/coding-agent/src/modes/interactive/components/tree-selector.ts(共 1,439 行)用了一套非常精巧的排版算法解决终端画树难题。

1. 活跃分支置顶与“防右移爆炸”缩进规则(flattenTree)

在 TreeList.flattenTree()(第 203~331 行)中,组件并没有用递归(防止超长会话几千轮对话导致调用栈溢出 Maximum call stack size exceeded),而是手写显式栈做了两遍迭代遍历:

  1. 1. 后序标记活跃分支优先排在最上方:先用一遍逆后序遍历算出 containsActive: Map<SessionTreeNode, boolean>,标记哪些子树里包含当前的 currentLeafId。在展开任意父节点的子节点列表时,包含当前活跃叶子的那个子分支永远排在第 1 位,其余历史旁支按时间戳紧随其后;同时,从根到当前叶子的整条活跃路径上的所有节点都会标上一颗醒目的高亮圆点 • ,让你一眼看清自己当前身处哪条支流。
  2. 2. “单脉相承不缩进,一树多花才缩进”:普通文件树每深一层就缩进一次;但对话树里 95% 的节点都是 user -> assistant -> toolResult -> assistant 这样一对一的单链条。因此 TreeList 定下了三条黄金缩进铁律(每级缩进占 3 个字符宽):
    • • 在 indent === 0(主干)时:只要父节点只有 1 个孩子,孩子永远保持 indent = 0 贴左对齐!只有当某个节点分叉出 2 个及以上孩子(multipleChildren === true)时,子分支才变为 indent = 1,并画出 ├─  或 └─  分叉连接符;
    • • 在分叉后的第一代(justBranched && indent > 0):为了让这根新分支下的后续单链对话在视觉上归属于该分支,下一代再缩进 1 格形成子树视觉块;
    • • 在 indent >= 2 之后:单子链条一律保持水平对齐不增加缩进,只有再次遇到真分叉时才 +1!
  3. 3. 固定左侧游标栏的横向智能视口(renderHorizontalViewport):即便极其罕见地连续分叉了十几次导致缩进过深,renderHorizontalViewport() 也会把最左侧 2 列选中游标(› )死死钉住,当检测到当前选中行的文字起点快要贴近屏幕右边缘时,自动将树体内容向左平滑横移(Horizontal Panning),保证你在窄终端或手机 SSH 屏幕上依然能读全消息内容。

2. 五档过滤模式与可见树连接符动态重算

一段真实的编程会话里掺杂着大量账本元数据(model_change、label、context_edit)以及工具执行结果(toolResult)。TreeSelectorComponent 内置了 5 种过滤视图(可通过 settings.json 的 treeFilterMode 设置默认初始视图):

过滤模式(FilterMode)
切换快捷键
显示/隐藏规则
典型用途
default
(默认)
Ctrl+D
隐藏 label、context_edit、custom、model_change、thinking_level_change、session_info 等纯元数据,以及没有文本且未报错的纯工具调用 assistant 中间帧;显示用户提问、助手文本回复、工具结果、压缩与分支摘要
日常全景浏览对话脉络与工具动作
no-toolsCtrl+T
在 default 基础上进一步隐藏所有 toolResult 节点
屏蔽几十条 read/grep 刷屏,只看人机对话
user-onlyCtrl+U只显示用户发送的 user 消息
快速定位历史某轮提问,回车一键撤回重编
labeled-onlyCtrl+L只显示打过 label 标签的书签节点
在几百轮超长会话中秒级跳回里程碑检查点
allCtrl+A
除内部计费条目 usage 外显示全部原始账本节点
调试扩展 custom 状态、查看模型/思考等级切换记录

细节亮点(recalculateVisualStructure):当你按 Ctrl+U 切到“只看用户消息”时,原本中间隔着好几条 assistant 和 toolResult 的两条用户消息变成了直接父子关系。如果继续沿用原始树的缩进和 ├─ 竖线就会错位断裂。因此每次切换过滤模式、折叠分支或输入搜索词后,applyFilter() 都会在可见节点子集上重新构建虚拟父子映射(visibleParentMap),动态重算所有缩进与连接线!

3. 树选择器高频操作速查

除了上下键移动光标和 Enter 确认跳转,TreeSelectorComponent 还藏着几个极其实用的生产力动作:

  • • 直接打字实时全文搜索:无需按 / 聚焦搜索框,打开 /tree 后直接敲键盘字母(支持空格分词多关键词匹配),列表会实时过滤出包含关键词的节点;按 Esc 先清空搜索词,再按一次 Esc 才关闭树窗口;
  • • 分段折叠与快速跳跃(Ctrl+Left / Ctrl+Right 或 Alt+Left / Alt+Right):遇到带 ⊟ 标记的分叉节点,按 Ctrl+Left 可一键把整个子分支折叠成 ⊞;若当前节点不可折叠,则会直接把光标跳到当前分支段的起点或终点;
  • • 原地打书签标签(Shift+L)与切换标签时间(Shift+T):选中任意节点按 Shift+L 即可输入标签名(如 working-auth),它会在左侧显示醒目的黄色 [working-auth] 标记并持久化写入 .jsonl;
  • • 无损复制节点全文(Ctrl+X):想把半小时前模型写的一段正则或某次 bash 命令拷出来,无需跳转分支,光标移上去按 Ctrl+X 即可将完整文本写入系统剪贴板。

六、/tree 的七大实战使用场景与扩展编程范式

理解了 /tree 的实现机制后,你会发现它绝不仅仅是一个“后悔药”按钮,而是管理大模型上下文信噪比的瑞士军刀。以下是七个最典型的工程使用场景:

场景 1:改写历史 Prompt 重试(精准消除歧义)

当你发出一句需求描述,看到模型开始往错误的方向理解(例如你想要后端分页,模型却开始写前端虚拟列表)时:

  1. 1. 按 Esc 停掉当前生成,再双击 Esc 打开 /tree;
  2. 2. 光标默认就在底部附近,选中你刚才发出的那条 user 消息回车,选 No summary;
  3. 3. 原提问已经自动回到输入框,补上一句“注意:只修改后端 API 分页参数,不动前端组件”重新发送。刚才那半截走偏的生成被彻底甩在旁支,主线上下文干干净净。

场景 2:方案 A / 方案 B 架构试错与踩坑经验迁移

面对复杂重构拿不准该用哪套技术方案时:

  1. 1. 在方案讨论节点先按 Shift+L 打个标签 arch-fork;
  2. 2. 先让模型大胆尝试激进的“方案 A”。如果折腾了 10 轮发现某个底层库存在死穴,打开 /tree 按 Ctrl+L 找到 arch-fork 节点回车;
  3. 3. 选择 Summarize(或 Summarize with custom prompt 输入“重点总结方案 A 遇到的兼容性死穴”)。
  4. 4. 切回分叉点后,模型手里拿着一份几百字的“方案 A 尸检报告”去写“方案 B”,既省下了 10 轮试错的几万 Token,又绝不会重蹈方案 A 的覆辙。

场景 3:“无痕支线提问”——保持主线上下文零污染

这是重度用户最喜欢的高阶技巧。假设你正在让 Pi 重构核心支付模块,上下文已经高度聚焦;这时你突然忘了某个 TypeScript 泛型体操语法,或者想让它帮忙写一条一次性的数据迁移 SQL:

  1. 1. 直接在当前对话里问这个无关问题,等拿到答案后(甚至可以让它连调几次 bash 查清环境问题);
  2. 2. 双击 Esc 打开 /tree,选中你问这个支线问题之前的最后一条主线 assistant 回复,选择 No summary;
  3. 3. 主线瞬间恢复原状!刚才那几轮支线问答消耗的所有 Token 全部从后续请求账单中清零,但如果半小时后你忘了刚才问出来的 SQL,随时再敲 /tree 就能在旁支里翻出来按 Ctrl+X 复制。

场景 4:工具报错刷屏后一键止损回滚

有时模型调用 bash 跑错了一条命令,或者连续三次 edit 匹配失败,往上下文里灌了一大堆无效报错堆栈。无需让模型在泥潭里硬撑,直接 /tree 选中出错前的最后一个健康节点切过去,给它一句明确提示词即可满血复活。

场景 5:超长会话里程碑书签(Bookmark)导航

配合官方示例 packages/coding-agent/examples/extensions/bookmark.ts,你可以在每完成一个子阶段时执行 /bookmark step-1-schema-ready(底层调用 pi.setLabel(entry.id, label)),后续在 /tree 中按 Ctrl+L 就能把几百条流水账折叠成清晰的几个里程碑检查点。

场景 6:只读历史检索与跨分支代码片段提取

不想切换分支、只想找回一小时前模型输出过的某段配置?敲 /tree 直接输入关键词过滤,找到目标节点按 Ctrl+X 拷贝全文,再按 Esc 退出,当前会话游标纹丝不动。

场景 7:通过扩展(Extension)定制树导航与同步外部状态

Pi 围绕 /tree 暴露了完整的扩展生命周期钩子(session_before_tree、session_tree)和编程接口(ctx.navigateTree()、pi.setLabel())。下面给出三个最具代表性的扩展实战模式:

范式 A:拦截 session_before_tree 接管分支摘要或自动打标

和 session_before_compact 类似,你可以拦截 session_before_tree 事件,改用便宜快速的小模型生成分支摘要、强制注入自定义摘要指令,或者自动给生成的摘要节点打上标签:

import { uuidv7 } from "@earendil-works/pi-ai";import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";import { convertToLlm, prepareBranchEntries, serializeConversation } from "@earendil-works/pi-coding-agent";export default function (pi: ExtensionAPI) {    pi.on("session_before_tree", async (event, ctx) => {        const { preparation, signal } = event;        // 若用户未要求生成摘要,或离开分支为空,仅自动附加一个时间戳标签后放行        if (!preparation.userWantsSummary || preparation.entriesToSummarize.length === 0) {            return;        }        // 查找轻量级 Flash 模型接管分支摘要,节省主模型开销        const fastModel = ctx.modelRegistry.find("google", "gemini-2.5-flash");        if (!fastModel) {            // 未配置小模型时,也可以只覆写 customInstructions 和 label,继续复用内置摘要器            return {                customInstructions: "请使用简洁的中文输出分支探索总结,突出失败原因与修改过的文件路径。",                label: "from-branch",            };        }        const { messages } = prepareBranchEntries(preparation.entriesToSummarize, 100_000);        if (messages.length === 0) return;        const conversationText = serializeConversation(convertToLlm(messages));        const response = await ctx.modelRegistry.complete(            fastModel,            {                messages: [                    {                        role: "user",                        content: [                            {                                type: "text",                                text: `请将以下被放弃的对话分支浓缩为结构化中文交接摘要(包含目标、已完成项、受阻原因与涉及文件):\n\n<conversation>\n${conversationText}\n</conversation>`,                            },                        ],                        timestamp: Date.now(),                    },                ],            },            { maxTokens: 4096, signal, cacheRetention: "none", sessionId: uuidv7() },        );        const summaryText = response.content            .filter((b): b is { type: "text"; text: string } => b.type === "text")            .map((b) => b.text)            .join("\n");        if (!summaryText.trim()) return;        return {            label: "flash-summary",            summary: {                summary: summaryText,                usage: response.usage, // 计入会话总成本统计                details: { summarizer: fastModel.id },            },        };    });}

范式 B:监听 session_tree 让有状态扩展随分支自动“时光倒流”

如果你的扩展在内存里维护了状态(例如 Todo 任务列表、游戏棋盘、自定义开关),由于 /tree不会重启扩展,当用户从分支 A 跳到分支 B 时,你必须监听 session_tree 事件,根据新分支路径 ctx.sessionManager.getBranch() 重新回放状态(参考官方示例 todo.ts):

import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";export default function (pi: ExtensionAPI) {    let todos: Array<{ id: number; text: string; done: boolean }> = [];    const reconstructFromActiveBranch = (ctx: ExtensionContext) => {        todos = [];        // getBranch() 只返回从根到当前新 leafId 的活跃路径条目,天然排除了其它旁支!        for (const entry of ctx.sessionManager.getBranch()) {            if (entry.type === "message" && entry.message.role === "toolResult" && entry.message.toolName === "todo") {                const details = entry.message.details as { todos?: typeof todos } | undefined;                if (details?.todos) {                    todos = details.todos;                }            }        }    };    // 会话初次加载与每次 /tree 切换分支后,都用同一套纯函数从活跃路径重建内存状态    pi.on("session_start", async (_event, ctx) => reconstructFromActiveBranch(ctx));    pi.on("session_tree", async (_event, ctx) => reconstructFromActiveBranch(ctx));}

范式 C:弥补“只切对话不切代码”——用扩展实现 /tree 联动 Git 工作区回滚

前面我们特别提醒过,内置 /tree 不会回滚磁盘代码。但借助 turn_start + pi.appendEntry() + session_before_tree,不到 40 行代码就能给 /tree 装上自动代码时光机(改造自官方 git-checkpoint.ts):

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";export default function (pi: ExtensionAPI) {    const checkpoints = new Map<string, string>();    // 每轮模型动手改代码前,用 git stash create 生成一个无副作用的工作区快照对象(不改动当前工作区)    pi.on("turn_start", async (_event, ctx) => {        const leafId = ctx.sessionManager.getLeafId();        if (!leafId) return;        const { code, stdout } = await pi.exec("git", ["stash", "create"]);        const stashSha = stdout.trim();        if (code === 0 && stashSha) {            checkpoints.set(leafId, stashSha);        }    });    // 用户执行 /tree 准备跳转前,若目标节点存有代码快照,弹窗询问是否连同磁盘代码一起回滚!    pi.on("session_before_tree", async (event, ctx) => {        const stashSha = checkpoints.get(event.preparation.targetId);        if (!stashSha || !ctx.hasUI) return;        const choice = await ctx.ui.select("检测到该历史节点存在 Git 代码快照,是否同步恢复工作区文件?", [            "仅切换对话上下文(保留当前磁盘代码)",            "同时将工作区代码恢复到该节点状态",            "取消本次 /tree 跳转",        ]);        if (choice === undefined || choice === "取消本次 /tree 跳转") {            return { cancel: true };        }        if (choice === "同时将工作区代码恢复到该节点状态") {            await pi.exec("git", ["checkout", "--", "."]);            await pi.exec("git", ["stash", "apply", stashSha]);            ctx.ui.notify("已将工作区代码同步恢复至目标分支节点", "info");        }    });}

七、总结:一张全景表掌握 /tree 核心机制

最后,我们将 /tree 命令从存储结构、游标算法到 UI 渲染与扩展机制的全部关键设计浓缩为以下全景对照表:

架构层次
核心机制与策略
解决的工程痛点
对应源码位置
会话持久层
单 .jsonl 追加式树状账本(id + parentId)+ 内存叶子游标 leafId
不新建会话文件、不删改任何历史记录
,实现零成本原地分叉与多分支并存
session-manager.ts_appendEntry()
 / branch() / resetLeaf()
上下文投影层buildSessionPath()
 从 leafId 沿 parentId 反向回溯至根,结合 Compaction 与 context_edit 投影
老分支自动脱离模型上下文视野(0 Token 开销),且随时可再次通过 /tree 无损切回
session-manager.tsbuildSessionPath()
 / buildSessionProjection()
差异化落位规则
选 user / custom_message 退至 parentId 并回填输入框;选 assistant / 其它节点停在 targetId 且输入框留空
精准贴合“撤回改写提问”与“顺着某条回复继续聊”两种截然不同的直觉意图
agent-session.tsnavigateTree()
跨分支摘要桥接
LCA 算法定位最近公共祖先,仅浓缩 oldLeaf -> commonAncestor 区间为 BranchSummaryEntry 挂于 newLeafId
避免重复摘要公共主干;将失败分支的踩坑结论与累积 <read/modified-files> 带入新分支
branch-summarization.tscollectEntriesForBranchSummary()
 / generateBranchSummary()
分支环境同步
导航后依次执行 _refreshFinalizedContext() + _restoreToolsFromTranscript()
确保切换分支后不仅对话记忆同步,连该分支动态加载的激活工具集(Active Tools)也精确还原
agent-session.ts_restoreToolsFromTranscript()
终端树渲染器
显式栈扁平化、活跃分支置顶(• 标记)、单链零缩进防右移溢出、5 档过滤与可见连接线动态重算
在窄终端与超深对话中依然保持树形结构清晰可读,支持实时搜索、折叠、打标与复制
tree-selector.tsTreeSelectorComponent
 / TreeList
插件扩展闭环ctx.navigateTree()
、session_before_tree(可取消/接管摘要)、session_tree(重建分支状态)
支持切换廉价摘要模型、分支状态回放,以及联动 Git 快照实现“对话 + 代码”双重时光倒流
extensions/types.ts
 / bookmark.ts

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料