拓冰网站定制 
Headroom Rust 重构开发指南从 Cargo Workspace 到 PyO3 绑定、Parity 测试与 CCR 多后端部署【免费下载链接】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/headroomHeadroom 正在将核心压缩逻辑从 Python 逐步移植到 Rust仓库根目录的 RUST_DEV.md 是这次 Rust 重写唯一新增的顶层开发文档。本文以该文档为骨架结合 Cargo.toml、Makefile 与各 crate 源码完整拆解 Rust workspace 的布局与构建体系、headroom-proxy透明反向代理的部署方式、maturin PyO3 的 Python 接线、Rust↔Python parity 对拍机制以及多 worker 部署下 CCR 存储分片的选型策略帮助你在这条 Python → Rust 迁移线上开发、验证与排障。一、Workspace 布局五个 crate 各司其职整个 Rust 侧由根目录 Cargo.toml 定义的 Cargo workspace 承载共五个成员Cargo.toml # workspace 根 rust-toolchain.toml # 固定 stable rustc附 rustfmt clippy crates/ headroom-core/ # 库共享类型 transform trait 面 headroom-proxy/ # 二进制axum /healthzPhase 2 起持续扩展 headroom-py/ # PyO3 cdylib向 Python 暴露 headroom._core headroom-parity/ # 库 parity-run CLI用于 Python 对拍测试 headroom-simulators/ # 二进制确定性的本地上游桩供 proxy 测试 tests/parity/ fixtures/transform/*.json # 从 Python 实现的录制输出Phase 1 移植的对拍基准 recorder.py # Python 侧 fixture 录制器 scripts/record_fixtures.py # 运行录制器的入口各 crate 的实际职责可以从源码结构中印证headroom-core是全部压缩算法的宿主crates/headroom-core/src/transforms/ 下包含smart_crusher/、text_crusher/、code_compressor.rs、diff_compressor.rs、log_compressor.rs、search_compressor.rs、kompress.rs等实现以及signals/错误信号检测、ccr/压缩后内容检索存储、tokenizer/tiktoken/HF/估算器等子系统headroom-proxy是 axum 实现的透明反向代理crates/headroom-proxy/src/ 下已有 SSE 帧处理、WebSocket 转发、Bedrock/Vertex 原生路由、缓存稳定化等模块headroom-py是 PyO3 cdylibcrates/headroom-py/Cargo.toml 中crate-type [cdylib]库名即_core把headroom-core的能力暴露为 Python 的headroom._core模块headroom-parity依赖headroom-core直接跑对拍不依赖 pyo3因此不需要 Python 环境即可运行headroom-simulators提供确定性的本地上游桩用于 proxy 集成测试。为什么default-members要排除 headroom-pyCargo.toml 中default-members刻意不包含headroom-py这是 RUST_DEV.md 明确解释的构建陷阱PyO3 cdylib 依赖extension-modulefeature 让 pyo3不链接libpython否则 Python 解释器无法import它。如果把它放进默认成员cargo build --workspace会尝试按普通库的方式链接它在缺少宿主 Python 解释器的机器上直接失败。因此cargo build --workspace裸命令跳过headroom-py由 maturin 负责它的构建cargo test --workspace仍会运行其测试Cargo.toml 顶部注释说明 pyo3 在测试场景可以动态链接。配套地rust-toolchain.toml 把工具链固定在channel 1.95.0并带rustfmt、clippy组件。文档记录了固定版本的原因2026-04-27 曾发生 CI永远拿最新 stable与本地开发机版本漂移导致 clippy 新 lint 只在 CI 爆红的事故固定后本地通过 CI 通过。升级流程是改 channel 字符串 →rustup update→make ci-precheck→ 修复新 lint → 提交。serde_json 的 feature 选择直接服务于字节保真workspace 依赖里serde_json启用了preserve_order、arbitrary_precision、raw_value三个 featureCargo.toml 有详细注释这与 RUST_DEV.md 的对拍主题直接相关preserve_order让Value::Object用 IndexMap 保持 JSON 键序smart_crusher移植依赖它与 Pythonstr(dict)的插入序保持一致arbitrary_precision保留原始数字字面量1.0不会塌缩为1大整数不经过 f64支撑未改动字节必须字节保真透传的架构不变量raw_value暴露未解析的 JSON 片段类型供转发路径对未修改的messages[*]条目做精确字节拷贝。二、常用命令Makefile 目标与 CI 前置门禁开发机不装just仓库根 Makefile 是命令的 source of truth并被.github/workflows/rust.yml镜像。RUST_DEV.md 中列出的核心目标如下目标作用make testcargo test --workspacemake test-parity用 maturin 构建headroom-py后运行parity-run runmake benchcargo bench --workspacemake build-proxyrelease 构建headroom-proxystrip 后打印体积make build-wheelmaturin build --release -m crates/headroom-py/Cargo.tomlmake fmtcargo fmt --allmake lintcargo fmt --checkcargo clippy --workspace -- -D warnings对照 Makefile 源码可以看到实际仓库比文档表格更全make verify-rust-core一条命令完成 maturin-develop 符号链接 导入验证。注释标明它用于排查proxy 静默回退到纯 Python 模式的问题proxy 启动 lifespan 时也会跑同样的检查make ci-precheck在git push之前本地复跑 CI 全部门禁——ci-precheck-rustfmt check clippy 全量测试、ci-precheck-python先构建 Rust 扩展再跑 smart_crusher 影响面的一批 pytest见 Makefile 第 109-127 行列出的 11 个测试文件、ci-precheck-commitlint对origin/main以来的提交做 conventional commit 校验make install-git-hooks一次性安装 pre-commit / commit-msg / pre-push 钩子make build-e2e-wrap/run-e2e-wrap构建并运行 wrap-e2e 的 Docker 镜像。一个值得注意的实现细节Makefile 中test-parity目标实际执行的是cargo run -p headroom-parity -- run --fixtures tests/parity/fixtures不再包含maturin develop步骤——因为 headroom-parity 的对拍器直接调用 headroom-corePhase 0 明确不从 Rust 调 Python这一步的删除把 Python 工具链从 CI parity 任务中剥离了。阅读文档时应以 Makefile 当前实现为准。三、运行 headroom-proxy透明反向代理与部署 runbookheadroom-proxy是一个透明反向代理。按其定位Phase 1 阶段它将 HTTP/1.1、HTTP/2、SSE 与 WebSocket 流量原样转发到配置的上游——不带任何 provider 逻辑。预期部署形态运维把现有 Python proxy 放到私有端口把headroom-proxy放在原公开端口并指向它终端用户无感知。构建与本地运行# 构建 make build-proxy ./target/release/headroom-proxy --help # 指向本地上游运行 ./target/release/headroom-proxy \ --listen 0.0.0.0:8787 \ --upstream http://127.0.0.1:8788 # 健康检查 curl -s http://127.0.0.1:8787/healthz # {ok:true,...} curl -s http://127.0.0.1:8787/healthz/upstream # 上游可达时返回 200这两个端点的实现见 crates/headroom-proxy/src/health.rs/healthz只要进程活着就返回{ok:true,service:headroom-proxy}/healthz/upstream则主动 GET 上游的/healthz上游 2xx 才返回 200否则 503。源码注释还解释了为什么用url.set_path(/healthz)而非相对 join——避免上游 URL 带非斜杠路径如http://localhost:8788/api时按 RFC 3986 把api段吃掉。Phase 1 切换 runbook# 1. 把 Python proxy 挪到私有端口例如 8788 HEADROOM_HOST127.0.0.1 HEADROOM_PORT8788 python -m headroom.proxy # 或你现有的启动器 # 2. 在原公开端口8787跑 Rust proxy 指向它 ./target/release/headroom-proxy --listen 0.0.0.0:8787 --upstream http://127.0.0.1:8788 # 3. 终端用户继续打 :8787无变化。 # 4. 验证透传 curl -si http://127.0.0.1:8787/v1/models # 5. 回滚 停掉 Rust proxy把 Python 重新绑回 8787。配置参数完整表参数环境变量默认值说明--listenHEADROOM_PROXY_LISTEN0.0.0.0:8787绑定地址--upstreamHEADROOM_PROXY_UPSTREAM必填代理转发的目标 base URL--upstream-timeout600s端到端请求超时为流式响应刻意放宽--upstream-connect-timeout10sTCP/TLS 连接超时--max-body-bytes100MB缓冲场景的上限流式路径不受此限--log-levelinfoRUST_LOG风格过滤--rewrite-host/--no-rewrite-hostrewrite是否把 Host 头改写为上游默认改写--graceful-shutdown-timeout30s收到 SIGTERM/SIGINT 后等待在途请求的时间用调用遥测决定下一个移植对象在把另一个 Python 压缩器移植到 Rust 之前RUST_DEV.md 建议先看实际调用量——Python proxy 已在/statsheadroom.proxy.prometheus_metrics上暴露按 transform 维度的遥测# 按调用次数排序的压缩器本进程生命周期内 curl -s http://127.0.0.1:8788/stats | jq .compressions_by_strategy # { # intelligent_context: 12453, # smart_crusher: 487, # search: 312, # diff: 28, # code: 0, # ← 从未触发移植可以安全推迟 # ... # } # 按 transform 的耗时avg/max/count curl -s http://127.0.0.1:8788/stats | jq .pipeline_timing # 每个策略贡献的 token 节省 curl -s http://127.0.0.1:8788/stats | jq .tokens_saved_by_strategy这是 2026-04-30 审计清理 PR 建议采用的移植优先级数据源调用量为零或近零的策略是推迟候选处于热路径的策略无论 LOC 多少都应移植。保留路径/healthz与/healthz/upstream由 Rust proxy 拦截不会被转发。运维不要把真实上游路由命名为这两个路径其余一切路径都是 catch-all 转发。四、Maturin Python 接线headroom-py 与headroom._coreheadroom-py是一个 PyO3 cdylib向 Python 暴露headroom._core。extension-modulefeature 是按需开启的见 crates/headroom-py/Cargo.toml 第 30-32 行这样普通的cargo build --workspace不会在缺少 libpython 的机器上尝试链接它。该 crate 还通过build.rs在 Linux/glibc 上编译一份 glibc-2.38 兼容 shimglibc_compat.c保证 wheel 在较老 glibc 的系统上可加载。首次搭建建议干净 venvpython3.11 -m venv /tmp/hr-rust-venv source /tmp/hr-rust-venv/bin/activate pip install maturin cd crates/headroom-py maturin develop # editable 开发构建安装 headroom._core cd /tmp # 重要先离开仓库根目录 python -c from headroom._core import hello; print(hello()) # headroom-core为什么要cd /tmp仓库根目录同时含 Python 的headroom/包。在仓库根目录跑冒烟导入会让 Python 把headroom解析到./headroom/__init__.py完整 SDK拉起重依赖而不是 maturin 安装的轻量命名空间包。测试要么在仓库根目录之外运行要么确保headroom已安装进同一个 venv此时 maturin 装的_core.so会落在它旁边两个导入都能正确解析。冒烟入口hello()的绑定在 crates/headroom-py/src/lib.rs它只是透传headroom_core::hello()用于验证链接。这个绑定层远不止冒烟测试。从 crates/headroom-py/src/lib.rs 可以看出它是 PythonContentRouter热路径上的 Rust 后端桥DiffCompressor、SmartCrusher含crush、crush_array_json、compact_document_json、ccr_get等方法、LogCompressor、SearchCompressor、TextCrusher都以 1:1 镜像 Python dataclass 的构造签名暴露配置对象如PySmartCrusherConfig接受与 Python 同名的全部 kwarg便于 shim 用SmartCrusherConfig(**asdict(py_cfg))直通。文件顶部注释说明了为什么选进程内 PyO3 而不是 IPC/RPCContentRouter 在 proxy 热路径上压缩任何子进程/RPC 桥都会吞掉想省下的成本而 PyO3 调用只有微秒级开销。热方法crush、compress等统一采用py.detach(...)模式释放 GIL让压缩运行期间其他 uvicorn worker/asyncio 任务继续推进。Release wheelmake build-wheel # wheel 落在 target/wheels/CI.github/workflows/rust.yml通过PyO3/maturin-action构建 linux-x86_64、macos-arm64、macos-x86_64 三个平台的 wheel 并作为 artifact 上传。wheel 体积优化是 Cargo.toml 中[profile.release]注释记录的一段实战项目撞过 PyPI 单项目 10 GB 累计存储上限事后剖析发现每个 wheel 约 18 MB 中有约 6.4 MB 是纯调试元数据ELF 的.strtab/.symtab。于是 release profile 采用strip symbolslto thincodegen-units 1把 Linux wheel 压到约 10-11 MB同时刻意不设置panic abort——proxy 是长期存活的异步进程一个坏请求触发 abort 会杀掉整个代理并断开所有并发客户端。另有[profile.ci]继承 release 但关闭 LTO、放宽 codegen-units供 CI 快速产出可用扩展。五、Parity 对拍机制Rust 移植正确性的守门员crates/headroom-parity持有 Rust↔Python 的 oracle 基础设施crates/headroom-parity/src/lib.rs 即其全部核心JSON fixtures位于tests/parity/fixtures/transform/schema 为{ transform, input, config, output, recorded_at, input_sha256 }与 tests/parity/recorder.py 的录制端一一对应TransformComparatortraitlib.rs每个 transform 一个实现接收 fixture 的 input/config产出与fixture.output比较的 JSON 值未实现的 stub 返回Err(...)harness 将其标记为Skipped而不是 panic 或 diff——stub 不能弄红 parity 门禁parity-runCLIcargo run -p headroom-parity -- run [--only TRANSFORM]负向测试lib.rs 的单测harness_reports_diff_for_divergent_comparatorlib.rs用一个恒定输出rust-output的假比较器对期望python-output的 fixture 运行证明 harness 在真实移植落地之前就能检测到分歧输出。当前比较器实况与几个工程细节文档写于 Phase 0/1 交界当时的 stub 是cache_aligner和ccr。从当前 lib.rs 的builtin_comparators()看已落地的真实比较器扩展为八个log_compressor、diff_compressor、tokenizer、smart_crusher、content_detector、text_crusher、kompress、code_aware_compressorstub 机制stub_comparator!宏仍保留给未实现项。实现中有三处值得借鉴的稳健性设计f64 归一化lib.rs 的compare_fixtureserde_json 对json!(f64)构造与从 fixture JSON 解析存在 1 ULP 的不对称比较前把实际输出走一遍to_stringfrom_str的有损解析让两边经过同一个解析器避免浮点噪声误报fixture 完整性校验load_fixtures_for会检查 fixture 声明的transform字段与其所在目录名一致不一致直接报错lib.rs模型类比较器离线运行KompressComparator只从本地 HuggingFace 缓存解析 ONNX 模型与 tokenizer绝不联网本地无模型时返回Errharness 把对应 fixture 全部标Skipped而不是失败。重新录制 fixturesource .venv/bin/activate # 主 Python SDK venv python scripts/record_fixtures.py # 底层用 tests/parity/recorder.py ls tests/parity/fixtures/*/ | sort | uniq -c当前 tests/parity/fixtures/ 下已积累 8 个 transform 目录其中 tokenizer 38 个、smart_crusher 16 个、diff_compressor 22 个、log_compressor 18 个等。录制器通过 monkey-patch 进程内的 transform 类见 tests/parity/recorder.py 的record_all()抓输出不修改headroom/下任何文件。六、退役 Python 组件的已知回归追踪Stage 3b/3c.1b 的退役删除了DiffCompressor与SmartCrusher的 Python 源码替换为 PyO3 委托 shim。2026-04-28 的审计发现退役时部分子系统被静默断开RUST_DEV.md 专设一节追踪每个缺口及其处置状态。这部分是维护者最应精读的章节SmartCrusher 四个子系统的处置表子系统状态跟踪测试TOIN 学习回路2026-04-28 重接。shim 的crush()与_smart_crush_content()在真实压缩后调用toin.record_compression()按strategy ! passthrough过滤掉 JSON 重规范化best-effortTOIN 失败仅 debug 级日志、不中断压缩tests/test_smart_crusher_toin_attachment.pyCCR marker 开关2026-04-29 端到端生效。RustSmartCrusherConfig新增enable_ccr_marker: boolcrush_array在发出ccr:HASH标记文本与 CCR store 写入前检查它。Python shim 用ccr_config.enabled and ccr_config.inject_retrieval_marker翻转该值——两个 Python 开关合并成同一个 Rust 门因为任一关闭时存储 payload 都没有意义。范围仅限 row-drop 哨兵路径tests/test_smart_crusher_toin_attachment.pycrusher.rs内enable_ccr_marker_*测试自定义相关性 scorer以 fail-loud 方式关闭2026-04-29。relevance_config/scorer构造参数保留在签名里以维持源码兼容但任一非 None 时 shim 抛NotImplementedError——静默丢弃用户提供的 scorer 是教科书式静默回退缺陷。完整管线等待 Stage-3c.2 的相关性 crate Python 桥test_custom_*_arg_raises_not_implemented按工具的 TOIN 学习钩子部分重接。_smart_crush_content接收tool_name并把它织入 TOIN 记录目前只改善query_context聚合尚不驱动按工具覆盖test_smart_crush_content_records_to_toinenable_ccr_marker这个字段在当前 PyO3 绑定中可以确认存在——crates/headroom-py/src/lib.rs 中SmartCrusherConfig构造签名的默认值就是enable_ccr_marker true。DiffCompressor子系统状态自适应上下文窗口逐字节生效parity fixture 锁定TOIN 集成本来就没有——DiffCompressor 经由 ContentRouter 的_record_to_toin记录非 SmartCrusher 策略本来就会走该路径无回归Phase 3e.1signals/trait 模块与 KeywordDetectorPython 的error_detection.py正则注册表退役后以 trait 分层tier体系在crates/headroom-core/src/signals/重生crates/headroom-core/src/signals/mod.rs完整架构见 crates/headroom-core/src/signals/README.md。要点按粒度划分 traitLineImportanceDetector已上线ContentTypeDetector与ItemImportanceDetectorI等其消费者被触碰时再落地TieredT组合子tiered.rs组合而非继承未来 ML 检测器作为新 tier 插入不需要改KeywordDetector或任何调用方只有一个具体实现KeywordDetectoraho-corasick。按项目无静默回退规则没有 NoOp/stub 实现——未来的 tier 必须带着真实实现落地顺手修掉的 bugERROR_KEYWORDS正则补齐timeout|abort|denied|rejected此前与关键词集漂移token从SECURITY_KEYWORDS中移除在每次 LLM 指标引用上误报。两侧修复同步——Python 侧的 shim 会基于 Rust 暴露的关键词表重新编译正则配套的规范化扩展路径文档把 BGE 分类头——在已加载的bge-small-en-v1.5embedder 之上做 384 维 → 4 类 softmax——记录为天然的 ML tier另保留两个开放备选ONNX 蒸馏 tinyBERT、基于词汇特征的逻辑回归。排期中Phase 3g —— 压缩管线形式化issue #315战略决策2026-04-29在 Phase 3e压缩器移植与 Phase 3fRust MCP 脚手架收尾后把先无损 → 再有损 → 再 CCR的顺序形式化为横切编排器CompressionPipelineLosslessTransform/LossyTransformtrait落在crates/headroom-core/src/pipeline/现有压缩器重构为可插拔 transform 的组合。关键设计选择是用 parser 处理结构在散文/结构边界处交给模型。文档明确警告3e/3f 完成前不要开始编码。观察清单潜在回归尚未审计CCRConfig.enabledFalse端到端 ——2026-04-29 已关闭enabledFalse与inject_retrieval_markerFalse都折叠到同一个 Rustenable_ccr_markerFalse门无 marker、无 store 写入SmartCrusherConfig.use_feedback_hintsFalse—— 配置字段已转发到 Rust但禁用路径在 Rust 内部的生效情况尚未用 parity fixture 验证。文档要求上述任何一项变化时同时更新本节与对应测试文件shim 的 docstring 也引用本节保持三处一致。七、Phase 0 遗留 Blockers这些是 Phase 0 的已知限制记录在此以免 Phase 1 重新踩坑cache_alignerfixturesCacheAligner.apply()签名为(messages, tokenizer, **kwargs)而Tokenizer是 provider 相关的最廉价的NoopTokenCounter/TiktokenTokenCounter构造也要拉headroom.providers.*连带完整 observability 栈如 opentelemetry。录制器只在 tokenizer 可廉价构造时记录cache_aligner否则记 blocker 并跳过见 recorder.py 的_build_cache_aligner_tokenizerccr不是一个类仓库里有CCRToolInjector、CCRResponseHandler、CCRToolCall、CCRToolResult等而非单一CCR类。录制器瞄准与 Rust 移植最对等的编码风格入口CCRToolInjector.inject_tool与CCRResponseHandler.parse_response若 Phase 1 想要不同的切分应相应更新recorder.py::record_allpre-commit 钩子噪声scripts/sync-plugin-versions.py每次提交都会改动.claude-plugin/marketplace.json、.github/plugin/marketplace.json和plugins/headroom-agent-hooks/**/plugin.json。改动无害但 Phase 0 每个提交都会带上——Phase 1 无需特殊处理让钩子跑即可rust-toolchain.toml现已固定channel 1.95.0此前跟踪stable让 CI 跑在本地开发机之前——2026-04-27 事故的修复项。已解决保留此处作为历史记录。八、多 worker 部署CCR 分片问题与后端选型状态更新现已有两个持久化 CCR 后端可选一旦选定持久化后端只能用单个--workers 的建议就不再适用。crates/headroom-core/src/ccr/backends/ 提供CcrStoretrait 的三个实现选择逻辑由backends::from_config在启动时依据CcrBackendConfig完成后端适用场景持久化多 worker 安全InMemoryCcrStore测试、单 worker 原型否否SqliteCcrStore默认单实例生产 / 单机集群是文件是需 sticky sessionRedisCcrStoreopt-in多主机 / 水平扩展生产是Redis是任意层无需 sticky从 backends/mod.rs 的from_config实现可以确认两个关键行为初始化失败必须上抛给调用方对应项目feedback_no_silent_fallbacks.md规则——DB 路径配错或 Redis URL 不可达会中止启动而不是静默降级到内存后端feature 门控的 Redis 后端若未编译进返回显式的UnsupportedBackend错误提示用--features redis重新构建。返回成功即代表后端已通过就绪自检SQLite schema 就位、Redis PING 返回 PONG。CcrBackendConfig::sqlite_default使用默认 30 分钟 TTL。各后端何时适用SqliteCcrStore是新部署的默认。DB 文件在本地磁盘同一主机上多个 worker 通过 SQLite WAL 模式锁共享它因此只要 sticky 负载均衡把每个会话路由到同一主机--workers N就能工作。proxy 重启后存活新 worker 打开同一 DB 文件即可恢复所有在途ccr:HASH标记RedisCcrStorecfg 门控于redisfeature是水平扩展部署的 drop-in所有主机的所有 worker 打同一个 Redis 实例负载均衡任意层都不需要 sticky session。在 proxy crate 的 Cargo 构建中用--features redis开启InMemoryCcrStore只适合测试与单 worker 开发。生产使用它会在重启时丢失所有ccr:HASH标记并在 worker 间分片——把它限制在本地机器上。内存后端在--workers N 1下具体坏在哪每个 uvicorn worker 是独立 Python 进程以下状态会跨 worker 分片PythonCompressionStore—— 当HEADROOM_CCR_BACKEND未设置或为sqlite时默认是SQLiteBackendworkspace_dir()/ccr_store.db重启安全、跨 worker 共享见headroom/cache/compression_store.py的_create_default_ccr_backend显式设HEADROOM_CCR_BACKENDmemory才会启用按进程的InMemoryBackend——本节的分片风险实际只适用于后者headroom/proxy/server.py中的相关日志仍假设默认内存实现这一点已过时HeadroomProxy._compression_cachesheadroom/proxy/server.py——按会话的CompressionCache字典实例变量永远是按 workerHeadroomProxy.session_tracker_store—— 由 Anthropiccache_read_input_tokens响应推导的按会话前缀跟踪状态实例变量永远按 workerTOIN 学习者状态—— 快照写~/.headroom/toin.json但保留按进程的内存状态一个 worker 上的模式统计在下一次磁盘 flush 前对其他 worker 不可见。当 uvicorn 轮转请求时turn-1 落在 worker A 的会话turn-2 可能落在 worker Bworker B 对 worker A 做过的事一无所知ccr:HASH标记解析为None模型看到一条它无法执行的晦涩指令。切换到SqliteCcrStore默认或RedisCcrStore即可解决 CCR 分片sticky-session 负载均衡则能解决上述全部状态。在现网中发现它proxy 在启动时若发现--workers N 1会打印WARNING级日志。HEADROOM_CCR_BACKEND未设置时警告涵盖 CCR 检索失败并建议设置HEADROOM_CCR_BACKENDsqlite已配置跨 worker 后端时警告只覆盖剩余的按 worker 状态compression cache、prefix tracker、TOIN、CostTracker。参考入口开发文档主体RUST_DEV.md架构与阶段计划REALIGNMENT/00-overview.md、REALIGNMENT/02-architecture.mdWorkspace 与 profileCargo.toml、rust-toolchain.toml、Makefile核心算法crates/headroom-core/src/transforms/mod.rs、crates/headroom-core/src/signals/README.md代理与健康端点crates/headroom-proxy/src/proxy.rs、crates/headroom-proxy/src/health.rsPyO3 绑定crates/headroom-py/src/lib.rs、crates/headroom-py/Cargo.toml对拍机制crates/headroom-parity/src/lib.rs、tests/parity/recorder.py、tests/parity/fixtures/CCR 后端crates/headroom-core/src/ccr/backends/mod.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），仅供参考 Headroom Rust 重构开发指南：从 Cargo Workspace 到 PyO3 绑定、Parity 测试与 CCR 多后端部署
Headroom Rust 重构开发指南从 Cargo Workspace 到 PyO3 绑定、Parity 测试与 CCR 多后端部署【免费下载链接】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/headroomHeadroom 正在将核心压缩逻辑从 Python 逐步移植到 Rust仓库根目录的 RUST_DEV.md 是这次 Rust 重写唯一新增的顶层开发文档。本文以该文档为骨架结合 Cargo.toml、Makefile 与各 crate 源码完整拆解 Rust workspace 的布局与构建体系、headroom-proxy透明反向代理的部署方式、maturin PyO3 的 Python 接线、Rust↔Python parity 对拍机制以及多 worker 部署下 CCR 存储分片的选型策略帮助你在这条 Python → Rust 迁移线上开发、验证与排障。一、Workspace 布局五个 crate 各司其职整个 Rust 侧由根目录 Cargo.toml 定义的 Cargo workspace 承载共五个成员Cargo.toml # workspace 根 rust-toolchain.toml # 固定 stable rustc附 rustfmt clippy crates/ headroom-core/ # 库共享类型 transform trait 面 headroom-proxy/ # 二进制axum /healthzPhase 2 起持续扩展 headroom-py/ # PyO3 cdylib向 Python 暴露 headroom._core headroom-parity/ # 库 parity-run CLI用于 Python 对拍测试 headroom-simulators/ # 二进制确定性的本地上游桩供 proxy 测试 tests/parity/ fixtures/transform/*.json # 从 Python 实现的录制输出Phase 1 移植的对拍基准 recorder.py # Python 侧 fixture 录制器 scripts/record_fixtures.py # 运行录制器的入口各 crate 的实际职责可以从源码结构中印证headroom-core是全部压缩算法的宿主crates/headroom-core/src/transforms/ 下包含smart_crusher/、text_crusher/、code_compressor.rs、diff_compressor.rs、log_compressor.rs、search_compressor.rs、kompress.rs等实现以及signals/错误信号检测、ccr/压缩后内容检索存储、tokenizer/tiktoken/HF/估算器等子系统headroom-proxy是 axum 实现的透明反向代理crates/headroom-proxy/src/ 下已有 SSE 帧处理、WebSocket 转发、Bedrock/Vertex 原生路由、缓存稳定化等模块headroom-py是 PyO3 cdylibcrates/headroom-py/Cargo.toml 中crate-type [cdylib]库名即_core把headroom-core的能力暴露为 Python 的headroom._core模块headroom-parity依赖headroom-core直接跑对拍不依赖 pyo3因此不需要 Python 环境即可运行headroom-simulators提供确定性的本地上游桩用于 proxy 集成测试。为什么default-members要排除 headroom-pyCargo.toml 中default-members刻意不包含headroom-py这是 RUST_DEV.md 明确解释的构建陷阱PyO3 cdylib 依赖extension-modulefeature 让 pyo3不链接libpython否则 Python 解释器无法import它。如果把它放进默认成员cargo build --workspace会尝试按普通库的方式链接它在缺少宿主 Python 解释器的机器上直接失败。因此cargo build --workspace裸命令跳过headroom-py由 maturin 负责它的构建cargo test --workspace仍会运行其测试Cargo.toml 顶部注释说明 pyo3 在测试场景可以动态链接。配套地rust-toolchain.toml 把工具链固定在channel 1.95.0并带rustfmt、clippy组件。文档记录了固定版本的原因2026-04-27 曾发生 CI永远拿最新 stable与本地开发机版本漂移导致 clippy 新 lint 只在 CI 爆红的事故固定后本地通过 CI 通过。升级流程是改 channel 字符串 →rustup update→make ci-precheck→ 修复新 lint → 提交。serde_json 的 feature 选择直接服务于字节保真workspace 依赖里serde_json启用了preserve_order、arbitrary_precision、raw_value三个 featureCargo.toml 有详细注释这与 RUST_DEV.md 的对拍主题直接相关preserve_order让Value::Object用 IndexMap 保持 JSON 键序smart_crusher移植依赖它与 Pythonstr(dict)的插入序保持一致arbitrary_precision保留原始数字字面量1.0不会塌缩为1大整数不经过 f64支撑未改动字节必须字节保真透传的架构不变量raw_value暴露未解析的 JSON 片段类型供转发路径对未修改的messages[*]条目做精确字节拷贝。二、常用命令Makefile 目标与 CI 前置门禁开发机不装just仓库根 Makefile 是命令的 source of truth并被.github/workflows/rust.yml镜像。RUST_DEV.md 中列出的核心目标如下目标作用make testcargo test --workspacemake test-parity用 maturin 构建headroom-py后运行parity-run runmake benchcargo bench --workspacemake build-proxyrelease 构建headroom-proxystrip 后打印体积make build-wheelmaturin build --release -m crates/headroom-py/Cargo.tomlmake fmtcargo fmt --allmake lintcargo fmt --checkcargo clippy --workspace -- -D warnings对照 Makefile 源码可以看到实际仓库比文档表格更全make verify-rust-core一条命令完成 maturin-develop 符号链接 导入验证。注释标明它用于排查proxy 静默回退到纯 Python 模式的问题proxy 启动 lifespan 时也会跑同样的检查make ci-precheck在git push之前本地复跑 CI 全部门禁——ci-precheck-rustfmt check clippy 全量测试、ci-precheck-python先构建 Rust 扩展再跑 smart_crusher 影响面的一批 pytest见 Makefile 第 109-127 行列出的 11 个测试文件、ci-precheck-commitlint对origin/main以来的提交做 conventional commit 校验make install-git-hooks一次性安装 pre-commit / commit-msg / pre-push 钩子make build-e2e-wrap/run-e2e-wrap构建并运行 wrap-e2e 的 Docker 镜像。一个值得注意的实现细节Makefile 中test-parity目标实际执行的是cargo run -p headroom-parity -- run --fixtures tests/parity/fixtures不再包含maturin develop步骤——因为 headroom-parity 的对拍器直接调用 headroom-corePhase 0 明确不从 Rust 调 Python这一步的删除把 Python 工具链从 CI parity 任务中剥离了。阅读文档时应以 Makefile 当前实现为准。三、运行 headroom-proxy透明反向代理与部署 runbookheadroom-proxy是一个透明反向代理。按其定位Phase 1 阶段它将 HTTP/1.1、HTTP/2、SSE 与 WebSocket 流量原样转发到配置的上游——不带任何 provider 逻辑。预期部署形态运维把现有 Python proxy 放到私有端口把headroom-proxy放在原公开端口并指向它终端用户无感知。构建与本地运行# 构建 make build-proxy ./target/release/headroom-proxy --help # 指向本地上游运行 ./target/release/headroom-proxy \ --listen 0.0.0.0:8787 \ --upstream http://127.0.0.1:8788 # 健康检查 curl -s http://127.0.0.1:8787/healthz # {ok:true,...} curl -s http://127.0.0.1:8787/healthz/upstream # 上游可达时返回 200这两个端点的实现见 crates/headroom-proxy/src/health.rs/healthz只要进程活着就返回{ok:true,service:headroom-proxy}/healthz/upstream则主动 GET 上游的/healthz上游 2xx 才返回 200否则 503。源码注释还解释了为什么用url.set_path(/healthz)而非相对 join——避免上游 URL 带非斜杠路径如http://localhost:8788/api时按 RFC 3986 把api段吃掉。Phase 1 切换 runbook# 1. 把 Python proxy 挪到私有端口例如 8788 HEADROOM_HOST127.0.0.1 HEADROOM_PORT8788 python -m headroom.proxy # 或你现有的启动器 # 2. 在原公开端口8787跑 Rust proxy 指向它 ./target/release/headroom-proxy --listen 0.0.0.0:8787 --upstream http://127.0.0.1:8788 # 3. 终端用户继续打 :8787无变化。 # 4. 验证透传 curl -si http://127.0.0.1:8787/v1/models # 5. 回滚 停掉 Rust proxy把 Python 重新绑回 8787。配置参数完整表参数环境变量默认值说明--listenHEADROOM_PROXY_LISTEN0.0.0.0:8787绑定地址--upstreamHEADROOM_PROXY_UPSTREAM必填代理转发的目标 base URL--upstream-timeout600s端到端请求超时为流式响应刻意放宽--upstream-connect-timeout10sTCP/TLS 连接超时--max-body-bytes100MB缓冲场景的上限流式路径不受此限--log-levelinfoRUST_LOG风格过滤--rewrite-host/--no-rewrite-hostrewrite是否把 Host 头改写为上游默认改写--graceful-shutdown-timeout30s收到 SIGTERM/SIGINT 后等待在途请求的时间用调用遥测决定下一个移植对象在把另一个 Python 压缩器移植到 Rust 之前RUST_DEV.md 建议先看实际调用量——Python proxy 已在/statsheadroom.proxy.prometheus_metrics上暴露按 transform 维度的遥测# 按调用次数排序的压缩器本进程生命周期内 curl -s http://127.0.0.1:8788/stats | jq .compressions_by_strategy # { # intelligent_context: 12453, # smart_crusher: 487, # search: 312, # diff: 28, # code: 0, # ← 从未触发移植可以安全推迟 # ... # } # 按 transform 的耗时avg/max/count curl -s http://127.0.0.1:8788/stats | jq .pipeline_timing # 每个策略贡献的 token 节省 curl -s http://127.0.0.1:8788/stats | jq .tokens_saved_by_strategy这是 2026-04-30 审计清理 PR 建议采用的移植优先级数据源调用量为零或近零的策略是推迟候选处于热路径的策略无论 LOC 多少都应移植。保留路径/healthz与/healthz/upstream由 Rust proxy 拦截不会被转发。运维不要把真实上游路由命名为这两个路径其余一切路径都是 catch-all 转发。四、Maturin Python 接线headroom-py 与headroom._coreheadroom-py是一个 PyO3 cdylib向 Python 暴露headroom._core。extension-modulefeature 是按需开启的见 crates/headroom-py/Cargo.toml 第 30-32 行这样普通的cargo build --workspace不会在缺少 libpython 的机器上尝试链接它。该 crate 还通过build.rs在 Linux/glibc 上编译一份 glibc-2.38 兼容 shimglibc_compat.c保证 wheel 在较老 glibc 的系统上可加载。首次搭建建议干净 venvpython3.11 -m venv /tmp/hr-rust-venv source /tmp/hr-rust-venv/bin/activate pip install maturin cd crates/headroom-py maturin develop # editable 开发构建安装 headroom._core cd /tmp # 重要先离开仓库根目录 python -c from headroom._core import hello; print(hello()) # headroom-core为什么要cd /tmp仓库根目录同时含 Python 的headroom/包。在仓库根目录跑冒烟导入会让 Python 把headroom解析到./headroom/__init__.py完整 SDK拉起重依赖而不是 maturin 安装的轻量命名空间包。测试要么在仓库根目录之外运行要么确保headroom已安装进同一个 venv此时 maturin 装的_core.so会落在它旁边两个导入都能正确解析。冒烟入口hello()的绑定在 crates/headroom-py/src/lib.rs它只是透传headroom_core::hello()用于验证链接。这个绑定层远不止冒烟测试。从 crates/headroom-py/src/lib.rs 可以看出它是 PythonContentRouter热路径上的 Rust 后端桥DiffCompressor、SmartCrusher含crush、crush_array_json、compact_document_json、ccr_get等方法、LogCompressor、SearchCompressor、TextCrusher都以 1:1 镜像 Python dataclass 的构造签名暴露配置对象如PySmartCrusherConfig接受与 Python 同名的全部 kwarg便于 shim 用SmartCrusherConfig(**asdict(py_cfg))直通。文件顶部注释说明了为什么选进程内 PyO3 而不是 IPC/RPCContentRouter 在 proxy 热路径上压缩任何子进程/RPC 桥都会吞掉想省下的成本而 PyO3 调用只有微秒级开销。热方法crush、compress等统一采用py.detach(...)模式释放 GIL让压缩运行期间其他 uvicorn worker/asyncio 任务继续推进。Release wheelmake build-wheel # wheel 落在 target/wheels/CI.github/workflows/rust.yml通过PyO3/maturin-action构建 linux-x86_64、macos-arm64、macos-x86_64 三个平台的 wheel 并作为 artifact 上传。wheel 体积优化是 Cargo.toml 中[profile.release]注释记录的一段实战项目撞过 PyPI 单项目 10 GB 累计存储上限事后剖析发现每个 wheel 约 18 MB 中有约 6.4 MB 是纯调试元数据ELF 的.strtab/.symtab。于是 release profile 采用strip symbolslto thincodegen-units 1把 Linux wheel 压到约 10-11 MB同时刻意不设置panic abort——proxy 是长期存活的异步进程一个坏请求触发 abort 会杀掉整个代理并断开所有并发客户端。另有[profile.ci]继承 release 但关闭 LTO、放宽 codegen-units供 CI 快速产出可用扩展。五、Parity 对拍机制Rust 移植正确性的守门员crates/headroom-parity持有 Rust↔Python 的 oracle 基础设施crates/headroom-parity/src/lib.rs 即其全部核心JSON fixtures位于tests/parity/fixtures/transform/schema 为{ transform, input, config, output, recorded_at, input_sha256 }与 tests/parity/recorder.py 的录制端一一对应TransformComparatortraitlib.rs每个 transform 一个实现接收 fixture 的 input/config产出与fixture.output比较的 JSON 值未实现的 stub 返回Err(...)harness 将其标记为Skipped而不是 panic 或 diff——stub 不能弄红 parity 门禁parity-runCLIcargo run -p headroom-parity -- run [--only TRANSFORM]负向测试lib.rs 的单测harness_reports_diff_for_divergent_comparatorlib.rs用一个恒定输出rust-output的假比较器对期望python-output的 fixture 运行证明 harness 在真实移植落地之前就能检测到分歧输出。当前比较器实况与几个工程细节文档写于 Phase 0/1 交界当时的 stub 是cache_aligner和ccr。从当前 lib.rs 的builtin_comparators()看已落地的真实比较器扩展为八个log_compressor、diff_compressor、tokenizer、smart_crusher、content_detector、text_crusher、kompress、code_aware_compressorstub 机制stub_comparator!宏仍保留给未实现项。实现中有三处值得借鉴的稳健性设计f64 归一化lib.rs 的compare_fixtureserde_json 对json!(f64)构造与从 fixture JSON 解析存在 1 ULP 的不对称比较前把实际输出走一遍to_stringfrom_str的有损解析让两边经过同一个解析器避免浮点噪声误报fixture 完整性校验load_fixtures_for会检查 fixture 声明的transform字段与其所在目录名一致不一致直接报错lib.rs模型类比较器离线运行KompressComparator只从本地 HuggingFace 缓存解析 ONNX 模型与 tokenizer绝不联网本地无模型时返回Errharness 把对应 fixture 全部标Skipped而不是失败。重新录制 fixturesource .venv/bin/activate # 主 Python SDK venv python scripts/record_fixtures.py # 底层用 tests/parity/recorder.py ls tests/parity/fixtures/*/ | sort | uniq -c当前 tests/parity/fixtures/ 下已积累 8 个 transform 目录其中 tokenizer 38 个、smart_crusher 16 个、diff_compressor 22 个、log_compressor 18 个等。录制器通过 monkey-patch 进程内的 transform 类见 tests/parity/recorder.py 的record_all()抓输出不修改headroom/下任何文件。六、退役 Python 组件的已知回归追踪Stage 3b/3c.1b 的退役删除了DiffCompressor与SmartCrusher的 Python 源码替换为 PyO3 委托 shim。2026-04-28 的审计发现退役时部分子系统被静默断开RUST_DEV.md 专设一节追踪每个缺口及其处置状态。这部分是维护者最应精读的章节SmartCrusher 四个子系统的处置表子系统状态跟踪测试TOIN 学习回路2026-04-28 重接。shim 的crush()与_smart_crush_content()在真实压缩后调用toin.record_compression()按strategy ! passthrough过滤掉 JSON 重规范化best-effortTOIN 失败仅 debug 级日志、不中断压缩tests/test_smart_crusher_toin_attachment.pyCCR marker 开关2026-04-29 端到端生效。RustSmartCrusherConfig新增enable_ccr_marker: boolcrush_array在发出ccr:HASH标记文本与 CCR store 写入前检查它。Python shim 用ccr_config.enabled and ccr_config.inject_retrieval_marker翻转该值——两个 Python 开关合并成同一个 Rust 门因为任一关闭时存储 payload 都没有意义。范围仅限 row-drop 哨兵路径tests/test_smart_crusher_toin_attachment.pycrusher.rs内enable_ccr_marker_*测试自定义相关性 scorer以 fail-loud 方式关闭2026-04-29。relevance_config/scorer构造参数保留在签名里以维持源码兼容但任一非 None 时 shim 抛NotImplementedError——静默丢弃用户提供的 scorer 是教科书式静默回退缺陷。完整管线等待 Stage-3c.2 的相关性 crate Python 桥test_custom_*_arg_raises_not_implemented按工具的 TOIN 学习钩子部分重接。_smart_crush_content接收tool_name并把它织入 TOIN 记录目前只改善query_context聚合尚不驱动按工具覆盖test_smart_crush_content_records_to_toinenable_ccr_marker这个字段在当前 PyO3 绑定中可以确认存在——crates/headroom-py/src/lib.rs 中SmartCrusherConfig构造签名的默认值就是enable_ccr_marker true。DiffCompressor子系统状态自适应上下文窗口逐字节生效parity fixture 锁定TOIN 集成本来就没有——DiffCompressor 经由 ContentRouter 的_record_to_toin记录非 SmartCrusher 策略本来就会走该路径无回归Phase 3e.1signals/trait 模块与 KeywordDetectorPython 的error_detection.py正则注册表退役后以 trait 分层tier体系在crates/headroom-core/src/signals/重生crates/headroom-core/src/signals/mod.rs完整架构见 crates/headroom-core/src/signals/README.md。要点按粒度划分 traitLineImportanceDetector已上线ContentTypeDetector与ItemImportanceDetectorI等其消费者被触碰时再落地TieredT组合子tiered.rs组合而非继承未来 ML 检测器作为新 tier 插入不需要改KeywordDetector或任何调用方只有一个具体实现KeywordDetectoraho-corasick。按项目无静默回退规则没有 NoOp/stub 实现——未来的 tier 必须带着真实实现落地顺手修掉的 bugERROR_KEYWORDS正则补齐timeout|abort|denied|rejected此前与关键词集漂移token从SECURITY_KEYWORDS中移除在每次 LLM 指标引用上误报。两侧修复同步——Python 侧的 shim 会基于 Rust 暴露的关键词表重新编译正则配套的规范化扩展路径文档把 BGE 分类头——在已加载的bge-small-en-v1.5embedder 之上做 384 维 → 4 类 softmax——记录为天然的 ML tier另保留两个开放备选ONNX 蒸馏 tinyBERT、基于词汇特征的逻辑回归。排期中Phase 3g —— 压缩管线形式化issue #315战略决策2026-04-29在 Phase 3e压缩器移植与 Phase 3fRust MCP 脚手架收尾后把先无损 → 再有损 → 再 CCR的顺序形式化为横切编排器CompressionPipelineLosslessTransform/LossyTransformtrait落在crates/headroom-core/src/pipeline/现有压缩器重构为可插拔 transform 的组合。关键设计选择是用 parser 处理结构在散文/结构边界处交给模型。文档明确警告3e/3f 完成前不要开始编码。观察清单潜在回归尚未审计CCRConfig.enabledFalse端到端 ——2026-04-29 已关闭enabledFalse与inject_retrieval_markerFalse都折叠到同一个 Rustenable_ccr_markerFalse门无 marker、无 store 写入SmartCrusherConfig.use_feedback_hintsFalse—— 配置字段已转发到 Rust但禁用路径在 Rust 内部的生效情况尚未用 parity fixture 验证。文档要求上述任何一项变化时同时更新本节与对应测试文件shim 的 docstring 也引用本节保持三处一致。七、Phase 0 遗留 Blockers这些是 Phase 0 的已知限制记录在此以免 Phase 1 重新踩坑cache_alignerfixturesCacheAligner.apply()签名为(messages, tokenizer, **kwargs)而Tokenizer是 provider 相关的最廉价的NoopTokenCounter/TiktokenTokenCounter构造也要拉headroom.providers.*连带完整 observability 栈如 opentelemetry。录制器只在 tokenizer 可廉价构造时记录cache_aligner否则记 blocker 并跳过见 recorder.py 的_build_cache_aligner_tokenizerccr不是一个类仓库里有CCRToolInjector、CCRResponseHandler、CCRToolCall、CCRToolResult等而非单一CCR类。录制器瞄准与 Rust 移植最对等的编码风格入口CCRToolInjector.inject_tool与CCRResponseHandler.parse_response若 Phase 1 想要不同的切分应相应更新recorder.py::record_allpre-commit 钩子噪声scripts/sync-plugin-versions.py每次提交都会改动.claude-plugin/marketplace.json、.github/plugin/marketplace.json和plugins/headroom-agent-hooks/**/plugin.json。改动无害但 Phase 0 每个提交都会带上——Phase 1 无需特殊处理让钩子跑即可rust-toolchain.toml现已固定channel 1.95.0此前跟踪stable让 CI 跑在本地开发机之前——2026-04-27 事故的修复项。已解决保留此处作为历史记录。八、多 worker 部署CCR 分片问题与后端选型状态更新现已有两个持久化 CCR 后端可选一旦选定持久化后端只能用单个--workers 的建议就不再适用。crates/headroom-core/src/ccr/backends/ 提供CcrStoretrait 的三个实现选择逻辑由backends::from_config在启动时依据CcrBackendConfig完成后端适用场景持久化多 worker 安全InMemoryCcrStore测试、单 worker 原型否否SqliteCcrStore默认单实例生产 / 单机集群是文件是需 sticky sessionRedisCcrStoreopt-in多主机 / 水平扩展生产是Redis是任意层无需 sticky从 backends/mod.rs 的from_config实现可以确认两个关键行为初始化失败必须上抛给调用方对应项目feedback_no_silent_fallbacks.md规则——DB 路径配错或 Redis URL 不可达会中止启动而不是静默降级到内存后端feature 门控的 Redis 后端若未编译进返回显式的UnsupportedBackend错误提示用--features redis重新构建。返回成功即代表后端已通过就绪自检SQLite schema 就位、Redis PING 返回 PONG。CcrBackendConfig::sqlite_default使用默认 30 分钟 TTL。各后端何时适用SqliteCcrStore是新部署的默认。DB 文件在本地磁盘同一主机上多个 worker 通过 SQLite WAL 模式锁共享它因此只要 sticky 负载均衡把每个会话路由到同一主机--workers N就能工作。proxy 重启后存活新 worker 打开同一 DB 文件即可恢复所有在途ccr:HASH标记RedisCcrStorecfg 门控于redisfeature是水平扩展部署的 drop-in所有主机的所有 worker 打同一个 Redis 实例负载均衡任意层都不需要 sticky session。在 proxy crate 的 Cargo 构建中用--features redis开启InMemoryCcrStore只适合测试与单 worker 开发。生产使用它会在重启时丢失所有ccr:HASH标记并在 worker 间分片——把它限制在本地机器上。内存后端在--workers N 1下具体坏在哪每个 uvicorn worker 是独立 Python 进程以下状态会跨 worker 分片PythonCompressionStore—— 当HEADROOM_CCR_BACKEND未设置或为sqlite时默认是SQLiteBackendworkspace_dir()/ccr_store.db重启安全、跨 worker 共享见headroom/cache/compression_store.py的_create_default_ccr_backend显式设HEADROOM_CCR_BACKENDmemory才会启用按进程的InMemoryBackend——本节的分片风险实际只适用于后者headroom/proxy/server.py中的相关日志仍假设默认内存实现这一点已过时HeadroomProxy._compression_cachesheadroom/proxy/server.py——按会话的CompressionCache字典实例变量永远是按 workerHeadroomProxy.session_tracker_store—— 由 Anthropiccache_read_input_tokens响应推导的按会话前缀跟踪状态实例变量永远按 workerTOIN 学习者状态—— 快照写~/.headroom/toin.json但保留按进程的内存状态一个 worker 上的模式统计在下一次磁盘 flush 前对其他 worker 不可见。当 uvicorn 轮转请求时turn-1 落在 worker A 的会话turn-2 可能落在 worker Bworker B 对 worker A 做过的事一无所知ccr:HASH标记解析为None模型看到一条它无法执行的晦涩指令。切换到SqliteCcrStore默认或RedisCcrStore即可解决 CCR 分片sticky-session 负载均衡则能解决上述全部状态。在现网中发现它proxy 在启动时若发现--workers N 1会打印WARNING级日志。HEADROOM_CCR_BACKEND未设置时警告涵盖 CCR 检索失败并建议设置HEADROOM_CCR_BACKENDsqlite已配置跨 worker 后端时警告只覆盖剩余的按 worker 状态compression cache、prefix tracker、TOIN、CostTracker。参考入口开发文档主体RUST_DEV.md架构与阶段计划REALIGNMENT/00-overview.md、REALIGNMENT/02-architecture.mdWorkspace 与 profileCargo.toml、rust-toolchain.toml、Makefile核心算法crates/headroom-core/src/transforms/mod.rs、crates/headroom-core/src/signals/README.md代理与健康端点crates/headroom-proxy/src/proxy.rs、crates/headroom-proxy/src/health.rsPyO3 绑定crates/headroom-py/src/lib.rs、crates/headroom-py/Cargo.toml对拍机制crates/headroom-parity/src/lib.rs、tests/parity/recorder.py、tests/parity/fixtures/CCR 后端crates/headroom-core/src/ccr/backends/mod.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），仅供参考