ARTICLE · 1376050
会话树导航与分支回溯机制 - Pi 源码分析 12
本文是「Pi 源码分析」第 12 篇。在用 Coding Agent 处理复杂工程任务时,对话很少是一条笔直的单行道:你可能想改写三轮前的某句提问重新生成;可能在尝试某种重构方案撞南墙后,想带着踩坑教训退回岔路口换条路走;也可能只是临时插嘴问一个支线问题,问完不想让它留在主线上下文里白白消耗 Token。
在传统线性聊天工具里,你只能在“将就着把脏历史留在上下文里”和“删掉历史消息再也找不回来”之间二选一。Pi Coding Agent 用 /tree(会话树导航) 命令彻底解开了这个死结。本篇我们深入 packages/coding-agent 源码,把以下四个核心问题一次讲透:
1. /tree命令的功能到底是什么?2. 调用 /tree之后:会新开一个会话吗?老会话(老分支)是如何处理的?3. 它在底层数据结构、上下文投影、分支摘要与终端 UI 上是怎么实现的? 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() |
| 2b. 老会话(老分支)如何处理? | 原样保留在同一个文件里,自动脱离模型视野,可选摘要桥接:.jsonl 文件中,随时可以再次通过 /tree 切回去;② 逻辑上自动隔离:发给大模型的上下文只取“从新 leafId 沿 parentId 回溯到根节点”的那条路径,老分支不在路径上,因此消耗 0 Token,也不会干扰模型;③ 经验可跨分支传递:若导航时选择 Summarize,Pi 会提取“老分支叶子回退至最近公共祖先”之间的对话,让 LLM 浓缩成一条 branch_summary 记录挂到新分支起点,把踩坑结论带过去。 | session-manager.tsbranch()branchWithSummary() / buildSessionPath()branch-summarization.ts |
| 3. 它一般是怎么实现的? | leafId) + 路径反向投影(Path Projection)” 架构:每条记录携带 id 与 parentId 构成有向树;分叉只是改写 leafId 指针;选中“用户消息”时回退到其父节点并将文本塞回输入框供改写,选中“助手消息”时直接停在该节点后续写。 | session-manager.tsagent-session.ts |
| 4. 它的使用场景有哪些? | 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. E1 (user):“给login.ts加 JWT 校验”2. E2 (assistant):“好的,目前有两种主流方案:方案一用jsonwebtoken,方案二用jose……”3. E3 (user):“用方案一jsonwebtoken”4. E4 (assistant + toolCall):调用edit修改了 3 个文件5. E5 (user):“跑一下单元测试”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 图谱的设计:
SessionManager 对应机制 | ||
|---|---|---|
SessionEntry | ||
entry.id | generateId() 截取 UUID 前 8 位并做碰撞校验生成 | |
entry.parentIdstring | null) | id;若为 null 则表示树的根节点(Root) | |
HEAD | SessionManager.leafIdstring | 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. 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. 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. 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. branch(branchFromId: string):校验 ID 存在后,仅仅执行一行this.leafId = branchFromId!此时甚至不需要写磁盘——等用户发出下一条消息时,新消息的parentId就会自动指向branchFromId,新分支自然落盘。2. resetLeaf():执行this.leafId = null。用于用户选中会话的第 1 条根消息重新编辑的场景,下一条发出的消息parentId为null,成为树里的第 2 个根节点。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. 回退游标与回填提问:因为 E3是一条用户消息,Pi 明白你想“撤回并改写这句话”,于是将目标挂载点定为E3的父节点E2,同时把"用方案一 jsonwebtoken"填回底部输入框。2. 追加分支摘要 E7:Pi 收集从老叶子E6回退到公共祖先E2之间的E3..E6,调用大模型生成浓缩摘要,往同一个.jsonl文件末尾追加第 7 条记录E7(type: "branch_summary",parentId: "E2",fromId: "E6"),此时leafId变为"E7"。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 与 /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 血缘 | parentSession: "<原文件路径>" | 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. 斜杠命令 /tree:在输入框输入/tree回车,命中interactive-mode.ts第 3366 行if (text === "/tree") { this.showTreeSelector(); };2. 空输入框双击 Esc(最顺手的快捷方式):当底部输入框为空且当前没有流式输出或正在运行的bash命令时,500ms 内连按两次Esc,Pi 会读取settings.json中的doubleEscapeAction配置(默认值为"tree",也可改为"fork"或"none"),直接调用this.showTreeSelector();3. 自定义全局快捷键 app.session.tree:默认未绑定按键,用户可在keybindings.json中配置(如"app.session.tree": ["ctrl+shift+t"]),触发编辑器动作回调打开树选择器;4. 扩展 API 编程化调用 ctx.navigateTree(targetId, options):在自定义斜杠命令(ExtensionCommandContext)中无需弹出 UI,直接由代码驱动跳转到任意节点(注意 RPC 模式目前仅暴露只读的get_tree查询接口,尚未提供直接的navigate_treeRPC 命令,但可通过扩展命令触发)。
2. 阶段一:UI 确认弹窗与流式并发守卫(showTreeSelector)
打开 interactive-mode.ts 第 5693~5840 行的 showTreeSelector(),当用户在 TreeSelectorComponent 中选中一个目标条目 entryId 按下回车时,Pi 并不会莽撞地立刻改指针,而是做了三层严谨的交互与并发处理:
1. 原地点击幂等短路:如果 entryId === this.sessionManager.getLeafId()(选中的就是当前所在的叶子节点),直接关闭选择器并提示"Already at this point",什么也不做。2. 三级摘要意愿询问(支持按 Esc逐级回退):只要用户在settings.json中没有开启branchSummary.skipPrompt: true(默认false),界面就会弹出选择菜单:• "No summary"(直接切过去,不要摘要)• "Summarize"(使用内置默认模板生成分支摘要)• "Summarize with custom prompt"(接着弹出多行编辑器,让你输入自定义摘要侧重点customInstructions)人性化回退细节:如果你在二级菜单按Esc取消,它不会直接把你踢回主聊天界面,而是调用this.showTreeSelector(entryId)重新打开树选择器,且光标依然停在你刚才选中的那个节点上!如果在三级自定义指令框按Esc,则会退回二级摘要菜单。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. 按 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. 防续写文本序列化 + 专用结构化 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. 防工具调用校验与前缀/后缀拼装:通过 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. this._refreshFinalizedContext():重新调用sessionManager.buildSessionProjection(),把新分支路径投影出来的AgentMessage[]赋值给this.agent.state.messages,彻底换掉 Agent 脑子里的对话记忆。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. 触发 session_tree事件并重绘 TUI:发出后置事件通知所有扩展同步状态,返回{ editorText, cancelled: false, summaryEntry }。外层InteractiveMode收到后,执行this.chatContainer.clear()清屏,调用this.renderInitialMessages()把新分支的历史重新渲染到终端上,并将editorText填入底部编辑器(仅在编辑器当前为空时写入,避免覆盖用户草稿)。
下图完整串联了上述三个模块在三大阶段的端到端时序交互:

