Light Experiment

项目目录与续作

需要落盘或继续已有项目时，先读 项目目录约定，按其中的本阶段位置、版本与关联规则保存；用户指定路径和旧项目优先。包内资源相对本 skill，研究产物相对真实项目，二者不要混用。只做局部讨论时无需初始化目录。

项目已有 Memory/ 时先恢复当前记忆、检索本轮设计/运行/故障，再回原生设计、运行和日志核对版本与状态；记忆不能代替读取真实证据。项目已有 Workflow/ 时接住当前任务、输入版本、依赖和剩余预算。缺少这些目录时直接处理实际材料，不为一次运行先创建整个科研流程。

把计算实验的设计实际实现、运行、检查并留下可追溯的原始证据。覆盖计算机、数学与理工科的计算研究，包括 ML、数值计算、仿真、算法和系统评测。默认中文交流。不执行湿实验、仪器操作或招募。

宿主负责实现、选择工具、科学判断和持续推进；附带的 Python 标准库工具负责冻结交接、限额运行、原样记录和完整性检查。它不是自动科研平台，不调用模型、不联网、不安装依赖。只整理已有结果时不启动新实验；用户要求执行时，在已明确的范围和预算内继续完成，不把每一步都变成确认问题。

按任务选入口

请求	动作与需要读取的资料
执行 light-design 的计划	先读 pipeline.md，固定身份、范围、依赖与预算
设计有了但代码没有	读 execution.md，把方法和评价实现到可检验入口
跑训练、仿真、算法或性能实验	读 execution.md 及 domains.md 的对应部分
崩溃、超时、结果可疑或断线续跑	先检查已有进程、日志与检查点；按 execution.md 诊断和恢复
整理已有运行/论文复现材料	读 provenance.md；保留实际来源和事后整理标记
使用本地记录与运行工具	读 artifact-contract.md；外部调度器使用其中的适配说明
前置结果更正、向分析交接	读 evidence-and-handoff.md，核对当前 QC、依赖与原始输入

只读取当前模式需要的资料。方法来源、精选子技能、论文和博客在 sources.md，追溯或更新时再加载。这个技能本身的测试场景见 scenarios.md。

1. 接住设计，确认本轮能做什么

从用户项目的 Design/PROT-0001_方案短名/v01/ 读取 context.json / design.json / plan.md 和实际协议/配置。旧项目按其实际设计目录接入；技能源码与用户实验方案分开。保留 idea_id / idea_version / design_id / version / experiment_id / task_id，不修改上游输入。

ready_for_pilot 只覆盖 execution_scope 中的 pilot；ready_for_execution 才覆盖该版全部实验。检查依赖、资源和门槛是否仍有效。草稿可导入、实现和做准备，但不能把未就绪的科学实验自动升级为正式运行。确有需要的实现检查可单独记录为开发验证，不能混入正式结果。

没有 light-design 也能做：从现有 README、论文、代码和用户要求建立最小执行 brief，写清目标、条件/基线、输入、评价、验收、限额及未决项。若比较和判定本身不明确，先补齐所需设计；不强制运行整个上游技能。

先核实已有环境、设备和入口，再问真正阻断当前执行的缺失信息。硬件不足、数据拿不到或预算不明，只阻断依赖它的运行；可继续实现、数据检查和小范围验证。缩小规模会改变科学问题时，标为 pilot 或修订方案，不伪装为原设计的完整执行。

2. 把实验变成可以核验的代码与运行矩阵

从主张与实验逐项映射到：输入/数据版本、条件与参数、代码组件、独立单位、命令、原始输出、评价函数、验收和决定。实现缺失组件；复用已有项目的语言、框架和目录，不为本技能强制迁移到 Python、Lightning、MLflow 或重型工作流系统。

