# Video-Tree-TRM5

> 在层次化视频树上构建可自我进化的搜索 Agent 与可训练递归检索器，实现长视频理解。目标会议：EMNLP 2026。

## 系统概览

本项目是 Video-Tree-TRM4（MVP）的生产级重构，采用 Clean Architecture 分层设计。

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

| PyTorch | 本项目 | 模块 |
|---------|--------|------|
| DataLoader | 出题 question_gen | `app/question_gen/` |
| 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/` |

### 三大模块

| 模块 | 目录 | 说明 |
|------|------|------|
| 建树 | `app/tree/` | 离线预处理：VLM 生成三层 TreeIndex（L1段落→L2片段→L3帧），支持字幕注入和后增强 |
| 训练 | `app/harness/` + `core/` | 自进化循环：推理→诊断→进化，含 CE-Gate 统计检验、信息阶梯、mini-batch 调度 |
| 新题构建 | `app/question_gen/` | 生成 Video-MME 风格训练题，原始 benchmark 作 held-out 泛化评测 |

### 可提取内核

`core/agent/` 和 `core/evolution/` 只依赖 Protocol 接口，可独立提取用于其他项目。

## 快速开始

```bash
# 1. 创建 Conda 环境
conda create -n Video-Tree-TRM python=3.11 -y
conda activate Video-Tree-TRM
pip install -e ".[dev]"

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 填入 API 密钥

# 3. 验证
make lint
make test
```

## 项目结构

详见 `research-wiki/ARCHITECTURE.md`。

## 文档

| 文档 | 说明 |
|------|------|
| `research-wiki/ARCHITECTURE.md` | 系统架构与边界 |
| `research-wiki/overview.md` | 自进化循环总览 |
| `CLAUDE.md` | Agent 工作指令 |
| `reference/docs/architecture.md` | 建树+检索器参考设计 |