Skip to content

Content-addressed message store + on-demand retrieval (acp_retrieve) — CCR foundation (from billion-context#1097) #352

Closed

Description

@ranxianglei

来源: ranxianglei/billion-context#1097 分析 content-addressed message store + acp_retrieve(built-in CCR)时发现

背景 / Motivation

billion-context #1097 要把 absorb 从「默认强制有损」升级为「默认无损、省略才有损」:超大工具结果的原文进每会话内容存储,线上只留占位符,模型按需 acp_retrieve 拉回全文。

owner 裁定(#1097):这是内核先行的工作。内容寻址存储(与 blockContents 合一)、按需拉回的原生支持(占位符格式、retrieve 权限、与「编号永不复用」契约的一致性)都属于 acp-kernel 的管线。本 issue 是内核侧的设计请求;billion-context 侧做接入(工具注册、占位符渲染、原文缓存),对应原型已在 billion-context PR #1099。

为什么归属内核

现有积木都在内核里,只差统一成一个内容寻址层:

  • 稳定 per-message ref(mNNNNN 编号)= ID 方案(messageRefs.byRaw / byRef)
  • blockContents 持久化 = 存储载体(StateStore envelope,与 stableSystem 同路径:原子写、compaction-proof、零新依赖)
  • decompress = block 级恢复(当前仅整段 folded range)
  • search_context = 发现
  • 「编号永不复用」= 内核硬保证(ref 一旦分配,即使消息被 fold / edit / truncate 也永不重发)

把 store 放进内核才能做到:单一持久化路径、单一真相源、且天然满足 id-never-reused 契约(host 层无法保证这一点)。

请求的内核能力

1. 内容寻址存储(与 blockContents 合一)

  • 每会话一个 store:folded-block 原文 与 超限工具结果原文共存于同一持久化路径(现有 StateStore envelope)。
  • 内容寻址去重:同一内容(hash)绝不落盘两次。
  • 追加式:每个 ref 的原文 append-only,不随 fold / edit 改变或释放。

2. 占位符契约(placeholder contract)

  • 确定性占位符格式,携带元数据(kind/tool、tokens、head preview、ref),无模型调用生成,到达后 byte-stable(prefix-cache 友好)。
  • 建议 wire shape(供讨论):
    📦 [stored #m00423 · shell output · 4,213 tok] `npm run build`
       → acp_retrieve("m00423") returns the full text
    

3. retrieve 契约 + 权限(retrieve primitive)

  • 内核级操作:按 ref 取回原文(acp_retrieve 背后的内核原语)。
  • 必须尊重 id-never-reused:ref 永远映射到唯一原文,即使该消息后来被 fold / edit / truncate / archived。
  • 需定义 retrieve 与 compaction / archive([bug] 0.0.90 regression: syncBlocks throws on id-less host-shaped messages (baseIdOf of undefined) #421 applyCompactionArchive 会 prune ref maps)的交互——存储的 ref 不得因 archive 失效,或明确 retention 策略。
  • retrieve 注入是 ephemeral:取回内容作为 trailing request-only message(与 nudge / systemNotes 同通道),永不进入 fold space、永不消耗 message ref。

4. 与 id-never-reused 契约的一致性

  • store 按 ref 存原文,不得导致被释放的 ref 被重新签发(assignRefsNode 游标 = highestUsedIndex+1,收缩 map 会掉游标)。store 应是 per-ref append-only,不参与 ref 空间的回收。

5. absorb 默认阈值调整(行为变更,需显式披露)

  • minToolTokens: 1000 → 4000(内核默认,src/absorb.ts 的 DEFAULT_ABSORB_CONFIG.minToolTokens,当前值 1e3)。
  • old → new:1000 → 4000。原因:提高强制蒸馏门槛,减少不必要的有损 churn,给无损 CCR 让路。
  • 注意:DEFAULT_ABSORB_CONFIG.enabled 仍为 false(absorb 默认关闭)→ 无回归风险,改动面可控。

设计约束(承自 #1097)

  1. 只在到达时替换(live-zone):内容在工具结果到达时替换一次,之后字节不再变化;占位符元数据确定性生成。
  2. tool-pair 完整性:OpenAI 系 wire 上只允许工具结果内部内容缩小,assistant tool_calls 的配对必须存活(fold 路径已强制的同类约束)。
  3. retrieve 注入 ephemeral:trailing request-only message,不进 fold space、不占 ref。
  4. 占位符要够信号(command / path / size),让模型不拉取也能判断相关性。

Phasing

  • v1:超阈值文本工具结果 → ID-reference + acp_retrieve;与 absorb 共存(ID-reference 优先,仅语义压缩需要的内容才走模型蒸馏)。
  • v2:block summary 携带覆盖的 message ID 列表;decompress 增加 range 级恢复;search_context 返回 ID 而非仅 snippet。
  • v3:planning-aware retrieval(todo/task 状态对候选排序,LineRetriever 风格);依赖独立,可单独落地。

兼容性 / 风险

  • 纯增量;absorb 默认关闭 → 无回归。
  • Hallucinated IDs → retrieve 返回 not-found,代价一次工具调用。
  • 模型从不 retrieve(静默丢失)→ 强占位符元数据 + nudge 提示;在 status 里度量 retrieve rate。
  • 缓存交互 → 到达时替换保持前缀稳定;ephemeral retrieve 注入不碰 anchor。

参考

  • billion-context#1097(设计 + owner 裁定)
  • billion-context PR #1099(bili 侧接入原型:工具注册 / 占位符渲染 / 原文缓存;当前用 bili-local store 顶替,内核就绪后改为消费内核 store)

内核就绪后,billion-context 侧走配置开关 + 默认关闭接入。

Activity

  1. ranxianglei commented on Sep 22, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 Triage 完成(查重 + 审核 + 设计裁定),v1 实现进行中,PR 将回本线程。

    1. 重复判定

    无重复。相邻但不同主题的 open issue:#350(closed,pre-crush channel JSON/code)、#353(图片预压缩 + image_full restore)、#354(tool-result valuator + 确定性压缩插件接口)。本 issue 是「内容寻址存储 + retrieve 原语」的内核奠基,与三者正交,单独处理。

    2. 审核结论(动手前查证)

    • 积木存在性核实:per-message ref(mNNNNN,byRaw/byRef、additive-only、游标 highestUsedIndex+1)✓;StateStore envelope 机制(src/persist/store.ts,原子写/compaction-proof/零新依赖)✓;decompress/collectBlockContent(cache-safe 原语)✓;search_context ✓;「编号永不复用」硬保证(allocateFreeRef 前向扫描 + Revert "fix: reclaim dead message refs, reuse exhausted capacity (#176)" — ref slot reuse is unsafe #191 revert)✓。
    • 一处归属修正:blockContents 与 applyCompactionArchive 是 billion-context 侧概念(前者是 bili 的 per-block 原文缓存,后者在 bili src/session.ts——[bug] 0.0.90 regression: syncBlocks throws on id-less host-shaped messages (baseIdOf of undefined) #421 里它在 omp native compaction 后把 byRaw/byRef prune 到 live raw ids、nextIndex 不动)。内核里没有这两个对象。因此「与 blockContents 合一」在内核侧落地为:内核交付统一的内容寻址 store 形状 + 持久化机制(StateStore),bili 把现有 blockContents 数据迁移进同一 store(PR #1099 原型切换点)。内核保持 zero-I/O(DESIGN.md 核心原则:core holds no state, host persists)。
    • 层次判断:根因确实是缺一个统一内容寻址层(不是症状级修补);五项请求能力与管线架构一致,方案成立。

    3. 设计裁定(issue 中留白项)

    1. 存储布局(纯数据,host 经 StateStore 独立记录持久化,与 blockContents 同 envelope 路径):
      { version, byHash: Record<sha256, text>, byRef: Record<ref, {hash, rawId, kind, toolName?, tokens, head}> }
      • 内容去重:byHash 同 hash 只落一份;ref→raw 别名在写入时固化 → [bug] 0.0.90 regression: syncBlocks throws on id-less host-shaped messages (baseIdOf of undefined) #421 式 archive prune 掉 messageRefs 后,retrieve 仍按 store 自己的 byRef 解析,存储的 ref 不因 archive 失效(issue 要求项);append-only,首次写入为准,不参与 ref 空间回收。
      • 代际边界:store 随 session state 走;Responses/codex rebase(refs 重置 m00001)时 host 随 state 重置 store,杜绝跨代 ref 撞号;omp in-session compaction 不重置 state → store 不受影响。retention(清理)明确为 host 策略(与 store.ts「cleanup is downstream policy」一致)。
    2. 占位符:采用 issue 建议 wire shape,加确定性标记 [acp-stored 用于幂等检测与 absorb 排除;元数据(kind/tool、tokens、head preview、command)无时间戳/随机成分,token 数在到达时固化 → 之后 byte-stable(prefix-cache 友好)。
    3. 管线节点 ccr-store:位于 prune 之后、absorb-hide/prompt 之前(需 assignRefs 已出 ref;新结果落在 preserve-recent 区不会被 prune 吃掉)。只在到达时替换一次,后续轮次幂等跳过。ID-reference 优先:absorb 候选检查跳过带标记的占位符。
    4. retrieve 原语 + ephemeral 注入:core.retrieve(store, ref) → 原文 | not-found(hallucinated ID 代价 = 一次工具调用)。注入消息用保留前缀 acp_retrieved_<ref>(role=system, text,同构于 acp_summary_):assignRefs 跳过(永不消耗 ref)+ boundaries 收集 messageIds 时排除(永不进 fold space),即使 host 未剥离而 round-trip 也安全。OpenAI 系 wire 要求每个 tool_call 有配对 tool response → 工具结果本身是短 ack,全文走 trailing request-only message(host 持久化前剥离,与 nudge 同通道)。
    5. 工具注册:照 absorb 的 opt-in 模式 —— acp_retrieve 不进 ACP_TOOL_NAMES,仅 config.ccr.enabled 时注册/注入;CCR 排除自身工具结果(防 retrieve 结果再被 store 的死循环)。三套 wire schema(Anthropic/OpenAI/Responses)齐备。
    6. v1 范围:store + 占位符 + 节点 + retrieve 原语 + 工具 schema + status 度量(storedCount/retrievalCount)。folded-block 原文入库做可选开关 ccr.storeCompressedMessages(默认 false,导出 storeCoveredOriginals() 供 adapter 在 applyCompression 后调用)——v2 range 级恢复的地基,默认不改变任何现有行为。

    4. ⚠️ 行为变更披露(强制项)

    DEFAULT_ABSORB_CONFIG.minToolTokens:1000 → 4000(两处同步:src/absorb.ts:28 + src/config.ts:37)。

    • old → new:1000 → 4000。DEFAULT_ABSORB_CONFIG.enabled 保持 false → 默认用户零影响。
    • 受影响面:显式开启 absorb 且未自设 minToolTokens 的 host,强制蒸馏门槛从 1000 tok 升到 4000 tok(1k–4k 的结果不再触发 absorb prompt)。原因:提高有损蒸馏门槛、减少 churn,给无损 CCR 让路(issue 第 5 项明确要求)。
    • 新增 Config.ccr.minToolTokens 默认同为 4000,两阈值对齐。

    5. 计划

    v1 实现 + 全量测试 → PR(Closes #352)链接回本线程。分支 2026-09-23_ccr-content-store。

  2. ranxianglei commented on Sep 22, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 内核侧 CCR 基础已实现完毕 → PR #358(Closes #352):#358

    交付内容(对照 issue 的 5 项请求)

    新模块 src/content-store.ts + src/ccr.ts(+32 个测试于 tests/ccr.test.ts,全套 798/798 通过):

    1. 内容寻址存储 — MessageContentStore:每会话一个 store,sha256 内容寻址去重(byHash)+ ref 索引(byRef),per-ref append-only、first-write-wins。内核保持零 I/O:store 是纯数据 JSON envelope({version, byHash, byRef}),由 host 与 CompressionState 走同一条 StateStore 持久化路径(README 有指引)。folded-block 原文可由 host 在 applyCompression 后调用导出的 storeCoveredOriginals() 补入——v1 不自动接线(避免扩大 applyCompression 的 API 面),作为 v2 groundwork。
    2. 占位符契约 — 确定性生成、无模型调用、跨 turn byte-stable:
      📦 [acp-stored #m00423 · shell output · 4,213 tok] `npm run build`
         → acp_retrieve("m00423") returns the full text
      
      kind 标签(shell output / file read / search output / web fetch / tool result)+ token 数 + command/path head(≤ maxHeadChars,默认 96)。到达时替换一次,之后字节不变;重复见到(含带 dcp tag 回传的形态)幂等跳过。
    3. retrieve 原语 — core.retrieve(store, ref) / applyRetrieve:命中返回 {ok, text, ackText, injection, entry};injection 是 ephemeral acp_retrieved_* trailing message——不消耗 ref(assignRefs/rebuild 显式跳过)、不进 fold space(resolveBoundaries 排除)、穿过 prune/hide 节点存活。幻觉 ref → not-found ack(代价一次工具调用)。RETRIEVE_TOOL 三套 wire shape 按 absorb 同款 opt-in 模式导出(不在 ACP_TOOL_NAMES 里)。
    4. id-never-reused 一致性 — store 按 ref 存原文但完全独立于 ref 空间回收:first-write-wins 保证即使消息被 fold/edit/truncate、甚至 messageRefs 被 archive 式 prune(billion-context#421 场景),ref→原文映射仍指向唯一原文。有专门测试模拟 archive prune 后 retrieve 成功。retrieve 注入永不进入 assignRefs 游标路径,不会导致编号重发。
    5. absorb 共存 — 占位符标记的结果不是 absorb 候选(ID-reference 优先,仅语义压缩需要的内容才走蒸馏)。

    管线接入:ccr-store 节点插在 canonical order 的 prune 之后、filter 之前;processTurn 接受可选 input.contentStore(省略 = 空 store,存量会话零影响),结果恒带回 result.contentStore;status breakdown 新增 storedMessages/retrievals(度量 retrieve rate,对应「模型从不 retrieve」风险的观测手段)。

    ⚠️ 行为变更披露(必须明示)

    • DEFAULT_ABSORB_CONFIG.minToolTokens: 1000 → 4000(src/absorb.ts + src/config.ts defaultConfig 两处同步)。原因:提高强制蒸馏门槛,把大结果处理让位给无损 CCR,减少不必要的有损 churn。无回归面:enabled 仍为 false(absorb 默认关闭),只有显式开启 absorb 的配置受影响且可自行钉阈值;CCR 本身同样默认关闭(config.ccr.enabled: false)。
    • 其余全部纯增量:新功能默认关闭,ProcessTurnResult 新增必填字段 contentStore(对直接解构 result 的 host 是 additive 变更,类型层面新增字段,运行时向后兼容)。

    验证

    npm run typecheck 干净 · npm test 798/798 · npm run build OK。新文件 prettier-clean;仓库既有格式债未动。

    留给 owner 的设计决定(如不同意可改)

    1. store 由 host 持久化而非内核落盘——内核零 I/O 原则(DESIGN.md),与 blockContents/stableSystem 的 StateStore 路径合一由 host 侧完成;billion-context 侧接入时即用现成 StateStore。
    2. v1 不自动把 folded 原文灌入 store——storeCoveredOriginals 留作 host 可调用的导出原语;若你希望 applyCompression 内建(加配置开关),说一声我补上。
    3. 小问题顺带报告(不单独立项):AGENTS.md 模块图此前就漏了 src/absorb.ts 一行(既有疏漏,本次已补 ccr/content-store 两行,absorb 行未动以免混入无关 diff)。

    v2(block summary 携带 message ID 列表、decompress range 级恢复、search_context 返回 ID)与 v3(planning-aware retrieval)依赖本 PR 落地后可独立跟进。

    中文摘要:实现了 issue 请求的内核侧 CCR 基础(内容寻址存储 + 确定性占位符 + acp_retrieve 检索原语),纯增量、默认关闭,唯一行为变更是 absorb minToolTokens 1000→4000(absorb 仍默认关闭,无回归),PR #358 待评审合并。

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