langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/loop/context/compaction_service.py

@@ -0,0 +1,60 @@
+"""
+主循环 **上下文治理** 对 Graph 的 **门面服务**（唯一推荐接入点）。
+
+与 Claude Code 对齐：
+- 内部编排 CC 五段（`ContextPipeline` + `stages/*`），与 `query.ts` 中 `messagesForQuery` 顺序一致；
+- `factory` 中 `prune_and_compress` 节点应调用 `default_loop_context_compaction().run(...)`，而非散落模块函数。
+
+设计要点：
+- `LoopContextCompaction` 构造注入 `ContextPipeline`，便于单测替换阶段序列；
+- `default_loop_context_compaction()` 返回进程内单例，避免每轮重复装配。
+
+注意：
+- 不修改 `should_end` / `finish_reason` 等 exit 字段；只产出 `messages` 增量补丁。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping
+
+from .pipeline import ContextPipeline
+from .settings import CompactionSettings
+from .types import ContextCompactionContext
+
+
+class LoopContextCompaction:
+    """对 LangGraph state 执行 CC 五段上下文流水线。"""
+
+    def __init__(self, pipeline: ContextPipeline) -> None:
+        self._pipeline = pipeline
+
+    @classmethod
+    def with_default_pipeline(
+        cls,
+        *,
+        settings: CompactionSettings | None = None,
+    ) -> LoopContextCompaction:
+        """使用 CC 默认五段顺序装配管道。"""
+        return cls(ContextPipeline.with_default_stages(settings=settings))
+
+    def run(self, state: Mapping[str, Any], model: Any | None = None) -> Dict[str, Any]:
+        """返回 `Command(update=...)` 可用的补丁（常见为 ``{}`` 或 ``{"messages": ...}``）。"""
+        ctx = ContextCompactionContext.from_state(state, model)
+        return self._pipeline.run(state, ctx)
+
+
+_default_loop_context_compaction: LoopContextCompaction | None = None
+
+
+def default_loop_context_compaction() -> LoopContextCompaction:
+    """进程内单例门面（`factory` 节点调用）。"""
+    global _default_loop_context_compaction
+    if _default_loop_context_compaction is None:
+        _default_loop_context_compaction = LoopContextCompaction.with_default_pipeline()
+    return _default_loop_context_compaction
+
+
+__all__ = [
+    "LoopContextCompaction",
+    "default_loop_context_compaction",
+]

langchain_agentx/loop/context/message_utils.py

@@ -0,0 +1,56 @@
+"""
+LangChain 消息内容规范化与 token 粗估（供 `stages/*` 复用）。
+
+与 Claude Code 对齐：
+- CC 各紧凑阶段同样基于「字符 / token 近似」做预算；此处集中实现，避免五段内重复逻辑。
+
+设计要点：
+- 仅使用 `BaseMessage.content` 的公开形状（`str`、多模态 `list[dict|str]`），与 LangChain 一致；
+- `estimate_*` 为 **启发式**，与真实 tokenizer 有偏差，仅用于会话级预算与观测。
+
+注意：
+- 不 import 具体阶段；不依赖 LangGraph。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def stringify_content(content: Any) -> str:
+    """将 LangChain `Message.content` 规范为纯文本（多模态块取 text 段）。"""
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        for block in content:
+            if isinstance(block, str):
+                parts.append(block)
+            elif isinstance(block, dict):
+                if block.get("type") == "text":
+                    parts.append(str(block.get("text", "")))
+                else:
+                    parts.append(str(block))
+            else:
+                parts.append(str(block))
+        return "".join(parts)
+    return str(content)
+
+
+def estimate_tokens_from_chars(n_chars: int, num_chars_per_token: int) -> int:
+    if num_chars_per_token <= 0:
+        return n_chars
+    return (max(0, n_chars) + num_chars_per_token - 1) // num_chars_per_token
+
+
+def estimate_tokens_from_content(content: Any, num_chars_per_token: int) -> int:
+    return estimate_tokens_from_chars(len(stringify_content(content)), num_chars_per_token)
+
+
+def total_estimated_tokens_for_messages(messages: list[Any], num_chars_per_token: int) -> int:
+    total_chars = 0
+    for m in messages:
+        total_chars += len(stringify_content(getattr(m, "content", None)))
+    return estimate_tokens_from_chars(total_chars, num_chars_per_token)

langchain_agentx/loop/context/pipeline.py

@@ -0,0 +1,127 @@
+"""
+上下文压缩流水线编排（`ContextPipeline` + 默认 CC 五段装配）。
+
+与 Claude Code 对齐：
+- **仅** `query.ts` 中 `applyToolResultBudget` → snip → microcompact → collapse → autocompact 五段；
+- `DefaultCompactionStages.build()` 为顺序 SSOT，与 TS 侧 `messagesForQuery` 链一致。
+
+设计要点：
+- `ContextPipeline.run` 仅消费 `CompactionStage`；若最终 `messages` 列表引用被替换则返回补丁；
+- 可选 `settings=` 与自定义五段注入的 `CompactionSettings` 对齐；省略时用 `get_active_compaction_settings()`（与 `DefaultCompactionStages` 默认一致）；
+- 阶段 C：可选写入 `compaction_pipeline_meta`（token 告警档、各段 `tokens_freed`），供观测与 event 适配；
+- 门面 `LoopContextCompaction`（见 `compaction_service.py`）负责 `ContextCompactionContext` 装配与调用本类。
+
+注意：
+- 阶段若就地改消息且仍返回同一 list，当前实现**无法**检测变更；实现阶段请返回新 list。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..config.token_estimator import TokenEstimator
+from .blocking_guard import CompactionBlockingGuard
+from .settings import CompactionSettings, get_active_compaction_settings
+from .stages import (
+    AutocompactStage,
+    ContextCollapseStage,
+    MicrocompactStage,
+    SnipCompactStage,
+    ToolResultBudgetStage,
+)
+from .stages.base import CompactionStage
+from .types import ContextCompactionContext
+
+
+class DefaultCompactionStages:
+    """CC 五段默认装配（顺序即契约）。"""
+
+    @staticmethod
+    def build() -> tuple[CompactionStage, ...]:
+        return (
+            ToolResultBudgetStage(),
+            SnipCompactStage(),
+            MicrocompactStage(),
+            ContextCollapseStage(),
+            AutocompactStage(),
+        )
+
+
+class ContextPipeline:
+    """顺序执行 CC 五段。"""
+
+    def __init__(
+        self,
+        stages: tuple[CompactionStage, ...],
+        *,
+        settings: CompactionSettings | None = None,
+    ) -> None:
+        self._stages = stages
+        self._settings_override = settings
+
+    @classmethod
+    def with_default_stages(
+        cls,
+        settings: CompactionSettings | None = None,
+    ) -> ContextPipeline:
+        """使用 `DefaultCompactionStages` 构建管道。"""
+        return cls(DefaultCompactionStages.build(), settings=settings)
+
+    @property
+    def stages(self) -> tuple[CompactionStage, ...]:
+        return self._stages
+
+    def run(self, state: dict[str, Any], ctx: ContextCompactionContext) -> dict[str, Any]:
+        messages = state.get("messages")
+        if not isinstance(messages, list) or not messages:
+            return {}
+
+        s = self._settings_override or get_active_compaction_settings()
+        estimator = TokenEstimator(num_chars_per_token=s.num_chars_per_token)
+        original_input = list(messages)
+        current = original_input
+        guard = CompactionBlockingGuard(settings=s)
+        tw = guard.calculate_token_warning_state(original_input)
+        tokens_before = estimator.estimate_messages_tokens(original_input)
+        stages_meta: list[dict[str, Any]] = []
+        total_freed = 0
+
+        for stage in self._stages:
+            sr = stage.run(current, ctx)
+            total_freed += sr.tokens_freed
+            stages_meta.append(
+                {
+                    "name": stage.name,
+                    "tokens_freed": sr.tokens_freed,
+                    "extra": dict(sr.extra),
+                }
+            )
+            current = sr.messages
+            ctx.snip_tokens_freed_carry += sr.tokens_freed
+
+        patch: dict[str, Any] = {}
+        if current is not original_input:
+            patch["messages"] = current
+
+        tokens_after = estimator.estimate_messages_tokens(current)
+        if s.emit_compaction_pipeline_meta and (
+            "messages" in patch or total_freed > 0
+        ):
+            patch["compaction_pipeline_meta"] = {
+                "estimated_tokens_before": tokens_before,
+                "estimated_tokens_after": tokens_after,
+                "tokens_freed_sum": total_freed,
+                "snip_tokens_freed_carry_final": ctx.snip_tokens_freed_carry,
+                "token_warning_level": tw.level,
+                "stages": stages_meta,
+            }
+
+        if not patch:
+            return {}
+        return patch
+
+
+__all__ = [
+    "ContextPipeline",
+    "DefaultCompactionStages",
+]

langchain_agentx/loop/context/settings.py

@@ -0,0 +1,103 @@
+"""
+主循环上下文治理的 **策略与提示词**（单一配置对象，便于替换与单测）。
+
+与 Claude Code 对齐：
+- 数值与 `OPENCODE_*` 环境变量覆盖语义、会话摘要模板与 CC `messagesForQuery` 后续各阶段读取的阈值/提示一致方向；
+- 各 `CompactionStage` 实现应通过 `get_active_compaction_settings()` 读取，避免散落魔法数。
+
+设计要点：
+- `CompactionSettings` 为 `frozen` 值对象；可变绑定为模块级 `active_compaction_settings`，单测可 `set_active_compaction_settings(...)` 整体替换。
+
+注意：
+- 不依赖 LangGraph；与 `tool_runtime` 单条截断分工见设计文档。
+- 紧凑化提示词函数（如 `get_compact_prompt`）在 **`loop/prompt/compact.py`**，不在本模块再导出。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import FrozenSet
+
+from ..prompt.compact import AutocompactLlmPromptKind
+
+
+@dataclass(frozen=True)
+class CompactionSettings:
+    """CC 对齐上下文治理的默认策略（提示词 + 数值阈值）。"""
+
+    num_chars_per_token: int = 4
+    prune_protect_tokens: int = 40_000
+    prune_minimum_tokens: int = 20_000
+    prune_protected_tools: FrozenSet[str] = field(default_factory=lambda: frozenset({"skill"}))
+    default_max_context_tokens: int = 120_000
+    default_compress_trigger_fraction: float = 0.8
+    default_compress_keep_recent_messages: int = 8
+    # --- autocompact LLM 提示词（对齐 `compact.ts` + `prompt.ts`）---
+    # 摘要插在保留 tail 之前 → 默认 `partial_up_to`；全量折叠无尾窗时用 `full`；与 CC partial pivot「from」一致时用 `partial_from`。
+    autocompact_llm_prompt_kind: AutocompactLlmPromptKind = "partial_up_to"
+    # 追加到 CC 模板末尾的 Additional Instructions（对齐 hook merge 的 customInstructions）。
+    compact_custom_instructions: str | None = None
+    # 非 None 时跳过 builder，整段作为 compact 调用的指令（单测 / 完全自定义）。
+    autocompact_llm_instructions_override: str | None = None
+    # 兼容旧字段：未设置 override 时若此字段非空则优先于 builder（避免破坏只传 compaction_system_prompt 的调用方）。
+    compaction_system_prompt: str | None = None
+    # --- tool_result_budget（对齐 applyToolResultBudget：单条结果软上限）---
+    tool_result_max_chars_per_message: int = 48_000
+    tool_result_budget_suffix: str = field(
+        default="\n\n[... truncated by tool_result_budget ...]"
+    )
+    # --- snip_compact（对齐 snip：尾部保留 + 历史大块截断）---
+    snip_preserve_tail_messages: int = 10
+    snip_max_tool_content_chars: int = 12_288
+    snip_suffix: str = field(default="\n\n[... snipped by snip_compact ...]")
+    # --- microcompact（轻量规范化；递归压缩时跳过）---
+    microcompact_skip_query_sources: FrozenSet[str] = field(
+        default_factory=lambda: frozenset({"compact"})
+    )
+    # --- context_collapse（重复 tool 结果治理）---
+    collapse_dedupe_consecutive_same_tool_call_id: bool = True
+    # --- autocompact（阈值触发；产品与 CC 对齐默认走 LLM 摘要，无 model 时回退 prune）---
+    autocompact_skip_query_sources: FrozenSet[str] = field(
+        default_factory=lambda: frozenset({"compact"})
+    )
+    autocompact_use_llm_when_available: bool = True
+    autocompact_llm_excerpt_chars_per_message: int = 20_000
+    # --- snip carry → autocompact 阈值放宽（对齐 CC snipTokensFreed 计入阈值）---
+    # True：将本流水线已累计的 `snip_tokens_freed_carry` 加到触发阈值上，避免 snip 已释放后仍立刻 autocompact。
+    autocompact_snip_carry_threshold_slack: bool = True
+    # --- blocking / token 告警（对齐 CC calculateTokenWarningState 分档）---
+    compaction_token_warn_fraction: float = 0.85
+    compaction_block_compact_llm_fraction: float = 0.98
+    # 达到或超过视为「主上下文已顶满」，建议由调用方拦主模型（本守卫 `should_block`）。
+    compaction_block_main_model_fraction: float = 1.0
+    # True：`model` 节点在 `invoke` 前若 `should_block` 命中则不再调主模型，写入合成 AIMessage 并结束。
+    enable_main_model_context_token_block: bool = True
+    # --- tool transcript guard（对齐 CC `ensureToolResultPairing`：发往 LLM 前修复 tool 配对）---
+    # True：在绑定模型 `invoke/ainvoke` 前对 `messages` 做确定性修复（跨 assistant 去重 tool_call_id、
+    # 去重连续 ToolMessage、补 synthetic 等），降低提供商 400 与会话卡死风险；不依赖提示词。
+    enable_tool_transcript_repair_before_llm: bool = True
+    # --- 观测：写入 state.compaction_pipeline_meta（需 LoopAgentStateFields 含该键）---
+    emit_compaction_pipeline_meta: bool = True
+
+
+active_compaction_settings: CompactionSettings = CompactionSettings()
+
+
+def get_active_compaction_settings() -> CompactionSettings:
+    """返回当前生效的策略（默认即模块级 `active_compaction_settings`）。"""
+    return active_compaction_settings
+
+
+def set_active_compaction_settings(settings: CompactionSettings) -> None:
+    """替换全局策略（单测或进程级配置用）。"""
+    global active_compaction_settings
+    active_compaction_settings = settings
+
+
+__all__ = [
+    "AutocompactLlmPromptKind",
+    "CompactionSettings",
+    "active_compaction_settings",
+    "get_active_compaction_settings",
+    "set_active_compaction_settings",
+]

langchain_agentx/loop/context/stages/__init__.py

@@ -0,0 +1,29 @@
+"""
+上下文压缩流水线阶段实现包。
+
+与 Claude Code 对齐：
+- 本子包 **仅含 CC 五段**（`CompactionStage` 子类）及泛型 `NoOpCompactionStage`；Graph 入口见 `default_loop_context_compaction().run`（`compaction_service`）。
+
+注意：
+- 新增 CC 阶段请在此包或子模块实现 `CompactionStage`，并在 `pipeline` 中注册。
+"""
+
+from __future__ import annotations
+
+from .autocompact import AutocompactStage
+from .base import CompactionStage
+from .collapse import ContextCollapseStage
+from .microcompact import MicrocompactStage
+from .noop import NoOpCompactionStage
+from .snip import SnipCompactStage
+from .tool_result_budget import ToolResultBudgetStage
+
+__all__ = [
+    "AutocompactStage",
+    "CompactionStage",
+    "ContextCollapseStage",
+    "MicrocompactStage",
+    "NoOpCompactionStage",
+    "SnipCompactStage",
+    "ToolResultBudgetStage",
+]

langchain_agentx/loop/context/stages/autocompact.py

@@ -0,0 +1,140 @@
+"""
+Autocompact 阶段：超阈值时折叠前缀消息（对齐 CC `deps.autocompact` 的会话级收紧）。
+
+与 Claude Code 对齐：
+- 当估计 token 超过 `default_max_context_tokens * default_compress_trigger_fraction` 时，保留首部 `SystemMessage` 与尾部 `default_compress_keep_recent_messages` 条，中间以占位或（可选）LLM 摘要替换；
+- `ctx.snip_tokens_freed_carry` 已由 `ContextPipeline` 累加前置阶段释放量，可供后续扩展阈值修正（与 CC `snipTokensFreed` 同向）。
+
+设计要点：
+- 默认 `autocompact_use_llm_when_available=True`：超阈值且 `ctx.model` 可用、且 **未** 命中 `CompactionBlockingGuard.should_block_compact_llm` 时走 LLM；否则或无 model / `invoke` 失败则 **prune**；
+- `autocompact_snip_carry_threshold_slack`：将 `ctx.snip_tokens_freed_carry` 加到触发阈值（进入本阶段前由前四段累加），对齐 CC `snipTokensFreed` 阈值修正。
+- LLM 路径对齐 `compact.ts`：`messages` 先放待摘要摘录，**最后一条** `HumanMessage` 为完整 compact 指令（与 `summaryRequest` 同序）；指令由 `build_autocompact_llm_instruction_prompt` 按 `autocompact_llm_prompt_kind` 选择（默认 `partial_up_to`，与「摘要 + 保留 tail」一致），`compact_custom_instructions` 对应 CC `customInstructions`；`autocompact_llm_instructions_override` / 非空的 `compaction_system_prompt` 可覆盖 builder；
+- 模型输出经 `get_compact_user_summary_message(..., recent_messages_preserved=True)`（内部 `format_compact_summary`）写入 state，与 CC 续写包装一致。
+
+注意：
+- `query_source in autocompact_skip_query_sources`（如 `compact`）时跳过，防递归压缩。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.messages import HumanMessage, SystemMessage
+
+from ..blocking_guard import CompactionBlockingGuard
+from ..message_utils import stringify_content, total_estimated_tokens_for_messages
+from ...prompt.compact import build_autocompact_llm_instruction_prompt, get_compact_user_summary_message
+from ..settings import CompactionSettings, get_active_compaction_settings
+from ..types import ContextCompactionContext, StageResult
+from .base import CompactionStage
+
+
+class AutocompactStage(CompactionStage):
+    """CC 阶段 ⑤：autocompact（阈值折叠 / 可选 LLM 摘要）。"""
+
+    def __init__(self, settings: CompactionSettings | None = None) -> None:
+        self._settings_override = settings
+
+    def _effective_settings(self) -> CompactionSettings:
+        return self._settings_override or get_active_compaction_settings()
+
+    @property
+    def name(self) -> str:
+        return "autocompact"
+
+    def run(self, messages: list[Any], ctx: ContextCompactionContext) -> StageResult:
+        s = self._effective_settings()
+        if ctx.query_source in s.autocompact_skip_query_sources:
+            return StageResult(messages=messages, tokens_freed=0, extra={"autocompact_skipped": "query_source"})
+        total = total_estimated_tokens_for_messages(messages, s.num_chars_per_token)
+        threshold = int(s.default_max_context_tokens * s.default_compress_trigger_fraction)
+        slack = ctx.snip_tokens_freed_carry if s.autocompact_snip_carry_threshold_slack else 0
+        if total <= threshold + slack:
+            return StageResult(messages=messages, tokens_freed=0)
+
+        leading: list[Any] = []
+        idx = 0
+        while idx < len(messages) and isinstance(messages[idx], SystemMessage):
+            leading.append(messages[idx])
+            idx += 1
+        rest = messages[idx:]
+        k = max(1, s.default_compress_keep_recent_messages)
+        if len(rest) <= k:
+            return StageResult(messages=messages, tokens_freed=0)
+
+        head = rest[:-k]
+        tail = rest[-k:]
+
+        block_llm = CompactionBlockingGuard(settings=s).should_block_compact_llm(messages)
+        if (
+            s.autocompact_use_llm_when_available
+            and ctx.model is not None
+            and not block_llm
+        ):
+            summary = _invoke_summary(ctx.model, s, head)
+            if summary:
+                folded = leading + [
+                    HumanMessage(
+                        content=get_compact_user_summary_message(
+                            summary,
+                            recent_messages_preserved=True,
+                        )
+                    )
+                ] + tail
+                new_total = total_estimated_tokens_for_messages(folded, s.num_chars_per_token)
+                return StageResult(
+                    messages=folded,
+                    tokens_freed=max(0, total - new_total),
+                    extra={"autocompact_mode": "llm", "folded_messages": len(head)},
+                )
+
+        folded = leading + [
+            HumanMessage(
+                content=(
+                    f"[Context autocompacted: {len(head)} earlier messages omitted; "
+                    "details dropped for token budget.]"
+                )
+            )
+        ] + tail
+        new_total = total_estimated_tokens_for_messages(folded, s.num_chars_per_token)
+        mode = "prune_blocked_llm" if block_llm else "prune"
+        return StageResult(
+            messages=folded,
+            tokens_freed=max(0, total - new_total),
+            extra={"autocompact_mode": mode, "folded_messages": len(head)},
+        )
+
+
+def _resolve_autocompact_llm_instruction(s: CompactionSettings) -> str:
+    if s.autocompact_llm_instructions_override is not None:
+        return s.autocompact_llm_instructions_override
+    if s.compaction_system_prompt is not None and s.compaction_system_prompt.strip() != "":
+        return s.compaction_system_prompt
+    return build_autocompact_llm_instruction_prompt(
+        s.autocompact_llm_prompt_kind,
+        s.compact_custom_instructions,
+    )
+
+
+def _invoke_summary(model: Any, s: CompactionSettings, head: list[Any]) -> str | None:
+    cap = max(256, s.autocompact_llm_excerpt_chars_per_message)
+    parts: list[str] = []
+    for m in head:
+        label = getattr(m, "type", type(m).__name__)
+        chunk = stringify_content(getattr(m, "content", None))[:cap]
+        parts.append(f"{label}: {chunk}")
+    body = "\n\n---\n\n".join(parts)
+    excerpt_msg = HumanMessage(
+        content=(
+            "[Conversation excerpt to summarize — follows above chronology in thread]\n\n" + body
+        )
+    )
+    instruction = _resolve_autocompact_llm_instruction(s)
+    instruction_msg = HumanMessage(content=instruction)
+    # 与 CC `streamCompactSummary` 一致：history 在前，compact 指令为**最后一条** user 消息。
+    try:
+        resp = model.invoke([excerpt_msg, instruction_msg])
+    except Exception:
+        return None
+    text = stringify_content(getattr(resp, "content", None))
+    return text if text else None

langchain_agentx/loop/context/stages/base.py

@@ -0,0 +1,32 @@
+"""
+压缩流水线阶段抽象基类（CompactionStage）。
+
+与 Claude Code 对齐：
+- 对应 `query.ts` 中 `messagesForQuery` 上顺序执行的治理步骤；每步为可替换策略单元。
+
+设计要点：
+- 子类实现 `run(messages, ctx) -> StageResult`；CC 五段均在 `stages/` 内实现。
+
+注意：
+- 不依赖 LangGraph；仅处理消息列表与 ContextCompactionContext。
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ..types import ContextCompactionContext, StageResult
+
+
+class CompactionStage(ABC):
+    """上下文压缩流水线中的一步（CC queryLoop 阶段 ① 子步骤）。"""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """阶段名（观测 / 日志）。"""
+
+    @abstractmethod
+    def run(self, messages: list[Any], ctx: ContextCompactionContext) -> StageResult:
+        """输入当前消息列表，返回更新后的列表与可选 tokens_freed。"""

