Claude Code恢复完整会话历史简易教程

2026-06-22阅读 0热度 0

Claude

buildConversationChain — 从 JSONL 精确重建对话流程

基于 src/utils/sessionStorage.ts 源码深度解析

要掌握 Claude Code 如何从磁盘上看似杂乱的 JSONL 文件里还原完整对话，必须深入源码，剖析其处理流水线。核心判断：JSONL 文件中的内容本质上是按写入时间追加的无序行——逻辑顺序隐藏于 parentUuid 构成的链表中。

整个恢复流程由四个环节串联：解析文件 → 定位锚点 → 沿链表回溯 → 修复因并行工具调用断裂的链。

整体流程

JSONL 文件在磁盘上（无序追加的行）
        │
        ▼
loadTranscriptFile()                     ← 步骤 1: 解析
        │
        ├─ 逐行 parse JSON → Entry 对象
        ├─ TranscriptMessage → Map
        ├─ 元数据条目 → 各自的 Map（summaries, titles, tags...）
        ├─ 计算 leafUuids（哪些消息是叶子节点）
        └─ applyPreservedSegmentRelinks() / applySnipRemovals()
        │
        ▼
findLatestMessage(leafUuids)             ← 步骤 2: 找锚点
        │
        ▼
buildConversationChain(messages, leaf)   ← 步骤 3: 链表回溯
        │
        ▼
recoverOrphanedParallelToolResults()     ← 步骤 4: 修复并行工具
        │
        ▼
返回 TranscriptMessage[]（从根到叶的有序数组）

步骤 1: loadTranscriptFile() — 解析 JSONL 建立索引

位置: src/utils/sessionStorage.ts:3472

1a. 逐行读取

const entries = parseJSONL(buf)   // 逐行 JSON.parse

每行 JSON 被解析为 Entry 联合类型，解析结果分发到不同数据结构中。

1b. 分发到不同容器

const messages = new Map()   // 对话消息
const summaries = new Map()              // compact 摘要
const customTitles = new Map()           // 用户自定义标题
const tags = new Map()                   // 标签
const fileHistorySnapshots = new Map()      // 文件快照
const attributionSnapshots = new Map()      // 归属快照
const contentReplacements = new Map()       // 内容替换记录
// ... 更多

根据 entry.type 字段分发:

entry.type === 'user'        → messages.set(entry.uuid, entry)
entry.type === 'assistant'   → messages.set(entry.uuid, entry)
entry.type === 'system'      → messages.set(entry.uuid, entry)
entry.type === 'attachment'  → messages.set(entry.uuid, entry)
entry.type === 'summary'     → summaries.set(entry.leafUuid, entry.summary)
entry.type === 'custom-title'→ customTitles.set(entry.sessionId, entry.customTitle)
entry.type === 'tag'         → tags.set(entry.sessionId, entry.tag)
entry.type === 'mode'        → modes.set(entry.sessionId, entry.mode)
... 以此类推

关键：JSONL 中的行按物理追加顺序写入，而非逻辑对话顺序。解析后的 Map 是哈希表——所有消息平铺在一个大 Map 中，逻辑顺序完全由 parentUuid 指针维护。

1c. 处理旧版 progress 桥接

旧版中 progress 类型条目也参与 parentUuid 链。新版不再将其视为 TranscriptMessage。为兼容旧 transcript，需要桥接:

// src/utils/sessionStorage.ts:3629-3641
if (isLegacyProgressEntry(entry)) {
  const parent = entry.parentUuid
  progressBridge.set(
    entry.uuid,
    parent && progressBridge.has(parent)
      ? (progressBridge.get(parent) ?? null)  // 链式解析
      : parent,
  )
  continue
}
// 后续处理 TranscriptMessage 时跳过 progress，直连到真正的 parent:
if (entry.parentUuid && progressBridge.has(entry.parentUuid)) {
  entry.parentUuid = progressBridge.get(entry.parentUuid) ?? null
}

1d. 大文件优化

对于超过 SKIP_PRECOMPACT_THRESHOLD 的大 transcript，加载时有三点优化：

