headroom

Headroom — 便携式 Token 缩减技能

这项技能教会任何编码 Agent 在上下文中应用 Headroom 压缩技术。它不需要 Headroom 二进制文件。

何时应用哪种转换

根据内容类型选择转换方式。如果工具结果少于约 200 个 Token，请跳过压缩——开销不值得。

Agent 即将使用／粘贴的内容	应用	辅助脚本
JSON 字典／对象数组（工具结果、API 响应）	SmartCrusher	scripts/smart_crusher.py
构建／测试日志（pytest、npm、cargo、make）	LogCompressor	scripts/log_compressor.py
grep／ripgrep／ag 输出（file:line:content）	SearchCompressor	scripts/search_compressor.py
源代码（Python、JS、TS、Go、Rust、Java、C/C++）	CodeCompressor	scripts/code_compressor.py
超出上下文预算的对话历史	RollingWindow	scripts/context_manager.py
模型即将写回的任何内容	Output Shaper（L2）	prompts/verbosity_steering.md

七条规则

这些是 Agent 应内化的核心规则。完整说明见 AGENTS.md；以下为简版。

1. 粘贴前先压缩。 在将超过约 200 个 Token 的任何工具结果粘贴到下一条消息前，运行相应的辅助脚本（如果没有脚本，则手动应用相应的启发式规则）。在叙述中注明脚本：“使用 SmartCrusher 将 1,432 → 187 个 Token（保留前 3 项、后 2 项、所有错误，以及按与查询的 BM25 相关度排名前 5 的项）。”
2. 绝不丢弃错误。 错误、堆栈跟踪、is_error: true 结果和 FAILED 行都至关重要。即使进行强力压缩，也始终完整保留它们。
3. 保留前 N 项和后 N 项。 对于数组、日志和搜索结果，始终保留前 3 项和后 2 项。它们能提供分页上下文和时效信息。
4. 稳定前缀。 构建提示词时，确保系统提示词和第一轮用户消息在不同请求间逐字节相同。将动态内容（时间戳、“今天是”、会话 ID）移到提示词的末尾，以保持提供方的 KV 缓存处于热状态。
5. 先丢弃最旧的工具输出。 当对话超出 Token 预算时，从最旧的一端丢弃完整的 tool_call + tool_result 配对。绝不拆分配对。绝不丢弃系统提示词。绝不丢弃最近的 2 轮用户消息。
6. 精简自己的输出。 默认详细程度为 L2：跳过开场白，不要复述屏幕上已有的代码，并用 path:line 引用。用户要求简洁时，降至 L3（仅结论）。绝不复述用户已经能看到的工具结果。
7. 确保可还原。 压缩工具结果时，将原始内容写入 .headroom-cache/<sha256>.txt，并在叙述中附上 SHA：“CCR key：a3f9…”。如果后续轮次需要原始内容，从那里取回。

此处“压缩”的含义

压缩是筛选，而不是打包。我们不会运行 gzip，而是挑选要保留的项目／行／节点，并输出更短的表示形式，同时保留 LLM 回答用户问题所需的信息。原始内容始终可以从 CCR 缓存中取回。

筛选启发式按优先级排序：

1. 错误 — 始终保留。
2. 前 N 项 — 分页／设置上下文。
3. 后 N 项 — 保留近期内容。
4. 异常值 — 数值数组中与均值相差 >2σ 的值，或字段与相邻项差异显著的项目。
5. 相关项 — 根据与用户当前问题的 BM25 相似度选出的前 K 项。
6. 变化点 — 字段值发生转换的项目（状态翻转、计数器重置）。
7. 抽样 — 从其余内容中选取具有统计代表性的样本，让 LLM 仍能感知其分布。

输出 token 控制（“L2 默认级别”）

生成回复时，除非用户要求更多或更少，否则请遵循 prompts/verbosity_steering.md 中的 2 级设置。五个级别如下：

• L0 — 关闭
• L1 — 略过客套话（“很好，我来……”）
• L2 — 在 L1 基础上，不重复屏幕上已有的代码／输出；通过 path:line 引用 (默认)
• L3 — 在 L2 基础上，只给出结论，除非用户要求，否则略过推理过程
• L4 — 片段式表达，尽可能减少 token

配套的“工作量路由”规则：如果上一轮是工具结果，且 is_error: false，同时用户没有提出新要求，那么这属于机械式延续。请以 L3 级别回复，并略过深入推理。如果上一轮是错误，或用户提出了新问题，则保持完整工作量。请参阅 prompts/effort_routing.md。

此技能中的文件

• AGENTS.md — 通用 Agent 规则（适用于任何 Agent 框架）。请先阅读此文件。
• CLAUDE.md — 同一套规则的 Claude Code／Cursor 专用副本。
• docs/techniques.md — 深入介绍每种转换，并附有完整示例。
• docs/integrations.md — 各 Agent 的设置说明（Hermes、Claw、Codex、Cursor、Aider、Goose、Continue、OpenHands、vibe、Copilot CLI）。
• docs/reversible-ccr.md — 磁盘上的 CCR 缓存约定。
• scripts/ — 纯 Python 标准库辅助工具。无需 pip install。
• prompts/ — 用于控制输出的系统提示词片段。
• examples/ — 每种转换的前后对比示例。

重要安全规则（不得违反）

这些规则与上游 Headroom 中的安全规则一致。每条规则都用于防止一种具体故障模式。

1. 绝不丢弃用户或助手文本。 可以压缩工具结果，但不能压缩人工撰写的消息。
2. 绝不拆分 tool_call／tool_result 对。 丢弃其中一半会使另一半失去对应内容，模型就会幻觉出结果。
3. 解析失败时不做任何处理。 如果输入无法解析为预期类型，则原样传递。错误的压缩比不压缩更糟。
4. 始终保留近期内容。 最后 N 轮（默认是 2 轮用户发言）永不丢弃，即使其重要性评分较低也不例外。
5. 始终保留系统提示词。 永不丢弃。
6. 100% 保留错误。 无一例外。
7. 保持幂等。 对已压缩的输出再次运行压缩器时，应不做任何处理（或几乎不做处理）。

致谢

此技能是对 chopratejas/headroom 中相关技术的可移植再实现。该项目由 Tejas Chopra 及贡献者开发，采用 Apache 2.0 许可证。完整署名信息请参阅 NOTICE 和 README.md 中的“致谢”部分。上游项目速度更快、更准确，并由 ML 提供支持；如果条件允许，请安装上游项目。