Compaction Debugger

compaction-debugger 是一个原生 OpenClaw context-engine 插件，并且自带一组 围绕预处理、compaction、调优、回归和发布检查的 skill。

一句话介绍：

• 它会在长对话里帮模型少看废话、多看重点

这是什么

这是一个帮 OpenClaw 在每轮对话前“整理上下文”的插件。

它不会把你所有历史都原样塞给模型，而是优先做这些事：

• 把较早的聊天内容压成更短的摘要
• 保留最近几轮对话原样
• 丢掉一部分没什么价值的旧内容，比如早期的短确认回复、旧 reasoning、旧工具噪音
• 当上下文已经非常接近模型窗口上限时，自动触发一次真正的 /compact

如果只用一句话介绍它：

• 它是一个“让模型少看废话、多看重点”的插件

它对普通用户有什么用

最直接的作用有 3 个：

1. 长对话里更容易省下一部分上下文 token
2. 模型更容易把注意力放在最近任务和关键事实上
3. 在上下文压力过高时，能自动帮你触发正式压缩

适合的场景：

• 你经常连续聊很多轮
• 会话里有很多工具输出、确认回复、过程性内容
• 你想让模型在长对话里更稳定一些

不适合期待的效果：

• 不是装上就每轮大幅省 token
• 不是长期记忆插件
• 不是“永远不忘”的无损上下文系统
• 不是完全替代 OpenClaw 官方 compaction 的新压缩器

它到底能不能省 token

能，但收益取决于你的对话是不是已经够长、够乱。

通常来说：

• 短对话：收益不明显，甚至可能不会触发摘要
• 长对话：收益会开始明显
• 旧工具输出多、旧 reasoning 多、旧 ACK 多：收益更明显

它节省的是：

• 每轮真正发给模型的上下文 token

它不直接保证：

• 立刻把整个 session 文件变短
• 每次都比原始上下文省很多

当前实现还有一个保护逻辑：

• 如果摘要做出来反而比原文更长，这轮就不会用摘要

所以这个插件不是“强行压”，而是“值得压时才压”。

它会不会影响模型回答

会。

因为模型看到的内容已经不是完整原始聊天记录，而是这个插件整理后的版本。

你可以这样理解：

• 旧内容会被压短
• 最近内容会保留
• 噪音会被删掉
• 重点会被尽量留下

这样做的好处是：

• 模型更容易聚焦当前问题
• 长对话里不容易被无关旧内容拖累

这样做的代价是：

• 模型看到的是“整理后的上下文”，不是逐字逐句的原始历史

所以它更像一个“会前整理资料”的助手，而不是一个“完整档案管理员”。

它已经实现了什么

当前版本已经有这些功能：

• 每轮对话前自动整理上下文
• 把较早消息压成摘要
• 保留最近消息原样
• 默认清理旧 reasoning、旧短 ACK、旧工具噪音
• 按上下文占用比例决定压缩强度
• 在非常接近窗口上限时自动触发正式 compaction
• 记录预处理和 compaction 前后的日志
• 自带一组查看、审计、调参、回归、发布辅助技能

它还没有实现什么

当前版本还没有做这些事：

• 自己生成官方那种正式 compaction summary
• 完全替换 OpenClaw 内置 compaction runtime
• 主动从外部记忆库或 RAG 拉上下文
• 把整个 transcript 永久改写成自己的结构

所以最准确的定位是：

• 平时是上下文整理器
• 高压时是自动 compaction 触发器
• 全程是日志和诊断记录器

内置 Skills

当前插件内置以下 skill：

• compaction-viewer
  • 查看和分析预处理与 compaction 日志
• compaction-audit
  • 审计某个 session 的预处理和 compaction 行为
• compaction-explainer
  • 用通俗语言解释插件预处理和官方 compaction 的区别
• token-report
  • 汇总 token 估算和节省量
• compaction-tuner
  • 根据日志给出参数调优建议
• context-threshold-advisor
  • 设计按上下文窗口占用率工作的 50% / 85% / 95% 阈值策略