readTranscriptForLoad() — 在 fd 层面跳过 compact boundary 之前的字节（attribution-snapshot 行在读取时直接过滤）
scanPreBoundaryMetadata() — 从 boundary 之前的字节中恢复 session 元数据（agentSetting、mode、pr-link 等）
walkChainBeforeParse() — 在 JSON 解析前遍历 parentUuid 链，丢弃不在链上的死分支（对分叉/合并场景节省大量内存）

1e. 计算叶子节点

// 所有作为别人 parent 的 UUID
const parentUuids = new Set(
  allMessages
    .map(msg => msg.parentUuid)
    .filter((uuid): uuid is UUID => uuid !== null),
)
// 叶子 = 所有消息的 UUID - 所有作为别人 parent 的 UUID
const leafUuids = new Set(
  allMessages
    .filter(m => isUserOrAssistantMessage(m))
    .map(m => m.uuid)
    .filter(uuid => !parentUuids.has(uuid))
)

叶子节点就是未被任何其他消息引用为 parentUuid 的消息。一个对话可以有多条链（如分叉），因此有多个叶子。

1f. applyPreservedSegmentRelinks()

位置: src/utils/sessionStorage.ts:1839

compact 发生后，JSONL 中会插入 compact boundary 标记。boundary 之前的消息通过"保留段"(preserved segment)机制保存:

JSONL 物理布局:
  msg_1 (parent: null)     ← pre-compact
  msg_2 (parent: 1)        ← pre-compact
  msg_3 (parent: 2)        ← pre-compact, preserved segment HEAD
  msg_4 (parent: 3)        ← pre-compact, preserved segment TAIL
  [compact boundary]       ← 带有 preservedSegment 元数据
  msg_5 (parent: null)     ← post-compact: boundary marker
  msg_6 (parent: 5)        ← post-compact: summary
  msg_7 (parent: 6)        ← post-compact: 新用户消息

applyPreservedSegmentRelinks 执行四步：

重新链接保留段头部 — 将 preserved segment 第一条消息的 parentUuid 指向 boundary 的 anchorUuid
重新链接保留段尾部 — 将 anchor 的其他直接子消息的 parentUuid 改为指向保留段尾部
清零保留段内 assistant 消息的 token usage — 避免 resume 后旧 usage 数据触发自动 compact
剪枝 — 删除 boundary 之前且不在保留段内的所有消息

1g. applySnipRemovals()

删除被 snip 操作标记移除的消息（snip 是精确的上下文裁剪机制，按消息范围删除）。

步骤 2: findLatestMessage() — 定位最新叶子

位置: src/utils/sessionStorage.ts:2046

function findLatestMessage(
  messages: Iterable,
  predicate: (m: T) => boolean,
): T | undefined {
  let latest: T | undefined
  let maxTime = -Infinity
  for (const m of messages) {
    if (!predicate(m)) continue
    const t = Date.parse(m.timestamp)
    if (t > maxTime) {
      maxTime = t
      latest = m
    }
  }
  return latest
}

从所有叶子节点中，选取 timestamp 最新的作为恢复起点。这确保 --resume 始终恢复到最后一条消息所在的链。

Map 中所有消息:
  msg_A (parent: null,  ts: 04:20:00)
  msg_B (parent: A,     ts: 04:21:00)
  msg_C (parent: B,     ts: 04:22:00)   ← 被 msg_D 引用为 parent → 不是叶子
  msg_D (parent: B,     ts: 04:23:00)   ← 无人引用为 parent → 是叶子！

leafUuids = { msg_D }
findLatestMessage → msg_D（timestamp 最大）

步骤 3: buildConversationChain() — 沿链表回溯

位置: src/utils/sessionStorage.ts:2069

export function buildConversationChain(
  messages: Map,   // 步骤 1 构建的 HashMap
  leafMessage: TranscriptMessage,           // 步骤 2 选出的最新叶子
): TranscriptMessage[] {
  const transcript: TranscriptMessage[] = []
  const seen = new Set()
  let currentMsg: TranscriptMessage | undefined = leafMessage
  // 从叶子向根遍历
  while (currentMsg) {
    // 环检测：防御性编程
    if (seen.has(currentMsg.uuid)) {
      logError(new Error(
        `Cycle detected in parentUuid chain at message ${currentMsg.uuid}. ` +
        `Returning partial transcript.`
      ))
      logEvent('tengu_chain_parent_cycle', {})
      break
    }
    seen.add(currentMsg.uuid)
    // 尾插到数组（结果是倒序的）
    transcript.push(currentMsg)
    // 通过 parentUuid 在 HashMap 中 O(1) 查找上一条消息
    currentMsg = currentMsg.parentUuid
      ? messages.get(currentMsg.parentUuid)
      : undefined
  }
  // 反转数组：从倒序变为正序（根 → 叶）
  transcript.reverse()
  // 修复并行工具调用的孤儿结果
  return recoverOrphanedParallelToolResults(messages, transcript, seen)
}

回溯过程示意

JSONL Map（无序 HashMap）:
  ┌──────────────────────────────────────────────────────┐
  │ uuid: "D"  type: assistant  parentUuid: "C"  ts:...  │
  │ uuid: "A"  type: user       parentUuid: null  ts:... │
  │ uuid: "C"  type: user       parentUuid: "B"  ts:...  │
  │ uuid: "B"  type: assistant  parentUuid: "A"  ts:...  │
  └──────────────────────────────────────────────────────┘

叶子 = "D"（最新 timestamp，无子节点）

回溯:
  step 1: currentMsg = D
           transcript = [D]
  step 2: currentMsg = messages.get("C") = C
           transcript = [D, C]
  step 3: currentMsg = messages.get("B") = B
           transcript = [D, C, B]
  step 4: currentMsg = messages.get("A") = A
           transcript = [D, C, B, A]
  step 5: currentMsg = messages.get(null) = undefined → 停止

reverse → [A, B, C, D]  ← 正确的对话顺序（从第一条到最新）

三个关键机制

机制	说明
O(1) HashMap 查找	messages.get(parentUuid) 不依赖 JSONL 行的物理顺序
环检测	链表出现环（数据损坏）时记录错误并退出，返回部分链
不完整链自动终止	parentUuid 指向的 UUID 不在 Map 中时返回 undefined，遍历终止

步骤 4: recoverOrphanedParallelToolResults() — 修复并行工具孤儿结果

位置: src/utils/sessionStorage.ts:2118

这是恢复过程中最精妙的部分。需要先理解两个问题：

LLM 发出并行工具调用时，JSONL 实际如何写入？
buildConversationChain 回溯后，部分消息为何丢失？

4.1 前置知识：并行工具调用的 JSONL 写入

假设 LLM 在一次回复中同时发出三个工具调用：Bash、Read、Grep。

API 返回的 assistant 消息（uuid: B）:
  message.content = [
    { type: "text",    text: "Let me check..." },
    { type: "tool_use", id: "toolu_1", name: "Bash", ... },
    { type: "tool_use", id: "toolu_2", name: "Read", ... },
    { type: "tool_use", id: "toolu_3", name: "Grep", ... },
  ]

这三个工具并行执行，各自独立完成。每个工具完成后，结果被包装为一条 user 消息写入 JSONL（通过 recordTranscript → insertMessageChain）。

关键点在于 insertMessageChain 写入时 parentUuid 的分配方式。看代码：

// src/utils/sessionStorage.ts:1001-1068（简化）
let parentUuid: UUID | null = startingParentUuid ?? null  // 初始值
for (const message of messages) {
  // ★ 关键：对 tool_result 消息，使用 sourceToolAssistantUUID
  let effectiveParentUuid = parentUuid
  if (message.type === 'user' && message.sourceToolAssistantUUID) {
    effectiveParentUuid = message.sourceToolAssistantUUID  // ← 指向 assistant B！
  }
  const transcriptMessage = {
    parentUuid: effectiveParentUuid,  // ← 写入 JSONL 的 parentUuid
    ...message,
  }
  await this.appendEntry(transcriptMessage)
  if (isChainParticipant(message)) {
    parentUuid = message.uuid  // ← 更新顺序链指针，供下一条消息使用
  }
}

