Lambenthan/empiricalwiki / .claude/skills/exp-run
exp-run
Verified实验执行全流程:准备代码 → 部署运行 → 监控状态 → 收集结果,支持三种运行模式
/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
- deploy 模式:status 必须为
--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_claimwiki/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)
-
读取实验页面:
wiki/experiments/{slug}.md:提取 setup(model, dataset, hardware, framework)、metrics、baseline、hypothesis- 验证 status ==
planned - 若 status 为
running,提示用户使用--collect模式 - 若 status 为
completed/abandoned,拒绝执行
-
加载实现上下文:
- 读取关联 idea 的 approach sketch(实现指南)
- 读取相关论文的方法描述(算法细节)
- 读取同一 claim 的其他实验(参考代码结构)
-
编写实验代码,统一写入
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 不同)
-
可选 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 反馈修正代码。
-
Sanity check(小规模验证):
- 用极小规模运行(1 epoch / 100 steps / 小 subset)
- 验证:代码无 crash、数据加载正确、GPU 可用、loss 下降
- 若 sanity 失败 → 修复代码,重试一次;仍然失败则报告错误并停止
Phase 2: 部署(Deploy)
Local 模式(--env local 或默认)
-
检查 GPU:
nvidia-smi确认 GPU 可用、显存足够 -
启动:
screen -dmS exp-{slug} bash -c \ "cd $(pwd) && bash experiments/code/{slug}/run.sh 2>&1 | tee logs/exp-{slug}.log" -
更新
wiki/experiments/{slug}.md:- status:
running - run_log:
logs/exp-{slug}.log
- status:
-
估算运行时长,写入 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 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} -
追加日志:
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。
-
确认连通:
python3 tools/remote.py status- 若不可达 → 报错并建议检查 config/server.yaml
-
查找空闲 GPU:
python3 tools/remote.py gpu-status- 若无空闲 GPU → 报告各 GPU 占用情况,建议等待
-
同步代码:
python3 tools/remote.py sync-code -
安装依赖(首次或 requirements 有变化):
python3 tools/remote.py setup-env -
启动远程实验:
python3 tools/remote.py launch \ --name "exp-{slug}" \ --cmd "bash experiments/code/{slug}/run.sh" \ --gpu {gpu_index} -
更新
wiki/experiments/{slug}.mdfrontmatter —— 以下字段已由 /exp-design 写入完整 CLAUDE.md 模板,都是空值:# 顶层 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 形如: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 的匹配)。 -
估算运行时长,写入 frontmatter(同 local 模式估算逻辑):
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} -
追加日志:
python3 tools/research_wiki.py log wiki/ \ "exp-run | deployed {slug} | env: remote | server: {host} | gpu: {gpu} | eta: {N}h"
输出 DEPLOY_REPORT 到终端:
# 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/"
-
检查结果文件存在:
results/{slug}/seed_*.json -
解析结果:
- 读取结果文件(JSON)
- 计算每个 metric 的 mean ± std(跨 seeds)
- 与 baseline 对比,计算提升幅度
-
更新实验页面
wiki/experiments/{slug}.md:- status:
completed - outcome:
succeeded/failed/inconclusive- succeeded:所有 success criteria 满足
- failed:核心指标未达标
- inconclusive:结果混合或方差过大
- key_result: 一句话总结核心发现
- date_completed: 今天日期
- 填充
## Resultssection:完整结果表格 - 填充
## Analysissection:初步分析 - 若 remote 模式:更新
remote.completed时间戳
- status:
-
追加日志:
python3 tools/research_wiki.py log wiki/ \ "exp-run | completed {slug} | outcome: {outcome} | key: {key_result}" -
输出 RUN_REPORT 到终端:
# 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:
# 等待 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
/researchStage 3a(deploy 模式)和 Stage 3c(collect 模式)/exp-status --collect-ready(collect 模式)- 用户手动调用
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |