light-project-structure

项目文件夹规范整理

标准科研项目骨架

project-name/
├── data/            原始/中间/处理后数据（大文件走 DVC）
│   ├── raw/ interim/ processed/ external/
├── src/             源代码
├── models/          模型权重与定义
├── results/         实验结果（指标、输出文件）
├── figures/         论文/报告用图
├── docs/            项目文档
├── paper/           论文（LaTeX/Word 工程）
├── ppt/             演示文稿
├── patent/          专利材料
├── software-copyright/  软著材料
├── experiments/     实验脚本与配置（按实验编号）
├── logs/            运行日志（MLflow/W&B 本地）
├── configs/         配置（Hydra yaml）
├── references/      文献库（Zotero 导出/.bib）
├── assets/          图标/模板/素材
├── notebooks/       探索性分析
├── .light/          编排台账 passport.yaml + handoff/ 会话衔接卡（纳入版本控制）
├── README.md  CHANGELOG.md  .gitignore  pyproject.toml

数据分层沿用 Cookiecutter Data Science：raw/(原始不可变) interim/(中间) processed/(建模用最终) external/(第三方源)。notebooks 用"编号-缩写-描述"命名（如 1.0-jl-eda.ipynb）。

数据流即 DAG（核心方法）

把整个项目想成一张有向无环图：节点是数据/产物，边是确定性变换脚本。沿三条铁律组织目录：

1. raw 不可变（immutable）：data/raw/ 一旦落地永不就地修改、永不被脚本写回。任何清洗/转换都读 raw、写 interim/ 或 processed/。这样原始事实始终可回溯，DAG 有可信源头。
2. 每个产物都能从上游重算：processed/、models/、results/、figures/ 都是 DAG 的下游节点，删掉也能由"上游数据 + 代码 + params"重新生成——因此它们进 .gitignore/DVC，不进 Git 文本库。能重算的不入库，是 DAG 思路的直接推论。
3. notebooks 拆探索 vs 报告：notebooks/exploratory/（草稿、可乱、编号命名 1.0-jl-eda.ipynb）与 notebooks/reports/（干净、可重跑、产出对外图表）分流。探索性 notebook 不进 DAG 关键路径；定稿逻辑要下沉到 src/，被 notebook 和管线共同 import，避免"逻辑只活在某个 cell 里"。

用 dvc.yaml 把这张 DAG 显式声明出来（stage 的 deps→outs 就是图的边），dvc repro 据此只重跑受影响的下游节点；dvc dag 可打印依赖图。

命名规范

• 目录/文件用小写+连字符或下划线，不用空格中文。
• 实验/版本带日期或序号：exp_004_ablation, paper_v3, fig3_ablation_v2。
• 数据文件含版本/划分标记；结果文件名映射到实验编号，可追溯。

整理动作

1. 盘点已有项目（借 repo-intake-and-plan 思路）：先读 README→扫 setup 脚本与文档化命令→把工作流归类为 推理/训练/评估，再据此给散落文件归位。
2. 新项目骨架：首选 scripts/scaffold.py——一条命令建全树 + 拷模板 + 可选 --dvc/--uv|--poetry： python scripts/scaffold.py ./my-proj --name my-proj --dvc（生成 data 四分层 + notebooks 探索/报告分流 + src 包 + .light/（passport 台账 + handoff/ 衔接卡目录，纳入版本控制）+ 落地 7 模板 + pyproject.toml；目标非空需 --force）。pyproject 默认 uv 后端（与 a03 推荐一致），加 --poetry 切 Poetry 备选。或用 CCDS（pipx install cookiecutter-data-science 后 ccds）；或按上面骨架手工生成。无论哪种，都要落 README/CHANGELOG/PROJECT_PLAN/.gitignore/.editorconfig/pyproject.toml。
3. 重命名规范化→补 README/CHANGELOG→产出"文件归位说明"（借 handoff 结构：Key Decisions 表 + 失败尝试 + 警告）。

版本与依赖

