YOHO AI

标签： headroom

  • Headroom：让 AI 智能体少花 90% Token 的上下文压缩层

    Headroom：让 AI 智能体少花 90% Token 的上下文压缩层

    项目简介

    Headroom 是一个为 AI 智能体（AI Agent）打造的上下文压缩层。它在提示词、工具输出、日志、RAG 检索片段、文件和对话历史到达大模型之前进行压缩，让你在获得相同答案的同时， Token 成本大幅下降。官方实测：JSON 类数据可减少 60–95% 的 Token，编码类智能体可减少 15–20%。

    核心功能

    • 多种部署形态：Python/TypeScript 内联库、headroom proxy 零代码代理、headroom wrap 一键包装 Claude/Codex/Cursor/Aider/Cline 等主流 Agent，以及原生 MCP Server。
    • 内容感知压缩：SmartCrusher 专攻 JSON，CodeCompressor 基于 AST 压缩代码，Kompress-v2-base 用自研 HuggingFace 模型处理自然语言。
    • 可逆压缩（CCR）：原始内容本地缓存，LLM 可通过 headroom_retrieve 按需取回，绝不丢失信息。
    • 跨 Agent 记忆：同一台机器上 Claude、Codex、Grok、Gemini 等工具可共享记忆库并自动去重。
    • 输出 Token 优化：通过 Verbosity steering 和 Effort routing，自动削减模型废话、重复代码和过度思考，进一步降低输出侧成本。
    • headroom learn：自动挖掘失败会话，把纠偏规则写入 CLAUDE.local.md、AGENTS.md 或 GEMINI.md，让 Agent 越用越聪明。

    安装要求和过程

    环境要求：Python 3.10+。推荐用 uv 或 pip 安装；TypeScript 开发者也可用 npm 安装 SDK（仅库，无 CLI）。

    # 推荐：uv 全局工具安装（隔离环境）
uv tool install --python 3.13 "headroom-ai[all]"

# 或者 pip
pip install "headroom-ai[all]"

# TypeScript SDK（仅库）
npm install headroom-ai

    启动方式三选一：

    # 一键部署 + 自动配置 Agent
headroom deploy

# 包装 Claude Code（自动启动本地代理并注入配置）
headroom wrap claude

# 零代码 drop-in 代理
headroom proxy --port 8787

    验证：

    headroom doctor    # 健康检查
headroom perf      # 性能报告
headroom dashboard # 实时节省看板

    典型使用场景

    Headroom 工作原理

    场景 1：AI 编码助手降本增效
    你每天用 Claude Code、Cursor 或 Codex 处理大型代码库。代码搜索结果、RAG 片段、测试日志动辄几万 Token。Headroom 自动压缩输入内容，代码搜索场景可减少 92% Token，而答案质量不变。配合 headroom learn，它还能把常见误操作自动写入项目本地规则文件。

    场景 2：SRE 事故排查
    排查线上事故时，需要把大量日志、监控输出、GitHub Issue、运行时报错塞进上下文。Headroom 对日志和结构化数据压缩率极高，65k Token 的排查材料可压缩到 5k 左右，让智能体在上下文窗口内“看完全部证据”，而不是被截断。

    场景 3：多 Agent 共享记忆
    你在同一项目里混用 Claude Code、Codex、Grok CLI 和 Aider。Headroom 提供跨 Agent 的共享记忆存储，避免每个工具重复读取文件、重复建立上下文，真正实现“一次理解，处处可用”。

    Headroom 压缩效果

    推荐理由

    Headroom 最让我喜欢的一点是“不绑架你的工作流”。它既可以是库，也可以是代理，还可以一键 wrap 你已有的 Agent，不需要重写 prompt 或迁移模型。而且它是本地优先的，原始内容不会离开你的机器，企业敏感代码也能放心使用。

    更难得的是，它在省钱的同时还做了“可逆压缩”和“失败学习”：前者保证信息不丢，后者让 Agent 越用越准。对于已经在用 Claude Code、Cursor、Codex 等工具的开发者来说，Headroom 几乎是“装完就能省钱”的基础设施。

    下载地址

    Headroom 采用 Apache 2.0 协议开源，当前 Stars 约 63.2K，主要语言为 Python。

  • Headroom：16.4k Stars！LLM上下文压缩层，最高省95% token消耗

    Headroom：16.4k Stars！LLM上下文压缩层，最高省95% token消耗

    用AI Agent干活，token消耗像流水。工具输出一多，日志一长，上下文就爆了。Headroom就是来解决这个问题的。

    Headroom

    项目是什么

    Headroom是一个面向AI Agent的上下文压缩层，在内容进入LLM之前先做压缩处理。工具输出、日志、RAG检索结果、代码文件、对话历史，统统可以压。官方数据说能省60-95%的token，而且答案质量不降。

    安装要求和过程

    要求Python 3.10以上。安装本身很简单：

    # 全量安装（推荐）
