正在打开工具详情…
正在打开工具详情…
在工具输出、日志、RAG 片段进入 LLM 之前压缩它们，全程本地运行不上传内容。适合被长上下文撑爆的编码代理用户；代价是收益取决于内容重复度，散文几乎压不动。
每天让编码代理或自建 Agent 吞大量 JSON、日志、检索结果的人，以及想省 token 又不想把内容传到第三方压缩服务的人。
主要处理散文、短对话的人——压缩率会低到没有意义；也不适合不愿在代理外面再挂一层本地代理服务的人。
Headroom 压缩的是「代理读进去的一切」——工具输出、日志、RAG 片段、文件和对话历史，压缩在你本机完成，不把 prompt 或文件内容发到任何地方。内部是 ContentRouter 判定内容类型后选压缩器（JSON 走 SmartCrusher、代码走 CodeCompressor、散文走 Kompress-v2-base），CacheAligner 标记会破坏 provider KV-cache 前缀的易变内容（它本身不改写 prompt），CCR 把原文存在本地，模型需要全文时调用 headroom_retrieve 取回。
三种形态：Python / TypeScript 库（compress(messages)）、零改代码的代理（headroom proxy --port 8787）、以及一条命令包住某个编码代理（headroom wrap claude|codex|grok|copilot|cursor|aider|cline|...，headroom unwrap 撤销）。它还顺带管输出侧：把「be terse」提示加到 system prompt 末尾（这样缓存仍然命中），并在「模型只是接着工具结果继续」时降低思考强度——默认关闭，用 HEADROOM_OUTPUT_SHAPER=1 开启。
代价要看清：收益完全取决于重复度。README 给的四个真实场景是代码搜索 21%、SRE 排障 57%、代码库探索 42%、issue 分类 30%；重复 JSON 与日志行能清掉 90% 以上，散文和本身紧凑的输出压不了多少，跑 headroom savings 才有属于你自己的数字。另外 npm 包 headroom-ai 只是 TypeScript SDK，，CLI 只在 PyPI 包里；接 DeepSeek / OpenRouter 这类第三方 OpenAI 兼容服务时必须显式 ，否则 key 会被发到 OpenAI 并返回 401。
--openai-api-url上手步骤之外的具体做法：常见场景怎么配、命令怎么写、报错怎么处理。
按第一次用会卡在哪讲：三种形态怎么选、wrap 会顺带装上 Serena、第三方 provider 那个 401 坑、以及为什么你看到的压缩率和官方数字不一样。
bashuv tool install --python 3.13 "headroom-ai[all]" # 隔离环境里的 CLI
pip install "headroom-ai[all]" # 同样带 headroom CLI
npm install headroom-ai # 只是 TS SDK，没有 CLI记住这条：npm 包不提供 headroom 命令，它是给你 import { compress } from 'headroom-ai' 用的库。
bashheadroom deploy # 一条龙：本地部署 + 配好代理
headroom wrap claude # 包住某个编码代理
headroom proxy --port 8787 # 起代理，任意 OpenAI 兼容客户端零改代码接入库模式直接嵌在代码里：
pythonfrom headroom import compress
result = compress(messages, model="gpt-4o")
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")包完之后每次都用 wrap 启动会话才会生效。headroom wrap 会起本地代理、装上 Serena 做语义代码导航，并把代理配置成走 Headroom；Claude Code 下 Serena 只注册给当前项目（--code-memory-scope user 改成全局，--code-memory none 跳过），headroom unwrap 可以撤销。
用 OpenCode + DeepSeek / OpenRouter / 自建网关时，默认上游是 https://api.openai.com/v1，你的 key 会被发到 OpenAI 并 401。必须显式指定：
bashheadroom wrap opencode --openai-api-url https://api.deepseek.com/v1
# 或先 export OPENAI_TARGET_API_URL=... 再 wrapREADME 把数字摊开讲了：收益随内容重复度上升。
| 场景 | 压缩率 |
|---|---|
| 代码搜索（100 条结果） | 21% |
| SRE 排障 | 57% |
| 代码库探索 | 42% |
| issue 分类 | 30% |
重复 JSON 数组与日志行能清掉 90% 以上；散文和本就紧凑的输出几乎压不动。跑 headroom savings 拿你自己的数字，别照搬 README。
输出 token 在 Opus 级模型上比输入贵得多。开启：
bashexport HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787它做两件事：把「简洁些」的提示追加到 system prompt 末尾（保住 prompt 缓存），以及在模型只是接着工具结果继续时降低思考强度。用 headroom output-savings 看结果——那是带置信区间的估算值，想要实测值就 export HEADROOM_OUTPUT_HOLDOUT=0.1 留一成会话做对照。