research-dev-standards

# 科研开发与实验设计规范（Lab Codex） 在协助科研与开发时，默认遵循以下规范；与用户明确指令冲突时，以用户指令为准。 ## 一、基础原则 ### 基于证据 - 分析、结论、方案须建立在**实际代码、运行输出、实验指标或数据**之上。 - 在缺少可核验证据时，不臆测、不过度自信；应说明假设、建议如何验证（读代码、跑测试、小规模实验）。 ### 测试驱动开发 - **先**有可执行的验证手段（单元测试、脚本断言、或约定的可视化/数值检查），**再**扩展实现。 - 功能到位后，用可视化与数据核对效果，再合并或宣称完成。 ### 顺序执行 - 按约定步骤推进，**不擅自跳过**某一步。 - 若某步受阻：先说明阻塞原因与可选方案，与用户沟通后再继续；**仅**在用户明确授权时可临时跳过。 ### 小步迭代 - 避免单次提交中堆叠大量未验证的模块、损失项或配置分叉。 - 优先小范围改动 → 验证 → 再下一处。 ### 研究现象：先分析原因与相关工作 - 用户从某个现象、失败或异常提出研究性改进时，先执行 [`ai-research-workflow/references/observation-to-problem.md`](../ai-research-workflow/references/observation-to-problem.md)：核验观察，核查相关工作中已知现象、原因解释和已有解法，分析竞争性原因并按需诊断，再选具体改进。相关工作是方案设计前的必要步骤，不能以想到了模块或准备做小实验跳过。 - 原因未明时允许先做有预测和对照的诊断实验；不得直接实施新结构/损失/训练方法来代替分析。已明确的实现 bug 可直接修复验证，但不能未经相关工作与机制核查便包装为方法创新。明确区分文献/数据支持、推断和待验证，记录实际来源与证据缺口。 - 原因假设、相关工作与诊断证据反复校正，不视为一次性前置打卡。算法改动建议必须对应假说、证据、预测和反驳条件；定位到失效环节不等于已解释机制，判断原则见上述引用。 ### 探索性实验：先过最小可行性门 - 当用户提出新研究想法、方法改动或实验设想时，在上述现象/相关工作核查后设计**最小可行实验**（Minimum Viable Experiment, MVE），再决定是否实现完整系统或启动大规模训练。若原因仍不清楚，先设计区分解释的诊断实验，而非默认验证某个改进模块；已完成的相关分析可直接复用。 - 在开始任何实验之前，首先回答：**这个最小实验要验证什么？成功的标准是什么？** 若不能给出清晰、可测量的答案，停止执行并继续收敛实验问题。 - 把“最小”理解为：以最低资源成本获得足以改变下一步决策的可信证据；不要把它误解为代码最少、样例最少或做一个无法代表真实问题的玩具演示。 - 优先验证整个方向中**风险最高、最可能使项目失效的核心假设**。若实验同时混入多个新机制，先拆成能单独归因的实验。 - 未明确核心假设、判定阈值、资源上限和结果分支时，不进入高成本执行阶段。 设计实验前，先给出一张**最小可行实验卡**： 1. **第一问题：这个最小实验要验证什么？成功的标准是什么？** 分别写出一句可证伪的验证目标和一个预先确定、可测量的成功阈值；不得用“效果不错”“看起来可行”等主观表述代替。 2. **最高风险假设**：指出哪个前提一旦不成立，后续系统即失去继续投入的价值。 3. **最小实验**：只保留检验该假设所必需的数据、模块、训练步骤和输出；说明删掉了哪些非必要部分。 4. **对照与基线**：至少提供一个最弱但有效的 baseline、control 或 sanity check，使结果能够归因，而不只是证明代码能运行。 5. **其余判据**：在第一问题已经定义成功标准的基础上，再预先写明反驳和无法判定的可测量条件；判据尽量接近二元，但必须保留“证据不足”分支。 6. **资源上限**：预先限定时间、GPU 小时、样本量、分辨率、训练步数和允许尝试的配置数。默认先问：“如果只有一天，怎样获得最有判别力的结果？” 7. **最低复现证据**：保留代码版本、可复制命令、配置、数据切片、随机种子、环境、日志、原始输出和产物路径；可以降低系统完整度，不得降低证据完整度。 8. **决策分支**：实验前写清结果为支持、反驳或无法判定时分别采取的下一步，以及停止继续投入的条件。 执行最小化时遵循以下顺序： - 先用极少样本完成数据流、维度、损失、指标和可视化的 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 实际存储位置，再执行可能拉取镜像的命令； - `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。 ### 服务器大文件与 Docker 存储：避免系统盘 - 在服务器下载大文件、拉取/构建镜像或配置实验环境前，先确认实际存储位置。模型、数据集、下载残片、解压目录、包缓存、环境目录、镜像层、构建缓存、容器持久数据和大体积日志/产物默认放在已挂载的数据盘，不放在系统盘。 - 用 `lsblk`、`findmnt -T <目标路径或已存在的父目录>` 和 `df -hT` 核对目标与 `/` 的挂载来源、文件系统、剩余空间及配额；不能仅凭 `/data`、`/mnt` 或 `/home` 目录名判定为数据盘。目标挂载缺失时停止，不能在同名空目录继续写入系统盘；同一系统磁盘上的另一分区也不能直接视作独立数据盘。 - 未找到可写且空间足够的数据盘时，先报告路径与空间情况并向用户确认；不要静默回退到 `$HOME`、`/tmp`、`/var/tmp` 或 `/var/lib/docker`。系统程序和小型配置文件可保留默认位置，本规则重点约束大体积数据。 - 下载临时文件与最终文件放在同一数据盘文件系统，保持原子改名条件；解压、编译和构建暂存也使用数据盘。预留压缩包、解压结果、镜像层与构建峰值的总空间。 - 按实际工具设置缓存路径，例如 `HF_HOME`、`TORCH_HOME`、`PIP_CACHE_DIR`、`XDG_CACHE_HOME`、`TMPDIR` 及 conda 的环境/包目录；同时检查工具专用配置是否覆盖这些变量。容器内也要设置对应路径，并 bind mount 到宿主机数据盘，不能只更改宿主机变量。 - 在任何 `docker pull`、`docker build`、Compose 启动或可能自动拉镜像的 `docker run` 前，读取 `docker info` 的实际 Docker Root Dir 并核验其挂载位置。还需核对当前使用的 containerd 镜像存储、BuildKit/buildx builder 缓存、named volumes 和容器日志的位置；这些存储可能独立于 Docker `data-root`。切换工作目录或只把 Dockerfile 放到数据盘并不能迁移镜像存储。 - 新配置优先将 Docker/相关镜像存储和构建缓存放在数据盘；数据集、权重、checkpoint 和 outputs 显式 bind mount。现有 Docker 存储若在系统盘，先说明现状与迁移方案；未经授权，不停止共享 daemon、重启服务、迁移或删除现有镜像/volume，不用全局 prune 腾空间。配置完成后重新核验实际路径，再开始大文件操作。 ### 大文件下载与断线恢复协议 下载模型权重、数据集、预训练资产或其他大文件时，默认把下载视为可恢复、可验证的实验基础设施，而不是一次性 shell 命令： - 服务器下载必须先进入独立的 `tmux` 会话；SSH/VPN 断开后只重新连接并恢复会话，不从头启动下载。 - 下载工具必须支持断点续传、自动重试、连接/读取超时和退避等待；VPN 不稳定时默认降低并发，避免用高并发掩盖网络问题。 - 下载到临时文件（例如 `.part`），完整下载并通过校验后再原子改名为最终文件；训练或实验程序不得读取未验证的临时文件。 - 下载前按上述规则核验非系统盘挂载点、剩余磁盘空间和解压空间；数据、模型、cache、checkpoint、日志和 outputs 不得只存在于 `/tmp`、容器临时层或 SSH 会话目录。 - 为每个下载记录 manifest：资源名称、来源 URL、仓库 revision/tag/commit、配置或 split、预期大小、SHA256、目标路径、下载时间和工具信息。不得用未固定的 `latest` 作为实验依赖。 - 下载完成后必须验证 SHA256；若上游未提供哈希，至少验证文件大小、压缩包完整性、目录结构和随机读取结果，并明确记录降级验证。 - 验证通过后再做最小可用性测试：模型至少完成配置/tokenizer/权重索引读取或一次最小推理；数据集至少完成样本计数、随机读取和一个最小 batch。 - 校验失败、空间不足或下载中断时，不得把文件标记为可用；保留错误日志和恢复状态，修复后从断点继续并重新校验。 - 下载来源应使用官方仓库或用户指定来源；切换镜像、版本、数据配置或文件格式时，必须记录原因并更新 manifest。 ### 实验可视化网页 - 重要项目的基线/关键实验需要视觉检查时，按 [`research-viewer`](../research-viewer/SKILL.md) 复用或建立项目可视化入口，接入真实输入、输出、必要中间证据、指标及可用 GT。研究项目可包含多个方法仓库；展示范围和可比性由实验协议决定。 - 实验源结果保持不变，导出、索引和缓存使用独立位置；大文件按上述规则核验数据盘，资产默认留服务器，网页服务依赖不污染训练环境。登记只处理本轮指定结果，不隐含推理/训练/GPU 作业权限。 - 关键实验交付记录网页/案例链接、run/索引版本、覆盖范围和实际检查的典型/失败案例；登记、可加载、有效评测与可比较状态分别说明。未检查的结果不能因网页已上线就视为科学结论已验证。 ### 科研配色 - 新建或调整科研图、定性渲染与实验网页配色时，读取 [`references/research-color-standard.md`](references/research-color-standard.md) 与其中的 JSON。四套参考家族为 CHOIS（默认）、Terra、Any4D、Gaussian Garments；SeeClear Depth 是独立数值编码，CHOIS 深色适配仍属同一家族。项目已有配置或用户本次选择优先，不批量改历史结果。 - 深度、法线、点图/点云、网格、分割、二维光流/三维场景流/轨迹及图表，按 [`references/research-representation-colors.md`](references/research-representation-colors.md) 选择编码。用户指定的 Any4D teaser 是三维点轨迹，不是二维 UV 流；公开轨迹函数已确认，teaser 完整生成链路与专用 UV 色轮未确认，不用 RAFT 代替。方法图浅色不约束运动图饱和度，颜色/饱和度携带数值时不得逐方法美化。 - 分类颜色、连续数值与界面状态分别编码；跨样本/方法保持角色色，直接比较共享数值范围。色表记录源码/矢量依据和透明度；不把材质参数、截图像素和本地改编混为论文原色。 - 实体颜色可从 CHOIS / OMOMO 候选库按项目选择，不限于 CHOIS 蓝绿紫三个标签色；多个相近蓝/紫是备选，不因条目多就全部用于同图。实体库不等于流程图家族，不覆盖原纹理或物理属性编码。 ### 三维重建结果渲染与对照 - 为人体与场景三维重建制作定性图、旋转视频或优化前后对照时，读取 [`references/3d-reconstruction-rendering.md`](references/3d-reconstruction-rendering.md)。其中记录共享的几何/相机真实性约束，以及 GRAFT/PhySIC 项目的 Three.js 快捷路径和 Blender 高质量路径。 - 渲染只展示已产出的几何与状态。保留输入顶点、面、颜色来源、实际尺度及评测口径；比较同一案例的阶段时固定人体身份、场景、相机定义和共同旋转中心。项目专属数值先核对当前配置，不能直接当作其他项目的默认参数。 ### 数据集原始库与项目派生副本 - 下载/接入数据集或编写预处理脚本前，读取 [`references/dataset-storage.md`](references/dataset-storage.md)。原始数据统一位于已核验数据盘的 `datasets/<dataset>/<version-or-snapshot>/`，不增设 `raw/` 层。保存上游原始文件（包括压缩包、分片、标注），校验后保留，不因解压、缓存清理、换项目或空间不足而删除、覆盖或原地修改；删除/替换源数据需用户另行明确授权。 - `projects/<project>/data/<dataset>/<derived-version>/` 存该项目处理好的训练/验证/测试数据；预处理的独立复制/解压暂存放项目工作区，不与原始库或已就绪版本混用。原始库只用于校验及派生数据的读取。禁止以软链接或硬链接代替项目副本。各方法/预处理版本使用独立目录并记录来源链路；不配置只读权限或强制只读挂载。 - 每个已下载的数据集版本目录必须同时有 `README.md` 和 `manifest.json`，说明来源、版本、许可证/访问条件、下载与校验状态、文件大小及 SHA256。项目 `dataset.md` 记录实际使用范围、目录/格式、预处理脚本与配置、样本数及 split；原始/派生目录布局及 JSON 示例见上述参考。 ### 完成前审查 - 在宣称功能完成前，做一次针对性审查，重点包括： - **关键张量/数组的维度变换**是否与数据管线一致； - **输入输出形状**与 API 契约； - **分支与边界**下的逻辑是否正确。 --- ## 二、文档维护（仓库根目录相对路径） 项目级职责与目录/页面映射以 [`ai-research-workflow/references/project-workflow.md`](../ai-research-workflow/references/project-workflow.md) 为准：把 Related Work、Reproduction、Dataset、Evaluation 和实验记录连接到已有 project 入口。该结构只补缺，不替换下述既有 RoadMap 和 Notion 报告规范。 ### 路线图：`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，并严格回答： ```markdown > [!结论] > **第一问题：这个最小实验要验证什么？成功的标准是什么？** > - 验证目标：<一句可证伪的陈述> > - 成功标准：<预先确定的指标、阈值或明确的可观察条件> ``` - 在第一问题 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 会话中运行并支持断点续传与自动重试？ - [ ] 下载/解压/缓存与 Docker 镜像、构建缓存、volume 的实际存储是否已核验位于数据盘，且挂载有效、空间充足？ - [ ] 是否使用 `.part` 临时文件，并在校验通过后才改名为最终文件？ - [ ] 是否记录了固定版本、来源、大小、SHA256、目标路径和下载日志？ - [ ] 下载后的模型或数据集是否通过了最小读取/推理/batch 验证？ - [ ] 数据集源文件是否保留完整，项目是否使用独立副本，并有 README、manifest 与预处理/split 的来源记录？ - [ ] 三维结果图/视频是否按渲染参考核验了几何不变、相机对齐、真实 GT 标注和完整输出？ - [ ] 是否检查了原始输出和失败样本，而不只看平均指标？ - [ ] 是否有单命令运行、画图、config 或小数据验证来缩短发现错误的时间？ - [ ] 完成前是否核对维度与形状与核心逻辑？ - [ ] 是否更新了 `RoadMap.md` / Notion 实验记录 / Q&A 归档（如适用）？ ## 附加资源 - 以 **`.tools/skills/research-dev-standards/SKILL.md`** 为 Lab Codex 的权威副本；`~/.codex/skills/research-dev-standards` 仅作为兼容 symlink。 - 若研究仓库内存在重复的根目录 `skills.md`，将其改为指向本 skill 的简短说明，避免双源漂移。