# Agent 执行环境修复（Spec-1）Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 修复 AgentLoop 两个工程缺陷（deepseek 输出变体解析失败 0 步阵亡、LLM 瞬时异常无步级重试）与 view_node 摘要吞实体问题。

**Architecture:** 三处独立小改动：(A1) `_parse_response` 前置围栏剥除 + action.args 平铺收拢；(A2) `run()` Phase 1 增加步级重试循环（显式可重试异常元组，默认 `(TimeoutError, OSError)`，20s/40s 退避）；(B) `TreeEnvironment` 新增结构化实体字段提取，`SearchToolDispatcher._handle_view_node` 在摘要后确定性追加 `[实体]`/`[画面文字]` 区块。

**Tech Stack:** Python 3.11 / pytest + pytest-asyncio / json_repair。设计文档：`research-wiki/designs/2026-07-11-agent-runtime-fixes-design.md`。

**设计变更备忘**：设计文档 A2 提到 openai SDK 传输异常入可重试元组——实现时收窄为默认 `(TimeoutError, OSError)`（`ssl.SSLError`、`ConnectionError` 均为 OSError 子类，覆盖实测穿透案例 796-3；openai API 类异常由 GovernedLLMClient 内部重试栈负责，且 core/ 不得依赖 openai）。元组保留为构造参数，未来可在组合根扩展。

---

### Task 1: A1 解析容错——围栏剥除 + args 平铺收拢

**Files:**
- Modify: `core/agent/loop.py`（`_parse_response`，约 265-300 行；模块顶部加正则常量）
- Test: `tests/unit/test_agent_loop.py`（追加测试类）

- [ ] **Step 1: 写失败测试（用 637-3 生产环境真实坏输出的结构等价样本）**

在 `tests/unit/test_agent_loop.py` 末尾追加：

```python
# ── A1 解析容错测试（Spec-1）──────────────────────────────────

# 生产真实样本结构：尾部围栏残留 + action.args 平铺（开头围栏场景由
# test_leading_json_fence 单独覆盖）
_REAL_FLAT_FENCED = """{
  "plan": {
    "goal": "从三个L1根节点开始建立全局认知",
    "tool": "view_node",
    "reason": "三个L1节点覆盖整个视频"
  },
  "action": {
    "tool": "view_node",
    "node_id": "J5Npf2xJpag_L1_000",
    "question": "What is the overall topic of this video?"
  }
}
```"""


class TestParseNormalization:
    """deepseek 输出变体（args 平铺 + ```json 围栏）归一化。"""

    def _parse(self, content: str):
        loop = AgentLoop(llm=AsyncMock(), max_steps=10)
        return loop._parse_response(_make_response(content))

    def test_flat_args_with_trailing_fence(self) -> None:
        """生产样本：action 平铺 node_id/question + 尾部围栏。"""
        parsed = self._parse(_REAL_FLAT_FENCED)
        assert parsed is not None
        action = parsed[4]
        assert action["tool"] == "view_node"
        assert action["args"] == {
            "node_id": "J5Npf2xJpag_L1_000",
            "question": "What is the overall topic of this video?",
        }

    def test_leading_json_fence(self) -> None:
        content = '```json\n{"reflect": {}, "plan": {}, "action": {"tool": "submit_answer", "args": {"answer": "A"}}}\n```'
        parsed = self._parse(content)
        assert parsed is not None
        assert parsed[4]["args"] == {"answer": "A"}

    def test_nested_args_unchanged(self) -> None:
        """标准嵌套结构不受归一化影响。"""
        parsed = self._parse(_submit_json("B"))
        assert parsed is not None
        assert parsed[4] == {"tool": "submit_answer", "args": {"answer": "B"}}

    def test_action_missing_tool_still_rejected(self) -> None:
        content = json.dumps({"reflect": {}, "plan": {}, "action": {"node_id": "x"}})
        assert self._parse(content) is None

    def test_empty_content_still_rejected(self) -> None:
        assert self._parse("") is None
```

- [ ] **Step 2: 运行测试确认失败**

Run: `conda run -n Video-Tree-TRM pytest tests/unit/test_agent_loop.py::TestParseNormalization -v`
Expected: `test_flat_args_with_trailing_fence` FAIL（返回 None）；`test_nested_args_unchanged` 等可能已 PASS。

