Video-Tree-TRM5/research-wiki/plans/infrastructure-setup.md

---
type: plan
node_id: plan:infrastructure-setup
title: 项目基础设施初始化计划
date: 2026-07-06
---

# 项目基础设施初始化计划

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

**Goal:** 为 Video-Tree-TRM5（TRM4 MVP 的生产级重构）创建全部基础设施文件，确立 Clean Architecture 分层、项目约束和开发工作流。

**Architecture:** 项目分三大模块（建树 / 训练 harness / 新题构建），核心内核 `core/`（AgentLoop + Evolution 引擎）可独立提取复用。采用 Protocol-based 接缝（参考 CHSAnalyzer2），依赖只能向内。基础设施文件按依赖顺序创建：ARCHITECTURE.md → CLAUDE.md → 其余文件。

**Tech Stack:** Python 3.11, Conda env `Video-Tree-TRM`, loguru, pluggy, sentence-transformers, torch, Redis (缓存/ARQ), ruff, pytest

**参考代码路径（实现者必须在生成内容前阅读）：**

| 参考 | 路径 | 用途 |
|------|------|------|
| CHSAnalyzer2 CLAUDE.md | `/home/iomgaa/Projects/CHSAnalyzer2/CLAUDE.md` | 工程化结构、P1-P6 原则、SOP、Skill 规则 |
| CHSAnalyzer2 ARCHITECTURE.md | `/home/iomgaa/Projects/CHSAnalyzer2/research-wiki/ARCHITECTURE.md` | Clean Architecture 分层、Protocol 接缝模式 |
| TRM4 CLAUDE.md | `/home/iomgaa/Projects/Video-Tree-TRM4/CLAUDE.md` | 领域内容、PyTorch 类比、配置管理 |
| TRM4 overview.md | `/home/iomgaa/Projects/Video-Tree-TRM4/research-wiki/overview.md` | 自进化循环总览 |
| TRM5 reference architecture.md | `/home/iomgaa/Projects/Video-Tree-TRM5/reference/docs/architecture.md` | 建树+检索器设计 |
| TRM4 config/default.yaml | `/home/iomgaa/Projects/Video-Tree-TRM4/config/default.yaml` | harness 配置参数 |
| TRM5 reference config/videomme.yaml | `/home/iomgaa/Projects/Video-Tree-TRM5/reference/config/videomme.yaml` | 建树配置参数 |
| TRM4 .env.example | `/home/iomgaa/Projects/Video-Tree-TRM4/.env.example` | LLM/VLM/ASR/OCR 端点模板 |
| TRM4 .gitignore | `/home/iomgaa/Projects/Video-Tree-TRM4/.gitignore` | gitignore 模板 |
| TRM4 tree-enhancement-design | `/home/iomgaa/Projects/Video-Tree-TRM4/research-wiki/designs/2026-07-06-tree-enhancement-design.md` | 树增强管线设计 |
| TRM4 question-gen-synth-design | `/home/iomgaa/Projects/Video-Tree-TRM4/research-wiki/designs/2026-07-06-question-gen-synth-design.md` | 赛题生成设计 |

---

## 文件总览

| # | 文件 | 动作 | 职责 |
|---|------|------|------|
| 1 | `.gitignore` | 新建 | Git 排除规则 |
| 2 | `research-wiki/ARCHITECTURE.md` | 新建 | Clean Architecture 分层设计、接缝清单、依赖方向 |
| 3 | `CLAUDE.md` | 重写 | Agent 指令入口（融合 CHSAnalyzer2 工程框架 + TRM4 领域内容） |
| 4 | `README.md` | 新建 | 项目概览 |
| 5 | `pyproject.toml` | 重写 | 项目元数据 + 依赖 + 工具配置 |
| 6 | `.env.example` | 新建 | 环境变量模板 |
| 7 | `config/default.yaml` | 新建 | 全量非敏感默认配置 |
| 8 | `Makefile` | 新建 | 工程命令收口 |
| 9 | `research-wiki/overview.md` | 新建 | 系统总览（自进化循环 + 模块结构） |
| 10 | `.claude/skills/writing-plans/SKILL.md` | 修改 | 增加核心算法保真校验步骤 |
| 11 | `.claude/skills/subagent-driven-development/SKILL.md` | 修改 | 增加实现后与参考代码比对步骤 |

---

### Task 1: Git 初始化 + .gitignore

**Files:**
- Create: `.gitignore`

- [ ] **Step 1: 初始化 Git 仓库**

```bash
cd /home/iomgaa/Projects/Video-Tree-TRM5
git init
```

- [ ] **Step 2: 创建 .gitignore**

以 TRM4 的 `.gitignore`（路径 `/home/iomgaa/Projects/Video-Tree-TRM4/.gitignore`）为基础，做以下调整：

**保留原文全部内容**，仅修改末尾的项目特有部分：

```
# 将 TRM4 .gitignore 末尾的项目特有部分替换为:

# ------------------------------
# Project-specific
# ------------------------------
.codex/
.claude/settings.local.json
.claude/worktrees/
.deepeval/
.playwright-mcp/
.wiki-site/
pencil/

# 数据与实验产物（不提交）
store/
workspaces/
results/

# graphify 知识图谱输出（可再生）
graphify-out/

# reference 中的 ZIP 包（太大）
reference/*.zip
```

- [ ] **Step 3: 首次提交**

```bash
git add .gitignore
git commit -m "chore: init repo with .gitignore"
```

---

### Task 2: ARCHITECTURE.md

**Files:**
- Create: `research-wiki/ARCHITECTURE.md`

- [ ] **Step 1: 阅读参考文档**

实现者必须先阅读以下文件以获取设计决策上下文：
- `/home/iomgaa/Projects/CHSAnalyzer2/research-wiki/ARCHITECTURE.md` — Clean Architecture 分层模式、Protocol 接缝
- `/home/iomgaa/Projects/Video-Tree-TRM5/reference/docs/architecture.md` — 建树+检索器设计
- `/home/iomgaa/Projects/Video-Tree-TRM4/research-wiki/overview.md` — 自进化循环总览

- [ ] **Step 2: 创建 ARCHITECTURE.md**

文档结构必须包含以下章节（每章的必要内容已列出）：

**§1 核心定位**
- 项目目标：在层次化视频树上构建可自我进化的搜索 Agent + 可训练的递归检索器，目标 EMNLP 2026
- 系统类比表（对标 PyTorch 训练循环）：复制 TRM4 overview.md 的对应表格，更新代码位置路径为新结构
- 三大模块一句话定义：建树（离线预处理，VLM 生成三层 TreeIndex）、训练（推理→诊断→进化自进化循环 + RecursiveRetriever 参数训练）、新题构建（生成训练题，原始 benchmark 作 held-out）

**§2 分层架构（Clean Architecture）**
- 四层依赖规则图（Mermaid）：`Entities ← Use Cases ← Ports ← Details`
- 目录结构规范（完整树形图），对应以下分层：

```text
project_root/
├── core/                    # 可提取内核（不依赖 app/、adapters/）
│   ├── agent/               # 【可提取包】AgentLoop 引擎
│   │   ├── loop.py          # Thinking+JSON 推理循环，pluggy hook
│   │   ├── types.py         # Step, LoopResult
│   │   └── protocols.py     # LLMProvider, ToolDispatcher Protocol
│   ├── evolution/           # 【可提取包】诊断+进化引擎
│   │   ├── diagnose.py      # 两阶段诊断管线
│   │   ├── evolve.py        # patch/rewrite 进化
│   │   ├── gate.py          # CE-Gate e-process
│   │   ├── validate.py      # 块顺序验证
│   │   ├── types.py         # DiagnosisResult, EvolutionRecord, ...
│   │   └── protocols.py     # SkillStore, RunLog, TelemetryRecorder Protocol
│   └── types.py             # 跨模块共享类型
│
├── app/                     # 应用层（组合 core + adapters，领域特化）
│   ├── tree/                # 模块1：建树
│   │   ├── index.py         # TreeIndex 数据结构（L1/L2/L3Node）
│   │   ├── video_builder.py # VideoTreeBuilder（asyncio 并发）
│   │   ├── text_builder.py  # TextTreeBuilder
│   │   ├── embeddings.py    # EmbeddingModel（local/remote 双后端）
│   │   ├── enhance/         # 树增强管线（verify/supplement/clean）
│   │   └── subtitle.py      # SRT 解析 + 字幕注入
│   ├── harness/             # 模块2：训练 harness
│   │   ├── runner.py        # 训练循环编排（对标 Trainer）
│   │   ├── inference.py     # 推理 step
│   │   ├── batching.py      # mini-batch 构建
│   │   ├── question_gen.py  # 数据加载、三池切分
│   │   ├── gate_ladder.py   # 信息阶梯
│   │   ├── momentum.py      # 慢速动量
│   │   ├── config.py        # RunConfig
│   │   ├── log.py           # HarnessLog (SQLite)
│   │   └── workspace.py     # Store + Workspace 版本管理
│   ├── question_gen/        # 模块3：新题构建
│   │   ├── generator.py     # 题目生成
│   │   ├── calibrator.py    # 基线校准
│   │   └── dedup.py         # 去重
│   ├── search/              # 搜索 Agent 装配
│   │   ├── prompt.py        # PromptManager
│   │   └── skills.py        # SkillRegistry
│   ├── retriever/           # 可训练检索器
│   │   ├── recursive.py     # RecursiveRetriever (CrossAttention+ACT)
│   │   ├── losses.py        # NavigationLoss + ACTLoss
│   │   └── train.py         # 两阶段训练入口
│   └── ports.py             # 应用层特有端口（EmbeddingProvider, TreeCache, ...）
│
├── adapters/                # 外部实现层
│   ├── llm.py               # GovernedLLMClient（遥测+熔断+Redis缓存）
│   ├── vlm.py               # VLM 客户端
│   ├── embedding.py         # Embedding 服务实现
│   ├── redis_cache.py       # Redis 响应缓存
│   ├── ocr.py               # MonkeyOCR 客户端
│   ├── asr.py               # ASR (Whisper) 客户端
│   └── telemetry.py         # SQLite 遥测记录实现
│
├── config/                  # 声明性配置（YAML，禁止 .py）
├── store/                   # 版本化资源（skills/prompts/questions/videos）
├── workspaces/              # 实验工作区
├── tests/                   # 测试
├── data/                    # 数据（不提交 Git）
├── logs/                    # 日志（不提交 Git）
├── results/                 # 实验结果
├── prompts/                 # 诊断 prompt（不参与进化，是评估标尺）
├── main.py                  # CLI 入口
└── research-wiki/           # 单一事实源
```