langchain_agentx/loop/context/stages/collapse.py

@@ -0,0 +1,76 @@
+"""
+Context collapse 阶段：合并连续重复 `tool_call_id` 的 `ToolMessage`（对齐 CC collapse 卫生语义子集）。
+
+与 Claude Code 对齐：
+- 对应 `applyCollapsesIfNeeded` 中「同一调用重复写回」类问题的治理：保留**最后一次**结果，去掉前置重复块，减少无意义重复 token。
+
+设计要点：
+- 仅处理**连续**且 `tool_call_id` 相同的 `ToolMessage`；不跨非 Tool 消息合并；
+- 可通过 `CompactionSettings.collapse_dedupe_consecutive_same_tool_call_id` 关闭。
+
+注意：
+- 不依赖 LangGraph；与 autocompact 分工：本阶段不生成会话摘要，仅结构化去重。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.messages import ToolMessage
+
+from ..message_utils import estimate_tokens_from_chars, stringify_content
+from ..settings import CompactionSettings, get_active_compaction_settings
+from ..types import ContextCompactionContext, StageResult
+from .base import CompactionStage
+
+
+class ContextCollapseStage(CompactionStage):
+    """CC 阶段 ④：context collapse（连续重复 tool 结果折叠）。"""
+
+    def __init__(self, settings: CompactionSettings | None = None) -> None:
+        self._settings_override = settings
+
+    def _effective_settings(self) -> CompactionSettings:
+        return self._settings_override or get_active_compaction_settings()
+
+    @property
+    def name(self) -> str:
+        return "context_collapse"
+
+    def run(self, messages: list[Any], ctx: ContextCompactionContext) -> StageResult:
+        _ = ctx
+        s = self._effective_settings()
+        if not s.collapse_dedupe_consecutive_same_tool_call_id or not messages:
+            return StageResult(messages=messages, tokens_freed=0)
+        out: list[Any] = []
+        i = 0
+        freed_chars = 0
+        dropped = 0
+        while i < len(messages):
+            m = messages[i]
+            if isinstance(m, ToolMessage):
+                j = i
+                tid = m.tool_call_id
+                while (
+                    j + 1 < len(messages)
+                    and isinstance(messages[j + 1], ToolMessage)
+                    and messages[j + 1].tool_call_id == tid
+                ):
+                    j += 1
+                # messages[i : j + 1] 同 id；保留最后一条，丢弃 i..j-1
+                if j > i:
+                    for k in range(i, j):
+                        freed_chars += len(stringify_content(messages[k].content))
+                        dropped += 1
+                    out.append(messages[j])
+                    i = j + 1
+                    continue
+            out.append(m)
+            i += 1
+        if len(out) == len(messages):
+            return StageResult(messages=messages, tokens_freed=0)
+        return StageResult(
+            messages=out,
+            tokens_freed=estimate_tokens_from_chars(freed_chars, s.num_chars_per_token),
+            extra={"collapse_dropped_tool_messages": dropped},
+        )