| name | light-project-structure |
| description | 规范整洁的项目文件夹整理。当任务涉及新建项目、整理已有项目结构、规整文件命名与版本时使用。规划 data、src、models、results、figures、docs、paper、ppt、patent、software-copyright、experiments、logs、configs、references、assets、notebooks 等目录，保证结构清晰、命名规范、版本可追踪，便于写论文、答辩、申请软著专利与复现实验。 |
| user-invocable | false |
项目文件夹规范整理
标准科研项目骨架
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（核心方法）
把整个项目想成一张有向无环图：节点是数据/产物，边是确定性变换脚本。沿三条铁律组织目录：
- raw 不可变（immutable）：
data/raw/ 一旦落地永不就地修改、永不被脚本写回。任何清洗/转换都读 raw、写 interim/ 或 processed/。这样原始事实始终可回溯，DAG 有可信源头。
- 每个产物都能从上游重算：
processed/、models/、results/、figures/ 都是 DAG 的下游节点，删掉也能由"上游数据 + 代码 + params"重新生成——因此它们进 .gitignore/DVC，不进 Git 文本库。能重算的不入库，是 DAG 思路的直接推论。
- 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。
- 数据文件含版本/划分标记；结果文件名映射到实验编号，可追溯。
整理动作
- 盘点已有项目（借 repo-intake-and-plan 思路）：先读 README→扫 setup 脚本与文档化命令→把工作流归类为 推理/训练/评估，再据此给散落文件归位。
- 新项目骨架：首选
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。
- 重命名规范化→补 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/。
