Ai Project Scaffold

为 AI 模型项目创建标准化目录结构：覆盖数据→分词→模型→实验全链路，支持多方案并行、来源追踪、质量记录。内置健康检查、追踪链、实验对比、checkpoint管理。严格文档规范防止 AI 生成冗余文档。

AI 项目目录结构管理 v2.0

适用于涉及数据清洗、分词/Tokenization、模型训练、后训练、强化学习等完整 AI 管线的项目。

🔴 文档铁律（AI 助手必须遵守）

⚠️ 这是本 skill 最重要的部分。违反任何一条都应被视为严重错误。

原则

1. 表 > 文 — 能用表格记录的，不写段落。表格可扫描、可对比、不冗余。
2. 记录决策，不写教程 — 文档回答"做了什么选择、为什么"，不写"怎么用、是什么"。
3. 一处一真理 — 同一信息绝不出现在两个文件里。信息有且仅有一个权威位置。
4. 日志即文档 — experiment_log.md 是唯一持续增长的文档。其他 README 只在结构变化时更新。
5. 写完删一半 — 写完任何文档后，删掉至少一半字数。留下的才是精华。

禁止清单

❌ 绝对禁止	✅ 应该做
写超过 200 字的段落说明	用表格或列表，每行 ≤ 一行
在 README 里粘贴代码	代码放在 scripts/，README 只写脚本名+用途
创建 GUIDE.md、TUTORIAL.md、NOTES.md 等随意命名的文档	只使用约定文件名
重复其他文件已有的信息	用链接引用（如 详见 01_data/README.md）
自动生成"项目概述""背景介绍"等水字数的章节	空着也比写废话强
写 detailed_explanation_v2_final.md	一个主题一个文件，版本在文件名里（如 token_eval_v2.md）
用 final、new、latest 等模糊后缀	用数字版本号 v1, v2, v3

文档命名规范

text

✅ 好命名:
  architecture_decision_001_transformer.md  # ADR 风格
  qc_report_wikipedia_zh_2024-03-15.md      # 数据集_日期
  eval_benchmark_mmlu_v2.md                 # 主题_版本

❌ 坏命名:
  notes.md                                  # 太模糊
  final_report.md                           # 哪个 final？
  test.md                                   # 测什么？
  new_doc_v3_final_revised.md               # 💀

允许的文档类型及字数上限

文档	最大字数	更新频率	说明
各层 README.md	300 字	结构变化时	表格为主，不写段落
experiment_log.md	不限（按条目追加）	每次实验	唯一允许持续增长的文件
metadata.yaml	不限	数据源变更时	结构化数据，不是散文
eval.md（分词方案下）	500 字	评估完成后	表格 + 关键数字
architecture_decision_*.md	500 字	做决策时	背景+选项+决策+后果
qc_report_*.md	300 字	每次 QC	数据集+问题+处理+结果
meeting_*.md	200 字	每次会议	日期+议题+结论，不要流水账

超过字数上限的文档应拆分为多个文件，或用表格代替段落。

---

设计理念

1. 分层管理 — 数据层 / 分词层 / 模型层 各自独立，互不污染
2. 多方案并行 — 每层支持多种技术方案/尝试并存，各自有独立空间
3. 来源可追溯 — 数据从哪来、经过什么处理、用到了哪个模型，全程可追踪
4. 质量可见 — 数据质量、分词效果、模型评估都有独立的记录空间
5. 文档极简 — 遵循上方🔴铁律，拒绝 AI 生成冗余文档

---

目录结构

text

