docs(solutions): CJK token estimation undercount fix

Document the ContextCompressor CJK 4x underestimation bug and fix:
- estimate_text_tokens() CJK 1:1 / ASCII 4:1 heuristic
- _summarize() max_chars budget fix (P1: was * 4, allowed 4x CJK budget)
- Linear compress flow + structured logging
- Prevention: charset-aware heuristics, audit dependent truncation points

docs/solutions/logic-errors/context-compressor-cjk-token-estimation.md

@@ -0,0 +1,152 @@
+---
+title: "ContextCompressor CJK token estimation undercounted by 4x"
+date: 2026-07-03
+module: core/compressor
+component: assistant
+tags:
+  - cjk
+  - token-estimation
+  - context-compression
+  - react-engine
+  - heuristic
+problem_type: logic_error
+severity: high
+symptoms:
+  - "estimate_tokens() uses len(content) // 4 (ASCII heuristic), undercounting CJK tokens by ~4x since CJK chars are ~1 char per token"
+  - "Context compression triggers too late for CJK-heavy conversations, risking context window overflow"
+  - "_summarize() pre-truncation uses max_chars = max_input_tokens * 4, allowing CJK text to send 4x the token budget to the LLM"
+  - "ReActEngine._should_compress() fallback inherits the same flawed len // 4 estimation for compressors without should_compress()"
+root_cause: logic_error
+resolution_type: code_fix
+---
+
+## Problem
+
+`ContextCompressor.estimate_tokens()` 使用 `len(content) // 4`（ASCII 启发式，4 字符 ≈ 1 token）估算 token 数。对 CJK（中文/日文/韩文）文本而言，1 个字符 ≈ 1 token，因此该估算器将 CJK token 数低估约 4 倍。这导致 CJK 为主的会话压缩触发过晚，存在上下文窗口溢出风险。`_summarize()` 的预截断 `max_chars = max_input_tokens * 4` 进一步放大了问题——允许 CJK 文本向 LLM 发送 4 倍 token 预算的输入。
+
+## Symptoms
+
+- CJK 为主的会话在远超预期阈值（约 4 倍）后才触发压缩，`should_compress()` 返回 `False` 而实际 token 已超出 `model_context_limit`
+- `_summarize()` 可能向 LLM 发送 4 倍 token 预算的 CJK 文本（P1 缺陷——可能触发上下文上限 / 400 错误）
+- 中文长会话面临上下文窗口溢出 / 请求失败的高风险
+- 压缩流程依赖递归深度 `_compression_depth`，难以观测与调试，缺乏结构化日志
+
+## What Didn't Work
+
+旧的 `len(content) // 4` 估算器基于 ASCII/拉丁语平均比例（约 4 字符/token）。对纯 CJK 文本（1 字符 ≈ 1 token），该估算产生约 4 倍偏低的估计。例如：4000 个中文字符会被估算为 1000 token，但实际约 4000 token。这导致：
+
+- `should_compress()` 的 headroom 阈值（`model_context_limit * 0.8`）直到实际 token 已 4 倍超出预期阈值才触发
+- `_summarize()` 中 `max_chars = max_input_tokens * 4` 在预算为 3200 token 时放行 12800 字符（≈12800 CJK token）— 此 P1 缺陷由 ce-code-review 捕获 (session history)
+- 旧的递归式 `compress()` 依赖 `_compression_depth` 计数器，流程难以阅读，且 `_compress_aggressive()` 接收已压缩的 `compressed` 列表，存在 summary-of-summary（F-010）风险
+
+## Solution
+
+**1. 新增 CJK 感知的 token 估算器**（`src/agentkit/core/compressor.py`）：
+
+```python
+def _is_cjk(char: str) -> bool:
+    """Check if a character is CJK (1 token ≈ 1 char)."""
+    cp = ord(char)
+    return (
+        0x4E00 <= cp <= 0x9FFF  # CJK Unified Ideographs
+        or 0x3040 <= cp <= 0x30FF  # Hiragana + Katakana
+        or 0xAC00 <= cp <= 0xD7AF  # Hangul Syllables
+    )
+
+
+def estimate_text_tokens(text: str) -> int:
+    """Estimate token count: CJK 1:1, other characters 4:1."""
+    cjk_count = 0
+    non_cjk_count = 0
+    for char in text:
+        if _is_cjk(char):
+            cjk_count += 1
+        else:
+            non_cjk_count += 1
+    return cjk_count + non_cjk_count // 4
+```
+
+`estimate_tokens()` 改用 `estimate_text_tokens()`：
+
+```python
+def estimate_tokens(self, messages: list[dict]) -> int:
+    """Estimate total tokens in message list (CJK 1:1, ASCII 4:1)"""
+    return sum(estimate_text_tokens(str(m.get("content", ""))) for m in messages)
+```
+
+**2. 修复 `_summarize()` 预截断**（P1 缺陷，由 ce-code-review 捕获）：
+
+```python
+# 修改前（CJK 可 4 倍超预算）:
+max_chars = max_input_tokens * 4
+
+# 修改后（CJK 1:1 精确，ASCII 4:1 保守）:
+max_chars = max_input_tokens
+conversation_text = conversation_text[:max_chars] + "\n...[truncated]"
+```
+
+**3. `ReActEngine._should_compress()` 回退路径同步使用 `estimate_text_tokens`**（`src/agentkit/core/react.py` 约 1750 行）：
+
+```python
+# Fallback: fixed threshold for compressors without headroom support
+estimated_tokens = sum(
+    estimate_text_tokens(str(m.get("content", ""))) for m in conversation
+)
+return estimated_tokens > self._DEFAULT_COMPRESS_THRESHOLD
+```
+
+**4. 重写 `compress()` 为线性流程**，移除递归式 `_compression_depth`：
+
+```python
+async def compress(self, messages: list[dict]) -> list[dict]:
+    """Linear flow: summarize -> aggressive -> truncate."""
+    tokens_before = self.estimate_tokens(messages)
+    if tokens_before <= self._max_tokens:
+        return messages
+    # ... 分离 system/old/recent ...
+    # Step 1: summarize
+    # Step 2: aggressive (F-010: 传入原始 messages 而非 compressed，避免 summary-of-summary)
+    if self.estimate_tokens(compressed) > self._max_tokens:
+        compressed = await self._compress_aggressive(messages)
+    # Step 3: truncate as last resort
+    if self.estimate_tokens(compressed) > self._max_tokens:
+        compressed = self._truncate(compressed)
+    # Step 4: 结构化日志
+    self._log_compression(tokens_before, tokens_after, len(messages), len(compressed), strategy)
+    return compressed
+```
+
+**5. 新增 `_log_compression()` 结构化日志**：
+
+```python
+logger.info(
+    "context compressed: %d -> %d tokens (%.1f%%), messages: %d -> %d, strategy: %s",
+    tokens_before, tokens_after, ratio * 100,
+    msg_count_before, msg_count_after, strategy,
+)
+```
+
+## Why This Works
+
+**根本原因**：CJK 字符在主流 tokenizer（BPE/WordPiece/SentencePiece）中近似 1:1 映射为 token，而 ASCII/拉丁文约 4 字符/token。`len(content) // 4` 把这 4 倍差异抹平了，导致 CJK 估算系统性偏低。
+
+修复后的 `estimate_text_tokens()` 对 CJK 字符按 1:1 计数、对非 CJK 保留 4:1，既纠正了 CJK 偏差又维持了 ASCII 行为。`_summarize()` 的 `max_chars = max_input_tokens` 对 CJK 精确（1:1）、对 ASCII 保守（截断到 1/4 预算但安全），彻底消除了"4 倍超预算"路径。
+
+`headroom_threshold=0.8` 吸收了纯 CJK 仍可能存在的 10-20% 估算偏差（`ponytail:` 注释已标注上限与升级路径——`litellm.token_counter` 或 provider 专用 tokenizer）。
+
+**可维护性改进**：线性 `compress()` 流程（summarize → aggressive → truncate）移除了递归深度计数器，单次读取即可理解全部降级路径；`_compress_aggressive()` 接收原始 `messages` 而非已压缩的 `compressed`，规避了 F-010 的 summary-of-summary；`_log_compression()` 提供结构化观测字段（before/after/ratio/msg_count/strategy），使压缩行为可调试、可告警。
+
+## Prevention
+
+- **字符集感知的估算启发式**：任何 token 估算逻辑必须考虑字符集差异。`len // 4` 仅对 ASCII 成立；CJK/emoji/其他多字节脚本需分别处理。涉及多语言输入时，优先使用 `litellm.token_counter` 或 provider 专用 tokenizer（当前 `estimate_text_tokens` 的 `ponytail` 注释已标注此升级路径）
+- **修改估算逻辑时审计所有依赖的截断点**：本次修复同步审计了 `estimate_tokens()`、`_summarize()` 预截断、`ReActEngine._should_compress()` 回退路径。`_truncate()` 仍用 `len(content) > self._max_tokens * 4` 判断（OQ21 延期项），后续需同步迁移至字符集感知逻辑
+- **测试覆盖字符集矩阵**：新增测试覆盖纯 CJK、纯 ASCII、CJK+ASCII 混合、平假名/片假名、谚文等场景（`tests/unit/test_context_compressor.py`），验证估算器在各字符集下的正确性
+- **避免 summary-of-summary**：多级压缩时，后续阶段应接收原始输入而非前级压缩产物，防止信息逐级失真（F-010 教训）
+- **结构化日志先行**：压缩是黑盒操作，必须输出 before/after token、压缩比、消息数、策略等结构化字段，便于线上问题定位
+
+## References
+
+- Plan: `docs/plans/2026-07-02-003-feat-context-compressor-cjk-prefix-enhancement-plan.md`（3 轮 ce-doc-review，收敛到 U1 + U3）
+- PR #21: `feat/context-compressor-cjk`（commits `be45fe4` + `3a05c4d`）
+- Upstream context: `docs/plans/2026-06-24-004-feat-long-horizon-reliability-optimization-plan.md`（headroom 压缩引入点）
+- Residual: OQ21（`_truncate()` `* 4` 一致性，P2 manual 跟进）