- [ ] **Step 3: 实现归一化**

`core/agent/loop.py` 模块顶部（`import re` 如缺则加，紧邻其他 import）：

```python
# deepseek 等模型稳定输出变体：```json 围栏包裹 JSON 体
_CODE_FENCE_RE = re.compile(r"^\s*```(?:json)?\s*\n?|\n?\s*```\s*$")
```

`_parse_response` 中两处修改。其一，repair 前剥围栏：

```python
        repaired = repair_json(_CODE_FENCE_RE.sub("", content).strip())
```

其二，action 校验前收拢平铺参数（替换原 `action = data["action"]` 与校验之间）：

```python
        action = data["action"]
        # deepseek 变体：args 平铺在 action 下（缺 args 嵌套），确定性收拢
        if isinstance(action, dict) and "tool" in action and "args" not in action:
            flat_args = {k: v for k, v in action.items() if k != "tool"}
            action = {"tool": action["tool"], "args": flat_args}
        if not isinstance(action, dict) or "tool" not in action or "args" not in action:
            return None
```

- [ ] **Step 4: 运行测试确认通过**

Run: `conda run -n Video-Tree-TRM pytest tests/unit/test_agent_loop.py -v`
Expected: 全部 PASS（含原有 9 个测试，确认无回归）。

- [ ] **Step 5: Commit**

```bash
git add core/agent/loop.py tests/unit/test_agent_loop.py
git commit -m "fix(agent): normalize fenced and flat-args LLM outputs in parser"
```

---

### Task 2: A2 步级重试

**Files:**
- Modify: `core/agent/loop.py`（`__init__` 第 72-77 行；`run()` Phase 1 约 117-129 行；模块顶部加 `import asyncio`——当前缺失，Task 2 测试的红灯即源于此）
- Test: `tests/unit/test_agent_loop.py`（追加测试类）

- [ ] **Step 1: 写失败测试**

```python
# ── A2 步级重试测试（Spec-1）──────────────────────────────────

import ssl


class TestStepLevelRetry:
    """LLM 瞬时异常的步级重试：可重试元组 / 退避 / fail-fast。"""

    def _make_loop(self, chat_side_effects: list) -> AgentLoop:
        llm = AsyncMock()
        llm.chat = AsyncMock(side_effect=chat_side_effects)
        return AgentLoop(llm=llm, max_steps=10)

    @pytest.mark.asyncio
    async def test_transient_error_retried_then_succeeds(self, monkeypatch) -> None:
        delays: list[float] = []

        async def _fake_sleep(seconds: float) -> None:
            delays.append(seconds)

        monkeypatch.setattr("core.agent.loop.asyncio.sleep", _fake_sleep)
        loop = self._make_loop(
            [
                ssl.SSLError("SSLV3_ALERT_BAD_RECORD_MAC"),
                TimeoutError("watchdog"),
                _make_response(_submit_json()),
            ]
        )
        result = await loop.run("sys", "user", _StubDispatcher())
        assert result.stop_reason == "finished"
        assert delays == [20.0, 40.0]

    @pytest.mark.asyncio
    async def test_retry_exhausted_terminates_with_error(self, monkeypatch) -> None:
        async def _fake_sleep(seconds: float) -> None:
            pass

        monkeypatch.setattr("core.agent.loop.asyncio.sleep", _fake_sleep)
        loop = self._make_loop([TimeoutError("t1"), TimeoutError("t2"), TimeoutError("t3")])
        result = await loop.run("sys", "user", _StubDispatcher())
        assert result.stop_reason == "error"
        assert loop._llm.chat.await_count == 3  # 首次 + 2 次重试

    @pytest.mark.asyncio
    async def test_non_retryable_fails_fast(self, monkeypatch) -> None:
        sleep_mock = AsyncMock()
        monkeypatch.setattr("core.agent.loop.asyncio.sleep", sleep_mock)
        loop = self._make_loop([RuntimeError("programming bug")])
        result = await loop.run("sys", "user", _StubDispatcher())
        assert result.stop_reason == "error"
        sleep_mock.assert_not_awaited()
        assert loop._llm.chat.await_count == 1
