ranxianglei
diff --git a/‎README.md‎
Lines changed: 64 additions & 11 deletions b/‎README.md‎
Lines changed: 64 additions & 11 deletions
diff --git a/‎README.zh-CN.md‎
Lines changed: 47 additions & 8 deletions b/‎README.zh-CN.md‎
Lines changed: 47 additions & 8 deletions
diff --git a/‎devlog/2026-07-25_tier-compression/REQ.md‎
Lines changed: 36 additions & 0 deletions b/‎devlog/2026-07-25_tier-compression/REQ.md‎
Lines changed: 36 additions & 0 deletions
@@ -90,23 +90,76 @@ Or add to your opencode config:
 ACP hands the context-compression tool directly to the model. The model is
 **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.
+and **search_context** (search compressed content). Compression uses a
+**three-tier LSM-tree architecture** (T1 capture → T2 distill → T3 condense)
+that keeps context bounded for years. A hardcoded 100% GC fallback acts as a
+safety net when the context window is completely full.
 
-### Lifecycle
+### Lifecycle — Three-Tier Compression
 
-Two operations: **compress** and **decompress**. Content loops between raw and
-compressed. When context hits 100%, old-gen block summaries are truncated as
-a last resort:
+ACP uses a **three-tier LSM-tree compression architecture**, inspired by
+database storage engines. Each tier compresses the previous tier's output,
+creating progressively denser summaries with natural frequency decrease:
 
 ```mermaid
 stateDiagram-v2
-    Raw --> Compressed : compress
-    Compressed --> Raw : decompress
-    Compressed --> Truncated : GC at 100%
+    Raw --> Tier1 : compress (every ~7 turns)
+    Tier1 --> Tier2 : distill (every ~250 turns)
+    Tier2 --> Tier3 : condense (every ~2500 turns)
+    Tier1 --> Raw : decompress
+    Tier2 --> Raw : decompress (recursive)
+    Tier3 --> Raw : decompress (recursive)
+    Tier1 --> GC_Truncated : GC at 100% context
 ```
 
-### Compression strategy
+| Tier | Name | Input | Output | Compression ratio | When it fires |
+|------|------|-------|--------|-------------------|---------------|
+| **T1** | Capture | Raw conversation | Detailed summary | ~45× | Context exceeds `maxContextLimit` |
+| **T2** | Distill | T1 summaries (≥ `nudgeGrowthTokens`) | Condensed decisions/outcomes | ~10× | T1 summaries accumulate past threshold |
+| **T3** | Condense | T2 summaries (≥ `nudgeGrowthTokens`) | Bare facts (1-3 per block) | ~5× | T2 summaries accumulate past threshold |
+
+**How triggers work:**
+
+- **T1** fires when raw context exceeds the configured limit. The model sees
+  compressible ranges and writes a detailed summary preserving file paths,
+  signatures, decisions, and rationale.
+- **T2** fires when T1 summary tokens reach `nudgeGrowthTokens` (default 5% of
+  context window). The model distills old T1 blocks — keeping decisions and
+  outcomes, dropping verbose process details.
+- **T3** fires when T2 summary tokens reach the same threshold. The model
+  condenses to bare facts (shipped releases, key bugs, architecture decisions).
+
+Each tier has an **independent cadence counter** — T2 firing doesn't block T3.
+T1 has priority via a `!shouldInject` guard: if T1 fires, T2/T3 wait until next
+turn. This ensures raw context compression happens first (it has the biggest
+impact).
+
+**Session capacity** — total tokens a single session can process from empty → T1 →
+T2 → T3 → context limit (real-calibrated: 500 API calls/day, ~9.6K new tokens/call,
+T1=45x/T2=10x/T3=3x):
+
+| Context limit | 1 month | 3 months | At limit | Limit reached |
+|---------------|---------|----------|----------|---------------|
+| 1M | 1.9B tok | 10.5B tok | **68.9B tok** | day 259 (~8.6 mo) |
+| 400K | 1.9B tok | 10.3B tok | **10.3B tok** | day 89 (~3 mo) |
+| 400K (200 calls/day) | 559M tok | 2.5B tok | **9.5B tok** | day 212 (~7 mo) |
+
+**Token savings** — without ACP, context grows unbounded and the session crashes
+after ~100 API calls (~0.2 days). With ACP, context is bounded by compression:
+
+| Metric | Without ACP | With ACP (1M model) |
+|--------|-------------|---------------------|
+| Session lifetime | ~0.2 days | 259 days (**1295x** longer) |
+| Total tokens processed | ~52M | 68.9B (**1325x** more work) |
+
+The core value: ACP doesn't just reduce per-call token cost — it enables a single
+session to process **1000x more total work** by keeping context bounded across
+the full session lifetime.
+
+The model uses the **same `compress` tool** for all tiers. T2/T3 compressions
+use block IDs as boundaries (`compress({ content: [{ startId: "b5", endId: "b20", summary: "..." }] })`). Tier is auto-detected from consumed blocks.
+
+### Compression strategy (Tier 1)
 
 The system injects a prompt telling the model the current context ratio, the
 compression ratio, whether context is idle, and compression suggestions. When the
@@ -132,7 +185,7 @@ later work.
 
 ### 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.
+When context reaches 100%, the system automatically truncates old-gen block summaries to prevent overflow. This is a last-resort safety net — with three-tier compression, the GC rarely activates because T2/T3 distillation keeps summary overhead bounded.
 
 ### Quality gate (non-blocking, off by default)
 
 
@@ -74,20 +74,59 @@ opencode plugin opencode-acp@latest --global
 
 ## 工作原理
 
-ACP 把上下文压缩工具直接交给模型。模型对上下文压缩**负全责**。模型的主要工具是 **compress** 和 **decompress**，辅以 **acp_status**（上下文监控）和 **search_context**（搜索已压缩内容）。当上下文达到 100% 时，系统自动触发 GC 截断作为兜底。
+ACP 把上下文压缩工具直接交给模型。模型对上下文压缩**负全责**。模型的主要工具是 **compress** 和 **decompress**，辅以 **acp_status**（上下文监控）和 **search_context**（搜索已压缩内容）。压缩采用**三级 LSM-tree 架构**（T1 捕获 → T2 蒸馏 → T3 浓缩），使上下文在数年内保持有界。当上下文达到 100% 时，系统自动触发 GC 截断作为兜底。
 
-### 生命周期
+### 生命周期 — 三级压缩
 
-两个操作：**压缩**、**解压缩**。内容在原始与压缩之间循环。当上下文达到 100% 时，GC 自动截断老年代 block 作为兜底：
+ACP 采用**三级 LSM-tree 压缩架构**，灵感来自数据库存储引擎。每一级压缩上一级的输出，产生逐渐精炼的摘要，频率自然递减：
 
 ```mermaid
 stateDiagram-v2
-    Raw --> Compressed : compress
-    Compressed --> Raw : decompress
-    Compressed --> GC_Truncated : GC (100%)
+    Raw --> Tier1 : compress（约每 7 轮）
+    Tier1 --> Tier2 : distill（约每 250 轮）
+    Tier2 --> Tier3 : condense（约每 2500 轮）
+    Tier1 --> Raw : decompress
+    Tier2 --> Raw : decompress（递归）
+    Tier3 --> Raw : decompress（递归）
+    Tier1 --> GC_Truncated : GC（100% 上下文）
 ```
 
-### 压缩策略
+| 层级 | 名称 | 输入 | 输出 | 压缩比 | 触发时机 |
+|------|------|------|------|--------|----------|
+| **T1** | 捕获 | 原始对话 | 详细摘要 | ~45× | 上下文超过 `maxContextLimit` |
+| **T2** | 蒸馏 | T1 摘要（≥ `nudgeGrowthTokens`） | 精炼的决策/结果 | ~10× | T1 摘要累积超过阈值 |
+| **T3** | 浓缩 | T2 摘要（≥ `nudgeGrowthTokens`） | 纯事实（每块 1-3 条） | ~5× | T2 摘要累积超过阈值 |
+
+**触发机制：**
+
+- **T1** 在原始上下文超过配置限制时触发。模型看到可压缩范围，编写详细摘要，保留文件路径、函数签名、决策和理由。
+- **T2** 在 T1 摘要 token 达到 `nudgeGrowthTokens`（默认上下文窗口的 5%）时触发。模型蒸馏旧的 T1 块 — 保留决策和结果，丢弃冗长的过程细节。
+- **T3** 在 T2 摘要 token 达到同样阈值时触发。模型浓缩为纯事实（已发布的版本、关键 bug、架构决策）。
+
+每层有**独立的节奏计数器** — T2 触发不阻塞 T3。T1 通过 `!shouldInject` 守卫获得优先级：如果 T1 触发了，T2/T3 等到下一轮。这确保原始上下文压缩优先发生（影响最大）。
+
+模型对所有层级使用**同一个 `compress` 工具**。T2/T3 压缩使用块 ID 作为边界（`compress({ content: [{ startId: "b5", endId: "b20", summary: "..." }] })`）。层级根据被消费的块自动检测。
+
+**会话容量** — 一个会话从空 → T1 → T2 → T3 → 上下文极限，总共可以处理多少 token（真实校准：500 次 API 调用/天，~9.6K 新 token/调用，T1=45x/T2=10x/T3=3x）：
+
+| 上下文上限 | 1 个月 | 3 个月 | 到极限 | 极限时间 |
+|-----------|--------|--------|--------|---------|
+| 1M | 19 亿 tok | 105 亿 tok | **689 亿 tok** | 第 259 天（~8.6 月） |
+| 400K | 19 亿 tok | 103 亿 tok | **103 亿 tok** | 第 89 天（~3 月） |
+| 400K（200 调用/天） | 5.6 亿 tok | 25 亿 tok | **95 亿 tok** | 第 212 天（~7 月） |
+
+**Token 节省** — 无 ACP 时上下文无限增长，约 100 次 API 调用后崩溃（~0.2 天）。有 ACP 时上下文被压缩在有界范围：
+
+| 指标 | 无 ACP | 有 ACP（1M 模型） |
+|------|--------|-----------------|
+| 会话寿命 | ~0.2 天 | 259 天（**长 1295 倍**） |
+| 总 token 产出 | ~5200 万 | 689 亿（**多 1325 倍**） |
+
+核心价值：ACP 不是减少每次调用的 token 成本，而是**让一个会话能处理 1000 倍以上的工作量**。
+
+模型对所有层级使用**同一个 `compress` 工具**。T2/T3 压缩使用块 ID 作为边界（`compress({ content: [{ startId: "b5", endId: "b20", summary: "..." }] })`）。层级根据被消费的块自动检测。
+
+### 压缩策略（一级压缩 / Tier 1）
 
 系统会注入一段 prompt，告诉模型当前的上下文比例、压缩比例、上下文是否空闲，以及压缩建议。当触发比例被命中时，内容按**优先级顺序**被压缩：
 