- 依赖方向硬性规则（表格）：

| 层 | 可依赖 | 禁止依赖 |
|---|--------|---------|
| `core/` | 标准库、typing、pluggy | `app/`、`adapters/`、任何框架 |
| `app/` | `core/`、标准库 | `adapters/`（只通过 Protocol） |
| `adapters/` | `core/`、`app/ports.py`、第三方库 | `app/` 内部模块 |

**§3 接缝清单（Protocol 端口）**
- 列出所有 Protocol 接口（分 core/protocols.py 和 app/ports.py），每个 Protocol 给出：名称、方法签名、职责一句话、当前实现类

核心端口（`core/` 内，可提取）：

| Protocol | 关键方法 | 职责 |
|----------|---------|------|
| `LLMProvider` | `chat()`, `chat_async()` | LLM 文本调用 |
| `VLMProvider` | `chat_with_images()`, `chat_with_images_async()` | VLM 图文调用 |
| `ToolDispatcher` | `dispatch(tool_name, args, context)` | Agent 工具调度 |
| `SkillStore` | `read_skill()`, `write_skill()`, `list_versions()` | 版本化技能存储 |
| `PromptStore` | `read_prompt()`, `write_prompt()` | 版本化提示词存储 |
| `RunLog` | `insert()`, `query()` | 实验日志 |
| `TelemetryRecorder` | `record_llm_call()` | Agent 遥测 |

应用层端口（`app/ports.py`）：

| Protocol | 关键方法 | 职责 |
|----------|---------|------|
| `EmbeddingProvider` | `embed(texts)` | 文本嵌入 |
| `TreeCache` | `get()`, `set()` | 树索引缓存（Redis 实现） |
| `ASRProvider` | `transcribe(audio_path)` | 语音识别 |
| `OCRProvider` | `recognize(image_path)` | OCR |

**§4 Agent 遥测规范**
- 每次 LLM/VLM 调用必须记录的字段表：

| 字段 | 类型 | 说明 |
|------|------|------|
| `call_id` | str | UUID |
| `parent_call_id` | str? | 父调用（agent step → LLM call 链路） |
| `session_id` | str | epoch/step/question 关联 ID |
| `model_name` | str | 使用的模型名 |
| `provider` | str | API 端点标识 |
| `messages` | str (JSON) | 原始输入 |
| `response` | str | 原始输出 |
| `prompt_tokens` | int | 输入 token 数 |
| `completion_tokens` | int | 输出 token 数 |
| `latency_ms` | int | 延迟毫秒 |
| `cache_hit` | bool | 是否命中 Redis 缓存 |
| `error` | str? | 异常信息 |

- 存储：SQLite `telemetry.db`，`llm_calls` 表

**§5 LLM 调用韧性**
- 硬超时：`asyncio.wait_for(call, timeout=config.llm_timeout)`
- 指数退避重试：max_retries, base_delay, max_delay（可配置）
- 熔断器：连续 N 失败 → 短路 M 秒 → 探针恢复
- Redis 响应缓存：content-addressed cache（model + messages hash → response）
- ARQ 任务队列：长时间推理任务异步执行

**§6 核心算法保真清单**
- 完整的 13 项算法表（建树 4 项 + 训练 9 项），包括算法名、参考文件路径、核心逻辑一句话描述
- 说明：迁移时逐一比对参考代码，不可简化

**§7 配置管理（双模式）**
- 工程配置：pydantic-settings + `.env`
- 科研实验配置：per-experiment YAML + harness run 快照
- D7 判定规则（从 CHSAnalyzer2 借鉴）

- [ ] **Step 3: 验证 Markdown 格式**

```bash
# 确认文件存在且非空
wc -l research-wiki/ARCHITECTURE.md
# 期望: 300-500 行
```

- [ ] **Step 4: 提交**

```bash
git add research-wiki/ARCHITECTURE.md
git commit -m "docs: add ARCHITECTURE.md with Clean Architecture design"
```

---

### Task 3: CLAUDE.md 重写

**Files:**
- Rewrite: `CLAUDE.md`

- [ ] **Step 1: 阅读参考文档**

实现者必须阅读以下三个文件并理解其结构：
- `/home/iomgaa/Projects/CHSAnalyzer2/CLAUDE.md` — 工程化框架（完整读取）
- `/home/iomgaa/Projects/Video-Tree-TRM4/CLAUDE.md` — 领域内容（完整读取）
- 刚创建的 `research-wiki/ARCHITECTURE.md` — 新架构设计

- [ ] **Step 2: 重写 CLAUDE.md**

**融合策略**：以 CHSAnalyzer2 CLAUDE.md 的**结构和工程化规则**为骨架，以 TRM4 CLAUDE.md 的**领域内容**填充，并新增遥测/韧性/保真要求。

**必须包含的章节及其来源**：

| 章节 | 来源 | 关键调整 |
|------|------|---------|
| §1 项目元数据 | TRM4 | 核心目标改为完整描述（自进化+可训练检索器），Conda 改 `Video-Tree-TRM`，Python 3.11 |
| §1.5 设计类比 | TRM4 | 保留 PyTorch 类比表，更新代码路径为新结构 |
| §2 常用命令 | CHSAnalyzer2 结构 + TRM4 内容 | Conda 环境 `Video-Tree-TRM`，GPU 约定保留，Makefile 入口更新 |
| §3 SOP | CHSAnalyzer2 | 保留双阶段 + 审核门控差异化，不改 |
| §4.1 核心原则 | CHSAnalyzer2 P1-P6 | 保留完整优先级排序，P1 YAGNI 加上"不等于砍健壮性" |
| §4.2 代码规范 | 融合两者 | 日志用 loguru（非 CHSAnalyzer2 的 RunStore），中文 Docstring |
| §4.3 Git 工作流 | CHSAnalyzer2 | 完全保留 |
| §4.4 工作区规范 | CHSAnalyzer2 | 知识输出到 research-wiki/ |
| §4.5 配置管理 | CHSAnalyzer2 双模式 + TRM4 优先级 | 工程 pydantic-settings + 科研 YAML，D7 规则 |
| §4.6 测试规范 | 融合 | Agent 测试输出 MD 规范保留 |
| **§4.7 核心算法保真** | **新增** | 13 项算法清单，引用 ARCHITECTURE.md §6 |
| **§4.8 Agent 遥测** | **新增** | 每次 LLM 调用必须记录的字段，引用 ARCHITECTURE.md §4 |
| **§4.9 LLM 韧性** | **新增** | 硬超时/熔断/缓存要求 |
| §5 项目结构 | ARCHITECTURE.md §2 | 从 ARCHITECTURE.md 的目录树复制，加硬性规则 |
| §6 上下文获取 | CHSAnalyzer2 | 更新文档路径 |
| §7 输出规范 | CHSAnalyzer2 | 中文，表格优先，长度控制 |
| §8 Skill 使用 | CHSAnalyzer2 | 保留无条件义务声明 + 触发时机表 |
| §9 Research Wiki | CHSAnalyzer2 | 保留，实体类型表不变 |

**Urgent 横幅**：

```markdown
> [!URGENT]
> **科研工程混合 + 生产级项目（非 MVP）**
> 1. 本项目是科研工程混合体（当下工程为主，后续 Agent 进化科研为主），要求**生产级**的稳定性、并发性、防御性、可观测与测试。YAGNI 仍然适用，但**绝不以牺牲健壮性、并发、防御、可观测、测试为代价**换取"简单"。
> 2. 你的所有思考过程和回复必须使用 **简体中文**。
```

**项目元数据**须包含：
- 核心目标：完整的一段话（自进化搜索 Agent + 可训练递归检索器 + 层次化视频树 + EMNLP 2026）
- 项目类型：科研工程混合体 + 生产级（非 MVP）
- 后端架构：Python 3.11
- Conda 环境：`Video-Tree-TRM` (Python 3.11)
- 目标会议：EMNLP 2026

- [ ] **Step 3: 验证**

```bash
wc -l CLAUDE.md
# 期望: 350-500 行

# 确认关键内容存在
grep -c "Video-Tree-TRM" CLAUDE.md    # 期望 >= 5（conda 环境引用）
grep -c "EMNLP 2026" CLAUDE.md        # 期望 >= 1
grep -c "核心算法保真" CLAUDE.md       # 期望 >= 1
grep -c "遥测" CLAUDE.md              # 期望 >= 1
grep -c "ARCHITECTURE.md" CLAUDE.md   # 期望 >= 2
```

- [ ] **Step 4: 提交**

```bash
git add CLAUDE.md
git commit -m "docs: rewrite CLAUDE.md for TRM5 production-grade project"
```

---

### Task 4: README.md

**Files:**
- Create: `README.md`

- [ ] **Step 1: 创建 README.md**

```markdown
# Video-Tree-TRM5

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

## 系统概览

本项目是 [Video-Tree-TRM4](../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` | 建树+检索器参考设计 |
```

- [ ] **Step 2: 提交**

```bash
git add README.md
git commit -m "docs: add README.md with project overview"
```

---

### Task 5: pyproject.toml

**Files:**
- Rewrite: `pyproject.toml`

- [ ] **Step 1: 重写 pyproject.toml**

```toml
[build-system]
requires = ["setuptools>=68.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "video-tree-trm"
version = "0.1.0"
description = "自进化搜索 Agent + 可训练递归检索器，在层次化视频树上实现长视频理解"
requires-python = ">=3.11"
dependencies = [
    # 核心框架
    "torch>=2.1",
    "pluggy>=1.3",
    "loguru>=0.7",
    # LLM/VLM 客户端
    "openai>=1.30",
    "httpx>=0.27",
    # 嵌入与 NLP
    "sentence-transformers>=3.0",
    "numpy>=1.26",
    # 配置管理
    "pydantic>=2.5",
    "pydantic-settings>=2.1",
    "pyyaml>=6.0",
    "python-dotenv>=1.0",
    # 视频处理
    "opencv-python-headless>=4.9",
    # JSON 修复
    "json-repair>=0.28",
    # 任务队列与缓存
    "arq>=0.26",
    "redis>=5.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "pytest-cov>=5.0",
    "pytest-asyncio>=0.23",
    "ruff>=0.5",
    "radon>=6.0",
]

[tool.setuptools.packages.find]
include = ["core*", "app*", "adapters*"]

[tool.pytest.ini_options]
pythonpath = [".", ".claude/tools"]
testpaths = ["tests"]
markers = [
    "requires_redis: 需要可达的 Redis（无则 skip）",
    "requires_gpu: 需要 GPU（无则 skip）",
    "slow: 慢速测试（CI 按需跑）",
]
asyncio_mode = "auto"

[tool.ruff]
target-version = "py311"
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "W", "I", "N", "UP", "B", "A", "C4", "SIM", "TCH"]
ignore = ["E501"]

[tool.ruff.lint.isort]
known-first-party = ["core", "app", "adapters"]
```

- [ ] **Step 2: 创建最小目录骨架**

后续 Makefile 和 README 引用 `core/`、`app/`、`adapters/`、`tests/` 路径。创建空包骨架使 lint/test 命令不报错：

```bash
mkdir -p core/agent core/evolution app/tree app/harness app/question_gen app/search app/retriever adapters tests/unit tests/integration tests/e2e
touch core/__init__.py core/agent/__init__.py core/evolution/__init__.py core/types.py
touch app/__init__.py app/tree/__init__.py app/harness/__init__.py app/question_gen/__init__.py app/search/__init__.py app/retriever/__init__.py app/ports.py
touch adapters/__init__.py
touch tests/__init__.py tests/unit/__init__.py tests/integration/__init__.py tests/e2e/__init__.py
```

创建最小测试文件使 `pytest` 有东西可跑：

```python
# tests/unit/test_smoke.py
"""冒烟测试：验证包可导入。"""


def test_core_importable():
    """core 包可导入。"""
    import core
    assert core is not None


def test_app_importable():
    """app 包可导入。"""
    import app
    assert app is not None


def test_adapters_importable():
    """adapters 包可导入。"""
    import adapters
    assert adapters is not None
```

- [ ] **Step 3: 验证 TOML 语法 + 可安装性**

```bash
python3 -c "import tomllib; tomllib.load(open('pyproject.toml','rb')); print('TOML OK')"
# Expected: TOML OK

conda run -n Video-Tree-TRM pip install -e ".[dev]" 2>&1 | tail -3
# Expected: Successfully installed ... (或已安装)
```

- [ ] **Step 4: 提交**

```bash
git add pyproject.toml core/ app/ adapters/ tests/
git commit -m "build: expand pyproject.toml, create package skeletons and smoke test"
```

---

### Task 6: .env.example

**Files:**
- Create: `.env.example`

- [ ] **Step 1: 创建 .env.example**

以 TRM4 的 `.env.example`（路径 `/home/iomgaa/Projects/Video-Tree-TRM4/.env.example`）为基础，新增 Redis 和 Embedding 配置：

```bash
# 国内 LLM 端点绕过本地代理
no_proxy=dashscope.aliyuncs.com,api.deepseek.com
NO_PROXY=dashscope.aliyuncs.com,api.deepseek.com

# ── 搜索 Agent LLM ──
SEARCH_LLM_MODEL=deepseek-v4-pro
SEARCH_LLM_BASE_URL=https://api.deepseek.com/v1
SEARCH_LLM_API_KEY=sk-xxx

# ── 评估 Judge LLM ──
JUDGE_LLM_MODEL=deepseek-v4-pro
JUDGE_LLM_BASE_URL=https://api.deepseek.com/v1
JUDGE_LLM_API_KEY=sk-xxx