```

- [ ] **Step 2: 运行测试确认失败**

Run: `conda run -n Video-Tree-TRM pytest tests/unit/test_agent_loop.py::TestStepLevelRetry -v`
Expected: 三个测试全部 ERROR——`monkeypatch.setattr("core.agent.loop.asyncio.sleep", ...)` 抛 AttributeError，因为当前 `loop.py` 未 import asyncio。这就是正确的红灯（实现步会加入 `import asyncio`，此后 monkeypatch 路径有效，绿灯判断以行为断言为准）。

- [ ] **Step 3: 实现步级重试**

`__init__` 签名扩展（保留既有参数不动）：

```python
    def __init__(
        self,
        llm: LLMProvider,
        max_steps: int,
        max_retries: int = 3,
        *,
        step_retries: int = 2,
        step_retry_delays: tuple[float, ...] = (20.0, 40.0),
        retryable_exceptions: tuple[type[BaseException], ...] = (TimeoutError, OSError),
    ) -> None:
        self._llm = llm
        self._max_steps = max_steps
        self._max_retries = max_retries
        self._step_retries = step_retries
        self._step_retry_delays = step_retry_delays
        self._retryable_exceptions = retryable_exceptions
```

`run()` Phase 1 整段替换（原 117-129 行 try/except）：

```python
            # Phase 1: LLM 调用（步级重试：防穿透 GovernedLLMClient 的瞬时异常）
            llm_error: Exception | None = None
            step_attempt = 0
            while True:
                try:
                    response = await self._call_llm(
                        messages, token_usage, session_id=session_id
                    )
                    break
                except self._retryable_exceptions as e:
                    step_attempt += 1
                    if step_attempt > self._step_retries:
                        llm_error = e
                        break
                    delay = self._step_retry_delays[
                        min(step_attempt - 1, len(self._step_retry_delays) - 1)
                    ]
                    logger.warning(
                        "LLM 瞬时异常，步级重试 {}/{}（{}s 后重发）: {}",
                        step_attempt, self._step_retries, delay, e,
                    )
                    await asyncio.sleep(delay)
                except Exception as e:
                    llm_error = e
                    break
            if llm_error is not None:
                logger.error("LLM API 调用失败: {}", llm_error)
                result = LoopResult(
                    steps=steps,
                    steps_used=step_count,
                    token_usage=token_usage,
                    stop_reason="error",
                )
                await _call_hook(pm.hook.on_finish, result=result)
                return result
```

注意：`asyncio.CancelledError` 继承 `BaseException`，两个 except 均不会捕获——取消信号天然穿透，符合设计。失败尝试的 error 遥测由 `GovernedLLMClient` 内部负责（已有），此处仅 loguru 记录。

- [ ] **Step 4: 运行测试确认通过**

Run: `conda run -n Video-Tree-TRM pytest tests/unit/test_agent_loop.py -v`
Expected: 全部 PASS（原有 9 个 + Task 1 的 5 个 + 本任务 3 个）。

- [ ] **Step 5: Commit**

```bash
git add core/agent/loop.py tests/unit/test_agent_loop.py
git commit -m "feat(agent): step-level retry for transient LLM errors (20s/40s backoff)"
```

---

### Task 3: B 摘要附带实体原文

**Files:**
- Modify: `app/tree/environment.py`（`TreeEnvironment` 新增方法，放在 `view_node` 之后约 216 行处）
- Modify: `app/search/tools.py`（`_handle_view_node` Phase 2/3 之间，约 196-204 行）
- Test: `tests/unit/test_tree_environment.py`、`tests/unit/test_search_tools.py`（各追加）

- [ ] **Step 1: 写 TreeEnvironment 失败测试**

`tests/unit/test_tree_environment.py` 追加（该文件已 import 全部 Card/Node 类型与 IndexMeta/TreeIndex，见文件头 11-20 行；构造模式对齐现有 `_make_test_index()`）：

```python
# ── node_entity_fields 测试（Spec-1 B）───────────────────────


