Coding Harness 上下文处理方案深度调研报告

DSH 事务性压缩族 + 缓存对齐的摘要请求

模块地图

packages/compaction/ 下五个可独立发布的包：compaction（核心类型：checkpoint、tool-pairing）、compaction-basic（摘要引擎）、command-compact（/compact 命令）、compaction-tool-result-pruner（工具结果裁剪）、compaction-image-offload（图片预算）。另有 packages/context/ 注入族：agent-instructions（指令摘要 digest）、file-reference（文件引用语法）、time-context（请求时区）、session-reference。

触发

• 压力比 thresholdRatio 默认 0.8（请求压力占上下文窗口比例）；余量 headroomTokens 默认 65,536（同时作为 maxTokens 上限）；逐字保留尾部比例 retainRatio 默认 0.16（compaction-basic/src/config.ts）。
• 支持按 provider/model 路由的精确覆盖（modelPolicies）：不同模型可配不同的摘要 provider、模型、重试次数（compactionRetries、maxOverflowRetries）。
• 配置在加载期校验并 deepFreeze 冻结（不可变原则贯穿全仓）。

算法

• 事务性压缩（region.ts，600 行）：selectCompactableRange 选范围 → validateSurfaceRegion 校验 → prepareCompaction/summarizeCompaction 摘要 → assertWholeSurfaceUnchanged 乐观并发断言（整个界面区间在摘要期间未被改动）→ commitCompactionBody 提交 → completeCompaction。任何阶段失败可整体回滚。
• 缓存对齐摘要请求（summarizer.ts，标志性设计）：摘要指令不是独立的系统提示，而是作为回放对话之后的最后一条 user 消息发出——前置的 system prompt、工具 schema、消息前缀逐字复现末次路由请求，使辅助调用成为该请求的真正前缀，直接命中 provider 的 KV 缓存而非重建。
• 结构化摘要：固定 8 段（Primary Request and Intent / Key Technical Concepts / Files and Code / Errors and Fixes / Pending Jobs / Current Work / Next Step / Critical Context），空段必须写 “(none)” 不得省略；若历史中已有 <compacted-summary> 旧检查点，则合并而非复制（保留仍属实的事实、丢弃过时信息）。
• 工具结果裁剪（pruner）：超过 thresholdChars=8192 的结果只保留头 headChars=4096 + 尾 tailChars=1024，中间替换为标记 [... tool result middle pruned ...]；按 codePoint 长度计算（Unicode 安全）。
• 图片 offload：记录“省略最旧保留图片出现位置”的决策，将超限旧图替换为“附件名 + 只读路径”文本占位，跨 route/resume/replay 保持一致，且不消耗 provider 重试预算。

状态与持久化

压缩作为 SessionEvent 日志中的条目落地（append-only 事件溯源），压缩后由 deriveMessages 从日志派生消息视图；replay/fork 用旧日志播种。快照覆盖全 profile：snapshots/session/compaction-output-reserve、snapshots/sdk/manual-compact、snapshots/acp/image-compaction。

配置

compaction.basic.{thresholdRatio, headroomTokens, retainRatio, retainTokens, summarizationProvider, summarizationModel, maxTokens, compactionRetries, maxOverflowRetries, auto, modelPolicies}。

近期更新

• cf7229e72a（10-22）超大摘要用更小前缀重试 → 10-23 被 3081c71bab revert，随后补文档说明重试成本与溢出恢复契约（dd87277afa、595f5a65f3）。
• eb1713f856（#7754）修复 checkpoint 中 released units 的保留问题。
• 10 月多份文档澄清压缩溢出恢复契约（cd6187f901、7ee39638b2）。

codex 三模式压缩：本地摘要 / 服务端原生 / 窗口重置

模块地图

core/src/：compact.rs（930 行，本地摘要主流程）、compact_token_budget.rs（窗口重置）、compact_remote_v2*.rs（服务端原生压缩，含 attempt/installation/media）、compact_retained_tool_outputs.rs、compact_model_fallback.rs、context/、context_manager/；独立 crate context-fragments（可注入片段体系）、rollout/src/compression（会话文件压缩）；prompts/templates/compact/{prompt.md, summary_prefix.md}。