• fact-viewer
  • 查看当前摘要和上下文里保留了哪些事实、目标、约束和标记词
• session-memory-inspector
  • 检查某个 session 当前还保留着哪些“可供 Pi 使用的记忆”
• context-regression-check
  • 做一轮标准回归检查，确认预处理、真实 /compact 和 recall 都正常
• plugin-package-check
  • 在发布到 ClawHub 或公开仓库前做打包检查
• clawhub-release-helper
  • 整理 ClawHub 上传前的发布步骤和检查点

建议分工：

• 想看“发生了什么”：用 compaction-viewer 或 compaction-audit
• 想把机制讲清楚：用 compaction-explainer
• 想看“省了多少 token”：用 token-report
• 想调参数：用 compaction-tuner
• 想按窗口比例设计压缩策略：用 context-threshold-advisor
• 想看“Pi 现在还记得什么”：用 fact-viewer
• 想看 session 当前还剩哪些记忆：用 session-memory-inspector
• 想做回归：用 context-regression-check
• 想准备发布：用 plugin-package-check 或 clawhub-release-helper

默认行为

这个插件有三个主要职责：

1. assemble() 在 Pi 开始运行前重写消息列表。较早的非 system 消息会在“确实比原始上下文更短” 的前提下，被压成一条合成 assistant 摘要；最近消息保持原样。当前版本还会根据 estimatedTokens / tokenBudget 按上下文窗口占用率分层决定压缩强度。
2. compact() 当前版本还没有自定义 compaction 算法，而是通过 delegateCompactionToRuntime(...) 委托给 OpenClaw 内置 runtime，同时继续记录 before-compaction-* 和 after-compaction-* 诊断日志。
3. afterTurn() 当上下文占用率进入 emergency 档位时，插件会在回合结束后自动触发一次真正的 runtime compaction，并通过冷却时间避免同一 session 反复连续压缩。

如果只看定位，可以把它理解成：

• 平时：预处理器
• 高压时：自动 compaction 触发器
• 全程：诊断记录器

默认配置值：

• keepRecentMessages = 10
• maxSummaryEntries = 24
• summaryCharBudget = 4000
• maxSummaryBullets = 12
• lightCompressionThreshold = 0.5
• heavyCompressionThreshold = 0.85
• emergencyCompressionThreshold = 0.95
• replyReserveRatio = 0.08
• replyReserveMinTokens = 4000
• autoCompactionEnabled = true
• autoCompactionCooldownMs = 600000
• debug = false
• cacheSummaries = true
• dropOldToolMessages = true
• dropTrivialAssistantMessages = true
• prependGuidance = ""

本地启用方式

启用插件，并把它设置为当前活动的 context engine：

{
  "plugins": {
    "entries": {
      "compaction-debugger": {
        "enabled": true,
        "config": {
          "keepRecentMessages": 8,
          "maxSummaryEntries": 20,
          "summaryCharBudget": 2200,
          "maxSummaryBullets": 10,
          "lightCompressionThreshold": 0.5,
          "heavyCompressionThreshold": 0.85,
          "emergencyCompressionThreshold": 0.95,
          "replyReserveRatio": 0.08,
          "replyReserveMinTokens": 4000,
          "autoCompactionEnabled": true,
          "autoCompactionCooldownMs": 600000,
          "autoCompactionInstructions": "Preserve explicit facts, active goals, recent user instructions, exact file paths, IDs, and errors.",
          "debug": true,
          "dropOldToolMessages": true,
          "dropTrivialAssistantMessages": true,
          "prependGuidance": "Compaction Debugger is active. Preserve compacted facts."
        }
      }
    },
    "slots": {
      "contextEngine": "compaction-debugger"
    }
  }
}

然后重启 gateway，使 slot 变更生效。

如果后续从包安装，推荐命令是：

openclaw plugins install clawhub:compaction-debugger

或者：

openclaw plugins install compaction-debugger

实际执行流程

运行链路如下：

