Video-Tree-TRM5/CLAUDE.md

CLAUDE.md

[!URGENT] 科研工程混合 + 生产级项目（非 MVP）

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

1. 项目元数据 (Metadata)

• 核心目标: 在层次化视频树上构建可自我进化的搜索 Agent + 可训练的递归检索器（RecursiveRetriever），通过 Harness Engineering（工具、技能、记忆、中间件）的持续改进实现长视频理解；服务于科研产出。详见 research-wiki/ARCHITECTURE.md、README.md。
• 项目类型: 科研工程混合体 + 生产级（非 MVP）
• 目标会议: AAAI 2026（2026年6月25日）
• 后端架构: Python 3.11（Clean Architecture 四层分层，详见 research-wiki/ARCHITECTURE.md §2）
• 版本管理: Git
• Conda 环境: Video-Tree-TRM (Python 3.11)

1.5 系统设计类比 (Design Analogy)

本系统的自进化循环对标 PyTorch 训练循环：

PyTorch 概念	本项目对应	代码位置
DataLoader	出题 question_gen	app/question_gen/loader.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
grad clipping	进化 validation	core/evolution/validate.py

关键推论

• 只有 inference 是 agent-controlled（LLM 自主决定工具调用），其余三步均为 code-controlled workflow。
• 四步之间通过函数调用 + 明确返回类型组合，无需调度框架。
• Store 中版本化资源 = 可回滚的"模型权重"，Workspace = 一次"训练实验"。

2. 常用命令 (Commands)

2.1 Conda 环境管理

[!CRITICAL] 所有 Python 相关命令（pytest / ruff / 脚本）必须在 Video-Tree-TRM 环境中执行

• 使用 conda activate Video-Tree-TRM & <command> 确保命令在正确环境中运行
• 或在命令前显式添加 source activate Video-Tree-TRM &&
• 如果需要使用 LLM 可以依据 .env 环境变量文件使用
• 对于需要长时间运行的程序请尽量使用tmux，并且不要进行任何形式的日志缓存，确保所有日志可以立刻马上输出，这有助于帮助我们检查错误。

# 激活项目环境（交互式 shell）
conda activate Video-Tree-TRM

# 推荐：使用 conda run 执行命令（自动使用正确环境）
conda activate Video-Tree-TRM & pip install xxx
conda activate Video-Tree-TRM & pytest xxx
conda activate Video-Tree-TRM & python xxx

2.2 Makefile 入口

常用工程动作统一收口到 Makefile。

make test            # conda 环境内跑 pytest + 覆盖率
make lint            # ruff check --fix + ruff format（app/ core/）

2.3 代码质量检查

# 代码格式化
conda activate Video-Tree-TRM & ruff format app/ core/ adapters/

# 代码检查并自动修复
conda activate Video-Tree-TRM & ruff check app/ core/ adapters/ --fix

2.4 GPU 约定

[!CRITICAL]

• 本地 (RTX 4070 Ti SUPER)：默认 CUDA_VISIBLE_DEVICES=0
• 所有涉及 GPU 的命令都要显式 CUDA_VISIBLE_DEVICES=<idx> 前缀，避免占用他人卡
• 严禁省略 CUDA_VISIBLE_DEVICES 导致 PyTorch 自动选卡

2.5 实验入口（sh 文件）

每个 sh 文件是自包含的实验记录，写死全部参数，零参数即可复现（GPU 卡号除外）。

# 典型调用
CUDA_VISIBLE_DEVICES=0 bash scripts/<experiment>.sh
MODE=mock N_SAMPLES=10 bash scripts/<experiment>.sh   # smoke test

3. 标准作业程序 (Standard Operating Procedure)

Agent 必须严格遵守以下生命周期执行任务（全量强制，不分级、不因任务"简单"而省略）：

Phase 1: 规划与设计 (Planning)

