cloneloop 0.1.0__py3-none-any.whl

mcp_ai_supervisor/web/core/agent_bridge.py

@@ -0,0 +1,957 @@
+#!/usr/bin/env python3
+"""
+qodercli Agent 桥接器模块
+=========================
+
+负责与 qodercli Agent 交互，包括：
+- 环境检查（安装、登录、模型探测）
+- Prompt 格式化与子进程调用
+- 响应解析（多策略 fallback）
+
+设计决策参考：
+- D49: Prompt 模板使用 $variable 语法
+- D56: _parse_response 多策略 fallback
+- D59/R20: 按 session_id 管理活跃子进程
+- D64: Prompt 只传路径和元数据
+- D72: 模型探测并行执行
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import re
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+from ...debug import server_debug_log as debug_log
+from ...log_writer import get_logger as _get_struct_logger
+
+logger = logging.getLogger(__name__)
+
+AGENT_TRACE_LOG = Path.home() / ".mcp" / "agent-trace.log"
+
+
+AGENT_FAILURE_CATEGORIES = frozenset({
+    "none",
+    "skill_compliance",
+    "content_quality",
+    "clarification",
+})
+
+
+def _normalize_failure_category(raw: object) -> str:
+    """未知或非法取值视为 none，保证下游只需处理固定枚举。"""
+    if raw is None:
+        return "none"
+    s = str(raw).strip().lower()
+    if s in AGENT_FAILURE_CATEGORIES:
+        return s
+    return "none"
+
+
+@dataclass
+class AgentReply:
+    """Agent 评估回复结果"""
+
+    is_valid: bool = True
+    is_lazy: bool = False
+    is_off_track: bool = False
+    needs_user_decision: bool = False
+    evaluation: str = ""
+    instruction: str = ""
+    raw_output: str = ""
+    success: bool = True
+    error: str = ""
+    execution_trace: dict = field(default_factory=dict)
+    failure_category: str = "none"
+
+
+class AgentBridge:
+    """qodercli Agent 桥接器 — 负责格式化 Prompt、调用 qodercli 子进程、解析回复"""
+
+    def __init__(self) -> None:
+        self.qodercli_path: str = os.getenv("MCP_QODERCLI_PATH", "qodercli")
+        self.model_priority: list[str] = ["ultimate", "auto"]
+        self.model: str = ""
+        self.total_timeout: int = int(os.getenv("MCP_AGENT_TOTAL_TIMEOUT", "300"))
+        self.max_turns: int = int(os.getenv("MCP_AGENT_MAX_TURNS", "10"))
+        self._setup_complete: bool = False
+        self._qodercli_available: bool = False
+        self._login_status: str = "unknown"
+        self._active_procs: dict[str, asyncio.subprocess.Process] = {}
+
+    # ─── 环境检查 ────────────────────────────────────────
+
+    async def _ensure_setup(self) -> bool:
+        """确保 qodercli 已安装、已登录、模型已配置（FR1）。"""
+        if self._setup_complete:
+            logger.debug("[AgentBridge] setup 已缓存，available=%s, model=%s", self._qodercli_available, self.model)
+            return self._qodercli_available
+
+        debug_log(f"[AgentBridge] 开始环境检查 (qodercli={self.qodercli_path})")
+        if not await self._check_installed():
+            logger.warning("[AgentBridge] qodercli 未安装，跳过模型探测")
+            self._qodercli_available = False
+            return False
+
+        results = await asyncio.gather(
+            *[self._probe_model(name) for name in self.model_priority],
+            return_exceptions=True,
+        )
+        for i, ok in enumerate(results):
+            if ok is True:
+                self.model = self.model_priority[i]
+                self._login_status = "logged_in"
+                self._qodercli_available = True
+                self._setup_complete = True
+                debug_log(f"[AgentBridge] qodercli 可用，使用模型: {self.model}")
+                return True
+
+        logger.warning("[AgentBridge] 所有模型探测失败，login_status=not_logged_in，探测结果: %s", results)
+        self._login_status = "not_logged_in"
+        self._qodercli_available = False
+        return False
+
+    async def recheck_setup(self) -> bool:
+        """重置缓存后重新执行环境检查"""
+        logger.debug("[AgentBridge] recheck_setup: 重置缓存并重新检查")
+        self._setup_complete = False
+        return await self._ensure_setup()
+
+    async def _check_installed(self) -> bool:
+        """检查 qodercli 是否安装"""
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                self.qodercli_path, "--version",
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            await asyncio.wait_for(proc.wait(), timeout=10)
+            return proc.returncode == 0
+        except (FileNotFoundError, asyncio.TimeoutError, OSError):
+            logger.warning("qodercli 未安装或不可用: %s", self.qodercli_path)
+            return False
+
+    async def _probe_model(self, model_name: str) -> bool:
+        """用简单调用探测模型是否可用"""
+        logger.debug("[AgentBridge] 探测模型: %s", model_name)
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                self.qodercli_path, "-p", "hello",
+                "--model", model_name,
+                "--max-turns", "1",
+                "--output-format", "text",
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            await asyncio.wait_for(proc.communicate(), timeout=30)
+            return proc.returncode == 0
+        except (asyncio.TimeoutError, OSError, Exception):
+            return False
+
+    # ─── 核心评估 ────────────────────────────────────────
+
+    async def evaluate(
+        self,
+        context: dict,
+        project_dir: str,
+        session_id: str = "",
+        task_complete: bool = False,
+    ) -> tuple[AgentReply, str]:
+        """调用 qodercli Agent 评估 AI 的工作。
+
+        Args:
+            context: ContextCollector.collect() 输出的结构化上下文
+            project_dir: 项目目录绝对路径
+            session_id: MCP 侧会话 ID，用于子进程管理和取消（R20）
+            task_complete: AI 是否声称任务完成
+
+        Returns:
+            tuple[AgentReply, str]: (评估结果, session_id)
+        """
+        # [BRIDGE_CALL_START] 记录 Agent 评估调用开始
+        _bridge_start = __import__('time').monotonic()
+        _bridge_logger = _get_struct_logger("agent", project_directory=project_dir)
+        _bridge_logger.info(
+            f"project={os.path.basename(project_dir)} session={session_id[:8] if session_id else '(none)'}",
+            f"[BRIDGE_CALL_START] 开始处理 Agent 评估调用 task_complete={task_complete}",
+        )
+        debug_log(
+            f"[AgentBridge] evaluate 开始: session={session_id}, "
+            f"task_complete={task_complete}"
+        )
+        logger.info(
+            "[AgentBridge] evaluate 开始 project=%r session=%s task_complete=%s",
+            project_dir,
+            session_id or "(none)",
+            task_complete,
+        )
+
+        if not await self._ensure_setup():
+            logger.warning("[AgentBridge] evaluate 中止: setup 失败, login=%s", self._login_status)
+            if self._login_status == "not_logged_in":
+                return (
+                    AgentReply(
+                        success=False,
+                        error="qodercli_not_logged_in",
+                        instruction="请先在终端登录 qodercli：执行 qodercli 后输入 /login",
+                    ),
+                    "",
+                )
+            return (
+                AgentReply(
+                    success=False,
+                    error="qodercli_not_available",
+                    instruction="",
+                ),
+                "",
+            )
+
+        prompt = self._format_prompt(context, task_complete=task_complete)
+        logger.info(
+            "[AgentBridge] Prompt 已生成 len=%d",
+            len(prompt),
+        )
+        debug_log(f"[AgentBridge] MCP→Agent Prompt 长度: {len(prompt)} 字符")
+        debug_log(f"[AgentBridge] MCP→Agent Prompt 全文:\n{prompt}")
+
+        try:
+            raw_output = await self._call_qodercli(
+                prompt, project_dir, session_id,
+            )
+            debug_log(f"[AgentBridge] qodercli 调用成功, 输出长度: {len(raw_output)}")
+        except asyncio.TimeoutError:
+            # [BRIDGE_ERROR] Agent 调用超时
+            _bridge_logger.error(
+                f"project={os.path.basename(project_dir)} session={session_id[:8] if session_id else '(none)'} "
+                f"error_type=timeout",
+                f"[BRIDGE_ERROR] qodercli 调用超时 ({self.total_timeout}s)",
+                exc_info=True,
+            )
+            logger.error("[AgentBridge] qodercli 调用超时 (%ds)", self.total_timeout)
+            return (AgentReply(success=False, error="timeout", instruction=""), "")
+        except RuntimeError as e:
+            error_msg = str(e)
+            # [BRIDGE_ERROR] 运行时错误
+            _bridge_logger.error(
+                f"project={os.path.basename(project_dir)} session={session_id[:8] if session_id else '(none)'} "
+                f"error_type=runtime_error",
+                f"[BRIDGE_ERROR] qodercli 运行时错误: {error_msg[:200]}",
+                exc_info=True,
+            )
+            logger.error("[AgentBridge] qodercli 运行时错误: %s", error_msg[:300])
+            if any(kw in error_msg.lower() for kw in ("login", "unauthorized")):
+                return (
+                    AgentReply(
+                        success=False,
+                        error="qodercli_not_logged_in",
+                        instruction="",
+                    ),
+                    "",
+                )
+            return (
+                AgentReply(
+                    success=False,
+                    error=f"qodercli_error: {error_msg[:200]}",
+                    raw_output=error_msg,
+                ),
+                "",
+            )
+
+        trace = self._extract_execution_trace(raw_output)
+        self._log_execution_trace(trace, project_dir, session_id)
+        logger.info(
+            "[AgentBridge] 执行轨迹摘要: tools=%d, files_read=%d, skills=%s, commands=%d",
+            len(trace["tool_calls"]), len(trace["files_read"]),
+            trace["skills_loaded"] or "(无)", len(trace["commands_run"]),
+        )
+
+        reply = self._parse_response(raw_output)
+        reply.execution_trace = trace
+
+        # [BRIDGE_CALL_RETURN] 记录 Agent 评估调用返回
+        _bridge_duration_ms = int((__import__('time').monotonic() - _bridge_start) * 1000)
+        _result_type = "success" if reply.success else f"failed:{reply.error}"
+        _bridge_logger.info(
+            f"project={os.path.basename(project_dir)} session={session_id[:8] if session_id else '(none)'} "
+            f"result_type={_result_type} duration_ms={_bridge_duration_ms}",
+            "[BRIDGE_CALL_RETURN] Agent 评估调用返回结果",
+        )
+        logger.info(
+            "[AgentBridge] 评估结果: is_valid=%s, success=%s, evaluation=%s",
+            reply.is_valid, reply.success,
+            (reply.evaluation[:100] + "...") if len(reply.evaluation) > 100 else reply.evaluation,
+        )
+        debug_log(
+            f"[AgentBridge] 解析结果详情: is_valid={reply.is_valid}, is_lazy={reply.is_lazy}, "
+            f"is_off_track={reply.is_off_track}, needs_user_decision={reply.needs_user_decision}, "
+            f"error={reply.error}\n"
+            f"  evaluation: {reply.evaluation or '(空)'}\n"
+            f"  instruction: {reply.instruction[:500] if reply.instruction else '(空)'}"
+        )
+        return (reply, "")
+
+    # ─── Prompt 格式化 ───────────────────────────────────────
+
+    @staticmethod
+    def _format_changed_files_block(cur: list, all_f: list) -> str:
+        """本轮与累计文件列表相同时只保留一节，减少重复。"""
+        cur = list(cur or [])
+        all_f = list(all_f or [])
+        if cur == all_f:
+            body = "\n".join(cur) if cur else "(无)"
+            return (
+                "### 变更文件\n"
+                + body
+                + "\n\n请自行通过 `git diff -- <file>` 查看具体改动。"
+            )
+        return (
+            "### 本轮变更文件\n"
+            + ("\n".join(cur) if cur else "(无)")
+            + "\n\n### 累计变更文件\n"
+            + ("\n".join(all_f) if all_f else "(无)")
+            + "\n\n请自行通过 `git diff -- <file>` 查看具体改动。"
+        )
+
+    @staticmethod
+    def _format_sub_agent_paths(paths: list | None) -> str:
+        """将子 Agent SKILL.md 路径列表格式化为 Prompt 字符串。"""
+        if not paths:
+            return "(无可用子 Agent)"
+        return "\n".join(f"- {p}" for p in paths)
+
+    def _format_prompt(self, context: dict, task_complete: bool = False) -> str:
+        """将上下文格式化为 Prompt（D49 $variable 语法，D64 只传路径）。"""
+        from string import Template
+
+        skills_dirs = context.get("project_skills_dirs", [])
+        skills_dirs_str = (
+            "\n".join(f"- {d}" for d in skills_dirs)
+            if skills_dirs
+            else "(无)"
+        )
+        project_dir = (context.get("project_dir") or "").strip()
+        user_task = context.get("original_task", "") or "(无)"
+        changed_files_block = AgentBridge._format_changed_files_block(
+            context.get("changed_files_this_round", []),
+            context.get("changed_files_all", []),
+        )
+
+        template_vars = {
+            "project_dir": project_dir,
+            "retry_count": str(context.get("retry_count", 0)),
+            "task_phase": context.get("task_phase", ""),
+            "completion_attempts": str(context.get("completion_attempts", 0)),
+            "user_task": user_task,
+            "project_rules_dir": context.get("project_rules_dir", "(无)"),
+            "project_skills_dirs": skills_dirs_str,
+            "sub_agent_skill_paths": AgentBridge._format_sub_agent_paths(
+                context.get("sub_agent_skill_paths", [])
+            ),
+            "current_summary": context.get("current_summary", ""),
+            "current_intention": context.get("current_intention", ""),
+            "changed_files_block": changed_files_block,
+            "agent_deny_count": str(context.get("agent_deny_count", 0)),
+            "task_complete": str(task_complete).lower(),
+        }
+        return Template(PROMPT_TEMPLATE).safe_substitute(template_vars)
+
+    # ─── 子进程调用 ──────────────────────────
+
+    async def _call_qodercli(
+        self, prompt: str, project_dir: str, session_id: str = "",
+    ) -> str:
+        """subprocess 调用 qodercli（R20: 按 session_id 管理进程，D51: token 过期检测）"""
+        cmd = [
+            self.qodercli_path,
+            "-p", prompt,
+            "--model", self.model,
+            "--max-turns", str(self.max_turns),
+            "--output-format", "stream-json",
+            "-w", project_dir,
+        ]
+
+        cmd_brief = (
+            f"{self.qodercli_path} -p \"<prompt {len(prompt)} chars>\" "
+            f"--model {self.model} --max-turns {self.max_turns} "
+            f"--output-format stream-json -w {project_dir}"
+        )
+        debug_log(
+            f"[AgentBridge] qodercli 调用命令（摘要）: {cmd_brief} "
+            f"(timeout={self.total_timeout}s, session={session_id})"
+        )
+        _stream_line_limit = 16 * 1024 * 1024
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            limit=_stream_line_limit,
+        )
+        if session_id:
+            self._active_procs[session_id] = proc
+
+        collected_lines: list[str] = []
+        stderr_chunks: list[bytes] = []
+        stream_log_prev_line: str | None = None
+        try:
+            async def _stream_stdout():
+                nonlocal stream_log_prev_line
+
+                assert proc.stdout is not None
+                while True:
+                    line_bytes = await proc.stdout.readline()
+                    if not line_bytes:
+                        break
+                    line = line_bytes.decode("utf-8", errors="replace").rstrip()
+                    collected_lines.append(line)
+                    try:
+                        if line != stream_log_prev_line:
+                            stream_log_prev_line = line
+                            self._log_stream_event(line)
+                    except Exception:
+                        pass
+
+            async def _drain_stderr():
+                assert proc.stderr is not None
+                while True:
+                    chunk = await proc.stderr.read(4096)
+                    if not chunk:
+                        break
+                    stderr_chunks.append(chunk)
+
+            await asyncio.wait_for(
+                asyncio.gather(_stream_stdout(), _drain_stderr()),
+                timeout=self.total_timeout,
+            )
+            await proc.wait()
+        except asyncio.TimeoutError:
+            proc.kill()
+            await proc.wait()
+            raise
+        finally:
+            self._active_procs.pop(session_id, None)
+
+        stderr_bytes = b"".join(stderr_chunks)
+        raw = "\n".join(collected_lines)
+
+        debug_log(f"[AgentBridge] qodercli 退出码: {proc.returncode}, lines={len(collected_lines)}, stderr={len(stderr_bytes)} bytes")
+        if proc.returncode != 0:
+            stderr_text = stderr_bytes.decode("utf-8", errors="replace")
+            logger.error("[AgentBridge] qodercli 非零退出: stderr=%s", stderr_text[:500])
+            if any(
+                kw in stderr_text.lower()
+                for kw in ("unauthorized", "login", "expired", "token")
+            ):
+                self._setup_complete = False
+                self._login_status = "not_logged_in"
+                self._qodercli_available = False
+            raise RuntimeError(
+                f"qodercli 退出码 {proc.returncode}: {stderr_text[:500]}"
+            )
+        debug_log(f"[AgentBridge] Agent→MCP 原始输出:\n{raw[:3000]}")
+        return raw
+
+    @staticmethod
+    def _log_stream_event(line: str) -> None:
+        """实时记录 stream-json 事件到日志。"""
+        if not line.strip() or not line.strip().startswith("{"):
+            return
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            return
+
+        ev_type = event.get("type", "")
+        ev_sub = event.get("subtype", "")
+        msg = event.get("message", {})
+        contents = msg.get("content", [])
+
+        if ev_type == "system" and ev_sub == "init":
+            model = event.get("model", "?")
+            tools = event.get("tools", [])
+            logger.info("[AgentBridge][STREAM] 初始化: model=%s, tools=%d个", model, len(tools))
+
+        elif ev_type == "assistant":
+            _seen_read_paths: set[str] = set()
+            _seen_text_prefix: set[str] = set()
+            for item in contents:
+                if item.get("type") == "function":
+                    name = item.get("name", "?")
+                    try:
+                        inp = json.loads(item.get("input", "{}"))
+                    except (json.JSONDecodeError, TypeError):
+                        inp = {}
+
+                    if name == "Read":
+                        fp = inp.get("file_path", "?")
+                        if fp in _seen_read_paths:
+                            continue
+                        _seen_read_paths.add(str(fp))
+                        logger.info("[AgentBridge][STREAM] 📖 Agent 读取文件: %s", fp)
+                    elif name in ("Bash", "BashOutput"):
+                        logger.info("[AgentBridge][STREAM] 🔧 Agent 执行命令: %s", inp.get("command", "?")[:200])
+                    elif name == "Skill":
+                        skill = inp.get("skill_name", "") or inp.get("name", "")
+                        logger.info("[AgentBridge][STREAM] 📚 Agent 加载 Skill: %s", skill)
+                    elif name in ("Edit", "Write"):
+                        logger.info("[AgentBridge][STREAM] ✏️ Agent 写入文件: %s", inp.get("file_path", "?"))
+                    elif name == "Grep":
+                        logger.info("[AgentBridge][STREAM] 🔍 Agent Grep: pattern=%s path=%s",
+                                    inp.get("pattern", ""), inp.get("path", ""))
+                    else:
+                        logger.info("[AgentBridge][STREAM] 🔧 Agent 调用工具: %s", name)
+
+                elif item.get("type") == "text":
+                    text = item.get("text", "")
+                    if text:
+                        tp = text[:200]
+                        if tp in _seen_text_prefix:
+                            continue
+                        _seen_text_prefix.add(tp)
+                        logger.info("[AgentBridge][STREAM] 💬 Agent 输出文本: %s", tp)
+
+        elif ev_type == "user":
+            for item in contents:
+                if item.get("type") == "tool_result":
+                    name = item.get("name", "?")
+                    is_err = item.get("is_error", False)
+                    status = "❌ 失败" if is_err else "✅ 成功"
+                    logger.info("[AgentBridge][STREAM] %s 工具结果: %s", status, name)
+
+        elif ev_type == "result":
+            logger.info("[AgentBridge][STREAM] 🏁 Agent 执行完毕")
+
+    # ─── 响应解析 ────────────────────────────────────────
+
+    def _parse_response(self, output: str) -> AgentReply:
+        """解析 qodercli --output-format=stream-json 的输出（D56 多策略 fallback）。"""
+        logger.debug("[AgentBridge] 开始解析响应, 长度=%d", len(output))
+        try:
+            text = self._extract_agent_text(output)
+        except RuntimeError as e:
+            error_type = str(e)
+            logger.warning("[AgentBridge] qodercli 返回错误响应: %s", error_type)
+            friendly = {
+                "qodercli_error_error_max_turns": "Agent 评估未在规定轮次内完成，请重试。",
+                "qodercli_error_error_timeout": "Agent 评估超时，请重试。",
+            }
+            msg = friendly.get(error_type, f"Agent 调用异常: {error_type}")
+            return AgentReply(
+                success=False,
+                error=error_type,
+                instruction=msg,
+                evaluation=msg,
+                raw_output=output,
+            )
+        if text is None:
+            logger.warning("[AgentBridge] 无法提取 Agent text, 走兜底")
+            return self._fallback_raw_output(output)
+        logger.debug("[AgentBridge] Agent text 提取成功, 长度=%d", len(text))
+
+        data = self._extract_json_from_text(text)
+        if data is None:
+            logger.warning("[AgentBridge] 内层 JSON 提取失败, Agent 未按格式输出, text=%s", text[:200])
+            return self._fallback_agent_text(text, output)
+
+        instruction = data.get("instruction", "")
+        evaluation = data.get("evaluation", "")
+        fc = _normalize_failure_category(data.get("failure_category"))
+        debug_log(
+            f"[AgentBridge] D31 字段分离: instruction={len(instruction)} chars, "
+            f"evaluation={len(evaluation)} chars, is_valid={data.get('is_valid', True)}, "
+            f"needs_user_decision={data.get('needs_user_decision', False)}, "
+            f"failure_category={fc}"
+        )
+        return AgentReply(
+            is_valid=data.get("is_valid", True),
+            is_lazy=data.get("is_lazy", False),
+            is_off_track=data.get("is_off_track", False),
+            needs_user_decision=data.get("needs_user_decision", False),
+            evaluation=evaluation,
+            instruction=instruction,
+            raw_output=output,
+            success=True,
+            failure_category=fc,
+        )
+
+    def _extract_agent_text(self, output: str) -> str | None:
+        """从 qodercli stdout 中提取 Agent 的实际文本内容。
+
+        兼容两代 stream-json schema：
+          - 新版 (qodercli >= 1.1.x)：{"type":"result","subtype":"success","result":"<正文>"}
+            正文在顶层 result 字段；错误时 is_error=true / subtype!=success。
+          - 老版：{"type":"result","message":{"content":[{"text":"<正文>"}]}}
+        另外新版会在会话启动时先输出一串 hook 事件
+        ({"type":"system","subtype":"hook_started",...})，若解析失败走到
+        兜底会把这些噪声当成回复发给 AI（历史 bug），因此本函数尽可能多策略命中。
+        """
+        lines = output.strip().splitlines()
+
+        for line in reversed(lines):
+            line = line.strip()
+            if not line or not line.startswith("{"):
+                continue
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            if obj.get("type") == "error":
+                subtype = obj.get("subtype", "unknown")
+                logger.warning("[AgentBridge] qodercli 返回错误: subtype=%s, code=%s",
+                               subtype, obj.get("error_code"))
+                raise RuntimeError(f"qodercli_error_{subtype}")
+
+            if obj.get("type") == "result":
+                # 新版 schema：错误信号在 result 行里（is_error / subtype）
+                if obj.get("is_error") is True:
+                    subtype = obj.get("subtype", "unknown")
+                    logger.warning("[AgentBridge] qodercli result 行报错: subtype=%s", subtype)
+                    raise RuntimeError(f"qodercli_error_{subtype}")
+                # 新版 schema：正文在顶层 result 字段
+                result_text = obj.get("result")
+                if isinstance(result_text, str) and result_text.strip():
+                    return result_text
+                # 老版 schema：message.content[0].text
+                try:
+                    return obj["message"]["content"][0]["text"]
+                except (KeyError, IndexError, TypeError):
+                    logger.warning("[AgentBridge] result 行无法提取正文, keys=%s", list(obj.keys()))
+                    continue
+
+        # 兜底 1：没有 result 行（异常退出/截断）时，拼接 assistant 消息的 text 块
+        assistant_texts: list[str] = []
+        for line in lines:
+            line = line.strip()
+            if not line or not line.startswith("{"):
+                continue
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if obj.get("type") != "assistant":
+                continue
+            for item in (obj.get("message", {}) or {}).get("content", []) or []:
+                if isinstance(item, dict) and item.get("type") == "text" and item.get("text"):
+                    assistant_texts.append(item["text"])
+        if assistant_texts:
+            logger.info("[AgentBridge] 无 result 行，从 %d 段 assistant text 拼接正文", len(assistant_texts))
+            return "".join(assistant_texts)
+
+        # 兜底 2：输出里直接包含评估 JSON 字段（非 stream-json 形态）
+        if '"is_valid"' in output or '"instruction"' in output:
+            return output
+
+        logger.warning("[AgentBridge] _extract_agent_text: 所有策略均失败, output 前200字: %s", output[:200])
+        return None
+
+    def _extract_json_from_text(self, text: str) -> dict | None:
+        """从 text 中提取 JSON（支持 markdown code block、裸 JSON、正则、引号修复）"""
+        candidates: list[str] = []
+        inner_json = re.search(r"```(?:json)?\s*\n(.*?)\n```", text, re.DOTALL)
+        if inner_json:
+            candidates.append(inner_json.group(1))
+        candidates.append(text)
+        json_match = re.search(r'\{[^{}]*"is_valid"[^{}]*\}', text, re.DOTALL)
+        if json_match:
+            candidates.append(json_match.group(0))
+
+        for i, candidate in enumerate(candidates):
+            try:
+                data = json.loads(candidate)
+                labels = ["code block", "裸 JSON", "正则 is_valid"]
+                debug_log(f"[AgentBridge] _extract_json_from_text: 从 {labels[i] if i < len(labels) else '候选'} 提取成功")
+                return data
+            except json.JSONDecodeError:
+                continue
+
+        for candidate in candidates:
+            repaired = self._try_repair_json(candidate)
+            if repaired is not None:
+                debug_log("[AgentBridge] _extract_json_from_text: JSON 引号修复后提取成功")
+                return repaired
+
+        logger.warning("[AgentBridge] _extract_json_from_text: 所有策略均失败, text 前300字: %s", text[:300])
+        return None
+
+    @staticmethod
+    def _try_repair_json(text: str) -> dict | None:
+        """修复嵌套 JSON 中字符串值内未转义引号的问题。"""
+        lines = text.strip().split("\n")
+        repaired: list[str] = []
+        for line in lines:
+            m = re.match(r'^(\s*"[^"]+"\s*:\s*)"(.*)"(,?)$', line)
+            if m:
+                prefix, value, comma = m.group(1), m.group(2), m.group(3)
+                value = value.replace('\\"', '"').replace('"', '\\"')
+                repaired.append(f'{prefix}"{value}"{comma}')
+            else:
+                repaired.append(line)
+        try:
+            return json.loads("\n".join(repaired))
+        except json.JSONDecodeError:
+            return None
+
+    def _fallback_agent_text(self, text: str, raw_output: str) -> AgentReply:
+        """text 已提取但不含评估 JSON：Agent 可能去执行了操作而非评估。"""
+        plain_text = text[:1000] if len(text) > 1000 else text
+        return AgentReply(
+            is_valid=False,
+            instruction=f"[Agent 未按评估格式输出] {plain_text}",
+            raw_output=raw_output,
+            success=True,
+            evaluation="Agent 未输出评估 JSON，可能在执行操作而非评估",
+        )
+
+    def _fallback_raw_output(self, output: str) -> AgentReply:
+        """完全无法提取文本时的兜底（R16: is_valid=False 防误放行）。
+
+        注意：不再直接把原始 stdout 前 1000 字当回复——那会把 stream-json 的
+        hook 事件噪声（{"type":"system","subtype":"hook_started",...}）原样发给
+        被监工 AI 和前端 UI（历史 bug）。先过滤掉 JSON 事件行，只保留非 JSON 的
+        自然文本；若过滤后为空，给出固定的友好提示而非噪声。
+        """
+        non_json_lines = [
+            ln for ln in output.strip().splitlines()
+            if ln.strip() and not ln.strip().startswith("{")
+        ]
+        plain_text = "\n".join(non_json_lines).strip()
+        if not plain_text:
+            plain_text = "（Agent 评估输出无法解析，本轮未生成有效回复，请重试或人工输入）"
+        elif len(plain_text) > 1000:
+            plain_text = plain_text[:1000]
+        return AgentReply(
+            is_valid=False,
+            instruction=plain_text,
+            raw_output=output,
+            success=True,
+            evaluation="(Agent 输出格式异常，已过滤 JSON 事件噪声后返回)",
+        )
+
+    # ─── 执行轨迹提取与日志 ─────────────────────────────────
+
+    @staticmethod
+    def _extract_execution_trace(output: str) -> dict:
+        """从 stream-json 输出中提取 Agent 完整执行轨迹。"""
+        trace: dict = {
+            "tool_calls": [],
+            "skills_loaded": [],
+            "files_read": [],
+            "files_written": [],
+            "commands_run": [],
+            "total_turns": 0,
+        }
+
+        pending_calls: dict[str, dict] = {}
+
+        for line in output.strip().splitlines():
+            line = line.strip()
+            if not line or not line.startswith("{"):
+                continue
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            ev_type = event.get("type", "")
+            msg = event.get("message", {})
+            contents = msg.get("content", [])
+
+            if ev_type == "assistant":
+                for item in contents:
+                    if item.get("type") == "function":
+                        call_id = item.get("id", "")
+                        name = item.get("name", "")
+                        try:
+                            inp = json.loads(item.get("input", "{}"))
+                        except (json.JSONDecodeError, TypeError):
+                            inp = {"_raw": item.get("input", "")}
+
+                        call_record = {"name": name, "input": inp}
+                        pending_calls[call_id] = call_record
+
+                        if name == "Read":
+                            path = inp.get("file_path", "")
+                            if path and path not in trace["files_read"]:
+                                trace["files_read"].append(path)
+                        elif name in ("Edit", "Write"):
+                            path = inp.get("file_path", "")
+                            if path and path not in trace["files_written"]:
+                                trace["files_written"].append(path)
+                        elif name in ("Bash", "BashOutput"):
+                            cmd = inp.get("command", "")
+                            if cmd:
+                                trace["commands_run"].append(cmd)
+                        elif name == "Skill":
+                            skill_name = inp.get("skill_name", "") or inp.get("name", "")
+                            if skill_name and skill_name not in trace["skills_loaded"]:
+                                trace["skills_loaded"].append(skill_name)
+                        elif name == "Grep":
+                            path = inp.get("path", "")
+                            if path and path not in trace["files_read"]:
+                                trace["files_read"].append(f"[Grep] {path}")
+                        elif name == "Glob":
+                            pattern = inp.get("pattern", "")
+                            if pattern:
+                                trace["files_read"].append(f"[Glob] {pattern}")
+
+                        trace["total_turns"] += 1
+
+            elif ev_type == "user":
+                for item in contents:
+                    if item.get("type") == "tool_result":
+                        call_id = item.get("tool_use_id", "")
+                        record = pending_calls.pop(call_id, None)
+                        if record is not None:
+                            result_content = item.get("content", "")
+                            if isinstance(result_content, str) and len(result_content) > 500:
+                                result_content = result_content[:500] + "...(truncated)"
+                            record["result"] = result_content
+                            record["is_error"] = item.get("is_error", False)
+                            trace["tool_calls"].append(record)
+
+        for call_id, record in pending_calls.items():
+            record["result"] = "(no result captured)"
+            record["is_error"] = False
+            trace["tool_calls"].append(record)
+
+        return trace
+
+    @staticmethod
+    def _format_trace_text(trace: dict, project_dir: str, session_id: str = "") -> str:
+        """将执行轨迹格式化为可读文本。"""
+        lines = [
+            f"{'=' * 60}",
+            f"Agent 执行轨迹 | project={project_dir} | session={session_id}",
+            f"{'=' * 60}",
+            f"总工具调用次数: {trace['total_turns']}",
+        ]
+
+        if trace["skills_loaded"]:
+            lines.append(f"  Skills ({len(trace['skills_loaded'])}个): {', '.join(trace['skills_loaded'])}")
+        else:
+            lines.append("  Skills: (无) Agent 未读取任何 Skill")
+
+        if trace["files_read"]:
+            lines.append(f"  读取文件 ({len(trace['files_read'])}个):")
+            for f in trace["files_read"]:
+                lines.append(f"    - {f}")
+        else:
+            lines.append("  读取文件: (无) Agent 未读取任何文件")
+
+        if trace["files_written"]:
+            lines.append(f"  写入文件 ({len(trace['files_written'])}个):")
+            for f in trace["files_written"]:
+                lines.append(f"    - {f}")
+
+        if trace["commands_run"]:
+            lines.append(f"  执行命令 ({len(trace['commands_run'])}个):")
+            for c in trace["commands_run"]:
+                lines.append(f"    $ {c[:200]}")
+
+        lines.append(f"  工具调用明细 ({len(trace['tool_calls'])}个):")
+        for i, call in enumerate(trace["tool_calls"], 1):
+            name = call.get("name", "?")
+            inp = call.get("input", {})
+            is_err = call.get("is_error", False)
+            status = "FAIL" if is_err else "OK"
+
+            inp_summary = ""
+            if name == "Read":
+                inp_summary = inp.get("file_path", "")
+            elif name in ("Bash", "BashOutput"):
+                inp_summary = inp.get("command", "")[:150]
+            elif name in ("Edit", "Write"):
+                inp_summary = inp.get("file_path", "")
+            elif name == "Skill":
+                inp_summary = inp.get("skill_name", "") or inp.get("name", "")
+            elif name == "Grep":
+                inp_summary = f"pattern={inp.get('pattern', '')} path={inp.get('path', '')}"
+            elif name == "Glob":
+                inp_summary = inp.get("pattern", "")
+            else:
+                inp_summary = json.dumps(inp, ensure_ascii=False)[:150]
+
+            lines.append(f"    [{i}] {name} [{status}] {inp_summary}")
+
+        lines.append(f"{'=' * 60}")
+        return "\n".join(lines)
+
+    @staticmethod
+    def _log_execution_trace(trace: dict, project_dir: str, session_id: str = "") -> None:
+        """将执行轨迹写入日志和 agent-trace.log（归档）。"""
+        trace_text = AgentBridge._format_trace_text(trace, project_dir, session_id)
+
+        for line in trace_text.split("\n"):
+            logger.info("[AgentBridge] %s", line)
+
+        try:
+            AGENT_TRACE_LOG.parent.mkdir(parents=True, exist_ok=True)
+            ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+            with open(AGENT_TRACE_LOG, "a", encoding="utf-8") as fh:
+                fh.write(f"\n[{ts}] {trace_text}\n")
+        except Exception as e:
+            logger.warning("[AgentBridge] 写入 agent-trace.log 失败: %s", e)
+
+
+# ─── Prompt 模板 ──────────────────────────────────────────
+
+PROMPT_TEMPLATE = """\
+# AI 监督评估任务
+
+## 角色
+
+你是 **工作质量监督者**（主 Agent）。请结合工作区内容判断主 AI 的工作是否达标。
+
+## 项目信息
+
+- 工作区: $project_dir
+- 迭代轮数: $retry_count
+- 监管阶段: $task_phase
+
+## 用户任务
+
+$user_task
+
+## 规则与 Skill 目录（路径须自行 Read）
+
+- 规则目录: $project_rules_dir
+- 项目内 Skill 目录: $project_skills_dirs
+
+## 可调度的子 Agent Skill
+
+以下是可用的子 Agent SKILL.md 路径，当需要调度子 Agent 时请 Read 对应文件：
+$sub_agent_skill_paths
+
+## AI 本轮行为
+
+### 工作摘要
+$current_summary
+
+### 完整意图
+$current_intention
+
+## 变更与产物线索
+
+$changed_files_block
+
+## 调用状态
+
+- AI 声称任务完成: $task_complete
+- 监工连续否决次数: $agent_deny_count（达 5 次时 MCP 弹窗由用户处理）
+
+## 输出要求
+
+请输出 JSON 格式评估结果，包含以下字段：
+- `is_valid` (bool): 工作是否合格
+- `is_lazy` (bool): 是否偷懒/敷衍
+- `is_off_track` (bool): 是否跑偏
+- `needs_user_decision` (bool): 是否需要用户决策
+- `evaluation` (string): 评估说明（宜 80 字以内）
+- `instruction` (string): 返回给主 AI 的指令（宜 500 字以内）
+- `failure_category` (string): `none` | `skill_compliance` | `content_quality` | `clarification`
+"""