@@ -107,7 +146,7 @@ stateDiagram-v2
 
 ### GC 兜底
 
-当上下文达到 100% 时，系统自动截断老年代 block 摘要，防止上下文溢出。这是最后的兜底机制，不影响模型的正常压缩/解压操作。
+当上下文达到 100% 时，系统自动截断老年代 block 摘要，防止上下文溢出。这是最后的兜底机制 — 有了三级压缩，GC 极少激活，因为 T2/T3 蒸馏将摘要开销控制在有界范围内。
 
 ### 质量门控（非阻塞，默认关闭）
 
 
@@ -0,0 +1,36 @@
+# 3-Tier Compression (LSM Tree Architecture)
+
+## Problem
+Summary blocks accumulate indefinitely (v1.13.5+ force-protection). At ~7.3K tokens/day growth rate, sessions hit the 100K summary ceiling in ~3 days. 92.5% of ancient blocks are shipped/historical work with zero actionable value.
+
+## Solution
+Implement a 3-tier LSM Tree compression architecture:
+- **Tier 1** (default): Full-detail compression of conversation ranges (existing behavior)
+- **Tier 2**: Distillation of old tier-1 summaries → decisions/outcomes only (~1/12 ratio)
+- **Tier 3**: Ultra-condensation of tier-2 summaries → bare facts (~1/3 ratio)
+
+End-to-end: 1/60 × 1/12 × 1/3 = 1/2160. Session longevity: 3 days → 271 days (9 months).
+
+## Design
+- Reuse existing `compress` tool for all tiers — `b` prefix (block ID) auto-detects tier
+- Each tier uses different prompt rules (from cc-alg v1.2.1)
+- `block.tier` field on CompressionBlock tracks tier (1/2/3, undefined=1)
+- `applyCompressionState` auto-detects output tier from consumed blocks (min consumed tier + 1)
+- Per-tier token counting via `getTierTokenUsage()`
+- Independent tier triggers with T1 priority: each tier checks its input summaries against `nudgeGrowthTokens`
+- Tier-aware decompress: default = one level up (T2→T1), `full:true` = recursive to raw
+- Cross-tier contamination prevention: candidates sorted by blockId, range narrowed when non-target blocks exist
+
+## Scope
+- **cc-alg v1.2.1**: TIER2_DISTILL_RULES, TIER3_CONDENSE_RULES prompts (keep function/module refs, source headers)
+- **opencode-acp**: block.tier field, tier auto-detection, per-tier counting, independent triggers, tier-aware decompress, hide-consumed, sync.ts anchor-survival fix
+
+## Session Capacity (real-calibrated)
+| Context limit | Total tokens | Duration |
+|---------------|-------------|----------|
+| 1M | 68.9B | 259 days |
+| 400K (500 calls/day) | 10.3B | 89 days |
+| 400K (200 calls/day) | 9.5B | 212 days |
+
+## Status
+33 commits, 919 tests pass, dual-agent reviewed (all findings fixed).