@baimingtao/lbs-agent 1.0.0

package/runtime/orchestration/loop/main_loop.py

@@ -0,0 +1,2014 @@
+"""
+Agent Loop — 真正的自循环引擎。
+
+核心循环：
+  接收任务
+    → LLM 推理（带工具 schema）
+      → LLM 返回 tool_calls？
+        → YES: 执行工具 → 把结果回灌 → 继续循环
+        → NO:  验证是否完成 → 完成就返回，没完成继续问
+
+这个循环不需要人干预。Agent 自己决定调什么工具、什么时候算完成。
+
+就像一个真正能干活的员工：
+  你给任务 → 它自己读文件、查资料、写代码、跑测试 → 给你最终结果
+  而不是每干一步就回来问你"下一步干啥"
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import time
+import uuid
+from queue import Queue, Empty
+from threading import Event
+from typing import Any, Callable, Optional
+
+from runtime.orchestration.tool_guardrails import ToolCallGuardrailController, toolguard_synthetic_result
+from runtime.core.llm.client import LLMClient, CompletionResult, ToolCallRequest
+from tools.tool.registry import ToolRegistry
+from runtime.context.management.context_manager import ContextManager
+from runtime.orchestration.verification import ToolResultVerifier
+from runtime.orchestration.loop.run_trace import LoopPhase, LoopTransition, RunTraceEvent
+from runtime.orchestration.runtime.events import RuntimeEvent, RuntimeEventBus
+
+# 数据类型从 types.py 导入（2026-07-16 从 main_loop.py 抽出）
+from runtime.orchestration.loop.progress_tracker import ProgressTracker
+from runtime.orchestration.loop.types import (
+    AgentStatus, ToolExec, ModelAttempt, LoopStep, AgentResult, AgentConfig,
+)
+from runtime.core.llm.error_classifier import classify_api_error, compute_backoff, classify_and_backoff, FailoverReason
+
+logger = logging.getLogger(__name__)
+
+
+# ═══════════════════════════════════════════════════
+# Agent Loop 核心引擎
+# ═══════════════════════════════════════════════════
+
+class AgentLoop:
+    """
+    真正的自循环 Agent 引擎。
+
+    用法：
+        config = AgentConfig(name="code", system_prompt="...", ...)
+        loop = AgentLoop(config, llm_client)
+        result = loop.run("重构 utils.py 里的 parse 函数")
+
+    result.success 告诉你成功没有
+    result.content 是最终输出
+    result.steps 是完整的执行轨迹
+    """
+
+    def __init__(
+        self,
+        config: AgentConfig,
+        llm_client=None,
+        agent_id: str = "",
+        tool_call_executor=None,
+        context_window=None,
+        message_history=None,
+        completion_gate=None,
+    ):
+        self.config = config
+        self.llm = llm_client  # 可能是 None（如果用 model_router）
+        self.agent_id = agent_id or f"agent-{uuid.uuid4().hex[:8]}"
+        self._current_model = config.model  # 当前使用的模型
+
+        self.status = AgentStatus.IDLE
+        if message_history is None:
+            message_history = config.message_history
+        if message_history is None:
+            from runtime.orchestration.loop.message_history import MessageHistory
+
+            message_history = MessageHistory(config.api_mode)
+        self.message_history = message_history
+        self.steps: list[LoopStep] = []
+        self.current_iteration = 0
+        self.start_time = 0.0
+        self._tool_call_count = 0
+        self._last_verification_error = ""
+        self._stall_count = 0
+        self._last_progress_signature = ""
+        self.progress_tracker = ProgressTracker(stall_threshold=getattr(config, 'stall_limit', 2))
+        self._retry_depth = 0  # P0-1: 递归重试深度保护，防止栈溢出
+        self._max_retry_depth = max(getattr(config, 'max_retry_attempts', 3) or 3, 3) + 2
+        self._last_assessment = None  # A1: 最近一次 stall 评估结果
+        self.model_attempts: list[ModelAttempt] = []
+        self.run_trace: list[RunTraceEvent] = []
+        self.compression_results: list[dict[str, Any]] = []
+        self.event_bus = config.event_bus or RuntimeEventBus()
+        self.run_id = ""
+        self._done_event = Event()
+        self._async_result = None
+        self._run_thread = None
+
+        # 通信
+        self.message_queue: Queue[str] = Queue()
+        self.cancel_event = Event()
+
+        if context_window is None:
+            context_window = config.context_window
+        if context_window is None:
+            from runtime.orchestration.loop.context_window import ContextWindow
+
+            context_window = ContextWindow.from_config(config, llm_client=llm_client)
+        self.context_window = context_window
+        self.context_manager = context_window.manager
+        self.context_memory = getattr(config, "context_memory", None)
+        if self.context_memory is None:
+            from runtime.memory.context_memory import ContextMemory
+            from runtime.memory.session.identity import ConversationIdentity
+            self.context_memory = ContextMemory(
+                ConversationIdentity.create(session_id=getattr(config, "session_id", "")),
+                self.message_history,
+                context_window,
+            )
+
+        # Memory 接入（优先使用 MemoryManager，回退兼容旧 inline 模式）
+        self.memory_manager = config.memory_manager
+        self.working_memory = config.working_memory
+        self.long_term_memory = config.long_term_memory
+
+        # Tracer — 可观测性
+        from runtime.orchestration.tracer import AgentTracer
+        self.tracer = AgentTracer(agent_name=self.config.name)
+
+        # RetryEngine — 弹性执行
+        from runtime.orchestration.retry_engine import RetryEngine
+        self.retry_engine = RetryEngine(
+            max_retries=config.max_retry_attempts or 3,
+            base_delay=config.retry_delay or 2.0,
+            circuit_threshold=5,
+            circuit_recovery=30.0,
+        )
+        self.tool_result_verifier = ToolResultVerifier()
+        self.guardrail_controller = ToolCallGuardrailController()
+        if tool_call_executor is None:
+            from runtime.orchestration.loop.tool_call_executor import ToolCallExecutor
+            tool_call_executor = ToolCallExecutor(config.tool_runtime, self.tool_result_verifier)
+        self.tool_call_executor = tool_call_executor
+        if completion_gate is None:
+            completion_gate = config.completion_gate
+        if completion_gate is None:
+            from runtime.orchestration.loop.completion_gate import CompletionGate
+            completion_gate = CompletionGate()
+        self.completion_gate = completion_gate
+
+        # 回调（给监控/UI 用）
+        self.on_step: Optional[Callable[[LoopStep], None]] = None
+        self.on_status_change: Optional[Callable[[AgentStatus], None]] = None
+
+    def _context_messages_for_llm(self) -> list[dict[str, Any]]:
+        """调用上下文 facade；测试/旧 seam 未配置时回退原始消息。"""
+        try:
+            return self.context_memory.build_llm_messages()
+        except Exception:
+            return self.messages
+
+    @property
+    def messages(self) -> list[dict[str, Any]]:
+        return self.message_history.messages
+
+    @messages.setter
+    def messages(self, value: list[dict[str, Any]]) -> None:
+        self.message_history.replace(value)
+
+    # ── 公共生命周期（P1-6: 统一 ReAct/Reactive 入口） ──────────
+
+    def _init_loop(self, task: str, context: str, mode: str) -> str:
+        """统一循环初始化：状态、事件、memory、tools schema、进度输出。
+
+        被 run() 和 run_react() 共用，消除重复。
+        Returns: tools_schema（供后续迭代使用）
+        """
+        self.start_time = time.time()
+        if not getattr(self, "_resume_active", False):
+            self.run_trace = []
+            self.compression_results = []
+        try:
+            if hasattr(self.context_window, "on_session_reset"):
+                self.context_window.on_session_reset()
+        except Exception:
+            pass
+        self.context_manager.on_session_reset() if hasattr(self.context_manager, "on_session_reset") else None
+        self.event_bus = self.config.event_bus or RuntimeEventBus()
+        self._publish_runtime_event("loop.started", task_preview=task[:200], mode=mode)
+        self._set_status(AgentStatus.RUNNING)
+        if not getattr(self, "_resume_active", False):
+            self.current_iteration = 0
+        self._resume_active = False
+        self._current_task = task
+        self._trace(LoopPhase.START, LoopTransition.STARTED, "loop started", {"mode": mode})
+
+        # 重置 ProgressTracker
+        self.progress_tracker.reset()
+
+        # P1-3: 如果 message_history 已有消息（来自 session 历史恢复），
+        # 不再重复注入完整 _build_initial_message，只用简短续接消息
+        has_history = bool(self.message_history.messages)
+
+        if has_history:
+            # 已有历史：只拼续接消息，不重复注入 tool_guidance / react_guidance / verification
+            # 明确告知模型这是续接对话，请结合历史 message 回答
+            parts = [f"## 续接对话\n用户在历史会话基础上提出了新的问题/指令：{task}"]
+            if context:
+                parts.append(f"\n--- 附带上下文 ---\n{context}")
+            parts.append("\n\n（会话完整历史在以上 messages 中，请结合历史延续回答，不要重复已确认的信息。）")
+            user_content = "".join(parts)
+            self.message_history.append_user(user_content)
+        else:
+            # 无历史：全量初始消息
+            user_content = self._build_initial_message(task, context)
+            if mode == "react":
+                user_content += self._build_react_guidance()
+            if self.memory_manager:
+                ctx_block = self._ensure_memory().prepare_context(task)
+                if ctx_block:
+                    user_content += "\n\n" + ctx_block
+                self._ensure_memory().store("current_task", task, tags=["task", "active"])
+                self._ensure_memory().store("start_time", self.start_time)
+                self._ensure_memory().on_turn_start(task)
+            else:
+                memory_context = ""
+                if self.long_term_memory:
+                    try:
+                        records = self.long_term_memory.search(agent_name=self.config.name, query=task[:100], limit=3)
+                        if records:
+                            memory_parts = [f"[{r.key}] {r.value[:200]}" for r in records]
+                            memory_context = "\n--- 相关记忆 ---\n" + "\n".join(memory_parts)
+                    except Exception:
+                        pass
+                if memory_context:
+                    user_content += "\n" + memory_context
+                if self.working_memory:
+                    self.working_memory.set("current_task", task, tags=["task", "active"])
+                    self.working_memory.set("start_time", self.start_time)
+            self.message_history.append_user(user_content)
+
+        tools_schema = self._build_tools_schema()
+
+        logger.info("[%s] loop started (%s): %s", self.config.name, mode, task[:100])
+        if self.config.report_progress:
+            label = f"{self.config.display_name or self.config.name}"
+            if mode == "react":
+                label += " [ReAct]"
+            self._print(f"\n{'='*60}")
+            self._print(f"Agent: {label}")
+            chain = [self.config.model] + self.config.fallback_models
+            self._print(f"Model: {' -> '.join(chain)}")
+            self._print(f"Tools: {self.config.tools or '(none)'}")
+            self._print(f"Task:  {task[:200]}")
+            self._print(f"{'='*60}\n")
+
+        return tools_schema
+
+    def _check_loop_limits(self) -> AgentResult | None:
+        """统一检查循环终止条件：cancel / timeout。
+
+        被 run() 和 run_react() 共用。
+        Returns: AgentResult 如果需要终止，None 如果可以继续。
+        """
+        if self.cancel_event.is_set():
+            return self._finish(False, "cancelled", "被取消", status=AgentStatus.CANCELLED)
+        elapsed = time.time() - self.start_time
+        if elapsed > self.config.timeout:
+            return self._finish(False, "timeout", f"超时 {self.config.timeout}s", status=AgentStatus.TIMEOUT)
+        return None
+
+    def _check_budget_limits(self) -> AgentResult | None:
+        """P3-2: 检查工具调用数和费用上限。
+
+        Returns: AgentResult 如果超限需要终止，None 如果可以继续。
+        """
+        # 工具调用数限制
+        max_tc = getattr(self.config, 'max_tool_calls', 0)
+        if max_tc > 0 and self._tool_call_count >= max_tc:
+            return self._finish(
+                False, "max_tool_calls",
+                f"达到工具调用上限 {max_tc} 次。",
+                status=AgentStatus.BUDGET_EXCEEDED,
+            )
+        # 费用限制（P2-7: 改用 usage_pricing 精确费率，不再用硬编码费率）
+        max_cost = getattr(self.config, 'max_cost_usd', 0.0)
+        if max_cost > 0:
+            try:
+                from runtime.core.llm.usage_pricing import CanonicalUsage, estimate_usage_cost
+                from decimal import Decimal
+                total_cost = Decimal("0")
+                for ma in self.model_attempts:
+                    cost = estimate_usage_cost(
+                        CanonicalUsage(
+                            input_tokens=getattr(ma, 'input_tokens', 0),
+                            output_tokens=getattr(ma, 'output_tokens', 0),
+                        ),
+                        ma.model or self.config.model,
+                    )
+                    if cost.amount_usd is not None:
+                        total_cost += cost.amount_usd
+                if total_cost >= Decimal(str(max_cost)):
+                    return self._finish(
+                        False, "max_cost",
+                        f"达到费用上限 ${max_cost:.4f}（当前 ${total_cost:.4f}）。",
+                        status=AgentStatus.BUDGET_EXCEEDED,
+                    )
+            except Exception:
+                pass
+        return None
+
+    # ── 公开接口 ───────────────────────────────────
+
+    def run(self, task: str, context: str = "") -> AgentResult:
+        """运行 Agent 自循环。给任务，返回最终结果。
+
+        根据 config.enable_planning 选择循环模式：
+          True  → run_react()（Plan-Act-Reflect 循环）
+          False → 反应式循环（LLM 走一步看一步）
+        """
+        if getattr(self.config, 'enable_planning', False) and self.config.tools:
+            return self.run_react(task, context)
+        tools_schema = self._init_loop(task, context, mode="reactive")
+
+        try:
+            while self.current_iteration < self.config.max_iterations:
+                limit_result = self._check_loop_limits()
+                if limit_result is not None:
+                    return limit_result
+
+                budget_result = self._check_budget_limits()
+                if budget_result is not None:
+                    return budget_result
+
+                self.current_iteration += 1
+                self._trace(LoopPhase.ITERATION, LoopTransition.ITERATION_START, "iteration started", {
+                    "task_preview": self._current_task[:240],
+                    "known_message_count": len(self.messages),
+                    "tool_count": len(tools_schema or []),
+                })
+                self._trace(LoopPhase.CONTEXT_PREFLIGHT, LoopTransition.STARTED, "context preflight")
+                self._safe_compress()
+                step = self._run_one_iteration(tools_schema)
+                self.steps.append(step)
+                if self.on_step:
+                    self.on_step(step)
+
+                stall_reason = self._detect_stall(step)
+                if stall_reason:
+                    if self._stall_count >= self.config.stall_limit:
+                        return self._finish(False, "stalled", stall_reason, status=AgentStatus.STALLED)
+                    # A2: 注入已知信息摘要
+                    known_info = self._build_known_info_summary()
+                    stall_msg = (
+                        "[运行时防空转] " + stall_reason + "\n"
+                        "请立刻改变策略：若任务要求读取/搜索/执行，必须调用对应工具并基于工具结果回答；"
+                        "不要继续重复计划、todo 或空泛说明。"
+                    )
+                    if known_info:
+                        stall_msg += f"\n\n{known_info}\n如果你已有足够信息，请直接给出最终回答。"
+                    self.message_history.append_user(stall_msg)
+                    continue
+
+                # 如果这一轮没有 tool_calls，说明 LLM 认为可以回答了
+                if not step.tool_execs:
+                    # 验证是否真的完成了
+                    if self._verify(step.llm_content):
+                        self._trace(LoopPhase.VERIFICATION, LoopTransition.PASSED, "completion verified")
+                        return self._finish(True, "", step.llm_content)
+                    else:
+                        self._trace(LoopPhase.VERIFICATION, LoopTransition.FAILED, "completion rejected", {"error": self._last_verification_error})
+                        # 没通过验证，push 一条消息让 LLM 继续
+                        self.message_history.append_user("你的回答不满足完成标准。请继续工作直到满足所有验证条件。")
+
+            failure_reason = self._last_verification_error or "max_iterations"
+            return self._finish(
+                False, failure_reason,
+                f"达到最大迭代 {self.config.max_iterations} 次仍未完成。"
+                f"最后一次输出: {(self.steps[-1].llm_content if self.steps else '')[:500]}",
+                status=AgentStatus.BUDGET_EXCEEDED,
+            )
+
+        except Exception as e:
+            if hasattr(self, '_escalation_msg') and self._escalation_msg:
+                logger.warning("[%s] escalated: %s", self.config.name, self._escalation_msg)
+                return self._finish(False, f"escalated: {e}", str(self._escalation_msg))
+            # RetryEngine 处理：不是所有崩溃直接返回，尝试退避
+            try:
+                decision = self.retry_engine.decide_on_exception(
+                    self.retry_engine.stats.total_attempts + 1, e,
+                    model=self._current_model or "",
+                )
+                self.tracer.on_retry(reason=decision.reason, attempt=decision.attempt, delay=decision.delay, fallback=decision.fallback, degrade=decision.degrade)
+                if decision.retry:
+                    import time as _rt
+                    logger.warning("[%s] loop retrying: %s (delay=%.1f)", self.config.name, decision.message, decision.delay)
+                    self._print(f"  [RETRY] {decision.message}")
+                    if decision.compress:
+                        # 压缩上下文后重试
+                        try:
+                            self._safe_compress()
+                        except Exception:
+                            pass
+                    if decision.delay > 0:
+                        _rt.sleep(min(decision.delay, 10.0))
+                    if self._retry_depth >= self._max_retry_depth:
+                        return self._finish(False, "max_retry_depth", f"递归重试达上限 {self._max_retry_depth} 次。")
+                    self._retry_depth += 1
+                    return self.run(self._current_task)  # 递归重试（有限深度）
+                if decision.fallback:
+                    logger.warning("[%s] loop fallback: %s", self.config.name, decision.message)
+                    self._print(f"  [FALLBACK] {decision.message}")
+                    if self.config.fallback_models:
+                        # 切 fallback model
+                        self._current_model = self.config.fallback_models[0]
+                    if self._retry_depth >= self._max_retry_depth:
+                        return self._finish(False, "max_retry_depth", f"递归重试达上限 {self._max_retry_depth} 次。")
+                    self._retry_depth += 1
+                    return self.run(self._current_task)
+                if decision.degrade:
+                    logger.warning("[%s] loop degrade: %s", self.config.name, decision.message)
+                    self._print(f"  [DEGRADE] {decision.message}")
+                    return self._finish(False, f"degraded: {e}", str(decision.message))
+            except Exception as _retry_err:
+                logger.exception("[%s] retry handler crashed", self.config.name)
+            logger.exception("[%s] loop crashed", self.config.name)
+            return self._finish(False, "crash", str(e))
+
+
+
+    # ═══════════════════════════════════════════════════════════
+    # Plan-Act-Reflect 循环
+    # ═══════════════════════════════════════════════════════════
+
+    def run_react(self, task: str, context: str = "") -> AgentResult:
+        """Plan-Act-Reflect 循环。
+
+        和 run()（反应式）的区别：
+          run()      = LLM 走一步看一步，每轮自己决定调什么工具
+          run_react() = 先让 LLM 做全局计划，执行后反思，再调整计划
+
+        循环结构：
+          PLAN    → LLM 分析任务 + 已有信息，输出当前最优的下一步行动
+          ACT     → 如果计划包含工具调用，执行工具
+          REFLECT → 评估结果，决定：完成？继续？修改计划？
+        """
+        tools_schema = self._init_loop(task, context, mode="react")
+
+        # 执行轨迹
+        self._react_phases: list[dict] = []  # 记录每轮的 plan/act/reflect
+
+        try:
+            while self.current_iteration < self.config.max_iterations:
+                limit_result = self._check_loop_limits()
+                if limit_result is not None:
+                    return limit_result
+
+                budget_result = self._check_budget_limits()
+                if budget_result is not None:
+                    return budget_result
+
+                self.current_iteration += 1
+                self._trace(LoopPhase.ITERATION, LoopTransition.ITERATION_START, "iteration started", {
+                    "task_preview": self._current_task[:240],
+                    "known_message_count": len(self.messages),
+                    "tool_count": len(tools_schema or []),
+                })
+                self._trace(LoopPhase.CONTEXT_PREFLIGHT, LoopTransition.STARTED, "context preflight")
+                self._safe_compress()
+
+                # ── Phase 1+2+3 合并为一轮 LLM 调用 ──
+                # 让 LLM 在一轮里输出：思考(PLAN) + 行动(ACT) + 评估(REFLECT)
+                # 这样比分3次调用更高效，也符合 ReAct 论文的核心思想
+                step = self._run_react_iteration(tools_schema)
+                self.steps.append(step)
+                if self.on_step:
+                    self.on_step(step)
+
+                # stall 检测
+                stall_reason = self._detect_stall(step)
+                if stall_reason:
+                    if self._stall_count >= self.config.stall_limit:
+                        return self._finish(False, "stalled", stall_reason, status=AgentStatus.STALLED)
+                    self.message_history.append_user(
+                        "[反思：检测到空转] " + stall_reason + "\n"
+                        "请重新规划：分析当前状态，制定不同的行动方案。"
+                    )
+                    continue
+
+                # 如果这一轮没有工具调用，说明 LLM 认为可以回答了
+                if not step.tool_execs:
+                    decision = self._decide_completion(step.llm_content, enforce_react_actions=True)
+                    if decision.passed and self.current_iteration < self.config.max_iterations:
+                        self._trace(LoopPhase.VERIFICATION, LoopTransition.PASSED, "completion verified")
+                        return self._finish(True, "", step.llm_content)
+                    self._trace(LoopPhase.VERIFICATION, LoopTransition.FAILED, "completion rejected", {"error": self._last_verification_error, "task_incomplete": bool(decision.task_incomplete)})
+                    if decision.task_incomplete:
+                        self._print(f"  [REFLECT: 任务未完成] Agent 输出了文字但没有执行完所有步骤")
+                        self.message_history.append_user(
+                            "[任务未完成] 你输出了计划但没有执行。\n"
+                            "你的任务里还有步骤没完成。\n"
+                            "不要描述下一步该做什么——直接调用工具去做。\n"
+                            f"已完成的工具调用: {self._tool_call_count} 次。\n"
+                            f"剩余迭代: {self.config.max_iterations - self.current_iteration} 轮。"
+                        )
+                        continue
+                    self.message_history.append_user(
+                        "[反思：验证未通过] " + self._last_verification_error + "\n"
+                        "请重新评估任务完成情况，补充缺失的内容。"
+                    )
+
+            failure_reason = self._last_verification_error or "max_iterations"
+            return self._finish(
+                False, failure_reason,
+                f"达到最大迭代 {self.config.max_iterations} 次仍未完成。"
+                f"最后一次输出: {(self.steps[-1].llm_content if self.steps else '')[:500]}",
+                status=AgentStatus.BUDGET_EXCEEDED,
+            )
+
+        except Exception as e:
+            if hasattr(self, '_escalation_msg') and self._escalation_msg:
+                return self._finish(False, f"escalated: {e}", str(self._escalation_msg))
+            # RetryEngine 处理
+            try:
+                decision = self.retry_engine.decide_on_exception(
+                    self.retry_engine.stats.total_attempts + 1, e,
+                    model=self._current_model or "",
+                )
+                self.tracer.on_retry(reason=decision.reason, attempt=decision.attempt, delay=decision.delay, fallback=decision.fallback, degrade=decision.degrade)
+                if decision.retry:
+                    import time as _rt
+                    logger.warning("[%s] react loop retry: %s (delay=%.1f)", self.config.name, decision.message, decision.delay)
+                    self._print(f"  [RETRY] {decision.message}")
+                    if decision.compress:
+                        try:
+                            self._safe_compress()
+                        except Exception:
+                            pass
+                    if decision.delay > 0:
+                        _rt.sleep(min(decision.delay, 10.0))
+                    if self._retry_depth >= self._max_retry_depth:
+                        return self._finish(False, "max_retry_depth", f"递归重试达上限 {self._max_retry_depth} 次。")
+                    self._retry_depth += 1
+                    return self.run_react(self._current_task)
+                if decision.fallback:
+                    logger.warning("[%s] react loop fallback: %s", self.config.name, decision.message)
+                    self._print(f"  [FALLBACK] {decision.message}")
+                    if self.config.fallback_models:
+                        self._current_model = self.config.fallback_models[0]
+                    if self._retry_depth >= self._max_retry_depth:
+                        return self._finish(False, "max_retry_depth", f"递归重试达上限 {self._max_retry_depth} 次。")
+                    self._retry_depth += 1
+                    return self.run_react(self._current_task)
+                if decision.degrade:
+                    self._print(f"  [DEGRADE] {decision.message}")
+                    return self._finish(False, f"degraded: {e}", str(decision.message))
+            except Exception as _retry_err:
+                logger.exception("[%s] retry handler crashed in react", self.config.name)
+            import traceback as _tb
+            err_detail = f"{type(e).__name__}: {e}"
+            logger.exception("[%s] react loop crashed: %s", self.config.name, err_detail)
+            self._print(f"  [CRASH] {err_detail}")
+            return self._finish(False, err_detail, str(e))
+
+
+
+    def _build_react_guidance(self) -> str:
+        """构造 Plan-Act-Reflect 框架引导，注入到初始消息尾部。"""
+        return (
+
+            "\n\n--- 工作方式 ---\n"
+            "你采用 Plan-Act-Reflect 循环工作：\n"
+            "1. PLAN：分析任务和当前已知信息，决定下一步做什么、用什么工具。\n"
+            "2. ACT：执行行动（调用工具或推理）。\n"
+            "3. REFLECT：评估结果——任务完成了吗？需要改变策略吗？\n"
+            "\n"
+            "每轮迭代中：\n"
+            "- 如果需要信息，先调用工具获取，不要猜测。\n"
+            "- 拿到工具结果后，评估是否足够回答任务。\n"
+            "- 如果不够，规划下一步获取什么信息。\n"
+            "- 如果足够，给出最终回答。\n"
+            "- 不要重复调用相同工具获取相同信息。"
+        )
+
+    def _run_react_iteration(self, tools_schema: list[dict] | None) -> LoopStep:
+        """执行一轮 ReAct 循环。
+
+        和 _run_one_iteration 的区别：
+          - 在 LLM 调用前，注入"当前已知信息"摘要（降低 LLM 重复调工具的概率）
+          - 工具执行后，自动注入反思提示
+        """
+        step = LoopStep(iteration=self.current_iteration, timestamp=time.time())
+
+        # 检查主 agent 发来的消息
+        incoming = self._check_messages()
+        if incoming:
+            self.message_history.append_user(f"[主Agent消息] {incoming}")
+
+        self._set_status(AgentStatus.RUNNING)
+        self._print(f"\n--- 迭代 {self.current_iteration} (ReAct) ---")
+
+        # ── LLM 调用 ──
+        try:
+            # HTTP SSE 解析器已正确处理 anthropic_messages 的 text/tool_use/thinking，
+            # 不再需要降级为非流式（之前的限制是因为旧 SDK get_final_message 抛 IndexError）。
+            use_stream = getattr(self.config, 'enable_streaming', False)
+
+            self._trace(LoopPhase.LLM_CALL, LoopTransition.LLM_REQUEST, "calling llm", {"stream": bool(use_stream)})
+            self._publish_runtime_event(
+                "llm.request",
+                model=self._current_model,
+                stream=bool(use_stream),
+                task_preview=getattr(self, "_current_task", "")[:240],
+                tool_count=len(tools_schema or []),
+            )
+            if use_stream:
+                response, used_model = self._call_llm_stream(tools_schema)
+            else:
+                response, used_model = self._call_llm(tools_schema)
+            self._trace(LoopPhase.LLM_CALL, LoopTransition.LLM_RESPONSE, "llm response", {"model": used_model, "finish_reason": response.finish_reason, "tool_calls": len(response.tool_calls or [])})
+            self._publish_runtime_event("llm.response", model=used_model, finish_reason=response.finish_reason, tool_calls=len(response.tool_calls or []))
+            self._current_model = used_model
+            step.model = used_model
+            self._consecutive_llm_errors = 0
+        except Exception as e:
+            err_str = str(e)
+            step.summary = f"LLM 错误: {e}"
+            step.finish_reason = "error"
+            self._print(f"  [LLM ERROR] {e}")
+            self._consecutive_llm_errors = getattr(self, '_consecutive_llm_errors', 0) + 1
+            should_retry, delay, reason_str, classified = classify_and_backoff(
+                self._consecutive_llm_errors, err_str,
+                strategy=self.config.error_strategy,
+                max_retries=self.config.max_retries,
+                base_delay=self.config.retry_delay,
+                provider=getattr(self.config, 'provider', ''),
+                model=getattr(self.config, 'model_name', ''),
+            )
+            self._print(f"  [{getattr(classified.reason, 'value', classified.reason).upper()}] {reason_str}")
+            if should_retry:
+                if delay > 0:
+                    time.sleep(delay)
+                if classified.should_compress:
+                    self._compress_context()
+                return step
+            if self.config.error_strategy == "continue":
+                step.llm_content = f"[本轮流过错误被跳过: {err_str[:200]}]"
+                step.finish_reason = "error_continue"
+                return step
+            self._escalation_msg = f"Agent {self.config.name} 不可恢复错误: {err_str}"
+            raise
+
+        step.llm_content = response.content
+        step.finish_reason = response.finish_reason
+        if response.content:
+            self._print(f"  [思考] {response.content[:300]}")
+
+        # 严格 sequential：先登记完整计划，再只执行一个 tool，结果立即进入下一轮。
+        all_tool_calls = list(response.tool_calls or [])
+        if all_tool_calls:
+            self.context_memory.register_pending_tool_calls(all_tool_calls)
+        tool_calls = all_tool_calls
+        if self.config.tool_execution_mode == "sequential":
+            tool_calls = tool_calls[: max(1, self.config.max_tool_calls_per_turn)]
+            response.tool_calls = tool_calls
+        self._append_assistant_message(response)
+
+        if not tool_calls:
+            step.summary = f"[REFLECT] 文本回复 (finish={response.finish_reason})"
+            return step
+        self._set_status(AgentStatus.WAITING_TOOL)
+        for tc in tool_calls:
+            # Guardrail 检查：工具是否在 agent 的允许列表中
+            if self.config.tools and tc.name not in self.config.tools and tc.name not in ('todo',):
+                reason = f"工具 {tc.name} 不在允许列表 {self.config.tools} 中"
+                self._print(f"  [GUARDRAIL] 拒绝 {tc.name}：不在允许工具列表中")
+                exec_record = self._guardrail_denied_exec(tc, reason)
+                step.tool_execs.append(exec_record)
+                self._append_tool_result(tc, exec_record)
+                continue
+
+            # Guardrail 检查：写操作是否被禁止
+            # 细化：只拦截对已有代码/配置的修改，允许新建报告类文件
+            # code agent 本身就是写代码的，其 guardrail 规则只通过 system prompt 提示，
+            # 不在 runtime 层拦截 write_file/patch。
+            is_code_agent = self.config.name in ('code', 'coder')
+            is_write_tool = tc.name in ('write_file', 'patch', 'terminal')
+            if is_write_tool and not is_code_agent:
+                # 检查目标文件是否是代码/配置
+                target_path = str(tc.arguments.get('path', ''))
+                _target_lower = target_path.lower().replace('\\', '/').split('/')[-1]
+                is_code_or_config = (
+                    any(target_path.endswith(ext) for ext in
+                        ('.py', '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
+                         '.java', '.kt', '.go', '.rs', '.c', '.cpp', '.h', '.hpp',
+                         '.rb', '.php', '.swift', '.vue', '.svelte', '.scss', '.less',
+                         '.yaml', '.yml', '.json', '.toml', '.ini', '.cfg',
+                         '.xml', '.sql', '.sh', '.bat', '.ps1'))
+                    or _target_lower.startswith('.env')
+                    or _target_lower in (
+                        'dockerfile', '.gitignore', 'makefile', 'cmakelists.txt')
+                    or _target_lower.startswith('dockerfile.')
+                )
+                # 报告/文档类文件不拦截
+                is_report = any(target_path.endswith(ext) for ext in
+                    ('.txt', '.md', '.html', '.htm', '.csv', '.log', '.rst'))
+                # 如果是修改已有文件（不是新建），也拦截
+                import os as _os_guard
+                _project_root = _os_guard.path.dirname(_os_guard.path.dirname(_os_guard.path.dirname(_os_guard.path.abspath(__file__))))
+                target_exists = _os_guard.path.exists(_os_guard.path.join(_project_root, target_path)) if target_path else False
+                modifying_existing_code = is_code_or_config and target_exists
+
+                is_denied = any('禁止' in g and ('写' in g or '修改' in g or '执行' in g)
+                                for g in (self.config.guardrails or []))
+                # 拦截条件：有禁止规则 + 是写工具 + (目标是对代码/配置 或 不是报告文件)
+                should_block = is_denied and (modifying_existing_code or (not is_report and is_code_or_config))
+                if should_block:
+                    matching_rules = [g for g in (self.config.guardrails or []) if '禁止' in g and ('写' in g or '修改' in g or '执行' in g)]
+                    reason = matching_rules[0]
+                    self._print(f"  [GUARDRAIL] 拒绝 {tc.name}：{reason} (target={target_path})")
+                    exec_record = self._guardrail_denied_exec(tc, reason, target=target_path)
+                    step.tool_execs.append(exec_record)
+                    self._append_tool_result(tc, exec_record)
+                    continue
+
+            self._print(f"  [行动] {tc.name}({json.dumps(tc.arguments, ensure_ascii=False)[:100]})")
+            self._publish_runtime_event("tool.started", tool_name=tc.name, call_id=tc.id)
+            exec_record = self._execute_tool(tc)
+            step.tool_execs.append(exec_record)
+            self._tool_call_count += 1
+            verification = self._verify_tool_exec(tc.id, exec_record)
+            self._publish_runtime_event("tool.completed", tool_name=tc.name, call_id=tc.id, success=bool(exec_record.success), duration_ms=exec_record.duration_ms, tool_source=exec_record.source)
+            exec_record.evidence.setdefault("verification", {
+                "passed": bool(verification.passed),
+                "score": verification.score,
+                "missing_items": list(verification.missing_items),
+                "risks": list(verification.risks),
+                "recommended_next_action": verification.recommended_next_action or ("continue" if verification.passed else "retry_or_mark_blocked"),
+            })
+            self._trace(
+                LoopPhase.TOOL_EXECUTION,
+                LoopTransition.TOOL_RESULT if exec_record.success else LoopTransition.FAILED,
+                "tool executed",
+                {
+                    "tool": tc.name,
+                    "success": bool(exec_record.success),
+                    "duration_ms": exec_record.duration_ms,
+                    "execution": dict(exec_record.evidence.get("execution") or {}),
+                    "policy": dict(exec_record.evidence.get("policy") or {}),
+                    "verification": dict(exec_record.evidence.get("verification") or {}),
+                },
+            )
+            if not verification.passed:
+                self._print(f"  [工具验收未通过] {'; '.join(verification.missing_items)}")
+            self._append_tool_result(tc, exec_record)
+            self._print(f"  [结果] {exec_record.result[:200]}")
+
+        tool_names = ", ".join(t.name for t in step.tool_execs)
+        step.summary = f"[ACT] 调用 {len(step.tool_execs)} 个工具: {tool_names}"
+
+        # ── ReAct 关键：工具执行后注入证据感知的反思引导 ──
+        # A2+A3: 如果检测到 file_revisit，注入强制收口提示而非普通 REFLECT
+        tool_summary = "; ".join(f"{t.name}={'成功' if t.success else '失败'}" for t in step.tool_execs)
+        remaining_iters = self.config.max_iterations - self.current_iteration
+
+        if self._should_force_finalize():
+            # A3: 证据充分 — 强制收口
+            revisited = ", ".join(self._last_assessment.revisited_files[:3]) if self._last_assessment else ""
+            self._print(f"  [EVIDENCE GATE] 检测到重复读取已访问文件 ({revisited})，强制收口")
+            self.message_history.append_user(
+                f"[EVIDENCE GATE — 证据已充分]\n"
+                f"你已经重复读取了之前访问过的文件: {revisited}。\n"
+                f"这些信息已经在你的上下文中，不需要再次获取。\n"
+                f"当前是第 {self.current_iteration}/{self.config.max_iterations} 轮，剩余 {remaining_iters} 轮。\n"
+                f"请立即基于已有信息给出最终回答。不要再调用任何工具。"
+            )
+        else:
+            # A2: 正常 REFLECT — 注入已知信息摘要帮助 LLM 判断
+            known_info = self._build_known_info_summary()
+            reflect_prompt = (
+                f"[REFLECT] 已完成工具调用: {tool_summary}。\n"
+                f"当前是第 {self.current_iteration}/{self.config.max_iterations} 轮。\n"
+            )
+            if known_info:
+                reflect_prompt += f"\n{known_info}\n"
+            reflect_prompt += (
+                f"\n请评估：已获得的信息是否足够完成任务？\n"
+                f"- 如果足够：直接给出最终回答。\n"
+                f"- 如果不够：说明还缺什么，下一步该怎么做。\n"
+                f"- 如果工具失败：分析原因，尝试替代方案。\n"
+                f"- 重要：不要重复读取已经访问过的文件。"
+            )
+            self.message_history.append_user(reflect_prompt)
+
+        return step
+
+
+    def cancel(self):
+        self.cancel_event.set()
+
+    def send_message(self, msg: str):
+        self.message_queue.put(msg)
+
+    def get_status(self) -> dict:
+        return {
+            "agent_id": self.agent_id,
+            "name": self.config.name,
+            "status": getattr(self.status, "value", self.status),
+            "iteration": self.current_iteration,
+            "max_iterations": self.config.max_iterations,
+            "tool_calls": self._tool_call_count,
+            "elapsed": round(time.time() - self.start_time, 1) if self.start_time else 0,
+            "last_step": self.steps[-1].summary if self.steps else "",
+        }
+
+    # ── 核心单轮 ───────────────────────────────────
+
+    def _run_one_iteration(self, tools_schema: list[dict] | None) -> LoopStep:
+        """执行一轮循环：LLM 调用 → 工具执行 → 结果回灌。"""
+        self.guardrail_controller.reset_for_turn()
+        step = LoopStep(iteration=self.current_iteration, timestamp=time.time())
+
+        # 检查主 agent 发来的消息
+        incoming = self._check_messages()
+        if incoming:
+            self.message_history.append_user(f"[主Agent消息] {incoming}")
+
+        # ── 1. LLM 调用 ──
+        self._set_status(AgentStatus.RUNNING)
+        self._print(f"\n--- 迭代 {self.current_iteration} ---")
+
+        try:
+            # HTTP SSE 解析器已正确处理 anthropic_messages 的 text/tool_use/thinking，
+            # 不再需要降级为非流式（之前的限制是因为旧 SDK get_final_message 抛 IndexError）。
+            use_stream = getattr(self.config, 'enable_streaming', False)
+
+            self._trace(LoopPhase.LLM_CALL, LoopTransition.LLM_REQUEST, "calling llm", {"stream": bool(use_stream)})
+            self._publish_runtime_event(
+                "llm.request",
+                model=self._current_model,
+                stream=bool(use_stream),
+                task_preview=getattr(self, "_current_task", "")[:240],
+                tool_count=len(tools_schema or []),
+            )
+            if use_stream:
+                response, used_model = self._call_llm_stream(tools_schema)
+            else:
+                response, used_model = self._call_llm(tools_schema)
+            self._trace(LoopPhase.LLM_CALL, LoopTransition.LLM_RESPONSE, "llm response", {"model": used_model, "finish_reason": response.finish_reason, "tool_calls": len(response.tool_calls or [])})
+            self._publish_runtime_event("llm.response", model=used_model, finish_reason=response.finish_reason, tool_calls=len(response.tool_calls or []))
+            self._current_model = used_model
+            step.model = used_model
+            self._consecutive_llm_errors = 0
+        except Exception as e:
+            err_str = str(e)
+            step.summary = f"LLM 错误: {e}"
+            step.finish_reason = "error"
+            self._print(f"  [LLM ERROR] {e}")
+            self._consecutive_llm_errors = getattr(self, '_consecutive_llm_errors', 0) + 1
+
+            strategy = self.config.error_strategy
+
+            # ── retry：指数退避重试（含 429/rate_limit 检测）──
+            if strategy == "retry" and self._consecutive_llm_errors <= self.config.max_retries:
+                delay = self._compute_backoff(self._consecutive_llm_errors, err_str)
+                self._print(f"  [RETRY] 第{self._consecutive_llm_errors}次重试，{delay:.1f}s 后重试")
+                time.sleep(delay)
+                return step
+
+            # ── continue：记录错误，用上一次的内容或空回复继续推进 ──
+            if strategy == "continue":
+                self._print(f"  [CONTINUE] 跳过本轮 LLM 错误，继续推进")
+                step.llm_content = f"[本轮流过错误被跳过: {err_str[:200]}]"
+                step.finish_reason = "error_continue"
+                return step
+
+            # ── escalate：上报给父 Agent/Orchestrator，然后优雅退出 ──
+            if strategy == "escalate":
+                self._print(f"  [ESCALATE] 上报错误给编排层")
+                self._escalation_msg = f"Agent {self.config.name} 在迭代 {self.current_iteration} 遇到不可恢复错误: {err_str}"
+                raise  # 让 run() 的 except 捕获，走 _finish
+
+            # ── fail（默认）：直接抛出 ──
+            raise
+
+        step.llm_content = response.content
+        step.finish_reason = response.finish_reason
+
+        if response.content:
+            self._print(f"  [思考] {response.content[:300]}")
+
+        # ── 2. 把 assistant 回复加入对话 ──
+        all_tool_calls = list(response.tool_calls or [])
+        if all_tool_calls:
+            self.context_memory.register_pending_tool_calls(all_tool_calls)
+        if self.config.tool_execution_mode == "sequential":
+            response.tool_calls = all_tool_calls[: max(1, self.config.max_tool_calls_per_turn)]
+        self._append_assistant_message(response)
+
+        # ── 3. 处理 tool_calls ──
+        if response.has_tool_calls:
+            self._set_status(AgentStatus.WAITING_TOOL)
+            for tc in response.tool_calls:
+                self._print(f"  [工具] {tc.name}({json.dumps(tc.arguments, ensure_ascii=False)[:100]})")
+                self._publish_runtime_event("tool.started", tool_name=tc.name, call_id=tc.id)
+                exec_record = self._execute_tool(tc)
+                step.tool_execs.append(exec_record)
+                self._tool_call_count += 1
+
+                verification = self._verify_tool_exec(tc.id, exec_record)
+                self._publish_runtime_event("tool.completed", tool_name=tc.name, call_id=tc.id, success=bool(exec_record.success), duration_ms=exec_record.duration_ms, tool_source=exec_record.source)
+                exec_record.evidence.setdefault("verification", {
+                    "passed": bool(verification.passed),
+                    "score": verification.score,
+                    "missing_items": list(verification.missing_items),
+                    "risks": list(verification.risks),
+                    "recommended_next_action": verification.recommended_next_action or ("continue" if verification.passed else "retry_or_mark_blocked"),
+                })
+                self._trace(
+                    LoopPhase.TOOL_EXECUTION,
+                    LoopTransition.TOOL_RESULT if exec_record.success else LoopTransition.FAILED,
+                    "tool executed",
+                    {
+                        "tool": tc.name,
+                        "success": bool(exec_record.success),
+                        "duration_ms": exec_record.duration_ms,
+                        "execution": dict(exec_record.evidence.get("execution") or {}),
+                        "policy": dict(exec_record.evidence.get("policy") or {}),
+                        "verification": dict(exec_record.evidence.get("verification") or {}),
+                    },
+                )
+                if not verification.passed:
+                    self._print(f"  [工具验收未通过] {'; '.join(verification.missing_items)}")
+
+                # 回灌结果
+                self._append_tool_result(tc, exec_record)
+                self._print(f"  [结果] {exec_record.result[:200]}")
+
+            tool_names = ", ".join(t.name for t in step.tool_execs)
+            step.summary = f"调用 {len(step.tool_execs)} 个工具: {tool_names}"
+        else:
+            step.summary = f"文本回复 (finish={response.finish_reason})"
+
+        return step
+
+    # ── 工具执行 ───────────────────────────────────
+
+    def _guardrail_denied_exec(self, tc: ToolCallRequest, reason: str, *, action: str = "deny", target: str = "") -> ToolExec:
+        metadata = {
+            "tool": tc.name,
+            "success": False,
+            "guardrail": {
+                "action": action,
+                "reason": reason,
+                "tool": tc.name,
+                "target": target,
+            },
+        }
+        self._trace(LoopPhase.TOOL_EXECUTION, LoopTransition.FAILED, "tool guardrail denied", metadata)
+        return ToolExec(
+            name=tc.name,
+            args=tc.arguments,
+            result=f"ERROR: 被 guardrail 拒绝: {reason}",
+            success=False,
+            source="guardrail",
+            provider_id="runtime.guardrail",
+            safety="policy",
+            evidence={"guardrail": metadata["guardrail"]},
+        )
+
+    def _execute_tool(self, tc: ToolCallRequest) -> ToolExec:
+        return self.tool_call_executor.execute(
+            tc,
+            agent_id=self.agent_id,
+            run_id=self.agent_id,
+        )
+
+    def _verify_tool_exec(self, call_id: str, exec_record: ToolExec):
+        return self.tool_call_executor.verify(call_id, exec_record)
+
+    # ── LLM 调用（支持 ModelRouter）─────────────
+
+    def _call_llm(self, tools_schema):
+        """调用 LLM，支持 ModelRouter 自动 fallback + key 轮转。
+
+        如果 config.model_router 存在：
+          1. acquire() 获取可用 client + model
+          2. 调用失败 → report_failure() → 重新 acquire（自动切模型/key）
+          3. 成功 → report_success()
+
+        如果没有 router，直接用 self.llm。
+        """
+        router = self.config.model_router
+        if not router:
+            # 没有 router，直接调
+            _started = time.time()
+            response = self.llm.chat(
+                messages=self._context_messages_for_llm(),
+                system=self._dynamic_system_prompt(),
+                model=self.config.model,
+                temperature=self.config.temperature,
+                tools=tools_schema,
+                extra_body=self.config.extra_body if self.config.extra_body else None,
+                request_timeout=self.config.llm_timeout,
+            )
+            _elapsed = int((time.time() - _started) * 1000)
+            _usage = getattr(response, "usage", None) or {}
+            _m = ModelAttempt(
+                iteration=self.current_iteration,
+                model=self.config.model,
+                status="success",
+                duration_ms=_elapsed,
+                input_tokens=int(_usage.get("prompt_tokens", _usage.get("input_tokens", 0))),
+                output_tokens=int(_usage.get("completion_tokens", _usage.get("output_tokens", 0))),
+            )
+            self.model_attempts.append(_m)
+            self.tracer.on_model_attempt(
+                model=_m.model, status=_m.status, duration_ms=_m.duration_ms,
+                input_tokens=_m.input_tokens, output_tokens=_m.output_tokens,
+                error=_m.error, iteration=_m.iteration,
+            )
+            return response, self.config.model
+
+        # 有 router：尝试 fallback 链。
+        # 注意：同一模型可能有多个 key/client。不能只按 model 去重，否则第一个 key
+        # 429/401 后会跳过同模型下的下一 key。参考 LBS 的 credential pool 思路：
+        # 一次失败淘汰的是当前 lease/credential，不是整个模型族。
+        last_error = ""
+        model_chain = list(getattr(router, "_model_chain", []) or [self.config.model])
+        key_count = len(getattr(router, "_keys", []) or [])
+        max_attempts = max(1, len(model_chain) * max(1, key_count), len(model_chain) + 1)
+
+        for attempt in range(max_attempts):
+            client, model = router.acquire()
+            if not client or not model:
+                break
+
+            capability_snapshot: dict[str, Any] = {}
+            if hasattr(router, "capability_snapshot"):
+                try:
+                    raw_snapshot = router.capability_snapshot(model)
+                    capability_snapshot = raw_snapshot.to_dict() if hasattr(raw_snapshot, "to_dict") else dict(raw_snapshot or {})
+                except Exception:
+                    capability_snapshot = {}
+
+            started = time.time()
+            try:
+                response = client.chat(
+                    messages=self._context_messages_for_llm(),
+                    system=self._dynamic_system_prompt(),
+                    model=model,
+                    temperature=self.config.temperature,
+                    tools=tools_schema,
+                    extra_body=self.config.extra_body if self.config.extra_body else None,
+                    request_timeout=self.config.llm_timeout,
+                )
+                if not getattr(response, "content", "") and not getattr(response, "tool_calls", None):
+                    raise ValueError("LLM returned empty response")
+                elapsed_ms = int((time.time() - started) * 1000)
+                router.report_success(model)
+                _m = ModelAttempt(
+                    iteration=self.current_iteration,
+                    model=model,
+                    status="success",
+                    duration_ms=elapsed_ms,
+                    capabilities=capability_snapshot,
+                    input_tokens=int((response.usage or {}).get("prompt_tokens", (response.usage or {}).get("input_tokens", 0))),
+                    output_tokens=int((response.usage or {}).get("completion_tokens", (response.usage or {}).get("output_tokens", 0))),
+                )
+                self.model_attempts.append(_m)
+                self.tracer.on_model_attempt(
+                    model=_m.model, status=_m.status, duration_ms=_m.duration_ms,
+                    input_tokens=_m.input_tokens, output_tokens=_m.output_tokens,
+                    error=_m.error, iteration=_m.iteration,
+                )
+                # 记录 token 用量
+                if hasattr(response, 'usage') and response.usage:
+                    try:
+                        from runtime.core.llm.usage_pricing import get_usage_tracker
+                        get_usage_tracker().record(
+                            model=model,
+                            agent_name=self.config.name,
+                            usage=response.usage,
+                        )
+                    except Exception:
+                        pass
+                # 过滤 thinking blocks
+                if hasattr(response, 'content') and response.content:
+                    try:
+                        from runtime.core.llm.think_scrubber import ThinkScrubber
+                        response.content = ThinkScrubber.strip(response.content)
+                    except Exception:
+                        pass
+                if model != self.config.model:
+                    self._print(f"[FALLBACK] 备选模型 → {model}", level="warn")
+                return response, model
+
+            except Exception as e:
+                elapsed_ms = int((time.time() - started) * 1000)
+                last_error = str(e)
+                error_class = router.classify_error(last_error) if hasattr(router, "classify_error") else "unknown"
+                router.report_failure(model, last_error)
+                _m = ModelAttempt(
+                    iteration=self.current_iteration,
+                    model=model,
+                    status="error",
+                    duration_ms=elapsed_ms,
+                    error=last_error,
+                    error_class=error_class,
+                    capabilities=capability_snapshot,
+                )
+                self.model_attempts.append(_m)
+                self.tracer.on_model_attempt(
+                    model=_m.model, status=_m.status, duration_ms=_m.duration_ms,
+                    input_tokens=_m.input_tokens, output_tokens=_m.output_tokens,
+                    error=_m.error, iteration=_m.iteration,
+                )
+                self._print(f"  [MODEL FAIL] {model}: {last_error[:100]}")
+                continue
+
+        raise ValueError(f"所有模型/key 均不可用。最后错误: {last_error}")
+
+    # ── 消息构造 ───────────────────────────────────
+
+
+
+    def _call_llm_stream(self, tools_schema):
+        """流式 LLM 调用，实时打印 token。
+
+        返回 (CompletionResult, model_used)。
+        如果 LLMClient 不支持 chat_stream，降级为同步调用。
+        """
+        router = self.config.model_router
+
+        def _try_stream(client, model):
+            """尝试流式调用单个 client，返回 (CompletionResult, model)。"""
+            accumulated = ""
+            tool_calls = []
+
+            def on_chunk(delta, chunk_type="text"):
+                nonlocal accumulated
+                if chunk_type == "text":
+                    accumulated += delta
+                # 实时推送每个 chunk 到 WS
+                if self.config.on_chunk:
+                    try:
+                        self.config.on_chunk(delta, chunk_type)
+                    except Exception:
+                        pass
+                if self.config.report_progress and not self.config.on_chunk:
+                    print(delta, end="", flush=True)
+
+            for delta_text, tc_so_far, done in client.chat_stream(
+                messages=self._context_messages_for_llm(),
+                system=self._dynamic_system_prompt(),
+                model=model,
+                temperature=self.config.temperature,
+                tools=tools_schema,
+                on_chunk=on_chunk,
+                extra_body=self.config.extra_body if self.config.extra_body else None,
+                request_timeout=self.config.llm_timeout,
+            ):
+                # accumulated is already maintained inside on_chunk above;
+                # do NOT add delta_text here — that doubles every character.
+                if done and tc_so_far:
+                    tool_calls = tc_so_far
+
+            # 流式结束，打印换行
+            if self.config.report_progress and accumulated and not self.config.on_chunk:
+                print()  # newline after streaming
+
+            # 应用网关去重（与非流式路径一致）
+            from runtime.core.llm.client import CompletionResult, _collapse_systematic_pair_duplication
+            deduped = _collapse_systematic_pair_duplication(accumulated)
+            if deduped != accumulated:
+                logger.warning("[%s] streaming output deduplicated: %d→%d chars",
+                               self.config.name, len(accumulated), len(deduped))
+                accumulated = deduped
+            if not accumulated and not tool_calls:
+                raise ValueError("LLM returned empty response")
+
+            return CompletionResult(
+                content=accumulated,
+                finish_reason="tool_calls" if tool_calls else "stop",
+                model=model,
+                tool_calls=tool_calls,
+            ), model
+
+        if not router:
+            # 无 router：优先流式，但不支持时降级为同步
+            if hasattr(self.llm, 'chat_stream') and getattr(self.llm, 'profile', None):
+                try:
+                    return _try_stream(self.llm, self.config.model)
+                except Exception:
+                    pass  # 流式失败，降级
+            return self._call_llm(tools_schema)
+
+        # 有 router：acquire → stream → fallback on error
+        last_error = ""
+        model_chain = list(getattr(router, "_model_chain", []) or [self.config.model])
+        key_count = len(getattr(router, "_keys", []) or [])
+        max_attempts = max(1, len(model_chain) * max(1, key_count), len(model_chain) + 1)
+
+        # 先 peek 一下是否支持流式（避免消耗 mock router 的 client）
+        _peek_client = None
+        try:
+            _peek_client, _peek_model = router.acquire()
+            if _peek_client and (not hasattr(_peek_client, 'chat_stream') or not getattr(_peek_client, 'profile', None)):
+                # 不支持流式：report_success 归还，降级为同步
+                router.report_success(_peek_model)
+                return self._call_llm(tools_schema)
+        except Exception:
+            # P1-3: peek 只是能力探测，不是真实调用。归还 lease 不应惩罚该 key。
+            if _peek_model:
+                try:
+                    router.report_success(_peek_model)
+                except Exception:
+                    pass
+            return self._call_llm(tools_schema)
+
+        # 支持流式：用 peek 到的 client 开始，后续走正常 fallback
+        _first_client = _peek_client
+        _first_model = _peek_model
+
+        for attempt in range(max_attempts):
+            if attempt == 0:
+                client, model = _first_client, _first_model
+            else:
+                client, model = router.acquire()
+            if not client or not model:
+                break
+            started = time.time()
+            try:
+                result, used_model = _try_stream(client, model)
+                router.report_success(model)
+                _stream_usage = getattr(result, "usage", None) or {}
+                _m = ModelAttempt(
+                    iteration=self.current_iteration,
+                    model=used_model,
+                    status="success",
+                    duration_ms=int((time.time() - started) * 1000),
+                    input_tokens=int(_stream_usage.get("prompt_tokens", _stream_usage.get("input_tokens", 0))),
+                    output_tokens=int(_stream_usage.get("completion_tokens", _stream_usage.get("output_tokens", 0))),
+                )
+                self.model_attempts.append(_m)
+                self.tracer.on_model_attempt(
+                    model=_m.model, status=_m.status, duration_ms=_m.duration_ms,
+                    input_tokens=_m.input_tokens, output_tokens=_m.output_tokens,
+                    error=_m.error, iteration=_m.iteration,
+                )
+                return result, used_model
+            except Exception as e:
+                elapsed_ms = int((time.time() - started) * 1000)
+                last_error = str(e)
+                error_class = router.classify_error(last_error) if hasattr(router, "classify_error") else "unknown"
+                router.report_failure(model, last_error)
+                _m = ModelAttempt(
+                    iteration=self.current_iteration,
+                    model=model,
+                    status="error",
+                    duration_ms=elapsed_ms,
+                    error=last_error,
+                    error_class=error_class,
+                )
+                self.model_attempts.append(_m)
+                self.tracer.on_model_attempt(
+                    model=_m.model, status=_m.status, duration_ms=_m.duration_ms,
+                    input_tokens=_m.input_tokens, output_tokens=_m.output_tokens,
+                    error=_m.error, iteration=_m.iteration,
+                )
+                self._print(f"  [MODEL FAIL] {model}: {last_error[:100]}")
+                continue
+
+        raise ValueError(f"流式调用：所有模型/key 均不可用。最后错误: {last_error}")
+
+    def _compute_backoff(self, attempt: int, error_str: str = "") -> float:
+        """委托给 error_classifier.compute_backoff。"""
+        from runtime.core.llm.error_classifier import classify_api_error, compute_backoff
+        classified = classify_api_error(error_str)
+        return compute_backoff(attempt, classified, base_delay=self.config.retry_delay or 2.0)
+
+    def _build_tool_guidance(self, task: str) -> str:
+        """按任务和可用工具注入硬约束，降低工具型 agent 空转。"""
+        if not self.config.tools:
+            return ""
+        available = set(self.config.tools or [])
+        task_text = task or ""
+        hints: list[str] = []
+        if "read_file" in available and re.search(r"(读取|查看|打开|前\s*\d+\s*行|文件|read)", task_text, re.I):
+            hints.append("任务涉及读取文件：第一步优先调用 read_file，不要用 todo 代替读取。")
+        if "search_files" in available and re.search(r"(搜索|查找|grep|find|包含|定位)", task_text, re.I):
+            hints.append("任务涉及搜索/定位：优先调用 search_files 获取证据。")
+        if "terminal" in available and re.search(r"(运行|测试|执行|命令|pytest|python|检查)", task_text, re.I):
+            hints.append("任务涉及运行命令：需要时调用 terminal，并报告真实退出码/输出。")
+        if not hints:
+            return ""
+        return "\n--- 工具使用硬约束 ---\n" + "\n".join(f"- {h}" for h in hints)
+
+
+    def _build_system_prompt(self) -> str:
+        """动态组装 system prompt：SOUL.md + AGENTS.md + base prompt + 能力 + skill。
+
+        层次（对标 LBS 三层 system prompt）：
+          stable   = SOUL.md（身份）+ AGENTS.md（项目指令）+ base prompt + 工具 + skill
+          context  = 任务上下文（在 _build_initial_message 中）
+          volatile = memory + 时间戳（在 run() 中注入）
+        """
+        parts = []
+        import os as _os2
+        _project_root = _os2.path.dirname(_os2.path.dirname(_os2.path.dirname(_os2.path.dirname(_os2.path.abspath(__file__)))))
+
+        # 0. SOUL — 主 Agent 角色身份（可配置，对标 LBS SOUL.md）
+        # 加载顺序：souls/{config.soul}.md → SOUL.md（向后兼容）
+        _soul_name = (
+            getattr(getattr(self.config, "models", None), "raw", {})
+            .get("default", {})
+            .get("soul")
+            or getattr(self.config, "soul", "小爪")
+            or "default"
+        )
+        _soul_loaded = False
+        _soul_path = _os2.path.join(_project_root, "souls", f"{_soul_name}.md")
+        if _os2.path.exists(_soul_path):
+            try:
+                with open(_soul_path, encoding="utf-8") as _f:
+                    soul = _f.read().strip()
+                if soul:
+                    parts.append(soul)
+                    _soul_loaded = True
+            except Exception:
+                pass
+        # 向后兼容：如果 souls/ 里没找到，尝试根目录 SOUL.md
+        if not _soul_loaded:
+            _soul_fallback = _os2.path.join(_project_root, "SOUL.md")
+            if _os2.path.exists(_soul_fallback):
+                try:
+                    with open(_soul_fallback, encoding="utf-8") as _f:
+                        soul = _f.read().strip()
+                    if soul:
+                        parts.append(soul)
+                except Exception:
+                    pass
+
+        # 0b. AGENTS.md — 项目指令（对标 LBS AGENTS.md / .cursorrules）
+        _agents_path = _os2.path.join(_project_root, "AGENTS.md")
+        if _os2.path.exists(_agents_path):
+            try:
+                with open(_agents_path, encoding="utf-8") as _f:
+                    agents_md = _f.read().strip()
+                if agents_md:
+                    parts.append(agents_md)
+            except Exception:
+                pass
+
+        # 1. base prompt（来自 prompts/*.md 或 YAML）
+        base = self.config.system_prompt or ""
+        if base:
+            parts.append(base)
+
+        # 2. agent 身份和能力 — B: 身份分层契约（Soul 人格层 vs Agent 执行角色层）
+        identity_lines = []
+        soul_loaded_name = _soul_name if _soul_loaded else ""
+        if soul_loaded_name and soul_loaded_name != "default":
+            identity_lines.append(f"你的人格身份（Soul）是「{soul_loaded_name}」。")
+        if self.config.display_name:
+            identity_lines.append(f"你当前的执行角色（Agent）是「{self.config.display_name}」。")
+        else:
+            identity_lines.append("你当前的执行角色（Agent）未指定。")
+        if self.config.description:
+            identity_lines.append(f"执行职责：{self.config.description}")
+        # B: 身份回答契约
+        if soul_loaded_name and soul_loaded_name != "default" and self.config.display_name:
+            identity_lines.append(
+                "回答身份类问题时（如「你是谁」），请同时报告人格身份和执行角色。"
+            )
+
+        # 3. 可用工具
+        if self.config.tools:
+            identity_lines.append("\n你有以下工具可用：")
+            for t in self.config.tools:
+                identity_lines.append(f"  - {t}")
+            identity_lines.append("根据任务需要主动调用工具，不要只给文字回复。")
+        else:
+            identity_lines.append("\n你没有外部工具，靠推理完成任务。")
+
+        # 4. 迭代约束
+        identity_lines.append(f"\n最多 {self.config.max_iterations} 轮迭代，超时 {self.config.timeout}s。")
+        identity_lines.append("高效工作：先规划再执行，不要重复无效操作。")
+
+        parts.append("\n".join(identity_lines))
+
+        # 5. guardrails（如果还没在初始消息中注入）
+        if self.config.guardrails:
+            parts.append("\n--- 安全约束 ---")
+            for g in self.config.guardrails:
+                parts.append(f"- {g}")
+
+        # 6. Skill 索引（让 LLM 知道有哪些专业知识可用）
+        skill_index = self._build_skill_index()
+        if skill_index:
+            parts.append(skill_index)
+
+        return "\n\n".join(parts)
+
+    def _build_skill_index(self) -> str:
+        """扫描本地 skills/ 目录，构建紧凑的 skill 索引注入 system prompt。
+
+        和 LBS 一样的机制：
+          - 扫描所有 SKILL.md 的 frontmatter（name + description）
+          - 按分类分组，输出紧凑索引
+          - 告诉 LLM：如果任务和某个 skill 相关，先 skill_view 加载它
+        """
+        import os as _os
+        skills_dir = getattr(self.config, "skills_dir", "")
+        if not skills_dir:
+            project_root = _os.path.dirname(_os.path.dirname(_os.path.dirname(_os.path.dirname(_os.path.abspath(__file__)))))
+            candidates = [
+                _os.path.join(project_root, ".lbs-agent", "skills", "active"),
+                _os.path.join(project_root, "skills"),
+            ]
+            skills_dir = next((path for path in candidates if _os.path.isdir(path)), "")
+        if not skills_dir or not _os.path.isdir(skills_dir):
+            return ""
+
+        # 扫描所有 SKILL.md
+        skills_by_category: dict[str, list[tuple[str, str]]] = {}
+        for dirpath, _, filenames in _os.walk(skills_dir):
+            if "SKILL.md" not in filenames:
+                continue
+            md_path = _os.path.join(dirpath, "SKILL.md")
+            try:
+                with open(md_path, encoding="utf-8-sig", errors="replace") as _f:
+                    text = _f.read()
+            except Exception:
+                continue
+
+            # 解析 frontmatter（P2-9: 扩大到50行以覆盖更长的 description）
+            name = ""
+            desc = ""
+            for line in text.splitlines()[:50]:
+                line = line.strip()
+                if line.startswith("name:"):
+                    name = line[5:].strip().strip("\'").strip('"')
+                elif line.startswith("description:"):
+                    desc = line[12:].strip().strip("\'").strip('"')
+                    if len(desc) > 100:
+                        desc = desc[:97] + "..."
+
+            if not name:
+                name = _os.path.basename(dirpath)
+
+            # 分类 = skills/ 下的第一级目录
+            rel = _os.path.relpath(dirpath, skills_dir)
+            parts = rel.replace("\\", "/").split("/")
+            category = parts[0] if len(parts) > 1 else "general"
+
+            skills_by_category.setdefault(category, []).append((name, desc))
+
+        if not skills_by_category:
+            return ""
+
+        # 构建索引文本
+        lines = [
+            "## Skills (可用技能)",
+            "以下是你可以使用的专业技能。如果任务和某个 skill 相关，",
+            "先用 skill_view(name) 加载它的完整说明，然后按说明工作。",
+            "Err on the side of loading — 加载不需要的 skill 比遗漏关键步骤好。",
+            "",
+            "<available_skills>",
+        ]
+        for category in sorted(skills_by_category.keys()):
+            lines.append(f"  {category}:")
+            seen = set()
+            for name, desc in sorted(skills_by_category[category], key=lambda x: x[0]):
+                if name in seen:
+                    continue
+                seen.add(name)
+                if desc:
+                    lines.append(f"    - {name}: {desc}")
+                else:
+                    lines.append(f"    - {name}")
+        lines.append("</available_skills>")
+
+        return "\n".join(lines)
+
+
+    def _dynamic_system_prompt(self) -> str:
+        """构建动态 system prompt（带缓存，只构建一次）。"""
+        if not hasattr(self, '_cached_system_prompt') or self._cached_system_prompt is None:
+            self._cached_system_prompt = self._build_system_prompt()
+        return self._cached_system_prompt
+
+    def _build_initial_message(self, task: str, context: str) -> str:
+        """组装初始 user 消息：任务 + 工具引导 + 上下文 + 完成标准。
+
+        注意：agent 身份、工具列表、guardrails 已移入 system prompt，
+        这里只放任务本身和上下文，避免重复。
+        """
+        parts = [task]
+        tool_guidance = self._build_tool_guidance(task)
+        if tool_guidance:
+            parts.append(tool_guidance)
+        if context:
+            parts.append(f"\n--- 上下文 ---\n{context}")
+        # verification_rules 是内部验证条件，不是给 LLM 的输出指令
+        # 只在有工具调用的 agent 中以人类可读的方式注入
+        if self.config.verification_rules and self.config.tools and self.config.verification_level != "light":
+            # 将内部规则名转换为人类可读的描述
+            rule_descriptions = {
+                "final_acceptance": "输出必须包含明确的最终结果",
+                "must_have_evidence": "结论必须有证据支撑（文件路径、测试结果等）",
+                "tests_must_pass": "代码修改必须通过测试验证",
+                "no_hallucination": "不得编造不存在的文件、函数或 API",
+            }
+            readable = []
+            for v in self.config.verification_rules:
+                readable.append(rule_descriptions.get(v, ""))
+            # 只注入有实际描述的规则
+            readable = [r for r in readable if r]
+            if readable:
+                parts.append("\n--- 完成标准 ---")
+                parts.append("完成后，你的输出需要满足：")
+                for r in readable:
+                    parts.append(f"- {r}")
+        return "\n".join(parts)
+
+    def _build_tools_schema(self) -> list[dict] | None:
+        if not self.config.tool_registry or not self.config.tools:
+            return None
+        return self.config.tool_registry.export_for_mode(
+            self.config.api_mode,
+            names=self.config.tools,
+        )
+
+    def _append_assistant_message(self, response: CompletionResult):
+        """把 LLM 回复委托给上下文记忆编码。"""
+        self.context_memory.append_assistant(response)
+
+    def _append_tool_result(self, tc: ToolCallRequest, exec_record: ToolExec):
+        """把工具结果写入消息历史，并完成对应 pending 调用。"""
+        self.context_memory.append_tool_result(tc, exec_record)
+
+    def resume_pending_tool_calls(self) -> list[str]:
+        """恢复 checkpoint 中未完成的工具调用，已完成调用不会重放。"""
+        resumed: list[str] = []
+        for call in self.context_memory.pending_tool_call_requests():
+            self._print(f"  [RESUME TOOL] {call.name}({json.dumps(call.arguments, ensure_ascii=False)[:100]})")
+            exec_record = self._execute_tool(call)
+            self._tool_call_count += 1
+            verification = self._verify_tool_exec(call.id, exec_record)
+            exec_record.evidence.setdefault("verification", {
+                "passed": bool(verification.passed),
+                "score": verification.score,
+                "missing_items": list(verification.missing_items),
+                "risks": list(verification.risks),
+                "recommended_next_action": verification.recommended_next_action or ("continue" if verification.passed else "retry_or_mark_blocked"),
+            })
+            self._append_tool_result(call, exec_record)
+            resumed.append(call.id)
+            if self.on_step:
+                self.on_step(None)
+        return resumed
+
+    # ── 进展/验收
+
+    def _build_known_info_summary(self) -> str:
+        """A2: 构造当前已积累的信息摘要，注入 LLM 前帮助判断证据是否充分。
+
+        从 context_memory 的 recent_tool_results 提取已获取的信息，
+        让 LLM 知道它已经有了什么，减少无意义的重复调用。
+        """
+        parts: list[str] = []
+
+        # 从 ContextState 提取已有工具结果
+        ctx_mem = getattr(self, "context_memory", None)
+        if ctx_mem is not None:
+            state = getattr(ctx_mem, "state", None)
+            if state is not None:
+                recent = getattr(state, "recent_tool_results", [])
+                if recent:
+                    seen_tools: list[str] = []
+                    for item in recent:
+                        if not isinstance(item, dict):
+                            continue
+                        tool = item.get("tool", "")
+                        status = item.get("status", "")
+                        ok = item.get("ok", True)
+                        if ok and status != "error":
+                            fp = item.get("path", "") or item.get("file_path", "")
+                            if fp:
+                                seen_tools.append(f"已读取: {fp}")
+                            elif tool:
+                                seen_tools.append(f"已执行: {tool}")
+                    if seen_tools:
+                        parts.append("当前已获取的信息:")
+                        parts.extend(f"  - {s}" for s in seen_tools[-8:])  # 最近8条
+
+        # 从 ProgressTracker 提取已访问文件
+        if self._last_assessment is not None:
+            visited = getattr(self.progress_tracker, "_seen_file_paths", set())
+            if visited:
+                parts.append(f"已访问文件数: {len(visited)}")
+
+        return "\n".join(parts) if parts else ""
+
+    def _should_force_finalize(self) -> bool:
+        """A3: 判断是否应该强制进入收口（finalization）阶段。
+
+        触发条件：
+        - 连续2轮以上有 file_revisit 信号（重复读取已访问的文件）
+        - 总工具调用数 >= 3 且最近轮次全部是 revisit
+        """
+        if self._last_assessment is None:
+            return False
+        assessment = self._last_assessment
+
+        # 条件1：本轮全部工具调用都是文件重读
+        if assessment.file_revisits > 0 and self._tool_call_count >= 3:
+            # 检查 signals 里是否还有 new_file / new_tool
+            has_new_info = any(
+                s.startswith("new_file:") or s.startswith("new_tool:")
+                for s in assessment.signals
+            )
+            # 如果本轮全是 revisit 且没有新信息，建议收口
+            if not has_new_info and assessment.file_revisits >= 1:
+                return True
+
+        return False
+
+    def _detect_stall(self, step: LoopStep) -> str:
+        """检测 agent 空转：使用结构化 ProgressTracker 替代纯字符串签名。
+
+        多维度评估：
+          - 新工具/新文件/新命令/结果变化 = 有进展
+          - 连续无进展达到阈值 = stall
+          - 工具失败/只调 todo = stall 信号
+        """
+        assessment = self.progress_tracker.assess(step)
+        self._stall_count = assessment.stall_count
+        self._last_progress_signature = assessment.progress_hash
+        self._last_assessment = assessment  # A1: 暴露给 ReAct 循环做证据感知
+
+        # 如果 ProgressTracker 判定 stall，直接返回原因
+        if assessment.stalled:
+            return assessment.reason
+
+        # 保留原有即时检测（stall_limit=1 时需要第一轮就触发）
+        # 但 ProgressTracker 已在 stall_threshold 轮内容忍重试
+        return ""
+
+    # ── 验证 ───────────────────────────────────────
+
+    def _decide_completion(self, content: str, *, enforce_react_actions: bool = False):
+        verification_level = getattr(self.config, "verification_level", "medium")
+        # no_tool_errors 是显式安全约束：即使 AgentConfig 未提升到 heavy，
+        # 也必须阻止失败工具后的伪成功收口。
+        if (
+            str(verification_level).strip().lower() == "medium"
+            and any(
+                (rule or "").strip().lower() in {"no_tool_errors", "final_acceptance"}
+                for rule in (self.config.verification_rules or [])
+            )
+        ):
+            verification_level = "heavy"
+        decision = self.completion_gate.decide(
+            content=content,
+            task=getattr(self, "_current_task", ""),
+            steps=self.steps,
+            verification_level=verification_level,
+            verification_rules=self.config.verification_rules,
+            tools=self.config.tools,
+            target_id=self.agent_id,
+            enforce_react_actions=enforce_react_actions,
+        )
+        self._print_verification(decision.outcome)
+        return decision
+
+    def _verify(self, content: str) -> bool:
+        """Compatibility shim for boolean completion checks."""
+        return self._decide_completion(content).passed
+
+    def _print_verification(self, outcome):
+        explanation = outcome.explain()
+        if not outcome.passed:
+            self._last_verification_error = explanation
+            self._print(f"  [验证未通过] {explanation}")
+        else:
+            self._last_verification_error = ""
+            self._print(f"  [验证通过] {explanation}")
+
+    def _compress_context_if_needed(self):
+        """在每轮模型调用前准备上下文，并记录可序列化的压缩证据。"""
+        try:
+            new_messages, result = self.context_window.prepare(self.messages)
+        except Exception as exc:
+            self._trace(
+                LoopPhase.CONTEXT_PREFLIGHT,
+                LoopTransition.FAILED,
+                "context preflight failed",
+                {
+                    "before_chars": sum(len(str(m.get("content", ""))) for m in self.messages),
+                    "after_chars": 0,
+                    "dropped": 0,
+                    "warnings": [str(exc)],
+                },
+            )
+            raise
+
+        evidence = {
+            "before_chars": int(getattr(result, "before_chars", 0) or 0),
+            "after_chars": int(getattr(result, "after_chars", 0) or 0),
+            "dropped": int(getattr(result, "dropped_messages", 0) or 0),
+            "warnings": [str(item) for item in (getattr(result, "warnings", None) or [])],
+            "compressed": bool(getattr(result, "compressed", False)),
+            "method": str(getattr(result, "method", "none") or "none"),
+        }
+        # 可观测性 hook
+        if result.compressed:
+            self.tracer.on_compression(
+                before_chars=evidence["before_chars"],
+                after_chars=evidence["after_chars"],
+                dropped=evidence["dropped"],
+                method=evidence["method"],
+                warnings=evidence["warnings"],
+            )
+        self._trace(
+            LoopPhase.CONTEXT_PREFLIGHT,
+            LoopTransition.PASSED,
+            "context preflight passed",
+            evidence,
+        )
+        if result.compressed:
+            self.message_history.replace(new_messages)
+            # P0-2: 记录压缩结果，供 AgentResult 和 SessionStore 使用
+            self.compression_results.append({
+                "iteration": self.current_iteration,
+                "before_tokens": getattr(result, "before_tokens", 0),
+                "after_tokens": getattr(result, "after_tokens", 0),
+                "before_chars": getattr(result, "before_chars", 0),
+                "after_chars": getattr(result, "after_chars", 0),
+                "dropped_messages": getattr(result, "dropped_messages", 0),
+                "pruned_tool_results": getattr(result, "pruned_tool_results", 0),
+                "deduplicated_files": getattr(result, "deduplicated_files", 0),
+                "method": getattr(result, "method", "unknown"),
+                "warnings": list(getattr(result, "warnings", []) or []),
+            })
+            self._print(
+                f"  [上下文压缩] {result.before_chars} -> {result.after_chars} chars, "
+                f"压缩 {result.dropped_messages} 条历史消息"
+            )
+            if result.warnings:
+                self._print(f"  [上下文压缩警告] {'; '.join(result.warnings)}")
+
+    # ── 辅助 ───────────────────────────────────────
+
+
+    # ── 降级模式（P3b）───────────────────────────────────────
+
+    def _ensure_memory(self):
+        """返回可用记忆体：MemoryManager → inline → dict 缓存。
+        绝不抛异常。失败时返回 NoopMemory。"""
+        if hasattr(self, '_memory_degraded') and self._memory_degraded:
+            return self._memory_cache
+        if self.memory_manager:
+            try:
+                return self.memory_manager
+            except Exception:
+                pass
+        # 降级：简单的 dict 缓存
+        class _NoopMemory:
+            def store(self, *a, **kw): pass
+            def recall(self, *a, **kw): return None
+            def search(self, *a, **kw): return []
+            def prepare_context(self, *a, **kw): return ""
+            def on_turn_start(self, *a, **kw): pass
+            def on_session_end(self, *a, **kw): pass
+            def initialize(self): pass
+            def shutdown(self): pass
+        self._memory_degraded = True
+        self._memory_cache = _NoopMemory()
+        self._print("  [DEGRADE] Memory 不可用，降级为空缓存", level="warn")
+        return self._memory_cache
+
+    def _safe_compress(self):
+        """安全压缩上下文，失败时不崩溃只打日志。"""
+        try:
+            self._compress_context_if_needed()
+        except Exception as e:
+            self._print(f"  [DEGRADE] 上下文压缩失败: {str(e)[:80]}, 降级为截断", level="warn")
+            # 降级：简单截断到上下文窗口
+            try:
+                max_msgs = getattr(self.config, 'max_iterations', 50) * 2 + 10
+                if len(self.messages) > max_msgs:
+                    keep = self.messages[:3] + self.messages[-(max_msgs-3):]
+                    self.message_history.replace(keep)
+            except Exception:
+                pass
+
+    def _safe_llm_call(self, tools_schema):
+        """安全调用 LLM，失败时返回降级回复。"""
+        if not self.llm:
+            self._print("  [DEGRADE] LLM 不可用，降级为文本生成", level="warn")
+            return None, ""
+        try:
+            return self._call_llm(tools_schema)
+        except Exception as e:
+            decision = self.retry_engine.decide_on_exception(1, e, model=self._current_model or "")
+            if decision.fallback and self.config.fallback_models:
+                self._print(f"  [FALLBACK] {decision.message}", level="warn")
+                self._current_model = self.config.fallback_models[0]
+                try:
+                    return self._call_llm(tools_schema)
+                except Exception as e2:
+                    self._print(f"  [DEGRADE] 备选模型也失败: {str(e2)[:80]}", level="warn")
+                    return None, ""
+            if decision.retry:
+                import time as _rt
+                _rt.sleep(min(decision.delay, 5.0))
+                try:
+                    return self._call_llm(tools_schema)
+                except Exception as e2:
+                    return None, ""
+            self._print(f"  [DEGRADE] LLM 调用失败: {decision.message}", level="warn")
+            return None, ""
+
+
+    def _check_messages(self) -> Optional[str]:
+        try:
+            return self.message_queue.get_nowait()
+        except Empty:
+            return None
+
+
+    def _trace(
+        self,
+        phase: LoopPhase,
+        transition: LoopTransition,
+        message: str = "",
+        metadata: dict[str, Any] | None = None,
+    ) -> RunTraceEvent:
+        """Record a phase-level runtime event. No secrets or raw prompts are stored."""
+        event = RunTraceEvent(
+            phase=phase,
+            transition=transition,
+            iteration=self.current_iteration,
+            agent_name=self.config.name,
+            message=message,
+            metadata=metadata or {},
+        )
+        self.run_trace.append(event)
+        self._publish_runtime_event(
+            "loop.trace",
+            phase=getattr(event.phase, "value", event.phase),
+            transition=getattr(event.transition, "value", event.transition),
+            iteration=event.iteration,
+            message=event.message,
+            metadata=dict(event.metadata or {}),
+            at=event.at,
+        )
+        # 可观测性 hook
+        self.tracer.on_trace(
+            phase=getattr(event.phase, "value", event.phase),
+            transition=getattr(event.transition, "value", event.transition),
+            iteration=event.iteration,
+            message=event.message,
+            metadata=dict(event.metadata or {}),
+        )
+        return event
+
+    def _publish_runtime_event(self, event_type: str, **payload: Any) -> RuntimeEvent:
+        return self.event_bus.publish(event_type, self.config.name or self.agent_id, **payload)
+
+    def _set_status(self, status: AgentStatus):
+        old = self.status
+        self.status = status
+        self.tracer.set_status(status.value if hasattr(status, "value") else str(status))
+        if old != status and self.on_status_change:
+            self.on_status_change(status)
+
+    def _print(self, msg: str, level: str = "info"):
+        """格式化输出 — 接入 display 模块。
+
+        level: info | success | error | warn | dim | tool | step
+
+        如果配置了 on_chunk 回调（WebSocket/API 模式），走回调而非 stdout，
+        避免 agent 在非 CLI 环境污染进程输出。
+        """
+        if not self.config.report_progress:
+            return
+        # WebSocket/API 模式：走 on_chunk 而非 print
+        if self.config.on_chunk:
+            try:
+                self.config.on_chunk(msg + "\n", chunk_type=level)
+            except Exception:
+                pass
+            return
+        try:
+            from runtime.orchestration.display import (
+                cyan, green, red, yellow, gray, bold, format_step_header
+            )
+            if level == "success":
+                print(green(msg))
+            elif level == "error":
+                print(red(msg))
+            elif level == "warn":
+                print(yellow(msg))
+            elif level == "dim":
+                print(gray(msg))
+            elif level == "tool":
+                print(f"  {cyan('[工具]')} {msg}")
+            elif level == "step":
+                print(bold(format_step_header(
+                    self.current_iteration, self.config.max_iterations, "ReAct"
+                )))
+            else:
+                print(msg)
+        except ImportError:
+            print(msg)
+
+    def _finish(self, success: bool, error: str, content: str, *, status: AgentStatus | None = None) -> AgentResult:
+        # N1: 重置递归重试深度，避免同一 AgentLoop 实例复用时脏状态
+        self._retry_depth = 0
+        # P1-1: 支持精细化终止状态，调用方可以传入精确的 status
+        if status is not None:
+            self._set_status(status)
+        else:
+            self._set_status(AgentStatus.DONE if success else AgentStatus.ERROR)
+        self._trace(LoopPhase.FINISH, LoopTransition.SUCCESS if success else LoopTransition.ERROR, "loop finished", {"error": error or ""})
+        self._publish_runtime_event("loop.finished", success=success, error=error or "", iterations=self.current_iteration, tool_calls=self._tool_call_count)
+
+        # Memory store：优先用 MemoryManager
+        if self.memory_manager:
+            try:
+                self._ensure_memory().store(f"task_result_{int(time.time())}",
+                    {"task": self._current_task[:200], "success": success, "result": content[:500]},
+                    tags=["result", "success" if success else "failed"])
+                self._ensure_memory().on_session_end(self.messages)
+            except Exception:
+                pass
+        else:
+            if self.long_term_memory and content:
+                try:
+                    self.long_term_memory.store(
+                        agent_name=self.config.name,
+                        key=f"task_result_{int(time.time())}",
+                        value={"task": self._current_task[:200], "success": success, "result": content[:500]},
+                        tags=["result", "success" if success else "failed"],
+                    )
+                except Exception:
+                    pass
+            if self.working_memory:
+                self.working_memory.set("last_result", {"success": success, "content": content[:500]})
+
+        try:
+            if hasattr(self.context_window, "on_session_end"):
+                self.context_window.on_session_end()
+        except Exception:
+            pass
+
+        # 输出 usage 统计
+        if self.config.report_progress:
+            try:
+                from runtime.core.llm.usage_pricing import get_usage_tracker, format_token_count, format_duration
+                tracker = get_usage_tracker()
+                tracker.record(model=self._current_model or self.config.model, agent_name=self.config.name)
+                # 简短输出
+                elapsed = time.time() - self.start_time if self.start_time else 0
+                self._print(f"  [用量] {format_duration(elapsed)} | model={self._current_model or self.config.model}")
+            except Exception:
+                pass
+        duration = time.time() - self.start_time
+
+        # 可观测性摘要
+        self.tracer.set_status("done" if success else "error")
+
+        result = AgentResult(
+            success=success,
+            content=content,
+            steps=list(self.steps),
+            error=error,
+            duration_seconds=duration,
+            iterations=self.current_iteration,
+            agent_name=self.config.name,
+            total_tool_calls=self._tool_call_count,
+            model_attempts=list(self.model_attempts),
+            run_trace=list(self.run_trace),
+            runtime_events=list(self.event_bus.list_events()),
+            compression_results=list(self.compression_results),
+        )
+
+        self._print(f"\n{'='*60}")
+        self._print(f"Agent: {self.config.name}")
+        self._print(f"结果: {'✓ 成功' if success else '✗ 失败'}")
+        self._print(f"迭代: {self.current_iteration}  工具调用: {self._tool_call_count}")
+        self._print(f"耗时: {duration:.1f}s")
+        if error:
+            self._print(f"错误: {error}")
+        self._print(f"{'='*60}\n")
+
+        logger.info(
+            "[%s] loop finished: success=%s iterations=%d tools=%d duration=%.1fs",
+            self.config.name, success, self.current_iteration,
+            self._tool_call_count, duration,
+        )
+        return result