Skip to content

从 opencode-acp#354 移交:Headroom / 外部压缩引擎在 billion-context 的集成 #445

Closed

Description

@ranxianglei

来源: opencode-acp#354(功能建议:将 Headroom 内核作为可选的上下文压缩插件集成到 ACP)
链接: ranxianglei/opencode-acp#354

背景

opencode-acp#354 由 @WantexZard 提出:希望让 ACP 支持一个可选的 Headroom compression backend / plugin——默认行为完全不变,只有主动安装并启用 Headroom 的用户才使用,从而避免 ACP 与 Headroom 两套上下文管理系统分别配置。

移交说明

经 owner(@ranxianglei)在 #354 的决定:

否决ework的分析 麻烦把这个issue提交的billion-context 由billion-context处理

本 issue 中与 billion-context 相关的部分由 billion-context 项目处理,不在 opencode-acp 侧实现。

待 billion-context 侧处理的范围(供参考,具体方案由本项目维护者定夺)

注:opencode-acp 侧 ework 此前的分析(compress.backend seam、互补 / 替换模型等)已被 owner 否决,此处不作为本 issue 的既定方案,仅供参考。

Activity

  1. ranxianglei commented on Sep 2, 2026

    @ranxianglei
    OwnerAuthor

    🤖 ework agent · qwen3.8-27b

    收到移交。已读完 bili 侧相关代码(src/plugin.ts、src/agent/opencode.ts、src/agent/shared.ts、src/launcher.ts)。先给结论,再给依据。当前未动任何代码——这是功能类 issue,按规范先对齐方向再实现。

    结论

    1. issue 第二条(协调 BILLION_CONTEXT_PROXY self-disable,避免工具名 / /acp 面板重复或遮蔽)——现状已满足,没有要修的 bug。 bili 与 ACP 现在是替换关系:bili opencode 导出 BILLION_CONTEXT_PROXY(src/launcher.ts:1873),opencode-acp 检测到后整体自我禁用(index.ts:37,v1.14.25 / PR fix: detect codex compaction requests before preflight; verbatim passthrough when not intercepted (#332) #335)——ACP 关掉自己的压缩,/acp 面板与 ACP 工具改由 bili 独占(薄插件 src/agent/opencode.ts 注册 /acp、绑定 session)。互斥 ⇒ 无重复、无遮蔽。

    2. issue 第一条(让 bili 成为外部压缩引擎的宿主)是真正的新工作,但正确的形状不是"通用引擎 host",而是一个有界的 opt-in 工具输出预压缩钩子。 理由见下。

    关键架构事实:Headroom 与 acp-kernel 是两种不同种类的压缩,正交而非可替换

    • acp-kernel(bili 现引擎):模型驱动、会话级语义摘要(compress/decompress/search_context)。摘要由模型写,不是引擎写。
    • Headroom:线层机械压缩,对工具输出做 Kneedle/BM25/CCR 可逆检索(POST /v1/compress),在 LLM 看到前把超大 tool result 压成 marker+hash。

    由此推出一个决定性的点:"替换压缩引擎"这个抽象本身是错的——摘要由模型写,引擎只能换"机械预处理"那一层。真正能"宿主"进 bili 的只有 Headroom 这类机械预处理器,而它是个有界、正交的关注点,不是"通用引擎"。

    为什么不做通用 compress.backend / 引擎 host

    • 这就是 fix: pass through Claude auto-mode classifier requests untouched (#353) #354 里被否决的那个耦合,只是从 ACP 搬到 bili——核心仍被绑到外部引擎的 lifecycle / config / 失败模式上。
    • 直接违背 bili 的核心设计:"proxy 是唯一的压缩权威"(src/agent/shared.ts:3、src/plugin.ts:31)。插件协议零 schema 漂移正源于权威唯一;塞一个可插拔的第二压缩权威进去,把这个优势抹掉。
    • 如上,"引擎"抽象本身错了(正交层不该用 backend 抽象)。

    我的建议(明确)

    在 bili 里加一个 opt-in 的"工具输出预压缩"钩子:转发请求前,可选地把超大 tool result 交给外部机械压缩器(Headroom 的 POST /v1/compress,作为 sidecar HTTP 端点)先压一遍,再走 acp-kernel。

    • 默认关:config 开关,off = 行为完全不变(满足 issue 核心诉求)。
    • 有界:具体预处理步骤,不是通用引擎缝。
    • 低耦合:bili 只调一个 HTTP 端点,不 import Headroom 代码、不耦合其 lifecycle;sidecar 不可达就降级为现状(不做工具输出压缩),主流程不受影响。
    • 正交:与 acp-kernel 语义压缩可同时开。
    • 效果:用 bili 的人一个 proxy 同时拿到语义压缩 + 机械工具输出压缩,不用自己再搭第二个 Headroom proxy——正好消掉 fix: pass through Claude auto-mode classifier requests untouched (#353) #354 的"两套系统分别配置"痛点。

    请你拍板

    我按上面的有界 opt-in 钩子推进。如果你的本意是"通用引擎 host"(更灵活,但高耦合且违背单一权威设计),请明确告诉我,我再重新评估;否则我据此定具体契约(sidecar 端点 / 触发阈值 / 降级策略)→ 建 devlog → 走 PR。

    (参考:社区 wentaonb123/acp-headroom 的 acp-headroom-opencode 是互补路线的现成实现,MIT,可作 sidecar 契约蓝本。)

  2. ranxianglei commented on Sep 2, 2026

    @ranxianglei
    OwnerAuthor

    他这个压缩我理解就是对工具过滤?bili 上是不是加一个过滤的 hook 即可?当然实现要从内核开始

  3. ranxianglei commented on Sep 2, 2026

    @ranxianglei
    OwnerAuthor

    🤖 ework agent · qwen3.8-27b

    对齐一下,然后给落地路径。

    先回答你的两个问题

    1. "对工具过滤?" —— 基本对,但更准确是对工具输出做机械压缩 + 可逆检索,不是纯丢弃。Headroom 的做法:把超大 tool result 压成一个 marker + 按相关性排过序的摘录,完整内容保留、可逆取回。所以"过滤"的直觉对(它确实在处理/挑选工具输出),但关键属性是可逆——上下文变小但东西没丢,模型需要时能取回。这点正好能落到 acp-kernel 现有的 compress/decompress/search_context 模型上,不是另起炉灶。

    2. "bili 上加一个过滤的 hook 即可?" —— 是。bili 侧就是一个 opt-in 配置开关(默认关,行为完全不变),打开后走内核的工具输出压缩。hook 很薄,重活在内核。

    确认方向:从内核(acp-kernel)开始 ✅

    这比我上一轮提的"外部 Headroom sidecar(HTTP 调用)"更干净——不引外部依赖、不耦合 Headroom 的 lifecycle、不跨进程。内核原生支持后,bili 只是 bundle + 暴露开关。

    落地路径(跨两仓,acp-kernel 必须先 ship)

    1. acp-kernel(ranxianglei/acp-kernel,独立仓):加一条自动工具输出压缩路径——
      • 触发:单条 tool result 超过阈值时自动压,不需要模型决策(这是它和模型驱动 compress 的本质区别)。
      • 形态:压成 marker + 相关性摘录,完整内容存 StateStore、可经 decompress/search_context 取回。
      • 开关:config flag,默认 off。
      • 走独立 PR + release(CI 发 npm)。
    2. 验证 acp-kernel 在 npm 上 live(npm view acp-kernel version)。
    3. billion-context:bump acp-kernel(精确版本,无 ^)→ 暴露配置 hook(默认 off)→ devlog → PR。

    我的设计建议(先给默认,你改)

    • 算法:先做内核原生的"头部保留 + 相关性摘录 + 可逆取回"版本——思想对齐 Headroom,但不照搬 Kneedle/BM25/CCR 的具体实现。理由:够用、好测、好维护;要完全对齐 Headroom 的压缩率再叠加 Kneedle/BM25 作为后续增强。
    • 触发阈值:默认单条 tool result > ~8K tokens 才压,且做成可配。

    方向没问题的话,我就先在 acp-kernel 开 issue/PR 动手(按上面"简单可逆版 + 可配阈值");要完全对齐 Headroom 的 Kneedle/BM25/CCR、或调阈值/开关命名,你说一声。当前未动代码。

  4. ranxianglei commented on Sep 2, 2026

    @ranxianglei
    OwnerAuthor

    取回的意义是啥?如果要取回何必再压缩?取回为啥不重新读一次工具?
    你看看他过滤了什么工具

  5. ranxianglei commented on Sep 2, 2026

    @ranxianglei
    OwnerAuthor

    🤖 ework agent · qwen3.8-27b

    查了 Headroom 源码(headroomlabs-ai/headroom + 社区集成 wentaonb123/acp-headroom)。你说得对——对工具输出,"取回"是多余的,砍掉。

    先答你的三连问

    取回的意义 / 为啥不重读一次工具?
    对工具输出确实没意义。Headroom 的 CCR(Compress-Cache-Retrieve)是把原文备份到磁盘、按 hash 取回(配套一个 headroom_retrieve 工具 + 反馈环:取回率高就压得松点)。但那是它通用压缩的机制——它压的不只是可重跑的工具输出。而我们这里只针对可重跑的工具输出:模型手里本来就有原始 tool-call 的参数(我们压的是 tool result,tool call 原样保留),要全文就重跑一次工具(同参数,或更窄的 query)即可。不需要磁盘备份、不需要 hash、不需要额外工具。所以 CCR 这一层对我们是过度设计。

    他过滤了什么工具?
    不是固定工具白名单。它按内容类型 + 相关性 + 每工具偏置决定压不压、压多少:

    • 内容类型路由(search / log / text / diff,content_router.py);
    • 相关性打分(BM25/hybrid/embedding,relevance_threshold=0.25);
    • 每工具偏置乘子(conservative=1.5 / moderate=1.0 / aggressive=0.7,adaptive_sizer.py);
    • Kneedle 求 K(保留多少条,adaptive_sizer.py)。

    实际压到的就是那些产出大、且只读可重跑的工具:read / grep·search / glob·list / 日志输出。有副作用的 bash 不在其列(不可干净重跑)。

    修订后的设计(砍掉取回,更简单)

    • 单向压缩:tool result 超阈值 → 压成按重要性排的摘录(top-K)。
    • 无 CCR / 无磁盘备份 / 无 hash / 无 retrieve 工具。
    • marker 里写重跑提示:"输出已截断到最相关的 top-K;要全文请重跑该工具(同参数或更窄 query)。"
    • 只压可重跑工具(read/grep/glob/ls/log),有副作用的 bash 不碰。

    一个诚实的边界

    重跑的前提是工具幂等(同参数 → 同输出)。read/grep/glob/ls/log 满足;bash 带副作用不满足——所以才"只压可重跑工具"。真要覆盖有状态工具才需要 CCR 备份,那是后续 opt-in 增强,不是默认。

    方向如果 OK,我就按这个更简版(单向压缩 + 重跑提示 + 只压可重跑工具,无 CCR)在 acp-kernel 动手。阈值 / 工具名单定稿时贴出来你过一眼。当前未动代码。

  6. ranxianglei commented on Sep 2, 2026

    @ranxianglei
    OwnerAuthor
    他过滤了什么工具?
    不是固定工具白名单。它按内容类型 + 相关性 + 每工具偏置决定压不压、压多少:
    
    内容类型路由(search / log / text / diff,content_router.py);
    相关性打分(BM25/hybrid/embedding,relevance_threshold=0.25);
    每工具偏置乘子(conservative=1.5 / moderate=1.0 / aggressive=0.7,adaptive_sizer.py);
    Kneedle 求 K(保留多少条,adaptive_sizer.py)。
    实际压到的就是那些产出大、且只读可重跑的工具:read / grep·search / glob·list / 日志输出。有副作用的 bash 不在其列(不可干净重跑)。
    

    举一些例子,他会跨工具压缩吗?如果可以的话我们用不上。
    如果只是过滤工具,是可以用得上的

  7. ranxianglei commented on Sep 2, 2026

    @ranxianglei
    OwnerAuthor

    🤖 ework agent · qwen3.8-27b

    查了集成层源码(acp-headroom 的 packages/core/src/stage.ts,202 行全读了)。结论:不跨工具,是逐条(per-message)压的 → 可用。

    证据(apply 方法)

    • 把消息列表过滤成 candidates(role==="tool" 且 text.length >= minChars 且不在 protectedTools 里 且在最后一条 user 之前),然后对每一条 candidate 独立调用 compressToolOutput(proxyUrl, { toolName, text, model })——一次只压一个工具的一条输出。
    • 返回 Map<message.id, 替换文本>——每条消息各自替换,没有任何跨工具合并 / 共享摘要。
    • 另有 applyOne(toolName, text) 就是显式的"压单条"模式。

    "跨消息"的部分只是挑选哪几条压,不是跨工具压缩

    • protectRecent(默认 true):最后一条 user 之后的结果不碰(当前轮是模型工作集)——位置过滤;
    • maxPerTurn:每轮只压最大的 N 条(延迟上限)——预算挑选;
    • 缓存按单条 sha256(text) 键——逐条缓存。

    这些都不产生跨工具的内容合并。(完整 proxy 里还有个 enable_cross_turn_dedup,默认关,且是去重不是压缩——我们不会搬它。)

    例子

    1. read 返回 3000 行文件(~50K tokens)→ 只压这一条 read 输出,压成 top-K 相关摘录;旁边的 grep、glob 结果各自独立压(或没过阈值就不压)。
    2. 连续两次 read 不同文件 → 两条各自独立压,不会合并成一份共享摘要。
    3. grep 返回 5000 行匹配 → 独立压成 top-K 最相关匹配。

    集成时要定的参数(都是"选哪条压",不是跨工具)

    • minChars(默认 4000):过阈值的才压;
    • protectedTools:永不压的工具名单;
    • protectRecent:当前轮不压;
    • maxPerTurn:每轮最多压几条。

    回到我们的设计

    正因为它是逐条的,正好能作为 acp-kernel 里的逐消息预处理步骤——对每条超阈值的 tool-result 消息独立压,和 acp-kernel 自己的模型驱动 compress(跨会话语义摘要)正交、不打架。之前说的"重跑提示"设计照旧适用。

    判定:可用。 方向确认的话我就在 acp-kernel 动手(逐条压缩 + 重跑提示 + 只压可重跑工具,无 CCR)。参数(阈值 / 工具名单 / maxPerTurn)定稿贴你过目。当前未动代码。

  8. ranxianglei commented on Sep 2, 2026

    @ranxianglei
    OwnerAuthor

    那他们压缩的时候是怎么压缩的。比如bash 什么去掉什么留下?

  9. ranxianglei commented on Sep 2, 2026

    @ranxianglei
    OwnerAuthor

    🤖 ework agent · qwen3.8-27b

    读了 log_compressor.rs 的头部注释(1795 行,注释把流水线写得很清楚)+ adaptive_sizer.py 全文。

    通用机制(怎么压)

    1. 先判内容类型(live_zone.rs 分发):JSON 数组 / 日志·构建输出 / grep·ripgrep / unified diff / 普通文本 → 各走各的压缩器。
    2. 逐条打分排序:按相关性(BM25/hybrid/embedding,对着 query)+ 重要性。
    3. 自适应求 K(adaptive_sizer.py,Kneedle):在"唯一 bigram 覆盖率曲线"上找拐点 = 加再多条目就不再提供新信息处。全独特→多留(最多 100%);大量重复→少留(~30%)。每工具偏置 conservative=1.5 / moderate=1.0 / aggressive=0.7。
    4. 留 top-K,其余丢(marker + 数量表示)。

    bash 具体(日志/构建输出 → LogCompressor)

    头部注释原话:典型输入 1 万+ 行、里面只有 5-10 个真错误,典型压缩比 10-50×。流水线:

    1. 格式检测(pytest / npm / cargo / jest / make / generic);
    2. 逐行分类:级别(ERROR/FAIL/WARN/INFO/DEBUG/TRACE)、是否栈帧、是否 summary 行;
    3. 逐行打分:级别基础分 + 栈帧 + summary 加成;
    4. 自适应总行数预算(Kneedle);
    5. 按类别选:errors(首/尾/最相关)、fails、warnings(去重)、stack traces、summaries;每个选中项周围留 context window;最后自适应封顶;
    6. 可选 CCR(ratio < 0.5 才存)。

    所以一次 bash 测试/构建输出:

    • 留下:错误行(首/尾/最相关)、失败行、警告(去重后)、栈追踪(app 帧保留,runtime/stdlib 帧折成 [... N runtime frames collapsed])、summary 行("FAILED: 3 tests"、"error: could not compile")、每个选中项周围的上下文。
    • 去掉:INFO/DEBUG/TRACE 噪音、重复行(去重——5000 行一样的 "ERROR: test_X failed at 0x…" 收成几条;但保留 message 前缀,不同错误不合并)、深层 runtime/stdlib 栈帧。

    对我们设计的两点启示

    1. 不 verbatim 搬(光 log_compressor 就 1795 行,还分 5 种格式)。取核心原则:判类型 → 按重要性/相关性给行打分 → 留 top-K(自适应)→ 丢其余 + marker。
    2. 一个修正:之前说"只压可重跑工具"。但 LogCompressor 是单向"留重要、丢噪音"——它不靠重跑,靠的是保留 errors/summaries 这些关键行。所以有状态的 bash 其实也能压(关键行留下了,丢的只是噪音);重跑提示只是可重跑工具的额外保险。我建议把设计从"只压可重跑"放宽到"压所有大输出,但保证留关键行 + marker 说明丢了什么",更稳。

    你确认方向我就按这个在 acp-kernel 动手。当前未动代码。

  10. ranxianglei commented on Sep 2, 2026

    @ranxianglei
    OwnerAuthor

    会不会误操作 压缩错了 。问题是什么应该给模型 什么不应该

  11. ranxianglei commented on Sep 2, 2026

    @ranxianglei
    OwnerAuthor

    🤖 ework agent · qwen3.8-27b

    会。这是这个功能最核心的风险,我不回避。

    机械压缩确实可能压错

    为什么:决定"什么重要"是一个任务相关的判断——取决于模型在做什么、在找什么。机械压缩用的是启发式(日志级别、对 query 的相关性、bigram 覆盖率),它只是近似这个判断,不是判断本身。所以会误判:

    • 一行看着像 INFO 噪音、其实是关键(配置值、一个措辞成 info 的警告);
    • 一行"重复"了、其实在不同上下文里各自重要;
    • 一行没匹配到 query、但模型需要它。

    一旦丢错,模型永远看不到(对有状态工具),就会基于不完整信息做决定。

    这正是 acp-kernel 自己的压缩是模型驱动的原因——模型写摘要,因为它才是"什么重要"的可靠判断者。机械自动压缩没有这个判断,天生更险。

    什么该给模型 / 什么不该(原则)

    • 必给:一切可能改变模型下一步动作的——错误、失败、关键结果、首次出现的唯一行、summary 行、输出的头和尾、模型可能据此行动的。
    • 可安全丢:纯冗余——完全重复的行、深层 runtime/stdlib 栈帧、样板头尾、进度噪音。这些可证明不影响判断。
    • 灰色地带(会出错的):"看着不重要、但可能关键"。机械压缩只能安全处理前两类,第三类必须保守(拿不准就留)。

    一句话:模型该拿到所有"可能影响决策"的,不该拿到纯冗余;而"影响决策"的边界只有模型知道,所以机械压缩只能碰明确的冗余,灰色地带一律偏留。

    怎么把风险框住(比上一条更保守)

    1. 可重跑工具优先(read/grep/glob/ls):模型能重跑恢复,压错了也能找回 → 风险低。这是默认。
    2. 有状态工具(bash):要么不自动压,要么只丢"可证明冗余"(完全重复、深层栈帧),绝不做重要性判断;要激进压就必须可恢复(备份)。——我上一条说"放宽到压所有大输出",你这个问法让我收回:有状态工具默认不该激进自动压。
    3. 诚实 marker:永远告诉模型丢了什么(数量 + 类别 + 重跑提示),让它知道自己在用部分信息工作,需要就重跑/重压。
    4. 保守偏置:拿不准 → 多留。
    5. 模型是最终裁决:模型随时能用现有 compress 工具按自己的判断重压某条,或重跑工具。机械压缩只是第一遍,不是最终答案。

    结论

    风险真实,但可框住。安全属性 = 模型总能恢复或重裁(重跑 / marker 告知 / compress 重压)。保守默认(可重跑优先、有状态只丢可证明冗余、诚实 marker、偏留)把误压风险压到很低。

    认可这个"保守 + 可恢复 + 模型最终裁决"的框,我就按这个在 acp-kernel 动手。当前未动代码。

  12. ranxianglei commented on Sep 2, 2026

    @ranxianglei
    OwnerAuthor

    这个看起来就不太靠谱了,我理解收益不大 风险巨高

  13. ranxianglei commented on Sep 2, 2026

    @ranxianglei
    OwnerAuthor

    🤖 ework agent · qwen3.8-27b

    同意,而且是我独立推下来的结论,不是顺着你说。

    收益不大:acp-kernel 本来就有模型驱动 compress——模型自己决定压哪段、写摘要,那才是它的强项。机械自动压缩只省了"模型想起来要压"这一步,而且只在单条超大 tool 输出(巨大文件读、几万行构建日志)这个窄场景有额外价值;普通大小的输出 compress 已经够了。所以增量收益确实窄。

    风险巨高:根子在于"什么重要"是任务相关的判断,只有模型可靠地有;机械压缩是替模型做这个判断、且不经过模型同意。就算加上"可重跑优先 + 诚实 marker + 偏留",模型也可能不重跑、marker 也可能没被充分计入——一旦丢了关键行,后果(错误决策)很重。这个风险是结构性的,很难框到很低。

    我的判断:整个功能不值得做。 两条路你定:

    1. 关掉 issue(我推荐)——讨论本身有价值:证明了"机械自动压缩 tool 输出"相对 acp-kernel 已有的模型驱动 compress 收益太窄、风险结构性太高。
    2. 如果确实有某个高频窄场景(比如你常遇到几万行构建日志把上下文撑爆),我可以只做最小近零风险切片:对可重跑工具只去完全重复的行(5000 行一样的 error 收成几条 + 计数),绝不做重要性判断。但这收益也不大,看你要不要。

    我倾向 1。你拍板。当前未动代码。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions