@@ -0,0 +1,985 @@
---
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（
**Architecture: ** 项目分三大模块（建树 / 训练 harness / 新题构建），核心内核 `core/` （
**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（
│ │ ├── text_builder.py # TextTreeBuilder
│ │ ├── embeddings.py # EmbeddingModel（
│ │ ├── 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（ ）
- 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` ，
| §1.5 设计类比 | TRM4 | 保留 PyTorch 类比表，更新代码路径为新结构 |
| §2 常用命令 | CHSAnalyzer2 结构 + TRM4 内容 | Conda 环境 `Video-Tree-TRM` ，
| §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，
| §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（
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（
| 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，
**2. Placeholder 扫描 ** ：无 TBD/TODO/placeholder。
**3. 类型一致性 ** ： `Video-Tree-TRM` ；目录结构全文统一为 Task 2 中定义的树形图。