每个 tool_result 的 parentUuid 都指向同一个 assistant 消息 B（因为 sourceToolAssistantUUID 覆盖了 effectiveParentUuid）。但顺序链指针 parentUuid 会在每写入一条消息后更新。

所以 JSONL 中实际写入的内容是：

消息      type          JSONL 中的 parentUuid    原因
──────────────────────────────────────────────────────────────────
A        user          null                     用户的第一条输入
B        assistant     A                        正常链（B 的 parent 是 A）
C        user          B           ←★            Bash 结果，sourceToolAssistantUUID = B
D        user          B           ←★            Read 结果，sourceToolAssistantUUID = B
E        user          B           ←★            Grep 结果，sourceToolAssistantUUID = B
F        assistant     E           ←★            顺序链：F 的 effectiveParentUuid = parentUuid 变量 = E

关键洞察:

C、D、E 的 parentUuid 都是 B —— 它们都是 B 的"子节点"
F 的 parentUuid 是 E —— 因为写入 E 之后 parentUuid 变量被更新为 E

4.2 问题：回溯时发生了什么

当 buildConversationChain 从叶子 F 开始回溯：

从叶子 F 出发，沿 parentUuid 链回溯：

  currentMsg = F
  → transcript = [F]
  → 下一个 = messages.get(F.parentUuid) = messages.get("E") = E

  currentMsg = E
  → transcript = [F, E]
  → 下一个 = messages.get(E.parentUuid) = messages.get("B") = B
                                                          ↑
                                          注意：E.parentUuid 是 B，不是 D！

  currentMsg = B
  → transcript = [F, E, B]
  → 下一个 = messages.get(B.parentUuid) = messages.get("A") = A

  currentMsg = A
  → transcript = [F, E, B, A]
  → 下一个 = messages.get(A.parentUuid) = messages.get(null) = undefined → 停止

reverse → [A, B, E, F]

问题暴露: 回溯得到的链是 [A, B, E, F]，C 和 D 丢失！

JSONL Map 中有 6 条 TranscriptMessage:
  A ←── 在链上
  B ←── 在链上
  C ←── ★ 不在链上！parentUuid = B，但回溯走的是 B→E→F
  D ←── ★ 不在链上！parentUuid = B，但回溯走的是 B→E→F
  E ←── 在链上
  F ←── 在链上（叶子）

回溯利用的 seen 集合 = {A, B, E, F}
不在 seen 中的 = {C, D}  ← 这就是"孤儿"

原因：parentUuid 只能表达一对多中的"一"侧。消息 B 有三个子节点（C、D、E），但每个子节点只能有一个 parentUuid 值。回溯时只能沿一条路径走（B→E→F），其他路径（B→C、B→D）被遗漏。

4.3 恢复算法详解

recoverOrphanedParallelToolResults 的目标就是找回这些孤儿。

第一步：收集链上所有的 assistant 消息

const chainAssistants = chain.filter(m => m.type === 'assistant')
// 结果: [B, F]  （链上的两条 assistant）

第二步：建立反向索引 —— 哪些 tool_result 指向这个 assistant

// 遍历 Map 中 ALL 消息（不仅是链上的）
// 按 parentUuid 对 tool_result 消息建立索引
const toolResultsByAsst = new Map()
for (const m of messages.values()) {
  if (m.type === 'user' && m.parentUuid && 
      Array.isArray(m.message.content) &&
      m.message.content.some(b => b.type === 'tool_result')) {
    // m 是一条 tool_result 消息
    const group = toolResultsByAsst.get(m.parentUuid)
    if (group) group.push(m)
    else toolResultsByAsst.set(m.parentUuid, [m])
  }
}
// 遍历后的 toolResultsByAsst:
//   B → [C, D, E]   ← 三条 tool_result 都指向 B！
//   （F 没有 tool_result 子节点，所以不在 Map 中）

