From 92ea93eff6df0a1a5cd5cbe0b4eacebc6ade45fe Mon Sep 17 00:00:00 2001 From: iomgaa Date: Mon, 6 Jul 2026 11:39:12 -0400 Subject: [PATCH] docs: add overview.md with system overview and module structure Co-Authored-By: Claude Opus 4.6 (1M context) --- research-wiki/overview.md | 76 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 research-wiki/overview.md diff --git a/research-wiki/overview.md b/research-wiki/overview.md new file mode 100644 index 0000000..5dd5211 --- /dev/null +++ b/research-wiki/overview.md @@ -0,0 +1,76 @@ +# 系统总览 (Overview) + +> Video-Tree-TRM5：在层次化视频树上构建可自我进化的搜索 Agent + 可训练递归检索器，通过 Harness Engineering 持续改进实现长视频理解。目标会议 EMNLP 2026。 + +## 1. 核心思想：自进化循环对标 PyTorch 训练 + +系统外层是一个 `for epoch` 循环，每轮跑 `推理 → 诊断 → 进化`，对标神经网络训练： + +| PyTorch | 本项目 | 代码位置 | +|---------|--------|----------| +| DataLoader | 出题 question_gen | `app/question_gen/generator.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` | + +只有 inference 是 agent-controlled（LLM 自主调工具），其余三步是 code-controlled workflow。 + +## 2. 模块结构 + +```mermaid +flowchart TD + main[main.py CLI 入口] --> runner[app/harness/runner.py 训练循环] + main --> build[app/tree/video_builder.py 建树] + main --> qgen[app/question_gen/generator.py 新题构建] + main --> train_ret[app/retriever/train.py 检索器训练] + + runner --> inf[app/harness/inference.py 推理] + runner --> diag[core/evolution/diagnose.py 诊断] + runner --> evo[core/evolution/evolve.py 进化] + runner --> ws[app/harness/workspace.py Store + Workspace] + + inf --> loop[core/agent/loop.py AgentLoop] + loop --> search[app/search/ prompt + skills] + loop --> llm[adapters/llm.py GovernedLLMClient] + build --> vlm[adapters/vlm.py] +``` + +## 3. 模块职责 + +| 模块 | 职责 | +|------|------| +| `app/tree/` | 建树模块：VLM 生成三层 TreeIndex（L1段落→L2片段→L3帧），字幕注入与后增强 | +| `app/harness/` | 训练 harness：runner 循环编排、推理 step、mini-batch、信息阶梯、workspace 版本管理 | +| `app/question_gen/` | 新题构建：题目生成、基线校准、去重 | +| `app/search/` | 搜索 Agent 装配：PromptManager + SkillRegistry | +| `app/retriever/` | 可训练检索器：RecursiveRetriever（CrossAttention+ACT）、两阶段训练 | +| `core/agent/` | AgentLoop 引擎：Thinking+JSON 推理循环，pluggy hook 驱动 | +| `core/evolution/` | 诊断+进化引擎：两阶段诊断、patch/rewrite 进化、CE-Gate e-process | +| `adapters/` | 外部实现层：GovernedLLMClient（遥测+熔断+缓存）、VLM、Embedding、ASR、OCR | + +## 4. 资源与工作区 + +| 路径 | 含义 | +|------|------| +| `store/` | 版本化资源 = "模型权重"：`skills/`、`prompts/`、`questions/`、`videos/` | +| `workspaces/` | 一次"训练实验"工作区，如 `video-mme-v1`。每次 run 冻结 config + Store 快照，保证可复现 | + +进化产出版本化（`skills/v1`, `v2`...）= 可回滚的 checkpoint；进化 validation（长度/格式约束）= grad clipping。 + +## 5. 可提取内核 + +`core/agent/` 和 `core/evolution/` 是两个独立可提取包，**只依赖 Protocol 接口**，不依赖 `app/`、`adapters/` 或任何框架。 + +| 可提取包 | 包含 | 依赖的 Protocol | +|----------|------|----------------| +| `core/agent/` | `loop.py`、`types.py`、`protocols.py` | `LLMProvider`、`VLMProvider`、`ToolDispatcher` | +| `core/evolution/` | `diagnose.py`、`evolve.py`、`gate.py`、`validate.py`、`types.py`、`protocols.py` | `SkillStore`、`PromptStore`、`RunLog`、`TelemetryRecorder` | + +判据：将它们连同 `core/types.py` 复制到另一个项目，提供 Protocol 假实现即可原样运行。 + +## 6. 实现路线 + +详见 `research-wiki/designs/` 下各设计文档与 `research-wiki/index.md`。