触发

• 主阈值 model_auto_compact_token_limit：无显式配置时取模型目录值且被 min 到上下文窗口×9/10；作用域可选 total 或 body_after_prefix（只计压缩窗口 prefix 之后的新增 token）。
• 回合末阈值 model_post_turn_compact_threshold_percent（缺省禁用）。
• 远程/本地分流看 provider 能力 remote_compaction：OpenAI/Azure、Bedrock、GCP 为 V2（服务端原生压缩），其余 Unsupported → 本地摘要。
• 异步后台压缩（feature async_compaction）在窗口 65% 即启动后台摘要；TokenBudget feature 开启时改为直接开新窗口不摘要。
• 手动 /compact 与自动共用 CompactTask 三分支；PreTurn 在模型切换致缩窗时触发（reason=ModelDownshift）。

算法（本地摘要）

• 把全历史 + 摘要 prompt（prompt.md：为接手模型写 handoff summary，含进展与关键决策、重要上下文/约束/用户偏好、剩余工作、关键数据）发给模型；prompt 可经 compact_prompt 配置替换。
• 保留：真实用户消息按预算从新到旧保留（上限 COMPACT_USER_MESSAGE_MAX_TOKENS=20,000，超出转带标记的截断）；客户端标记的 retained tool outputs；canonical 初始上下文重新注入到最后一条真实用户/摘要消息之前；World State 基线。
• 丢弃：assistant 消息、工具调用/输出（除 retained）、developer/system 消息、旧摘要。摘要以 SUMMARY_PREFIX（“Another language model started to solve this problem…”）编码为 user 角色的 CompactionSummary。
• ContextWindowExceeded 时从头部删最旧 item 重试以保前缀缓存；压缩失败保留原历史（400f2356d）。

算法（remote v2）

• 客户端发全历史 + 尾部 CompactionTrigger，服务端必须返回恰好一个 Compaction item，客户端只安装 checkpoint（prefix 策略）。
• 保留预算 RETAINED_MESSAGE_TOKEN_BUDGET=64,000：user 消息、hook prompt、≤10,000 token 的 agent 消息、客户端 developer 消息、retained tool outputs；newest-first 截断。
• retained tool outputs = 客户端 author 的、无 call_id 的具名输出（FunctionCallOutput{call_id:None, name:Some}），整体保留或整条丢弃；超窗工具输出被替换为 “Output exceeded the available model context and was truncated”。
• 媒体预算：resize 图按 7373 bytes、原文件图按 10000 patches、inline 按 URL 计费；媒体按消息边界整体保留/丢弃且 newest-first，不回填旧消息。
• 便宜模型回退：先前模型压缩失败且当前模型为 OpenAI 时，用当前模型重试（遥测 codex.compaction.model_fallback）；压缩请求 reasoning effort=Compaction。
• 后台推测执行：快照历史 → 后台跑压缩 → turn 内 checkpoint 复用（9e03960cf 接入 turn 生命周期）；安装时校验 prefix 的 history_version/auth_owner_generation，拼接 live suffix，拒绝则回退前台。

状态与持久化

replace_compacted_history 原子替换内存历史并写 RolloutItem::Compacted：message、完整 replacement_history、guardian_history、retained_context、window_number/ids、compaction_response_id、latest_token_usage_record、resume_metadata（拒绝音频文件、动态工具、多 agent 版本等）。不可逆（原始历史被替换）但 replacement_history 整体留存，resume 时选最新可回放的压缩作为基线；fork/resume 继承压缩窗口并保留 reasoning token 计数（c62e9df39）。全程有 pre/post compact hooks 与 ContextCompaction turn item，保证分析事件一致。

配置

