# 系统总览 (Overview)

> Video-Tree-TRM5：在层次化视频树上构建可自我进化的搜索 Agent + 可训练递归检索器，通过 Harness Engineering 持续改进实现长视频理解。目标会议 EMNLP 2026。

## 1. 核心思想：自进化循环对标 PyTorch 训练

系统外层是一个 `for epoch` 循环，每轮跑 `推理 → 诊断 → 进化`，对标神经网络训练：

| PyTorch | 本项目 | 代码位置 |
|---------|--------|----------|
| DataLoader | 出题 question_gen | `app/question_gen/generator.py` |
| model.forward() | 推理 inference | `app/harness/inference.py` + `core/agent/loop.py` |
| loss.backward() | 诊断 diagnose | `core/evolution/diagnose.py` |
| optimizer.step() | 进化 evolve | `core/evolution/evolve.py` |
| nn.Parameter | Skills + Prompts（版本化） | `store/skills/`, `store/prompts/` |
| training loop | 外层循环 runner | `app/harness/runner.py` |
| checkpoint | Store 版本快照 | `app/harness/workspace.py` |

只有 inference 是 agent-controlled（LLM 自主调工具），其余三步是 code-controlled workflow。

## 2. 模块结构

```mermaid
flowchart TD
    main[main.py CLI 入口] --> runner[app/harness/runner.py 训练循环]
    main --> build[app/tree/video_builder.py 建树]
    main --> qgen[app/question_gen/generator.py 新题构建]
    main --> train_ret[app/retriever/train.py 检索器训练]

    runner --> inf[app/harness/inference.py 推理]
    runner --> diag[core/evolution/diagnose.py 诊断]
    runner --> evo[core/evolution/evolve.py 进化]
    runner --> ws[app/harness/workspace.py Store + Workspace]

    inf --> loop[core/agent/loop.py AgentLoop]
    loop --> search[app/search/ prompt + skills]
    loop --> llm[adapters/llm.py GovernedLLMClient]
    build --> vlm[adapters/vlm.py]
```

## 3. 模块职责

| 模块 | 职责 |
|------|------|
| `app/tree/` | 建树模块：VLM 生成三层 TreeIndex（L1段落→L2片段→L3帧），字幕注入与后增强 |
| `app/harness/` | 训练 harness：runner 循环编排、推理 step、mini-batch、信息阶梯、workspace 版本管理 |
| `app/question_gen/` | 新题构建：题目生成、基线校准、去重 |
| `app/search/` | 搜索 Agent 装配：PromptManager + SkillRegistry |
| `app/retriever/` | 可训练检索器：RecursiveRetriever（CrossAttention+ACT）、两阶段训练 |
| `core/agent/` | AgentLoop 引擎：Thinking+JSON 推理循环，pluggy hook 驱动 |
| `core/evolution/` | 诊断+进化引擎：两阶段诊断、patch/rewrite 进化、CE-Gate e-process |
| `adapters/` | 外部实现层：GovernedLLMClient（遥测+熔断+缓存）、VLM、Embedding、ASR、OCR |

## 4. 资源与工作区

| 路径 | 含义 |
|------|------|
| `store/` | 版本化资源 = "模型权重"：`skills/`、`prompts/`、`questions/`、`videos/` |
| `workspaces/` | 一次"训练实验"工作区，如 `video-mme-v1`。每次 run 冻结 config + Store 快照，保证可复现 |

进化产出版本化（`skills/v1`, `v2`...）= 可回滚的 checkpoint；进化 validation（长度/格式约束）= grad clipping。

## 5. 可提取内核

`core/agent/` 和 `core/evolution/` 是两个独立可提取包，**只依赖 Protocol 接口**，不依赖 `app/`、`adapters/` 或任何框架。

| 可提取包 | 包含 | 依赖的 Protocol |
|----------|------|----------------|
| `core/agent/` | `loop.py`、`types.py`、`protocols.py` | `LLMProvider`、`VLMProvider`、`ToolDispatcher` |
| `core/evolution/` | `diagnose.py`、`evolve.py`、`gate.py`、`validate.py`、`types.py`、`protocols.py` | `SkillStore`、`PromptStore`、`RunLog`、`TelemetryRecorder` |

判据：将它们连同 `core/types.py` 复制到另一个项目，提供 Protocol 假实现即可原样运行。

## 6. 实现路线

详见 `research-wiki/designs/` 下各设计文档与 `research-wiki/index.md`。