@baimingtao/lbs-agent 1.0.0

package/runtime/context/management/context_manager.py

@@ -0,0 +1,1008 @@
+"""
+Context manager —— 会话上下文压缩引擎。
+
+对标 LBS ContextCompressor 的核心能力：
+  1. Token 估算（不是字符数）
+  2. Tool result 裁剪（旧工具结果替换为摘要）
+  3. Duplicate detection（同文件多次读取只留最新）
+  4. Threshold percent（基于模型 context window 百分比）
+  5. Preflight（循环前检查）
+  6. Anti-thrashing（连续压缩无效果时停止）
+
+压缩算法：
+  Phase 1: Prune — 裁剪旧 tool result（无 LLM 调用）
+  Phase 2: Boundary — 确定保护头部+尾部边界
+  Phase 3: Summarize — LLM 摘要中间消息（或降级为截断）
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from dataclasses import dataclass, field
+from typing import Any, Optional, Callable
+
+logger = logging.getLogger(__name__)
+
+# ── 常量 ─────────────────────────────────────────────
+
+# 粗略 token 估算：1 token ≈ 4 个字符（英文），中文约 2 字符/token
+# 取 3.5 作为折中
+_CHARS_PER_TOKEN = 3.5
+
+# tool result 裁剪后保留的最大字符数
+_TOOL_RESULT_PRUNE_CHARS = 200
+
+# 大 tool result 阈值（超过此长度考虑裁剪）
+_LARGE_TOOL_RESULT_CHARS = 2000
+
+# 最小压缩间隔：连续两次压缩之间至少新增 5 条消息
+_MIN_MESSAGES_BETWEEN_COMPRESS = 5
+
+
+@dataclass
+class CompressionResult:
+    compressed: bool
+    before_chars: int
+    after_chars: int
+    before_tokens: int = 0
+    after_tokens: int = 0
+    summary: str = ""
+    preserved_messages: int = 0
+    dropped_messages: int = 0
+    pruned_tool_results: int = 0
+    deduplicated_files: int = 0
+    warnings: list[str] = field(default_factory=list)
+    method: str = "none"  # none | prune | truncate | llm_summary
+    extracted_facts: list[str] = field(default_factory=list)
+
+
+class ContextManager:
+    """上下文压缩引擎。
+
+    配置：
+      context_length: 模型 context window（如 128000）
+      threshold_percent: 触发压缩的百分比（默认 0.50 = 50%）
+      protect_first_n: 保护头部 N 条消息（system prompt + 首次交互）
+      protect_last_n: 保护尾部 N 条消息（最近交互）
+      tail_token_budget: 尾部 token 预算（覆盖 protect_last_n）
+    """
+
+    def __init__(
+        self,
+        max_chars: int = 60000,  # 向后兼容
+        keep_recent: int = 8,    # 向后兼容
+        llm_summarizer: Optional[Callable[[list[dict]], str]] = None,
+        context_length: int = 128000,
+        threshold_percent: float = 0.50,
+        protect_first_n: int = 3,
+        protect_last_n: int = 12,
+        on_compression: Optional[Callable[[Any], None]] = None,
+    ):
+        # 新参数优先
+        self.context_length = context_length
+        self.threshold_percent = threshold_percent
+        self.threshold_tokens = max(
+            int(context_length * threshold_percent),
+            max_chars // _CHARS_PER_TOKEN,  # 不低于旧阈值
+        )
+        self.protect_first_n = protect_first_n
+        self.protect_last_n = protect_last_n
+        self.tail_token_budget = int(self.threshold_tokens * 0.4)  # 40% 给尾部
+
+        # 向后兼容
+        self.max_chars = max_chars
+        self.keep_recent = keep_recent
+
+        self._llm_summarizer = llm_summarizer
+        self._on_compression = on_compression
+
+        # Anti-thrashing 状态
+        self._last_compress_msg_count = 0
+        self._last_compress_tokens = 0
+        self._consecutive_ineffective = 0
+
+
+    def reset_session_state(self) -> None:
+        """清空本次 session 的压缩状态，避免跨会话污染。"""
+        self._last_compress_msg_count = 0
+        self._last_compress_tokens = 0
+        self._consecutive_ineffective = 0
+        self.last_prompt_tokens = 0
+        self.last_completion_tokens = 0
+        self.last_total_tokens = 0
+
+    def on_session_end(self) -> None:
+        """结束会话并清空所有压缩器状态。"""
+        self.reset_session_state()
+
+    def on_session_reset(self) -> None:
+        """开始新会话时清空旧压缩状态。"""
+        self.reset_session_state()
+    def update_from_response(self, usage: dict[str, int]):
+        """用 API 返回的真实 token 数校准估算。
+
+        当 API 返回 prompt_tokens 时，比粗略估算准确得多。
+        后续 should_compress 判断会优先使用这个值。
+        """
+        self.last_prompt_tokens = usage.get("prompt_tokens", 0)
+        self.last_completion_tokens = usage.get("completion_tokens", 0)
+        self.last_total_tokens = usage.get("total_tokens", self.last_prompt_tokens + self.last_completion_tokens)
+
+    def get_effective_token_count(self, messages: list[dict] = None) -> int:
+        """获取最准确的 token 估算。
+
+        优先用 API 返回的真实值，否则用粗略估算。
+        """
+        if hasattr(self, 'last_prompt_tokens') and self.last_prompt_tokens > 0:
+            return self.last_prompt_tokens
+        if messages:
+            return self.estimate_tokens(messages)
+        return 0
+
+    def set_llm_summarizer(self, fn: Callable[[list[dict]], str]):
+        self._llm_summarizer = fn
+
+    def update_model(self, context_length: int, threshold_percent: float = None):
+        """切换模型时更新 context window 和阈值。"""
+        self.context_length = context_length
+        if threshold_percent is not None:
+            self.threshold_percent = threshold_percent
+        self.threshold_tokens = max(
+            int(context_length * self.threshold_percent),
+            self.max_chars // _CHARS_PER_TOKEN,
+        )
+        self.tail_token_budget = int(self.threshold_tokens * 0.4)
+
+    # ── Token 估算 ────────────────────────────────────
+
+    def estimate_tokens(self, messages: list[dict[str, Any]]) -> int:
+        """粗略估算 messages 的 token 数。
+
+        比 LBS 简单但够用：
+          - 文本：字符数 / 3.5
+          - tool_calls：每个 +50 tokens（参数 JSON）
+          - 图片：+1000 tokens（如果有）
+        """
+        total = 0
+        for m in messages:
+            content = m.get("content", "")
+            if isinstance(content, str):
+                total += len(content) / _CHARS_PER_TOKEN
+            elif isinstance(content, list):
+                for part in content:
+                    if isinstance(part, dict):
+                        if part.get("type") == "text":
+                            total += len(part.get("text", "")) / _CHARS_PER_TOKEN
+                        elif part.get("type") == "image_url":
+                            total += 1000
+            total += 4  # role 开销
+
+            # tool_calls 开销
+            tcs = m.get("tool_calls")
+            if tcs:
+                for tc in tcs:
+                    total += 50
+                    args = tc.get("function", {}).get("arguments", "") if isinstance(tc, dict) else ""
+                    total += len(args) / _CHARS_PER_TOKEN
+
+        return int(total)
+
+    def estimate_message_tokens(self, msg: dict[str, Any]) -> int:
+        return self.estimate_tokens([msg])
+
+    # ── 判断是否需要压缩 ──────────────────────────────
+
+    def should_compress(self, messages: list[dict[str, Any]]) -> bool:
+        """检查是否需要压缩。"""
+        tokens = self.estimate_tokens(messages)
+
+        # Anti-thrashing：如果距离上次压缩新增消息不够，不压缩
+        new_msgs = len(messages) - self._last_compress_msg_count
+        if self._last_compress_msg_count > 0 and new_msgs < _MIN_MESSAGES_BETWEEN_COMPRESS:
+            return False
+
+        return tokens >= self.threshold_tokens
+
+    # ── 主压缩入口 ────────────────────────────────────
+
+    def compress_if_needed(self, messages: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], CompressionResult]:
+        """检查并执行上下文压缩。
+
+        算法：
+          Phase 0: Gate — 用 should_compress 判断是否需要完整压缩
+          Phase 1: Prune — 裁剪旧 tool result（轻量，总是执行）
+          Phase 2: 判断是否还需要进一步压缩
+          Phase 3: Summarize — LLM 摘要中间消息（或截断）
+        """
+        before_tokens = self.estimate_tokens(messages)
+        before_chars = sum(len(str(m.get("content", ""))) for m in messages)
+
+        # Phase 1: Prune old tool results（轻量预处理，总是执行）
+        messages, pruned_count, dedup_count = self._prune_tool_results(messages)
+
+        after_prune_tokens = self.estimate_tokens(messages)
+
+        # Phase 0 Gate: 如果 prune 后已低于阈值，且没有触发 should_compress，则不需要进入重压缩
+        if not self.should_compress(messages) and after_prune_tokens < self.threshold_tokens:
+            after_chars = sum(len(str(m.get("content", ""))) for m in messages)
+            result = CompressionResult(
+                compressed=pruned_count > 0 or dedup_count > 0,
+                before_chars=before_chars,
+                after_chars=after_chars,
+                before_tokens=before_tokens,
+                after_tokens=after_prune_tokens,
+                preserved_messages=len(messages),
+                dropped_messages=0,
+                pruned_tool_results=pruned_count,
+                deduplicated_files=dedup_count,
+                method="prune" if pruned_count > 0 or dedup_count > 0 else "none",
+            )
+            self._update_anti_thrash(after_prune_tokens, len(messages))
+            return messages, result
+
+        # Phase 2+3: 确定 boundary + 摘要中间消息
+        head_size = self._protect_head_size(messages)
+        tail_start = self._find_tail_boundary(messages, head_size)
+
+        head = messages[:head_size]
+        tail = messages[tail_start:]
+        middle = messages[head_size:tail_start]
+
+        if not middle:
+            after_chars = sum(len(str(m.get("content", ""))) for m in messages)
+            return messages, CompressionResult(
+                compressed=pruned_count > 0,
+                before_chars=before_chars, after_chars=after_chars,
+                before_tokens=before_tokens, after_tokens=after_prune_tokens,
+                preserved_messages=len(messages),
+                pruned_tool_results=pruned_count,
+                deduplicated_files=dedup_count,
+                method="prune",
+            )
+
+        # Phase 2.5: 从即将被丢弃的中间消息中提取关键事实
+        extracted_facts = self._extract_facts_from_middle(middle)
+
+        # 摘要中间消息
+        method = "truncate"
+        summary = ""
+        # 检查是否已有旧摘要（再次压缩）
+        old_summary = ""
+        for m in head:
+            if "[上下文压缩摘要" in str(m.get("content", "")):
+                old_summary = str(m["content"])
+                break
+
+        if self._llm_summarizer and not old_summary:
+            # 首次 LLM 摘要
+            try:
+                redacted_middle = [{"role": m.get("role", "user"),
+                                   "content": self._redact_secrets(str(m.get("content", "")))}
+                                  for m in middle]
+                summary = self._llm_summarizer(redacted_middle)
+                method = "llm_summary"
+            except Exception as e:
+                logger.warning("LLM 摘要失败，降级为静态摘要: %s", e)
+                summary = self._build_static_fallback_summary(middle)
+                method = "fallback"
+        elif self._llm_summarizer and old_summary:
+            # 再次压缩：更新已有摘要
+            summary = self._update_existing_summary(old_summary, middle)
+            method = "llm_summary_update"
+        else:
+            # 无 LLM：静态降级
+            summary = self._build_static_fallback_summary(middle)
+            method = "fallback"
+
+        # 将提取的事实注入摘要消息
+        if extracted_facts:
+            facts_block = "\n[保留事实]\n" + "\n".join(f"- {f}" for f in extracted_facts)
+            summary = summary + facts_block
+
+        summary_msg = {
+            "role": "user",
+            "content": f"[上下文压缩摘要 ({method})]\n{summary}",
+        }
+
+        # 保持 tool_call/tool_result 配对完整性
+        new_messages = self._sanitize_tool_pairs(head + [summary_msg] + tail)
+
+        # P3-4: 压缩后验证消息合法性
+        temp_result = CompressionResult(compressed=True, before_chars=0, after_chars=0)
+        self._safe_validate_after_compress(new_messages, temp_result)
+        if temp_result.warnings:
+            logger.warning("[compression] post-compression validation issues: %s", temp_result.warnings)
+
+        after_tokens = self.estimate_tokens(new_messages)
+        after_chars = sum(len(str(m.get("content", ""))) for m in new_messages)
+
+        result = CompressionResult(
+            compressed=True,
+            before_chars=before_chars,
+            after_chars=after_chars,
+            before_tokens=before_tokens,
+            after_tokens=after_tokens,
+            summary=summary[:500],
+            preserved_messages=len(new_messages),
+            dropped_messages=len(middle),
+            pruned_tool_results=pruned_count,
+            deduplicated_files=dedup_count,
+            method=method,
+            extracted_facts=extracted_facts,
+        )
+
+        if after_tokens >= after_prune_tokens:
+            result.warnings.append("压缩后 token 数未下降")
+            self._consecutive_ineffective += 1
+        else:
+            self._consecutive_ineffective = 0
+
+        self._update_anti_thrash(after_tokens, len(new_messages))
+        return new_messages, result
+
+    # ── P3-4: Post-compression validation ──────────────
+
+    def _validate_compressed_messages(self, messages: list[dict[str, Any]]) -> list[str]:
+        """验证压缩后的消息序列是否合法。
+
+        检查项：
+        1. 所有 tool_result 都有对应的 tool_call
+        2. 消息角色交替正确（user/assistant/tool）
+        3. 没有 None content（除非允许）
+        4. tool_call_id 没有重复
+
+        Returns: 问题列表（空列表 = 合法）
+        """
+        issues: list[str] = []
+
+        valid_call_ids = self._extract_tool_call_ids(messages)
+        seen_result_ids: set[str] = set()
+
+        for i, msg in enumerate(messages):
+            role = msg.get("role", "")
+
+            # 检查 tool_result 配对
+            is_tr, call_id = self._is_tool_result_message(msg)
+            if is_tr:
+                if call_id not in valid_call_ids:
+                    issues.append(f"msg[{i}]: orphan tool_result (call_id={call_id})")
+                if call_id in seen_result_ids:
+                    issues.append(f"msg[{i}]: duplicate tool_result (call_id={call_id})")
+                seen_result_ids.add(call_id)
+
+            # 检查 None content（assistant 允许，其他不允许）
+            raw_content = msg.get("content")
+            if raw_content is None and role not in ("assistant",):
+                # Anthropic tool_result 的 content 可能为 None
+                if not (isinstance(raw_content, list) and raw_content):
+                    issues.append(f"msg[{i}]: None content for role={role}")
+
+        # 检查首消息不是 tool/assistant-with-tool-result
+        if messages:
+            first_role = messages[0].get("role", "")
+            is_tr_first, _ = self._is_tool_result_message(messages[0])
+            if first_role == "tool" or is_tr_first:
+                issues.append("msg[0]: first message is tool_result without preceding tool_call")
+
+        return issues
+
+    def _safe_validate_after_compress(self, messages: list[dict[str, Any]], result: CompressionResult) -> None:
+        """压缩后验证，发现问题则记录 warning。"""
+        issues = self._validate_compressed_messages(messages)
+        for issue in issues:
+            result.warnings.append(f"[post-compression] {issue}")
+
+    # ── Phase 1: Tool Result 裁剪 ─────────────────────
+
+    def _prune_tool_results(self, messages: list[dict[str, Any]]) -> tuple[list[dict], int, int]:
+        """裁剪旧 tool result + 去重。
+
+        1. 保护尾部消息（最近的 tool result 保留完整）
+        2. 旧 tool result 替换为 1 行摘要
+        3. 同文件多次读取只保留最新
+        """
+        if not messages:
+            return messages, 0, 0
+
+        result = [dict(m) for m in messages]
+        pruned = 0
+        deduped = 0
+
+        # 确定尾部保护边界（token budget）
+        tail_boundary = self._find_tail_boundary(result, self._protect_head_size(result))
+
+        # 构建 tool_call_id → tool 信息映射（兼容 OpenAI + Anthropic）
+        call_id_to_tool: dict[str, tuple[str, str]] = {}
+        for msg in result:
+            if msg.get("role") == "assistant":
+                # OpenAI: tool_calls[].function.{name, arguments}
+                for tc in (msg.get("tool_calls") or []):
+                    if isinstance(tc, dict):
+                        cid = tc.get("id", "")
+                        fn = tc.get("function", {})
+                        call_id_to_tool[cid] = (fn.get("name", "?"), fn.get("arguments", ""))
+                # Anthropic: content[].{type: "tool_use", id, name, input}
+                content = msg.get("content")
+                if isinstance(content, list):
+                    for block in content:
+                        if isinstance(block, dict) and block.get("type") == "tool_use":
+                            cid = block.get("id", "")
+                            name = block.get("name", "?")
+                            args = block.get("input", "")
+                            if isinstance(args, dict):
+                                args = json.dumps(args, ensure_ascii=False)
+                            call_id_to_tool[cid] = (name, str(args))
+
+        # 去重：同文件多次读取只保留最新（兼容 OpenAI + Anthropic）
+        file_read_map: dict[str, int] = {}  # file_path → last msg index
+        for i, msg in enumerate(result):
+            is_tr, tr_call_id = self._is_tool_result_message(msg)
+            if is_tr and i < tail_boundary:
+                call_id = tr_call_id
+                tool_name, tool_args = call_id_to_tool.get(call_id, ("", ""))
+                if tool_name == "read_file":
+                    try:
+                        args = json.loads(tool_args) if isinstance(tool_args, str) else tool_args
+                        fp = args.get("path", "")
+                        if fp:
+                            if fp in file_read_map:
+                                # 旧的替换为摘要（兼容 content 为 str 或 list）
+                                old_idx = file_read_map[fp]
+                                old_content_raw = result[old_idx].get("content", "")
+                                old_content = str(old_content_raw)
+                                dedup_msg = f"[重复读取已裁剪] {fp} (原 {len(old_content)} chars)"
+                                if isinstance(old_content_raw, list):
+                                    # Anthropic: content is list of blocks
+                                    # 保持 tool_result block 类型不变
+                                    dedup_blocks = []
+                                    for block in old_content_raw:
+                                        if isinstance(block, dict) and block.get("type") == "tool_result":
+                                            db = dict(block)
+                                            db["content"] = dedup_msg
+                                            dedup_blocks.append(db)
+                                        else:
+                                            dedup_blocks.append(block)
+                                    result[old_idx]["content"] = dedup_blocks
+                                else:
+                                    result[old_idx]["content"] = dedup_msg
+                                deduped += 1
+                            file_read_map[fp] = i
+                    except Exception:
+                        pass
+
+        # 裁剪旧 tool result（尾部保护区域之外，兼容 OpenAI + Anthropic）
+        for i, msg in enumerate(result):
+            if i >= tail_boundary:
+                continue
+            is_tr, tr_call_id = self._is_tool_result_message(msg)
+            if not is_tr:
+                continue
+            content = str(msg.get("content", ""))
+            if len(content) <= _LARGE_TOOL_RESULT_CHARS:
+                continue
+            # 替换为摘要
+            call_id = tr_call_id
+            tool_name, tool_args = call_id_to_tool.get(call_id, ("unknown", ""))
+            summary_line = self._summarize_tool_result(tool_name, tool_args, content)
+            # 兼容 Anthropic content 为 list 的情况
+            # 保持 tool_result block 类型不变，只替换 content 文本，
+            # 避免 seeyon 网关报 "No tool output found for function call"。
+            if isinstance(msg.get("content"), list):
+                pruned_blocks = []
+                for block in msg["content"]:
+                    if isinstance(block, dict) and block.get("type") == "tool_result":
+                        pruned_block = dict(block)
+                        pruned_block["content"] = summary_line
+                        pruned_blocks.append(pruned_block)
+                    else:
+                        pruned_blocks.append(block)
+                result[i]["content"] = pruned_blocks
+            else:
+                result[i]["content"] = summary_line
+            pruned += 1
+
+        return result, pruned, deduped
+
+    _KEEP_HEAD = 1200   # 裁剪时保留头部字符数
+    _KEEP_TAIL = 800    # 裁剪时保留尾部字符数
+
+    def _summarize_tool_result(self, tool_name: str, args_json: str, content: str) -> str:
+        """裁剪大 tool result：保留头尾内容，只省略中间。
+
+        旧实现把完整内容替换成一行元信息摘要，导致 Agent 丢失正文。
+        新实现保留足够内容让 Agent 继续工作，只省略中间冗余部分。
+        """
+        head = content[:self._KEEP_HEAD]
+        tail = content[-self._KEEP_TAIL:]
+        omitted = len(content) - self._KEEP_HEAD - self._KEEP_TAIL
+        lines = content.strip().split("\n")
+        line_count = len(lines)
+        try:
+            args = json.loads(args_json) if isinstance(args_json, str) else args_json
+        except Exception:
+            args = {}
+        # 工具专属标注
+        meta = ""
+        if tool_name == "read_file":
+            meta = f"[read_file] {args.get('path', '?')} — {line_count} lines, {len(content)} chars"
+        elif tool_name == "terminal":
+            ec_match = re.search(r"\[exit=(\d+)\]", content)
+            meta = f"[terminal] {args.get('command', '?')[:60]} → exit={ec_match.group(1) if ec_match else '?'}, {line_count} lines"
+        elif tool_name == "search_files":
+            meta = f"[search_files] pattern={args.get('pattern', '?')} → {line_count} results"
+        else:
+            meta = f"[{tool_name}] {len(content)} chars → {line_count} lines"
+        return f"{meta} (中间省略 ~{omitted} 字符)\n{head}\n\n... [{omitted} chars omitted] ...\n\n{tail}"
+
+    # ── Phase 2: Boundary ─────────────────────────────
+
+    def _protect_head_size(self, messages: list[dict]) -> int:
+        """计算头部保护消息数。"""
+        head = 0
+        # 保护 system prompt（如果有）
+        if messages and messages[0].get("role") == "system":
+            head = 1
+        else:
+            head = 0
+        # 保护首次交互
+        head += self.protect_first_n
+        return min(head, len(messages))
+
+    def _find_tail_boundary(self, messages: list[dict], head_size: int) -> int:
+        """从尾部往回走，按 token budget 确定尾部保护边界。"""
+        if not messages:
+            return 0
+
+        accumulated = 0
+        budget = self.tail_token_budget
+        min_tail = min(self.protect_last_n, len(messages))
+        soft_ceiling = int(budget * 1.5)
+
+        boundary = len(messages)
+        for i in range(len(messages) - 1, head_size - 1, -1):
+            msg_tokens = self.estimate_message_tokens(messages[i])
+            if accumulated + msg_tokens > soft_ceiling and (len(messages) - i) >= min_tail:
+                boundary = i + 1
+                break
+            accumulated += msg_tokens
+
+        boundary = max(boundary, len(messages) - min_tail)
+        boundary = max(boundary, head_size + 1)
+
+        # 确保 tool_call/tool_result 配对完整
+        boundary = self._align_boundary(messages, boundary)
+        return boundary
+
+    def _align_boundary(self, messages: list[dict], idx: int) -> int:
+        """确保 boundary 不切断 tool_call/tool_result 配对。
+
+        兼容 OpenAI 和 Anthropic 格式。
+        """
+        while idx > 0 and idx < len(messages):
+            msg = messages[idx]
+            # OpenAI: role=tool
+            # Anthropic: user content contains tool_result block
+            is_tr, _ = self._is_tool_result_message(msg)
+            if is_tr:
+                idx -= 1
+                continue
+            # 如果前一条是 assistant 带 tool_call（OpenAI tool_calls 或 Anthropic tool_use），也包含进来
+            if idx > 0 and self._is_tool_call_message(messages[idx - 1]):
+                idx -= 1
+                continue
+            break
+        return idx
+
+    # ── Phase 3: Summarize ────────────────────────────
+
+
+    def _compute_summary_budget(self, turns_to_summarize: list[dict]) -> int:
+        """根据待压缩内容大小动态计算摘要 token 预算。
+
+        比例：待压缩内容的 10%，上限 max_summary_tokens，下限 2000。
+        """
+        content_tokens = self.estimate_tokens(turns_to_summarize)
+        budget = int(content_tokens * 0.10)
+        max_budget = min(int(self.context_length * 0.05), 8000)
+        return max(2000, min(budget, max_budget))
+
+    def _redact_secrets(self, text: str) -> str:
+        """脱敏 API key、token、密码等敏感信息。"""
+        import re
+        # API key patterns (sk-xxx...)
+        text = re.sub(r'(sk-[a-zA-Z0-9]{8})[a-zA-Z0-9]+', r'\1***', text)
+        # Bearer tokens
+        text = re.sub(r'(Bearer\s+)[a-zA-Z0-9._-]{8,}', r'\1***', text)
+        # key=value patterns — use a safe character class
+        for keyword in ("api_key", "api_secret", "password", "token", "secret"):
+            pattern = keyword + r"[\'\"]?\s*[:=]\s*[\'\"]?[^\'\"\s]+"
+            text = re.sub(pattern, keyword + "=***", text, flags=re.IGNORECASE)
+        return text
+
+    def _build_static_fallback_summary(self, turns: list[dict]) -> str:
+        """LLM 摘要失败时的确定性降级。
+
+        P1-4: 结构化字段，不再只提取路径和错误。
+
+        固定输出：
+          任务目标:
+          已完成:
+          关键文件:
+          关键命令:
+          已知错误:
+          当前状态:
+          未完成事项:
+        """
+        import re
+        paths: list[str] = []
+        commands: list[str] = []
+        errors: list[str] = []
+        user_requests: list[str] = []
+        completed_actions: list[str] = []
+        tool_names: list[str] = []
+
+        all_text = ""
+        for msg in turns:
+            role = msg.get("role", "")
+            content = str(msg.get("content", ""))
+            all_text += content + "\n"
+
+            if role == "user":
+                user_requests.append(content[:150])
+            if "[exit=" in content:
+                commands.append(content[:100])
+            if any(kw in content for kw in ("完成", "成功", "done", "pass", "通过")):
+                completed_actions.append(content[:120])
+
+            # Collect tool names from tool_calls
+            tcs = msg.get("tool_calls") or []
+            for tc in tcs:
+                if isinstance(tc, dict):
+                    tool_names.append(tc.get("function", {}).get("name", "?"))
+
+        for m in re.finditer(r'[\w/\\]+\.[a-z]{2,4}(?:\b|\s)', all_text):
+            path = m.group().strip()
+            if path not in paths and len(path) > 3:
+                paths.append(path)
+
+        for m in re.finditer(r'(?:ERROR|Error|error|失败|异常)[^\n]{0,200}', all_text):
+            errors.append(m.group()[:150])
+
+        lines = ["[确定性降级摘要 — 结构化]"]
+
+        if user_requests:
+            lines.append("\n任务目标:")
+            for r in user_requests[-2:]:
+                lines.append(f"  - {r}")
+
+        if completed_actions:
+            lines.append("\n已完成:")
+            for c in completed_actions[-5:]:
+                lines.append(f"  - {c}")
+        elif tool_names:
+            unique_tools = list(dict.fromkeys(tool_names))
+            lines.append("\n已调用工具:")
+            lines.append(f"  - {', '.join(unique_tools[:10])}")
+
+        if paths:
+            lines.append("\n关键文件:")
+            for fp in paths[:10]:
+                lines.append(f"  - {fp}")
+
+        if commands:
+            lines.append("\n关键命令:")
+            for c in commands[-5:]:
+                lines.append(f"  - {c}")
+
+        if errors:
+            lines.append("\n已知错误:")
+            for e in errors[-3:]:
+                lines.append(f"  - {e}")
+
+        if user_requests:
+            lines.append("\n当前状态: 任务进行中")
+            lines.append("\n未完成事项:")
+            lines.append("  - 需要继续执行剩余步骤")
+        else:
+            lines.append("\n当前状态: 无法判断")
+
+        return "\n".join(lines)
+
+    def _update_existing_summary(self, old_summary: str, new_turns: list[dict]) -> str:
+        """再次压缩时，更新已有摘要而非从头生成。
+
+        如果有 LLM summarizer，用它做增量更新。
+        否则把新内容追加到旧摘要后面。
+        """
+        if not old_summary:
+            return self._truncate_middle(new_turns)
+
+        if self._llm_summarizer:
+            new_content = self._truncate_middle(new_turns)
+            combined = f"已有摘要:\n{old_summary}\n\n新增内容:\n{new_content}"
+            try:
+                redacted = self._redact_secrets(combined)
+                return self._llm_summarizer([{"role": "user", "content": redacted}])
+            except Exception:
+                return self._build_static_fallback_summary(new_turns)
+        else:
+            # 无 LLM：追加新摘要
+            new_part = self._truncate_middle(new_turns)
+            return f"{old_summary}\n\n--- 后续新增 ---\n{new_part}"
+
+    def _truncate_middle(self, messages: list[dict[str, Any]]) -> str:
+        """确定性截断摘要（降级方案）。"""
+        lines = [f"已压缩 {len(messages)} 条历史消息，保留关键轨迹："]
+        for i, msg in enumerate(messages[-15:], 1):
+            role = msg.get("role", "unknown")
+            content = str(msg.get("content", "")).replace("\n", " ")[:200]
+            if msg.get("tool_calls"):
+                tc_names = [t.get("function", {}).get("name", "?") if isinstance(t, dict) else str(t) for t in msg["tool_calls"]]
+                content += f" [工具: {', '.join(tc_names)}]"
+            lines.append(f"{i}. {role}: {content}")
+        return "\n".join(lines)
+
+    # ── Provider-neutral tool helpers ──────────────────
+
+    @staticmethod
+    def _extract_tool_call_ids(messages: list[dict]) -> set[str]:
+        """收集所有 tool_call_id，兼容 OpenAI 和 Anthropic 格式。
+
+        OpenAI:
+          assistant.tool_calls[].id
+          tool.tool_call_id
+
+        Anthropic:
+          assistant.content[].{type: "tool_use", id: ...}
+          user.content[].{type: "tool_result", tool_use_id: ...}
+        """
+        ids: set[str] = set()
+        for msg in messages:
+            role = msg.get("role", "")
+            # OpenAI: assistant.tool_calls
+            if role == "assistant" and msg.get("tool_calls"):
+                for tc in msg["tool_calls"]:
+                    if isinstance(tc, dict):
+                        cid = tc.get("id", "")
+                        if cid:
+                            ids.add(cid)
+            # Anthropic: assistant.content[].tool_use
+            content = msg.get("content")
+            if role == "assistant" and isinstance(content, list):
+                for block in content:
+                    if isinstance(block, dict) and block.get("type") == "tool_use":
+                        cid = block.get("id", "")
+                        if cid:
+                            ids.add(cid)
+        return ids
+
+    @staticmethod
+    def _is_tool_result_message(msg: dict) -> tuple[bool, str]:
+        """判断是否是 tool_result 消息，返回 (is_tool_result, tool_call_id)。
+
+        兼容 OpenAI (role=tool, tool_call_id) 和 Anthropic (user.content[].tool_result)。
+        """
+        if msg.get("role") == "tool":
+            return True, msg.get("tool_call_id", "")
+        content = msg.get("content")
+        if msg.get("role") == "user" and isinstance(content, list):
+            for block in content:
+                if isinstance(block, dict) and block.get("type") == "tool_result":
+                    return True, block.get("tool_use_id", "")
+        return False, ""
+
+    @staticmethod
+    def _extract_tool_result_ids(msg: dict) -> list[str]:
+        """提取一条消息中所有 tool_result 的 tool_use_id。
+
+        兼容 OpenAI (role=tool, tool_call_id) 和 Anthropic
+        (user.content[].tool_result)。
+        """
+        ids: list[str] = []
+        if msg.get("role") == "tool":
+            cid = msg.get("tool_call_id", "")
+            if cid:
+                ids.append(cid)
+            return ids
+        content = msg.get("content")
+        if msg.get("role") == "user" and isinstance(content, list):
+            for block in content:
+                if isinstance(block, dict) and block.get("type") == "tool_result":
+                    cid = block.get("tool_use_id", "")
+                    if cid:
+                        ids.append(cid)
+        return ids
+
+    @staticmethod
+    def _is_tool_call_message(msg: dict) -> bool:
+        """判断是否是 tool_call 消息（assistant 发起的工具调用）。
+
+        兼容 OpenAI 和 Anthropic 格式。
+        """
+        if msg.get("role") == "assistant" and msg.get("tool_calls"):
+            return True
+        content = msg.get("content")
+        if msg.get("role") == "assistant" and isinstance(content, list):
+            for block in content:
+                if isinstance(block, dict) and block.get("type") == "tool_use":
+                    return True
+        return False
+
+    # ── Tool pair sanitization ────────────────────────
+
+    def _extract_facts_from_middle(self, middle: list[dict]) -> list[str]:
+        """从即将被压缩的中间消息中提取关键事实。
+
+        纯静态提取（不调 LLM），识别用户陈述中的偏好/参数/决策。
+        提取后自动脱敏。
+        """
+        if not middle:
+            return []
+        facts: list[str] = []
+        for msg in middle:
+            if not isinstance(msg, dict):
+                continue
+            role = msg.get("role", "")
+            content = str(msg.get("content", "")).strip()
+            if not content or len(content) < 5:
+                continue
+            # 只从 user 消息中提取（用户陈述的事实）
+            if role != "user":
+                continue
+            # 识别偏好/参数声明
+            lower = content.lower()
+            # 中文偏好模式
+            for pattern in [
+                "我喜欢", "我偏好", "我习惯", "我的", "请记住", "我要求",
+                "默认使用", "项目使用", "数据库", "配置", "密码是", "密钥是",
+                "不要", "避免", "必须",
+            ]:
+                if pattern in lower:
+                    # 取包含模式的那一句
+                    idx = lower.find(pattern)
+                    sentence = content[idx:idx+200].split("\n")[0].strip()
+                    if len(sentence) > 3:
+                        facts.append(self._redact_secrets(sentence))
+                    break
+            else:
+                # 英文偏好模式
+                en_patterns = ["i prefer", "i like", "i use", "my name", "my project",
+                               "default", "always use", "never", "don't"]
+                for pattern in en_patterns:
+                    if pattern in lower:
+                        idx = lower.find(pattern)
+                        sentence = content[idx:idx+200].split("\n")[0].strip()
+                        if len(sentence) > 3:
+                            facts.append(self._redact_secrets(sentence))
+                        break
+        # 去重，保留最多 10 条
+        seen = set()
+        unique = []
+        for f in facts:
+            key = f[:50].lower()
+            if key not in seen:
+                seen.add(key)
+                unique.append(f)
+        return unique[:10]
+
+    def _sanitize_tool_pairs(self, messages: list[dict]) -> list[dict]:
+        """只保留按消息顺序恰好配对一次的工具调用和结果。
+
+        压缩可能截掉 tool_call 或 tool_result 的任一端；把残留端发给
+        provider 会触发 ``No tool output found`` 或协议校验错误。该方法
+        兼容 OpenAI ``tool_calls``/``role=tool`` 与 Anthropic
+        ``tool_use``/``tool_result`` 格式，并保留非工具内容。
+        """
+        pending: set[str] = set()
+        paired_call_ids: set[str] = set()
+        accepted_result_indexes: set[int] = set()
+
+        # 第一遍只接受“先调用、后首次结果”的严格配对。
+        # 注意：同一条 user 消息可能包含多个 tool_result block（Anthropic 格式），
+        # 必须逐个检查，不能只看第一个。
+        for index, msg in enumerate(messages):
+            result_ids_in_msg = self._extract_tool_result_ids(msg)
+            if result_ids_in_msg:
+                for call_id in result_ids_in_msg:
+                    if call_id in pending:
+                        paired_call_ids.add(call_id)
+                        pending.remove(call_id)
+                        accepted_result_indexes.add(index)
+                continue
+
+            if msg.get("role") == "assistant":
+                for tool_call_id in self._extract_tool_call_ids([msg]):
+                    # 相同 id 的重复调用不能覆盖尚未完成的调用。
+                    pending.add(tool_call_id)
+
+        result: list[dict] = []
+        for index, msg in enumerate(messages):
+            is_result, _ = self._is_tool_result_message(msg)
+            if is_result:
+                if index in accepted_result_indexes:
+                    result.append(msg)
+                continue
+
+            if msg.get("role") != "assistant":
+                result.append(msg)
+                continue
+
+            cleaned = dict(msg)
+            tool_calls = msg.get("tool_calls")
+            if isinstance(tool_calls, list):
+                cleaned["tool_calls"] = [
+                    call for call in tool_calls
+                    if isinstance(call, dict) and call.get("id") in paired_call_ids
+                ]
+
+            content = msg.get("content")
+            if isinstance(content, list):
+                cleaned["content"] = [
+                    block for block in content
+                    if not (isinstance(block, dict) and block.get("type") == "tool_use"
+                            and block.get("id") not in paired_call_ids)
+                ]
+
+            # 若 assistant 消息只剩空 tool_calls，则去掉该字段；保留文本回复。
+            if tool_calls is not None and not cleaned.get("tool_calls"):
+                cleaned.pop("tool_calls", None)
+            result.append(cleaned)
+
+        return result
+
+    # ── Anti-thrashing ────────────────────────────────
+
+
+    def compress_with_observers(self, messages: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], Any]:
+        """compress_if_needed 的可观察版本：压缩完成后调用 on_compression 回调。"""
+        new_messages, result = self.compress_if_needed(messages)
+        if self._on_compression is not None and getattr(result, "compressed", False):
+            try:
+                self._on_compression(result)
+            except Exception:
+                pass
+        return new_messages, result
+
+    def _update_anti_thrash(self, after_tokens: int, msg_count: int):
+        self._last_compress_msg_count = msg_count
+        self._last_compress_tokens = after_tokens
+
+
+def build_llm_summarizer(llm_client, system_prompt: str = "") -> Callable[[list[dict]], str]:
+    """构造 LLM 摘要函数。"""
+    _sys = system_prompt or (
+        "你是上下文压缩器。对以下 Agent 对话历史做结构化摘要。\n"
+        "必须按以下固定格式输出：\n"
+        "任务目标: <一句话>\n"
+        "已完成: <列表>\n"
+        "关键文件: <列表>\n"
+        "关键命令: <列表>\n"
+        "已知错误: <列表>\n"
+        "当前状态: <进行中/已完成/阻塞>\n"
+        "未完成事项: <列表>\n"
+        "丢弃冗余文本和重复内容。输出不超过 800 字。"
+    )
+
+    def summarize(messages: list[dict]) -> str:
+        parts = []
+        for msg in messages:
+            role = msg.get("role", "?")
+            content = str(msg.get("content", ""))[:500]
+            if msg.get("tool_calls"):
+                tc_names = [t.get("function", {}).get("name", "?") if isinstance(t, dict) else str(t) for t in msg["tool_calls"]]
+                content += f" [工具: {', '.join(tc_names)}]"
+            parts.append(f"[{role}] {content}")
+        history_text = "\n".join(parts)
+        if len(history_text) > 12000:
+            history_text = history_text[:6000] + "\n...[省略]...\n" + history_text[-6000:]
+        result = llm_client.chat(
+            messages=[{"role": "user", "content": f"请摘要以下对话历史:\n\n{history_text}"}],
+            system=_sys,
+            temperature=0.3,
+            max_tokens=1024,
+        )
+        return result.content.strip()
+
+    return summarize