Headroom Phase Gwrap-CLI 观测面设计——RTK 广度扩展、tokens_saved_rtk 数据平面与代理指标体系【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom本文基于 Headroom 重构计划Realignment中的 Phase G 规格文档完整讲解该阶段 3 个 PR 的设计与落地将 wrap-CLI 覆盖扩展到更多 agent、接通从未被写入的tokens_saved_rtk数据平面、补齐缓存命中率/压缩比/令牌校验等 Prometheus 观测面。读完本文你能理解 Headroom 为何坚持RTK 只放在 wrap-CLI 侧、不进代理的架构决策并能对照 当前 Rust 代理的指标目录 和 指标常量实现 完成指标查询、告警与容量排查。需要首先说明的一点该文档自身也标注了RTK 与 lean-ctx 已整体从 Headroom 中移除——headroom/rtk/、headroom/lean_ctx/两个包、所有--rtk/--context-tool标志、wrap 侧的 hooks 与 hint 文件注入、代理侧的rtk gain轮询均已删除headroom/context_tool_cleanup.py 负责卸载早期版本残留在用户磁盘上的持久化状态Claude Code hooks、PATH 符号链接、MCP 注册、标记围栏指令块等。因此下文中 RTK 相关章节应视为历史规格与决策依据而文档中保留下来的非 RTK 观测项cache-hit rate、compression ratio、token validation已经在 Rust 代理中真实落地是当前可直接使用的功能。一、Phase G 的目标、周期与关键架构决策规格文档给出的目标Goal可以拆成四个部分扩展 RTK 覆盖把 wrap-CLI 的 agent 覆盖面做宽历史目标随 RTK 移除而作废闭合tokens_saved_rtk数据平面修复字段存在但从未被填充的 bug历史目标字段本身保留增加每次调用的 RTK 指标历史目标已随 RTK 移除而取消补齐当时缺失的观测面缓存命中率、压缩比、令牌校验——这一项是当前代码库中真实存在的功能。日历周期约 1 周拆分为 3 个 PR。为什么 RTK 留在 wrap-CLI 侧而不是代理侧这是 Phase G 最值得保留下来的决策记录。依据 Agent F 审计和 2026-05-01 的用户指令在代理侧调用 RTK的方案被明确拒绝理由有三(a) 缓存热区风险对tool_result内容做压缩会碰到前缀缓存的缓存热区cache hot zone。整个 Realignment 计划的第一、第二条跨阶段不变量见 REALIGNMENT/INDEX.md就是代理不打算修改的字节必须与到达代理的字节 SHA-256 逐字节相等以及系统、工具定义、旧轮次、思考/压缩项永远不被修改。代理侧改写 tool_result 直接违背这两条。(b) 并行实现冲突与 crates/headroom-core 的 log_compressor 这类已有的日志压缩 transform 形成两套并行的实现。(c) 价值主张不同RTK 改写的是命令commandsHeadroom 压缩的是输出outputs二者解决的不是同一个问题。因此Integrate RTK with everything 被解读为扩展 wrap-CLI 广度 闭合数据平面 观测面。这个决策的意义在于未来任何贡献者在考虑要不要在代理里调用 RTK之前应先看到这份书面化的拒绝理由避免重复踩缓存热区的坑。二、PR-G1wrap-CLI 广度扩展历史章节该 PR分支realign-G1-wrap-more-agents风险 LOW约 800 LOC的目标是消除审计项 P5-62在已有的wrap claude/wrap codex/wrap aider/wrap copilot/wrap cursor模式之上新增headroom wrap cline、headroom wrap continue、headroom wrap goose、headroom wrap openhands四个子命令。每个 wrap 子命令遵循统一的四步模式该模式在 headroom/cli/wrap.py 中仍是现存实现的骨架确保 RTK 二进制已安装历史上为_ensure_rtk_binary()向 agent 的指令文件AGENTS.md / .cursorrules 等注入!-- headroom:rtk-instructions --标记围栏块启动代理或附着到一个已在运行的代理用代理的环境变量覆盖来启动 agent CLI。规划的文件清单均为历史计划其中 wrap 相关子命令现存活于headroom/cli/wrap.py的单文件实现中而非独立子包文件说明headroom/cli/wrap/cline.pyClineVS Code 内 agent指令文件为.clinerulesheadroom/cli/wrap/continue_dev.pyContinue.continue/config.json配置系统消息注入headroom/cli/wrap/goose.pyGooseBlock 的 CLI.goose/config.yamlheadroom/cli/wrap/openhands.pyOpenHands通过OPENHANDS_INSTRUCTIONS环境变量注入指令headroom/cli/wrap/__init__.py修改注册新子命令headroom/cli/main.py修改headroom wrap --help列出新 agente2e/wrap/run.py修改扩展 e2e runner 覆盖新 wrapper配套的冒烟测试约定了四个断言点——二进制已安装、指令已注入、代理已启动、对模拟 LLM 的调用可用外加幂等性约束test_wrap_idempotent_inject.py::test_double_injection_no_duplicate_block即重复注入不会产生重复的指令块。这一指令注入必须幂等的约束在 RTK 移除后依然有意义context_tool_cleanup.py 之所以能安全地把!-- headroom:rtk-instructions --围栏块当作 Headroom 私有资产去清理正是因为这是 Headroom 自己的围栏没有第三方会写它。验收标准测试通过手动执行headroom wrap cline -- claude-3-7-sonnet能拉起一个前面带代理、.clinerules里带 RTK 指令的 Cline 会话。回滚方式是git revert旧 wrapper 不受影响。文档还记录了延后项Roo Code、Devin 风格 CLI、裸gh copilot独立版、gpt-engineer、sweep、smol-developer 等 agent 留待采用度证明价值后以独立 PR 加入。三、PR-G2tokens_saved_rtk数据平面的设计历史章节字段仍在该 PR分支realign-G2-tokens-saved-rtk风险 LOW约 200 LOC针对审计项P5-60tokens_saved_rtk字段是死字段已分配、从未被填充。它的设计链路值得作为数据平面接线的范例拆解数据源定期轮询rtk gain --format json。代理侧的_get_rtk_stats当时位于headroom/proxy/helpers.py:132返回结构体RtkStats { invocations: int, tokens_saved: int, last_run_at: datetime }轮询结果带 5 秒的记忆化memoization避免每次记账都触发子进程。差值计算在 headroom/subscription/tracker.py 中新增_last_rtk_tokens_saved: int 0状态每次调用update_session_savings时拉取_get_rtk_stats()计算delta current.tokens_saved - self._last_rtk_tokens_saved把tokens_saved_rtkdelta写入贡献记录并更新自身状态。落点字段SubscriptionContribution定义在 headroom/subscription/models.py上的tokens_saved_rtk字段——该字段在 RTK 移除后仍然存在headroom/subscription/models.py与headroom/subscription/tracker.py中仍含rtk相关引用只是不再有生产路径为其赋非零值。规划的三个测试覆盖了数据平面的三类典型风险test_tokens_saved_rtk_populated_from_rtk_stats—— 字段确实从 RTK 统计中被填充test_delta_computed_correctly_across_polls—— 跨多次轮询的差值计算正确防止把累积值当增量重复记账test_rtk_failure_zero_delta_no_throw—— RTK 轮询失败时返回零差值而不是抛异常观测面不允许打断主记账链路。验收标准测试通过一次带 RTK 调用的 wrap 会话结束后tokens_saved_rtk 0。回滚语义也很干净git revert后该字段退回静默的零不影响其他功能。这段字段先于功能存在 → 被审计发现死掉 → 接线 失败降级为零差值的完整生命周期在 REALIGNMENT/01-bug-list.md 的 P5-60 条目中有对应的审计记录。四、PR-G3代理观测面——当前真实落地的核心这是 Phase G 中当前代码库中最值得关注的部分。规格列出的指标清单、告警语义、文件落点如下其中绝大多数已在 Rust 代理中实现。4.1 指标清单规格 → 现状对照指标类型规格中的定义现状wrap_rtk_invocations_total{tool}计数来自rtk gain --format json轮询tool标签是git/ls/cargo等被改写的命令已取消RTK 集成整体移除wrap_rtk_tokens_saved_per_session直方图会话结束时写入已取消同上proxy_cache_hit_rate_per_session直方图由每会话的usage.cache_read_input_tokens / total_input_tokens计算已落地是 Phase HPython 代理退役的金丝雀门禁proxy_compression_ratio_by_strategy{strategy, content_type}直方图每块压缩比已落地proxy_compression_rejected_by_token_check_total{strategy}计数压缩器跑了但输出未变小的次数PR-B4 引入PR-G3 保证导出已落地proxy_passthrough_bytes_modified_total{path}规范中写作 gauge必须恒为 0压缩开启路径之外非零即告警已落地以计数器实现proxy_rate_limit_remaining_*规范中写作一组从上游响应头提取已落地拆为 requests/tokens/input/output 四个 gaugeproxy_service_tier_count_total{tier}计数service_tier分布已落地proxy_response_status_count_total{status}计数incomplete / failed / cancelled / completed / in_progress已落地proxy_image_generation_call_log_redacted_total计数请求日志中多 MB base64 图片被脱敏的次数已落地Python 侧4.2 规格中的文件落点crates/headroom-proxy/src/observability/prometheus.rs—— 新增全部指标crates/headroom-proxy/src/sse/anthropic.rs—— 在message_delta处发出缓存命中率crates/headroom-proxy/src/sse/openai_responses.rs—— 在response.completed处发出crates/headroom-proxy/src/sse/openai_chat.rs—— 在最终 usage chunk 处发出crates/headroom-proxy/src/handlers/responses.rs—— 提取并记录service_tier当status incomplete时记录incomplete_details.reasonheadroom/proxy/request_logger.py——脱敏超过 1024 字节的 base64 字符串替换为base64 truncated, X bytesP4-45 图片日志脱敏也在此 PR 落地crates/headroom-proxy/src/observability/cache_hit_rate.rs与compression_ratio.rs—— 两个新模块当前在 crates/headroom-proxy/src/observability/ 目录中可查证docs/observability.md—— 记录每个指标的含义与漂移时的运维动作当前仓库中该文档已成文含完整指标目录与 PromQL 示例。规划的验收测试包括cache_hit_rate_emitted_per_session、compression_ratio_emitted_per_strategy、passthrough_bytes_modified_zero_when_no_compression、service_tier_logged、incomplete_status_logged_with_reason集成测试位于crates/headroom-proxy/tests/integration_metrics.rs以及 Python 侧的tests/test_image_log_redaction.py::test_large_base64_truncated——该测试文件在当前 tests/ 目录中真实存在。4.3 源码级实现证据指标名称与标签集中管理。从源码结构看所有 PR-G3 指标线名与标签键都集中在 crates/headroom-proxy/src/observability/metric_names.rsMETRIC_*是线名常量、METRIC_*_HELP是注册时的 HELP 文本、LABEL_*是标签键常量。文件头注释明确写道这是 Realignment 构建约束可配置每个指标名 标签词表集中定义在一处的落点——重命名一个指标时代码评审只需看一个文件。这个重命名只出现在一个 diff 里的工程约束比指标本身更值得借鉴。标签基数纪律Cardinality discipline。同一文件给出了有界标签词表的完整实现service_tier标签词表是严格闭集{auto, default, flex, on_demand, priority, scale}加一个哨兵值other。validate(raw)函数对入站 JSON 中的service_tier做大小写敏感匹配未识别的值被分桶到other并打tracing::warn!——原始入站值永远不会直接用作标签恶意客户端每请求发一个随机service_tier也无法击穿标签基数cardinality DoS同时线格式漂移会在日志中大声出现而不是被静默分桶。response_status是五值枚举completed / incomplete / failed / cancelled / in_progressin_progress是非终态入口——客户端中途断流时按最后观测到的状态计数观测方能看到请求是流中途关闭的。docs/observability.md 的Cardinality discipline一节进一步说明auth_mode是 3 值枚举、provider3 值、strategy与content_type都是static str来自压缩器的BlockAction::Compressed和headroom_core::transforms::ContentType而 Python 代理的model标签因为取自请求体客户端可控在记录时刻用MAX_DISTINCT_MODELSheadroom.telemetry.context封顶超出后并入other哨兵并打一次性警告。结论是不存在任何客户端可控值能驱动无界标签基数的代码路径。缓存命中率的发射闸门。proxy_cache_hit_rate_per_session直方图只在 SSE 流完整结束才采样Anthropic 侧要求StreamStatus::MessageStopOpenAI Chat 侧要求state.usage.is_some()最终 usage chunk 只在流完成时到达OpenAI Responses 侧要求terminal_status().is_some()。客户端中途断流时通道关闭但终态标志未置位——此时记录日志并跳过采样而不是把半截流的脏样本计入分布。从源码结构看这一H2 aborted-stream gate设计保证直方图里的每个样本都对应一次完整计费会话是缓存命中率数据可信的前提。按策略独立的压缩比H1 修复。proxy_compression_ratio_by_strategy每个策略使用该策略自己的before/after 令牌数采样经Outcome::Compressed.per_strategy_tokens从 live-zone manifest 穿透。修复前一个 body 上跑了多个策略时会把同一个聚合比值重复发给每个策略标签导致按策略分列的仪表盘读到垃圾数据。配合proxy_compression_rejected_by_token_check_total压缩器跑了但输出未严格变小、保留原文的次数运维可以区分策略根本没在缩和策略跑了但被令牌校验拒绝两种失效形态。缓存安全告警接线C2。proxy_passthrough_bytes_modified_total从proxy.rs发出当派发器承诺逐字节透传Outcome::NoCompression或Outcome::Passthrough但最终 body 字节长度发生变化时按字节差在请求路径标签下累加。检查发生在 prompt_cache_key 注入器之前因此注入器有意的字节修改不会触发告警——这正是规格中必须恒为 0压缩开启路径之外非零即告警语义的实现方式与 Realignment 的全局不变量第 1 条字节忠实形成实现 自检闭环。H3 force-zero 与启动形态。prometheus crate v0.13 的gather()会整体跳过空 MetricVec——家族第一次被带标签元组累加前连 HELP/TYPE 行都不出现。为了让运维从启动起就看到完整目录handle_metrics在首次抓取前用哨兵标签__init__对每个 counter/gauge MetricVec 做 0 触碰因此 PromQL 查询统一带{... ! __init__}过滤docs/observability.md 中的全部示例查询都包含该过滤。直方图不做 force-zero——合成的observe(0.0)会贡献真实样本、污染分位数读数所以两个直方图家族在首个真实会话后才出现在抓取结果中。配套的 H4 契约把prometheus依赖在 Cargo.toml 中精确钉版 0.13.4不用 caret并给出了升级后必须重跑的 5 步回归脚本。4.4 可复制的查询与运维动作规格文档的验收标准包含手动抓取/metrics能看到新指标家族。当前文档给出的可直接使用入口curl -s http://127.0.0.1:8787/metrics典型运维查询全部摘自 docs/observability.md均含__init__过滤# 缓存安全告警恒应为 0 sum(rate(proxy_passthrough_bytes_modified_total{path!__init__}[5m])) # 按策略 p50 压缩比 histogram_quantile(0.50, sum by (strategy, le) (rate(proxy_compression_ratio_by_strategy_bucket{strategy!__init__}[1h]))) # 压缩器跑了但被令牌校验拒绝的策略高比率 该压缩器需要调参 sum by (strategy) (rate(proxy_compression_rejected_by_token_check_total{strategy!__init__}[1h])) # 上游限流余量越小越接近被限流 proxy_rate_limit_remaining_tokens{provideranthropic}其中proxy_cache_hit_rate_per_session还承担了Phase H 金丝雀门禁的职责判断发布 Rust、退役 Python的脚本对 p50/p95/p99/均值四条查询全部与 Python 基线比对——单看一个分位数不够只在长会话尾部出现的回归会溜过中位数检查任何一条低于基线即门禁失败。五、SUPERSEDED 的部分与残留清理机制Phase G 文档开头的 SUPERSEDED 声明定义了它的历史边界值得逐条对照现状RTK 与 lean-ctx 全部移除headroom/rtk/、headroom/lean_ctx/包不存在headroom/context_tool_cleanup.py是当前代码库中处理该遗留的唯一模块。它的 docstring 完整记录了被移除集成的磁盘持久化足迹下载的rtkRust Token Killer与lean-ctx二进制、Claude CodePreToolUsehooks、PATH 上的符号链接、注入到十余个 agent hint 文件的标记围栏指令块、Claude Code 的 MCP 注册。清理策略的工程细节均出自 headroom/context_tool_cleanup.py 的文件级注释溯源判定只删 Headroom 安装或促使上下文工具安装的文件。MCP 条目的command、hook 脚本体只有在其路径落在 Headroom 管理 bin 目录内才视为 Headroom 的hook 条目命名~/.claude/hooks下已分类脚本时继承该脚本的判定保守原则~/.local/bin/{rtk,lean-ctx}仅当它是指向 Headroom bin 目录的符号链接时才被 unlink——用户自己的构建永不触碰JSON 配置解析失败时报告并跳过绝不覆盖手工编辑的笔误不能让用户丢配置工具自己对配置的备份原样保留幂等与一次迁移headroom wrap/headroom unwrap每次运行都会调用purge_context_tool_artifacts机器级清理hooks、二进制、MCP 注册在一个工作区内只做一次随后用.context-tools-purged印章文件标记完成避免每次 wrap 都重写机器级文件而项目/配置目录作用域的 hint 文件每次启动都检查因为下次启动可能位于不同项目或不同的CODEX_HOME明确承认的边界两个场景无法自动判定用户 PATH 上先于 Headroom 已有lean-ctx时写出的配置#1698 之后写入、只 exec 裸rtk而不引用管理路径的 hook文档选择记录为限制而不是强行修复——后者会留下一个静默空转的 hook#487、#1698 的已知残留。tokens_saved_rtk字段如前所述字段在 headroom/subscription/models.py 中保留RTK 轮询链路_get_rtk_stats随功能删除。docs/rtk-architecture.md规格中原计划新增该文档以书面化RTK 只留在 wrap-CLI 侧的决策RTK 移除时该文档随功能一起被删除Phase G 文档开头声明相关决策背景仍完整保留在本文引用的规格文档内。从源码结构看metric_names.rs第 97 行起的注释是这套先实现、后退役轨迹的最直接证据proxy_image_generation_call_log_redacted_total的 Rust 侧计数器因无生产发射点被移除图片脱敏的唯一真源在 Python 代理headroom/proxy/prometheus_metrics.py两个wrap_rtk_*名称彻底消失——因为它们测量的 RTK 集成已从 Headroom 中删除。六、Phase G 验收清单与审计项闭合规格文档末尾的验收摘要逐项标注现状wrap CLI 覆盖扩展到 cline/continue/goose/openhands ——历史项wrap 子命令本体保留RTK 相关步骤移除tokens_saved_rtk字段端到端填充 ——历史项字段保留轮询链路随 RTK 移除每次调用的 RTK Prometheus 指标 ——已取消每会话缓存命中率指标 —— ✅ 落地docs/observability.md metric_names.rs每块压缩比直方图 —— ✅ 落地令牌校验拒绝计数 —— ✅ 落地透传字节被修改告警 gauge —— ✅ 落地counter 实现告警语义不变限流头观测与导出 —— ✅ 落地4 个 gaugeservice_tier分布指标 —— ✅ 落地带闭集词表 other哨兵响应终态incomplete | failed | cancelled带原因记录 —— ✅ 落地图片 base64 日志脱敏 —— ✅ 落地Python 侧计数 1024 字节阈值替换docs/rtk-architecture.md决策文档 ——已随 RTK 删除。文档结尾声明Phase G 使审计项 P4-41、P4-42、P4-45、P5-58、P5-60、P5-61、P5-62、P6-68、P6-69、P6-72 退出未决清单审计项全文见 REALIGNMENT/01-bug-list.md其中 P5-60 即字段已分配、从未填充的tokens_saved_rtk。七、可复用的工程实践小结从 Phase G 规格与当前实现中可以提炼出四条在 LLM 代理/网关类项目里直接可迁移的做法观测面指标与全局不变量绑定把必须恒为 0的缓存安全指标透传字节被修改做成一等公民并接上告警使字节忠实这条架构不变量从文档承诺变成可被监控证伪的运行时断言标签基数纪律所有客户端可控的输入值一律经过闭集词表验证 哨兵分桶后再进标签原始值永不直接外泄为标签指标目录的启动形态契约force-zero 触碰让抓取形态从进程启动就可预测同时用精确钉版 回归脚本守护依赖库的实现定义行为退役功能的清理即产品功能删除后用溯源判定、幂等印章、保守跳过原则来处理用户磁盘上的持久化残留并把无法自动判定的边界显式写成已知限制——context_tool_cleanup.py 是这一模式的完整范本。如需继续深入建议的阅读顺序REALIGNMENT/INDEX.md跨阶段不变量与保留原语清单→ REALIGNMENT/01-bug-list.md被 Phase G 闭合的审计项原文→ docs/observability.md指标目录、PromQL 与接线细节→ crates/headroom-proxy/src/observability/metric_names.rs指标常量与标签词表源码。【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考