五、终端交互层揭秘: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. 后序标记活跃分支优先排在最上方:先用一遍逆后序遍历算出 containsActive: Map<SessionTreeNode, boolean>,标记哪些子树里包含当前的currentLeafId。在展开任意父节点的子节点列表时,包含当前活跃叶子的那个子分支永远排在第 1 位,其余历史旁支按时间戳紧随其后;同时,从根到当前叶子的整条活跃路径上的所有节点都会标上一颗醒目的高亮圆点•,让你一眼看清自己当前身处哪条支流。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. 固定左侧游标栏的横向智能视口( 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-tools | Ctrl+T | default 基础上进一步隐藏所有 toolResult 节点 | read/grep 刷屏,只看人机对话 |
user-only | Ctrl+U | 只显示用户发送的 user 消息 | |
labeled-only | Ctrl+L | 只显示打过 label 标签的书签节点 | |
all | Ctrl+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. 按 Esc停掉当前生成,再双击Esc打开/tree;2. 光标默认就在底部附近,选中你刚才发出的那条 user消息回车,选No summary;3. 原提问已经自动回到输入框,补上一句“注意:只修改后端 API 分页参数,不动前端组件”重新发送。刚才那半截走偏的生成被彻底甩在旁支,主线上下文干干净净。
场景 2:方案 A / 方案 B 架构试错与踩坑经验迁移
面对复杂重构拿不准该用哪套技术方案时:
1. 在方案讨论节点先按 Shift+L打个标签arch-fork;2. 先让模型大胆尝试激进的“方案 A”。如果折腾了 10 轮发现某个底层库存在死穴,打开 /tree按Ctrl+L找到arch-fork节点回车;3. 选择 Summarize(或Summarize with custom prompt输入“重点总结方案 A 遇到的兼容性死穴”)。4. 切回分叉点后,模型手里拿着一份几百字的“方案 A 尸检报告”去写“方案 B”,既省下了 10 轮试错的几万 Token,又绝不会重蹈方案 A 的覆辙。
场景 3:“无痕支线提问”——保持主线上下文零污染
这是重度用户最喜欢的高阶技巧。假设你正在让 Pi 重构核心支付模块,上下文已经高度聚焦;这时你突然忘了某个 TypeScript 泛型体操语法,或者想让它帮忙写一条一次性的数据迁移 SQL:
1. 直接在当前对话里问这个无关问题,等拿到答案后(甚至可以让它连调几次 bash查清环境问题);2. 双击 Esc打开/tree,选中你问这个支线问题之前的最后一条主线assistant回复,选择No summary;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 投影 | /tree 无损切回 | session-manager.tsbuildSessionPath()buildSessionProjection() |
| 差异化落位规则 | user / custom_message 退至 parentId 并回填输入框;选 assistant / 其它节点停在 targetId 且输入框留空 | agent-session.tsnavigateTree() | |
| 跨分支摘要桥接 | oldLeaf -> commonAncestor 区间为 BranchSummaryEntry 挂于 newLeafId | <read/modified-files> 带入新分支 | branch-summarization.tscollectEntriesForBranchSummary()generateBranchSummary() |
| 分支环境同步 | _refreshFinalizedContext() + _restoreToolsFromTranscript() | agent-session.ts_restoreToolsFromTranscript() | |
| 终端树渲染器 | • 标记)、单链零缩进防右移溢出、5 档过滤与可见连接线动态重算 | tree-selector.tsTreeSelectorComponentTreeList | |
| 插件扩展闭环 | ctx.navigateTree()session_before_tree(可取消/接管摘要)、session_tree(重建分支状态) | extensions/types.tsbookmark.ts |















































