def _make_entity_test_index() -> TreeIndex:
    """带实体字段的最小三层树（含一个空字段 L2）。"""
    l3 = L3Node(
        id="vid_L1_000_L2_000_L3_000",
        card=L3Card(
            frame_summary="一名男子戴耳机",
            visible_entities=["Bluetooth headset (both ears)", "man"],
            ongoing_actions=["talking"],
            visible_text=["EARPHONE BOTTLE OPENER"],
            spatial_layout="man center",
            visual_attributes={},
        ),
        timestamp=10.0,
    )
    l2 = L2Node(
        id="vid_L1_000_L2_000",
        card=L2Card(
            event_description="产品评测",
            entities=["Bluetooth headset (both ears)", "reviewer"],
            actions=["reviewing"],
            action_subjects=["reviewer"],
            visible_text=["$9.99"],
            spatial_relations="",
            state_changes=None,
        ),
        time_range=(0.0, 60.0),
        children=[l3],
    )
    l2_empty = L2Node(
        id="vid_L1_000_L2_001",
        card=L2Card(
            event_description="空镜",
            entities=[],
            actions=[],
            action_subjects=[],
            visible_text=[],
            spatial_relations="",
            state_changes=None,
        ),
        time_range=(60.0, 120.0),
    )
    l1 = L1Node(
        id="vid_L1_000",
        card=L1Card(
            scene_summary="评测场景",
            main_setting="室内",
            key_entities=["reviewer"],
            main_actions=["评测"],
            topic_keywords=["数码"],
            visible_text=[],
            temporal_flow="线性",
        ),
        time_range=(0.0, 120.0),
        children=[l2, l2_empty],
    )
    return TreeIndex(metadata=IndexMeta("/test.mp4", "video"), roots=[l1])


class TestNodeEntityFields:
    def test_l2_entities_and_visible_text(self) -> None:
        env = TreeEnvironment(_make_entity_test_index())
        fields = env.node_entity_fields("vid_L1_000_L2_000")
        assert "Bluetooth headset (both ears)" in fields["实体"]
        assert "$9.99" in fields["画面文字"]

    def test_l3_visible_entities(self) -> None:
        env = TreeEnvironment(_make_entity_test_index())
        fields = env.node_entity_fields("vid_L1_000_L2_000_L3_000")
        assert "Bluetooth headset (both ears)" in fields["实体"]
        assert "EARPHONE BOTTLE OPENER" in fields["画面文字"]

    def test_empty_fields_omitted(self) -> None:
        env = TreeEnvironment(_make_entity_test_index())
        assert env.node_entity_fields("vid_L1_000_L2_001") == {}

    def test_unknown_node_raises(self) -> None:
        env = TreeEnvironment(_make_entity_test_index())
        with pytest.raises(KeyError):
            env.node_entity_fields("nonexistent")
```

- [ ] **Step 2: 运行确认失败**

Run: `conda run -n Video-Tree-TRM pytest tests/unit/test_tree_environment.py::TestNodeEntityFields -v`
Expected: FAIL（`AttributeError: node_entity_fields`）。

- [ ] **Step 3: 实现 TreeEnvironment.node_entity_fields**

`app/tree/environment.py`，`view_node` 方法之后追加；模块级常量放 `_SUBTITLE_SKIP` 附近：

```python
# 各层级 card 的实体字段名（B 修复：dispatcher 追加原文用）
_ENTITY_FIELDS_BY_LEVEL: dict[str, tuple[str, ...]] = {
    "L1": ("key_entities",),
    "L2": ("entities",),
    "L3": ("visible_entities",),
}
```

```python
    def node_entity_fields(self, node_id: str) -> dict[str, str]:
        """返回节点 card 的实体/画面文字字段原文。

        供 dispatcher 在按题摘要后确定性追加，防止 LLM 摘要吞掉
        entities/visible_text 信号（benchmark 错题 M1 恶化因素）。

        参数:
            node_id: 节点 ID。

        返回:
            {"实体": "...", "画面文字": "..."}，空字段不含对应键。

        异常:
            KeyError: 节点不存在。
        """
        node = self._id_to_node.get(node_id)
        if node is None:
            raise KeyError(f"节点不存在: {node_id}")
        level = _node_level(node)
        out: dict[str, str] = {}

        entity_values: list[str] = []
        for field_name in _ENTITY_FIELDS_BY_LEVEL[level]:
            for value in getattr(node.card, field_name) or []:
                if isinstance(value, str) and value.strip():
                    entity_values.append(value.strip())
        if entity_values:
            out["实体"] = "; ".join(dict.fromkeys(entity_values))

        text_values = [
            v.strip()
            for v in (getattr(node.card, "visible_text", None) or [])
            if isinstance(v, str) and v.strip()
        ]
        if text_values:
            out["画面文字"] = "; ".join(dict.fromkeys(text_values))
        return out