1. 需求探索: 涉及创建新功能、新组件、修改行为时，必须先调用 brainstorming skill 进行需求探索与设计。无论用户的指令多么具体、改动多么简单，都不得跳过此步骤（除非用户显式说"跳过 brainstorming"）。
2. 查阅规格 & 讨论: 仔细阅读 research-wiki/（单一事实源）下对应的文档，了解项目最新情况。对于不理解的地方请与人类进行多轮讨论，确保理解人类的设计意图。
3. 日志方案设计: 功能会产生运行时数据时，必须调用 structured-logging skill 设计日志方案。
4. 撰写计划: 正式编码前，必须调用 writing-plans skill 撰写实现计划。
5. 审核门控（差异化）:
   • design：Claude 自审 → Codex 审 → 人类审（保留人类门，批准后方可进入计划阶段）。
   • plan：Claude 自审 → Codex 审 → 直接执行（无 plan 人类门）；plan 经 Claude 自审 + Codex 审通过后直接进入 Phase 2 执行。

Phase 2: 执行与验证 (Execution & Verification)

1. 编码: 审核通过后，开始编写代码。
2. 验证: 声称工作完成前，必须调用 verification-before-completion skill 进行验证。
   • 环境检查: 确保所有命令在 Video-Tree-TRM 环境中执行。
   • 失败: 回到编码阶段修复，直到通过。
   • 成功: 进入下一步。

4. 核心规则 (Rules)

4.1 核心原则 (Core Principles)

以下原则按优先级排序，冲突时高优先级原则优先。

P1: YAGNI（You Aren't Gonna Need It）

• 不写当前用不到的代码。"未来可能需要"不是写代码的理由。
• 但 YAGNI 不等于砍健壮性：生产级所需的并发控制、防御校验、可观测埋点、错误隔离与测试都是"当前需要"，不在 YAGNI 削减之列。
• 抽象只在真正易变 / 需替换 / 需造测试替身的接缝处引入（见 research-wiki/ARCHITECTURE.md §3），其余写直白的领域函数。

P2: 高可读性（Readability）

• 命名：用领域术语命名，不用技术实现命名。名字应让人无需读函数体就能猜出它干什么。
• 注释：解释"为什么"，不解释"是什么"。需要注释来解释代码在做什么 = 代码不够清晰。

P3: 单一职责（Single Responsibility）

• 每个函数只做一件事，每个模块只负责一个领域。
• 判断标准：能否用一句话描述职责？需要用"和"连接 = 应该拆分。

P4: 显式优于隐式（Explicit over Implicit）

• 所有公共函数的参数和返回值必须有完整类型注解。
• 函数需要的东西通过参数传入（依赖注入），不从全局状态或环境变量中偷偷拿取。
• 严禁使用默认参数掩盖逻辑（必须显式传递关键参数）。

P5: 防御性与安全性（Defensiveness & Safety）

• 所有外部输入（用户输入、API 响应、LLM 返回、文件读取）校验后再使用。
• 严禁 except Exception: pass。每个 except 处理特定异常类型。
• 严禁出错后使用默认值掩盖错误。正确做法是直接报错。
• 敏感信息（API key、密码、token）不得出现在代码中，走 .env / 密钥管理。

P6: 可测试性（Testability）

• 纯函数优先：相同输入永远产生相同输出。
• 外部依赖通过端口（Protocol）注入，便于测试时替换成假实现（见 research-wiki/ARCHITECTURE.md §3 接缝清单）。
• 测试用例应尽可能使用真实样本，而非完全虚假的数据。

4.2 代码开发规范 (Code Style)

