experiment-bridge

工作流 1.5：实验桥接

每次审阅时段开始前，请遵循 可选审阅者： 通过规范的辅助解析器解析调用 → .aris/reviewer.json → Claude Code 默认配置（Codex MCP）， 并通过 reviewer_route.py 保留此时段的层级、新上下文、源文件／图像输入和确定性门控。 下方的 Codex 示例／固定配置仅适用于 backend=codex；其他路由使用各自首次调用／回复契约。保存 路由和实际返回的身份；无法使用的选项记为 REVIEW_UNAVAILABLE。根据实际的 系列／完成状态／范围对接受情况进行分类。将调用中的审阅者／模型／effort 覆盖项 传递给包含审阅者的子流程。生成工作进程保持不变。

根据计划实施并部署实验：$ARGUMENTS

概述

此技能连接工作流 1（创意发现 + 方法优化）和工作流 2（自动审阅循环）。它会将实验计划转化为正在运行的实验，并提供初步结果。

Workflow 1 output:                    This skill:                                    Workflow 2 input:
refine-logs/EXPERIMENT_PLAN.md   →   implement → GPT-6-Astra review → deploy → collect → initial results ready
refine-logs/EXPERIMENT_TRACKER.md     code        (cross-model)    /run-experiment     for /auto-review-loop
refine-logs/FINAL_PROPOSAL.md

常量

• CODE_REVIEW = true — 部署前由 GPT-6-Astra xhigh 审阅实验代码，及早发现逻辑错误，避免浪费 GPU 时间。设为 false 可跳过。
• AUTO_DEPLOY = true — 实施并审阅后自动部署实验。设为 false 可在部署前手动检查代码。
• SANITY_FIRST = true — 先运行 sanity 阶段的实验（规模最小、速度最快），再启动其余实验，及早发现配置错误。
• MAX_PARALLEL_RUNS = 4 — 并行部署的实验数量上限（受可用 GPU 数量限制）。
• BASE_REPO = false — 用作基础代码库的 GitHub 仓库 URL。设置后先克隆仓库，再在其基础上实施实验。设为 false（默认值）时，从头编写代码或复用现有项目文件。
• COMPACT = false — 设为 true 时：(1) 如果 idea-stage/IDEA_CANDIDATES.md 可用，则读取该文件，而非完整的 idea-stage/IDEA_REPORT.md；(2) 收集结果后，将实验结果追加到 EXPERIMENT_LOG.md。

覆盖示例：/experiment-bridge "EXPERIMENT_PLAN.md" — compact: true, base repo: https://github.com/org/project

输入

此技能需要以下一项或多项：

1. refine-logs/EXPERIMENT_PLAN.md（最佳）— 来自 /experiment-plan、由主张驱动的实验路线图
2. refine-logs/EXPERIMENT_TRACKER.md — 逐次运行的执行表
3. refine-logs/FINAL_PROPOSAL.md — 用于实施上下文的方法说明
4. idea-stage/IDEA_CANDIDATES.md — 精简版创意摘要（COMPACT: true 时优先使用）（如果未找到，则回退到 ./IDEA_CANDIDATES.md）
5. idea-stage/IDEA_REPORT.md — 完整的头脑风暴结果 （如果未找到，则回退到 ./IDEA_REPORT.md）

如果这些文件都不存在，请询问用户要实施哪些实验。

工作流

阶段 1：解析实验计划

读取 EXPERIMENT_PLAN.md 并提取：

1. 运行顺序和里程碑 — 哪些实验先运行（sanity → baseline → main → ablation → polish）
2. 每个实验块的信息：
   • 数据集／划分／任务
   • 对比系统和变体
   • 要计算的指标
   • 配置详情（backbone、超参数、种子）
   • 成功标准
   • 优先级（MUST-RUN 或 NICE-TO-HAVE）
3. 计算预算 — 预计 GPU 小时总数
4. 方法详情（来自 FINAL_PROPOSAL.md）— 具体需要实施什么

简要概述：

📋 Experiment plan loaded:
- Milestones: [N] (sanity → baseline → main → ablation)
- Must-run experiments: [N]
- Nice-to-have: [N]
- Estimated GPU-hours: [X]

Proceeding to implementation.

研究契约回退：如果 idea-stage/docs/research_contract.md 尚不存在（例如创意是在 /idea-discovery 之外选定的，或属于较早的一次运行）， 现在请使用选定的创意和实验计划中的主张，根据 templates/RESEARCH_CONTRACT_TEMPLATE.md 创建该文件。下游的 /result-to-claim 和 /ablation-planner 会将此文件作为主张来源，而会话恢复 （docs/SESSION_RECOVERY_GUIDE.md）也依赖此文件存在。

阶段 2：实现实验代码

如果设置了 BASE_REPO——请先克隆仓库：

