Headroom：给 AI Agent 留出真正思考的空间

AI Agent 的瓶颈不总是“模型不够强”。很多时候，模型被塞进了太多噪音：几千行构建日志、重复的工具输出、庞大的 JSON、没有筛过的 RAG 片段、历史对话、整份源文件。上下文窗口看似越来越大，但真正困难的问题变成了：怎样让模型看到足够的信息，同时不被无关内容淹没？headroom正是围绕这个问题设计的。它不是一个新的聊天机器人，也不是一个新的代码助手，而是一个放在 AI Agent 和 LLM 之间的上下文压缩层。它的目标是让工具输出、日志、文件、RAG chunk 和对话历史在进入模型之前先变瘦，同时保留必要信息；如果模型需要原文，再通过检索机制取回。它解决的不是“摘要”，而是上下文工程把headroom简单理解为摘要工具会低估它。普通摘要通常只关心“把长文本变短”，但 Agent 场景更复杂：日志里可能只有一行错误最关键，JSON 里字段关系不能乱，代码压缩不能破坏结构，RAG 片段需要保留可追溯性，工具输出还可能在后续步骤被再次引用。因此headroom关心的是上下文工程。它要判断内容类型，选择合适的压缩策略，稳定提示前缀以提高 provider KV cache 命中率，把原始内容保存在本地，并在必要时让 LLM 通过工具取回细节。这比单纯截断上下文更可靠，也更接近真实生产系统的需求。工作流程：压缩、保留、按需取回可以把它的流程拆成四步。第一步，内容进入 Headroom。来源可以是工具输出、日志、RAG 结果、文件内容、对话历史，或者某个 Agent wrapper 捕获到的上下文。第二步，ContentRouter 判断内容类型。JSON、代码、自然语言、日志、图像相关内容，不应该使用同一套压缩策略。仓库和文档中提