企业官网建设流程全解析

Axl 是一款面向开发者的开源 AI 编码助手（终端 + Web 双端），其**上下文压缩（Context Compaction）**机制专门解决超长会话撑爆模型上下文窗口的问题：在保留完整会话日志的前提下，把较早的对话历史总结成一份"续写摘要"，并保证工具调用与工具结果的配对组永不被拆散。本文带你完整理解 Axl 上下文压缩的触发时机、切分规则与可靠性设计。

一、为什么 AI 助手离不开上下文压缩？

AI 助手每发出一轮请求，都要把"系统提示 + 历史对话 + 工具声明"全部塞进模型的上下文窗口。当你在 Axl 里连续调试、反复读写文件，历史消息会快速逼近模型窗口上限。此时有两种选择：

• ❌ 粗暴截断：直接丢弃旧消息。如果恰好丢掉"模型发起工具调用"而留下"工具执行结果"，大多数模型 API 会直接报错，对话从此无法继续。
• ✅ 智能压缩：把旧历史总结成一段结构化的摘要，只替换"模型可见的前缀"，完整会话仍保存在日志里随时可查。

Axl 选择了后者，并且把"不拆散工具调用组"设计成一条硬性不变量，甚至在重放日志时都会校验它是否被违反。

二、Axl 上下文压缩的 3 种触发方式

1. 阈值自动压缩：每次模型请求前检查

守护进程（daemon）在每次向模型发起请求前都会估算输入 token 数，包括工具执行之后的追加请求。满足以下条件即自动压缩：

estimatedInputTokens > contextWindow - reserveTokens

即"剩余空间不足以容纳模型输出"时提前出手。这个判断逻辑非常简洁，见 shouldCompact，主循环中的检查点见 agent-session.ts。

2. 上下文溢出兜底：出错后压缩并重试一次

如果估算乐观、模型提供商仍然在输出任何内容之前报出context_limit错误，Axl 会以overflow理由执行至多一次压缩，然后把原请求原样重试一次。见 agent-session.ts，官方文档说明见 docs/compaction.md。

3. 手动 /compact 命令：想压就压

任何客户端（终端或 Web）都可以输入：

• /compact—— 使用默认策略压缩
• /compact <instructions>—— 附上你的关注点，让摘要聚焦在这些指令上

如果此时 AI 正在回答，请求会被排队，等当前回合及后续跟进完成后再执行；压缩进行中新输入的消息则作为下一个提示词排队，不会污染已冻结的压缩输入。排队逻辑见 session-manager.ts，命令注册见 command-catalog.ts。

三、核心机制：如何切分又不破坏工具调用组？

这是 Axl 上下文压缩最有意思的部分，全部实现集中在 packages/kernel/src/compaction.ts。

1. 第一步：把会话投影成"消息组"

Axl 先把规范事件日志投影成模型可见的消息组（见 projectContext）：

关键设计是：一次助手发言携带的多个工具调用，与它前面的发言被合并为一个整体。这样"调用"和"结果"的配对关系在数据结构层面就可见了。

2. 切分点回退规则：宁可少压，不可拆散

自动压缩时，算法从最新的历史往前累加 token，直到达到keepRecentTokens（默认 20000），以此确定"保留区"和"待压缩区"的边界（prepareCompaction）。随后执行两条保护规则（compaction.ts）：

1. 回退到 assistant：如果保留区的第一个组恰好是一条tool.result，边界会一路向前回退到发出该调用的 assistant 组——绝不把"调用"和"结果"分到摘要和保留区两边。
2. 跨回合单独总结：如果回退后的边界落在一个带工具调用的 assistant 组上，且该组属于较新的用户回合，Axl 不会把整个回合硬塞进摘要，而是把该回合的"前缀"单独做一次简短前缀总结（turnPrefixPrompt），只写清"理解后文所需的最少信息"。

3. 重放校验：完整性是硬性不变量

压缩结果会以context.compacted事件落盘，记录replacedEventIds（被摘要替换掉的事件 ID）。任何后续读取历史时，Axl 会重新投影上下文并校验：

• 一个消息组要么完整隐藏、要么完整可见，绝不允许部分隐藏；
• 被隐藏的组必须构成历史的前缀。

任何违反都会抛出ReplayError（如 "splits a model message group"），见 compaction.ts。换句话说，"工具调用组完整性"不是口头承诺，而是被程序强制验证的协议级保证。

四、总结摘要长什么样？

摘要由模型生成，但 Axl 对它有严格约束：

• 固定章节结构：Goal、Constraints & Preferences、Progress（Done / In Progress / Blocked）、Key Decisions、Next Steps、Critical Context，见 summaryPrompt；
• 必须精确保留继续工作所需的确切文件路径、函数名、命令和错误信息；
• 超长工具结果截断：送入摘要提示的工具结果超过 2000 字符会被截断（compaction.ts），避免摘要请求本身再次溢出；
• 累计文件清单：压缩后摘要末尾自动附加<read-files>和<modified-files>两个区块，是从历史工具调用中统计出的"已读/已改文件清单"，并与上一次压缩的清单累加合并（withFileSections）——这样模型压缩后无需重新读文件就知道自己动过哪些文件；
• 禁止摘要模型调工具：摘要请求强制toolChoice: "none"，模型一旦试图发工具调用会直接报错，见 summarizeText；
• 滚动压缩：多次压缩时，旧摘要会作为<previous-summary>输入新一轮总结，摘要链持续收敛而不是无限膨胀。

五、持久化与可靠性设计

Axl 的完整会话保存在规范 JSONL 日志中，压缩只替换模型可见的前缀，原始消息一条都不删。压缩全生命周期都会被记录为事件：

compaction.queued→compaction.started→context.compacted（成功）/compaction.failed（失败或取消）

一个很克制的细节：守护进程重启后，排队中或进行中的压缩会被直接记为失败，而不是假装"中断的摘要已续上"（docs/compaction.md）。失败的回合保留了压缩失败事件和原始提供商错误，用户随时可以手动/compact重试。

六、如何配置上下文压缩参数？

在~/.axl/settings.json中配置（修改后需重启 daemon），默认值为reserveTokens: 16384、keepRecentTokens: 20000（protocol/src/compaction.ts）：

{ "version": 1, "compaction": { "enabled": true, "reserveTokens": 16384, "keepRecentTokens": 20000, "modelOverrides": { "anthropic/claude-sonnet-4-6": { "reserveTokens": 32768, "keepRecentTokens": 30000 } } } }

三个参数的心智模型：

• reserveTokens：给模型输出预留的 token，越大越早压缩；
• keepRecentTokens：压缩后原样保留的近期历史大小，越大摘要越"失忆"少；
• modelOverrides：按provider/model身份为特定模型单独调参。

另外，自动压缩（非手动）还会做一个自适应收窄：实际保留量取keepRecentTokens与contextWindow - reserveTokens的较小值，防止在小窗口模型上保留区本身就把窗口撑爆，见 agent-session.ts。

七、一句话总结

Axl 的上下文压缩 =阈值预估 + 溢出兜底 + 手动命令三种触发，配合消息组投影、切分点回退、前缀独立总结三招保住工具调用组完整性，再用固定章节摘要、累计文件清单、事件级持久化让长会话压缩后依然"无缝续写"。理解了这套机制，你就能明白为什么 Axl 的超长会话既不报工具配对错误，也不会丢失"我读过、改过哪些文件"的关键记忆。