<project_name>/
├── README.md                          # 项目总览（≤300字）
├── _project_config.yaml               # 项目元信息
├── .gitignore                         # 自动生成，忽略 checkpoints/logs/数据/.env
├── scripts/                           # 管理脚本（自动复制）
│   ├── check_project.py               # 健康检查
│   ├── trace.py                       # 追踪链生成
│   ├── compare_runs.py                # 实验对比
│   └── checkpoint_mgmt.py             # Checkpoint 管理
│
├── 01_data/                           # 📊 数据层
│   ├── README.md                      # 数据来源登记表（表格，≤300字）
│   ├── 01_raw/                        # 原始数据（按来源分目录）
│   │   └── source_<name>/
│   │       ├── metadata.yaml          # 结构化元信息
│   │       └── data/
│   ├── 02_qc/                         # 质量控制
│   │   ├── scripts/                   # QC 脚本
│   │   ├── reports/                   # QC 报告（命名: qc_report_<dataset>_YYYY-MM-DD.md）
│   │   └── cleaned/                   # 清洗后数据
│   ├── 03_processed/                  # 处理后
│   │   ├── text/
│   │   ├── image/
│   │   ├── audio/
│   │   └── multimodal/                # 多模态细化
│   │       ├── image_text/
│   │       ├── video_text/
│   │       ├── audio_text/
│   │       └── interleaved/
│   └── 04_quality_log.md              # 数据质量追踪日志（表格追加）
│
├── 02_tokenization/                   # 🔤 分词层
│   ├── README.md                      # 分词策略总览（表格，≤300字）
│   ├── 01_existing/                   # 现成 tokenizer
│   │   └── <tokenizer_name>/
│   │       ├── config.yaml
│   │       └── notes.md               # 选用理由（≤150字）
│   ├── 02_custom/                     # 自制
│   │   └── <approach_name>/
│   │       ├── README.md              # 方案说明（≤200字）
│   │       ├── scripts/
│   │       ├── configs/
│   │       ├── vocab_output/
│   │       └── eval.md                # 评估结果（表格，≤500字）
│   ├── 03_training/                   # token 相关训练
│   ├── 04_evaluation/                 # 内在 + 下游评估
│   │   ├── intrinsic/
│   │   └── extrinsic/
│   └── 05_generated/                  # 分词产生的新数据记录
│
├── 03_models/                         # 🧠 模型层
│   ├── README.md                      # 架构选型决策（表格，≤300字）
│   ├── 01_pretraining/
│   │   └── <arch_name>/<run_name>/
│   │       ├── configs/               # 训练配置
│   │       ├── scripts/               # 训练脚本
│   │       ├── checkpoints/           # gitignored
│   │       ├── logs/                  # gitignored
│   │       └── eval/
│   ├── 02_post_training/
│   │   ├── sft/                       # 监督微调
│   │   ├── dpo/                       # DPO
│   │   ├── orpo/                      # ORPO
│   │   ├── kto/                       # KTO
│   │   ├── simpo/                     # SimPO
│   │   └── rlhf/                      # RLHF 流程
│   ├── 03_rl/
│   │   ├── ppo/
│   │   ├── grpo/
│   │   └── reward_models/
│   ├── 04_evaluation/
│   │   ├── benchmarks/
│   │   └── reports/
│   └── 05_deployment/
│
├── 04_experiments/                    # 🔬 实验管理
│   ├── experiment_log.md              # 时间线日志（唯一可无限增长的文件）
│   └── runs/
│
├── 05_docs/                           # 📚 文档（严格遵守铁律）
│   ├── design/                        # 架构决策记录（ADR 风格）
│   ├── meetings/                      # 会议记录（命名: meeting_YYYY-MM-DD_主题.md）
│   └── references/                    # 外部参考文献
│
└── 06_shared/                         # 🔧 共享资源
    ├── scripts/                       # 通用脚本
    └── configs/
        ├── training/                  # DeepSpeed/LoRA/QLoRA/WandB 模板
        ├── data/                      # 数据处理配置模板
        └── deployment/                # 部署配置模板

---

🛠 管理工具

新建项目

bash

python3 init_ai_project.py --name "MyLLM" [--output /path/to/parent]

自动生成：完整目录 + 各层 README 模板 + .gitignore + 5 个配置模板 + 管理脚本副本

添加组件

bash

# 数据来源（自动生成 metadata.yaml）
--add-source --source <名称>