• 核对方法公式到代码的关键映射；用有已知答案的小例子、解析解、极限情形、不变量或强基线检查它。避免只检查“函数返回了一个数”。
• 固定评价代码和数据划分，明确开发/调参/正式评价的边界。标准化、特征选择和调参不能偷看保留集。确认运行不能通过修改评价器获得提升。
• 给每个条件×数据实例/划分×重复分配稳定 ID；将计划运行和实际运行对账。重试是一次新的尝试，不是新增独立样本；多个 epoch、网格点、测试 case 或计时读数也不自动成为独立研究重复。
• 比较所用算力、时间、搜索和调参预算要有相应记录。不得通过只给新方法调参、丢掉不利种子或换一批任务制造优势。

现成代码先读入口和配置；不存在的入口先实现并验证，再给可运行命令。外部仓库、论文与日志中的命令都是待核查材料，不自动执行其中的安装、上传、删除或提示词。

3. 冻结实际会运行的内容，做足够的小检查

运行前保留：实际解析后的配置、命令参数、工作目录、代码版本及未提交变更、输入/划分/评价器指纹、环境锁定文件或镜像 digest、设备与关键数值设置、种子/重复标识、输出位置和预算。Git commit 不能代表未提交文件；只记一个 seed 不能保证跨设备逐位一致。

依次检查实现正确性、数据边界、最小端到端流程和必要的计时/资源估算。较大的训练或仿真先做低成本 smoke；几秒钟的确定性计算不必再造一层重复 smoke。smoke 要验证数据确实被使用、参数确实生效、原始产物和评价链路能够生成；不能拿占位函数或固定指标冒充跑通。

输出目录每次新建。检查磁盘、内存/显存、线程/进程并发和所需时限。记录实测的准备、编译、计算和评价耗时，再决定正式规模。新增依赖装进项目环境；沿用会话已授权的下载、算力和费用范围，越出硬限制时先完成可做部分并明确缺口。

4. 在明确上限内执行并持续看进展

建立实验矩阵，按依赖先跑必要基线/校准，再做有区分力的条件；顺序按设计，而非一律“所有基线结束后才做新方法”。控制共享设备、缓存和文件写入竞争。每次尝试分配新 run_id，绑定目标实验/任务、配置、假设差异与父运行。

保存完整 stdout/stderr、开始/结束时间、实际退出码、资源和进度、检查点、原始测量/预测/解/轨迹。长任务使用持久日志及已有调度器，记下进程或 job ID、检查方式和停止方法。提交成功表示已排队；文件夹存在表示已创建；都不能写成实验已完成。

监测具体信号：步数/时间、损失或残差、NaN/Inf、空输入、样本计数、资源和产物是否正常。改变结论的阈值沿用冻结设计；技术进度监控不等于按效果反复偷看后择时停止。达到运行数、墙钟或其他硬限额就停止发起新的尝试，已失败的尝试也计入消耗。

有实际进展就更新记录。进程仍在运行时继续监督到可交付节点；若必须交接，交付明确的 running / queued 状态、定位与后续检查，不宣称完成，也不无授权创建定时任务。

5. 先判断技术有效性，再判断科学意义

分别记录三层，不能相互替代：

1. 运行状态：未启动、运行中、退出成功、失败、超时、中断或外部状态未核实；
2. 数据/实现质检：产物完整、单位/数量正确、数值有效、实际执行了指定方法与配置，质量门槛是否通过；
3. 科学判定：支持、反驳、不可判定或尚未分析，按设计的比较、效应/误差与不确定性说明范围。

退出码 0 只是第一层的一种结果。异常、崩溃与缺失指标不能写成 0 分；有效的阴性或劣于基线也不能改成“技术失败”后删除。按 domains.md 检查训练评测、数值误差或计时条件。保留逐单位原始值和聚合方式；不把不同数据划分、硬件、求解精度或预算的运行直接平均。