model_auto_compact_token_limit(+scope)、model_post_turn_compact_threshold_percent、compact_prompt、experimental_compact_prompt_file；features：token_budget、async_compaction（默认 65%）、CompactionImageBudget、RetainClientToolOutputs、RetainClientDeveloperMessages。

近期更新（8-11 月，245 次触及本批文件）

• 11-04 19438adcb 专用 context window ID 类型；1685f2d62 上传音频按实测时长计费。
• 11-03 3780a5f75 压缩中给保留文件音频计费；f1b0721c8 上传音频持久化拒绝恢复。
• 11-02 WebSocket↔HTTP fallback 会话级保持与压缩传输恢复（446044992）；压缩后允许 volatile World State section 刷新（2fa67f03f）。
• 10-28 resume/fork 保留 reasoning token 计数（c62e9df39）；10-27 不可用图片引用替换（cb66dbecf）。
• 10-14 400f2356d 压缩失败保留会话历史；10-20 改善压缩 rollout 读取失败诊断。
• 10-13 后台压缩接入 turn 生命周期（9e03960cf）+ 推测性 remote v2 基础设施（1a69ad323）。
• 10-10 保留 client 标记的 tool outputs（6c0c6759d）；08-12 远程压缩后丢弃 descendant progress 更新、保留 client developer messages（bff03ecce）。

pi 轮次边界压缩 + split-turn 双摘要 + 分支摘要

模块地图

packages/coding-agent/src/core/compaction/：compaction.ts（1104 行，主逻辑）、branch-summarization.ts（会话树分支摘要）、utils.ts（序列化/文件聚合）；token 计数在 packages/ai（catalog 提供模型窗口）。durable 会话的压缩状态迁至 pi-durable（原 packages/agent/src/harness/compaction 已于 10-01 7fd478a2 移除）。

触发

• 判据：contextTokens > model.contextWindow − reserveTokens；reserveTokens 默认 16,384，逐字保留 keepRecentTokens 默认 20,000（settings-defaults.ts）。
• token 估算：优先用最近一条合法 assistant 回复的 usage.totalTokens（含 cache 计数），尾部新增消息用 chars/4 保守估算。
• 两条自动路径：下次 assistant 响应前（_exceedsCompactionThreshold）；轮次结束后（_checkCompaction，含溢出恢复：上下文溢出错误 → 省略式恢复 → 按 “overflow” 压缩）。手动 AgentSession.compact() 先中止当前操作且不重试。
• 支持 compaction.modelOverrides["provider/id"] 逐模型覆盖（含压缩专用模型）。

算法

• 切点纪律：从最新往回累加估算 token 至 ≥ keepRecentTokens；切点只允许落在 user/assistant/turn-start 消息边界，绝不切 toolResult；尾部工具结果超预算时回退到其前的 assistant 边界（8bdcd449 #9740）。
• split-turn：切点落在回合中部时，对该回合前缀单独生成 turn-prefix 摘要，与主摘要用分隔符合并；/compact 自定义指令同时作用于两段（adfc1446）。
• 迭代合并：有 previousSummary 时用 UPDATE prompt 合并而非重写。
• 摘要固定结构：Goal / Constraints / Progress / Key Decisions / Next Steps / Critical Context；序列化时工具结果截断 2000 字符、thinking 省略；文件操作聚合成 <read-files>/<modified-files> 附录（utils.ts）。
• 分支摘要（branch-summarization.ts）：会话树导航离开某分支时，把 old leaf 到公共祖先之间的分支条目总结成 branch_summary 条目，预算 = contextWindow − 16384，优先保留摘要类条目。

状态与持久化

压缩结果作为 compaction 条目 append 进 jsonl 会话文件：summary、firstKeptEntryId、tokensBefore、details{readFiles,modifiedFiles}、usage、边界处完整 systemMessage。投影规则：上下文 = [最新 compaction 条目，firstKeptEntryId 起原文，之后全部条目]。fork 复制全部条目（含 compaction）→ 压缩在 fork 后存活。生成失败（stopReason=length/error）拒绝落盘（97fa14e3）。扩展钩子：session_before_compact（可取消/供结果）、session_compact、session_compact_failed。