git clone <BASE_REPO> base_repo/
# Read the repo's README, understand its structure, find entry points
# Implement experiments by modifying/extending this codebase

按顺序为每个里程碑编写实验脚本：

1. 检查现有代码——扫描项目（或克隆的 base_repo/），查找现有实验脚本、模型代码和数据加载器。尽可能复用现有代码。

2. 实现缺失部分：

   • 使用恰当的 argparse 编写训练脚本（所有超参数均可配置）
   • 编写计算指定指标的评估脚本
   • 根据需要实现数据加载 / 预处理
   • 实现尚不存在的基线
   • 固定随机种子，确保结果可复现
   • 将结果保存为 JSON/CSV，以便后续分析
   • 正确记录日志（如果 CLAUDE.md 中配置了 wandb）

3. 遵循计划中的运行顺序——先实现 sanity 阶段的实验，再实现基线，然后是主要方法，最后是消融实验。

4. 部署前自行检查：

   • EXPERIMENT_PLAN.md 中的所有超参数是否都已体现在 argparse 中？
   • 随机种子是否已固定且可控制？
   • 结果是否以可解析的格式（JSON/CSV）保存？
   • 代码是否符合 FINAL_PROPOSAL.md 中的方法描述？

阶段 2.5：跨模型代码审查（当 CODE_REVIEW = true 时）

如果 CODE_REVIEW 为 false，请跳过此步骤。

部署前，将实验代码发送给 GPT-6-Astra xhigh 进行审查：

请先解析此审查槽位；以下是 backend=codex 示例。

mcp__codex__codex:
  model: gpt-6-astra
  config: {"model_reasoning_effort": "xhigh"}
  prompt: |
    Review the following experiment implementation for correctness.

    ## Experiment Plan:
    [paste key sections from EXPERIMENT_PLAN.md]

    ## Method Description:
    [paste from FINAL_PROPOSAL.md]

    ## Implementation:
    [paste the experiment scripts]

    Check for:
    1. Does the code correctly implement the method described in the proposal?
    2. Are all hyperparameters from the plan reflected in the code?
    3. Are there any logic bugs (wrong loss function, incorrect data split, missing eval)?
    4. Is the evaluation metric computed correctly?
    5. **CRITICAL: Does evaluation use the dataset's actual ground truth labels — NOT another model's output as ground truth?** This is a common and severe bug.
    6. Any potential issues (OOM risk, numerical instability, missing seeds)?

    For each issue found, specify: CRITICAL / MAJOR / MINOR and the exact fix.

    === SCOPE LIMITS (these bound what you PROPOSE, never what you look for) ===
    Report anything that is actually wrong here — including a rare-looking case, if
    this repo actually produces it. Then keep the fix in scope:
    1. This is a RESEARCH-WORKFLOW tool, not a security paper. Verification is
       welcome; over-defense is not. Assume a cooperating operator on their own
       machine — a malicious local user is NOT in the threat model.
    2. Do NOT propose SHA / hash / content-fingerprint / digest-binding schemes.
       Reporting a real defect in hashing code that already exists is fine.
    3. NO speculative machinery: do not add feature flags, migration frameworks,
       compat layers, wrappers, pins, or similar mechanisms unless evidence shows
       a current repo defect they fix or an explicit existing invariant they must
       preserve. "Load-bearing", "compatibility", and "not scaffolding" are labels,
       not evidence. Point to the failing path/artifact or invariant, and check the
       proposal's factual premises, such as whether a named package version exists.
    4. NO corner-case obsession: exotic encodings, symlink races, RTL text and
       millisecond races are out of scope unless you can show the case arises here.
    5. Where a rubric or checklist is genuinely needed, do not over-mechanize
       judgement. A clear sentence a human reads beats a scored table nobody
       maintains.
    Exception: code that runs remote commands, starts a network service, or installs
    an MCP server runs on the user's machine with their credentials — trust-boundary
    findings there are in scope and the default is strict.
    Say plainly when something is correct. Do not manufacture findings.

审查结果处理：

• 未发现 CRITICAL 问题 → 进入阶段 3
• 发现 CRITICAL 问题 → 修复后重新提交审查（最多 2 轮）
• Codex MCP 不可用 → 静默跳过，进入阶段 3（优雅降级）

阶段 3：健全性检查（如果 SANITY_FIRST = true）

在部署完整的实验套件之前，运行健全性阶段实验：

/run-experiment [sanity experiment command]

等待完成。验证：

• 训练循环运行无错误
• 指标已正确计算并保存
• GPU 内存用量在限制范围内
• 输出格式符合预期

如果健全性检查失败 → 先自动调试，不要放弃。预算：针对同一故障最多尝试 2 次修补，然后最多进行 2 次干净重实现（总计 4 次）：