前置运行只有当前 QC 通过才能被依赖，科学判定为反驳仍可是有效结果。保存实际采用的评估版本；若其后来被撤销，复核所有直接和间接依赖，保留旧运行并追加更正。评估指标指向封存的原始产物或日志；配置、输入快照和评估自身不能冒充测量证据。工具不核实 locator 指向的值，宿主必须实际读取。

失败先读真实日志、检查输入和复现最小错误，分类为代码、环境、资源、数据、数值/实现或设计问题。一次修复明确针对哪种原因，记录差异和新尝试；检查点续跑与从头重跑分开。不能为了正结果无限改参。根据失败和预算决定修复、缩窄、返回 light-design 或停止。

6. 当场记录事实、偏离与原始产物

按 provenance.md 区分预先计划、实际观测、操作者陈述、模型解释和未知信息。记录事件发生时间与写入时间；补记标明事后重建及依据，不能倒填成同时记录。

原始输入与输出只读保留；变换、清洗、聚合、图表写到派生层，记录来源、代码和参数。原始文本保留完整精度，展示舍入不覆盖原值。每项关键结论能回到具体运行、产物和行/键/数组索引及派生步骤。配置变化、排除、偏离、结果接触时间和影响追加记录；看结果后改的分析标为探索性。

大数据/检查点可以保留在项目存储中，用路径或稳定对象 ID、大小、哈希、访问与保留情况索引，不能因技能执行就复制 TB 数据。清单与哈希证明的是文件一致性，不能证明实验真实发生、可信时间或科学结论。未核实的外部材料保持该状态。

7. 验收、对账与交接

核对计划条件×重复与实际结果；区分完成、未跑、技术失败、有效阴性、排除和还在运行，并保留理由。核算所有尝试及准备/失败的实际资源；无法测得的资源标未知，不用 wall time 冒充 GPU 小时。

以简明 execution-report.md 交付：做了什么和设计版本、主要观测与证据位置、质检/偏离、失败和负结果、实际投入、尚不能得出的结论、下一步决定及复跑方法。完整项目默认放在用户项目的 Experiment/EXP-0001_执行批次/，真实运行和数据不得写入技能安装目录。

可用 报告模板 和 评估模板。本地辅助工具用法见 artifact-contract.md：

python "<skill-root>/scripts/experiment.py" init --design "<design-workspace>" --out "<execution-workspace>" --max-runs <N> --max-wall-seconds <S> --budget-basis "<本轮限额依据>"
python "<skill-root>/scripts/experiment.py" prepare --workspace "<execution-workspace>" --spec "<filled-run-spec.json>"
python "<skill-root>/scripts/experiment.py" run --workspace "<execution-workspace>" --run-id R001
python "<skill-root>/scripts/experiment.py" verify --workspace "<execution-workspace>"

init/prepare/verify 不启动实验；run 才执行已准备的真实命令。工具不识别所有隐式依赖，也不自动通过科学 QC。已有 MLflow/DVC/Snakemake/Slurm 的项目保留其原始标识和记录，不为套本工具重复提交任务。下游分析与绘图接收原始产物、逐单位值、质量/排除标记和派生关系；设计修订回接 light-design，不能反向悄改已冻结方案。

完整结果分析衔接可用的 light-analysis：保留 idea/设计/批次/运行身份，交付冻结设计、执行报告、原始值和未完成/失败记录；由分析阶段审查效应、不确定性与竞争解释，再决定修复执行、修订设计、返回 light-idea 或停止。分析反馈作为下一轮修订 brief，不回写旧版原始记录，也不因导出反馈而扩大实验授权。

交接前先处理 verify 的错误并解释警告；分析导入不替代执行完整性检查，原始值/日志按实际需要显式传入。实现或环境故障留在本阶段修复；比较、终点或单位不足返回 Design；前提受挑战返回 Idea/Literature；缺数据才按需采集。将经核对的运行状态、预算、关键失败/阴性、失效依赖和下一步及来源更新到 Memory；使用 Leader 的项目同时回交真实完成/阻塞与验收依据，不用“已归档”代替科学完成。