```

已核实：`_node_level`（`environment.py:35-48`）返回 `"L1"/"L2"/"L3"` 字符串，与 `_LEVEL_LABEL` 键一致，`_ENTITY_FIELDS_BY_LEVEL` 直接以此为键。

- [ ] **Step 4: 运行确认通过**

Run: `conda run -n Video-Tree-TRM pytest tests/unit/test_tree_environment.py -v`
Expected: 全部 PASS。

- [ ] **Step 5: 写 dispatcher 失败测试**

`tests/unit/test_search_tools.py` 追加。注意：现有 `dispatcher` fixture（第 190 行）的树 entities 只有 `["person"]`，**不复用**——新增专用 fixture 注入带实体的树；summarize 无现成 stub 模式，用 monkeypatch 新建：

```python
# ── view_node 实体追加测试（Spec-1 B）────────────────────────


def _make_entity_tree() -> TreeIndex:
    """L2 带实体字段的最小树（与 _make_test_tree 同构，仅换 card 内容）。"""
    l2 = L2Node(
        id="vid_L1_000_L2_000",
        card=L2Card(
            event_description="产品评测",
            entities=["Bluetooth headset (both ears)", "reviewer"],
            actions=["reviewing"],
            action_subjects=["reviewer"],
            visible_text=["$9.99"],
            spatial_relations="",
            state_changes=None,
        ),
        time_range=(5.0, 15.0),
        children=[],
    )
    l1 = L1Node(
        id="vid_L1_000",
        card=L1Card(
            scene_summary="评测场景",
            main_setting="室内",
            key_entities=["reviewer"],
            main_actions=["评测"],
            topic_keywords=["数码"],
            visible_text=[],
            temporal_flow="线性",
        ),
        time_range=(0.0, 30.0),
        children=[l2],
    )
    return TreeIndex(
        metadata=IndexMeta(source_path="test.mp4", modality="video"),
        roots=[l1],
    )


@pytest.fixture()
def entity_dispatcher(
    prompts_dir: Path,
    skills_registry: SkillRegistry,
) -> SearchToolDispatcher:
    """树含实体字段的 dispatcher（其余配置与 dispatcher fixture 一致）。"""
    return SearchToolDispatcher(
        env=TreeEnvironment(_make_entity_tree()),
        tool_llm=FakeLLM(),
        vlm=FakeVLM(),
        ocr=FakeOCR(),
        prompts_dir=prompts_dir,
        skills=skills_registry,
        embed_fn=_fake_embed_fn,
        verify_vision=False,
        anchor=False,
        assemble_mode="ids",
    )


class TestViewNodeEntityAppendix:
    @pytest.mark.asyncio
    async def test_view_node_appends_entity_blocks(
        self, monkeypatch, entity_dispatcher: SearchToolDispatcher
    ) -> None:
        """摘要后必须出现 [实体]/[画面文字] 区块（确定性追加，不经 LLM）。"""

        async def _stub_summarize(*args, **kwargs) -> str:
            return "[内容摘要] 与问题无关的摘要"

        monkeypatch.setattr("app.search.tools.summarize_node", _stub_summarize)
        result = await entity_dispatcher.dispatch(
            "view_node",
            {"node_id": "vid_L1_000_L2_000", "question": "耳机戴哪只耳？"},
            context={},
        )
        assert "[实体]" in result
        assert "Bluetooth headset (both ears)" in result
        assert "[画面文字]" in result
        assert "$9.99" in result
