用 headroom wrap 一条命令压缩代理上下文并注入 Serena 语义导航

方案简介

本方案使用 Headroom 提供的 headroom wrap 能力，把主流编码代理（Claude Code、Codex、Cursor 等）一键接入本地压缩管线。Headroom 在数据到达 LLM 之前压缩代理读取的一切内容——工具输出、日志、RAG 片段、文件与会话历史——用极少的 token 获得同样的回答。压缩完全在本机运行，提示词与文件内容不会被发送到任何地方去压缩。

该方案适合重度使用 AI 编码代理、希望降低 token 消耗并保留完整上下文回取能力的开发者。一个命令即可完成部署，也可用 headroom unwrap 一键撤销。

亮点与能力

• 一条命令包装 15 种编码代理，headroom unwrap 一键撤销
• 启动本地代理，代理流量全部经过压缩，无需改动任何代码
• 自动安装 Serena，提供语义代码导航能力
• Serena 注册在用户作用域，其他项目也可继续使用
• 可逆压缩（CCR）：原文缓存在本地，模型可按需调用 headroom_retrieve 取回全文
• CacheAligner 标记会破坏 KV-cache 前缀的易变内容，但绝不改写提示词
• 输出 token 削减：不仅压缩发送内容，也修剪模型写回的内容
• 跨代理共享记忆，Claude、Codex、Gemini、Grok 共用一个存储并自动去重

组成与分工

• Headroom：本地运行的压缩层，包含 ContentRouter、CacheAligner 与 CCR，对外提供 CLI、代理与 MCP 服务
• Claude Code / Codex 等代理：被 wrap 的编码代理，流量被配置为经由 Headroom 本地代理路由
• Serena：语义代码导航工具，由 headroom wrap 自动安装并注册到用户作用域
• ContentRouter：检测内容类型并为其选择合适的压缩器
• SmartCrusher / CodeCompressor / Kompress-v2-base：分别处理 JSON、源代码与散文文本
• CCR：把原文缓存到本地，模型需要全文时可调用 headroom_retrieve

前置要求

• Python 3.13（CLI 通过 uv 安装在自包含环境中）
• uv 包管理器，或直接使用 pip

安装命令：

bash
uv tool install --python 3.13 "headroom-ai[all]" # CLI in a self-contained env
pip install "headroom-ai[all]" # Python — ships the headroom CLI

注意：headroom CLI 只随 PyPI 包提供。npm 的 headroom-ai 包是 TypeScript SDK，是一个需要 import 的库（import { compress } from 'headroom-ai'），不提供 headroom 命令。

实施步骤

1. 安装

使用 uv 安装自包含环境的 CLI：

bash
uv tool install --python 3.13 "headroom-ai[all]" # CLI in a self-contained env

或用 pip：

bash
pip install "headroom-ai[all]" # Python — ships the headroom CLI

2. 选择模式并包装代理

bash
headroom wrap claude # wrap a coding agent

这条命令会启动本地代理、安装 Serena 并以路由经过 Headroom 的配置启动代理。

3. 健康检查与验证

bash
headroom doctor # health check — confirms routing works
headroom dashboard # live savings (proxy must be running)

撤销

bash
headroom unwrap

如不想安装 Serena，可在 wrap 时用 --code-memory none 跳过。

使用与配置要点

• 每次都通过被包装的代理启动会话，压缩设置才会生效："Launch a wrapped agent session each time, so the setup runs."
• headroom doctor 确认路由工作正常；headroom dashboard 查看实时节省（需代理在运行）
• headroom perf、headroom savings 可对自身流量度量实际节省比例
• Serena 注册在用户作用域（对 Claude Code 而言在 ~/.claude.），在运行 headroom unwrap 前对其他项目也持续可用
• 省钱效果与负载重复度相关：重复 JSON 数组和日志行在基准中可清掉 90%，散文和已经致密的输出压缩很少

注意事项与常见问题

• npm 的 headroom-ai 包不含 CLI，只有 TypeScript SDK
• headroom dashboard 的实时节省需要代理正在运行
• 省钱比例取决于内容：重复性高的负载（JSON、日志）节省大，散文与致密内容压缩很少
• 撤销集成请使用 headroom unwrap ，否则 Serena 会一直保留在用户作用域

优缺点

• ✓ 零代码改动接入代理
• ✓ 本地压缩数据不出机器
• ✕ 仅 PyPI 包含 CLI
• ✕ npm 包无 headroom 命令

出处

本方案挖掘自开源项目 headroomlabs-ai/headroom，方案内容与实施命令均来自其 README 原文。