gglucass/headroom-desktop

# Headroom Desktop — 将 Claude Code & Codex 的 token 成本降低约 50% **Headroom 是一款 macOS 菜单栏应用，能将 [Claude Code](https://www.anthropic.com/claude-code) 和 [OpenAI Codex](https://openai.com/codex/) 的 token 成本降低约 50% —— 且完全不改变你的编码习惯。** 它运行着一条本地优先的优化流水线，对导致每次提示词膨胀的工具输出、日志和样板代码进行可逆压缩，从而让你已经付费的 AI 方案可发挥约 2 倍的效能。模型所需的任何内容都不会丢失 —— 它可以按需还原原始内容。 [](https://extraheadroom.com)  [](https://github.com/gglucass/headroom-desktop/releases/latest) ### 安装 1. 前往[最新发布版本](https://github.com/gglucass/headroom-desktop/releases/latest) 2. 在 macOS 上，下载 `.dmg` 文件（例如 `Headroom_0.2.9.dmg`） 3. 打开 DMG 文件，将 **Headroom** 拖入“应用程序”文件夹 4. 启动 Headroom —— 它会出现在你的菜单栏中，并引导你完成设置 Headroom 已经过签名和公证，macOS 在打开它时不会弹出 Gatekeeper 警告。 Linux 预览版构件已在同一发布页面提供。目前，它们最好被视为 Headroom 核心代理、Claude Code 路由和 RTK 流程的预览版。Linux 预览构建版本尚不支持 `Headroom Learn`。  Headroom 是一款本地优先的桌面托盘应用，它通过本地优化流水线路由你的编码客户端。其稳定目标平台是 macOS；Linux 构建目前处于实验阶段。它会安装并管理一个独立的 Python 运行时，打包经过验证的 token 节省工具，并直观展示节省分析 —— 所有这些都不会触及你的系统环境。 ## 工作原理 Headroom 常驻在你的菜单栏中，主要做三件事： 1. **安装受管理的 Python 运行时** 到 Headroom 专用的存储空间中 —— 与你的系统 Python 隔离，不会出现 `pip install --user` 造成的污染。 2. **串联 token 节省工具**（用于提示词优化的 `headroom`，用于 CLI 输出压缩的 `rtk`），部署在你的客户端和 LLM API 之间。 3. **为你展示具体数据** —— 每日和每月的节省图表、各客户端的 token 统计数据以及流水线健康状况。 该应用程序以轻量级的 Tauri 外壳（约几 MB）发布。重型 Python 组件会在首次启动时获取，并保存在 `~/Library/Application Support/Headroom` 中。 ## Headroom 在你的系统上做了哪些改动 在此完整披露 Headroom 写入的每个位置，以便你在安装前进行评估。应用程序中的安装界面会显示相同的列表，且卸载流程会撤销每一项操作。 **安装时：** - 将一个独立的 Python 运行时（约 2 GB）下载到 `~/Library/Application Support/Headroom` 目录下。你的系统 Python 不会受到影响。 - 向 `~/.claude/settings.json` 添加一个 `PreToolUse` 钩子，并在 `~/.claude/hooks/headroom-rtk-rewrite.sh` 放置一个脚本，以便 Claude Code 通过 Headroom 进行路由。在进行任何修改之前，都会写入一个带有时间戳的 `settings.json` 备份。 - 对于 Codex，向 `~/.codex/config.toml` 添加一个 Headroom provider 块，并向你托管的 shell 块添加一个 `OPENAI_BASE_URL` 导出，以便 Codex CLI 和桌面应用程序通过本地代理进行路由。TOML 块由 `# >>> headroom:... >>>` 标记包围，修改前会写入备份，并且现有的 Codex 线程会被重新标记为受管理的 provider。 - 创建 `~/Library/Application Support/Headroom` 目录，用于存储日志、缓存和各客户端的设置状态。 - 将你的 Headroom session token 存储在 macOS Keychain 中，服务名前缀为 `com.extraheadroom.headroom`。 - 如果你选择“登录时启动”，则会在 `~/Library/LaunchAgents/` 下安装一个 LaunchAgent plist 文件。否则永远不会添加。 - 向你的 shell 配置文件（`.zshrc`、`.zprofile` 等）添加一个受管理的块，将 Headroom 托管的 `bin` 目录（位于 `~/Library/Application Support/Headroom` 下）前置到 `PATH` 中，以便在终端中使用 `rtk`。每个受管理的块都由 `# >>> headroom:... >>>` 标记包围，如果你愿意，可以手动删除。 **退出（或暂停）时：** Headroom 会移除所有会拦截客户端的内容 —— Claude Code 钩子条目和钩子脚本、`ANTHROPIC_BASE_URL` 和 `OPENAI_BASE_URL` 重定向、`~/.codex/config.toml` 中的 Codex provider 块，以及受管理的 shell 块。Codex 线程会重新标记回其原生 provider。Claude Code 和 Codex 的行为将与启动 Headroom 之前完全一样。Python 运行时、日志和 Keychain 条目会保留在磁盘上，以便下次快速启动。 **卸载时（设置 → 卸载 Headroom）：** 上述所有内容都将被移除，包括 LaunchAgent plist、`~/Library/Preferences/com.extraheadroom.headroom*`、`~/Library/Caches/com.extraheadroom.headroom` 以及 Keychain 条目。在确认之前，应用程序中的卸载对话框会显示完整列表。 如果代理意外终止，看门狗会自动重启它；如果反复失败，它会自动暂停并移除拦截状态，以便你的客户端无需干预即可继续工作。 ## 内置工具 | 工具 | 功能描述 | 默认状态 | |------|-------------|---------| | [headroom](https://pypi.org/project/headroom-ai/) | 提示词优化流水线 | 必需 | | [rtk](https://github.com/gglucass/rtk) | 在 Claude Code 的 bash 命令到达上下文窗口之前重写它们，以去除无用信息 | 可选附加组件 | | [markitdown](https://github.com/microsoft/markitdown) | 在 agent 读取之前，将 PDF 和 Office 文档转换为干净的 Markdown | 可选附加组件 | | ponytail | 引导 agent 编写更精简、较少过度设计的代码 | 可选附加组件 | **工具收录政策：** 只有完全在本地运行、位于 Headroom 管理的存储空间内、且具有稳定 CLI 接口的工具才会被收录。没有云端依赖，不会修改宿主机的配置文件。详见 [`research/tool-compatibility-matrix.md`](research/tool-compatibility-matrix.md)。 ## 压缩基准测试 以下数据来自支持该优化流水线的 [headroom](https://github.com/chopratejas/headroom) 开源库，摘自已发布的基准测试页面。 ### 当前基准测试摘要 | 基准测试 | 测试内容 | 结果 | |-----------|---------------|--------| | Scrapinghub 文章提取 | 在移除样板内容的同时，从 181 个 HTML 页面中提取正文 | 0.919 F1, 98.2% 召回率, **94.9% 压缩率** | | SmartCrusher JSON 压缩 | 在压缩后的 100 条生产环境日志中查找一个严重错误 | 4/4 正确, **87.6% 压缩率** | | QA 准确率保留 | 对原始 HTML 和提取后的内容提出相同的问题 | 0.87 F1 对比 0.85 基线, 62% 精确匹配 对比 60% | | 多工具 agent 测试 | 使用压缩后的工具输出，4 工具 agent 调查内存泄漏 | 发送 6,100 对比 15,662 token, **76.3% 压缩率**，发现结果相同 | ### 基准测试详情 | 基准测试 | 设置 | 准确率 | 压缩率 | |-----------|-------|----------|-------------| | HTML 提取 | Scrapinghub 文章提取基准，181 个页面 | 0.919 F1, 0.879 精确率, 0.982 召回率 | 94.9% | | JSON 压缩 | 100 条生产环境日志，位置 67 处出现严重错误 | 4/4 正确答案 | 87.6% | | QA 准确率保留 | SQuAD v2 + HotpotQA，原始 HTML 对比提取后内容 | +0.02 F1，+2% 精确匹配 对比原始 HTML | — | | 多工具 agent 测试 | 拥有 4 个工具调查内存泄漏的 Agno agent | 与基线发现相同 | 76.3% | ### 哪些内容压缩效果好，哪些不好 | 内容类型 | 典型节省率 | 备注 | |-------------|-----------------|-------| | JSON 数组（搜索结果、API 响应、数据库行） | 86–100% | 主要用例 | | 结构化日志 | 82–95% | 始终保留错误和异常 | | Agent 对话（25–50 轮） | 56–81% | | | 纯文本 / 文档 | 43–46% | 仅节省成本，会增加延迟 | | 源代码 | 大部分直接透传 | 活动消息中的代码默认受保护 —— 详见限制说明 | ### 需要了解的限制 - **代码压缩刻意保持保守。** 最近消息（默认为最后 4 条）中的代码，以及任何用户询问关于代码的问题（如 `analyze`、`debug`、`fix` 等）的对话，都不会被压缩。通过代码节省的资源来自于丢弃旧的、不再相关的消息 —— 而不是剥离函数主体。 - **跳过短内容。** 少于 5 个项目的数组和少于 200 个 token 的内容将保持不变直接通过。 - **文本压缩 (LLMLingua) 会增加延迟。** 首次使用时需要下载约 2 GB 的模型，并且在速度快的模型上无法达到收支平衡点。适用于降低成本，而非提升速度。 - **纯文本 RAG 结果直接透传。** 压缩针对的是工具输出和 JSON；用户消息中的纯文本不会被压缩。 完整的方法论和可复现的基准测试：[chopratejas/headroom 基准测试](https://chopratejas.github.io/headroom/benchmarks/) · [限制说明](https://chopratejas.github.io/headroom/LIMITATIONS/) ## 有趣的设计决策 - **对宿主机零污染。** Headroom 拥有自己完整的依赖树。卸载该应用程序后，你的 shell、Python 和 PATH 将完全恢复原样（除了可选的 `rtk` PATH 添加项，该操作是可逆的）。 - **Rust 外壳，Python 大脑。** Tauri/Rust 层负责处理托盘生命周期、受管理的安装、客户端检测和更新交付。优化工作在 Python 中进行，这也是 headroom 生态系统所在之处。 - **支持回滚的客户端配置。** 当 Headroom 修改受支持客户端的配置（例如 Claude Code 设置）时，它会首先写入备份。禁用或卸载时会还原原始配置。 - **开源外壳，私有网络。** 桌面应用程序采用 MIT 许可协议并开源。营销网站和账户后端位于一个单独的私有仓库中 —— 因此，贡献者无需后端访问权限即可构建并运行完整的桌面体验。 ## 项目结构 ``` src/ React + Tauri frontend (tray UI, onboarding, savings dashboard) src-tauri/ Rust backend state.rs Dashboard state and data shaping tool_manager.rs Bootstrap, Python runtime, and tool installation client_adapters.rs Client detection and guided setup insights.rs Daily local recommendation engine research/ Tool vetting artifacts and compatibility matrix docs/ Architecture notes, release process ``` ## macOS 发布流程 更新通过 Tauri 的内置更新程序在 App Store 之外发布。该应用程序会在后台轮询 GitHub Releases，在安装前进行提示，并请求重启以完成安装。本地 DMG 构建和 GitHub Actions 工作流都会运行 `./scripts/verify-release.sh` —— 失败的测试将在发布任何内容之前阻止构建。 有关完整的发布设置，请参阅 [`docs/macos-release.md`](docs/macos-release.md)。 ### 分支与版本控制 使用 `./scripts/bump-version.sh ` 可以一次性更新所有四个版本文件（`package.json`、`package-lock.json`、`src-tauri/tauri.conf.json`、`Cargo.toml`）。接受 `X.Y.Z` 或 `X.Y.Z-rc.N` 格式（前导 `v` 会被去除）。 CI 中配置了两个发布渠道： - **`main`** —— 稳定渠道。使用默认下载的用户会从此处获取更新。版本号必须是普通的 `X.Y.Z`。受分支保护：拒绝直接推送；更改只能通过 PR 合并。 - **`staging`** —— 候选发布 (RC) 渠道。通过指向滚动 `staging` GitHub release 的单独构建进行安装。版本号必须是 `X.Y.Z-rc.N`。 开发工作在 `feature/*` 分支上进行，随后合并到 `staging` 进行测试。稳定版的晋升会通过一个发布 合并到 `main` 分支（见下文）。 **候选发布 (RC) 流程：** 1. 将 feature 分支中的工作合并到 `staging`。 2. 将 `package.json` + `src-tauri/tauri.conf.json` 的版本升级至 `X.Y.Z-rc.N`（例如 `0.2.44-rc.1`）并推送。`.github/workflows/release-macos-staging.yml` 会发布一个带有版本号的预发布标签 `vX.Y.Z-rc.N`，并将构件镜像到滚动的 `staging` release 中。 3. 测试机会自动更新（它内置了两个 endpoint，并且因为其安装版本带有 `-rc` 后缀，会自动将路由指向 staging endpoint）。 4. 如果出现问题，将版本升级至 `rc.2` 并再次推送。重复此操作，直到构建成功。 **晋升至稳定版：** `main` 受分支保护，因此晋升需通过发布 PR 进行。合并 **必须** 是一个合并提交（不是压缩合并，也不是变基合并），以便 staging 的提交 —— 包括 rc 标签的提交 —— 保留在 `main` 的历史记录中，从而通过 rc-祖先检查。 1. 从经过验证的 `staging` 末端切出一个发布分支：`git checkout -b release/X.Y.Z staging`。 2. 在该分支上，运行 `./scripts/bump-version.sh X.Y.Z`（去除 `-rc.N`），进行提交并推送。 3. 发起一个从 `release/X.Y.Z` 到 `main` 的 PR。 4. 使用 **“Create a merge commit”** 进行合并。`.github/workflows/release-macos.yml` 会在推送到 `main` 时触发，并发布稳定版。 5. 主工作流 **强制要求** 存在一个 `vX.Y.Z-rc.N` 预发布版本，且其提交是稳定版（合并）提交的祖先。否则，构建将失败。这保证了稳定版只会发布通过 staging 渠道测试过的代码。 6. 稳定版构建发布后，主工作流会将滚动的 `staging` release 重新指向稳定版 DMG。测试机接收到该更新并安装后 —— 因为新版本是普通的 `X.Y.Z` —— 会自动将未来的所有检查切换到稳定版 endpoint。 7. 删除 `release/X.Y.Z` 分支。 **绕过 rc 检查：** 对于无法进行 staging 周期的热修复，请在 **PR 合并提交信息** 中包含 `[skip-rc-check]`（工作流读取的是合并提交的信息，而不是版本升级的提交信息）。最简单的方法：将 `[skip-rc-check]` 放在 PR 标题或正文第一行，以便 GitHub 将其包含在自动生成的合并提交中。请谨慎使用 —— 这个防护机制的存在是为了防止发布未经测试的稳定版。 ## 开发 ``` npm install npm run tauri dev ``` 要启用实时身份验证和定价流程，请创建一个 `.env`： ``` HEADROOM_ACCOUNT_API_BASE_URL="https://extraheadroom.com/api/v1" HEADROOM_APTABASE_APP_KEY="REPLACE_WITH_APTABASE_APP_KEY" VITE_SENTRY_DSN="REPLACE_WITH_SENTRY_DSN" VITE_HEADROOM_SALES_CONTACT_URL="mailto:hello@extraheadroom.com" VITE_HEADROOM_CONTACT_FORM_URL="https://extraheadroom.com/contact_request" ``` 有关完整列表（包括发布构建使用的可选更新程序和 macOS 签名密钥），请参阅 [`.env.example`](.env.example)。在生产环境 DMG 构建中，请设置与 GitHub Actions 仓库变量相同的密钥。 运行测试： ``` npm run test:all # frontend + Rust cargo test --manifest-path src-tauri/Cargo.toml # Rust only ``` 清理 Rust 构建产物（`src-tauri/target/` 目录会快速膨胀）： ``` cargo clean --manifest-path src-tauri/Cargo.toml ``` ## 依赖固定 `headroom-ai` 在首次运行时会从特定的固定 wheel 包中安装。自动升级已被禁用 —— 该应用程序附带一个已知良好的版本，并且只有在发布构件本身更新时才会更改其安装内容。 [`src-tauri/src/tool_manager.rs`](src-tauri/src/tool_manager.rs) 中的三个常量控制着固定状态： - `HEADROOM_PINNED_VERSION` —— 版本字符串（例如 `"0.8.2"`）。必须与 wheel URL 匹配。 - `HEADROOM_PINNED_WHEEL_URL` —— 要下载的准确 PyPI wheel URL。 - `HEADROOM_PINNED_SHA256` —— wheel 的 SHA-256 校验值，在下载后进行验证。 要升级 `headroom-ai`：同时更新这三个常量，运行构建并发布新的桌面版本。用户会在桌面更新流程中自动获取新的 Python 依赖 —— 没有单独的 PyPI 检查或后台升级路径。 其他捆绑组件（`rtk`、Python 独立运行时、供应商 wheels 索引）以相同的方式进行固定 —— 每个平台一个版本、一个校验值。

标签：AI编程辅助, SOC Prime, 令牌压缩, 可视化界面, 开发工具, 成本优化, 本地代理, 桌面应用, 逆向工具, 通知系统