第三步：对每个链上的 assistant，找出孤儿

for (const asst of chainAssistants) {    // asst = B, 然后 asst = F
  // 查找所有 parentUuid 指向该 assistant 的 tool_result
  const trs = toolResultsByAsst.get(asst.uuid)  // B → [C, D, E]
  // 过滤出不在链上的（即 seen 集合中没有的）
  for (const tr of trs) {
    if (!seen.has(tr.uuid)) orphanedTRs.push(tr)
  }
}
// 对于 B: seen = {A, B, E, F}
//   C 不在 seen → 孤儿！
//   D 不在 seen → 孤儿！
//   E 在 seen → 不是孤儿（链上已有）
// orphanedTRs = [C, D]
// 对于 F: toolResultsByAsst 中没有 key=F → 无操作

第四步：按时间戳排序孤儿

orphanedTRs.sort((a, b) => a.timestamp.localeCompare(b.timestamp))
// C 先完成 (ts: 04:20:01), D 后完成 (ts: 04:20:02)
// sorted = [C, D]

第五步：将孤儿插入到正确位置

// "锚点" = 触发这些 tool_use 的 assistant 消息本身
// 孤儿应该出现在 assistant 和下一个 assistant 之间
const anchor = asst    // 即 B
inserts.set(anchor.uuid, [C, D])
// 含义：在 B 后 面插入 [C, D]

最后：重建数组

const result = []
for (const m of chain) {   // chain = [A, B, E, F]
  result.push(m)
  const toInsert = inserts.get(m.uuid)
  if (toInsert) result.push(...toInsert)
}
// 遍历过程:
//   m = A: result = [A],         A 没有待插入项
//   m = B: result = [A, B],      B 有待插入项 → push(C, D)
//          result = [A, B, C, D]
//   m = E: result = [A, B, C, D, E],  E 没有待插入项
//   m = F: result = [A, B, C, D, E, F], F 没有待插入项

4.4 最终效果对比

回溯得到的链（修复前）:
  [A, B, E, F]
   ↑  ↑     ↑
   │  │     └─ 第二轮 assistant
   │  └─────── 只有 Grep 的 tool_result（最后完成的那个）
   └────────── 用户输入

修复后的链:
  [A, B, C, D, E, F]
   ↑  ↑  ↑  ↑  ↑  ↑
   │  │  │  │  │  └─ 第二轮 assistant
   │  │  │  │  └──── Grep 结果（最后完成）
   │  │  │  └─────── Read 结果（恢复的孤儿）
   │  │  └────────── Bash 结果（恢复的孤儿）
   │  └───────────── 包含 Bash+Read+Grep 的 assistant
   └──────────────── 用户输入

4.5 算法的通用性

此算法不仅处理单个 assistant 发出多个 tool_use，还涵盖：

场景	示例	恢复方式
单个 assistant 发出 N 个并行工具	B 发出 Bash+Read+Grep	恢复 N-1 个孤儿 tool_result
多个 assistant 各自发出工具	B1 发出 Bash, B2 发出 Read	每轮独立恢复
同一 API 请求的多个分片（streaming）	B 被分成 B₁、B₂ 两个消息	siblingsByMsgId 按 message.id 分组处理
嵌套工具调用	Tool A 触发 Agent B，Agent B 触发 Tool C	每层独立恢复

4.6 一句话总结

并行工具调用的结果在 JSONL 中都指向同一个 assistant 消息作为 parent。但 parentUuid 链是线性的——从叶子回溯只能走到最后完成的那条 tool_result。recoverOrphanedParallelToolResults 通过反向索引（parentUuid → tool_result 列表）找出所有孤儿，按时间戳排序后插回正确位置。

步骤 5: Compact 恢复的特殊处理

preservedSegment 机制

compact 发生时，大部分旧消息被摘要替代，但最近几条核心对话可标记为"保留段"保留在 JSONL 中。

applyPreservedSegmentRelinks