• Git 管文本，DVC 管大文件：dvc init→dvc add data/x.csv(生成 .dvc 小文件并自动写 .gitignore)→git add *.dvc .gitignore→dvc remote add -d storage s3://...→dvc push。拉取：git pull && dvc pull。.dvc/dvc.yaml/dvc.lock/.dvc/config 入 Git，数据本体进 DVC。
• 多阶段管线用 dvc.yaml(stage 字段：cmd 必填、deps、params、outs、metrics、plots)，dvc repro 只重跑变更阶段（frozen:true 阶段跳过）；实验用 dvc exp run/show/diff。
• 依赖锁定默认 uv（与 a03 backend-coding 一致，快且 lock 跨平台）：uv init→uv add→uv sync(按 uv.lock 精确装)；dev/test 依赖 uv add --dev 进 [dependency-groups]；应用项目提交 uv.lock。备选 Poetry：poetry init→poetry add→poetry install，dev/test 放 [tool.poetry.group.dev.dependencies]，提交 poetry.lock。scaffold 默认出 uv 版 pyproject，--poetry 切备选。

质量门（配置要点）

四件套——Ruff（替代 flake8+black+isort）、pre-commit（rev 钉死 tag、接 ruff-pre-commit）、EditorConfig（root=true 统一缩进/换行）、.gitignore（GitHub Python 模板 + 科研条目）——的配置已落进 templates/ 对应模板，逐项 [tool.*] 键与命令见 references.md；质量门口径与 a03 backend-coding 一致（a03 为代码侧单一真相源）。任务运行器二选一：make 已有则 Makefile；要跨平台+可读用 Taskfile（checksum 跳过、task -l）。

与项目库对应

目录结构与 db09 project_card 的各 status 字段一一对应（paper_status↔paper/，code_status↔src/，data_status↔data/…），便于 a02 跟踪进度。

现成模板（本技能目录 templates/，可直接复制使用）

• scripts/scaffold.py — 一条命令生成全套骨架：建目录树 + 拷 7 模板到项目根（去 .template 后缀）+ 写 src/<module>/__init__.py + 始终落 pyproject.toml（默认 uv 后端，--poetry 切备选，均带 Ruff）；--dvc 加写 dvc.yaml，--force 覆盖非空。已实测两路径 selftest 通过。
• 7 份模板：PROJECT_STRUCTURE.md（目录规范+命名+db09 对应）、README.template.md、PROJECT_PLAN.template.md（可勾选任务+No-Placeholders）、CHANGELOG.template.md（Keep a Changelog+SemVer）、python-research.gitignore（基线取 GitHub 官方 Python.gitignore，HTTP 200@2026-06-06，补科研条目）、editorconfig.template、pre-commit-config.template.yaml（rev 钉死 tag，pre-commit autoupdate --freeze 维护，仅 git 仓库内 pre-commit install 后生效）。各模板用途与配置项细节见 references.md。

新建项目时优先 python scripts/scaffold.py <dir> [--poetry --dvc] 一步到位；或手工把上述文件复制到项目根（gitignore/editorconfig 去掉模板后缀），填充 README/CHANGELOG/PROJECT_PLAN 中的 {{占位符}} 即可。

产出

规整后的目录树 + 上面 templates/ 的 README/CHANGELOG/.gitignore/.editorconfig 落地文件 + 一份"文件归位说明"。

衔接

为 m05/a03/a04 提供落地结构；为 m15(软著专利)、m07(论文)、m16(PPT) 预留对应目录；状态同步 a02/db09。 整理任务量大时按"可独立完成+带验收标准+标依赖顺序"拆解（借 to-issues 的垂直切片思路：每个任务是一条端到端可独立认领的路径，而非横向按层切）；复杂整理先出"精确路径+具体动作+验证步骤"的计划再执行，写到无上下文者也能照做的程度（借 writing-plans，任务粒度 2–5 分钟）。复现/审计场景固定 repro_outputs/ 归档每次跑的结果，落 verified/partial/blocked 三态标记 + 输出 + PATCHES.md（改了哪些文件）+ 假设与阻塞清单（借 minimal-run-and-audit）。

工具与方法的可核查细节（真实命令/配置/端点/链接）见同目录 references.md；现成可复制模板见同目录 templates/。