iomgaa/Video-Tree-TRM5
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
49d6fe8f51eb15169750beb6dce53201086a3f5d
Video-Tree-TRM5/CLAUDE.md
T
iomgaa da28c10c84 docs: 同步 question_gen 模块路径到 ARCHITECTURE.md 和 CLAUDE.md 
DataLoader 代码位置 generator.py → loader.py；
目录树更新 question_gen/ 结构反映实际文件。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-07-07 04:51:26 -04:00

452 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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，并且不要进行任何形式的日志缓存，确保所有日志可以立刻马上输出，这有助于帮助我们检查错误。
```bash
# 激活项目环境（交互式 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`。
```bash
make test # conda 环境内跑 pytest + 覆盖率
make lint # ruff check --fix + ruff format（app/ core/）
```
### 2.3 代码质量检查
```bash
# 代码格式化
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 卡号除外）。
```bash
# 典型调用
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 四层分层：
```text
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） |
Reference in New Issue View Git Blame Copy Permalink