Skip to content

[RFC] acp_rule lifecycle & CRUD design: source of truth, full semantics, protection as downstream conclusion #390

Open

Description

@ranxianglei

来源: #378 (PR, #378) 分析 #377「acp_rule 调用对保护应随规则存活性条件化」时发现 — 维护者于 2026-09-24 决定搁置 PR #378,要求先出综合设计、再回来重做。本 issue 即该设计任务。

背景

需要回答的三个问题

  1. 生命周期所有权(source of truth):存活规则的单一事实源是谁——宿主执行器状态(billion-context server-side rules 表)、内核会话状态(类 CCR envelope,由 adapter 每轮传入)、还是流推导?
  2. 完整 CRUD 语义:
    • record 重复提交是更新还是复制?(幂等语义)
    • rule id 是否单调递增、永不复用?(决定「终态集合成员资格 = 逐事件存活性」是否成立——与 §2 principle 6 的 ref 不可变同一纪律)
    • 规则是否跨会话?fork recovery / rebuild 后如何恢复?
    • 与 native compaction / ref 重置如何交互(dead pair 被折叠吸收后,与 block summary、CCR 检索的关系)?
  3. 保护语义(下游结论):基于前两问的答案,哪些消息/pair 保持保护;fold gate、assignRefsNode BLOCKED、filterProtectedToolMessages、CCR skip-store、absorb/crush refusal 五个消费点如何统一消费该信号。

方案对比