# ── 视觉模型（Qwen VL）──
VL_LLM_MODEL=qwen3.6-plus
VL_LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
VL_LLM_API_KEY=sk-xxx

# ── 进化 LLM（Prompt 改写）──
EVOLVE_LLM_MODEL=deepseek-v4-pro
EVOLVE_LLM_BASE_URL=https://api.deepseek.com/v1
EVOLVE_LLM_API_KEY=sk-xxx

# ── ASR 字幕生成（Groq Whisper）──
ASR_MODEL=whisper-large-v3
ASR_BASE_URL=https://api.groq.com/openai/v1
ASR_API_KEY=gsk-xxx

# ── MonkeyOCR ──
MONKEY_OCR_URLS=http://10.77.0.20:7866,http://10.77.0.20:7867

# ── Embedding（远程模式时使用）──
EMBED_BACKEND=local
EMBED_MODEL=BAAI/bge-base-zh-v1.5
EMBED_API_KEY=
EMBED_API_URL=

# ── Redis（响应缓存 + ARQ 任务队列）──
REDIS_URL=redis://localhost:6379/0

# ── LLM 韧性参数 ──
LLM_TIMEOUT=120
LLM_MAX_RETRIES=3
LLM_RETRY_BASE_DELAY=2.0
LLM_CIRCUIT_BREAKER_THRESHOLD=5
LLM_CIRCUIT_BREAKER_COOLDOWN=60
```

- [ ] **Step 2: 提交**

```bash
git add .env.example
git commit -m "config: add .env.example with LLM/Redis/telemetry templates"
```

---

### Task 7: config/default.yaml

**Files:**
- Create: `config/default.yaml`

- [ ] **Step 1: 创建 config 目录和默认配置**

```bash
mkdir -p config
```

合并 TRM5 reference 建树配置 + TRM4 harness 配置为统一文件：

```yaml
# config/default.yaml
# 全量默认参数，所有非敏感配置的唯一默认值来源。
# 优先级: CLI args > .env > 此文件。敏感信息在 .env 中管理。

# ── 建树模块 ──
tree:
  max_paragraphs_per_l2: 5
  l1_segment_duration: 600.0       # L1 段时长（秒）
  l2_clip_duration: 60.0           # L2 clip 时长（秒）
  l3_fps: 0.5                      # L3 帧提取频率（帧/秒）
  l2_representative_frames: 6      # L2 VLM 描述用的代表帧数
  cache_dir: "cache/trees"
  concurrency: 16                  # asyncio Semaphore 上限
  subtitle_inject: true            # 建树时是否注入 SRT 字幕
  srt_window_sec: 5.0              # 字幕匹配时间窗口（前后各 N 秒）

# ── Embedding ──
embed:
  backend: "local"
  model_name: "BAAI/bge-base-zh-v1.5"
  embed_dim: 768
  device: "cpu"

# ── 可训练检索器 ──
retriever:
  embed_dim: 768
  num_heads: 4
  L_layers: 2
  L_cycles: 4
  max_rounds: 5
  ffn_expansion: 2.0
  checkpoint: null
  k_l1: 1
  k_l2: 1
  k_l3: 1
  max_paths: 5

# ── 检索器训练 ──
train:
  lr: 1.0e-4
  weight_decay: 1.0e-5
  batch_size: 1
  max_epochs_phase1: 30
  max_epochs_phase2: 20
  nav_loss_weight: 1.0
  act_loss_weight: 0.1
  margin_loss_weight: 0.5
  act_lambda_step: 0.1
  act_gamma: 0.9
  eval_interval: 5
  save_dir: "checkpoints"
  dataset: "videomme"
  dataset_path: "data/videomme/splits/train.jsonl"

# ── Harness 自进化循环 ──
harness:
  workspace_dir: "workspaces/default"
  store_dir: store
  mode: infer                      # infer / train
  concurrency: 12
  max_steps: 15                    # Agent 单题最大步数
  skill_mode: auto
  n_samples: 0                     # 0 = 全量
  questions: "benchmarks/Video-MME"
  skills_version: v1
  prompts_version: v1
  epochs: 1
  # CE-Gate 参数
  gate_e_confirm: 20.0
  gate_e_provisional: 3.0
  gate_w_net_min: 2
  gate_delta_min: 0.02
  gate_lambda_dir: -0.642
  gate_e_rollback: 10.0
  gate_block: 8
  gate_n_max: 40
  gate_p_low: 0.05
  gate_p_high: 0.95
  gate_probe_quota: 0.2
  gate_gamma_decay: 0.9
  gate_cooldown_steps: 2
  gate_guard_err: 0.10
  # 进化参数
  edit_budget_start: 5
  edit_budget_end: 2
  skill_update_mode: patch
  appendix_consolidate_threshold: 6
  # 数据池
  diag_size: 200
  diag_correct_ratio: 0.5
  val_size: 30
  val_correct_ratio: 0.5
  test_size: 60
  # mini-batch
  batch_size: 15
  min_class_per_batch: 2
  batch_correct_ratio: 0.5
  momentum_samples: 20
  eval_min_per_class: 2
  early_stop_patience: 8
  use_slow_momentum: true
