exp-batch

Exp Batch：确认必要性 → 明确配置 → 预检 → 运行 → 汇总指标

小而完整：一个分支，做好做扎实，可用于绘图。不要横向扩展到其他分支；也不要为了节省时间而降低严谨性。

1. 确认该分支是否仍有必要

• 检查项目记忆、实验计划和现有结果：是否已有探测实验剪除了该分支？是否已在等效配置下测量了该指标？如果是，请说明并停止（或记录为何先前的剪枝不适用）。
• 用 2-3 句话重述：本批次为最终表格/图表新增什么、填补哪些单元格，以及验收指标是什么。无需计划文档。

2. 只审议尚未确定的配置决策

• 路径、设备可用性、缓存位置、先前配置等事实由你检查。只向用户询问会改变科学含义的选择：协议未固定的超参数、种子数量、使用哪个拆分、覆盖回调还是重新加载，以及正式还是探索性状态。
• 保持本批次的指标约定与同类运行完全一致：拆分、指标定义和测量面都相同。测量方式不同的批次不能与其他批次共用一张图——如有偏差，须在记录中明确标出。
• 提出一轮结构化问题；只有当回答引出了真正新的科学选择时，才允许进行第二轮。如果配置决策变得繁杂，这实际上就是一场实验活动——建议使用 exp-campaign。

3. 预检：环境与资源

未完成此检查就启动的运行，迟早会与其他人争用默认设备。此检查只需几秒钟，无需审批，并且每次启动前都要执行——无论是探测还是正式运行，无论长短。跳过繁文缛节才是重点（不搭建脚手架、不写防御性代码、不增加审批轮次）；这次检查不属于繁文缛节。

• **环境：**解释器/环境是否已激活、工作目录、当前实际可导入的依赖版本、输入路径是否存在、输出目录和检查点目录是否可写。
• **先确认平台：**使用项目记忆、约定或当前会话已指定的设备平台（CUDA / Ascend / MUSA / PPU-class / …）。如果确实未知，就从环境中确认（已安装的工具包、设备文件、项目自身启动器设置的内容），或询问一次；然后使用该平台自己的工具和变量术语——平台选错导致的错误是自找的，也会浪费运行资源。
• 按实际情况检查资源，而不是按通常情况推断：使用当前机器上的工具读取实时设备状态——nvidia-smi、Ascend 的 npu-smi、MUSA 的 mthreads-smi 或该平台的等效工具——查看利用率、内存，以及每台设备由哪个进程占用（他人的作业和本项目其他并行分支都要算在内）。根据检查结果做出决定，并通过平台对应的可见设备变量（CUDA_VISIBLE_DEVICES、ASCEND_RT_VISIBLE_DEVICES、MUSA_VISIBLE_DEVICES、…）明确指定设备；绝不能让运行落到默认设备上。检查点/日志所需磁盘空间，以及任务不受设备限制时所需的 RAM/CPU，也应一并检查。
• **冲突：**先前尝试遗留的作业（“上次的任务真的结束了吗？”）和同级分支通常会暗中占用显卡；查看进程列表中的所有者、名称和已运行时间即可确认。
• **成本：**如实估算该配置所需的运行时间/内存，以便之后能将资源争用识别为资源争用，而不是归咎于代码。
• 然后运行，并遵守项目关于由谁启动哪些任务的规定。如果可用资源无法满足配置要求，不要启动，也不要悄悄缩小配置：说明缺少什么，并在等待、换用另一台设备或经协商更改配置之间做出选择。

4. 在本次会话中实现，并遵循项目规范运行

