Exp Run

---
description: 实验执行全流程：准备代码 → 部署运行 → 监控状态 → 收集结果，支持三种运行模式
argument-hint: <experiment-slug> [--review] [--collect] [--full] [--env local|remote]
---

# /exp-run

> 执行 wiki/experiments/ 中已规划的实验。
> **三种运行模式**，适应不同场景：
> - **默认（deploy）**：仅 Phase 1-2，部署后立即返回，适合需要数小时/天的实验。
> - **`--collect`**：仅 Phase 3-4，检查已部署实验是否完成，完成则收集结果（`--check` 为 alias）。
> - **`--full`**：完整 Phase 1-4，适合几分钟内即可完成的本地快速实验。
>
> 推荐流程：`/exp-run <slug>` 部署 → `/exp-status` 监控 → `/exp-run <slug> --collect` 收集。

## Inputs

- `experiment`：wiki/experiments/ 中的 slug
  - deploy 模式：status 必须为 `planned`
  - --collect 模式：status 必须为 `running`
  - --full 模式：status 必须为 `planned`
- `--review`（可选）：Phase 1 中启用 Review LLM code review 审查实验代码（deploy / full 模式有效）
- `--collect`（可选）：collect 模式——检查实验是否完成，完成则收集结果；`--check` 是 alias
- `--full`（可选）：完整模式——执行全部 4 个 Phase（适合快速本地实验）
- `--env local|remote`（可选，默认 `local`）：部署环境
  - `local`：本机 GPU 直接运行
  - `remote`：通过 SSH 部署到远程机器（需 `config/server.yaml`）

## Outputs

- **deploy 模式**：
  - 实验代码：`experiments/code/{slug}/`（Phase 1 生成）
  - `wiki/experiments/{slug}.md` — status: planned → running
  - **DEPLOY_REPORT**（输出到终端）— 部署确认、session 信息、下一步指引
  - `wiki/log.md` — 追加部署日志
- **collect 模式**（实验已完成时）：
  - `wiki/experiments/{slug}.md` — status: running → completed，填充 outcome/key_result/date_completed
  - **RUN_REPORT**（输出到终端）— 结果摘要、metrics 对比、下一步建议
  - `wiki/log.md` — 追加收集日志
- **collect 模式**（实验仍在运行时）：
  - 仅输出进度报告到终端，不修改 wiki
- **full 模式**：同 deploy + collect 的全部输出

## Wiki Interaction

### Reads
- `wiki/experiments/{slug}.md` — 实验配置：setup、metrics、baseline、hypothesis、target_claim
- `wiki/claims/{target-claim}.md` — 目标 claim 的上下文（理解实验目的）
- `wiki/ideas/{linked-idea}.md` — 关联 idea 的 approach sketch（指导代码实现）
- `wiki/papers/*.md` — 相关论文的方法细节和超参数（参考实现）
- `wiki/experiments/*.md` — 同一 claim 的其他实验（参考 setup、避免重复错误）

### Writes
- `experiments/code/{slug}/` — 实验代码目录（Phase 1 生成，deploy / full 模式）
  - `experiments/code/{slug}/train.py` — 主训练/推理脚本
  - `experiments/code/{slug}/config.yaml` — 超参数配置文件
  - `experiments/code/{slug}/run.sh` — 启动封装脚本（含 CUDA_VISIBLE_DEVICES 等）
  - `experiments/code/{slug}/requirements.txt` — 依赖（若与主项目不同）
- `wiki/experiments/{slug}.md` — 更新 status、outcome、key_result、date_completed、run_log、remote 块
- `wiki/log.md` — 追加操作日志

### Graph edges created
- **无**。实验与 claim 的 tested_by 边已在 /exp-design 中创建。

## Workflow

**前置**：确认工作目录为 wiki 项目根（包含 `wiki/`、`raw/`、`tools/` 的目录）。

---

### Deploy 模式（默认，status == planned）

**Phase 1: 准备（Prepare）**

1. **读取实验页面**：
   - `wiki/experiments/{slug}.md`：提取 setup（model, dataset, hardware, framework）、metrics、baseline、hypothesis
   - 验证 status == `planned`
   - 若 status 为 `running`，提示用户使用 `--collect` 模式
   - 若 status 为 `completed`/`abandoned`，拒绝执行

2. **加载实现上下文**：
   - 读取关联 idea 的 approach sketch（实现指南）
   - 读取相关论文的方法描述（算法细节）
   - 读取同一 claim 的其他实验（参考代码结构）