```

- [ ] **Step 2: 验证 YAML 语法**

```bash
python3 -c "import yaml; yaml.safe_load(open('config/default.yaml')); print('OK')"
```

Expected: `OK`

- [ ] **Step 3: 提交**

```bash
git add config/default.yaml
git commit -m "config: add default.yaml with tree/retriever/harness parameters"
```

---

### Task 8: Makefile

**Files:**
- Create: `Makefile`

- [ ] **Step 1: 创建 Makefile**

```makefile
.PHONY: test lint format wiki build-tree train infer generate-questions

ENV := Video-Tree-TRM

# ── 代码质量 ──
test:
	conda run -n $(ENV) pytest tests/ --cov=core --cov=app --cov=adapters --cov-report=term-missing --cov-fail-under=80

lint:
	conda run -n $(ENV) ruff check core/ app/ adapters/ --fix

format:
	conda run -n $(ENV) ruff format core/ app/ adapters/

# ── 建树 ──
build-tree:
	conda run -n $(ENV) python main.py build-tree $(ARGS)

# ── 训练 ──
train:
	CUDA_VISIBLE_DEVICES=0 conda run -n $(ENV) python main.py train $(ARGS)

infer:
	CUDA_VISIBLE_DEVICES=0 conda run -n $(ENV) python main.py infer $(ARGS)

# ── 新题构建 ──
generate-questions:
	conda run -n $(ENV) python main.py generate-questions $(ARGS)

# ── 知识库 ──
wiki:
	conda run -n $(ENV) python3 .claude/tools/research_wiki.py rebuild_index research-wiki/
```

- [ ] **Step 2: 验证 Makefile 语法**

```bash
make -n test 2>&1 | head -3
# 期望: 显示 conda run 命令（dry run），不报语法错
```

- [ ] **Step 3: 提交**

```bash
git add Makefile
git commit -m "build: add Makefile with test/lint/build-tree/train targets"
```

---

### Task 9: research-wiki/overview.md

**Files:**
- Create: `research-wiki/overview.md`

- [ ] **Step 1: 创建 overview.md**

以 TRM4 的 `research-wiki/overview.md`（路径 `/home/iomgaa/Projects/Video-Tree-TRM4/research-wiki/overview.md`）为蓝本，更新为 TRM5 的新架构：

必须包含：
1. 一句话项目定位
2. 核心思想：自进化循环对标 PyTorch 训练（表格，更新代码路径为新 `app/`/`core/` 结构）
3. 模块结构图（Mermaid flowchart，展示 main.py → runner → 四步循环 + 三大模块）
4. 模块职责表（与 TRM4 overview 格式相同，路径更新）
5. 资源与工作区表（store/ 和 workspaces/ 的说明）
6. "实现路线"一句话指向 `research-wiki/designs/` 和 `research-wiki/index.md`
7. **新增**：可提取内核说明（`core/agent/` 和 `core/evolution/` 的独立性）

- [ ] **Step 2: 提交**

```bash
git add research-wiki/overview.md
git commit -m "docs: add overview.md with system overview and module structure"
```

---

### Task 10: writing-plans Skill 修改

**Files:**
- Modify: `.claude/skills/writing-plans/SKILL.md`

- [ ] **Step 1: 在 Self-Review 章节后、Codex Plan Review 章节前插入新章节**

在 SKILL.md 的 `## Self-Review` 章节结束后、`## Codex Plan Review` 章节开始前，插入以下内容：

