jasperpwang 科研开发与实验设计规范（Lab Codex）
在协助科研与开发时，默认遵循以下规范；与用户明确指令冲突时，以用户指令为准。
一、基础原则
基于证据
- 分析、结论、方案须建立在实际代码、运行输出、实验指标或数据之上。
- 在缺少可核验证据时，不臆测、不过度自信；应说明假设、建议如何验证（读代码、跑测试、小规模实验）。
测试驱动开发
- 先有可执行的验证手段（单元测试、脚本断言、或约定的可视化/数值检查），再扩展实现。
- 功能到位后，用可视化与数据核对效果，再合并或宣称完成。
顺序执行
- 按约定步骤推进，不擅自跳过某一步。
- 若某步受阻：先说明阻塞原因与可选方案，与用户沟通后再继续；仅在用户明确授权时可临时跳过。
小步迭代
- 避免单次提交中堆叠大量未验证的模块、损失项或配置分叉。
- 优先小范围改动 → 验证 → 再下一处。
探索性实验：先过最小可行性门
- 当用户提出任何新研究想法、方法改动或实验设想时，先设计最小可行实验（Minimum Viable Experiment, MVE），再决定是否实现完整系统或启动大规模训练。
- 在开始任何实验之前，首先回答：这个最小实验要验证什么？成功的标准是什么？ 若不能给出清晰、可测量的答案，停止执行并继续收敛实验问题。
- 把“最小”理解为：以最低资源成本获得足以改变下一步决策的可信证据；不要把它误解为代码最少、样例最少或做一个无法代表真实问题的玩具演示。
- 优先验证整个方向中风险最高、最可能使项目失效的核心假设。若实验同时混入多个新机制，先拆成能单独归因的实验。
- 未明确核心假设、判定阈值、资源上限和结果分支时，不进入高成本执行阶段。
设计实验前，先给出一张最小可行实验卡：
- 第一问题：这个最小实验要验证什么？成功的标准是什么？ 分别写出一句可证伪的验证目标和一个预先确定、可测量的成功阈值；不得用“效果不错”“看起来可行”等主观表述代替。
- 最高风险假设：指出哪个前提一旦不成立，后续系统即失去继续投入的价值。
- 最小实验：只保留检验该假设所必需的数据、模块、训练步骤和输出；说明删掉了哪些非必要部分。
- 对照与基线：至少提供一个最弱但有效的 baseline、control 或 sanity check，使结果能够归因，而不只是证明代码能运行。
- 其余判据：在第一问题已经定义成功标准的基础上，再预先写明反驳和无法判定的可测量条件；判据尽量接近二元，但必须保留“证据不足”分支。
- 资源上限：预先限定时间、GPU 小时、样本量、分辨率、训练步数和允许尝试的配置数。默认先问：“如果只有一天，怎样获得最有判别力的结果？”
- 最低复现证据：保留代码版本、可复制命令、配置、数据切片、随机种子、环境、日志、原始输出和产物路径；可以降低系统完整度，不得降低证据完整度。
- 决策分支：实验前写清结果为支持、反驳或无法判定时分别采取的下一步，以及停止继续投入的条件。
执行最小化时遵循以下顺序：
- 先用极少样本完成数据流、维度、损失、指标和可视化的 smoke test；涉及学习时优先做单 batch 过拟合检查。
- 在不破坏核心假设的前提下，优先复用预训练模型、冻结 backbone、缓存特征、降低分辨率或序列长度、缩小数据子集，并考虑 LoRA / Adapter 等参数高效微调。
- 只改变一个关键机制，固定其余变量；不要用同时加入多个模块的结果声称某一机制有效。
- 最小实验通过预设门槛后，才允许扩大数据、模型、训练时长或系统复杂度，并且每轮只扩大一个主要维度。
根据结果作出明确处理：
- 支持：把结论限制在当前数据、指标和资源边界内；下一轮只增加一层复杂度，并设置新的门槛。
- 反驳：先区分原理失败、实现失败和测量失败，再决定修正、转向或终止；不得把一次未跑通直接等同于科学假设被推翻。
- 无法判定：优先提高实验的判别力、检查方差与测量敏感性；不得默认通过扩大算力掩盖设计问题。
研究循环
- 每个重要实验或分析都应写成一个可校正循环：
假设 / 设置 / 预测 / 结果 / 更新后的判断 / 下一步最小动作。 - 在运行前写下预测，训练对模型、数据、baseline、损失项和指标的品味；不要只在看到结果后解释。
- 优先缩短发现错误的时间：单命令运行、单命令画图、可复现 config、小数据切片、单 batch 过拟合检查。
- 看指标前后都要检查原始输出：可视化、失败样本、日志、几何结果、视频、渲染图或数据样例。
- 对失败样本做聚类：先攻击最大的失败堆，再决定是否扩大实验规模。
- 任何新增方法结论都要经受 baseline 调参、最小 ablation、数据/评价边界检查。
实验环境优先级：tmux first + Docker first
- 默认路线：tmux first 保证长任务不中断，Docker first / Docker Compose 保证环境可复现。
- 需要在服务器上跑实验、训练、下载数据、编译或长时间配置环境时，先进入
tmux会话，再启动命令；不要把长任务裸跑在普通 SSH shell 里。 - 宿主机只保持最小稳定层：SSH、tmux、NVIDIA Driver、Docker、Docker Compose、NVIDIA Container Toolkit、存储挂载。
- 项目依赖默认进入容器：CUDA runtime、Python、PyTorch、系统库、编译依赖、项目包版本。
- 配新服务器或新项目环境时，先检查：
- 项目是否已有
Dockerfile/docker-compose.yml/.devcontainer； - 服务器是否通过
nvidia-smi、docker --version、docker compose version； docker run --rm --gpus all ... nvidia-smi是否能看到 GPU；- 代码、数据、cache、checkpoints、outputs 是否挂载到稳定目录。
- 项目是否已有
- 只有 Docker 不可用、权限不足或临时救急时，才用 conda / pip-on-host / system package 作为 fallback，并在结果中说明原因。
- 不静默接受 Anaconda Terms of Service，不随意修改全局 conda channels，不把项目依赖散装到宿主机。
- 环境完成的最低标准：容器内跑通项目最小验证命令，例如
nvidia-smi、核心 Python import、单 batch overfit、dry run 或 smoke test。
大文件下载与断线恢复协议
下载模型权重、数据集、预训练资产或其他大文件时，默认把下载视为可恢复、可验证的实验基础设施，而不是一次性 shell 命令：
- 服务器下载必须先进入独立的
tmux会话；SSH/VPN 断开后只重新连接并恢复会话，不从头启动下载。 - 下载工具必须支持断点续传、自动重试、连接/读取超时和退避等待；VPN 不稳定时默认降低并发，避免用高并发掩盖网络问题。
- 下载到临时文件（例如
.part），完整下载并通过校验后再原子改名为最终文件；训练或实验程序不得读取未验证的临时文件。 - 下载前检查稳定挂载点、剩余磁盘空间和解压空间；数据、模型、cache、checkpoint、日志和 outputs 不得只存在于
/tmp、容器临时层或 SSH 会话目录。 - 为每个下载记录 manifest：资源名称、来源 URL、仓库 revision/tag/commit、配置或 split、预期大小、SHA256、目标路径、下载时间和工具信息。不得用未固定的
latest作为实验依赖。 - 下载完成后必须验证 SHA256；若上游未提供哈希，至少验证文件大小、压缩包完整性、目录结构和随机读取结果，并明确记录降级验证。
- 验证通过后再做最小可用性测试：模型至少完成配置/tokenizer/权重索引读取或一次最小推理；数据集至少完成样本计数、随机读取和一个最小 batch。
- 校验失败、空间不足或下载中断时，不得把文件标记为可用；保留错误日志和恢复状态，修复后从断点继续并重新校验。
- 下载来源应使用官方仓库或用户指定来源；切换镜像、版本、数据配置或文件格式时，必须记录原因并更新 manifest。
完成前审查
- 在宣称功能完成前，做一次针对性审查，重点包括：
- 关键张量/数组的维度变换是否与数据管线一致；
- 输入输出形状与 API 契约；
- 分支与边界下的逻辑是否正确。
二、文档维护（仓库根目录相对路径）
路线图：RoadMap.md
- 在讨论与实现功能过程中同步更新。
- 记录：当前分支相关功能、已知问题、待办与优先级（简明、可执行）。
实验记录：Notion（不再维护 docs/Experiment.md / 根目录 Experiment.md）
实验记录的权威落点是 Notion 实验页；不要新建或继续更新仓库内
Experiment.md，除非用户明确要求临时例外。写作结构与验收以
experiment-report-writing为准：章节标题用简短英文序号（1. Settings、2. Preprocess、3. Quantity、4. Quality、5. Next、6. Pause、7. Appendix），正文默认中文；结论 callout 用灰色背景；1. Settings只写方法改动 + 压缩实验metadata（对齐 Var. Geometry Prior 风格），不堆负责人/机器/长假设/评测流程；平台写入走research-doc-workflow→notion-doc-workflow。每次重要实验都要在运行前创建 Notion 条目/页面，预先写下验证目标、成功标准、设置和预测；实验结束后再补充结果与判断。不得只在看到结果后回填实验目的或修改成功标准。
每条记录在标题之后的第一个块必须是
结论callout，并严格回答：> [!结论] > **第一问题：这个最小实验要验证什么？成功的标准是什么？** > - 验证目标：<一句可证伪的陈述> > - 成功标准：<预先确定的指标、阈值或明确的可观察条件>在第一问题 callout 之前不得先写命令、模型结构、超参数或结果。该 callout 必须在运行前冻结；看到结果后不得回改验证目标或成功标准，目标发生变化时应创建新的实验条目。若两个答案无法写清楚，将实验保持为“待设计”，不要启动训练或批量运行。
后续依次记录：状态、最高风险假设、最小实验、对照与基线、反驳/无法判定条件、资源上限、运行前预测、完整或可复制命令、Docker 镜像/Compose 文件/容器入口、关键超参与环境说明、主要结果（指标/现象）、失败样本/原始输出观察、更新后的判断、下一步最小动作、产物路径（检查点、日志、图表、视频等）。失败或已暂停时还必须有暂停记录。
Q&A 归档
- 对用户问题在基于代码与数据给出可靠解答后，将问题摘要 + 结论要点 + 必要时引用路径/命令写入归档。
- 默认归档文件：若不存在则创建
docs/Q&A.md（若项目已另有约定文件，则写入约定处并在此 skill 中保持一致）。
执行清单（代理自检）
开始复杂任务前可快速对照：
- 实验记录是否在运行前创建，并在标题后的第一个
结论callout 回答“验证什么、成功标准是什么”？ - 结论是否有代码/运行/实验依据？
- 是否有测试或可重复验证步骤？
- 是否按步骤执行，未擅自跳步？
- 改动是否小步、可回滚？
- 新想法是否先写出最小可行实验卡，而不是直接搭建完整系统？
- 是否锁定最高风险假设，并设置可测量判据、资源上限与停止条件？
- 是否具备 baseline / control / sanity check，能够区分原理、实现和测量失败？
- 实验/分析是否写下
假设 / 设置 / 预测 / 结果 / 更新后的判断 / 下一步最小动作？ - 长任务是否先进入
tmux会话，而不是裸跑在 SSH shell？ - 实验环境是否优先走 Docker/Compose，而不是散装到宿主机？
- 是否验证了容器内 GPU、核心 import、smoke test 或单 batch 运行？
- 大文件下载是否在独立 tmux 会话中运行并支持断点续传与自动重试？
- 是否使用
.part临时文件，并在校验通过后才改名为最终文件？ - 是否记录了固定版本、来源、大小、SHA256、目标路径和下载日志？
- 下载后的模型或数据集是否通过了最小读取/推理/batch 验证？
- 是否检查了原始输出和失败样本，而不只看平均指标？
- 是否有单命令运行、画图、config 或小数据验证来缩短发现错误的时间？
- 完成前是否核对维度与形状与核心逻辑？
- 是否更新了
RoadMap.md/ Notion 实验记录 / Q&A 归档（如适用）？
附加资源
- 以
.tools/skills/research-dev-standards/SKILL.md为 Lab Codex 的权威副本；~/.codex/skills/research-dev-standards仅作为兼容 symlink。 - 若研究仓库内存在重复的根目录
skills.md，将其改为指向本 skill 的简短说明，避免双源漂移。