3. **编写实验代码**，统一写入 `experiments/code/{slug}/`：
   - `train.py`：根据 setup 配置生成训练/评估脚本，包含：
     - 参数解析（argparse，所有超参数可配置）
     - 数据加载（支持 setup.dataset）
     - 模型初始化（支持 setup.model 和 baseline 模型）
     - 训练/推理循环
     - 指标计算（对应 metrics 列表）
     - 结果保存（JSON 格式，路径：`results/{slug}/seed_{N}.json`）
     - 随机种子控制（多 seed 运行）
     - Checkpoint 保存/恢复（`checkpoints/{slug}/`）
   - `config.yaml`：所有超参数（learning_rate, batch_size, epochs, seeds 等）
   - `run.sh`：封装完整启动命令（含 CUDA_VISIBLE_DEVICES、logging、conda 激活）
   - `requirements.txt`：实验专属依赖（若与主项目 requirements 不同）

4. **可选 Review LLM code review**（`--review`）：
   ```
   mcp__llm-review__chat:
     system: "You are a senior ML engineer reviewing experiment code.
              Focus on: correctness of the training loop, proper evaluation protocol,
              fair baseline comparison, reproducibility (seeds, determinism),
              proper metric computation, and common pitfalls (data leakage,
              wrong split, gradient accumulation bugs)."
     message: |
       ## Experiment
       {experiment title and hypothesis}

       ## Code
       {generated code}

       ## Expected Behavior
       {setup details from wiki page}

       Review for correctness and potential issues.
   ```
   根据 Review LLM 反馈修正代码。

5. **Sanity check（小规模验证）**：
   - 用极小规模运行（1 epoch / 100 steps / 小 subset）
   - 验证：代码无 crash、数据加载正确、GPU 可用、loss 下降
   - 若 sanity 失败 → 修复代码，重试一次；仍然失败则报告错误并停止

**Phase 2: 部署（Deploy）**

#### Local 模式（`--env local` 或默认）

1. **检查 GPU**：`nvidia-smi` 确认 GPU 可用、显存足够
2. **启动**：
   ```bash
   screen -dmS exp-{slug} bash -c \
     "cd $(pwd) && bash experiments/code/{slug}/run.sh 2>&1 | tee logs/exp-{slug}.log"
   ```
3. 更新 `wiki/experiments/{slug}.md`：
   - status: `running`
   - run_log: `logs/exp-{slug}.log`
4. **估算运行时长**，写入 frontmatter：
   根据 `setup.hardware`（GPU 型号/数量）、`setup.model`（参数量）、`setup.dataset`（规模）合理估算：

   | 典型场景 | 估算范围 |
   |----------|----------|
   | 单 GPU + 小数据集（CIFAR / 小 NLP benchmark） | 0.5 – 3h |
   | 单 A100 + 中等数据集（ImageNet / GLUE） | 4 – 12h |
   | 多 GPU 或大模型 fine-tuning（≥7B） | 8 – 48h |

   ```bash
   python3 tools/research_wiki.py set-meta \
     wiki/experiments/{slug}.md started "{YYYY-MM-DDTHH:MM}"
   python3 tools/research_wiki.py set-meta \
     wiki/experiments/{slug}.md estimated_hours {N}
   ```
5. 追加日志：
   ```bash
   python3 tools/research_wiki.py log wiki/ \
     "exp-run | deployed {slug} | env: local | session: exp-{slug} | eta: {N}h"
   ```

#### Remote 模式（`--env remote`）

**前提**：用户已配置 `config/server.yaml`。

1. **确认连通**：`python3 tools/remote.py status`
   - 若不可达 → 报错并建议检查 config/server.yaml
2. **查找空闲 GPU**：`python3 tools/remote.py gpu-status`
   - 若无空闲 GPU → 报告各 GPU 占用情况，建议等待
3. **同步代码**：`python3 tools/remote.py sync-code`
4. **安装依赖**（首次或 requirements 有变化）：`python3 tools/remote.py setup-env`
5. **启动远程实验**：
   ```bash
   python3 tools/remote.py launch \
     --name "exp-{slug}" \
     --cmd "bash experiments/code/{slug}/run.sh" \
     --gpu {gpu_index}
   ```
6. 更新 `wiki/experiments/{slug}.md` frontmatter —— 以下字段已由 /exp-design 写入完整 CLAUDE.md 模板,都是空值:
   ```bash
   # 顶层 scalar 字段 —— 用 set-meta
   python3 tools/research_wiki.py set-meta wiki/experiments/{slug}.md status running
   python3 tools/research_wiki.py set-meta wiki/experiments/{slug}.md run_log "logs/exp-{slug}.log"
   ```

   嵌套 `remote:` 块无法通过 `set-meta` 更新（set-meta 只处理顶层 scalar 字段）。直接用 `Edit` 工具就地替换这五个空的子字段值。文件里已有的 block 形如：
   ```yaml
   remote:
     server: ""
     gpu: ""
     session: ""
     started: ""
     completed: ""
   ```
   用 5 次 Edit 调用（每个子字段一次）设置 `server`、`gpu`、`session`、`started`。`completed: ""` 留空由 Phase 4 填写。如果发现文件里没有 `remote:` block,说明 /exp-design 没写完整的 CLAUDE.md 模板;停下来报 bug,不要在这里追加 block（追加会让字段顺序偏离 canonical 模板,破坏后续 edit 的匹配）。
7. **估算运行时长**，写入 frontmatter（同 local 模式估算逻辑）：
   ```bash
   python3 tools/research_wiki.py set-meta \
     wiki/experiments/{slug}.md started "{YYYY-MM-DDTHH:MM}"
   python3 tools/research_wiki.py set-meta \
     wiki/experiments/{slug}.md estimated_hours {N}
   ```
8. 追加日志：
   ```bash
   python3 tools/research_wiki.py log wiki/ \
     "exp-run | deployed {slug} | env: remote | server: {host} | gpu: {gpu} | eta: {N}h"
   ```

**输出 DEPLOY_REPORT 到终端**：

```markdown
# Deploy Report: {experiment title}

### Status: DEPLOYED ✅

- Session: exp-{slug}
- Environment: local | remote ({host} GPU {gpu})
- Log file: logs/exp-{slug}.log
- Code: experiments/code/{slug}/
- Estimated: ~{N}h（预计完成于 {YYYY-MM-DD HH:MM}）

### Next Steps

1. Monitor progress: `/exp-status`
2. Check this experiment: `/exp-run {slug} --collect`
3. In /research pipeline: progress saved to wiki/outputs/pipeline-progress.md

### Quick Commands
```bash
# Local: check if still running
screen -ls | grep exp-{slug}

# Local: tail log
tail -f logs/exp-{slug}.log
```
```

---

### Collect 模式（`--collect` 或 `--check`，status == running）

**Phase 3: 监控/检查运行状态（Monitor）**

1. **读取部署信息**：从 `wiki/experiments/{slug}.md` frontmatter 获取环境（local 或 remote）和 session 名。

2. **检查进程是否还活着**：
   - **Local**：`screen -ls | grep exp-{slug}`
   - **Remote**：`python3 tools/remote.py check --name "exp-{slug}"`，解析 `alive` 字段

3. **若实验仍在运行（alive == true）**：
   - 获取最近日志：
     - Local：`tail -30 logs/exp-{slug}.log`
     - Remote：`python3 tools/remote.py tail-log --name "exp-{slug}" --lines 30`
   - **异常检测**：
     - NaN loss：检测 `loss: nan`
     - OOM：`CUDA out of memory`
     - Traceback：Python 异常堆栈
     - Inf loss：`loss: inf`
   - **自动修复尝试**（若检测到异常，最多 1 次）：
     - NaN/爆炸 → 从最近 checkpoint 恢复，降低学习率
     - OOM → 减小 batch size，重启
   - **输出进度报告**（不修改 wiki，仅报告）：
     ```
     Experiment {slug}: RUNNING
     Progress: step {N} / epoch {E}
     Latest metric: {metric} = {value}
     Anomalies: {none | NaN detected | ...}
     Estimated remaining: ~{N} hours
     Run `/exp-status` to monitor all running experiments.
     ```
   - **返回**（不执行 Phase 4）

4. **若实验已完成（alive == false / session gone）**：
   - 继续执行 Phase 4

**Phase 4: 收集结果（Collect Results）**

1. **拉取远程结果**（仅 remote 模式）：
   ```bash
   python3 tools/remote.py pull-results \
     --remote-path "results/{slug}/" \
     --local-path "./results/{slug}/"

   python3 tools/remote.py pull-results \
     --remote-path "logs/exp-{slug}.log" \
     --local-path "./logs/"
   ```

2. **检查结果文件存在**：`results/{slug}/seed_*.json`

3. **解析结果**：
   - 读取结果文件（JSON）
   - 计算每个 metric 的 mean ± std（跨 seeds）
   - 与 baseline 对比，计算提升幅度

4. **更新实验页面** `wiki/experiments/{slug}.md`：
   - status: `completed`
   - outcome: `succeeded` / `failed` / `inconclusive`
     - succeeded：所有 success criteria 满足
     - failed：核心指标未达标
     - inconclusive：结果混合或方差过大
   - key_result: 一句话总结核心发现
   - date_completed: 今天日期
   - 填充 `## Results` section：完整结果表格
   - 填充 `## Analysis` section：初步分析
   - 若 remote 模式：更新 `remote.completed` 时间戳