• 文档: 所有模块、类、方法必须包含 中文 Docstring (功能、参数、返回值、关键实现细节)。
• 运行时检查: 关键维度、设备一致性、门控条件必须通过 assertion 或 if 验证。
• 代码组织:
  • 使用阶段化注释 (# Phase 1, # Phase 2) 组织复杂逻辑。
  • 接口返回值需包含完整诊断信息（输出、统计、溯源），使用条件标志控制。
• 命名与依赖:
  • 类名 PascalCase，变量描述性命名，私有变量前缀 _。
  • 导入顺序：标准库 → 第三方库 → 项目内部。
• 日志与错误处理:
  • 使用 loguru 作为统一日志框架，禁用 print()。
  • Agent 遥测走 TelemetryRecorder Protocol（见 §4.8），不要自己拼裸 SQL 或临时落盘。
• 功能修改:
  • 必须 不考虑向后兼容，直接修改原文件。代码简洁性优先。

4.3 Git 工作流规范

• Feature Branch: 所有开发工作在 feature 分支上进行，严禁直接在 main/master 上修改。
• 增量提交: 频繁提交，每个提交有明确的语义。
• 提交前检查: 提交前 git diff 审查变更，避免提交调试代码或临时文件。
• 风险操作前备份: 执行重构或大改动前，先提交当前状态作为回滚点。
• Commit 规范: 提交代码时必须调用 commit skill。

4.4 工作区与实现规范

• 临时文件清理: 任务完成后删除所有临时脚本、调试输出、中间文件。
• 实现完整性: 开始实现就必须完成到可运行状态，严禁留下 TODO、NotImplementedError、mock 占位。
• 知识输出路径: 所有 Skill 产出的知识统一写入 research-wiki/（单一事实源）。
  • 设计文档 → research-wiki/designs/
  • 实现计划 → research-wiki/plans/
  • 调试发现 → research-wiki/findings/
  • 架构决策 → research-wiki/adrs/
  • 审查记录 → research-wiki/reviews/

4.5 配置管理规范（双模式）

本项目存在两类配置，互不混用：

模式	用途	载体	优先级
工程配置	系统运行所需、少变或敏感（API 密钥、Redis URL、LLM 超时等）	pydantic-settings + .env（敏感项不提交，模板见 .env.example）	.env 环境变量
科研实验配置	会在实验中被反复扫动 / 对比的参数（gate 阈值、batch 大小、评估口径等）	per-experiment YAML + harness run 运行快照（保证可复现）	实验 YAML

D7 配置归属判定规则（防串台，强制遵守）： 某参数是否会在科研实验中被反复扫动 / 对比？

• 是 → 科研配置（per-experiment YAML + harness run 快照）。
• 否（系统运行所需、少变、或敏感）→ 工程配置（pydantic-settings + .env）。

CLI args 仅用于单次临时覆盖，不作为任何配置的常驻来源。 配置合并优先级: CLI args > .env > YAML，三者统一归口到 dataclass。

• 原则: 上述两类载体之外，严禁在代码中散落硬编码默认值；缺失关键配置应直接报错而非兜底。
• Prompt 分类: 推理 prompt（system.md、*_extract.md、*_verify.md）存放在 store/prompts/ 下，参与版本化进化。诊断 prompt（diagnose_*.md）存放在项目根 prompts/ 下，不参与版本化——它们是评估标尺，不应随进化改变。

4.6 测试组织规范

测试哲学

• 真实场景优先: 测试用例应使用真实数据或真实数据的二次构造，而非完全虚假的样本。

• 边缘场景处理: 边缘场景不通过测试解决，而是通过代码中的 assertion/报错解决。测试只负责确保核心功能和核心场景能真实跑通。

• 测试目标: 验证系统在真实条件下的端到端正确性。生产级业务应逐步提高覆盖率并以 integration 测试为重。

• 目录: tests/{unit,integration,e2e}/test_*.py，最低覆盖率 80%

• 运行: conda activate Video-Tree-TRM & pytest tests/ --cov=app --cov=core --cov-report=term-missing

Agent 测试输出规范（仅限 agent / LLM 类测试）

下述规范只适用于涉及 agent / LLM 执行的测试；常规单元 / 集成测试无需产出该 MD。

要素	规范
输出位置	tests/outputs/<test_module>/<test_name>_<timestamp>.md
触发时机	所有涉及 Agent / LLM 执行的测试
内容要求	任务描述、每步 Agent 输入/输出/推理过程、工具调用、最终结果
格式要求	结构化 Markdown（标题、代码块、列表），人类可读
分析方式	Claude Code 读取 MD 文件，评估推理质量、任务完成度、代码正确性

pytest 集成: 使用 fixture 或工具类自动保存，测试结束后输出文件路径。

4.7 核心算法保真

迁移时逐一比对参考代码，不可简化。完整清单见 research-wiki/ARCHITECTURE.md §6（建树 4 项 + 训练 9 项 = 13 项）。

#	算法	核心逻辑
1	L2 轴心建树策略	L2 先行→L3 向下→L1 向上，asyncio 链式并发
2	VLM 批量帧描述 + JSON fallback	_L3_BATCH_SIZE=5 批量调用，解析失败逐帧 fallback
3	断点续跑机制	progress.json + L1 中间 JSON，按段恢复
4	RecursiveRetriever	Cross-Attention 选择器 + ACT halt + z 状态累积
5	CE-Gate e-process	截断 Beta 混合、四出口门控
6	信息阶梯	冷启动 2:1、gamma-EMA、反泄漏
7	块顺序验证	基线缓存、INFRA 护栏、配对翻转
8	诊断瀑布	错误归因级联、缺陷 vs 失误、D1-D5
9	进化 patch 引擎	保护跨度、rank-and-clip、附录/动量
10	Mini-batch 构建	FFD + round-robin + 正确率混合
11	Agent Loop	Thinking+JSON、json_repair、pluggy hook
12	树环境语义搜索	分块 embedding、祖先去重、锚定验证
13	训练循环编排	三级嵌套、慢更新10步、断点续训

任何 PR 涉及上述算法的修改，必须在 commit message 中标注对应序号并说明变更理由。

4.8 Agent 遥测

每次 LLM/VLM 调用必须经过 TelemetryRecorder Protocol（core/protocols.py）记录。完整规范见 research-wiki/ARCHITECTURE.md §4。

必录字段	类型	说明
call_id	str	UUID，本次调用唯一标识
parent_call_id	str?	父调用 ID（agent step → LLM call 链路）
session_id	str	epoch/step/question 关联 ID
model_name	str	使用的模型名
provider	str	API 端点标识
messages	str (JSON)	原始输入
response	str	原始输出
thinking	str	thinking/reasoning 内容
prompt_tokens / completion_tokens	int	token 用量
latency_ms	int	延迟毫秒
ttft_ms	float?	首 token 延迟（流式测量）
max_inter_token_ms	float?	最大 token 间隔（流式测量）
cache_hit	bool	是否命中 Redis 缓存
error	str?	异常信息（正常为 null）

存储实现：adapters/telemetry.py → SQLite telemetry.db。GovernedLLMClient（adapters/llm.py）在每次调用后自动写入，严禁绕过此路径裸调 LLM API。

4.9 LLM 韧性

所有 LLM/VLM 调用必须经过 GovernedLLMClient（adapters/llm.py）治理，禁止裸调 OpenAI SDK。治理栈四层（详见 research-wiki/ARCHITECTURE.md §5）：

层	机制	说明
1	熔断器	连续 N 失败 → 短路 M 秒 → 探针恢复（adapters/breaker.py）
2	Redis 响应缓存	content-addressed：hash(model + messages) → response
3	流式三层看门狗	TTFT / inter_token / total 超时保护（adapters/streaming.py）
4	指数退避重试	max_retries、base_delay、max_delay（可配置）

熔断参数（LLM_CIRCUIT_BREAKER_THRESHOLD、LLM_CIRCUIT_BREAKER_COOLDOWN）和超时（LLM_TIMEOUT、LLM_TTFT_TIMEOUT、LLM_INTER_TOKEN_TIMEOUT）通过 .env 工程配置管理。

5. 项目结构规范

目录结构遵循 research-wiki/ARCHITECTURE.md §2.3 Clean Architecture 四层分层：

project_root/
├── CLAUDE.md                # Agent 指令入口
├── README.md                # 项目概览与快速开始
├── Makefile                 # 工程命令收口（test / lint）
├── main.py                  # CLI 入口（唯一允许的根目录 .py）
├── .env / .env.example      # 工程配置（.env 不提交 Git）
├── .claude/                 # Claude 配置（skills, hooks, tools）
│
├── core/                    # 可提取内核（不依赖 app/、adapters/）
│   ├── protocols.py         # 共享端口（LLMProvider, VLMProvider, TelemetryRecorder）
│   ├── agent/               # AgentLoop 引擎（loop, types, protocols）
│   ├── evolution/           # 诊断+进化引擎（diagnose, evolve, gate）
│   └── types.py             # 跨模块共享类型
│
├── app/                     # 应用层（组合 core + adapters，领域特化）
│   ├── tree/                # 建树模块（TreeIndex, VideoTreeBuilder）
│   ├── harness/             # 训练 harness（runner, inference, batching）
│   ├── question_gen/        # 新题构建
│   ├── search/              # 搜索 Agent 装配（prompt, skills）
│   ├── retriever/           # 可训练检索器（RecursiveRetriever）
│   └── ports.py             # 应用层端口
│
├── adapters/                # 外部实现层（LLM/VLM/embedding/cache/遥测）
├── config/                  # 声明性配置（YAML，禁止 .py）
├── store/                   # 版本化资源（skills/prompts/questions/videos）
├── workspaces/              # 实验工作区
├── prompts/                 # 诊断 prompt（不参与进化，是评估标尺）
├── scripts/                 # 实验运行脚本（仅 .sh，禁止 .py）
├── tools/                   # 独立工具脚本（不被其他模块 import）
├── tests/                   # 测试代码
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── data/                    # 数据（不提交 Git）
├── logs/                    # 运行日志（不提交 Git）
├── results/                 # 实验结果输出
└── research-wiki/           # 研究知识库 = 单一事实源

硬性规则

1. 依赖只能向内：adapters/ → app/ports.py / core/protocols.py；app/ → core/；core/ 绝不依赖 app/ 或 adapters/。
2. 可提取内核判据：core/agent/ 和 core/evolution/ 搬到没有 adapters 的环境，用假实现替换 Protocol 即可原样运行。
3. 根目录除 main.py 外不得出现 .py 文件。
4. prompts/、config/ 只放声明性文件（.md / .yaml / .json），不放可执行代码。
5. scripts/ 只放 .sh 脚本，不放 .py 文件。
6. 禁止创建以下目录名：helpers/、common/、shared/、misc/、lib/。必须使用具体的领域名称。
7. data/、logs/ 不提交 Git。

6. 上下文获取与迷途指南 (Context & Navigation)

需求	文档路径	说明
系统架构与边界	research-wiki/ARCHITECTURE.md	四层分层、依赖方向、接缝清单、核心算法、韧性规范
项目目标与背景	README.md	核心业务逻辑与项目定性
关键决策记忆	research-wiki/adrs/	架构决策记录（ADR）
领域知识压缩摘要	research-wiki/query_pack.md	idea-creator 的核心上下文输入
研究知识库索引	research-wiki/index.md	所有实体的分类索引
代码结构检索	graphify-out/GRAPH_REPORT.md + conda activate Video-Tree-TRM & graphify query/path/explain/affected（主对话可用 /graphify）	读代码前先查图谱而非盲读；首次需手动 /graphify .，刷新用 /graphify . --update

7. 输出规范

7.1 语言要求

• 所有输出语言: 中文

7.2 文档撰写约束

优先使用的表达方式（按优先级排序）

1. 表格 — 对比、配置、参数说明、实验结果等结构化信息
2. 伪代码 — 描述算法和流程时，而非完整可执行代码
3. Mermaid 流程图 — 流程、架构、状态转换
4. 简洁的连贯段落 — 论述逻辑关系时，2-3 句话的短段落

严格禁止

• 禁止大段代码: 文档中不得出现超过 15 行的代码块。需要展示实现思路时用伪代码；需要完整代码时引用文件路径。
• 禁止碎片化列点: 不得出现连续超过 5 个的短句列点。改用表格或合并为连贯段落。
• 禁止冗长解释: 能用一句话说清的不用三句话。能用表格呈现的不用段落罗列。

文档长度控制

文档类型	长度上限	超出时的处理
实验报告	300 行	拆分为摘要 + 附录，摘要不超过 100 行
计划/方案（research-wiki/plans/）	1000 行	聚焦关键决策，细节留给代码注释
设计文档（research-wiki/designs/）	400 行	用 Mermaid 图替代文字描述
会议/进度记录	100 行	只记结论和 action items

8. Skill 使用规则

[!CRITICAL] Skill 调用是无条件义务，不是判断题。

当任务匹配下方触发时机表中的任一条件时，你必须在行动前通过 Skill 工具调用对应 Skill。

以下任何理由都不构成跳过 Skill 的正当依据：

• "用户已经给出了明确方案，brainstorming 不会产生额外价值"
• "这个改动很小/很简单，不需要走完整流程"
• "我判断调用后也会发现不适用"
• "用户的指令已经足够具体，不需要探索"

你没有权限做这个判断。 即使你 100% 确信 Skill 不会改变结果，仍然必须调用。 调用后 Skill 流程明确指示"不适用"时，才可以跳过后续步骤。

优先级（从高到低）：

1. 用户的显式指令（如用户说"跳过 brainstorming"则可跳过）
2. Skill 的详细流程（优先于 CLAUDE.md 中的宏观规则）
3. CLAUDE.md 宏观规则

工程类 Skill（当前主力，按触发时机强制调用）

Skill	触发时机
brainstorming	创建新功能、新组件、修改行为前
writing-plans	有需求/规格后、编码前
systematic-debugging	遇到 bug、测试失败、异常行为时
test-driven-development	实现功能或修复 bug 时
verification-before-completion	声称完成、提交、创建 PR 前
commit	提交代码时
finishing-a-development-branch	实现完成且测试通过，准备集成时
subagent-driven-development	执行实现计划时：Claude 子代理实现 + 3×Codex 审（规格合规 / 功能质量 / 代码风格）
requesting-code-review	完成重要功能、合并前（Codex 审查）
receiving-code-review	收到代码审查反馈后
structured-logging	功能会产生运行时数据时，brainstorming 之后
research-wiki	管理知识库、初始化、查询、统计时
harness-eval	功能完成后评估性能，或 subagent-driven-development Step 10

科研类 Skill（现阶段先不用，不写门控规则）

这些 skill 为一等公民资产，但项目当前处于工程为主的架构平台期，现阶段先不用；何时启用由模型依据任务实际需要自行判断，不设强制触发门控。

Skill	用途
research-lit	了解领域现状、找论文、文献综述
idea-creator	生成 / 排序研究想法
novelty-check	验证想法新颖性、查新

9. Research Wiki

项目唯一知识仓库（单一事实源），所有 Skill 产出的研究与开发知识统一存储于此。

初始化

使用 /research-wiki init 或 python3 .claude/tools/research_wiki.py init research-wiki/。

实体类型

实体	目录	来源 Skill
paper	papers/	research-lit
idea	ideas/	idea-creator
experiment	experiments/	run-experiment（未来）
claim	claims/	novelty-check
gap	gaps/	research-lit, idea-creator
design	designs/	brainstorming
finding	findings/	systematic-debugging, verification
adr	adrs/	架构决策记录（重大不可逆的技术决策）
plan	plans/	writing-plans
review	reviews/	code-review
schema	schemas/	structured-logging
metric	metrics/	structured-logging, harness-eval

关键文件

文件	说明
query_pack.md	压缩摘要（≤8000 字符），idea-creator 的核心上下文
index.md	自动生成的分类索引
log.md	所有变更的审计日志
graph/edges.json	实体间关系图（NetworkX JSON）