1. 用户发送一条普通消息。
2. OpenClaw 读取当前激活的 context-engine slot。
3. compaction-debugger.assemble() 接收到当前 transcript。
4. 较早的非 system 消息会被压成一条合成 assistant 摘要。
5. 最近消息保持原样。
6. Pi 收到的是重写后的消息列表，而不是原始全量 transcript。
7. 如果用户之后发送 /compact，OpenClaw 会把这个 slash command 路由到命令处理器。
8. compaction-debugger 记录 before_compaction。
9. 内置 compaction runtime 通过 delegateCompactionToRuntime(...) 执行真正压缩。
10. compaction-debugger 记录 after_compaction。
11. transcript 中会写入真实的 type:"compaction" 记录，会话继续运行。

按上下文窗口分层压缩

当前版本不再只看“消息条数”，而是优先看：

estimatedTokens / tokenBudget

并按占用率分成 4 档：

• none
  • 低于 lightCompressionThreshold
  • 不做摘要压缩
• light
  • 达到 lightCompressionThreshold
  • 轻度清理旧上下文
• heavy
  • 达到 heavyCompressionThreshold
  • 更激进地压缩旧上下文
• emergency
  • 达到 emergencyCompressionThreshold
  • 进入最激进的 assemble 压缩模式

此外还会检查“回复预留空间”：

replyReserve = max(replyReserveMinTokens, tokenBudget * replyReserveRatio)

如果剩余可用 token 低于这条预留线，插件会把压缩档位再提高一级。

如果某一轮在回合结束后仍然处于 emergency 档位，并且没有处于冷却窗口内，插件还会：

• 自动触发一次真实 runtime compaction
• 使用 autoCompactionInstructions 作为额外压缩提示
• 在同一 session 上等待 autoCompactionCooldownMs 后才允许再次自动触发

以 200000 token 窗口为例：

• 50% 约等于 100000
• 85% 约等于 170000
• 95% 约等于 190000

这意味着：

• 上下文占用在 100000 以下时，通常不做摘要压缩
• 达到 100000 以后开始轻压缩
• 达到 170000 以后进入重压缩
• 达到 190000 以后进入紧急模式

如果你后续要把逻辑继续做深，最自然的方向就是在 emergency 档位之外再直接触发正式 compaction。 当前版本已经做到了这一步。

实际例子

假设对话是：

• 用户：Remember FACT-ALPHA and reply ACK-1
• 用户：Remember FACT-BETA and reply ACK-2
• 用户：Remember FACT-GAMMA and reply ACK-3
• 用户：Remember FACT-DELTA and reply ACK-4

当 keepRecentMessages=4 时，后续某一轮 Pi 不会再收到所有旧消息的完整原文， 而是可能收到类似这样的上下文：

system ...
assistant: Compaction Debugger preprocess summary
assistant: Older condensed messages: 4
assistant: 1. user: Remember FACT-ALPHA and reply ACK-1
assistant: 2. assistant: ACK-1
assistant: 3. user: Remember FACT-BETA and reply ACK-2
assistant: 4. assistant: ACK-2
user: Remember FACT-GAMMA and reply ACK-3
assistant: ACK-3
user: Remember FACT-DELTA and reply ACK-4
assistant: ACK-4

如果这时用户再发送：

/compact Focus on remembered FACT-* items and recent progress.

那么真正的 compaction 摘要仍然由 OpenClaw 内置 runtime 生成，这个插件只是在前后 包一层诊断逻辑。压缩完成后，用户依然可以继续问：

List every remembered FACT-* item in alphabetical order, comma-separated, and nothing else.

Pi 仍然应该能基于 compacted context 给出正确回答。

推荐本地测试流程

建议按下面的顺序做本地验证：

1. 启用插件，并把 plugins.slots.contextEngine 设置为 compaction-debugger。
2. 打开 debug=true。
3. 重启 gateway。
4. 连续发送 4 到 6 轮短消息，内容里最好包含明显标记，比如 FACT-* 或 CODE-*。
5. 通过真实 gateway 聊天链路发送 /compact，不要用 openclaw agent --local 去验证 slash command。
6. 再问一个依赖较早历史内容的 recall 问题。
7. 查看日志，确认预处理和 compaction 都已经触发。