配置

compaction.{enabled, reserveTokens, keepRecentTokens, modelOverrides}；branchSummary.{reserveTokens, skipPrompt}。

近期更新

• d0fe2130（#11680）context edits 进分支摘要输入；269afc66（#11482）分支摘要传 thinking level。
• 6fcb4867（#11036）摘要请求去除固定输出上限；90305d90摘要期禁用工具；15e7bdc1摘要省略 thinking。
• cache-friendly 原语（cff1cf52，8-18）已被 8dab7028 revert——缓存对齐的收益不足以抵消复杂度（行业里少见的“加了又退”样本）。

ZCode 双层压缩（microcompact → 完整）+ 四阶段执行模型

模块地图

apps/zcode-cli/packages/core/src/compact/：policy.ts（触发策略）、microcompact.ts（轻量层）、rounds.ts（轮次分组）、manual.ts（手动流程）、prompt.ts（摘要 prompt）、compact-active.ts（运行时编排）；契约在 contracts/src/compact/；事件在 contracts/src/events/session.events.ts；设计文档 docs/design/v2/compact/ + rewind-compact.md。

触发（policy.ts）

• 默认上下文窗口 200,000；有效窗口 = 窗口 − 输出预留（min(maxOutput, 32k)，preflight 策略上限 21k）；阈值 = 有效窗口 − 13,000 buffer（注释明确：provider 窗口 input+output 共享，只能让出输入侧）。
• token 来源优先 provider 真实 usage（base + cacheRead/Write + contextUsage + incremental + output），无 usage 时本地 chars/3 估算（覆盖正文+reasoning+toolCall name+JSON input）。
• 决策 reason 五态：disabled / not_enough_messages / circuit_breaker（连续失败 3 次熔断）/ below_threshold / above_threshold。
• microcompact：阈值 = min(完整阈值×0.9, 完整−2000)；触发 = 时间驱动（idle > 60 分钟）或 token 压力；清理旧的可压缩工具结果（Read/Bash/Grep/Glob/WebFetch/WebSearch/Edit/Write/ApplyPatch），保留最近 5 个，至少省 256 token 才生效；媒体内容与已清理内容跳过；只改内存投影、写 microcompact_boundary 观测事件、不产生完整 boundary。

算法

• 四阶段（CompactPhase × CompactReason）：standalone_turn+user_requested（手动 /compact）；pre_request+context_limit（turn 首个 model 请求前）；mid_turn+context_limit（同 turn 工具批次后的下一次请求前）；reactive+provider_overflow（主请求溢出后的压缩重试，成功后原请求重放）。
• rounds 分组：groupByAssistantStartedRounds 按 assistant 消息 id 变化切轮次；自动/响应式保留最近若干组原文（基础 1 组），其余进摘要；minimumGroupsToPreserve 可配。
• prompt：强制纯文本输出（preamble/trailer “Respond with TEXT ONLY”）；<analysis> + <summary> 两段；9 段式（Primary Request / Key Technical Concepts / Files and Code / Errors / Problem Solving / All user messages（含反归属声明：模型生成的伪 user 轮不得归为用户）/ Pending / Current Work / Optional Next Step）；安全约束须逐字保留。格式器剥离 analysis、抽取 summary；续写消息附 transcript 路径、REPL 状态、preserved-segment 尾注。
• 手动路径：turn kind=compact、inputVisibility=model-only（v4 投影不渲染成用户气泡）；历史不足时健康 no-op；自动路径最多 3 次尝试，中间失败发 retrying 时间线事件；rapid-refill 熔断（不足 3 个 tool turn 内连续 3 次快速回填即熔断）。

状态与持久化

