Headroom Rust 核心 signals 模块详解：行级重要性检测 Trait 与 Tiered 组合式检测架构

Headroom Rust 核心 signals 模块详解行级重要性检测 Trait 与 Tiered 组合式检测架构【免费下载链接】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 仓库crates/headroom-core中的 signals 模块文档展开讲清楚压缩前如何判断一行文本值不值得保留这一核心设计按粒度划分的检测 Trait 家族、Tiered组合器如何以置信度驱动短路/降级、KeywordDetector的 Aho-Corasick 自动机实现细节以及如何按项目约定把未来的 ML 检测器如 BGE 分类头无侵入地接入现有检测栈。读完后可掌握一套关键词 → 结构化解析 → 小模型的渐进式检测器扩展方法论。为什么 signals 是 crate 顶层模块而不是 transforms 的子模块Rust 侧的压缩逻辑位于 transforms 目录而检测分类逻辑独立放在 signals 目录。模块文档注释解释了分层理由transforms 负责变signals 负责判transforms 里的压缩器负责变更数据signals 里的检测器负责对数据做分类打分、归类。同一个分类器喂给多个消费方行级重要性打分同时被text_compressor、search_compressor、diff_compressor、log_compressor使用。如果把它嵌套在某个 transform 之下会暗示归某一个消费方所有造成错误的归属。无静默回退No silent fallbacks是项目级约定模块注释明确写了没有NoOpDetector、没有返回全零的桩 ML 实现、没有悄悄降级的 fallback 分类器。某一级检测器要么真正干活要么把我没有把握这件事通过confidence字段如实表达而不是被强行扭转为阳性答案。模块注释还给出了检测能力的成熟路径这决定了 traits 的演进方向模式回退Pattern fallback——关键词/正则扫描便宜但脆弱是每个检测器的起点即当前的KeywordDetector结构化解析Structured parser——输入有语法diff、JSON、代码时直接解析unidiff与tree-sitter已在项目其他部分落地ML 模型——对模糊类别行重要性、锚点单元格、HTML 抽取在小规模标注流量上训练的小分类器优于关键词规范扩展路径是在已有的bge-small-en-v1.5embedder 上加分类头。三类实现都挂在同一个按粒度的 trait 之下分层通过Tiered组合完成从不使用继承。Trait 家族按粒度拆分而不是按领域拆分signals/README.md 中的 trait 家族表如下Trait粒度状态LineImportanceDetector逐行已交付Phase 3e.1ContentTypeDetector整个文本块未来对transforms::detection的泛化ItemImportanceDetectorI[I]排序未来面向 SmartCrusher 单元格 / 搜索命中设计要点是按粒度、不按领域把所有能力塞进一个DetectorAny会迫使每个调用点都去 match 输入形态拆成三个 trait 后每个调用点都能被类型系统约束住。模块公开了keyword_detector、line_importance、tiered三个子模块并在 mod.rs 中重导出KeywordDetector、KeywordRegistry、ImportanceCategory、ImportanceContext、ImportanceSignal、LineImportanceDetector与Tiered。ImportanceContext一行文本从哪里来决定哪套模式生效ImportanceContext 有四个变体它决定了哪一组模式会触发Text——自由文本text_compressormarkdown 结构有意义Search——grep/ripgrep 输出search_compressorerror/warn 关键词占主导Diff——git diffdiff_compressorerror security importance 关键词生效Log——日志输出log_compressorerror/warn 关键词 级别前缀生效。例如 markdown 标题在Text语境里算优先级信号在 diff hunk 里就不算。ImportanceSignal绝不返回裸 bool单个检测器对单行文本的输出是 ImportanceSignal包含三个字段字段含义category: OptionImportanceCategory命中的类别Error/Warning/Importance/Security/Markdown未命中为Nonepriority: f32压缩器排序依据0.0 最先丢弃1.0 无论如何保留confidence: f32Tiered组合器用来决定是否继续问下一层0.0 无信息1.0 检测器确信它提供两个构造器ImportanceSignal::neutral()category 为 None、priority 与 confidence 均为 0.0表示我对这行没有意见和ImportanceSignal::matched(category, priority, confidence)命中检测。is_match()仅以category.is_some()判定是否命中。trait 定义本身很薄pub trait LineImportanceDetector: Send Sync { fn score(self, line: str, ctx: ImportanceContext) - ImportanceSignal; }注释明确要求实现必须Send Sync因为压缩器会在 tokio 工作线程之间共享检测器实例同时实现应当便宜关键词自动机、词法特征或可摊销embedding 分类头配合批量推理。Tiered 组合器以置信度为驱动的短路栈Tiereddyn Trait把一个有序检测器栈串起来规则只有一条ESCALATE_THRESHOLD 为0.7。核心打分逻辑在 score 实现impl LineImportanceDetector for Tiereddyn LineImportanceDetector { fn score(self, line: str, ctx: ImportanceContext) - ImportanceSignal { let mut best ImportanceSignal::neutral(); for tier in self.tiers { let signal tier.score(line, ctx); if signal.confidence ESCALATE_THRESHOLD { return signal; } if signal.confidence best.confidence { best signal; } } best } }语义可以拆成三条短路第一个confidence 0.7的 tier 立即胜出后续 tier 不再被咨询落空低置信度 tier 会被跳过继续问下一层兜底如果没有任何 tier 越过阈值返回见过的最高置信度信号让调用方至少拿到一个最佳猜测且 confidence 分数如实反映了整栈的不确定度。栈是组合而非继承KeywordDetector不知道未来 ML 检测器的存在ML 检测器也不知道关键词检测器的存在——双方各自实现 traitTiered只负责排序。with构建器要求最精确的层放最前with_detector便捷方法则帮调用点省掉as Boxdyn …的样板。tiered.rs 的单元测试用两个合成检测器把上述语义逐条钉死AlwaysFiresHighconfidence 0.95放在关键词层之前时ERROR: connection refused 被判为Security而不是Error证明高置信层先短路AlwaysFiresLowconfidence 0.5则必须落到关键词层结果变为Error没有任何层命中阈值时返回 best-seen0.5 的Importance空栈返回 neutral。KeywordDetectoraho-corasick 自动机 词边界后过滤当前唯一注册的检测层是 KeywordDetector它是 Tier-3 模式检测器用aho-corasick一次确定有限自动机扫描就能在一行里找出所有关键词复杂度O(n m)替代了 Python 侧error_detection.py的独立正则逐个搜索——关键词集只有一份真源不会出现表与编译后的模式漂移。置信度与优先级常量常量值作用KEYWORD_CONFIDENCE0.7恰好达到 ESCALATE_THRESHOLD无歧义的关键词命中不会被下一层再议同时给未来 ML 层留出在边缘样本上覆盖的空间见 L41ERROR_PRIORITY0.95Error 类命中行的保留优先级SECURITY_PRIORITY0.85Security 类WARNING_PRIORITY0.75Warning 类IMPORTANCE_PRIORITY0.6Importance 类important/todo/fixme/bug…MARKDOWN_PRIORITY0.45Markdown 结构类仅 Text 语境关键词注册表 KeywordRegistryKeywordRegistry::default_set() 定义了默认词表这也是配置与检测逻辑的分界——静态词表属于检测器的配置与消费它的检测器放在一起errorerror, exception, fail, failed, failure, fatal, critical, crash, panic, abort, timeout, denied, rejectedwarningwarn, warningimportanceimportant, note, todo, fixme, hack, xxx, bug, fixsecuritysecurity, auth, password, secretmarkdown_prefixes# , ## , ### , #### , **, 按前缀匹配不是整行关键词error_indicatorserror, fail, exception, traceback, fatal, panic, crash供contains_error_indicator快速分诊用的子串集独立于行打分集注册表还通过as_map()提供确定性快照BTreeMap保证迭代顺序稳定供 PyO3 侧 Python shim 反射出旧的正则表保持双语言行为一致。语境相关的匹配规则match_in_context 的查找顺序是先查跨语境通用的 error/importance 自动机再按语境分流——Diff语境security 自动机生效Text/Search/Log语境warning 自动机生效注意 Diff 不含 warning这与 Python 的PRIORITY_PATTERNS_DIFF形状保持一致仅Text语境markdown 结构前缀生效。自动机以ascii_case_insensitive(true)与MatchKind::LeftmostLongest构建命中的字节偏移再经过 is_word_boundary 做整词校验——因此 panicker 不会误触panic。另有一个刻意的例外contains_error_indicator走无词边界的子串匹配因为它服务的是是否包含 error 形态内容的快速分诊调用点如消息签名分类保留 Python 时代的宽松语义它使用的词集也不同于score()含traceback、不含timeout等四个后补词。相对 Python 版本修复的两个 bugfixed_in_3e1文件头注释记录了 2026-04-29 修复、并由 parity 夹具锁定的两处行为差异Python 的ERROR_KEYWORDS列了{abort, timeout, denied, rejected}但ERROR_PATTERN正则遗漏了这四个词——Connection timeout 因此从未被标记为 error。Rust 版把四词纳入自动机消费的 error 集Python 的SECURITY_KEYWORDS包含token会在input_tokens、tokens_saved等 LLM 度量行上产生大量误报。Rust 版将其从 security 集剔除。对应的回归测试见 keyword_detector.rs 测试模块timeout_now_classified_as_error_in_diff、rejected_now_classified_as_error、token_no_longer_flags_security_in_llm_proxy_context、auth_still_flags_security_in_diff、warning_fires_in_search_but_not_diff、word_boundary_excludes_substring_matches等分歧行都带// fixed_in_3e1标记Python 侧的 parity 夹具为 tests/test_signals_keyword_parity.py。检测器如何被 transforms 消费信号最终以两种方式进入压缩决策按类别加权search_compressor.rs 在boost_errors开启时调用importance.score(..., ImportanceContext::Search)把Error映射为 0.5、Warning0.4、Importance0.3对应 Python 的PRIORITY_PATTERNS_SEARCH顺序而Security与Markdown不加权bump 为 0.0——这体现了类别到业务语义的映射发生在调用点而不是检测器内部。该压缩器还提供with_detector构造器允许换入自定义LineImportanceDetector实现按行计数日志 offload 路径log_offload.rs持有Boxdyn LineImportanceDetector默认KeywordDetector对日志行逐行打分统计再决定哪些行可被卸载。两处调用点都是在消费方把检测器接进 Tiered检测器模块本身不感知其他层——这正是文档第 4 条接入约定的实例。如何新增一个检测器项目约定文档给出了五步清单值得作为扩展规范逐条执行确认粒度。逐行分类器实现LineImportanceDetector整块分类器走新 trait。不要把跨粒度的工作硬塞进一个 trait实现score(self, ...) - ImportanceSignal。如实设置confidence如果你是该输入的权威检测器给 0.7如果希望分歧时让下一层覆盖就给更低的值禁止静默回退。没有信息时返回ImportanceSignal::neutral()——绝不用低置信度编造一个阳性答案来 fail open在消费方接入Tiered而不是在 signals 模块内。检测器自身不知道其他层的存在补齐 parity 夹具。如果新检测器替换或增强了既有实现为分歧行打上// fixed_in_phase标记保留审计线索。规范的 ML 扩展路径BGE 分类头README 认为最可能成为下一层的是在relevance::EmbeddingScorer已加载的bge-small-en-v1.5embedder 上加一个分类头。目标形态pub struct BgeClassifierDetector { embedder: Arcdyn Embedder, // 与相关性打分共享 classifier: LogisticRegression, // 384 维 → 4 类 softmax threshold: f32, // 在验证集上校准 } impl LineImportanceDetector for BgeClassifierDetector { ... }这被定位为最省路径理由有三见 README零新增资产embedder 已经为 SmartCrusher 的相关性打分加载relevance/embedding.rs 中默认模型即BAAI/bge-small-en-v1.5384 维经 fastembed/ONNX Runtime 运行。分类头仅约 1.5 KB 权重、每行约 1 ms 推理可批处理不需要新的 ONNX runtime、模型文件或下载校准置信度天然契合 Tiered高置信正样本可以短路KeywordDetector边缘样本则让位——而边缘样本恰恰是关键词自动机可靠的区域trait 形状零改动LineImportanceDetector对三条路径都直接兼容。同时保留两个备选以防 BGE 头欠拟合蒸馏 tinyBERTONNX——精度更高10–20 MB 模型、3 ms 延迟引入新的ort依赖词法特征上的逻辑回归——输入是比率、行长度、结构标记、栈帧启发式约 5 KB 模型、三者中最快适合做 A/B 基线。这三条路对上层完全透明它们都只是Tiered栈里的新成员。什么不属于 signals 模块边界约定同样写在文档里扩展时不要越界具体 transforms——归 crates/headroom-core/src/transforms/静态关键词数据表——是KeywordDetector的配置而非检测逻辑随消费方放在signals/keyword_detector.rs的KeywordRegistry标签保护headroom:keep标记——属于用户意图不属于分类。小结signals 模块用最小的类型面一个 trait 一个信号结构体 一个组合器承载了 Headroom Rust 核心的保留哪些行决策ImportanceSignal的三元组让类别、保留优先级与不确定度彼此解耦Tiered的 0.7 阈值把谁说了算变成一条可测试、可替换的栈规则KeywordDetector则示范了如何在修复 Python 版遗留 bug 的同时用 parity 夹具固化行为。对想扩展检测能力尤其是小模型层的开发者五步接入约定和 BGE 分类头方案给出了从当前 0.7 置信度关键词层平滑演进到 ML 层、且不动任何调用点的完整路线。【免费下载链接】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），仅供参考