opencode-acp 1.12.10 → 1.13.1

package/NOTICE

@@ -0,0 +1,29 @@
+opencode-acp — NOTICE
+
+Copyright (c) 2026 ranxianglei
+Licensed under AGPL-3.0-or-later (see ./LICENSE).
+
+This distribution bundles portions of context-compress-algorithms
+(https://github.com/ranxianglei/context-compress-algorithms), which is
+originally published under the MIT License. The MIT-licensed source retains
+its MIT status when consumed directly from that project; the bytes inlined
+into this AGPL distribution become part of the combined AGPL work.
+
+For the standalone MIT-licensed version, install
+`context-compress-algorithms` directly.
+
+MIT License (context-compress-algorithms):
+
+  Copyright (c) 2026 ranxianglei
+
+  Permission is hereby granted, free of charge, to any person obtaining a
+  copy of this software and associated documentation files (the "Software"),
+  to deal in the Software without restriction, including without limitation
+  the rights to use, copy, modify, merge, publish, distribute, sublicense,
+  and/or sell copies of the Software, and to permit persons to whom the
+  Software is furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

package/README.md

@@ -4,6 +4,8 @@
 <strong>Active Context Pruning</strong> for <a href="https://opencode.ai">OpenCode</a>
 <br />
 The model decides <em>when</em> and <em>what</em> to compress — not a hard limit.
+<br />
+<strong>200K tokens is enough.</strong>
 </p>
 
 ---
@@ -28,10 +30,14 @@ is, to date, the best context-management implementation on the market.
 
 This brings two concrete effects:
 
-- **It saves about two-thirds of tokens.** A model with a 1,000,000-token context
-  window effectively runs in the **200,000–300,000 token range**.
-- **It supports ultra-long sessions without losing key content** — **500M-token-level
-  cumulative context, 100,000 messages per session**.
+- **200K tokens is enough.** Across 30,000+ API calls in 50 real engineering
+  sessions, **97% of requests stayed under 200K tokens** — p90 at 150K, p95 at
+  180K. Every API call re-bills the full context, so keeping context low directly
+  reduces cost — even with a 90%+ prompt-cache hit rate, the non-cached portion
+  is billed at full price.
+- **It supports ultra-long sessions without losing key content** — observed at
+  **3,300+ messages and 300M+ cumulative tokens** per session; architecturally
+  supports up to **100,000 messages** (5-digit message-ID space).
 
 ---
 
@@ -39,22 +45,23 @@ This brings two concrete effects:
 
 Real engineering context, in practice.
 
-**Supports 500M-token-level cumulative context, with p95 context around 30% and
-an average prompt-cache hit ratio above 85%.** (That average — not per-session —
-is explained in [Impact on Prompt Caching](#impact-on-prompt-caching), where it
-turns out to save far more tokens than traditional compression.)
-
-|                            | Session 1   | Session 2   |
-| -------------------------- | ----------- | ----------- |
-| **Messages**               | 3,024       | 2,028       |
-| **Total tokens processed** | 582 M       | 463 M       |
-| **Prompt-cache hit ratio** | 86.2%       | 89.0%       |
-| **Context p50 (median)**   | 1.2 K (<1%) | 1.8 K (<1%) |
-| **Context p75**            | 2.8 K       | 3.5 K       |
-| **Context p90**            | 108 K (11%) | 58 K (6%)   |
-| **Context p95**            | 251 K (25%) | 335 K (34%) |
-| **Context p99**            | 425 K (43%) | 442 K (44%) |
-| **Peak**                   | 488 K (49%) | 769 K (77%) |
+**Across 6 active engineering sessions (11,000+ API calls), context p90 stays
+at 150K–190K (15–19%), p95 at 160K–210K (16–21%) of the 1M window — with an
+aggregate prompt-cache hit ratio of 91%.** (Why aggregate — not per-session —
+matters is explained in [Impact on Prompt Caching](#impact-on-prompt-caching),
+where it turns out to save far more tokens than traditional compression.)
+
+| Session   | Duration    | Messages | API calls | Cumulative | Cache hit | Context p50 | Context p90 | Context p95 |
+| --------- | ----------- | -------- | --------- | ---------- | --------- | ----------- | ----------- | ----------- |
+| 0b89319b  | 230h (9.5d) | 3,344    | 2,796     | 339M       | 93%       | 108K (11%)  | 167K (17%)  | 210K (21%)  |
+| 0a3be0cd  | 130h (5.4d) | 3,183    | 2,499     | 276M       | 91%       | 104K (10%)  | 145K (15%)  | 153K (15%)  |
+| 0b2cd5a7  | 131h (5.4d) | 2,560    | 2,181     | 314M       | 91%       | 142K (14%)  | 191K (19%)  | 197K (20%)  |
+| 08f2d501  | 37h (1.5d)  | 1,985    | 1,888     | 196M       | 95%       | 100K (10%)  | 156K (16%)  | 168K (17%)  |
+| 1410c791† | 865h (36d)  | 1,279    | 1,100     | 218M       | 87%       | 132K (13%)  | 407K (41%)  | 427K (43%)  |
+| 096cf8c4  | 72h (3d)    | 1,041    | 918       | 91M        | 89%       | 92K (9%)    | 148K (15%)  | 161K (16%)  |
+
+† Bug-testing session; p95 is abnormally high. Excluding it, p95 stays ≤ 210K
+across all other sessions.
 
 (Context percentages are of the 1M window.)
 
@@ -81,9 +88,10 @@ Or add to your opencode config:
 ## How It Works
 
 ACP hands the context-compression tool directly to the model. The model is
-**100% responsible** for context compression. The model's available tools are
-mainly: **compress** and **decompress**. A hardcoded 100% GC fallback acts as
-a safety net when the context window is completely full.
+**100% responsible** for context compression. The model's primary tools are
+**compress** and **decompress**, supported by **acp_status** (context monitoring)
+and **search_context** (search compressed content). A hardcoded 100% GC fallback
+acts as a safety net when the context window is completely full.
 
 ### Lifecycle
 
@@ -122,27 +130,46 @@ interfere with the model's self-attention, short blocks lead the model to compre
 some content first, handle the urgent matter, then decompress what it needs in
 later work.
 
-### Deletion strategy
+### GC safety net
+
+When context reaches 100%, the system automatically truncates old-gen block summaries to prevent overflow. This is a last-resort safety net and does not interfere with the model's normal compress/decompress operations.
+
+### Quality gate (non-blocking, off by default)
+
+After each `compress` call, ACP can run a pluggable quality gate to detect summaries that catastrophically lost content (e.g., a 5K-token range compressed to a 147-char summary with none of the technical keywords). Failures only emit `logger.warn` — they never reject the compression (the result is already committed to state and visible to the model).
+
+The default algorithm (`rouge-recall-v1`) is a two-layer gate calibrated against 6,913 real-world blocks:
+
+- **L1 (length floor)**: Catches catastrophic retention failures — summaries shorter than 200 chars OR with <1% retention vs. the original. 100% recall, 0% FPR.
+- **L2 (content coverage)**: Only runs on blocks that pass L1. Flags when **both** ROUGE-1 F1 < 0.05 **and** top-20 keyword recall < 0.20 (AND-combine keeps FPR at ~6.6%).
+
+The interface is pluggable: future algorithms (e.g., LLM-as-judge via external API) can be registered through `registerQualityGate()` without touching pipeline wiring. Tokenizer uses hand-rolled word-level tokenization (English keywords + Chinese unigrams/bigrams) — not ACP's BPE tokenizer, which is too coarse for ROUGE-style matching.
 
-To handle the accumulation of many small historical blocks, the new version adds
-a deletion strategy. The model decides whether to delete. **Once deleted, content
-is irrecoverable.** This replaces the original forced GC, so that forced garbage
-collection no longer deletes things the model considers important.
+Off by default for one release of burn-in. To enable:
+
+```jsonc
+{
+    "qualityGate": {
+        "enabled": true,
+        "algorithm": "rouge-recall-v1",
+    },
+}
+```
 
 ---
 
 ## Impact on Prompt Caching
 
 Historically, ACP has fixed many of the low-cache-hit-rate problems caused by
-DCP. The overall cache hit rate is now **~87%**.
+DCP. The overall cache hit rate is now **~91%**.
 
 Compared to traditional compression — which only compresses at 80–90% and, once it
 compresses, forces 100% of the context to re-hit — ACP's hit rate is effectively
 higher.
 
-Additionally, ACP keeps total context around **~30% most of the time**, versus the
-traditional **50–80%**. So total token savings are far higher than traditional
-compression.
+Additionally, ACP keeps total context around **~10–15% most of the time** (p50
+100K, p90 150K of the 1M window), versus the traditional **50–80%**. So total
+token savings are far higher than traditional compression.
 
 **Conclusion:** ACP simultaneously raises the overall cache hit rate **and**
 ensures key context information is not lost.
@@ -209,8 +236,8 @@ Each level overrides the previous, so project settings take priority over global
     "debug": false,
     // Notification display: "off", "minimal", or "detailed"
     "pruneNotification": "detailed",
-    // Notification type: "chat" (in-conversation) or "toast" (system toast)
-    "pruneNotificationType": "chat",
+    // Notification type: "chat" (deprecated, falls back to toast) or "toast" (system toast)
+    "pruneNotificationType": "toast",
     // Slash commands configuration
     "commands": {
         "enabled": true,
@@ -319,6 +346,28 @@ Each level overrides the previous, so project settings take priority over global
         // run major GC when context usage exceeds this (hardcoded, not configurable)
         "majorGcThresholdPercent": "100%",
     },
+    // Post-compression quality gate (non-blocking; off by default)
+    "qualityGate": {
+        // Master switch. When false, no evaluation runs.
+        "enabled": false,
+        // Algorithm name. Pluggable — future algorithms (including external
+        // API judges) can be registered without changing pipeline wiring.
+        "algorithm": "rouge-recall-v1",
+        // Per-algorithm config
+        "algorithms": {
+            "rouge-recall-v1": {
+                // Hard floor on summary length (chars). Below this → L1 fails.
+                "layer1MinChars": 200,
+                // Min retention = summaryLen / (compressedTokens*4) * 100.
+                // Catches catastrophic retention failures (<1%) with 0% FPR.
+                "layer1MinRetentionPct": 1.0,
+                // L2 fails (combined with top20Recall via AND) when below this.
+                "layer2MaxRougeF1": 0.05,
+                // L2 fails (combined with rougeF1 via AND) when below this.
+                "layer2MaxTop20Recall": 0.20,
+            },
+        },
+    },
 }
 ```
 
@@ -350,7 +399,7 @@ By default, these tools are always protected from pruning:
 
 The `protectedTools` arrays in `commands` and `strategies` add to this default list.
 
-For the `compress` tool, `compress.protectedTools` ensures specific tool outputs are **hard-excluded** from compression ranges (v1.10.0+). When the model compresses a range that includes a protected tool message, that message survives intact in visible context — only the surrounding non-protected messages are compressed. By default `compress.protectedTools` includes `task`, `skill`, `todowrite`, `todoread`, and `decompress`.
+For the `compress` tool, `compress.protectedTools` ensures specific tool outputs are **hard-excluded** from compression ranges (v1.10.0+). When the model compresses a range that includes a protected tool message, that message survives intact in visible context — only the surrounding non-protected messages are compressed. By default `compress.protectedTools` includes only `skill` — this is sufficient in practice, as skill outputs are the one tool type whose content must never be lost to compression.
 
 ---
 
@@ -422,6 +471,35 @@ For the complete list with root cause analysis, see the [bug tracker](https://gi
 
 ## Changelog
 
+### v1.13.1 — cc-alg Extraction + Compress Notification Freeze Fix (PRs #167, #168)
+
+**Problem (compress notification freeze, #167)**: After every successful `compress` tool call, ACP injected a user-role notification message with a single `ignored: true` text part. opencode strips `ignored` parts before sending to the LLM, leaving an empty user message. The provider (zhipuai-lb / glm-5.2) rejects this with HTTP 400 code 1214 (`"messages 参数非法"`), `isRetryable: false` — opencode does not retry, and the session freezes until external recovery. 113 total occurrences across active sessions (8 in a single 3,156-message session).
+
+**Fix (compress notification freeze, #167)**: (1) `lib/ui/notification.ts:280-298` — `sendCompressNotification` now always uses `client.tui.showToast`; the prior `chat` branch (which called `sendIgnoredMessage`) is removed. A warn log fires once per compress when the user explicitly set `pruneNotificationType: "chat"` so the behavior change is discoverable. (2) `lib/messages/utils.ts:232-269` — `dropEmptyMessages` now treats text parts carrying `ignored: true` as contributing to emptiness, so any future ignored-only user message is dropped before reaching the provider (defense in depth). (3) `lib/config.ts:175` — default `pruneNotificationType` changed from `"chat"` to `"toast"` so default-configured users see no deprecation warning.
+
+**Problem (cc-alg extraction, #168)**: Reusable compression algorithms (ROUGE-1 quality gate, hand-rolled tokenizer, trigger policy, compression-rules prompt) were locked inside ACP's AGPL codebase, preventing MIT-licensed reuse by other projects. Internal coupling between algorithm modules and ACP plumbing made independent testing and reuse difficult.
+
+**Fix (cc-alg extraction, #168)**: 4 modules extracted to external MIT package `context-compress-algorithms@1.0.0` (npm: https://www.npmjs.com/package/context-compress-algorithms, GitHub: https://github.com/ranxianglei/context-compress-algorithms). ACP imports via `^1.0.0` and inline-bundles into `dist/index.js` via tsup `noExternal`, so hosts install no extra dependency. NOTICE file added for MIT attribution of bundled code. New trigger policy registry at `lib/messages/inject/policy/` enables host-side customization of nudge trigger behavior (default policy comes from cc-alg's `defaultTriggerPolicy`). Provenance audit confirmed zero derivation from DCP upstream (AGPL-3.0) — search for `rouge` / `qualityGate` / `computeShouldNudge` / `HOW_TO_COMPRESS_RULES` against DCP repo all returned 0 hits, so MIT extraction is legally safe. AGENTS.md updated with new Git Safety Rule forbidding `version` field bumps on non-release branches to prevent future version-number drift.
+
+Files (compress notification): `lib/ui/notification.ts`, `lib/messages/utils.ts`, `lib/config.ts`, `tests/drop-empty-messages.test.ts`.
+Files (cc-alg extraction): `lib/compress/quality-gate/tokenizer.ts` (deleted), `lib/compress/quality-gate/algorithms/rouge-recall-v1.ts` (deleted), `lib/prompts/compression-rules.ts` (deleted), `lib/compress/quality-gate/{index,algorithms/index}.ts` (re-export from cc-alg for backward compat), `lib/messages/inject/{inject,utils}.ts`, `lib/messages/inject/policy/{types,registry,index}.ts` (new), `lib/prompts/{system,context-limit-nudge,turn-nudge,iteration-nudge}.ts`, `package.json`, `tsup.config.ts`, `NOTICE` (new), `AGENTS.md`. Tests: `tests/quality-gate-tokenizer.test.ts` (deleted, moved to cc-alg), `tests/quality-gate-rouge-recall-v1.test.ts` (deleted, moved to cc-alg — 55 tests migrated), `tests/quality-gate-pipeline-integration.test.ts` (uses inline stub gate), `tests/trigger-policy-integration.test.ts` (new). 794 tests pass (cc-alg has its own 95 tests in its own repo).
+
+### v1.13.0 — Pluggable Quality Gate (Issue #20)
+
+**Problem**: ACP had no mechanism to detect summaries that catastrophically lost content. The model could compress a 5K-token range into a 147-char summary missing every technical keyword, and the system would silently accept it. Issue #20 (calibrated against 6,913 real-world blocks from real sessions) identified two distinct failure modes: (1) length-floor failures — summaries <1% the size of the original (caught with 100% recall, 0% FPR via simple char count), and (2) content-coverage failures — summaries long enough to pass the length floor but capturing none of the original's keywords (e.g., a 996-char summary of a 5K-token original that recovers 0.6% of content words).
+
+**Fix**: Added a pluggable `qualityGate` subsystem under `lib/compress/quality-gate/` with a `QualityGate` interface (`name`, `version`, `description`, `evaluate(ctx, config)`). The pipeline calls `evaluateBatchQuality()` in `finalizeSession()` after state is saved — failures only emit `logger.warn` (non-blocking: the compression result is already committed). The default algorithm `rouge-recall-v1` is a two-layer gate: L1 is a length/retention floor (200 chars AND 1% retention), L2 is an AND-combine of ROUGE-1 F1 < 0.05 AND top-20 keyword recall < 0.20 (AND keeps FPR at ~6.6% while still catching the long-but-empty failure mode). Tokenizer is hand-rolled word-level (English keywords ≥4 chars + Chinese unigrams/bigrams) — separate from ACP's BPE tokenizer, which is too coarse for ROUGE matching. Config defaults `enabled: false` for one release of burn-in. Interface leaves room for future algorithms including external API judges (sync signature today; future async gates need either type widening or internal wait+timeout wrap, registry/config unchanged).
+
+Files: `lib/compress/quality-gate/{types,registry,tokenizer,evaluate,index}.ts`, `lib/compress/quality-gate/algorithms/{rouge-recall-v1,index}.ts`, `lib/compress/pipeline.ts`, `lib/config.ts`, `lib/config-validation.ts`, `dcp.schema.json`. Tests: `tests/quality-gate-{tokenizer,registry,rouge-recall-v1,pipeline-integration}.test.ts` (NEW, 74 tests). 842 tests pass.
+
+### v1.12.11 — README Refresh (PR #164)
+
+**Problem**: README documentation had drifted from code reality. The tagline under-emphasized ACP's core capability. The "Deletion strategy" section in the English README described a feature that no longer exists and contradicted the Chinese version. Cache hit rate and context usage statistics were stale (87%, ~30%). The `compress.protectedTools` default was documented as 5 tools (`task, skill, todowrite, todoread, decompress`) when the actual code default is only `skill`.
+
+**Fix**: (1) Added `<strong>200K tokens is enough.</strong>` tagline alongside the existing one-liner. (2) Refreshed "Proven at scale" table with real API-level data from 6 active sessions (Duration, Messages, API calls, Cumulative tokens, Cache hit %, P50/P90/P95 context), with outlier annotated. Aggregate cache hit ~91%. (3) Replaced "Deletion strategy" section (EN) with "GC safety net" matching the Chinese version. (4) Updated "How It Works" to list `acp_status` and `search_context` as supporting tools. (5) Updated cache stats: 87% → 91%, context ~30% → ~10–15% (p50 100K, p90 150K of 1M window). (6) Corrected `compress.protectedTools` default documentation to `skill` only (matches `COMPRESS_DEFAULT_PROTECTED_TOOLS` at `lib/config.ts:121`).
+
+Files: `README.md`, `README.zh-CN.md`. No code changes. Tests: 768 pass (unchanged).
+
 ### v1.12.10 — Batch Compress + Decompress Range Mode + GC Memory-Loss Fix + Token Classification + Nudge Quality (PRs #73, #155, #156, #157, #158, #159, #161)
 
 **Problem**: Seven issues across compression UX, token accounting, GC safety, and nudge quality. (1) `decompress` required a per-block `acp_status` → decompress-per-block loop to restore multiple compressed blocks. (2) Since v1.12.9 (compress-as-anchor), compress tool `summary` content was misclassified as `toolTokens` instead of `summaryTokens`, inflating tool% and deflating summary% in the context breakdown. (3) The `compress` tool only accepted a single range per call — the model had to issue multiple calls to compress unrelated ranges, wasting turns. (4) The `[PROTECTED: ...]` label listed every tool in a protected message instead of only the triggering tools. (5) When all visible content was protected, the nudge still fired with an empty recommendation list. (6) When a nudge was suppressed, the next-turn check re-evaluated every turn. (7) **The GC system was silently destroying model-written summaries**: any block with `summary.length > 6000` chars was force-truncated to 3000 regardless of context pressure (0% pressure triggered truncation), and blocks with high `survivedCount` were auto-deactivated — causing irrecoverable memory loss across hundreds of sessions.
@@ -440,7 +518,7 @@ Files: `lib/messages/prune.ts`, `lib/messages/utils.ts`, `lib/compress/recap.ts`
 
 ### v1.12.8 — Phantom Block Rejection (PR #148)
 
-**Problem**: When the model called `compress` on a range that was already covered by an active compression block, `applyCompressionState` still created a new block with `directMessageIds: []`, `compressedTokens: 0`, and `effectiveMessageIds` inherited from the consumed block. The model saw "0 tokens removed" in the notification, retried the same range, and entered a death loop: each phantom block added ~1K of summary overhead while compressing nothing, causing context to *grow* with every compression call (issues #93, #135). User sessions showed 9 consecutive phantom compressions (b12–b20) on the same range before the user manually intervened.
+**Problem**: When the model called `compress` on a range that was already covered by an active compression block, `applyCompressionState` still created a new block with `directMessageIds: []`, `compressedTokens: 0`, and `effectiveMessageIds` inherited from the consumed block. The model saw "0 tokens removed" in the notification, retried the same range, and entered a death loop: each phantom block added ~1K of summary overhead while compressing nothing, causing context to _grow_ with every compression call (issues #93, #135). User sessions showed 9 consecutive phantom compressions (b12–b20) on the same range before the user manually intervened.
 
 **Fix**: Added `checkPhantomBlock()` — a stateless pre-check in `lib/compress/pipeline.ts` that mirrors `applyCompressionState`'s `newlyCompressedMessageIds` computation. For each plan, it builds the effective message set (plan messages + consumed blocks' effective messages) and checks whether ANY message is "new" (i.e., has no active block covering it BEFORE mutation). If no message is new, the plan is a phantom and the entire compress call is rejected with a clear error before any state mutation occurs. Wired into both range-mode (`compress/range.ts`) and message-mode (`compress/message.ts`) after plan preparation, before snapshot. 12 tests cover: empty plans, all-new messages, consumed-block inheritance, GC'd messages (deactivated blocks count as new), and the exact `applyCompressionState` mirroring.
 
@@ -569,6 +647,7 @@ This release fixes two critical compression-injection bugs (#20 echo, #78 drift)
 #### Tool-Result Recap Injection — Fixes #20 & #78 (PR #95)
 
 **Problem**: Compression summaries were injected as text-based `role:assistant` or `role:user` messages. Both roles misled the model:
+
 - `role:assistant` (Bug 37 path) → model treated summaries as its own prior output and echoed them verbatim (#20, GLM-5.2).
 - `role:user` (Bug 36 merge path) → model treated summaries as user instructions and chased old topics (#78, gpt-5.5).
 
@@ -611,6 +690,7 @@ Fixes the over-compression bug reported in issue #18 and GitHub #85, where the `
 Additionally, the `compress.toolOutputNudgeThreshold` config key was **dead** — declared in the type but missing from the config merge, validation list, and JSON schema, so user overrides were silently dropped.
 
 **Fix** (4 coordinated changes):
+
 - `lib/messages/inject/inject.ts`: `toolOutputThreshold` now defaults to `nudgeGrowthTokens` (adaptive) instead of the hardcoded `5000`.
 - `lib/config.ts` `mergeCompress`: `toolOutputNudgeThreshold` override now flows through the config merge.
 - `lib/config-validation.ts`: `compress.toolOutputNudgeThreshold` registered as a valid config key.

package/README.zh-CN.md

@@ -4,6 +4,8 @@
 <strong>Active Context Pruning</strong> — <a href="https://opencode.ai">OpenCode</a> 的主动上下文剪枝插件
 <br />
 由模型决定<em>何时</em>压缩、压缩<em>什么</em> — 而非硬性截断。
+<br />
+<strong>20 万 token 足矣。</strong>
 </p>
 
 ---
@@ -26,8 +28,8 @@ ACP 将上下文管理的所有权限全部交给模型自己，而不依靠外
 
 这带来两个影响：
 
-- **省 token（约三分之二）。** 一个 100 万 token 上下文窗口的模型，实际只在 **20 万–30 万 token** 区间运行。
-- **超长上下文不丢关键内容** —— 支持 **5 亿级别上下文、单会话 10 万条消息**。
+- **20 万 token 足矣。** 在 50 个真实工程会话、3 万余次 API 调用中，**97% 的请求低于 20 万 token** —— p90 约 15 万，p95 约 18 万。每次 API 调用都会对完整上下文重新计费，因此上下文越低越省钱 —— 即使缓存命中率达 90%+，未缓存部分仍按全价计费。
+- **超长上下文不丢关键内容** —— 实测单会话 **3,300+ 条消息、3 亿+ 累计 token**；架构上支持单会话 **10 万条消息**（5 位消息 ID 空间）。
 
 ---
 
@@ -35,19 +37,18 @@ ACP 将上下文管理的所有权限全部交给模型自己，而不依靠外
 
 真实工程中的上下文情况。
 
-**支持 5 亿级别 token，p95 上下文比例在 30% 左右，平均缓存命中率 85% 以上。**（注意这是平均缓存命中率，不是单会话命中率——后面[对 Prompt 缓存的影响](#对-prompt-缓存的影响)会解释，这实际上比传统压缩算法大幅度节省了 token。）
+**在 6 个活跃工程会话（11,000+ 次 API 调用）中，上下文 p90 稳定在 15 万–19 万（15–19%），p95 在 16 万–21 万（16–21%）—— 聚合缓存命中率达 91%。**（注意这是平均缓存命中率，不是单会话命中率——后面[对 Prompt 缓存的影响](#对-prompt-缓存的影响)会解释，这实际上比传统压缩算法大幅度节省了 token。）
+
+| 会话      | 时长        | 消息数 | API 调用 | 累计 token | 缓存命中率 | 上下文 p50  | 上下文 p90  | 上下文 p95  |
+| --------- | ----------- | ------ | -------- | ---------- | ---------- | ----------- | ----------- | ----------- |
+| 0b89319b  | 230h (9.5d) | 3,344  | 2,796    | 3.39 亿    | 93%        | 10.8万(11%) | 16.7万(17%) | 21.0万(21%) |
+| 0a3be0cd  | 130h (5.4d) | 3,183  | 2,499    | 2.76 亿    | 91%        | 10.4万(10%) | 14.5万(15%) | 15.3万(15%) |
+| 0b2cd5a7  | 131h (5.4d) | 2,560  | 2,181    | 3.14 亿    | 91%        | 14.2万(14%) | 19.1万(19%) | 19.7万(20%) |
+| 08f2d501  | 37h (1.5d)  | 1,985  | 1,888    | 1.96 亿    | 95%        | 10.0万(10%) | 15.6万(16%) | 16.8万(17%) |
+| 1410c791† | 865h (36d)  | 1,279  | 1,100    | 2.18 亿    | 87%        | 13.2万(13%) | 40.7万(41%) | 42.7万(43%) |
+| 096cf8c4  | 72h (3d)    | 1,041  | 918      | 0.91 亿    | 89%        | 9.2万(9%)   | 14.8万(15%) | 16.1万(16%) |
 
-|                         | 会话一         | 会话二         |
-| ----------------------- | -------------- | -------------- |
-| **消息总条数**          | 3,024          | 2,028          |
-| **累计处理 token**      | 5.82 亿        | 4.63 亿        |
-| **prompt-cache 命中率** | 86.2%          | 89.0%          |
-| **上下文 p50（中位）**  | 1.2 K（<1%）   | 1.8 K（<1%）   |
-| **上下文 p75**          | 2.8 K          | 3.5 K          |
-| **上下文 p90**          | 10.8 万（11%） | 5.8 万（6%）   |
-| **上下文 p95**          | 25.1 万（25%） | 33.5 万（34%） |
-| **上下文 p99**          | 42.5 万（43%） | 44.2 万（44%） |
-| **峰值**                | 48.8 万（49%） | 76.9 万（77%） |
+† Bug 测试会话，p95 异常偏高。排除该会话后，其余会话 p95 均 ≤ 21 万。
 
 （上下文百分比均以 1M 窗口计。）
 
@@ -73,7 +74,7 @@ opencode plugin opencode-acp@latest --global
 
 ## 工作原理
 
-ACP 把上下文压缩工具直接交给模型。模型对上下文压缩**负全责**。模型可用的工具主要是：**compress** 和 **decompress**。当上下文达到 100% 时，系统自动触发 GC 截断作为兜底。
+ACP 把上下文压缩工具直接交给模型。模型对上下文压缩**负全责**。模型的主要工具是 **compress** 和 **decompress**，辅以 **acp_status**（上下文监控）和 **search_context**（搜索已压缩内容）。当上下文达到 100% 时，系统自动触发 GC 截断作为兜底。
 
 ### 生命周期
 
@@ -108,15 +109,37 @@ stateDiagram-v2
 
 当上下文达到 100% 时，系统自动截断老年代 block 摘要，防止上下文溢出。这是最后的兜底机制，不影响模型的正常压缩/解压操作。
 
+### 质量门控（非阻塞，默认关闭）
+
+每次 `compress` 调用之后，ACP 可以运行一个可拔插的质量门控，检测摘要是否灾难性丢失了内容（例如：5K token 的范围被压缩成 147 字符、且不含任何技术关键词的摘要）。失败只发出 `logger.warn`——绝不拒绝压缩（结果已经提交到状态、对模型可见）。
+
+默认算法 `rouge-recall-v1` 是基于 6,913 个真实块校准的两层门控：
+
+- **L1（长度下限）**：捕获灾难性留存失败——摘要短于 200 字符 OR 留存率低于原始的 1%。100% 召回，0% 误报。
+- **L2（内容覆盖）**：只在通过 L1 的块上运行。当 **同时** ROUGE-1 F1 < 0.05 **且** top-20 关键词召回 < 0.20 时触发（AND 合并使误报率维持在 ~6.6%）。
+
+接口可拔插：未来算法（例如通过外部 API 的 LLM-as-judge）可通过 `registerQualityGate()` 注册，无需改动 pipeline 接线。分词器使用手写的词级分词（英文关键词 + 中文 unigram/bigram），不使用 ACP 的 BPE 分词器——后者对 ROUGE 风格的匹配粒度过粗。
+
+默认关闭，发布一个版本的烧入期后再开启。启用方式：
+
+```jsonc
+{
+    "qualityGate": {
+        "enabled": true,
+        "algorithm": "rouge-recall-v1",
+    },
+}
+```
+
 ---
 
 ## 对 Prompt 缓存的影响
 
-历史上 ACP 修复了大量由 DCP 导致的低缓存命中率问题。目前整体缓存命中率约为 **87%**。
+历史上 ACP 修复了大量由 DCP 导致的低缓存命中率问题。目前整体缓存命中率约为 **91%**。
 
 相比传统压缩——只在 80–90% 时才压缩，一旦压缩就强制 100% 的上下文重新命中——ACP 的命中率实际上更高。
 
-此外：ACP 大部分时间将总上下文维持在 **~30%** 左右，而传统方案是 50–80%。因此总 token 节省远高于传统压缩。
+此外：ACP 大部分时间将总上下文维持在 **~10–15%**（p50 10 万、p90 15 万，以 1M 窗口计），而传统方案是 50–80%。因此总 token 节省远高于传统压缩。
 
 **结论：** ACP 在提高整体缓存命中率的同时，确保关键上下文信息不丢失。
 
@@ -182,8 +205,8 @@ ACP 使用自己的配置文件，按以下顺序搜索：
     "debug": false,
     // Notification display: "off", "minimal", or "detailed"
     "pruneNotification": "detailed",
-    // Notification type: "chat" (in-conversation) or "toast" (system toast)
-    "pruneNotificationType": "chat",
+    // Notification type: "chat" (deprecated, falls back to toast) or "toast" (system toast)
+    "pruneNotificationType": "toast",
     // Slash commands configuration
     "commands": {
         "enabled": true,
@@ -292,6 +315,27 @@ ACP 使用自己的配置文件，按以下顺序搜索：
         // 上下文使用率超过此值时执行主 GC（兜底，硬编码为 100%）
         "majorGcThresholdPercent": "100%",
     },
+    // 压缩后质量门控（非阻塞；默认关闭）
+    "qualityGate": {
+        // 主开关。false 时不执行任何评估
+        "enabled": false,
+        // 算法名。可拔插——未来算法（包括外部 API 评审）可以注册而无需改 pipeline
+        "algorithm": "rouge-recall-v1",
+        // 各算法的独立配置
+        "algorithms": {
+            "rouge-recall-v1": {
+                // 摘要长度硬下限（字符）。低于此值 → L1 失败
+                "layer1MinChars": 200,
+                // 最小留存率 = summaryLen / (compressedTokens*4) * 100
+                // 捕获灾难性留存失败（<1%），0% 误报
+                "layer1MinRetentionPct": 1.0,
+                // 当 ROUGE-1 F1 低于此值时（与 top20Recall 经 AND 合并）L2 失败
+                "layer2MaxRougeF1": 0.05,
+                // 当 top-20 关键词召回低于此值时（与 rougeF1 经 AND 合并）L2 失败
+                "layer2MaxTop20Recall": 0.20,
+            },
+        },
+    },
 }
 ```
 
@@ -323,7 +367,7 @@ ACP 暴露六个可编辑的 prompt：
 
 `commands` 和 `strategies` 中的 `protectedTools` 数组会添加到此默认列表。
 
-对于 `compress` 工具，`compress.protectedTools` 确保特定工具的输出被**硬排除**在压缩范围之外（v1.10.0+）。当模型压缩包含受保护工具消息的范围时，该消息完整保留在可见上下文中 — 只有周围的非受保护消息被压缩。默认包含 `task`、`skill`、`todowrite`、`todoread` 和 `decompress`。
+对于 `compress` 工具，`compress.protectedTools` 确保特定工具的输出被**硬排除**在压缩范围之外（v1.10.0+）。当模型压缩包含受保护工具消息的范围时，该消息完整保留在可见上下文中 — 只有周围的非受保护消息被压缩。默认仅包含 `skill` —— 实践中这一个就够了，因为 skill 输出是唯一绝不能被压缩丢失的工具类型。
 
 ---
 
@@ -395,6 +439,35 @@ ACP 在首次启动时自动将配置从 `dcp.jsonc` 迁移到 `acp.jsonc`，将
 
 ## 更新日志
 
+### v1.13.1 — cc-alg 抽取 + 压缩通知冻结修复（PR #167, #168）
+
+**问题（压缩通知冻结，#167）**：每次 `compress` 工具调用成功后，ACP 会注入一条 user 角色通知消息，其中只包含一个带 `ignored: true` 标记的 text part。opencode 在发送给 LLM 前会剥离 ignored parts，于是这条消息变成空 user 消息。Provider（zhipuai-lb / glm-5.2）会以 HTTP 400 code 1214（`"messages 参数非法"`）拒绝，且 `isRetryable: false`——opencode 不会重试，会话冻结，直到外部恢复。所有活跃会话累计发生 113 次（单个 3,156 条消息的会话出现 8 次）。
+
+**修复（压缩通知冻结，#167）**：（1）`lib/ui/notification.ts:280-298`——`sendCompressNotification` 改为始终调用 `client.tui.showToast`；移除了原本调用 `sendIgnoredMessage` 的 `chat` 分支。当用户显式配置 `pruneNotificationType: "chat"` 时，输出一次 warn 日志以便发现行为变化。（2）`lib/messages/utils.ts:232-269`——`dropEmptyMessages` 现在将带 `ignored: true` 的 text part 也视为"可丢弃"，任何未来出现的 ignored-only user 消息会在到达 provider 之前被丢弃（纵深防御）。（3）`lib/config.ts:175`——默认 `pruneNotificationType` 从 `"chat"` 改为 `"toast"`，使用默认配置的用户不会看到弃用警告。
+
+**问题（cc-alg 抽取，#168）**：可复用的压缩算法（ROUGE-1 质量门控、手写 tokenizer、trigger policy、compression-rules prompt）锁在 ACP 的 AGPL 代码库里，其他项目无法以 MIT 协议复用。算法模块与 ACP 管道的内部耦合也使独立测试和复用困难。
+
+**修复（cc-alg 抽取，#168）**：4 个模块抽取到独立 MIT 包 `context-compress-algorithms@1.0.0`（npm：https://www.npmjs.com/package/context-compress-algorithms，GitHub：https://github.com/ranxianglei/context-compress-algorithms）。ACP 通过 `^1.0.0` 引用，并用 tsup `noExternal` 把 cc-alg inline-bundle 进 `dist/index.js`，host 不需要安装额外依赖。新增 `NOTICE` 文件按开源合规要求随包发布 MIT 归属。新增 `lib/messages/inject/policy/` 注册表支持 host 端自定义 nudge trigger 行为（默认 policy 来自 cc-alg 的 `defaultTriggerPolicy`）。Provenance 审计确认对 DCP 上游（AGPL-3.0）零 derivation——在 DCP 仓库搜索 `rouge` / `qualityGate` / `computeShouldNudge` / `HOW_TO_COMPRESS_RULES` 均为 0 hit，MIT 抽取法律安全。AGENTS.md 新增 Git 安全规则：非 release 分支禁止修改 `version` 字段，避免今后版本号再次被改乱。
+
+文件（压缩通知）：`lib/ui/notification.ts`、`lib/messages/utils.ts`、`lib/config.ts`、`tests/drop-empty-messages.test.ts`。
+文件（cc-alg 抽取）：`lib/compress/quality-gate/tokenizer.ts`（删除）、`lib/compress/quality-gate/algorithms/rouge-recall-v1.ts`（删除）、`lib/prompts/compression-rules.ts`（删除）、`lib/compress/quality-gate/{index,algorithms/index}.ts`（从 cc-alg re-export，向后兼容）、`lib/messages/inject/{inject,utils}.ts`、`lib/messages/inject/policy/{types,registry,index}.ts`（新增）、`lib/prompts/{system,context-limit-nudge,turn-nudge,iteration-nudge}.ts`、`package.json`、`tsup.config.ts`、`NOTICE`（新增）、`AGENTS.md`。测试：`tests/quality-gate-tokenizer.test.ts`（删除，迁到 cc-alg）、`tests/quality-gate-rouge-recall-v1.test.ts`（删除，迁到 cc-alg——55 个测试迁移）、`tests/quality-gate-pipeline-integration.test.ts`（改用 inline stub gate）、`tests/trigger-policy-integration.test.ts`（新增）。794 个测试通过（cc-alg 自身在独立仓库有 95 个测试）。
+
+### v1.13.0 — 可拔插质量门控（Issue #20）
+
+**问题**：ACP 没有机制检测摘要是否灾难性丢失了内容。模型可能把 5K token 的范围压缩成 147 字符、且不含任何技术关键词的摘要，系统也会默默接受。Issue #20（基于真实会话的 6,913 个块校准）识别出两种不同的失败模式：(1) 长度下限失败——摘要 < 原始的 1%（通过简单的字符计数即可 100% 召回，0% 误报）；(2) 内容覆盖失败——摘要长度足够通过长度门，但没有捕获原始内容中的任何关键词（例如：5K token 原始内容的 996 字符摘要只恢复了 0.6% 的内容词）。
+
+**修复**：在 `lib/compress/quality-gate/` 下添加可拔插的 `qualityGate` 子系统，定义 `QualityGate` 接口（`name`、`version`、`description`、`evaluate(ctx, config)`）。pipeline 在 `finalizeSession()` 中状态保存之后调用 `evaluateBatchQuality()`——失败仅发出 `logger.warn`（非阻塞：压缩结果已经提交）。默认算法 `rouge-recall-v1` 是两层门控：L1 是长度/留存下限（200 字符 AND 1% 留存），L2 是 ROUGE-1 F1 < 0.05 与 top-20 关键词召回 < 0.20 的 AND 合并（AND 把误报率维持在 ~6.6%，同时仍能捕获"长但空"的失败模式）。分词器为手写的词级分词（英文关键词 ≥4 字符 + 中文 unigram/bigram），与 ACP 的 BPE 分词器分离——后者对 ROUGE 匹配粒度过粗。配置默认 `enabled: false`，发布一个版本的烧入期。接口为未来算法留出空间，包括外部 API 评审（当前为同步签名；未来异步门控需要扩展类型或在内部 wait+timeout 包装，registry/config 不变）。
+
+文件：`lib/compress/quality-gate/{types,registry,tokenizer,evaluate,index}.ts`、`lib/compress/quality-gate/algorithms/{rouge-recall-v1,index}.ts`、`lib/compress/pipeline.ts`、`lib/config.ts`、`lib/config-validation.ts`、`dcp.schema.json`。测试：`tests/quality-gate-{tokenizer,registry,rouge-recall-v1,pipeline-integration}.test.ts`（新增，74 个测试）。842 个测试通过。
+
+### v1.12.11 — README 文档刷新（PR #164）
+
+**问题**：README 文档与代码实际脱节。tagline 没有突出 ACP 的核心能力。英文版的 "Deletion strategy" 章节描述了一个已不存在的功能，且与中文版不一致。缓存命中率和上下文使用率数据过期（87%、~30%）。`compress.protectedTools` 默认值文档列出了 5 个工具（`task, skill, todowrite, todoread, decompress`），但代码实际默认值只有 `skill`。
+
+**修复**：（1）新增 `<strong>20 万 token 足矣。</strong>` tagline。（2）"Proven at scale" 表格更新为 6 个活跃会话的真实 API 级数据（运行时长、消息数、API 调用数、累计 token、缓存命中率、P50/P90/P95），离群值标注。（3）英文版 "Deletion strategy" 替换为 "GC safety net"，与中文版 "GC 兜底" 一致。（4）"工作原理" 列出 `acp_status` 和 `search_context` 为辅助工具。（5）缓存统计更新：87% → 91%，上下文 ~30% → ~10–15%（1M 窗口的 p50 10 万、p90 15 万）。（6）`compress.protectedTools` 默认值文档更正为仅 `skill`（匹配 `lib/config.ts:121` 的 `COMPRESS_DEFAULT_PROTECTED_TOOLS`）。
+
+文件：`README.md`、`README.zh-CN.md`。无代码改动。测试：768 通过（不变）。
+
 ### v1.12.10 — 批量压缩 + Decompress 范围模式 + GC 记忆丢失修复 + Token 分类 + Nudge 质量（PR #73, #155, #156, #157, #158, #159, #161）
 
 **问题**：七个问题，涉及压缩 UX、token 统计、GC 安全和 nudge 质量。（1）`decompress` 需要先 `acp_status` 再逐块 decompress 的循环才能恢复多个压缩块。（2）自 v1.12.9 起，compress 工具的 `summary` 内容被错误分类为 `toolTokens` 而非 `summaryTokens`，导致上下文分布中 tool% 虚高、summary% 虚低。（3）`compress` 工具每次调用只能压缩一个范围 —— 模型需要多次调用才能压缩不相关的范围，浪费轮次。（4）`[PROTECTED: ...]` 标签列出受保护消息中的所有工具而非仅触发保护的工具。（5）当所有可见内容都是受保护内容时，nudge 仍然以空推荐列表注入。（6）当 nudge 被抑制时，下一轮检查每轮都重新评估。（7）**GC 系统在静默销毁模型编写的 summary**：任何 `summary.length > 6000` 字符的块在零上下文压力下被强制截断到 3000，且 `survivedCount` 过高的块被自动 deactivate —— 导致数百个会话的不可恢复记忆丢失。
@@ -542,6 +615,7 @@ Issue #23（上下文内存泄露）的综合修复。7 个 commit，22 个文
 #### 工具结果注入 — 修复 #20 & #78（PR #95）
 
 **问题**：压缩摘要以文本形式的 `role:assistant` 或 `role:user` 消息注入。两种角色都会误导模型：
+
 - `role:assistant`（Bug 37 路径）→ 模型将摘要当作自己的前文，逐字复读（#20，GLM-5.2）。
 - `role:user`（Bug 36 合并路径）→ 模型将摘要当作用户指令，去执行旧话题（#78，gpt-5.5）。