```

（L2 无 children → `summarize_children` 不会被触发，无需 stub。）

- [ ] **Step 6: 运行确认失败**

Run: `conda run -n Video-Tree-TRM pytest tests/unit/test_search_tools.py::TestViewNodeEntityAppendix -v`
Expected: FAIL（输出无 `[实体]` 区块）。

- [ ] **Step 7: 实现 dispatcher 追加**

`app/search/tools.py` `_handle_view_node`，Phase 2 摘要之后、Phase 3 子节点概览之前：

```python
        parts: list[str] = [
            f"[节点] {node_id} | {level_label} | {time_str}",
            "",
            summary,
        ]

        # Phase 2.5: 确定性追加实体/画面文字原文（防按题摘要吞噬，Spec-1 B）
        for label, text in self._env.node_entity_fields(node_id).items():
            parts.append(f"[{label}] {text}")
```

- [ ] **Step 8: 运行确认通过 + 全量回归**

Run: `conda run -n Video-Tree-TRM pytest tests/unit/test_search_tools.py tests/unit/test_tree_environment.py -v`
Expected: 全部 PASS。
Run: `make test`
Expected: 全绿，覆盖率不降。

- [ ] **Step 9: Commit**

```bash
git add app/tree/environment.py app/search/tools.py tests/unit/test_tree_environment.py tests/unit/test_search_tools.py
git commit -m "feat(search): append raw entity fields after view_node summary"
```

---

### Task 4: 端到端验证（真实 benchmark 抽样重跑）

**Files:** 无新文件（验证性任务）

- [ ] **Step 1: 抽样重跑（24 题，tmux + 无缓存日志）**

```bash
tmux new-session -d -s spec1check
tmux send-keys -t spec1check "cd /home/iomgaa/Projects/Video-Tree-TRM5 && CUDA_VISIBLE_DEVICES=0 N_SAMPLES=24 RUN_ID=spec1check bash scripts/infer_video_mme.sh" Enter
```

注：`infer_video_mme.sh` 不支持 RUN_ID 环境变量时，直接以 `conda run -n Video-Tree-TRM python main.py --workspace-dir workspaces/default --store-dir store --mode infer --concurrency 24 --max-steps 40 --skill-mode auto --n-samples 24 --questions benchmarks/Video-MME --run-id spec1check --skills-version v1 --prompts-version v1` 运行。

- [ ] **Step 2: 验证三项指标**

```bash
sqlite3 workspaces/default/harness.db "SELECT stop_reason, COUNT(*) FROM predictions WHERE run_id='infer_spec1check' GROUP BY stop_reason;"
```
Expected: 无 `parse_error`（A1 生效）；`error` 为 0 或仅真实网络故障（A2 生效）。

```bash
sqlite3 workspaces/default/harness.db "SELECT steps_json FROM predictions WHERE run_id='infer_spec1check' LIMIT 1;" | grep -c "\[实体\]"
```
Expected: ≥1（B 生效：view_node 输出含实体区块）。

- [ ] **Step 3: 收尾**

Run: `make lint && make test`
Expected: 全绿。

```bash
git status  # 确认无未预期改动
```

---

## Self-Review 记录

1. **Spec 覆盖**：A1（Task 1）、A2 含 20s/40s 与显式异常元组（Task 2）、B 含 dispatcher 侧追加与 TreeEnvironment 结构化提取（Task 3）、验证三件套（Task 4 + 各任务单测）——设计四节全覆盖。
2. **占位符扫描**：Task 3 Step 1 的 `_build_env_with_node(s)` 指向 `test_tree_environment.py` 现有构造模式，属"复用现有 fixture"指令而非 TBD；其余步骤均含完整代码/命令。
3. **类型一致性**：`node_entity_fields` 在 Task 3 Step 3 定义、Step 7 调用，签名一致；`step_retry_delays` 构造参数与测试断言 `[20.0, 40.0]` 一致。

## 核心算法保真校验

本计划涉及**算法 #10 Agent Loop**（`core/agent/loop.py`）：A1/A2 均为解析与异常路径的加固，不触碰 Thinking+JSON 协议、json_repair 兜底链、pluggy hook 时序与步数语义（解析失败重试不计步、工具无效不计步的现状行为在测试中有回归覆盖）。对照参考 `/home/iomgaa/Projects/Video-Tree-TRM4/core/loop.py`：本改动为 TRM5 新增韧性层，无迁移简化。其余 12 项算法不涉及。