• 研究人员发出开始指令后，在此处的同一会话中进行实现。不转交到新会话（那是 exp-campaign 的模式）；执行时机由研究人员把控，正式运行遵循项目对启动者的规定——由研究人员运行，或经其明确授权后运行。
• **模块放置：**将每部分代码放入所属模块；实验专用代码应放在实验自己的目录中，并采用可预测的布局，以便按名称找到实验。不要为单个使用方创建共享抽象；如果兄弟分支会因此争用同一个文件，则拆分为独立模块。
• **松散耦合：**通过现有接口使用稳定的共享库。绝不修改共享内部实现来适配本批次，也不要向共享代码添加批次专用分支。如果接口确实缺少所需功能，请停止并升级处理——这是整个 campaign 层面的决策。
• **Ponytail 研究代码：**只编写能正确运行本批次所需的最少代码。**不要进行防御式编程：**不要添加推测性的校验、“以防万一”的分支，也不要吞掉错误——发生错误时，带着真实错误退出。运行失败时，首先怀疑环境（设备争用、磁盘已满、缓存过期、作业冲突），再怀疑代码；只有证据表明代码有误时才修改代码。
• 留意此类项目已知的失败模式：OOM（你自己的或机器的）、NaN、检查点序列化、指标退化崩塌（例如答案完全相同），以及驱逐——其他作业或内核在运行期间占用设备。发生故障时：保留失败产物和日志，尽可能缩小隔离范围，绝不要将失败的运行报告为结果行。
• **采取行动前，先区分“环境”和“代码”：**退出代码、日志末尾内容，以及使用平台自带工具重新读取设备状态（我的进程还活着吗？现在是谁在使用设备？），可帮助区分作业被驱逐和真正的错误。被驱逐的运行要保留证据，依据实时读取结果选择空闲设备，并在记录偏差后重新排队；只有证据表明代码有误时才修改代码。为了适应资源而更改配置时必须标记——这可能破坏与兄弟运行之间的指标契约。
• **这些模式只是典型情况，并非全部。**出现意料之外的故障时，由你当场处理：作出判断、保留证据，并说明采取了什么措施。不要停下来等待不存在的规则，也绝不要让故障被当作结果通过。
• 负面结果也是结果：使用与成功结果相同的架构记录。

5. 使用 later 等待长时间运行（委派执行）

长时间运行（数小时设备时间）不得占用当前轮次，也不得循环轮询。无人值守模式如下：

• 明确委派。“运行并检查结果”即表示委派执行。如果研究人员尚未委派，应在启动前先询问：“这需要约 X 小时；我可以在后台运行，并通过 later 工具自动恢复——要委派给我吗？”说明在批次完成前，每一轮都会以安排 later 结束。
• 在后台启动，遵循项目约定（nohup/tmux/启动器），然后调用 later 工具：估算运行时长，增加约 10% 的余量（运行 5 小时 → 安排 5.5 小时），并将提示词写成给未来自己的完整指令——需要检查什么、做出什么判断、接下来运行什么。
• 安排后结束本轮——later 调用必须是本轮的最后一个动作：等待期间不得空转、循环或消耗 token 进行轮询。安排的提示会作为用户消息到达，并在没有人工介入的情况下恢复会话。跨运行串联唤醒：每次唤醒时检查、判断、启动下一次运行，并安排下一次 later。
• **计时器只是估算值，并不代表运行已完成。**唤醒后，记录指标前要确认运行确实已完成且成功。如果仍在运行，则根据观察到的进度（日志/epoch 计数器、当前吞吐量——资源争用可能会让原计划 5 小时的运行延长到 7 小时）重新估算剩余时间，不能沿用原计划，并为剩余时间加上余量后再次安排 later。重复此过程，直到运行实际完成；唤醒次数不限。
• 如果主机没有 later 工具，则采用降级方案：告知研究人员预计时长和返回时间，或遵循项目自身的等待约定。

6. 将指标写入可用于绘图的位置

• 每次运行都要写入共享结果表，包含：id、配置、数据拆分、表面、指标、状态、证据路径。记录每个 epoch/数据点，不仅是选定的结果。
• 完成前检查数据是否适合绘图：这批数据能否作为独立曲线系列纳入最终图表，并包含所需的锚点（基线参考线）？如果数据形态会导致绘图不理想（孤立点、混用坐标轴），现在就修正数据收集方式，不要等到绘图时再处理。
• **必须撰写批次报告——包括部分完成、受阻或中止的工作。**在项目计划文件旁创建 <batch-or-stage>.report.md（默认路径为 docs/experiments/<slug>.stage<N>.report.md；独立分支的报告放在项目的实验目录中），内容包括：完成情况总表（按计划的每次运行/单元列出：完成 / 部分 / 搁置 / 未动 + 证据路径）、实际运行的准确配置和命令、未运行的内容及原因、指标约定偏差、失败情况及处理方式（驱逐 / OOM / NaN），以及项目需要重新考虑的事项。绝不伪造结果行，也不得默默跳过计划中的运行。
• 在聊天中简要报告相同内容。规划会话不会因这批工作而唤醒——研究人员会带回报告，因此需要审阅的是该文件。