pip install "headroom-ai[all]"

# Node.js版本
npm install headroom-ai

# Docker
docker pull ghcr.io/chopratejas/headroom:latest

    如果你想按需安装，可以只装指定模块：[proxy]、[mcp]、[ml]、[code]、[memory]、[relevance]、[image]，不用全量。装完直接 headroom wrap claude 就能把Claude Code包起来用，零代码修改。

    核心功能

    • 三种接入模式：当作Python/TypeScript库直接调用 compress()，或者跑一个本地代理让任意应用零改动接入，或者直接wrap主流AI编码工具（Claude Code、Cursor、Aider、Copilot都支持）。
    • MCP服务器模式：提供了 headroom_compress、headroom_retrieve、headroom_stats 三个工具，可以接进任何MCP客户端。对用Claude Desktop或者Cline的人很方便。
    • 可逆压缩（CCR）：原始内容不会删，LLM觉得信息不够的时候可以通过工具调用把原始内容拿回来。不是有损压缩，是”按需取用”。
    • 跨Agent共享内存：多个Agent（Claude、Codex、Gemini）可以共享同一套上下文存储，自动去重。做多Agent协作的人会喜欢这个功能。
    • 自动学习：跑一下 headroom learn，它会去分析失败的会话，把修正规则自动写进 CLAUDE.md / AGENTS.md 这些配置文件。相当于Agent自己进化。

    典型使用场景

    先看数据。官方跑了一些真实工作负载的压缩测试：

    工作负载类型 压缩前token 压缩后token 压缩率
    代码搜索（100条结果） 17,765 1,408 92%
    SRE故障排查 65,694 5,118 92%
    GitHub Issue分类 54,174 14,761 73%

    实际场景里，最爽的是这两个：

    第一，长日志排查。SRE场景里把6万多token的日志压缩到5千多，压缩率92%，而且LLM给出的排查结论和质量没差。这意味着你可以用更便宜的模型、更短的上下文窗口，处理同样复杂的任务。

    第二，RAG场景。把检索回来的大量chunk先压缩再塞给LLM，原本只能放5条chunk的上下文窗口，现在能放20条。检索质量上去了，token消耗反而下来了。

    为什么推荐它

    我试过几个类似的方案，RTK、lean-ctx，还有OpenAI自己出的压缩方案。Headroom最打动我的是”可逆压缩”这个设计。很多压缩方案是单向的，压完原始信息就没了，LLM判断需要细节的时候拿不到原文。Headroom的CCR机制让LLM可以按需取回原始内容，这个设计很聪明。

    另外就是接入成本真的低。如果你用的是Claude Code或者Cursor，一条命令 headroom wrap claude 就搞定，不需要改代码，不需要重新配置，直接生效。对于已经用上这些工具的人来说，几乎是零成本的优化。

    本周Headroom在GitHub周增长榜排第一，新增了13,000+ star。16.4k的总star数不算高，但增长曲线很陡，说明用过的人都在往上加。这种”开发者口碑传播”的项目，通常比营销驱动的项目更值得跟。

    GitHub：github.com/chopratejas/headroom
    官网文档：headroom-docs.vercel.app
    协议：Apache 2.0（可商用）