维度 A 流推导(= PR #378) B 内核会话表(解析 acp_rule 调用参数) C 宿主声明 typed state(adapter 每轮传入快照/diff)
事实源 无(每次从流重建) 内核第二副本 宿主执行器(唯一)
对格式漂移的鲁棒性 差(嗅探结果字符串) 较好(内核拥有工具参数 schema) 强(消费类型结构,不碰字符串)
plugin 模式可行 ✓ 零同步 ✓ ✓(adapter 查 server)
失败操作脱同步 不存在该概念 有(remove 不存在的 id 失败等,内核副本漂移) 无(快照为准)
能承载 CRUD 语义 ✗(只有存活性) 部分 ✓
成本 低 中 中(adapter 接线 + plugin 模式一次查询)

建议:以 C 为主机制(typed state 进 CompressionState,如 state.rules = { version, entries: [{id, text, ...}] },事实源保持在宿主执行器,billion-context server 本就持久化 rules,#1178 增加删除);叠加 B 式乐观本地更新(观察到成功调用立即更新本地镜像,下一快照对账),使压缩决策不必等往返;A 降级为可选 fallback(默认关)或移除。这样格式漂移不再影响正确性(最多影响展示层),CRUD 语义有了归属(宿主执行器 + typed 契约),保护语义成为纯下游读取。

待 owner 确认的两个语义点:

  • 重复 record:建议同 id 重复提交 = 幂等更新(覆盖 text,不新增条目);是否允许显式 update action,需与 billion-context 执行器行为一起定。
  • 跨会话:server 端持久化暗示是;内核侧只接收快照、不拥有状态。

约束

  • 缓存安全(owner 条件):自然折叠发生前请求字节不变。
  • §7.3 protected-tool filtering 契约的变更仍须人工把关。
  • Zero runtime deps、platform-agnostic;wire 格式变更遵循 cross-repo 顺序(kernel 先发)。
  • 若采用 B/C,rule id 沿用「永不复用」纪律。

状态

设计讨论阶段 — owner 拍板方案前不要实现。 相关:#377(原始问题)、PR #378(参考实现,draft)、billion-context#1177 / #1178 / #1179。

Activity

  1. ranxianglei commented on Sep 24, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    #390 设计分析完成。 结论先行:同意以 C 为主机制,附三点修正(保持扁平数组形状 / 跳过 B 式镜像层 / A 完全移除而非降级 fallback)。按 issue 约束,未开始任何实现,等拍板。

    0. 查重结论

    全仓(open+closed)检索 acp_rule:无并行设计任务。相关线程均已在 issue 正文关联(#377、PR #378、bili#1177/#1178/#1179、pi#433/#490)。本 issue 是唯一设计任务,不重复。

    1. 前提核实(全部对照当前代码验证,非转述)

    内核侧(master d3808d6,v0.0.86):

    • src/protected.ts:10 ALWAYS_PROTECTED_TOOLS = ["compress", "acp_rule"],在 isMessageProtected 内无条件先行判定(:70);宿主钩子(config.isToolProtected)在其后、只能加保护不能撤。
    • 五个消费点全部汇聚到该谓词:fold gate src/recommend.ts:174,211;assignRefsNode src/compress.ts:592-620;filterProtectedToolMessages src/compress.ts:1253;CCR skip-store src/ccr.ts:293;absorb refusal src/absorb.ts:95,304。发现既有不一致:消费点②被 hasProtection(保护配置非空,:595-610)门控,其余四点无条件——空保护配置宿主(内核默认 protectedTools: [])今天给 acp_rule pair 普通 mNNNNN ref 而非 BLOCKED。统一谓词必须顺带修掉(行为变更披露见 §3)。
    • CRUD 原语 v0.0.80+ 已存在:src/rules.ts addRule(文本去重拒绝 :95-101)/ removeRule / clearRules / allocateRuleId(单调不复用 :67-69 + 最高存活 id 回填守卫 :54-61,id 格式 RULE_ID_RE = /^rule(\d+)$/ :52);状态字段 state.rules?: RuleRecord[](src/types.ts:257)+ state.nextRuleId(:261);持久化经 src/persist/state-merge.ts:23-24 携带;rebuildCompressionState 展开输入 state(src/rebuild.ts:39)→ rules 随输入 state 保留、不从历史重放。
    • DESIGN.md:221 已定位:"rules as structured data in core; text rendering in adapter"。
    • 内核不拥有 acp_rule JSON schema(compress-tools.ts 零引用),schema 由宿主定义(bili src/compress-tool.ts、pi src/rule-tool.ts),但 record 参数名两边一致(可选 rule 文本);结果文本格式由共享执行器产出。

    宿主侧(billion-context master 浅克隆核实):

    • formatRulesForPrompt 在 src/ 全量 grep 零命中——没有任何宿主把规则注入系统提示词。规则的模型可见载体就是历史 record pair 本身。(billion-context#1259 review floor 4 的「rules still reach the model every turn via formatRulesForPrompt system-prompt injection」与代码不符,系转述内核文档;内核 README、types.ts:152-154、RULES_USAGE_PROMPT(rules.ts:29-35)同样声称「每轮重新注入」——此文档漂移建议 phase 1 PR 内标注顺手修。)
    • executeRule(src/rules-feature.ts)是 streaming loop 与 plugin tool API 共用的唯一执行器,直接 mutate ctx.session.state——执行器与折叠管线共享同一 state 实例。delete/clear 尚未接线(#1178 open),当前生产无 Removed/Cleared 事件,任何方案此刻都 no-op safe。
    • billion-context-pi#490:record-only 工具,.acp.json sidecar 跨重启持久化,deriveChildState/mergeInitialState 携带 rules/nextRuleId,明确零系统提示词参与。

    对 #377 原始前提的修正:"plugin 模式下折叠跑在 agent 自带 kernel 副本、其 state 没有 rules 表"在可核实的部署中不成立(bili 两条 lane 共享 state 实例;pi sidecar 带表)。该场景只存在于假想未来宿主(stateless 每轮重建 state / 远程执行器)。这削弱了 A(流推导)作为主机制的必要性;其安全价值(无表时仍判对存活性)可被更简单的 fail-closed 覆盖(§3 C4)。

    2. 三问回答

    Q1 生命周期所有权(source of truth)

    建议:宿主执行器拥有生命周期,内核经既有 state.rules 消费 typed 快照。 即选项 C,但有一个重要修正:机制自 v0.0.80 起已经存在——缺的不是新状态通道,而是三样东西:①显式契约(adapter 保证每轮 state.rules 反映权威存储);②以表为 liveness oracle(替代按名 ALWAYS 保护);③表缺失时的 fail-closed 定义。

    契约条文(建议入 DESIGN.md/AGENTS.md):

    • C1 规则生命周期(增删清、id 分配、持久化、跨会话范围)归宿主执行器;内核 helpers 是 mutation 语义的参考实现。
    • C2 每次 processTurn/applyCompression,state.rules 是该轮的权威存活集合;adapter 保证其新鲜度(executor 与 folder 共享 state 实例时平凡成立——所有现有宿主皆如此)。
    • C3 liveness oracle:record pair 受保护 ⟺ 其 id ∈ state.rules;非 record pair(delete/clear/list/失败)= 事件轨迹,不受保护。
    • C4 fail-closed:state.rules 为 undefined(pre-rules 状态 / 未接线的宿主)→ 所有 record pair 视为受保护(= 现状)。不确定时绝不过度释放。
    • C5 id 单调、永不复用(既有纪律,src/rules.ts:63-69)——保证任何重建路径下终态集合成员资格良定义。

    拒 A 作主机制:格式漂移耦合(内核不拥有结果字符串契约)、只编码存活性不编码 CRUD、且其动机场景无可核实实例。拒 B 另建:B 即现状(宿主经 helpers mutate 内核 state 表),再叠「第二副本 + 对账」层是为当前架构中不存在的同步问题买单——留 phase 3 规格化(仅当远程执行器架构出现时)。

    Q2 完整 CRUD 语义

    • 重复 record:今日语义 = 文本去重拒绝(返回 "identical rule already exists (ruleN)",src/rules.ts:95-101)。注意:record schema 无 id 参数(只有可选 rule 文本;delete 才按 id 定位),所以 issue 里「同 id 重复提交 = 幂等更新」不映射到现行 schema——真正的决策是是否新增显式 update action。建议:phase 1 维持现状(诚实报错、无静默覆盖、零 schema 变更);update/re-record 移入 phase 2——有下面发现的 load-bearing 理由,不宜无限期推迟。
    • id 单调不复用:是,保持(已强制,types.ts:258-261 文档一致)。与 ref 同纪律(§2 principle 6)。
    • 跨会话:是,宿主级——两个已核实宿主都持久化(bili server-side state;pi .acp.json sidecar 跨重启)。内核立场:只收快照、不拥有状态。fork/rebuild:rebuildCompressionState 保留输入 state 的 rules(src/rebuild.ts:39),在 C2 下正确;明确文档化 rebuild 不从历史重放 rule 操作(C2 下无需;而重放结果需要解析结果字符串——正是要去掉的耦合)。
    • native compaction / ref reset 交互:⚠️ 发现一个三问未显式覆盖的载体缺口,已单独立项 acp_rule carrier gap: surviving rules silently lost after historical reset events (native compaction, etc.) — requires re-materialization spec + update/re-record capability | acp_rule 载体缺口:历史重置事件(native compaction 等)后存活规则静默丢失 — 需 re-materialization 规格 + update/re-record 能力 #391(来源标记指向本 issue)。事实链:(a) 无宿主做提示词注入(§1 已证)→ 历史 record pair 是规则唯一的模型可见载体;(b) 历史替换型事件(pi native compaction、fork adoption、任何宿主侧重写历史)会抹掉这些 pair;(c) 之后 state.rules 仍有条目但无任何机制渲染回上下文 → 提醒静默死亡。phase 1 在此不引入回归(现状同样丢失,只是把既有缺口文档化);phase 2 规格:adapter MUST 在任何历史重置事件后重新物化存活规则为新 record pair(字节变化发生在重置时刻,前缀缓存彼时本已整体失效 → 满足缓存安全条件)。这需要 update/re-record 能力(今日 addRule 对相同文本拒绝,朴素重录必败)——这就是 update action 必须排进 phase 2 的理由。
    • dead pair 折叠 ↔ block summary ↔ CCR 检索:dead pair 进入自然折叠 → 被 block effectiveMessageIds 覆盖 → CCR v2(storeCoveredOriginals,bili#1179/#1207,proxy 模式默认开)归档原文、可按 ref 取回;摘要得 lossy 提及。live pair 保持受保护 → ccr skip-store(src/ccr.ts:293)阻止占位符替换 → 原文持续可见。两机制正交组合,除统一谓词外无额外工作。

    Q3 保护语义(下游结论)

    统一谓词(具体提案,替代 PR #378 的流 walk):

    // 形状复用 LatestProtected(src/protected.ts:118-131)
    export function collectRulePairProtection(
      messages: CoreMessage[], state: CompressionState,
    ): { callIds: Set<string>; msgIds: Set<string> } | undefined // undefined = 无 acp_rule 消息

    判定链(每个 acp_rule call/result pair,按 toolCallId 配对):

    1. liveIds = state.rules ? new Set(ids) : null(null = 未知 → fail-closed);
    2. record 候选 ⟺ 调用参数解析成功且含 string rule 键;解析失败 → 按 record 候选处理(fail-closed);
    3. 从结果文本提取全部 /^rule\d+$/ id token(内核拥有的 id 格式);
    4. 受保护 ⟺ record 候选 ∧ (liveIds === null ∨ 结果含 ≥1 个 live id ∨ 结果无任何 id token → fail-closed 保护)。

    鲁棒性(与 PR #378 的关键差异):前缀词无关——只耦合内核自有的 id 格式 rule\d+,不碰 "Recorded"/"Removed" 这类宿主字符串;前缀改名最坏退化为 fail-closed 过保(= 现状),不可能欠保。已知假阳性类(可接受,安全方向):list 结果含 live id 但非 record 候选(参数无 rule 键)→ 不受保护,消除「list pair 永保」累积向量;成功 record 的 text 恰好引用其他 live id → 该 pair 过保;失败的 record 尝试(超限/重复被拒,错误文本无 id token)按第 4 步 fail-closed 保留保护——小量过保换格式漂移安全,可接受。

    五个消费点统一消费(每轮计算一次,各点 union):

    # 消费点 接线
    ① fold gate src/recommend.ts:174,211 union 进 protectedCallIds + 直接检查
    ② assignRefsNode src/compress.ts:592-620 置于 hasMediaPayload 同层、hasProtection 门外(:606)——修复既有不一致
    ③ filterProtectedToolMessages src/compress.ts:1253 union 进 protectedCallIds
    ④ CCR skip-store src/ccr.ts:293 加检查
    ⑤ absorb refusal src/absorb.ts:95,304 candidate gate + apply refusal 两处加检查

    并从 ALWAYS_PROTECTED_TOOLS 移除 "acp_rule"(保留 "compress")。

    行为变更披露(old → new):

    触及 §7.3 契约 #6(protected-tool filtering)→ 人工把关;跨仓顺序:kernel 先发 → bili pin bump(待 #1178 合并后)→ pi pin bump。

    3. 方案对比结论(同意 C 主机制,三点修正)

    • R1 保持扁平 RuleRecord[],不引入 {version, entries} 信封:扁平形状已在 0.0.80+ 发布并持久化于真实会话(bili server state、pi sidecar);改信封破坏跨仓 state 兼容性,功能收益为零。日后需元数据(createdAt、human/model 来源标记)时 additive 扩展 RuleRecord 可选字段即可,向后兼容。
    • R2 跳过 B 式乐观本地镜像层:所有已核实部署中 executor 与 folder 共享同一 state 实例,"乐观更新"天然发生(mutation 即更新);现在建镜像 + 对账层是为不存在的同步问题付维护成本。远程执行器架构出现时再按 phase 3 规格补。
    • R3 A 完全移除,而非降级为 opt-in fallback:C4 fail-closed 已给无表宿主今天的(过)保护行为;流 walk 的唯一增量价值是"在无表宿主上正确释放 dead pair",而此类宿主今天不存在;为一个假想场景保留 ~130 行正则 walk 维护面不值。PR feat: conditionally protect acp_rule pairs by stream-derived rule liveness #378 分支保留为参考实现。(此处偏离 issue 的「降级为可选 fallback(默认关)或移除」二选一——我选移除。)

    4. 分阶段实施计划(拍板后执行)

    5. 待 owner 拍板(每条附我的默认建议)

    1. A 的去留:移除 vs 保留 default-off flag?→ 建议移除(R3)。
    2. update action 时机:phase 2 与 re-materialization 一起排期?→ 建议是(load-bearing:载体缺口 acp_rule carrier gap: surviving rules silently lost after historical reset events (native compaction, etc.) — requires re-materialization spec + update/re-record capability | acp_rule 载体缺口:历史重置事件(native compaction 等)后存活规则静默丢失 — 需 re-materialization 规格 + update/re-record 能力 #391 依赖它)。
    3. state.rules 形状:扁平 vs {version, entries}?→ 建议扁平(R1)。
    4. 载体策略(历史 pair vs 系统提示词注入):phase 1 假设 pair-only(已核实的现实);注入方案暂否(每次增删改头部字节 → 每次变更全量前缀缓存失效)。update 能力落地后再作为独立产品决策评估。

    6. 分析中新立 issue

    载体缺口(历史重置后存活规则静默丢失)是独立于本设计结论的既有问题,已按规范单独立项并带来源标记:#391。

    中文一句话总结:核实了全部前提(含一处修正——plugin 模式"折叠侧无 rules 表"在现有部署中不成立)后,建议以 C 为主机制(宿主拥有生命周期、内核经既有 state.rules 消费 typed 快照 + fail-closed 兜底),id 永不复用纪律保持、重复 record 维持文本去重拒绝、跨会话归宿主持久化;保护语义收敛为单一谓词统一喂五个消费点,仅耦合内核自有 id 格式、对宿主字符串漂移免疫;A 完全移除、B 式镜像层留待远程执行器出现再说;另发现"无宿主注入提示词 → 历史重置即静默丢规则"的载体缺口,已单立 #391。等你拍板 §5 四点后即可开工 phase 1。

  2. added 2 commits that reference this issue on Sep 25, 2026
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