发布到 ClawHub 前

建议在发布前检查这几项：

1. openclaw.plugin.json 的 id、kind、skills 和配置 schema 都已经稳定。
2. package.json 已声明 openclaw.install.npmSpec 和 openclaw.install.minHostVersion。
3. npm pack --dry-run 的结果里只包含真正需要发布的文件。
4. logs/、cache/、临时测试配置和本地备份文件没有进入发布包。
5. README.md 已写清楚：
   • 这个插件做什么
   • 如何启用
   • 如何切换 plugins.slots.contextEngine
   • 自动 compaction 的行为
6. 至少完成一轮真实本地验证：
   • 普通消息预处理
   • 真实 /compact
   • emergency 自动正式 compaction

如果本地已经装好 clawhub CLI，发布命令可以是：

clawhub publish . --slug compaction-debugger --name "Compaction Debugger" --version 1.0.0 --tags latest

如果你准备同时发 npm，则还需要先确认 compaction-debugger 这个包名是否可用。

配置项

• keepRecentMessages：保留多少条最近的非 system 消息不做压缩
• maxSummaryEntries：最多从多少条较早消息中抽取内容生成摘要
• summaryCharBudget：合成摘要的大致字符预算
• maxSummaryBullets：旧上下文摘要中最多保留多少条结构化 bullet
• lightCompressionThreshold：开始进入轻压缩的上下文占用率阈值
• heavyCompressionThreshold：开始进入重压缩的上下文占用率阈值
• emergencyCompressionThreshold：开始进入紧急模式的上下文占用率阈值
• replyReserveRatio：希望为模型回复预留的最小预算比例
• replyReserveMinTokens：无论窗口多大，都至少预留这么多 token 给回复
• autoCompactionEnabled：进入紧急档位后是否自动触发一次真实 compaction
• autoCompactionCooldownMs：同一 session 两次自动 compaction 之间的最短间隔
• autoCompactionInstructions：自动触发正式 compaction 时追加的压缩提示
• debug：设为 true 时会写入额外的 assemble-*.json 诊断日志
• cacheSummaries：如果旧上下文指纹没变化，复用上一次生成的摘要
• dropOldToolMessages：默认忽略旧工具输出，除非其中包含失败信息
• dropTrivialAssistantMessages：默认忽略旧 assistant 的短确认回复，比如 ACK 或 OK
• prependGuidance：每轮 Pi 运行前额外附加的系统提示

日志

日志默认写到：

~/.openclaw/extensions/compaction-debugger/logs

常见文件：

• assemble-*.json when debug=true
• before-compaction-*.json
• after-compaction-*.json

各文件含义：

• assemble-*.json：Pi 经过预处理后实际拿到的上下文
• assemble-*.json 中还会记录 sourceEstimatedTokens、estimatedTokens 和 estimatedTokenSavings
• assemble-*.json 中还会记录 compressionMode、usageRatio、replyReserve
• before-compaction-*.json：compaction 触发前的消息数量和 token 估算
• after-compaction-*.json：compaction 后的 transcript 预览和 token 估算

已知限制

• openclaw agent --local 不会走真实 slash-command 路由，因此不能拿来验证真实 /compact。
• 合成摘要本身是有损的，它的目标是保留工作上下文，不是完整还原原始 transcript。
• 如果配置过于激进，可能会隐藏一些仍然有价值的旧 assistant/tool 上下文。建议先从 keepRecentMessages=8 开始，确认 assemble-*.json 效果后再继续往下调。
• 当前版本的插件仍然是“委托 compaction”，并没有替换 OpenClaw 内置 compaction 总结器。
• 如果周边 OpenClaw 配置启用了无关 channel 或 memory 集成，本地测试 gateway 可能会出现 与本插件无关的警告；这些警告不一定代表插件本身有问题。