1. 读取错误信息 — 解析回溯、stderr 和日志文件。（对于令人意外的 REVIEWER 判定，同样应遵守读取主要产物的原则：参见 shared-references/review-tracing.md § 使用跟踪信息进行调试。）
2. 诊断 — 对故障进行分类：
   • OOM → 减小批次大小或启用梯度检查点
   • ImportError → 安装缺少的包
   • FileNotFoundError → 修正路径或下载数据
   • CUDA 错误 → 检查 GPU 是否可用，并减小模型规模
   • NaN/发散 → 降低学习率，并检查数据预处理
3. 修复并重新运行 — 应用修复，然后重新运行健全性检查
4. 第 2 次及之后仍失败？→ 请 Codex 救援（如果已安装 Codex 插件）： 在下一次重试前，调用 /codex:rescue，请它对根本原因给出第二意见。Codex 会独立读取代码和错误日志，可能会发现 Claude 遗漏的问题（例如张量形状错误、细微的导入遮蔽、配置不匹配等）。应用它建议的修复，然后重新运行。
   • 如果无法使用 /codex:rescue（未安装插件），则继续使用 Claude 自己的诊断
5. 两次修补都因同一故障失败？→ 丢弃并进行干净重实现 （最多重实现 2 次）。根据 EXPERIMENT_PLAN.md / 研究契约重写失败脚本，是与再次修补同等的 PEER 方案，并非最后手段——在两个错误修补的基础上再做第三次修补，通常比干净重建更糟。仅删除本次尝试自己的代码/脚手架（此阶段生成的脚本）；绝不能删除计划、EXPERIMENT_TRACKER.md、用户编写的项目源代码、收集的数据和结果（参见 shared-references/external-cadence.md § 让失败的尝试重新开始，而不只是修补）。
6. 预算耗尽（2 次修补 + 2 次重实现），或两次重实现都以相同方式失败？ → 停止，并报告故障、所有尝试过的修复及错误日志。两次干净重实现都以相同方式失败，通常意味着计划或环境有问题——请在报告中明确说明，因为需要人工处理的是这个问题，而不是失败的构建本身。不要继续使用有问题的代码。

首次失败时切勿放弃。大多数实验崩溃都可以在无需人工干预的情况下修复。

阶段 4：部署完整实验

按照计划中的里程碑顺序部署实验。根据作业数量进行路由：

小批次（每个里程碑 ≤5 个作业） → 直接使用 /run-experiment：

/run-experiment [experiment commands]

大批次（≥10 个作业、多随机种子扫描或存在阶段依赖） → 使用 /experiment-queue 进行适当编排：

/experiment-queue [grid spec or manifest]

自动路由规则：如果 EXPERIMENT_PLAN.md 中任一里程碑声明了 ≥10 个作业（例如，seeds: [42, 200, 201, ...] × N: [64, 128, 256] × n: [50K, 150K, 500K, 652K] = 36 个作业），或声明了 teacher→student 阶段依赖，则将该里程碑路由到 /experiment-queue。否则使用 /run-experiment。

/experiment-queue 提供：可感知 OOM 并采用退避策略的重试、陈旧屏幕清理、波次转换竞态预防、阶段依赖执行，以及可抵御崩溃的状态持久化到 queue_state.json。清单 YAML 格式请参见 skills/experiment-queue/SKILL.md。

对于每个里程碑：

1. 并行部署实验（/run-experiment 最多运行 MAX_PARALLEL_RUNS 个，/experiment-queue 则使用清单中的 max_parallel）
2. 使用 /monitor-experiment 跟踪进度（如果 /experiment-queue 正在运行，则从 queue_state.json 读取）
3. 实验完成后收集结果

🚦 检查点（如果 AUTO_DEPLOY = false）：

🔧 Code implementation complete. Ready to deploy:

Milestone 0 (sanity): [status — passed/pending]
Milestone 1 (baseline): [N experiments, ~X GPU-hours]
Milestone 2 (main method): [N experiments, ~X GPU-hours]
Milestone 3 (ablations): [N experiments, ~X GPU-hours]

Total estimated: ~X GPU-hours on [N] GPUs

Deploy now? Or review the code first?

阶段 5：收集初步结果

随着实验完成：

1. 解析输出文件（JSON/CSV/日志）以获取关键指标
2. 训练质量检查——如果 W&B 数据可用（CLAUDE.md 中有 wandb: true 和 wandb_project），调用 /training-check 检测 NaN、损失发散、平台期或过拟合。如果未配置 W&B，则静默跳过。
3. 更新 refine-logs/EXPERIMENT_TRACKER.md——填写 Status 和 Notes 列
4. 根据 EXPERIMENT_PLAN.md 检查成功标准——每个实验是否达到了要求？
5. 撰写初步结果摘要：

# Initial Experiment Results

**Date**: [today]
**Plan**: refine-logs/EXPERIMENT_PLAN.md

