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

type, node_id, title, date

type	node_id	title	date
plan	plan:infrastructure-setup	项目基础设施初始化计划	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 仓库

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: 首次提交

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
• 目录结构规范（完整树形图），对应以下分层：

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 格式

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

• Step 4: 提交

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 横幅：

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

项目元数据须包含：

• 核心目标：完整的一段话（自进化搜索 Agent + 可训练递归检索器 + 层次化视频树 + EMNLP 2026）

• 项目类型：科研工程混合体 + 生产级（非 MVP）

• 后端架构：Python 3.11

• Conda 环境：Video-Tree-TRM (Python 3.11)

• 目标会议：EMNLP 2026

• Step 3: 验证

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: 提交

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

# 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

[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 命令不报错：

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 有东西可跑：

# 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 语法 + 可安装性

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: 提交

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 配置：

# 国内 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: 提交

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 目录和默认配置

mkdir -p config

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

# 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 语法

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

Expected: OK

• Step 3: 提交

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

.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 语法

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

• Step 3: 提交

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: 提交

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 章节开始前，插入以下内容：

## 核心算法保真校验

计划编写完成、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: 提交

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 之后），追加：

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

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

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

### 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: 提交

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 中定义的树形图。