[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-chopratejas--headroom":3,"tool-chopratejas--headroom":61},[4,18,26,36,44,52],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",141543,2,"2026-04-06T11:32:54",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107888,"2026-04-06T11:32:50",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":10,"last_commit_at":50,"category_tags":51,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[35,15,13,14],{"id":53,"name":54,"github_repo":55,"description_zh":56,"stars":57,"difficulty_score":10,"last_commit_at":58,"category_tags":59,"status":17},4292,"Deep-Live-Cam","hacksider\u002FDeep-Live-Cam","Deep-Live-Cam 是一款专注于实时换脸与视频生成的开源工具，用户仅需一张静态照片，即可通过“一键操作”实现摄像头画面的即时变脸或制作深度伪造视频。它有效解决了传统换脸技术流程繁琐、对硬件配置要求极高以及难以实时预览的痛点，让高质量的数字内容创作变得触手可及。\n\n这款工具不仅适合开发者和技术研究人员探索算法边界，更因其极简的操作逻辑（仅需三步：选脸、选摄像头、启动），广泛适用于普通用户、内容创作者、设计师及直播主播。无论是为了动画角色定制、服装展示模特替换，还是制作趣味短视频和直播互动，Deep-Live-Cam 都能提供流畅的支持。\n\n其核心技术亮点在于强大的实时处理能力，支持口型遮罩（Mouth Mask）以保留使用者原始的嘴部动作，确保表情自然精准；同时具备“人脸映射”功能，可同时对画面中的多个主体应用不同面孔。此外，项目内置了严格的内容安全过滤机制，自动拦截涉及裸露、暴力等不当素材，并倡导用户在获得授权及明确标注的前提下合规使用，体现了技术发展与伦理责任的平衡。",88924,"2026-04-06T03:28:53",[14,15,13,60],"视频",{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":77,"owner_email":78,"owner_twitter":79,"owner_website":79,"owner_url":80,"languages":81,"stars":101,"forks":102,"last_commit_at":103,"license":104,"difficulty_score":105,"env_os":106,"env_gpu":107,"env_ram":107,"env_deps":108,"category_tags":115,"github_topics":117,"view_count":32,"oss_zip_url":79,"oss_zip_packed_at":79,"status":17,"created_at":133,"updated_at":134,"faqs":135,"releases":164},4502,"chopratejas\u002Fheadroom","headroom","The Context Optimization Layer for LLM Applications","Headroom 是一款专为大语言模型（LLM）应用设计的上下文优化层，旨在大幅降低 AI 代理运行时的令牌消耗。在构建代码助手、客服机器人或数据分析智能体时，工具调用、数据库查询、文件读取及 RAG 检索等操作往往包含大量重复的“样板”信息，导致 70% 至 95% 的输入令牌被浪费。Headroom 通过在数据进入模型前自动压缩这些冗余内容，确保在保持回答质量不变的前提下，显著减少令牌使用量。\n\n这款工具非常适合开发者和技术研究人员，无论是使用 LangChain、Cursor 等主流框架，还是编写自定义的 Python 或 TypeScript 代码，都能轻松集成。其独特亮点在于极高的灵活性：既可以通过简单的函数调用嵌入现有逻辑，也能作为透明代理运行，无需修改任何代码即可拦截并优化所有请求。支持 OpenAI、Anthropic 等百家模型提供商，让各类 AI 应用在长上下文场景中运行得更高效、更经济。","\u003Cp align=\"center\">\n  \u003Ch1 align=\"center\">Headroom\u003C\u002Fh1>\n  \u003Cp align=\"center\">\n    \u003Cstrong>Compress everything your AI agent reads. Same answers, fraction of the tokens.\u003C\u002Fstrong>\n  \u003C\u002Fp>\n  \u003Cp align=\"center\">\n    Every tool call, DB query, file read, and RAG retrieval your agent makes is 70-95% boilerplate.\u003Cbr>\n    Headroom compresses it away before it hits the model.\u003Cbr>\u003Cbr>\n    Works with \u003Cb>any agent\u003C\u002Fb> — coding agents (Claude Code, Codex, Cursor, Aider), custom agents\u003Cbr>\n    (LangChain, LangGraph, Agno, Strands, OpenClaw), or your own Python and TypeScript code.\n  \u003C\u002Fp>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fchopratejas\u002Fheadroom\u002Factions\u002Fworkflows\u002Fci.yml\">\n    \u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fchopratejas\u002Fheadroom\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg\" alt=\"CI\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Fheadroom-ai\u002F\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fheadroom-ai.svg\" alt=\"PyPI\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Fheadroom-ai\u002F\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fpyversions\u002Fheadroom-ai.svg\" alt=\"Python\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fpypistats.org\u002Fpackages\u002Fheadroom-ai\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Fheadroom-ai.svg\" alt=\"Downloads\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fheadroom-ai\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fheadroom-ai.svg\" alt=\"npm\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fchopratejas\u002Fheadroom\u002Fblob\u002Fmain\u002FLICENSE\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-Apache%202.0-blue.svg\" alt=\"License\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fchopratejas.github.io\u002Fheadroom\u002F\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocs-GitHub%20Pages-blue.svg\" alt=\"Documentation\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fdiscord.gg\u002FyRmaUNpsPJ\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDiscord-Join%20us-5865F2?logo=discord&logoColor=white\" alt=\"Discord\">\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n---\n\n## Where Headroom Fits\n\n```\nYour Agent \u002F App\n  (coding agents, customer support bots, RAG pipelines,\n   data analysis agents, research agents, any LLM app)\n      │\n      │  tool calls, logs, DB reads, RAG results, file reads, API responses\n      ▼\n   Headroom  ← proxy, Python\u002FTypeScript SDK, or framework integration\n      │\n      ▼\n LLM Provider  (OpenAI, Anthropic, Google, Bedrock, 100+ via LiteLLM)\n```\n\nHeadroom sits between your application and the LLM provider. It intercepts requests, compresses the context, and forwards an optimized prompt. Use it as a transparent proxy (zero code changes), a Python function (`compress()`), or a framework integration (LangChain, LiteLLM, Agno).\n\n### What gets compressed\n\nHeadroom optimizes any data your agent injects into a prompt:\n\n- **Tool outputs** — shell commands, API calls, search results\n- **Database queries** — SQL results, key-value lookups\n- **RAG retrievals** — document chunks, embeddings results\n- **File reads** — code, logs, configs, CSVs\n- **API responses** — JSON, XML, HTML\n- **Conversation history** — long agent sessions with repetitive context\n\n---\n\n## Quick Start\n\n**Python:**\n```bash\npip install \"headroom-ai[all]\"\n```\n\n**TypeScript \u002F Node.js:**\n```bash\nnpm install headroom-ai\n```\n\n### Any agent — one function\n\n**Python:**\n```python\nfrom headroom import compress\n\nresult = compress(messages, model=\"claude-sonnet-4-5-20250929\")\nresponse = client.messages.create(model=\"claude-sonnet-4-5-20250929\", messages=result.messages)\nprint(f\"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})\")\n```\n\n**TypeScript:**\n```typescript\nimport { compress } from 'headroom-ai';\n\nconst result = await compress(messages, { model: 'gpt-4o' });\nconst response = await openai.chat.completions.create({ model: 'gpt-4o', messages: result.messages });\nconsole.log(`Saved ${result.tokensSaved} tokens`);\n```\n\nWorks with any LLM client — Anthropic, OpenAI, LiteLLM, Bedrock, Vercel AI SDK, or your own code.\n\n### Any agent — proxy (zero code changes)\n\n```bash\nheadroom proxy --port 8787\n```\n\n```bash\n# Point any LLM client at the proxy\nANTHROPIC_BASE_URL=http:\u002F\u002Flocalhost:8787 your-app\nOPENAI_BASE_URL=http:\u002F\u002Flocalhost:8787\u002Fv1 your-app\n```\n\nWorks with any language, any tool, any framework. **[Proxy docs](docs\u002Fproxy.md)**\n\n### Coding agents — one command\n\n```bash\nheadroom wrap claude       # Starts proxy + launches Claude Code\nheadroom wrap codex        # Starts proxy + launches OpenAI Codex CLI\nheadroom wrap aider        # Starts proxy + launches Aider\nheadroom wrap cursor       # Starts proxy + prints Cursor config\nheadroom wrap openclaw     # Installs + configures OpenClaw plugin\n```\n\nHeadroom starts a proxy, points your tool at it, and compresses everything automatically.\n\n### Multi-agent — SharedContext\n\n```python\nfrom headroom import SharedContext\n\nctx = SharedContext()\nctx.put(\"research\", big_agent_output)      # Agent A stores (compressed)\nsummary = ctx.get(\"research\")               # Agent B reads (~80% smaller)\nfull = ctx.get(\"research\", full=True)       # Agent B gets original if needed\n```\n\nCompress what moves between agents — any framework. **[SharedContext Guide](docs\u002Fshared-context.md)**\n\n### MCP Tools (Claude Code, Cursor)\n\n```bash\nheadroom mcp install && claude\n```\n\nGives your AI tool three MCP tools: `headroom_compress`, `headroom_retrieve`, `headroom_stats`. **[MCP Guide](docs\u002Fmcp.md)**\n\n### Drop into your existing stack\n\n| Your setup | Add Headroom | One-liner |\n|------------|-------------|-----------|\n| **Any Python app** | `compress()` | `result = compress(messages, model=\"gpt-4o\")` |\n| **Any TypeScript app** | `compress()` | `const result = await compress(messages, { model: 'gpt-4o' })` |\n| **Vercel AI SDK** | Middleware | `wrapLanguageModel({ model, middleware: headroomMiddleware() })` |\n| **OpenAI Node SDK** | Wrap client | `const client = withHeadroom(new OpenAI())` |\n| **Anthropic TS SDK** | Wrap client | `const client = withHeadroom(new Anthropic())` |\n| **Multi-agent** | SharedContext | `ctx = SharedContext(); ctx.put(\"key\", data)` |\n| **LiteLLM** | Callback | `litellm.callbacks = [HeadroomCallback()]` |\n| **Any Python proxy** | ASGI Middleware | `app.add_middleware(CompressionMiddleware)` |\n| **Agno agents** | Wrap model | `HeadroomAgnoModel(your_model)` |\n| **LangChain** | Wrap model | `HeadroomChatModel(your_llm)` |\n| **OpenClaw** | One-command wrap | `headroom wrap openclaw` |\n| **Claude Code** | Wrap | `headroom wrap claude` |\n| **Codex \u002F Aider** | Wrap | `headroom wrap codex` or `headroom wrap aider` |\n\n**[Full Integration Guide](docs\u002Fintegration-guide.md)** | **[TypeScript SDK](docs\u002Ftypescript-sdk.md)**\n\n---\n\n## Demo\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fchopratejas_headroom_readme_424740944d9a.gif\" alt=\"Headroom Demo\" width=\"800\">\n\u003C\u002Fp>\n\n---\n\n## Does It Actually Work?\n\n**100 production log entries. One critical error buried at position 67.**\n\n|  | Baseline | Headroom |\n|--|----------|----------|\n| Input tokens | 10,144 | 1,260 |\n| Correct answers | **4\u002F4** | **4\u002F4** |\n\nBoth responses: *\"payment-gateway, error PG-5523, fix: Increase max_connections to 500, 1,847 transactions affected.\"*\n\n**87.6% fewer tokens. Same answer.** Run it: `python examples\u002Fneedle_in_haystack_test.py`\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>What Headroom kept\u003C\u002Fb>\u003C\u002Fsummary>\n\nFrom 100 log entries, SmartCrusher kept 6: first 3 (boundary), the FATAL error at position 67 (anomaly detection), and last 2 (recency). The error was automatically preserved — not by keyword matching, but by statistical analysis of field variance.\n\u003C\u002Fdetails>\n\n### Real Workloads\n\n| Scenario | Before | After | Savings |\n|----------|--------|-------|---------|\n| Code search (100 results) | 17,765 | 1,408 | **92%** |\n| SRE incident debugging | 65,694 | 5,118 | **92%** |\n| Codebase exploration | 78,502 | 41,254 | **47%** |\n| GitHub issue triage | 54,174 | 14,761 | **73%** |\n\n### Accuracy Benchmarks\n\nCompression preserves accuracy — tested on real OSS benchmarks.\n\n**Standard Benchmarks** — Baseline (direct to API) vs Headroom (through proxy):\n\n| Benchmark | Category | N | Baseline | Headroom | Delta |\n|-----------|----------|---|----------|----------|-------|\n| [GSM8K](https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002Fopenai\u002Fgsm8k) | Math | 100 | 0.870 | 0.870 | **0.000** |\n| [TruthfulQA](https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002Ftruthfulqa\u002Ftruthful_qa) | Factual | 100 | 0.530 | 0.560 | **+0.030** |\n\n**Compression Benchmarks** — Accuracy after full compression stack:\n\n| Benchmark | Category | N | Accuracy | Compression | Method |\n|-----------|----------|---|----------|-------------|--------|\n| [SQuAD v2](https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002Frajpurkar\u002Fsquad_v2) | QA | 100 | **97%** | 19% | Before\u002FAfter |\n| [BFCL](https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002Fgorilla-llm\u002FBerkeley-Function-Calling-Leaderboard) | Tool\u002FFunction | 100 | **97%** | 32% | LLM-as-Judge |\n| Tool Outputs (built-in) | Agent | 8 | **100%** | 20% | Before\u002FAfter |\n| CCR Needle Retention | Lossless | 50 | **100%** | 77% | Exact Match |\n\nRun it yourself:\n\n```bash\n# Quick smoke test (8 cases, ~10s)\npython -m headroom.evals quick -n 8 --provider openai --model gpt-4o-mini\n\n# Full Tier 1 suite (~$3, ~15 min)\npython -m headroom.evals suite --tier 1 -o eval_results\u002F\n\n# CI mode (exit 1 on regression)\npython -m headroom.evals suite --tier 1 --ci\n```\n\nFull methodology: [Benchmarks](docs\u002Fbenchmarks.md) | [Evals Framework](headroom\u002Fevals\u002FREADME.md)\n\n---\n\n## Key Capabilities\n\n### Lossless Compression\n\nHeadroom never throws data away. It compresses aggressively, stores the originals, and gives the LLM a tool to retrieve full details when needed. When it compresses 500 items to 20, it tells the model *what was omitted* (\"87 passed, 2 failed, 1 error\") so the model knows when to ask for more.\n\n### Smart Content Detection\n\nAuto-detects what's in your context — JSON arrays, code, logs, plain text — and routes each to the best compressor. JSON goes to SmartCrusher, code goes through AST-aware compression (Python, JS, Go, Rust, Java, C++), text goes to Kompress (ModernBERT-based, with `[ml]` extra).\n\n### Cache Optimization\n\nStabilizes message prefixes so your provider's KV cache actually works. Claude offers a 90% read discount on cached prefixes — but almost no framework takes advantage of it. Headroom does.\n\n### Failure Learning\n\n```bash\nheadroom learn                   # Analyze past Claude Code sessions, show recommendations\nheadroom learn --apply           # Write learnings to CLAUDE.md and MEMORY.md\nheadroom learn --all --apply     # Learn across all your projects\n```\n\nReads your conversation history, finds every failed tool call, correlates it with what eventually succeeded, and writes specific corrections into your project files. Next session starts smarter. **[Learn docs](docs\u002Flearn.md)**\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fchopratejas_headroom_readme_3e6a77f21996.gif\" alt=\"headroom learn demo\" width=\"800\">\n\u003C\u002Fp>\n\n### Image Compression\n\n40-90% token reduction via trained ML router. Automatically selects the right resize\u002Fquality tradeoff per image.\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>All features\u003C\u002Fb>\u003C\u002Fsummary>\n\n| Feature | What it does |\n|---------|-------------|\n| **Content Router** | Auto-detects content type, routes to optimal compressor |\n| **SmartCrusher** | Universal JSON compression — arrays of dicts, strings, numbers, mixed types, nested objects |\n| **CodeCompressor** | AST-aware compression for Python, JS, Go, Rust, Java, C++ |\n| **Kompress** | ModernBERT token compression (replaces LLMLingua-2) |\n| **CCR** | Reversible compression — LLM retrieves originals when needed |\n| **Compression Summaries** | Tells the LLM what was omitted (\"3 errors, 12 failures\") |\n| **CacheAligner** | Stabilizes prefixes for provider KV cache hits |\n| **IntelligentContext** | Score-based context management with learned importance |\n| **Image Compression** | 40-90% token reduction via trained ML router |\n| **Memory** | Persistent memory across conversations |\n| **Compression Hooks** | Customize compression with pre\u002Fpost hooks |\n| **Read Lifecycle** | Detects stale\u002Fsuperseded Read outputs, replaces with CCR markers |\n| **`headroom learn`** | Analyzes past failures, writes project-specific learnings to CLAUDE.md\u002FMEMORY.md |\n| **`headroom wrap`** | One-command setup for Claude Code, Codex, Aider, Cursor |\n| **SharedContext** | Compressed inter-agent context sharing for multi-agent workflows |\n| **MCP Tools** | headroom_compress, headroom_retrieve, headroom_stats for Claude Code\u002FCursor |\n\n\u003C\u002Fdetails>\n\n---\n\n## Headroom vs Alternatives\n\nContext compression is a new space. Here's how the approaches differ:\n\n| | Approach | Scope | Deploy as | Framework integrations | Data stays local? | Reversible |\n|---|---|---|---|---|---|---|\n| **Headroom** | Multi-algorithm compression | All context (tool outputs, DB reads, RAG, files, logs, history) | Proxy, Python library, ASGI middleware, or callback | LangChain, LangGraph, Agno, Strands, LiteLLM, MCP | Yes (OSS) | Yes (CCR) |\n| **[RTK](https:\u002F\u002Fgithub.com\u002Frtk-ai\u002Frtk)** | CLI command rewriter | Shell command outputs | CLI wrapper | None | Yes (OSS) | No |\n| **[Compresr](https:\u002F\u002Fcompresr.ai)** | Cloud compression API | Text sent to their API | API call | None | No | No |\n| **[Token Company](https:\u002F\u002Fthetokencompany.ai)** | Cloud compression API | Text sent to their API | API call | None | No | No |\n\n**Use it however you want.** Headroom works as a standalone proxy (`headroom proxy`), a one-function Python library (`compress()`), ASGI middleware, or a LiteLLM callback. Already using LiteLLM, LangChain, or Agno? Drop Headroom in without replacing anything.\n\n**Headroom + RTK work well together.** RTK rewrites CLI commands (`git show` → `git show --short`), Headroom compresses everything else (JSON arrays, code, logs, RAG results, conversation history). Use both.\n\n**Headroom vs cloud APIs.** Compresr and Token Company are hosted services — you send your context to their servers, they compress and return it. Headroom runs locally. Your data never leaves your machine. You also get lossless compression (CCR): the LLM can retrieve the full original when it needs more detail.\n\n---\n\n## How It Works Inside\n\n```\n  Your prompt\n      │\n      ▼\n  1. CacheAligner            Stabilize prefix for KV cache\n      │\n      ▼\n  2. ContentRouter           Route each content type:\n      │                         → SmartCrusher    (JSON)\n      │                         → CodeCompressor  (code)\n      │                         → Kompress        (text, with [ml])\n      ▼\n  3. IntelligentContext      Score-based token fitting\n      │\n      ▼\n  LLM Provider\n\n  Needs full details? LLM calls headroom_retrieve.\n  Originals are in the Compressed Store — nothing is thrown away.\n```\n\n**Overhead**: 15-200ms compression latency (net positive for Sonnet\u002FOpus). Full data: [Latency Benchmarks](docs\u002FLATENCY_BENCHMARKS.md)\n\n---\n\n## Integrations\n\n| Integration | Status | Docs |\n|-------------|--------|------|\n| `headroom wrap claude\u002Fcodex\u002Faider\u002Fcursor` | **Stable** | [Proxy Docs](docs\u002Fproxy.md) |\n| `compress()` — one function | **Stable** | [Integration Guide](docs\u002Fintegration-guide.md) |\n| `SharedContext` — multi-agent | **Stable** | [SharedContext Guide](docs\u002Fshared-context.md) |\n| LiteLLM callback | **Stable** | [Integration Guide](docs\u002Fintegration-guide.md#litellm) |\n| ASGI middleware | **Stable** | [Integration Guide](docs\u002Fintegration-guide.md#asgi-middleware) |\n| Proxy server | **Stable** | [Proxy Docs](docs\u002Fproxy.md) |\n| Agno | **Stable** | [Agno Guide](docs\u002Fagno.md) |\n| MCP (Claude Code, Cursor, etc.) | **Stable** | [MCP Guide](docs\u002Fmcp.md) |\n| Strands | **Stable** | [Strands Guide](docs\u002Fstrands.md) |\n| LangChain | **Stable** | [LangChain Guide](docs\u002Flangchain.md) |\n| **OpenClaw** | **Stable** | [OpenClaw plugin](#openclaw-plugin) |\n\n---\n\n## OpenClaw Plugin\n\nThe [`@headroom-ai\u002Fopenclaw`](plugins\u002Fopenclaw) plugin integrates Headroom as a ContextEngine for [OpenClaw](https:\u002F\u002Fgithub.com\u002Fopenclaw\u002Fopenclaw). It compresses tool outputs, code, logs, and structured data inline — 70-90% token savings with zero LLM calls. The plugin can connect to a local or remote Headroom proxy and will auto-start one locally if needed.\n\n### Install\n\n```bash\npip install \"headroom-ai[proxy]\"\nopenclaw plugins install --dangerously-force-unsafe-install headroom-ai\u002Fopenclaw\n```\n\n> **Why `--dangerously-force-unsafe-install`?** The plugin auto-starts `headroom proxy` as a subprocess when no running proxy is detected. OpenClaw blocks process-launching plugins by default, so this flag is required to permit that behavior.\n\nOnce installed, assign Headroom as the context engine in your OpenClaw config:\n\n```json\n{\n  \"plugins\": {\n    \"entries\": { \"headroom\": { \"enabled\": true } },\n    \"slots\": { \"contextEngine\": \"headroom\" }\n  }\n}\n```\n\nThe plugin auto-detects and auto-starts the proxy — no manual proxy management needed. See the [plugin README](plugins\u002Fopenclaw\u002FREADME.md) for full configuration options, local development setup, and launcher details.\n\n---\n\n## Cloud Providers\n\n```bash\nheadroom proxy --backend bedrock --region us-east-1     # AWS Bedrock\nheadroom proxy --backend vertex_ai --region us-central1 # Google Vertex\nheadroom proxy --backend azure                          # Azure OpenAI\nheadroom proxy --backend openrouter                     # OpenRouter (400+ models)\n```\n\n---\n\n## Installation\n\n```bash\npip install headroom-ai                # Core library\npip install \"headroom-ai[all]\"         # Everything including evals (recommended)\npip install \"headroom-ai[proxy]\"       # Proxy server + MCP tools\npip install \"headroom-ai[mcp]\"         # MCP tools only (no proxy)\npip install \"headroom-ai[ml]\"          # ML compression (Kompress, requires torch)\npip install \"headroom-ai[agno]\"        # Agno integration\npip install \"headroom-ai[langchain]\"   # LangChain (experimental)\npip install \"headroom-ai[evals]\"       # Evaluation framework only\n```\n\n### Container images (GHCR tags)\n\n- supported platforms: `linux\u002Famd64`, `linux\u002Farm64`\n- tags `:code` - image with Code-Aware Compression (AST-based) i.e. `pip install \"headroom-ai[proxy,code]\"`\n- tags `:slim` - image with distorless base\n\n| Tag                 |                                                      | Extras       | Docker Bake target          |\n|---------------------|------------------------------------------------------|--------------|-----------------------------|\n| `\u003Cversion>`         | ```ghcr.io\u002Fchopratejas\u002Fheadroom:\u003Cversion>```         | `proxy`      | `runtime`                   |\n| `latest`            | ```ghcr.io\u002Fchopratejas\u002Fheadroom:latest```            | `proxy`      | `runtime`                   |\n| `nonroot`           | ```ghcr.io\u002Fchopratejas\u002Fheadroom:nonroot```           | `proxy`      | `runtime-nonroot`           |\n| `code`              | ```ghcr.io\u002Fchopratejas\u002Fheadroom:code```              | `proxy,code` | `runtime-code`              |\n| `code-nonroot`      | ```ghcr.io\u002Fchopratejas\u002Fheadroom:code-nonroot```      | `proxy,code` | `runtime-code-nonroot`      |\n| `slim`              | ```ghcr.io\u002Fchopratejas\u002Fheadroom:slim```              | `proxy`      | `runtime-slim`              |\n| `slim-nonroot`      | ```ghcr.io\u002Fchopratejas\u002Fheadroom:slim-nonroot```      | `proxy`      | `runtime-slim-nonroot`      |\n| `code-slim`         | ```ghcr.io\u002Fchopratejas\u002Fheadroom:code-slim```         | `proxy,code` | `runtime-code-slim`         |\n| `code-slim-nonroot` | ```ghcr.io\u002Fchopratejas\u002Fheadroom:code-slim-nonroot``` | `proxy,code` | `runtime-code-slim-nonroot` |\n\n### Docker Bake\n\n```bash\n# List all available build targets\ndocker buildx bake --list targets\n\n# Build default image locally (proxy + nonroot)\ndocker buildx bake runtime-default\n\n# Build one variant and load to local Docker image store\ndocker buildx bake runtime-code-slim-nonroot \\\n  --set runtime-code-slim-nonroot.platform=linux\u002Famd64 \\\n  --set runtime-code-slim-nonroot.tags=headroom:local \\\n  --load\n```\n\nPython 3.10+\n\n---\n\n## Documentation\n\n| | |\n|---|---|\n| [Integration Guide](docs\u002Fintegration-guide.md) | LiteLLM, ASGI, compress(), proxy |\n| [Proxy Docs](docs\u002Fproxy.md) | Proxy server configuration |\n| [Architecture](docs\u002FARCHITECTURE.md) | How the pipeline works |\n| [CCR Guide](docs\u002Fccr.md) | Reversible compression |\n| [Benchmarks](docs\u002Fbenchmarks.md) | Accuracy validation |\n| [Latency Benchmarks](docs\u002FLATENCY_BENCHMARKS.md) | Compression overhead & cost-benefit analysis |\n| [Limitations](docs\u002FLIMITATIONS.md) | When compression helps, when it doesn't |\n| [Evals Framework](headroom\u002Fevals\u002FREADME.md) | Prove compression preserves accuracy |\n| [Memory](docs\u002Fmemory.md) | Persistent memory |\n| [Agno](docs\u002Fagno.md) | Agno agent framework |\n| [MCP](docs\u002Fmcp.md) | Context engineering toolkit (compress, retrieve, stats) |\n| [SharedContext](docs\u002Fshared-context.md) | Compressed inter-agent context sharing |\n| [Learn](docs\u002Flearn.md) | Offline failure learning for coding agents |\n| [Configuration](docs\u002Fconfiguration.md) | All options |\n\n---\n\n## Community\n\nQuestions, feedback, or just want to follow along? **[Join us on Discord](https:\u002F\u002Fdiscord.gg\u002FyRmaUNpsPJ)**\n\n---\n\n## Contributing\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fchopratejas\u002Fheadroom.git && cd headroom\npip install -e \".[dev]\" && pytest\n```\n\n---\n\n## License\n\nApache License 2.0 — see [LICENSE](LICENSE).\n","\u003Cp align=\"center\">\n  \u003Ch1 align=\"center\">Headroom\u003C\u002Fh1>\n  \u003Cp align=\"center\">\n    \u003Cstrong>压缩你的 AI 助手所读取的所有内容。答案不变，但使用的 token 数量大幅减少。\u003C\u002Fstrong>\n  \u003C\u002Fp>\n  \u003Cp align=\"center\">\n    你的助手进行的每一次工具调用、数据库查询、文件读取以及 RAG 检索中，有 70% 到 95% 都是重复性的样板内容。\u003Cbr>\n    Headroom 可以在这些内容进入模型之前将其压缩掉。\u003Cbr>\u003Cbr>\n    支持\u003Cb>任何助手\u003C\u002Fb>——编程助手（Claude Code、Codex、Cursor、Aider）、自定义助手\u003Cbr>\n    （LangChain、LangGraph、Agno、Strands、OpenClaw），或者你自己的 Python 和 TypeScript 代码。\n  \u003C\u002Fp>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fchopratejas\u002Fheadroom\u002Factions\u002Fworkflows\u002Fci.yml\">\n    \u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fchopratejas\u002Fheadroom\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg\" alt=\"CI\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Fheadroom-ai\u002F\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fheadroom-ai.svg\" alt=\"PyPI\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Fheadroom-ai\u002F\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fpyversions\u002Fheadroom-ai.svg\" alt=\"Python\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fpypistats.org\u002Fpackages\u002Fheadroom-ai\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Fheadroom-ai.svg\" alt=\"下载量\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fheadroom-ai\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fheadroom-ai.svg\" alt=\"npm\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fchopratejas.github.io\u002Fheadroom\u002F\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocs-GitHub%20Pages-blue.svg\" alt=\"文档\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fdiscord.gg\u002FyRmaUNpsPJ\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDiscord-Join%20us-5865F2?logo=discord&logoColor=white\" alt=\"Discord\">\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n---\n\n## Headroom 的适用场景\n\n```\n你的助手 \u002F 应用\n  (编程助手、客服机器人、RAG 流水线、数据分析助手、研究助手、任何 LLM 应用)\n      │\n      │  工具调用、日志、数据库读取、RAG 结果、文件读取、API 响应\n      ▼\n   Headroom  ← 代理、Python\u002FTypeScript SDK 或框架集成\n      │\n      ▼\n LLM 提供商  (OpenAI、Anthropic、Google、Bedrock、通过 LiteLLM 支持 100 多家)\n```\n\nHeadroom 位于你的应用和 LLM 提供商之间。它会拦截请求，压缩上下文，并转发优化后的提示词。你可以将其作为透明代理使用（无需修改代码）、作为一个 Python 函数 (`compress()`)，或者通过框架集成（LangChain、LiteLLM、Agno）来使用。\n\n### 哪些内容会被压缩\n\nHeadroom 会优化你的助手注入到提示词中的任何数据：\n\n- **工具输出** — shell 命令、API 调用、搜索结果\n- **数据库查询** — SQL 查询结果、键值查找\n- **RAG 检索** — 文档片段、嵌入结果\n- **文件读取** — 代码、日志、配置文件、CSV 文件\n- **API 响应** — JSON、XML、HTML\n- **对话历史** — 长时间的助手会话中包含的重复性上下文\n\n---\n\n## 快速开始\n\n**Python:**\n```bash\npip install \"headroom-ai[all]\"\n```\n\n**TypeScript \u002F Node.js:**\n```bash\nnpm install headroom-ai\n```\n\n### 适用于任何助手——只需一个函数调用\n\n**Python:**\n```python\nfrom headroom import compress\n\nresult = compress(messages, model=\"claude-sonnet-4-5-20250929\")\nresponse = client.messages.create(model=\"claude-sonnet-4-5-20250929\", messages=result.messages)\nprint(f\"节省了 {result.tokens_saved} 个 token ({result.compression_ratio:.0%})\")\n```\n\n**TypeScript:**\n```typescript\nimport { compress } from 'headroom-ai';\n\nconst result = await compress(messages, { model: 'gpt-4o' });\nconst response = await openai.chat.completions.create({ model: 'gpt-4o', messages: result.messages });\nconsole.log(`节省了 ${result.tokensSaved} 个 token`);\n```\n\n支持任何 LLM 客户端——Anthropic、OpenAI、LiteLLM、Bedrock、Vercel AI SDK，或你自己的代码。\n\n### 适用于任何助手——代理模式（无需修改代码）\n\n```bash\nheadroom proxy --port 8787\n```\n\n```bash\n# 将任何 LLM 客户端指向代理\nANTHROPIC_BASE_URL=http:\u002F\u002Flocalhost:8787 your-app\nOPENAI_BASE_URL=http:\u002F\u002Flocalhost:8787\u002Fv1 your-app\n```\n\n支持任何语言、任何工具、任何框架。**[代理文档](docs\u002Fproxy.md)**\n\n### 编程助手——一条命令搞定\n\n```bash\nheadroom wrap claude       # 启动代理并运行 Claude Code\nheadroom wrap codex        # 启动代理并运行 OpenAI Codex CLI\nheadroom wrap aider        # 启动代理并运行 Aider\nheadroom wrap cursor       # 启动代理并打印 Cursor 配置\nheadroom wrap openclaw     # 安装并配置 OpenClaw 插件\n```\n\nHeadroom 会启动一个代理，将你的工具指向该代理，并自动压缩所有内容。\n\n### 多智能体——SharedContext\n\n```python\nfrom headroom import SharedContext\n\nctx = SharedContext()\nctx.put(\"research\", big_agent_output)      # 智能体 A 存储（已压缩）\nsummary = ctx.get(\"research\")               # 智能体 B 读取（体积缩小约 80%）\nfull = ctx.get(\"research\", full=True)       # 智能体 B 在需要时获取原始数据\n```\n\n压缩在智能体之间传递的数据——适用于任何框架。**[SharedContext 使用指南](docs\u002Fshared-context.md)**\n\n### MCP 工具（Claude Code、Cursor）\n\n```bash\nheadroom mcp install && claude\n```\n\n为你的 AI 工具提供三个 MCP 工具：`headroom_compress`、`headroom_retrieve`、`headroom_stats`。**[MCP 使用指南](docs\u002Fmcp.md)**\n\n### 轻松融入现有技术栈\n\n| 你的设置 | 添加 Headroom | 一行命令 |\n|------------|-------------|-----------|\n| **任何 Python 应用** | `compress()` | `result = compress(messages, model=\"gpt-4o\")` |\n| **任何 TypeScript 应用** | `compress()` | `const result = await compress(messages, { model: 'gpt-4o' })` |\n| **Vercel AI SDK** | 中间件 | `wrapLanguageModel({ model, middleware: headroomMiddleware() })` |\n| **OpenAI Node SDK** | 包装客户端 | `const client = withHeadroom(new OpenAI())` |\n| **Anthropic TS SDK** | 包装客户端 | `const client = withHeadroom(new Anthropic())` |\n| **多智能体** | SharedContext | `ctx = SharedContext(); ctx.put(\"key\", data)` |\n| **LiteLLM** | 回调 | `litellm.callbacks = [HeadroomCallback()]` |\n| **任何 Python 代理** | ASGI 中间件 | `app.add_middleware(CompressionMiddleware)` |\n| **Agno 助手** | 包装模型 | `HeadroomAgnoModel(your_model)` |\n| **LangChain** | 包装模型 | `HeadroomChatModel(your_llm)` |\n| **OpenClaw** | 一键封装 | `headroom wrap openclaw` |\n| **Claude Code** | 封装 | `headroom wrap claude` |\n| **Codex \u002F Aider** | 封装 | `headroom wrap codex` 或 `headroom wrap aider` |\n\n**[完整集成指南](docs\u002Fintegration-guide.md)** | **[TypeScript SDK](docs\u002Ftypescript-sdk.md)**\n\n---\n\n## 演示\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fchopratejas_headroom_readme_424740944d9a.gif\" alt=\"Headroom 演示\" width=\"800\">\n\u003C\u002Fp>\n\n---\n\n## 它真的有效吗？\n\n**100 条生产日志条目。第 67 位埋藏着一个严重错误。**\n\n|  | 基线 | Headroom |\n|--|----------|----------|\n| 输入 token 数量 | 10,144 | 1,260 |\n| 正确答案 | **4\u002F4** | **4\u002F4** |\n\n两种响应均为：*“支付网关，错误 PG-5523，修复方案：将 max_connections 增加到 500，受影响的交易数为 1,847。”*\n\n**token 数量减少了 87.6%。答案相同。** 运行命令：`python examples\u002Fneedle_in_haystack_test.py`\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Headroom 保留的内容\u003C\u002Fb>\u003C\u002Fsummary>\n\n从 100 条日志中，SmartCrusher 保留了 6 条：前 3 条（边界）、第 67 条的 FATAL 错误（异常检测）以及最后 2 条（最近性）。该错误被自动保留——并非通过关键词匹配，而是通过对字段方差的统计分析实现。\n\u003C\u002Fdetails>\n\n### 真实工作负载\n\n| 场景 | 前 | 后 | 节省 |\n|----------|--------|-------|---------|\n| 代码搜索（100 条结果） | 17,765 | 1,408 | **92%** |\n| SRE 事件调试 | 65,694 | 5,118 | **92%** |\n| 代码库探索 | 78,502 | 41,254 | **47%** |\n| GitHub 问题分类 | 54,174 | 14,761 | **73%** |\n\n### 准确性基准测试\n\n压缩不会降低准确性——已在真实的开源基准上进行了测试。\n\n**标准基准测试**——基线（直接调用 API）与 Headroom（通过代理）：\n\n| 基准 | 类别 | N | 基线 | Headroom | 差值 |\n|-----------|----------|---|----------|----------|-------|\n| [GSM8K](https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002Fopenai\u002Fgsm8k) | 数学 | 100 | 0.870 | 0.870 | **0.000** |\n| [TruthfulQA](https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002Ftruthfulqa\u002Ftruthful_qa) | 事实性 | 100 | 0.530 | 0.560 | **+0.030** |\n\n**压缩基准测试**——完整压缩流程后的准确性：\n\n| 基准 | 类别 | N | 准确性 | 压缩率 | 方法 |\n|-----------|----------|---|----------|-------------|--------|\n| [SQuAD v2](https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002Frajpurkar\u002Fsquad_v2) | 问答 | 100 | **97%** | 19% | 压缩前后对比 |\n| [BFCL](https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002Fgorilla-llm\u002FBerkeley-Function-Calling-Leaderboard) | 工具\u002F函数 | 100 | **97%** | 32% | 使用 LLM 作为评判者 |\n| 内置工具输出 | 代理 | 8 | **100%** | 20% | 压缩前后对比 |\n| CCR 针尖保留 | 无损 | 50 | **100%** | 77% | 完全匹配 |\n\n您可以自行运行：\n\n```bash\n# 快速烟雾测试（8 个案例，约 10 秒）\npython -m headroom.evals quick -n 8 --provider openai --model gpt-4o-mini\n\n# 完整 Tier 1 测试套件（约 $3，15 分钟）\npython -m headroom.evals suite --tier 1 -o eval_results\u002F\n\n# CI 模式（回归时退出码为 1）\npython -m headroom.evals suite --tier 1 --ci\n```\n\n完整方法论：[基准测试](docs\u002Fbenchmarks.md) | [评估框架](headroom\u002Fevals\u002FREADME.md)\n\n---\n\n## 核心功能\n\n### 无损压缩\n\nHeadroom 绝不会丢弃任何数据。它会进行激进的压缩，同时保存原始数据，并为 LLM 提供在需要时检索完整细节的工具。当它将 500 个项目压缩至 20 个时，它会告诉模型 *哪些内容被省略了*（“87 个通过，2 个失败，1 个错误”），以便模型知道何时需要进一步查询。\n\n### 智能内容检测\n\n自动检测上下文中的内容类型——JSON 数组、代码、日志、纯文本——并将每种内容路由到最佳压缩器。JSON 数据交由 SmartCrusher 处理，代码则通过 AST 感知型压缩（Python、JS、Go、Rust、Java、C++），而文本则交给 Kompress（基于 ModernBERT 的压缩技术，额外包含 `[ml]` 标记）。\n\n### 缓存优化\n\n稳定消息前缀，使您的提供商的 KV 缓存真正发挥作用。Claude 对缓存前缀提供 90% 的读取折扣——但几乎没有框架能够利用这一点。Headroom 可以。\n\n### 失败学习\n\n```bash\nheadroom learn                   # 分析过去的 Claude Code 会话，展示建议\nheadroom learn --apply           # 将学习成果写入 CLAUDE.md 和 MEMORY.md\nheadroom learn --all --apply     # 在所有项目中学习\n```\n\n它会读取您的对话历史，找出每一次失败的工具调用，并将其与最终成功的操作相关联，然后将具体的修正建议写入您的项目文件中。下一次会话将更加智能。**[学习文档](docs\u002Flearn.md)**\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fchopratejas_headroom_readme_3e6a77f21996.gif\" alt=\"headroom learn demo\" width=\"800\">\n\u003C\u002Fp>\n\n### 图像压缩\n\n通过训练好的 ML 路由器实现 40-90% 的 token 减少。自动为每张图像选择合适的缩放和质量权衡。\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>所有功能\u003C\u002Fb>\u003C\u002Fsummary>\n\n| 功能 | 作用 |\n|---------|-------------|\n| **内容路由器** | 自动检测内容类型，路由到最优压缩器 |\n| **SmartCrusher** | 通用 JSON 压缩——字典数组、字符串、数字、混合类型、嵌套对象 |\n| **CodeCompressor** | 基于 AST 的 Python、JS、Go、Rust、Java、C++ 代码压缩 |\n| **Kompress** | 基于 ModernBERT 的 token 压缩（替代 LLMLingua-2） |\n| **CCR** | 可逆压缩——LLM 在需要时可检索原始数据 |\n| **压缩摘要** | 告诉 LLM 哪些内容被省略了（“3 个错误，12 个失败”） |\n| **CacheAligner** | 稳定前缀，提高提供商 KV 缓存命中率 |\n| **IntelligentContext** | 基于评分的上下文管理，结合学习到的重要性 |\n| **图像压缩** | 通过训练好的 ML 路由器实现 40-90% 的 token 减少 |\n| **Memory** | 跨对话的持久化记忆 |\n| **Compression Hooks** | 使用预\u002F后处理钩子自定义压缩过程 |\n| **Read Lifecycle** | 检测过时\u002F已替换的 Read 输出，用 CCR 标记代替 |\n| **`headroom learn`** | 分析过去的失败，将项目特定的学习成果写入 CLAUDE.md\u002FMEMORY.md |\n| **`headroom wrap`** | 一键设置 Claude Code、Codex、Aider、Cursor |\n| **SharedContext** | 压缩后的多智能体上下文共享，适用于多智能体工作流 |\n| **MCP 工具** | headroom_compress、headroom_retrieve、headroom_stats，专用于 Claude Code\u002FCursor |\n\n\u003C\u002Fdetails>\n\n---\n\n## Headroom 与替代方案\n\n上下文压缩是一个新兴领域。以下是各方法的主要区别：\n\n| | 方法 | 范围 | 部署方式 | 框架集成 | 数据是否本地存储？ | 是否可逆 |\n|---|---|---|---|---|---|---|\n| **Headroom** | 多算法压缩 | 所有上下文（工具输出、数据库读取、RAG、文件、日志、历史记录） | 代理、Python 库、ASGI 中间件或回调 | LangChain、LangGraph、Agno、Strands、LiteLLM、MCP | 是（开源） | 是（CCR） |\n| **[RTK](https:\u002F\u002Fgithub.com\u002Frtk-ai\u002Frtk)** | CLI 命令重写器 | Shell 命令输出 | CLI 包装器 | 无 | 是（开源） | 否 |\n| **[Compresr](https:\u002F\u002Fcompresr.ai)** | 云端压缩 API | 将文本发送至其 API | API 调用 | 无 | 否 | 否 |\n| **[Token Company](https:\u002F\u002Fthetokencompany.ai)** | 云端压缩 API | 将文本发送至其 API | API 调用 | 无 | 否 | 否 |\n\n**随心所欲地使用。** Headroom 可以作为独立代理（`headroom proxy`）、单函数 Python 库（`compress()`）、ASGI 中间件，或 LiteLLM 回调来使用。已经在使用 LiteLLM、LangChain 或 Agno？无需替换任何东西，直接接入 Headroom 即可。\n\n**Headroom 与 RTK 搭配效果极佳。** RTK 会重写 CLI 命令（`git show` → `git show --short`），而 Headroom 则负责压缩其他内容（JSON 数组、代码、日志、RAG 结果、对话历史）。两者结合使用效果更佳。\n\n**Headroom 与云端 API 的对比。** Compresr 和 Token Company 是托管服务——您将上下文发送到他们的服务器，他们会进行压缩后再返回给您。而 Headroom 则在本地运行。您的数据永远不会离开您的设备。此外，您还能获得无损压缩（CCR）：当 LLM 需要更多细节时，可以恢复原始完整内容。\n\n---\n\n## 内部工作原理\n\n```\n  您的提示\n      │\n      ▼\n  1. CacheAligner            稳定 KV 缓存前缀\n      │\n      ▼\n  2. ContentRouter           路由每种内容类型：\n      │                         → SmartCrusher    (JSON)\n      │                         → CodeCompressor  (代码)\n      │                         → Kompress        (文本，含 [ml])\n      ▼\n  3. IntelligentContext      基于评分的令牌优化\n      │\n      ▼\n  LLM 提供者\n\n  需要完整细节？LLM 会调用 headroom_retrieve。\n  原始数据保存在压缩存储中——不会有任何丢失。\n```\n\n**开销**：15–200 毫秒的压缩延迟（对 Sonnet\u002FOpus 来说是净收益）。完整数据：[延迟基准测试](docs\u002FLATENCY_BENCHMARKS.md)\n\n---\n\n## 集成\n\n| 集成 | 状态 | 文档 |\n|-------------|--------|------|\n| `headroom wrap claude\u002Fcodex\u002Faider\u002Fcursor` | **稳定** | [代理文档](docs\u002Fproxy.md) |\n| `compress()` — 单函数 | **稳定** | [集成指南](docs\u002Fintegration-guide.md) |\n| `SharedContext` — 多智能体 | **稳定** | [SharedContext 指南](docs\u002Fshared-context.md) |\n| LiteLLM 回调 | **稳定** | [集成指南](docs\u002Fintegration-guide.md#litellm) |\n| ASGI 中间件 | **稳定** | [集成指南](docs\u002Fintegration-guide.md#asgi-middleware) |\n| 代理服务器 | **稳定** | [代理文档](docs\u002Fproxy.md) |\n| Agno | **稳定** | [Agno 指南](docs\u002Fagno.md) |\n| MCP（Claude Code、Cursor 等） | **稳定** | [MCP 指南](docs\u002Fmcp.md) |\n| Strands | **稳定** | [Strands 指南](docs\u002Fstrands.md) |\n| LangChain | **稳定** | [LangChain 指南](docs\u002Flangchain.md) |\n| **OpenClaw** | **稳定** | [OpenClaw 插件](#openclaw-plugin) |\n\n---\n\n## OpenClaw 插件\n\n插件 [`@headroom-ai\u002Fopenclaw`](plugins\u002Fopenclaw) 将 Headroom 集成为 [OpenClaw](https:\u002F\u002Fgithub.com\u002Fopenclaw\u002Fopenclaw) 的 ContextEngine。它可以在原地压缩工具输出、代码、日志和结构化数据——节省 70%–90% 的令牌，且无需额外的 LLM 调用。该插件可以连接到本地或远程的 Headroom 代理，如果本地没有运行的代理，它还会自动启动一个。\n\n### 安装\n\n```bash\npip install \"headroom-ai[proxy]\"\nopenclaw plugins install --dangerously-force-unsafe-install headroom-ai\u002Fopenclaw\n```\n\n> **为什么需要 `--dangerously-force-unsafe-install`？** 当检测不到正在运行的代理时，插件会自动以子进程的方式启动 `headroom proxy`。默认情况下，OpenClaw 会阻止启动进程的插件，因此必须使用此标志才能允许该行为。\n\n安装完成后，在 OpenClaw 配置中将 Headroom 设置为上下文引擎：\n\n```json\n{\n  \"plugins\": {\n    \"entries\": { \"headroom\": { \"enabled\": true } },\n    \"slots\": { \"contextEngine\": \"headroom\" }\n  }\n}\n```\n\n插件会自动检测并启动代理——无需手动管理代理。完整的配置选项、本地开发设置和启动器详情，请参阅插件的 [README](plugins\u002Fopenclaw\u002FREADME.md)。\n\n---\n\n## 云提供商\n\n```bash\nheadroom proxy --backend bedrock --region us-east-1     # AWS Bedrock\nheadroom proxy --backend vertex_ai --region us-central1 # Google Vertex\nheadroom proxy --backend azure                          # Azure OpenAI\nheadroom proxy --backend openrouter                     # OpenRouter（400+ 模型）\n```\n\n---\n\n## 安装\n\n```bash\npip install headroom-ai                # 核心库\npip install \"headroom-ai[all]\"         # 包括评估在内的所有功能（推荐）\npip install \"headroom-ai[proxy]\"       # 代理服务器 + MCP 工具\npip install \"headroom-ai[mcp]\"         # 仅 MCP 工具（不含代理）\npip install \"headroom-ai[ml]\"          # ML 压缩（Kompress，需 torch）\npip install \"headroom-ai[agno]\"        # Agno 集成\npip install \"headroom-ai[langchain]\"   # LangChain（实验性）\npip install \"headroom-ai[evals]\"       # 仅评估框架\n```\n\n### 容器镜像（GHCR 标签）\n\n- 支持的平台：`linux\u002Famd64`、`linux\u002Farm64`\n- 标签 `:code` - 包含代码感知压缩（基于 AST）的镜像，即运行 `pip install \"headroom-ai[proxy,code]\"`\n- 标签 `:slim` - 使用无损基础镜像\n\n| 标签                 |                                                      | 额外组件       | Docker Bake 目标          |\n|---------------------|------------------------------------------------------|--------------|-----------------------------|\n| `\u003Cversion>`         | ```ghcr.io\u002Fchopratejas\u002Fheadroom:\u003Cversion>```         | `proxy`      | `runtime`                   |\n| `latest`            | ```ghcr.io\u002Fchopratejas\u002Fheadroom:latest```            | `proxy`      | `runtime`                   |\n| `nonroot`           | ```ghcr.io\u002Fchopratejas\u002Fheadroom:nonroot```           | `proxy`      | `runtime-nonroot`           |\n| `code`              | ```ghcr.io\u002Fchopratejas\u002Fheadroom:code```              | `proxy,code` | `runtime-code`              |\n| `code-nonroot`      | ```ghcr.io\u002Fchopratejas\u002Fheadroom:code-nonroot```      | `proxy,code` | `runtime-code-nonroot`      |\n| `slim`              | ```ghcr.io\u002Fchopratejas\u002Fheadroom:slim```              | `proxy`      | `runtime-slim`              |\n| `slim-nonroot`      | ```ghcr.io\u002Fchopratejas\u002Fheadroom:slim-nonroot```      | `proxy`      | `runtime-slim-nonroot`      |\n| `code-slim`         | ```ghcr.io\u002Fchopratejas\u002Fheadroom:code-slim```         | `proxy,code` | `runtime-code-slim`         |\n| `code-slim-nonroot` | ```ghcr.io\u002Fchopratejas\u002Fheadroom:code-slim-nonroot``` | `proxy,code` | `runtime-code-slim-nonroot` |\n\n### Docker Bake\n\n```bash\n# 列出所有可用的构建目标\ndocker buildx bake --list targets\n\n# 在本地构建默认镜像（包含代理且以非 root 用户运行）\ndocker buildx bake runtime-default\n\n# 构建特定变体并加载到本地 Docker 镜像仓库\ndocker buildx bake runtime-code-slim-nonroot \\\n  --set runtime-code-slim-nonroot.platform=linux\u002Famd64 \\\n  --set runtime-code-slim-nonroot.tags=headroom:local \\\n  --load\n```\n\nPython 3.10+\n\n---\n\n## 文档\n\n| | |\n|---|---|\n| [集成指南](docs\u002Fintegration-guide.md) | LiteLLM、ASGI、compress()、代理 |\n| [代理文档](docs\u002Fproxy.md) | 代理服务器配置 |\n| [架构](docs\u002FARCHITECTURE.md) | 管道的工作原理 |\n| [CCR 指南](docs\u002Fccr.md) | 可逆压缩 |\n| [基准测试](docs\u002Fbenchmarks.md) | 准确性验证 |\n| [延迟基准测试](docs\u002FLATENCY_BENCHMARKS.md) | 压缩开销及成本效益分析 |\n| [局限性](docs\u002FLIMITATIONS.md) | 压缩何时有效，何时无效 |\n| [评估框架](headroom\u002Fevals\u002FREADME.md) | 证明压缩不会降低准确性 |\n| [内存](docs\u002Fmemory.md) | 持久化内存 |\n| [Agno](docs\u002Fagno.md) | Agno 代理框架 |\n| [MCP](docs\u002Fmcp.md) | 上下文工程工具包（压缩、检索、统计） |\n| [共享上下文](docs\u002Fshared-context.md) | 压缩后的多代理间上下文共享 |\n| [学习](docs\u002Flearn.md) | 编码代理的离线故障学习 |\n| [配置](docs\u002Fconfiguration.md) | 所有可配置选项 |\n\n---\n\n## 社区\n\n有问题、反馈，或只是想关注我们的进展？**[加入我们的 Discord](https:\u002F\u002Fdiscord.gg\u002FyRmaUNpsPJ)**\n\n---\n\n## 贡献\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fchopratejas\u002Fheadroom.git && cd headroom\npip install -e \".[dev]\" && pytest\n```\n\n---\n\n## 许可证\n\nApache License 2.0 — 详见 [LICENSE](LICENSE)。","# Headroom 快速上手指南\n\nHeadroom 是一款专为 AI Agent 设计的上下文压缩工具。它能将 Agent 读取的工具调用、数据库查询、文件内容及 RAG 检索结果压缩 70-95%，在保持回答质量不变的前提下，大幅减少 Token 消耗。适用于 Claude Code、Cursor、LangChain 及自定义 Python\u002FTS 应用。\n\n## 环境准备\n\n*   **操作系统**：Linux, macOS, Windows\n*   **运行环境**：\n    *   **Python**: 版本 3.9 或更高\n    *   **Node.js**: 版本 18 或更高（如需使用 TypeScript\u002FNode 集成）\n*   **前置依赖**：无特殊系统级依赖，需确保已安装对应语言的包管理器（pip 或 npm）。\n\n> **提示**：国内开发者若遇到 PyPI 或 npm 下载缓慢，可配置国内镜像源加速：\n> *   **PyPI**: `pip install -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple ...`\n> *   **npm**: `npm config set registry https:\u002F\u002Fregistry.npmmirror.com`\n\n## 安装步骤\n\n根据你的开发语言选择以下任一方式安装：\n\n### Python 环境\n```bash\npip install \"headroom-ai[all]\"\n# 或使用清华源加速\n# pip install \"headroom-ai[all]\" -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n```\n\n### TypeScript \u002F Node.js 环境\n```bash\nnpm install headroom-ai\n# 或使用淘宝镜像加速\n# npm install headroom-ai --registry=https:\u002F\u002Fregistry.npmmirror.com\n```\n\n## 基本使用\n\nHeadroom 提供多种集成方式，以下是三种最常用的场景：\n\n### 1. 代码集成（最灵活）\n直接在代码中调用 `compress` 函数，适用于任何 LLM 客户端（OpenAI, Anthropic, LiteLLM 等）。\n\n**Python 示例：**\n```python\nfrom headroom import compress\n\n# 压缩消息列表\nresult = compress(messages, model=\"claude-sonnet-4-5-20250929\")\n\n# 将压缩后的消息发送给 LLM\nresponse = client.messages.create(model=\"claude-sonnet-4-5-20250929\", messages=result.messages)\n\nprint(f\"节省 {result.tokens_saved} tokens (压缩率 {result.compression_ratio:.0%})\")\n```\n\n**TypeScript 示例：**\n```typescript\nimport { compress } from 'headroom-ai';\n\nconst result = await compress(messages, { model: 'gpt-4o' });\nconst response = await openai.chat.completions.create({ model: 'gpt-4o', messages: result.messages });\n\nconsole.log(`Saved ${result.tokensSaved} tokens`);\n```\n\n### 2. 透明代理模式（零代码修改）\n启动一个本地代理服务器，拦截所有请求并自动压缩上下文。适用于无法修改源码的现有应用或 CLI 工具。\n\n**启动代理：**\n```bash\nheadroom proxy --port 8787\n```\n\n**配置应用指向代理：**\n```bash\n# Anthropic 系列工具\nANTHROPIC_BASE_URL=http:\u002F\u002Flocalhost:8787 your-app\n\n# OpenAI 系列工具\nOPENAI_BASE_URL=http:\u002F\u002Flocalhost:8787\u002Fv1 your-app\n```\n\n### 3. 编程助手一键封装\n针对主流编程 Agent（如 Claude Code, Cursor, Aider），使用 `wrap` 命令自动完成代理启动与配置。\n\n```bash\n# 封装 Claude Code\nheadroom wrap claude\n\n# 封装 Cursor (打印配置信息)\nheadroom wrap cursor\n\n# 封装 Aider\nheadroom wrap aider\n\n# 封装 OpenAI Codex CLI\nheadroom wrap codex\n```\n\n执行后，Headroom 会自动启动后台代理并将对应的编程工具指向该代理，实现全自动压缩。","某电商公司的数据团队正在开发一个智能客服 Agent，该 Agent 需要实时查询库存数据库、检索历史订单日志并读取产品文档来回答用户复杂的售后问题。\n\n### 没有 headroom 时\n- **上下文爆炸**：每次回答需注入大量 SQL 查询结果和冗长的 JSON 日志，导致单次对话消耗数万个 Token，其中 90% 都是重复的字段名和格式符号。\n- **响应延迟严重**：由于输入内容过长，LLM 处理时间显著增加，用户平均等待回答的时间从 2 秒延长至 8 秒以上。\n- **成本失控**：高昂的输入 Token 费用使得每解决一个客户问题的成本高达 0.5 元，大规模部署后月度预算迅速超支。\n- **关键信息淹没**：过多的样板数据（Boilerplate）挤占了上下文窗口，导致模型偶尔忽略关键的异常报错信息，给出错误的解决方案。\n\n### 使用 headroom 后\n- **极致压缩**：headroom 在数据进入模型前自动压缩了数据库返回值和日志文件，去除了 95% 的冗余字符，仅保留语义核心，Token 用量骤减。\n- **速度飞跃**：输入长度大幅缩短，LLM 推理速度回归毫秒级，用户几乎感觉不到延迟，体验流畅如真人对话。\n- **成本降低 80%**：得益于 Token 数量的断崖式下降，单次问答成本降至 0.1 元以下，让大规模自动化客服成为经济可行的方案。\n- **准确率提升**：精简后的上下文让模型能更聚焦于关键错误代码和用户意图，不再被无关的格式噪音干扰，问题解决率显著提升。\n\nheadroom 通过智能压缩上下文中 70-95% 的样板数据，在不牺牲回答质量的前提下，彻底解决了 AI 应用面临的成本高、速度慢和上下文受限三大难题。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fchopratejas_headroom_44a5c6e5.png","chopratejas","Tejas Chopra","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fchopratejas_2e46fd2d.jpg","Software","Netflix, Inc.","Los Gatos","chopratejas@gmail.com",null,"https:\u002F\u002Fgithub.com\u002Fchopratejas",[82,86,90,94,98],{"name":83,"color":84,"percentage":85},"Python","#3572A5",96.4,{"name":87,"color":88,"percentage":89},"TypeScript","#3178c6",2.4,{"name":91,"color":92,"percentage":93},"HTML","#e34c26",1.1,{"name":95,"color":96,"percentage":97},"Dockerfile","#384d54",0,{"name":99,"color":100,"percentage":97},"HCL","#844FBA",1180,102,"2026-04-06T11:16:57","Apache-2.0",1,"Linux, macOS, Windows","未说明",{"notes":109,"python":110,"dependencies":111},"该工具主要作为代理（Proxy）或 SDK 运行，支持 Python 和 TypeScript\u002FNode.js 环境。可通过 pip 或 npm 安装。支持多种集成方式（如 LangChain, Vercel AI SDK, MCP 等）。若使用基于 ModernBERT 的文本压缩功能（Kompress），可能需要额外的机器学习依赖，但具体硬件需求未在文档中明确列出。工具核心功能是压缩上下文令牌，通常可在标准 CPU 环境下运行。","3.8+",[112,113,114],"headroom-ai","ModernBERT (可选，用于文本压缩)","LiteLLM (可选，用于多模型支持)",[14,13,35,15,116],"插件",[118,119,120,121,122,123,124,125,126,127,128,129,130,131,132],"agent","ai","anthropic","compression","context-engineering","context-window","fastapi","langchain","llm","mcp","openai","proxy","python","rag","token-optimization","2026-03-27T02:49:30.150509","2026-04-07T00:49:40.348420",[136,141,145,150,154,159],{"id":137,"question_zh":138,"answer_zh":139,"source_url":140},20494,"为什么运行 headroom proxy 时提示找不到 '--anyllm-provider' 或 '--openai-api-url' 等选项？","这通常是因为文档与当前安装的版本不匹配，或者缺少必要的依赖包。请尝试使用 `uv pip install headroom-ai[anyllm]` 安装特定扩展包。如果仍然报错，可能是该功能尚未在当前版本中完全实现或文档有误。维护者曾指出某些此类问题是故意留作新手任务（good first issue），建议检查最新发布的版本文档或直接查看 `headroom proxy --help` 确认实际支持的参数。","https:\u002F\u002Fgithub.com\u002Fchopratejas\u002Fheadroom\u002Fissues\u002F41",{"id":142,"question_zh":143,"answer_zh":144,"source_url":140},20495,"如何正确配置 OpenRouter 作为后端提供者？","除了命令行参数外，必须将 API 密钥设置为环境变量才能正常工作。请确保在运行命令前导出变量：`export OPENROUTER_API_KEY=your_api_key`。然后使用类似 `headroom proxy --port 8787 --backend anyllm` 的命令启动（具体参数视版本而定）。日志中显示 \"Backend: Openrouter via any-llm\" 即表示配置成功。",{"id":146,"question_zh":147,"answer_zh":148,"source_url":149},20496,"为什么 Headroom 的压缩率很低（例如只有 1%），感觉没有生效？","压缩效果取决于具体的使用场景和数据类型。在某些测试中，用户观察到压缩率从早期的 20-30% 下降到 1%，这可能是因为输入内容本身难以压缩，或者 CLI 过滤层已经处理了大部分冗余。维护者表示正在开发更深入的令牌压缩功能以提升效果。你可以查看 `\u002Fstats` 输出中的 `by_layer` 部分，确认 `compression` 层是否有 tokens 被移除。如果数值较低，可能是当前内容特性导致，建议关注后续版本更新。","https:\u002F\u002Fgithub.com\u002Fchopratejas\u002Fheadroom\u002Fissues\u002F46",{"id":151,"question_zh":152,"answer_zh":153,"source_url":149},20497,"如何查看 Headroom 的详细节省统计和会话摘要？","Headroom 会在日志中输出详细的会话摘要（SESSION SUMMARY）。启动代理后，留意日志中包含 \"HEADROOM PROXY SESSION SUMMARY\" 的部分。它会列出总请求数、缓存响应数、输入\u002F输出令牌数、节省的令牌数及百分比（Token savings）、平均延迟等关键指标。例如：\"Tokens saved: 8,457,062\", \"Token savings: 16.1%\"。此外，也可以通过访问统计端点（如 `\u002Fstats`）获取 JSON 格式的详细数据。",{"id":155,"question_zh":156,"answer_zh":157,"source_url":158},20498,"如何在 Agno 框架中集成 Headroom？","Headroom 提供了对 Agno 的支持，类似于 LangChain 的集成方式。你需要安装特定版本的包，例如 `pip install headroom-ai==0.2.14`。在使用过程中，如果遇到 \"HeadroomAgnoModel is not a native reasoning model\" 的警告，这表示 Headroom 模型包装器可能阻止了 Agno 识别底层模型的推理能力，默认会回退到手动思维链（Chain-of-Thought）模式。这通常不影响基本功能，但需注意日志中的相关提示。","https:\u002F\u002Fgithub.com\u002Fchopratejas\u002Fheadroom\u002Fissues\u002F5",{"id":160,"question_zh":161,"answer_zh":162,"source_url":163},20499,"访问 Dashboard (http:\u002F\u002Flocalhost:8787\u002Fdashboard) 时显示乱码或空白页面怎么办？","这是一个已知的 Bug（特别是在 v0.3.0 版本中），表现为页面显示随机符号或二进制数据而非实时统计图表。这通常是因为前端资源未正确加载或后端路由配置问题。建议尝试升级到最新版本，因为维护者通常会在此类问题报告后修复。如果问题依旧，可以尝试清除浏览器缓存或使用无痕模式访问。若仍无法解决，可能需要检查是否完整安装了包含 dashboard 依赖的版本（如 `headroom-ai[all]`）。","https:\u002F\u002Fgithub.com\u002Fchopratejas\u002Fheadroom\u002Fissues\u002F22",[165,170,175,180],{"id":166,"version":167,"summary_zh":168,"released_at":169},126457,"v0.5.2","## 变更内容\n\n- **修复：缓存感知的成本定价** — 仪表板中的“输入成本”现使用 LiteLLM 的原生缓存定价（对于 Anthropic，缓存读取按 10% 计费，缓存写入按 125% 计费），而非所有 token 均按列表价计费。此前的输入成本估算严重偏高。\n- **仪表板清晰度提升** — 新增说明，成本估算仅涵盖消息 token（不包括系统提示词和工具定义）。","2026-03-20T19:56:27",{"id":171,"version":172,"summary_zh":173,"released_at":174},126458,"v0.3.7","## v0.3.7 新增内容\n\n### 新特性\n\n- **any-llm 后端** — 通过 [any-llm](https:\u002F\u002Fmozilla-ai.github.io\u002Fany-llm\u002Fproviders\u002F) 将请求路由至 38+ 家 LLM 提供商（OpenAI、Mistral、Groq、Ollama 等）\n  - 使用 `--backend anyllm --anyllm-provider \u003Cprovider>` 启用\n  - 安装命令：`pip install 'headroom-ai[anyllm]'`\n- **IntelligentContextManager** — 基于语义的上下文管理，采用多因子重要性评分机制：时间新近度、语义相似度、TOIN 重要性、错误指标、前向引用、token 密度\n- **LLMLingua-2 集成** — 可选的基于机器学习的压缩功能，使用微软的 LLMLingua-2 模型实现内容感知的压缩率\n- **代码感知压缩** — 基于 AST 的语法保留压缩，采用 tree-sitter 对 Python、JavaScript、TypeScript、Go、Rust、Java、C、C++ 进行处理\n- **ContentRouter** — 智能压缩调度器，可根据内容类型自动选择最优压缩器\n- **自定义模型配置** — 支持 Claude 4.5 (Opus)、Claude 4 (Sonnet、Haiku)、o3、o3-mini，并为未知模型提供基于模式的推理支持\n- **OSS 评估套件** — 全面的准确性、延迟和压缩质量基准测试\n- **通用 JSON 压缩** — 在所有转换中提升 JSON 压缩效果\n\n### 亮点\n\n- 6 种压缩算法：SmartCrusher、CacheAligner、ContentRouter、CodeCompressor、LLMLingua、IntelligentContext\n- 生产就绪的代理服务器，具备缓存、限流和指标监控功能\n- 集成：LangChain、Agno、MCP、Strands、AWS Bedrock\n- 通过 LiteLLM + any-llm 支持 100+ 家 LLM 提供商\n\n### 安装\n\n```bash\npip install headroom-ai[all]==0.3.7\n```\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fchopratejas\u002Fheadroom\u002Fcompare\u002Fv0.3.0...v0.3.7","2026-02-24T04:55:24",{"id":176,"version":177,"summary_zh":178,"released_at":179},126459,"v0.3.0","## 新增功能\n\n### Bedrock 后端修复\n- 对于 Claude 4 及更高版本的模型，使用推理配置文件（`us.anthropic.*`）\n- 为 Claude Code 用户添加虚拟 API 密钥支持\n- 清晰化 VS Code 的设置说明\n\n### CLI 改进  \n- 基于 Click 的全新 CLI，新增内存管理命令\n- 命令包括：`headroom memory list|show|edit|delete|prune|purge|export|import`\n\n### 云服务商支持\n- 通过 LiteLLM 支持 AWS Bedrock\n- 支持 Google Vertex AI\n- 支持 Azure OpenAI\n\n### 错误修复\n- 修复 Python 3.10+ 测试中的 asyncio 事件循环错误\n- 为不稳定 CI 添加全局 httpx.ReadTimeout 处理程序","2026-01-31T00:50:44",{"id":181,"version":182,"summary_zh":183,"released_at":184},126460,"v0.2.15","## Headroom 演示视频\n\n观看 Headroom 的实际运行效果——它在演示大幅节省 Token 的同时，使用 Claude Code 分析自身的代码库。\n\n**您将看到：**\n- 多工具代理对话过程中实时的 Token 优化\n- 智能上下文压缩，同时保留关键信息\n- 在处理大型代码库时显著降低成本\n\n您可以下载该视频，或查看 README 文件中的嵌入式演示。","2026-01-20T06:26:10"]