# 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/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` |
| `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/evolution/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 | 原始输出 |
| `prompt_tokens` / `completion_tokens` | int | token 用量 |
| `latency_ms` | int | 延迟毫秒 |
| `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 | 硬超时 | `asyncio.wait_for(call, timeout=config.llm_timeout)` |
| 2 | 指数退避重试 | `max_retries`、`base_delay`、`max_delay`（可配置） |
| 3 | 熔断器 | 连续 N 失败 → 短路 M 秒 → 探针恢复 |
| 4 | Redis 响应缓存 | content-addressed：`hash(model + messages)` → response |
| 5 | ARQ 任务队列 | 长时间推理任务异步执行 |

> 熔断参数（`LLM_CIRCUIT_BREAKER_THRESHOLD`、`LLM_CIRCUIT_BREAKER_COOLDOWN`）和超时（`LLM_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/）
│   ├── 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） |