append-only 会话事件：CompactStarted / CompactCompleted / CompactBoundary / MicrocompactBoundary；boundary payload 含 trigger/phase/reason/压缩前后 token 计数/preservedSegment/summaryMessageIds。原子写 bundle（摘要消息 user 角色 + compaction part，顺序=请求前公告→summary→附件），仅摘要成功才写；resume 从最近 boundary 后水合；事件存储对 turn-window 淘汰（封存 turn 的 model_request 瘦身为只留 messageCount）。

与 rewind/fork 的关系

active chain 从 compact boundary 开始；conversation rewind 只在 boundary 之后合法；compact 前的 file checkpoint 可做 file-only rewind 并标 covered_by_compact；回到 compact 前的对话点用 fork（append-only 分支切割）；partial compact 记 preservedSegment{head/anchor/tailMessageId} 且不得拆 tool_use/result 对。

配置

AgentRuntimeConfig.compact.{enabled, contextWindow, maxOutputTokens, modelContextBudgetStrategy(legacy|preflight-v1), summaryReserveTokens, bufferTokens, thresholdPercentOverride, maxConsecutiveFailures, microcompact{enabled, thresholdTokens, idleThresholdMinutes, keepRecentToolResults, compactableToolNames, clearErrorResults, minTokenSavings}}。

近期更新（均为 sync 提交）

• a9fe401e（v3.17.2，11-03）：子会话不再收到主会话的五阶段 plan 提醒（compact-active 调整）。
• 0a1fc56d（10-19）：摘要请求的工具候选按 ToolSearch/registry 能力过滤，防 MCP schema 撑爆摘要请求；compact-persistence 重写。
• a60ba6a7（10-30）：rewind-compact 文档 + session-store compact bundle 测试；aac47556（v3.15.1）：compact/README、plan、e2e 文档与 e2e 用例（断言 manual=standalone_turn/toolCount=0、auto=mid_turn、microcompact 占位符且不产生 full boundary、reactive 带 reason=provider_overflow）。

opencode 拒绝恢复阶梯 + 后台预压缩 + native 通道

模块地图

packages/core/src/session/compaction.ts（1246 行，核心）；触发点在 session/runner/llm.ts；配置在 config/plugin/compaction.ts；测试 test/session-runner.test.ts。

触发

• 三类 Trigger：auto（每 step 前 estimatePrompt ≥ ceiling）、overflow（provider 拒绝后一次性恢复）、manual（/compact）。
• ceiling = window − buffer；compaction.buffer 支持百分比（"1%"–"99%"，6700dd87b）或整数 token（旧键 reserved 经 normalize 迁移），默认留 max(15% 窗口, 16k)；窗口未知 → ceiling=Infinity，auto 永不触发（只靠 overflow 恢复）。
• 后台预压缩（experimental.background_compaction）：达 ceiling×0.85（PRECOMPUTE_RATIO）且实测 ≥64k 时在后台摘要 anchor 前全部历史；压缩到期直接换入以复用 prompt 缓存；每 session 一份，失败 2 次停止到下次压缩。

算法

• 切分：splitConversation 按 keep（默认 15k tokens）切出逐字尾部，其余整段发模型；7 段模板（Objective / Requirements / Decisions / Work State / Next Move / Relevant Files / Important Context）；instruction 类内容（AGENTS.md 等）明确排除、下轮单独给。
• 发送降级阶梯（flattenAndDropOldest）：原样发（保缓存）→ 整段 → 工具输出截断 → 输出移除+输入截断 → 只留 user 文本 → 省略；头尾各 2000 字符 clip，最新 exchange 永不省略。
• 拒绝恢复阶梯（6597f6cd6）：被拒请求按 SHRINK_STEPS [0.85, 0.7, 0.5, 0.35] 对首次被拒尺寸逐级降 target 并从零重截；measured 请求被拒后只以纯文本重发；payload-too-large 转文本一次不计步。
• native 通道：model.compaction.type==="native" 走 provider 原生压缩机制，保留最近 keep 的整条 user 消息；native 窗口仅原 provider 可回放。

状态与持久化

结果持久化为 type=compaction 消息（completed/failed + text + metadata.keepID）；历史从最新 compaction 加载，previousCompaction 恒为第一条；进程重启靠 settleStaleCompactions 结算孤儿 running 行。后台摘要存内存 Map（firstID/keepID/tailLimit/failures），模型或指令变化即失效。事件 Compaction.Started/Delta/Ended/Failed 广播；失败/中断照常计费（spent map）。

配置

compaction.auto（默认 true）、compaction.keep.tokens（15k）、compaction.buffer、experimental.background_compaction；旧键 tail_turns/prune 被拒绝。

近期更新

• 6700dd87b buffer 支持百分比配置；cb1e58fe4 prompt 大小封顶（fitOutput 压 maxTokens，floor 32k）。
• 6a5973d26（后改名 f523f7713）后台预压缩上线。
• 6597f6cd6 拒绝后不原样重发、逐级降尺寸重截。

goose 结构化 JSON 摘要 + 价格护栏 + 双可见性冻结

模块地图

独立 crate crates/goose-context-management/：lib.rs（三层 API）、summarize.rs、structured.rs（484 行，结构化解析）、format.rs、provider.rs（CompactingProvider）、model.rs（CompactionModel/TokenEstimator）、templates.rs、prompts/compaction.md；触发在 crates/goose/src/context_mgmt/mod.rs 与 agents/state_machine/proactive_compaction.rs。

触发

• proactive：下次推理前比较 session.usage.total_tokens（+未上报工具结果）或全量估算 / context_limit > threshold；assistant 结尾（无后续推理）跳过。
• threshold = min(GOOSE_AUTO_COMPACT_THRESHOLD 默认 0.8, GOOSE_AUTO_COMPACT_TOKEN_LIMIT 225,000 / context_limit)。225k 是价格护栏：刻意低于 OpenAI 272k 长上下文价格档（cd1da62a），是成本边界不是请求上限。
• reactive：尾部 ContextLengthExceeded；同一上下文错误 >2 次（MAX_CONTEXT_ERROR_COMPACTIONS）不再自动压。manages_own_context 的 provider（claude_code/gemini_cli）整体跳过。

算法

• agent 可见消息（剔除 turn-context 事件）经 format_message_for_compacting 扁平为 [role]: 文本（图片/文档/工具调用降级为短标记，Thinking 丢弃）。
• 摘要 prompt（compaction.md）：<analysis> 草稿（会被丢弃，仅作清单）+ 恰好一个 JSON block，10 字段：user_intent / technical_concepts / files[{path, summary, key_code}] / errors_and_fixes / problem_solving / user_messages / pending_tasks / current_work / next_step。
• prompt 明确“摘要只给模型读、可以比给人看的摘要长得多，把全部长度预算花在 JSON 字段上，逐字引用”；错误消息/panic 文本/测试输出须逐字引用；不编造新想法（No new ideas unless user confirmed）。
• lenient 解析（对象/数字自动 stringify、未知字段 flatten 保留）；解析失败或全空 → 原始文本无损保留。摘要器自身溢出：REMOVAL_PERCENTAGES [0,10,20,50,100] 从中间向外删 tool response 重试；无 tool response 直接 fast-fail 报错。
• CompactingProvider 包装任意 provider：遇 ContextLengthExceeded 自动压缩并以单条摘要重试一次。

状态与持久化

原消息 → user_visible=false & agent_visible=false（冻结）；摘要消息 agent-only + compaction_summary 标记；追加 assistant continuation（“Your context was compacted…”，普通/工具循环/手动三文案）。保留最近一条纯文本 user 消息逐字（手动压缩不保留）；当前 turn 的 turn-context 事件 carry 到最后且 created 时间戳重置（防持久化重排）。可见性投影：用户可见存档保留原 audience 注释，agent 回放去掉 user-only 内容。

配置