5. **追加日志**：
   ```bash
   python3 tools/research_wiki.py log wiki/ \
     "exp-run | completed {slug} | outcome: {outcome} | key: {key_result}"
   ```

6. **输出 RUN_REPORT 到终端**：
   ```markdown
   # Run Report: {experiment title}

   ## Outcome: {succeeded / failed / inconclusive}

   ## Results
   | Metric | Baseline | Ours (mean±std) | Δ |
   |--------|----------|-----------------|---|
   | {metric} | {baseline-value} | {mean}±{std} | +{delta} |

   ## Key Finding
   {key_result}

   ## Next Steps
   - Run `/exp-eval {slug}` to update claims in wiki
   - {if succeeded: proceed to next experiment in plan}
   - {if failed: analyze failure, consider /exp-design revision}
   ```

---

### Full 模式（`--full`，status == planned）

依次执行全部 4 个 Phase（Phase 1 → Phase 2 → Phase 3 → Phase 4），中间不返回。

适用场景：本地 CPU/GPU 几分钟内可完成的快速实验（sanity check、toy dataset 验证等）。

Phase 3 中不需要先检查 "是否还在运行"，而是等待 screen session 真正结束后再执行 Phase 4：
```bash
# 等待 session 结束（轮询）
while screen -ls | grep -q "exp-{slug}"; do
  sleep 30
done
# session 消失，进入 Phase 4
```

---

## Constraints

- **deploy 模式只接受 planned 实验**：若 status 为 running，提示使用 --collect；若为 completed，拒绝执行
- **collect 模式只接受 running 实验**：若 status 为 planned，提示先 deploy；若为 completed，提示已完成
- **collect 模式：alive 时不写 wiki**：仅报告进度，不修改任何 wiki 文件
- **代码统一写入 experiments/code/{slug}/**：不写到项目根目录或其他位置
- **不修改 claims**：实验结果只写入 experiments/ 页面，claims 的更新由 /exp-eval 负责
- **sanity check 必须通过**：Phase 1 sanity 失败则不部署（除非用户明确 override）
- **结果文件必须保存**：所有实验结果以 JSON 格式保存在 `results/{slug}/seed_{N}.json`
- **多 seed 结果取均值**：报告 mean ± std，不报告单次运行
- **graph edges 不在此 skill 创建**：tested_by 边已在 /exp-design 中创建
- **自动修复最多尝试 1 次**：防止无限重启循环

## Error Handling

- **experiment 找不到**：提示用户检查 slug，列出 wiki/experiments/ 中的候选（status=planned 或 running）
- **deploy 模式但 status == running**：提示 "已在运行中，使用 `/exp-run {slug} --collect` 检查状态"
- **collect 模式但 status == completed**：提示 "已完成，直接运行 `/exp-eval {slug}`"
- **GPU 不可用**：报告错误，建议用 --env remote 或等待 GPU 释放
- **Review LLM 不可用**（--review 模式）：跳过 code review，在 DEPLOY_REPORT 中标注「unreviewed」
- **sanity check 失败**：详细报告错误信息，尝试自动修复一次，仍失败则停止并建议手动调试
- **远程连接失败**：报告 SSH 错误，建议检查连接配置和 config/server.yaml
- **结果文件缺失**（collect 模式）：报告哪些 seeds 缺失结果，对已有结果正常汇总；若成功 seeds < 2 则标记 inconclusive
- **实验 crash**（collect 模式检测到 traceback）：在报告中附上 crash 信息和建议修复方向
- **--full 模式等待超时**：若 screen session 超过预期时间的 2x 仍存在，警告用户但不强制终止

## Dependencies

### Skills（via Skill tool）
- 无直接调用子 skill

### Tools（via Bash）
- `python3 tools/research_wiki.py log wiki/ "<message>"` — 追加日志
- `python3 tools/remote.py <command>` — 远程操作（status, gpu-status, sync-code, setup-env, launch, check, tail-log, pull-results）
- `nvidia-smi` — 本地 GPU 状态
- `screen` — 本地后台运行管理

### Configuration
- `config/server.yaml` — 远程服务器配置（仅 `--env remote` 时需要）

### MCP Servers
- `mcp__llm-review__chat` — Phase 1 代码审查（可选，`--review` 时使用）

### Claude Code Native
- `Read` — 读取 wiki 页面和日志文件
- `Write` — 写入 `experiments/code/{slug}/` 下的实验代码
- `Bash` — 执行部署命令、监控进程

### Called by
- `/research` Stage 3a（deploy 模式）和 Stage 3c（collect 模式）
- `/exp-status --collect-ready`（collect 模式）
- 用户手动调用