Files
Agent-Workbench/docs/research/CONTEXT-RECOVERY.md
T
2026-10-29 11:23:43 +08:00

11 KiB
Raw Blame History

Claude Code 2.1.312:上下文压缩与会话恢复

本次研究核对了当前 Windows 官方发行物中两条客户端机制。压缩不是简单地截掉旧消息:它有预算判断、摘要生成、钩子、状态返回、边界记录和失败保护。恢复也不是重读一段聊天文本:它按消息身份重建链,恢复工作状态,并识别没有对应结果的工具调用。

这些结论是已读取的静态代码条件与调用表达式,没有执行 Claude Code,没有访问用户会话,也没有观察真实模型服务。函数名称属于这个构建,不能当作跨版本稳定接口。

工件与方法

  • 官方包:@anthropic-ai/claude-code-win32-x64@2.1.312。
  • EXE:298,690,208 字节;SHA256 6099672ebe5dcb518b67d1d32dde1e3360bc6bee1dae7f8d28a69c49acc7c865。
  • 主体证据文件:recovered/modules/chunk-9hk5qx04.js,SHA256 c958226d1a62d226947f5795ba4d8de70fd3673ca9fb7b80bd50f29bde8923df。本文件的原始内容散列与 UTF-8 派生散列一致,因此索引还给出了可直接复核的 EXE 字节范围。
  • 名称适配导出:chunk-cgy8y2q9.js 导出 buildConversationChain、recordTranscript、loadTranscriptFromFile、loadTranscriptFile、restoreSessionMetadata、adoptResumedSessionFileAsync 等可读名称,对应主体中的混淆符号。
  • 用 Babel 只解析相关分块,读取函数、方法、分支、返回值和调用位置;没有把字符串命中当作行为证明。
  • 用 REA 对原分块局部选择和 32 个有来源映射的函数/方法摘录做惰性语法与关系分析。摘录仅为静态分析加入声明、导出和一个部分 class 包装;不会运行它们,也不宣称包装是原始源码。

每个函数的 UTF-16 字符区间、UTF-8 字节区间、行号、原始工件范围和片段散列在 CONTEXT-RECOVERY.index.json。完整本地 REA 记录在 CONTEXT-RECOVERY.evidence-bundle.json。

压缩链路

客户端入口协调函数 WFr 调用预算判断 dlr,随后选择普通摘要路径 BFr 或反应式路径。其返回值是明确的状态对象,不仅是成功或失败布尔值。

返回状态 读取到的条件或含义
not_needed 禁用压缩,或当前预算/触发判断未要求压缩
compacted 返回有效的压缩结果及阈值来源等元数据
hook_blocked 钩子拒绝或阻止这次压缩
failed 压缩失败,记录连续失败数和原因
failure_breaker_open 本会话连续失败已到保护上限,跳过后续尝试
rapid_refill_breaker_tripped 压缩后过快再次填满上下文,达到保护上限

dlr 读取消息预算、模型事实、所选窗口和使用量调整,返回预算级别是否为 compact 或 blocked。它还排除了某些查询来源、禁用状态及配置情形。因此不能把“消息数超过某个数字”当作这里的触发规则。

预算助手 JQ 从所选窗口扣除受上限约束的模型输出预算。DQ 默认再预留 13,000 token;有效的测试百分比覆盖也受这个预留限制。ike 能读取 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 等覆盖配置。这里的 13,000 是这个客户端构建中的常量,不建议直接抄成我们自己的所有模型的固定预算。

BFr 的普通摘要路径按以下代码顺序执行:

  1. 拒绝空会话,进入 compacting 状态,调用 pre_compact 钩子并合并自定义指令。
  2. 通过 Hrn 取得摘要响应;若响应显示请求过长,允许有限次数删减输入头部后重试。
  3. 拒绝没有有效文本的摘要和 API 错误消息。这是读取到的响应校验,具体远端请求与模型行为没有观察。
  4. 读取并清理文件读取状态,重新生成需要保留的附件等内容;创建 DK 的 compact_boundary 以及 isCompactSummary 消息。
  5. 为边界记录压缩前后 token、耗时、已发现工具等元数据,调用 post_compact 钩子,返回边界、摘要、附件和钩子结果。
  6. finally 无论结果如何都会结束压缩进度,并发出成功或失败的 SDK 状态。

zrn 的连续失败计数达到 Krn=3 时记录熔断。SVo 在上次已压缩且 turnCounter<3 时增加快速回填计数;DDr 在此计数达到 3 时返回 trip。这两种保护对应不同问题:摘要持续失败,以及摘要即使成功却很快再次填满。

源码还出现闲置预计算、较大模型和反应式路径。它们的调用条件已经定位,但本报告没有把这些外部辅助函数完整还原。钩子、文件读取状态等副作用也说明不能把整个原版压缩过程宣称为一个已经验证的原子事务。

持久化链路

recordTranscript 的构建内符号 eC 从会话存储读取已记录 UUID,跳过重复消息,再调用 NAt.insertMessageChain 写入新消息。NAt.recordInTurn 把 session 与 turn 的组合用于批处理串行入口。

NAt.insertMessageChain 对每条记录生成 parentUuid、会话身份、版本、分支等字段,并调用 appendEntry。普通记录继续消息链;压缩边界将物理 parentUuid 置为 null,同时保留旧链的 logicalParentUuid。

它还有一个特别有用的顺序:遇到压缩边界后设置 compactAwaitingSummary;后续用户/助手行写入后,才调用 requestCompact 进行日志整理。这体现了“先落下新的可恢复内容,再处理旧历史”的客户端设计意图。没有实机证明文件系统崩溃时的完整持久性,也没有证明所有存储后端都相同。