```markdown
## 核心算法保真校验

计划编写完成、Self-Review 通过后，**必须**执行以下校验：

对照 `research-wiki/ARCHITECTURE.md §6 核心算法保真清单` 中列出的 13 项关键算法，逐一检查：

1. 计划中是否涉及该算法的迁移/重写？
2. 若涉及，计划中的实现是否与参考代码的核心逻辑一致？
3. 是否存在简化、省略、或改变算法行为的步骤？

**参考代码路径**：

| 算法 | 参考文件 |
|------|---------|
| L2 轴心建树策略 | `reference/video_tree_trm/video_tree_builder.py` |
| VLM 批量帧描述 + JSON fallback | `reference/video_tree_trm/video_tree_builder.py` |
| 断点续跑机制 | `reference/video_tree_trm/video_tree_builder.py` |
| RecursiveRetriever | `reference/docs/architecture.md §5` |
| CE-Gate e-process | `/home/iomgaa/Projects/Video-Tree-TRM4/core/harness/eprocess.py` |
| 信息阶梯 | `/home/iomgaa/Projects/Video-Tree-TRM4/core/harness/gate_ladder.py` |
| 块顺序验证 | `/home/iomgaa/Projects/Video-Tree-TRM4/core/harness/validate.py` |
| 诊断瀑布 | `/home/iomgaa/Projects/Video-Tree-TRM4/core/harness/diagnose.py` |
| 进化 patch 引擎 | `/home/iomgaa/Projects/Video-Tree-TRM4/core/harness/evolve.py` + `patch.py` |
| Mini-batch 构建 | `/home/iomgaa/Projects/Video-Tree-TRM4/core/harness/batching.py` |
| Agent Loop | `/home/iomgaa/Projects/Video-Tree-TRM4/core/loop.py` |
| 树环境语义搜索 | `/home/iomgaa/Projects/Video-Tree-TRM4/core/tree/environment.py` |
| 训练循环编排 | `/home/iomgaa/Projects/Video-Tree-TRM4/core/harness/runner.py` |

**若发现任何简化**：在计划中明确标注该步骤需要逐行比对参考代码，并添加"保真校验"检查点。

**若计划不涉及任何核心算法**：记录"本计划不涉及核心算法迁移，保真校验不适用"即可。
```

- [ ] **Step 2: 提交**

```bash
git add .claude/skills/writing-plans/SKILL.md
git commit -m "skill: add algorithm fidelity check to writing-plans"
```

---

### Task 11: subagent-driven-development Skill 修改

**Files:**
- Modify: `.claude/skills/subagent-driven-development/SKILL.md`

- [ ] **Step 1: 在 §4.5 Automated Quality Gate 的 Gate checklist 末尾添加新检查项**

在 SKILL.md 的 `### 4.5 Automated Quality Gate` 章节的 Gate checklist 代码块末尾（`# 6. Metrics regression check` 之后），追加：

```bash
# 7. 核心算法保真检查（仅当任务涉及核心算法迁移时）
# - 读取 research-wiki/ARCHITECTURE.md §6 核心算法清单
# - 对每个被修改的核心算法文件，diff 与参考代码
# - 确认核心逻辑（条件分支、数学公式、状态机转换）未被简化
# - 若有差异，生成差异报告要求 implementer 解释
```

- [ ] **Step 2: 在 §5 Spec compliance review 之后、§6 之前插入新检查步骤**

在 `### 5. Spec compliance review` 章节结束后、`### 6. Functional quality review` 章节开始前，插入：

```markdown
### 5.5 核心算法保真审查

仅当当前任务涉及核心算法迁移（参照 `research-wiki/ARCHITECTURE.md §6`）时执行此步骤。

将以下内容交给 Codex 审查（`/codex:rescue --fresh --wait`）：

1. 当前任务修改的文件（`git diff`）
2. 对应的参考代码文件（从参考路径读取）
3. 审查指令："逐一比对以下核心逻辑，确认新实现未简化、省略或改变算法行为：[列出具体算法要点]"

**通过标准**：Codex 确认核心逻辑一致，或差异有合理的架构理由（如 Protocol 接口化）。
**未通过**：发回 implementer 修正，循环直到通过。

不涉及核心算法的任务跳过此步骤。
```

- [ ] **Step 3: 全文替换环境名**

在 SKILL.md **全文**中（不限于 §4.5），将所有 `conda run -n chs` 替换为 `conda run -n Video-Tree-TRM`。使用编辑器的全局替换功能，确认替换数量后执行。

- [ ] **Step 4: 提交**

```bash
git add .claude/skills/subagent-driven-development/SKILL.md
git commit -m "skill: add algorithm fidelity review to subagent-driven-development"
```

---

## Self-Review 检查清单

**1. Spec 覆盖**：

| 需求 | 对应 Task |
|------|----------|
| ARCHITECTURE.md（Clean Architecture、Protocol 接缝、遥测、韧性、保真清单） | Task 2 |
| CLAUDE.md（融合 CHSAnalyzer2 + TRM4 + 新增遥测/韧性/保真） | Task 3 |
| README.md | Task 4 |
| .gitignore | Task 1 |
| Makefile | Task 8 |
| pyproject.toml（扩展） | Task 5 |
| .env.example | Task 6 |
| config/default.yaml | Task 7 |
| research-wiki/overview.md | Task 9 |
| writing-plans Skill 修改（核心算法保真校验） | Task 10 |
| subagent-driven-development Skill 修改（保真审查 + 环境名） | Task 11 |
| Git 初始化 | Task 1 |
| ARQ 替代 AWQ（修正）| Task 5 (arq 依赖), Task 6 (REDIS_URL), Task 7 (无 harness ARQ 配置——YAGNI，ARQ 配置在代码实现时再加) |

**2. Placeholder 扫描**：无 TBD/TODO/placeholder。

**3. 类型一致性**：Conda 环境名全文统一为 `Video-Tree-TRM`；目录结构全文统一为 Task 2 中定义的树形图。