GOOSE_AUTO_COMPACT_THRESHOLD（0.8）、GOOSE_AUTO_COMPACT_TOKEN_LIMIT（225,000）、GOOSE_TOOL_PAIR_SUMMARIZATION（默认 false）、GOOSE_TOOL_CALL_CUTOFF；摘要模板可被用户 ~/.config/goose/prompts/ 覆盖；Python/Kotlin 经 uniffi 复用。

近期更新

• cd1da62a 225k 封顶（价格护栏落地）；0aa212e6 可选 context relevance 操作；c85a58d7 ACP 手动压缩失败上报；7f57d569 不向模型暴露压缩倒计时。

gemini-cli 新旧双路径 + 工具输出三件套（掩码/蒸馏/归一化）

模块地图

packages/core/src/context/：传统路径 chatCompressionService.ts（721 行）；新架构 contextManager.ts + pipeline 图 + profiles；工具输出三件套 toolOutputMaskingService.ts、toolDistillationService.ts、agentHistoryProvider.ts；状态缓存 compression_state.json 配套 contextCompressionService.ts。

触发（新旧两条路径并存）

• 传统路径：compressionThreshold 默认 0.5×tokenLimit(model)；findCompressSplitPoint 按 JSON 字符占比 0.7 找切点（1−COMPRESSION_PRESERVE_THRESHOLD 0.3，保护最近 30%）；上次失败后只做截断不再调 LLM。
• 新架构：generalistProfile budget maxTokens 150k / retainedTokens 65k，gcStrategy=incremental；currentTokens > retainedTokens 时按 age-out 分级（retained→normalized），coalescingThresholdTokens 迟滞防抖。
• 三模式：incremental（每次只处理最老必需节点，“minimum viable chunk, oldest 2 nodes”；stateSnapshotProcessor 为时点快照，max=accumulate 累积）；hotstart（首次渲染后用真实 countTokens 校准估算器，一次性）；barrier（render 前 await pipelines，view>maxTokens 触发同步 GC backstop，保证发出的请求不超窗）。

算法

• 传统摘要：state_snapshot 两阶段——先生成再 probe 验证自我纠正；新 token 数反而更大则 COMPRESSION_FAILED_INFLATED_TOKEN_COUNT 放弃；anchorInstruction 处理已有快照的整合。
• 掩码（masking）：混合反向扫描 FIFO——protectionThresholdTokens 50k 保护窗 + protectLatestTurn；越窗后累计可掩码 > minPrunableThresholdTokens 30k 才批量触发（约 80k 工具 token 起步）；完整输出写 tool-outputs/session-*/ 文件，原位换 <tool_output_masked> 预览（shell 保留 Error/Exit Code 段）；EXEMPT_TOOLS 永不掩码。
• 蒸馏（distillation）：单输出 > maxOutputTokens×4 字符时——存盘 + 结构截断（头 20%/尾）+ 可选 intent summary（独立模型，15s 超时，只抽错误/路径/结论 <10 行）；read_file 豁免。
• 消息级归一化（agentHistoryProvider）：normalMaxTokens 2500 / retainedMaxTokens 12000，高水位截断旧消息+摘要，边界不破坏 functionCall/Response 配对。

状态与持久化

compression_state.json 按文件路径缓存 FileRecord（level FULL/PARTIAL/SUMMARY/EXCLUDED + contentHash，内容变即失效），批量一次路由调用（chat-compression-2.5-flash-lite）决策；掩码产物按 session 隔离落盘；压缩 telemetry 事件记录 tokens/masked_count。

配置

compressionThreshold；contextManagement.{enabled, historyWindow.{maxTokens,retainedTokens}, messageLimits, tools.distillation.{maxOutputTokens,summarizationThresholdTokens}, tools.outputMasking.*}。

近期更新

• e6f92d6 大简化；01635dd loose boundary（屏障 backstop）；bedef96 工具输出体积上界；055e5f6 跨会话快照恢复；07792f9 自适应 token 计算器。

mcode 分层阶梯压缩（归档→裁剪→checkpoint）+ 可恢复收据

模块地图