# 分词方案（自动创建 scripts/configs/vocab/eval）
--add-tokenizer --approach <方案名>

# 预训练运行
--add-training --arch <架构> --run <运行名>

# 后训练运行
--add-posttrain --method <sft/dpo/orpo/kto/simpo/rlhf> --run <运行名>

# RL 运行
--add-rl --method <ppo/grpo/...> --run <运行名>

升级已有项目

bash

python3 init_ai_project.py --name "MyLLM" --upgrade
# 补充缺失目录 + .gitignore + 配置模板 + 管理脚本

健康检查

bash

python3 check_project.py --name "MyLLM"
# 扫描: 目录完整度 / metadata 字段 / eval 是否填写 / 日志是否更新
# 输出: 健康评分 0-100 + 具体问题清单

追踪链

bash

python3 trace.py --name "MyLLM"                    # 全局追踪
python3 trace.py --name "MyLLM" --layer models      # 只看模型层
python3 trace.py --name "MyLLM" --full              # 含文件详情

实验对比

bash

python3 compare_runs.py --name "MyLLM"                          # 全部对比
python3 compare_runs.py --name "MyLLM" --arch llama3             # 指定架构
python3 compare_runs.py --name "MyLLM" --stage post_training     # 只看后训练

Checkpoint 管理

bash

python3 checkpoint_mgmt.py --name "MyLLM" list                      # 列出所有
python3 checkpoint_mgmt.py --name "MyLLM" clean --keep 3 --dry-run  # 预览清理
python3 checkpoint_mgmt.py --name "MyLLM" clean --keep 3            # 每运行保留3个最新
python3 checkpoint_mgmt.py --name "MyLLM" archive --to /backup/     # 归档
python3 checkpoint_mgmt.py --name "MyLLM" stats                     # 磁盘统计

---

命名规范

层级	目录命名	示例
数据来源	source_<描述>	source_wikipedia_zh, source_internal_docs
QC 报告	qc_report_<dataset>_YYYY-MM-DD.md	qc_report_wikipedia_2024-03-15.md
分词方案	<方法>_v<版本>	bpe_v1, unigram_v2, sentencepiece_v1
模型架构	<架构名>	llama3, qwen2, custom_moe
训练运行	<描述>_v<版本>	baseline_v1, lr_3e4_v2, wd_0.1_v1
后训练方法	<缩写>	sft, dpo, ppo, grpo
会议记录	meeting_YYYY-MM-DD_<主题>.md	meeting_2024-03-15_arch_review.md
设计决策	architecture_decision_<序号>_<主题>.md	architecture_decision_001_transformer.md

---

追踪链

每个阶段记录输入/输出依赖，形成完整链路：

text

source_wikipedia_zh (01_data/01_raw/)
  → qc_report_wikipedia_2024-03-15.md (01_data/02_qc/reports/)
    → bpe_v1 (02_tokenization/02_custom/)
      → eval.md 评估通过
        → llama3/baseline_v1 (03_models/01_pretraining/)
          → sft/chat_v1 (03_models/02_post_training/)
            → ppo/reward_v2 (03_models/03_rl/)

💡 运行 python3 scripts/trace.py --name <项目> 自动生成追踪链。

---

AI 助手行为准则

使用本 skill 时，AI 助手必须:

1. 初始化项目时 — 只生成模板骨架，不填充假数据。空表格比假数据好。
2. 写 README 时 — 表格 > 列表 > 段落。默认用表格。
3. 记录实验时 — 追加到 experiment_log.md，用模板格式，不要新建文件。
4. 写评估报告时 — 数字和表格是主角，文字只是表头。
5. 不要做的事:
   • ❌ 不要创建 05_docs/ 下的随意命名的 .md 文件
   • ❌ 不要在多个 README 里重复同一段话
   • ❌ 不要写"本项目旨在..."这种水字数开头
   • ❌ 不要生成超过 300 字的 README
   • ❌ 不要用 final、new、latest、updated 命名文件