## Results by Milestone

### M0: Sanity — PASSED
- [result]

### M1: Baselines
| Run | System | Key Metric | Status |
|-----|--------|-----------|--------|
| R001 | baseline_1 | X.XX | DONE |

### M2: Main Method
| Run | System | Key Metric | Status |
|-----|--------|-----------|--------|
| R003 | our_method | X.XX | DONE |

### M3: Ablations
...

## Summary
- [X/Y] must-run experiments completed
- Main result: [positive/negative/inconclusive]
- Ready for /auto-review-loop: [YES/NO]

## Next Step
→ /auto-review-loop "[topic]"

阶段 5.5：编写精简日志（当 COMPACT = true 时）

如果 COMPACT 为 false，则完全跳过。

将每个已完成的实验追加到 EXPERIMENT_LOG.md：

## [Run ID] — [timestamp]
- **System**: [method name]
- **Config**: [key hyperparameters]
- **Result**: [primary metric = X.XX]
- **Verdict**: [positive / negative / inconclusive]
- **Reproduce**: `python train.py --config configs/run_id.yaml --seed 42`

此结构化日志可在会话恢复后保留——下游技能会读取它，而不是解析屏幕输出。

阶段 5.6：自动消融实验规划

主要实验（M2）完成并取得积极结果后，调用 /ablation-planner 来设计消融研究：

• 阅读主要结果和方法描述
• 生成由论点驱动的消融计划：要移除哪些组件、要比较什么、预期结果是什么
• 将消融模块追加到 refine-logs/EXPERIMENT_PLAN.md 和 refine-logs/EXPERIMENT_TRACKER.md
• 如果主要结果为负面或无法得出结论，则跳过消融规划并在摘要中注明

如果 /ablation-planner 不可用，则静默跳过——现有的 EXPERIMENT_PLAN.md 消融模块（如有）保持不变。

阶段 6：交接

呈现最终状态：

🔬 Experiment bridge complete:
- Implemented: [N] experiment scripts
- Deployed: [N] experiments on [M] GPUs
- Completed: [X/Y] must-run, [A/B] nice-to-have
- Main result: [one sentence]

Results: refine-logs/EXPERIMENT_RESULTS.md
Tracker: refine-logs/EXPERIMENT_TRACKER.md

Ready for Workflow 2:
→ /auto-review-loop "[topic]"

输出协议

所有输出文件均遵循以下共享协议：

• 输出版本控制协议——先写入带时间戳的文件，再复制到固定名称
• 输出清单协议——将每项输出记录到 MANIFEST.md
• 输出语言协议——遵循项目的语言设置

关键规则

• **重要：评估必须使用数据集的真实标注。**编写评估脚本时，务必将模型预测与数据集的实际真实标注/目标进行比较——绝不能使用其他模型的输出作为真实标注。仔细确认：(1) 真实标注来自数据集划分，而不是基线/骨干模型；(2) 所有方法的评估指标均根据相同的真实标注计算；(3) 如果任务提供了官方评估脚本，则使用这些脚本。
• **遵循计划。**不要擅自设计 EXPERIMENT_PLAN.md 中没有的实验。如果认为有所遗漏，请注明，但不要自行添加。
• **先做健全性检查。**未经验证确认健全性阶段通过，绝不要部署完整实验套件。
• **复用现有代码。**编写新脚本前先检查项目。应扩展，而非重复实现。
• **将所有内容保存为 JSON/CSV。**自动审核循环需要可解析的结果，而不仅仅是终端输出。
• **更新跟踪表。**每次运行完成后，EXPERIMENT_TRACKER.md 都应反映真实状态。
• **不要无限等待。**如果某项实验耗时超过预估时间的 2 倍，请标记并继续下一个里程碑。
• **注意预算。**根据计划预算跟踪 GPU 小时数。接近上限时发出警告。
• **Vast.ai 生命周期。**如果使用 vast.ai 实例，请在所有实验完成且结果已下载后销毁实例。运行中的实例每秒都在产生费用——不要让它们闲置。完成后使用 /vast-gpu destroy 或 /vast-gpu destroy-all。
• **Modal 生命周期。**如果使用 gpu: modal，无需清理——Modal 会在每次运行后自动缩容至零。但运行前务必显示费用估算，并确认已在 https://modal.com/settings 设置支出上限（绝不要通过 CLI 设置）。

与其他技能组合使用

/idea-discovery "direction"          ← Workflow 1: find + refine + plan
/experiment-bridge                   ← you are here (Workflow 1.5: implement + deploy)
/auto-review-loop "topic"            ← Workflow 2: review + iterate
/paper-writing "NARRATIVE_REPORT.md" ← Workflow 3: write the paper

Or use /research-pipeline for the full end-to-end flow (includes this bridge).