acp_rule 持久规则:状态字段、辅助函数与硬保护(跨仓功能内核侧)

[ranxianglei]

来源: ranxianglei/billion-context-pi#433 (增接 rule 命令,专门用来记住用户对模型的特别提醒) 分析该跨仓功能时发现——本 issue 为其内核(acp-kernel)侧实现。

需求(来自 billion-context-pi#433)

三仓(billion-context-pi / billion-context / acp-kernel)增加 acp_rule 工具记录持久提醒,以内核为主。内核侧提供:

1. CompressionState.rules?: RuleRecord[]({id, text}),可选字段,旧持久化状态向后兼容
2. 辅助函数:listRules / allocateRuleId / addRule / removeRule / clearRules / formatRulesForPrompt;addRule 校验:非空、单条字符上限(默认 300)、总条数上限(默认 50)、相同内容去重
3. ALWAYS_PROTECTED_TOOLS 增加 "acp_rule" —— 调用+结果默认从压缩范围硬排除(#433 第 1 点「默认保护」)
4. RULES_USAGE_PROMPT 提示词片段 + RULE_TOOL_NAME / DEFAULT_RULE_LIMITS 常量

功能开关(默认关闭)放在各适配器(pi 的 acp.json / billion-context 三级配置);内核不加新 Config 字段,保护无条件生效(功能关闭时不存在 acp_rule 消息,无副作用)。

验证

• npm run typecheck 通过
• tests/rules.test.ts 10/10 通过(含压缩排除保护集成测试)
• 全量测试套件 748/748 通过

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 已接手。这是 #433 的内核侧实现,方案已在 billion-context-pi#433 floor 2 对齐过,直接开工:

1. CompressionState.rules?: RuleRecord[]({id, text})+ 单调计数器(可选字段,旧持久化状态向后兼容,mergeCompressionState 同步补齐)
2. 新模块 src/rules.ts:listRules / allocateRuleId / addRule / removeRule / clearRules / formatRulesForPrompt,校验按 issue 要求(非空、单条 ≤300 字符、总数 ≤50、相同内容去重)
3. ALWAYS_PROTECTED_TOOLS 增加 "acp_rule" —— 保护判定集中在 isMessageProtected,compress/recommend/absorb 三条路径自动生效,无条件(不加 Config 字段)
4. RULES_USAGE_PROMPT + RULE_TOOL_NAME + DEFAULT_RULE_LIMITS

完成后跑 typecheck + 全量测试并提 PR。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 完成 — PR: #284

中文摘要:实现了 acp_rule 持久规则的内核侧(state 字段 + 6 个辅助函数 + 无条件压缩硬保护 + 提示词片段),typecheck 干净、rules 测试 10/10、全量 734/734、build 通过,可以 review。

实现(与 issue 需求逐条对应)

1. CompressionState.rules?: RuleRecord[]({id, text})+ 单调计数器 nextRuleId?: number,均为可选字段。旧持久化状态原样加载:mergeCompressionState 对两个字段做 parsed.x ?? fresh.x 透传(src/persist/state-merge.ts)。
2. 新模块 src/rules.ts:RULE_TOOL_NAME、DEFAULT_RULE_LIMITS(frozen {maxChars: 300, maxCount: 50})、listRules / allocateRuleId / addRule / removeRule / clearRules / formatRulesForPrompt。addRule 校验顺序:非空 → 单条字符上限(trimmed 长度)→ 相同内容去重(trimmed 精确匹配,报错指向已有 id)→ 总条数上限;全部返回不可变新 state(同 applyAbsorb 约定)。
3. ALWAYS_PROTECTED_TOOLS 增加 "acp_rule"(src/protected.ts)——无条件生效,不加 Config 字段。保护判定集中在 isMessageProtected,compress/recommend/absorb 三条路径自动覆盖;宿主未投影 toolName 的 result 半边由既有 collectProtectedToolCallIds pairing 兜住(集成测试里 result 正是无 toolName 的)。
4. RULES_USAGE_PROMPT:覆盖 #433 的四类触发场景(用户特别强调/反复强调/要求记住行为/自己踩过的坑),要求短而原则级、先 list 后 add、remove/clear 管理。

设计决定(供 review)

• rule id 永不复用(沿用 AGENTS.md §2.6 never-reuse-id 原则):allocateRuleId 是纯函数(不同于会变更 state 的 allocateBlockId);nextRuleId 在 remove/clear 后不重置;另有 max(counter, 已存在最大号+1) 守卫防手工构造 state。理由:model 会在 summary/引用里记 rule id,复用编号会造成静默错指。
• 未加入 ACP_TOOL_NAMES:与 acp_absorb 同为适配器 opt-in 功能(开关默认关闭放 pi/billion-context);保护虽无条件,但功能关闭时不存在 acp_rule 消息,零副作用。
• formatRulesForPrompt 空规则时返回 "" —— 空会话零 token 开销。

验证

• npm run typecheck ✅ 干净
• tests/rules.test.ts ✅ 10/10(含集成测试:protectedTools: [] 下 acp_rule call+result 同时被排除出 directMessageIds 和 effectiveMessageIds,证明无条件保护)
• 全量套件 ✅ 734/734(改动前基线 724,+10 即新测试)
• npm run build ✅

分支 2026-09-13_acp-rule-persistent-rules,commit 1bba844(7 files, +384/-2,未动 version)。等 review 后由你合并。

[ranxianglei]

Implementation landed in #332 (branch 2026-09-20_acp-rule-reconcile, based on current master).

Pre-flight: typecheck PASS · npm test 861/861 (15 new tests in tests/rules.test.ts) · build PASS.

Two documented deviations from the original spec here, driven by the concrete consumer (billion-context#750, port of the pi feature):

1. Config.rules?: RulesConfig {enabled?, maxRules?, maxRuleChars?} exists — the host gates the tool on config.rules.enabled === true and carries limit overrides through the resolved Config, so the kernel must accept the field (and validateConfig range-checks it). The "no Config field, defaults only" stance would make #750 unimplementable as written.
2. State-mutating helpers (addRule returns {ok:true;rule}|{ok:false;error}, mutates the passed state) rather than immutable state returns — #750's executeRule discards returned state, an immutable-only API would silently drop rules.

Supersedes #283 and #284 (competing implementations of this spec — see the comparison table in the PR). Close whichever of the three survives review after #332 lands.

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

Review of #332 complete — verified against current master and against the actual consumer (#750). Ready for your merge.

Verified

• Base: PR base = 043cc68 = origin/master HEAD → no stale-base risk. Single commit, 10 files (+431/−2), no version bump, no unrelated churn.
• Pre-flight (re-run locally on the branch): typecheck PASS · npm test 861/861 (baseline 846 + 15 new) · build PASS.
• CI: all green on the head commit (test Node 22 + Node 24, pr-validation, build-artifact).
• Spec coverage (point-by-point vs this issue): optional rules?/nextRuleId? state fields with back-compat passthrough in mergeCompressionState; all six helpers with addRule validation order non-empty → char cap (trimmed) → dedup (trimmed exact match, error cites existing id) → count cap; "acp_rule" in ALWAYS_PROTECTED_TOOLS unconditionally; RULES_USAGE_PROMPT / RULE_TOOL_NAME / DEFAULT_RULE_LIMITS. All four state-copy sites carry the new fields.
• §2.6 id immutability honored: allocateRuleId is pure, monotonic, never reset by remove/clear, with a max(counter, highest existing id + 1) backfill guard — consistent with the no-ref-reuse principle. Correctly kept out of ACP_TOOL_NAMES (adapter opt-in, same stance as acp_absorb).

Deviations — both confirmed necessary against the real consumer

I checked #750's actual source rather than taking the justification on faith:

1. Config.rules — #750 gates the tool on config.rules?.enabled === true and threads limit overrides through the resolved Config. Without the kernel field, #750 doesn't compile. The original "no Config field" stance is not viable for this consumer. Accepted.
2. State-mutating helpers — #750's executeRule calls addRule(state, ...) and discards the return value, relying on in-place mutation. An immutable-only API would silently drop every rule. Accepted.

Both are documented in the PR body — good.

Supersedes claim — holds

• feat(rules): acp_rule persistent rules — state field, helpers, hard protection #283 overlaps feat(rules): acp_rule persistent rules — reconciled API (state, limits, hard protection) #332 on 7 files, feat(rules): acp_rule persistent rule records with hard compression protection #284 on 9; both collide on the core module (src/rules.ts + tests/rules.test.ts) → genuinely mutually exclusive implementations.
• Decisive point: #750 imports formatRulesList, which exists only in feat(rules): acp_rule persistent rules — reconciled API (state, limits, hard protection) #332. Neither feat(rules): acp_rule persistent rules — state field, helpers, hard protection #283 nor feat(rules): acp_rule persistent rule records with hard compression protection #284 satisfies the consumer's import surface, so "supersedes" is correct, not just a preference call.

Fixed directly in the PR branch (no round-trip)

Repo-wide Prettier drift exists (104 files dirty, including master itself — pre-existing, out of scope), but the three files this PR introduced/touched were newly non-conformant (src/config.ts, src/rules.ts, tests/rules.test.ts). Pushed 04e97cd (style: commit, formatting only — verified word-diff shows zero semantic changes); typecheck/test/build re-run green, CI green on the new head.

Minor observation, left as-is: validateConfig range-checks maxRules/maxRuleChars with Number.isFinite && >= 1 but doesn't require integrality — a fractional limit like 1.5 passes and behaves as floor() in addRule. Zero practical impact; tightening it is a product call if you want it.

Gate & next steps

Per AGENTS.md §7.4, this one stays human-gated: it adds a Config field (config/schema is a structural constraint), it's a feat: not a pure fix, and it touches the protected-tool filtering contract surface (§7.3 item 6). It does not qualify for auto-merge — please merge manually when ready: #332

After it lands I'll close #283 and #284 as superseded (with links to this thread), and #282 closes via the PR's Closes #282. Nothing closed yet since #332 hasn't landed.

---

中文摘要:已完整 review #332——基线最新、typecheck/测试(861/861)/build/CI 全绿,两条偏离(新增 Config.rules 字段、可变式辅助函数)经对照 billion-context#750 实际代码确认均为该消费方所必需,"取代 #283/#284" 的判定成立(#750 依赖的 formatRulesList 仅 #332 提供);已直接在 PR 分支补了一个纯格式修复 commit(04e97cd,CI 绿)。因涉及新增 Config 字段与保护工具契约面,按规范不可自动合并,请你手动合并;合并后我会关闭 #283/#284。