packages/local-runtime-v2/src/service/turn-system/compaction/：automatic-context-compactor.ts（507 行，触发）、contracts.ts；algorithm/：compact-context.ts（991 行）、history-reduction.ts、tool-result-archiver.ts（783 行）、tool-trim-admission.ts、checkpoint-protocol.ts、checkpoint-format.ts、assistant-iteration-cadence.ts、todo-cadence.py、background-cadence.ts；execution/request-media-projection.ts；状态在 agent-host/compaction/。

触发

• probeBeforeLlm 每次 LLM 调用前执行；footprint=本地估算（inputTokens + 序列化字节，usageAnchor 进程级缓存最近实测，压缩后 invalidate 防旧值误导）。
• providerInputLimit = min(0.95×窗口, 窗口−16384, 窗口−outputFloor−2048)；automaticTriggerAt = min(providerInputLimit, (窗口−min(output, 窗口/4))×0.95)。
• contextManagement.compactionTriggerAt（a79348f #493）：(0,1] 比例或 >1 整数 token，每次调用读取，只能降低内置触发（单调语义）；非法值 warn 一次后忽略。
• provider 拒绝 → 无条件压缩：prefixCached 模型直接 llm_checkpoint（保图片字节一致），否则先归档工具输出+全部图片（archiveImages 是 recovery 专属，触发性压缩不动图片）。

算法

• 分层决策：tool_archive（可恢复归档）→ tool_trim（legacy 保留 30%，生产禁用）→ llm_checkpoint；准入（tool-trim-admission）要求实测 footprint 真减小且 ≤ providerInputLimit。
• checkpoint 候选阶梯（从大到小）：h0 原始 → htrim（归档后）→ hall（全部工具结果移除）→ hvideo（去附件）→ hmid（middle-out 删中间，保护 closure 0 + 含 user 的 closure）→ hmin（仅最近真实 user query）；逐档 fits 检查，provider error 原地重试一次，媒体拒绝走 attachment-free 阶梯。
• checkpoint prompt：8 段 markdown（Goal / Constraints / Completed Work / Current State / Blockers / Key Decisions / Pending User Asks / Critical Context）；标题从 prompt 尾部解析防漂移；历史视为不可信数据；recentUserQueries 逐字附在版本化 appendix 外。
• 工具结果归档：watermark 256KiB 总文本、单条 ≥2KiB、估计/实际节省 ≥256KiB、keepRecentRounds 5；控制工具（skill/todowrite/plan 等）豁免；receipt 含工具名/来源（grep pattern+path 等）/artifact 引用；无 read 工具时 materializeTrim 破坏性替换且不宣称可恢复。
• cadence：todo/background 提醒按 15 次 assistant 迭代节奏，从历史重放投影。
• 媒体投影：非 prefixCached 模型按 image 上限 + 请求体字节份额把超额图片换占位文本；占位不进持久历史；prefixCached 保持全图不动。

状态与持久化

压缩 = canonical history replaceMessages 操作（attemptId/compactionId 幂等，克隆消息）；结果附 CompactionCompatibility v5 appendix（summary + recentUserQueries + todoState + cadence + subagents）。session-id 恢复（c460f08 #466）：session_identity_reminder 在压缩丢 id 后重新注入；近期提交移除了拒绝后强制重发（绕过 before-LLM 管线导致截图上限/session-id 未重放）。

配置

contextManagement.{compactionTriggerAt, disableSystemReminderModels, cuMaxScreenshotsInContext: 2}；toolResultCompaction.{enabled, maxInlineKiB: 64, mcpDetailsMaxInlineKiB: 32, watermarkKiB: 256, minSavingsKiB: 256, minCandidateKiB: 2, keepRecentRounds: 5}；requestMedia.*。

近期更新

• a79348f compactionTriggerAt 单调语义；c460f08 session-id 恢复 + 移除强制溢出压缩。
• 5b4e0a4 oversized 重发改走正常恢复；1852771 图片上限与恢复；3123293 用量失效防误导；698a986 同步 MiniMax 0.7.2。