flushSessionStorage 的构建内符号 Wu 调用 NAt.flush。这个方法等待正在进行的 drain、排空写入队列、等待 pendingWriteCount 归零,再释放保留的重播记录;存在 storeFence 时抛出错误。它不等价于已证明所有写入都经过 fsync。

恢复链路

已核对的客户端链路为:

loadTranscriptFromFile (I7e)
  → loadTranscriptFile (Jre)
  → buildConversationChain (TBt)
  → 返回消息、工作树/成本等会话状态
  → restoreSessionMetadata (CK)
  → adoptResumedSessionFileAsync (PCe),重新绑定后续写入

I7e 对 JSONL 与旧 JSON 形式采用不同读取路径。JSONL 结果中有消息 Map、有效 leaf UUID、摘要与会话元数据等。它选择有效叶节点,再调用 TBt 构链;无消息、无有效链、错误 JSON 或错误结构会有明确错误。旧 JSON 读取还设有 256 MiB 限制。

TBt 沿 parentUuid 向前走,使用 Set 检测重复 UUID。发现循环会停止并返回部分链;找不到父节点时会调用时间顺序回退助手,然后逆转链并补齐相关内容。这是静态容错条件,不代表任何损坏会话都能完整恢复。

Jre 对较大的 JSONL 可以跳过压缩前历史,仍保留必要的附属账本与元数据。它同时支持存储 backend 分支和文件分支;权限不可读、缺失与错误等结果被分别处理。源码还记录尾部缺少换行的 tornTail 状态。写入前 NAt.sealTornTailSync 能补上换行,避免残缺尾部与新行直接连在一起;本报告没有验证坏行修复或断电恢复。

CK 恢复标题、模式、权限模式、工作树、工具使用记录与其他会话元数据。PCe 设置本会话写入文件、接收恢复来源,再重新附加会话元数据;失败会记入 writer health。

findUnresolvedToolUsesInTranscript 的构建内符号 IBt 将 tool_use.id 与后续 tool_result.tool_use_id 配对,返回还没有结果的调用。这个函数证明存在未完成调用的识别;它本身不能证明原版恢复时一律重试或一律不重试。

REA 的证据与限制

记录 实际支持与限制
ev_37df041a5f415dc11054ea3f138cd1dafdb1a62fc5eb56c0d27c36d112f831f8 原分块中精确选择 3 个文件;语法全部解析,1 个文件关系分析达到保留上限;2577 文件未分析
ev_2b539340ae6abd762b77fb797bd6aed16c21199f00d2845b53ae864638e9e501 32 个函数/方法的有来源摘录;2 个 JS 文件语法完整,7,427 AST 节点;没有节点/关系省略,但外部全局、动态调用和部分 class 状态仍未知
ev_af11084f350178aa3a8e4d480b661ef6d05124f882c82a5f2ff10a1377e0fa7f compacted 字面量种子的反向关系查询没有取得已保留种子,结果 partial;不能据此断言状态不存在
ev_211eeb035f0a11a4f739dfd378b4a12a79bfcfce2cdb749bf87f09002117d13a parentUuid 属性查询找到 1 个种子,但关系 ambiguous;没有证明完整自动语义路径

上述原分块的 import 使用 B:/~BUN/root/... 绝对虚拟路径。REA 没有自动建立它与当前提取目录的映射,相关跨分块关系保持 unknown。两个 trace 记录也没有提供自己的工件身份,只能通过其父 Evidence 和摘录来源索引追溯。本报告的调用链来自具体函数体的人工 AST 核对与可读导出对照,不包装成已经自动解析、实机验证的完整运行链。

原始作者源码、源映射、内嵌源码与字节码的运行等价性、模型输出质量、并发时序和所有异常恢复路径仍未知。没有执行目标代码。

提炼到自己的本地 Agent 工作台

以下是独立设计选择,并非照搬原客户端实现:

  1. 把压缩作为状态机。 采用 idle/evaluating/summarizing/ready/committed/failed/blocked,向界面展示原因、耗时与预算,避免把失败伪装成成功。
  2. 预算跟着模型走。 从模型窗口扣除响应预算、工具结果预算和可配置安全余量;允许人工摘要与自动摘要,保留完整本地历史。
  3. 先持久化新的恢复点,再清理旧内容。 摘要、保留的工具状态、父链与 checksum 一起写入后再切换活动上下文;失败继续使用此前有效 checkpoint。
  4. 日志按会话串行且可幂等恢复。 每个事件有 id/sessionId/parentId/turnId/type;重复事件不重复应用;长日志定期生成 snapshot,损坏尾部保留副本并报告。
  5. 工具意图与结果成对落盘。 在执行前保存 intent,执行后保存 result;重启出现 pending 时要求显式判定,禁止默默再次运行有副作用的命令。
  6. 给失败和低效循环设保护。 配置压缩重试上限、快速回填检测、工具步数和费用预算;熔断后仍让用户查看完整记录并选择继续。

建议验收使用自己的可控 fixture:重复事件、消息链循环、残缺 JSONL 尾部、摘要服务错误、有效摘要后进程退出、工具执行中断和重新打开工作台。不要用用户的真实会话作为测试数据。

复现

在研究根目录运行 analysis/scripts/context-locate.cjs、analysis/scripts/context-read.cjs 可重新定位指定符号。analysis/context-evidence/provenance.json 记录摘录来源;REA 本次使用的具体参数与查询在规范化 Evidence bundle 中。MCP 和工具导出中的文本始终作为分析数据。

本阶段已回答这两条机制的关键客户端结构;未验证的模型与运行时部分保持明确边界,可为统一产品的独立实现与验收提供依据。