RoJLD/repo-template

# 仓库模板 — Robin 的独断项目骨架 一套从真实的 Robin Denis 项目中提取的、经过实战检验的项目结构 （`Tools/hmm_studio`，`Experiment.Crypto.2026S1.RobinDenis`，`gitnexus`， `plane`）。这不是“Gemini 最佳实践清单”——这是在 2024 年到 2026 年间的多个独立/协作项目中真正奏效的经验。 ## 理念 **组合，而不是照搬。** 一个原型不应该背负 CODEOWNERS + SECURITY.md 的繁文缛节；而一个发布的开源（OSS）库则需要它们。一个 web 服务需要 Docker + 启动脚本；而一个纯库则不需要。该模板提供了两个正交的调节维度： - **Tier (1 / 2 / 3)** — 线性的规范度成熟度（包含多少流程/治理/文档记录）。 - **Addons** — 你可以自由搭配的正交能力包 （`ml`、`web`、`academic`、`devcontainer`、`supply-chain`、`infra`）。 一个真实的项目会选择一个 tier，**以及**零个或多个 addons。为了使操作 更加便捷，最常见的组合已被预配置为命名的 **recipes**。 ``` project = tier (1|2|3) + addons[*] ``` ## Tiers — 规范度维度 | Tier | 适用场景 | 增加的内容 | |---|---|---| | **1 — Prototype** | 一次性的实验，生命周期 < 1 周 | README、.gitignore、src/、tests/、LICENSE — 无 CHANGELOG、ADR、spec、validation、notes | | **2 — Tool**（默认） | 可能会扩展的个人项目，私有仓库 | + CHANGELOG、ADR、spec、roadmap、`validation/`、`notes/`、CONTRIBUTING | | **3 — OSS** | 公开面向用户，多名贡献者 | + CODE_OF_CONDUCT、SECURITY、CODEOWNERS、CITATION.cff | Tiers 是**单调递增的**：tier 3 ⊃ tier 2 ⊃ tier 1。 ## Addons — 能力维度 | Addon | 添加场景 | 增加的内容 | |---|---|---| | **`ml`** | Notebook、gallery、可复现的实验 | `notebooks/`、`examples/`、`binder/`（mybinder.org 配置）、`pyproject.toml [dev]` 中的 Jupyter 依赖 | | **`web`** | 包含 UI / API / DB 的服务 | `Dockerfile`、`docker-compose.yml`、`start.ps1` / `start.bat`、`stop.ps1` / `stop.bat`、`.dockerignore` | | **`academic`** | 文档网站 + 论文引用 | `mkdocs.yml`（material 主题）、`docs/papers/`、`CITATION.cff`、用于部署到 gh-pages 的 GH Action | | **`devcontainer`** | 零摩擦的协作者上手（Codespaces / VS Code Remote） | `.devcontainer/devcontainer.json` + Dockerfile + postCreate 脚本 | | **`supply-chain`** | OSS 规范管理：SBOM + 依赖更新 + scorecard | SBOM 工作流（CycloneDX）、Dependabot 配置、OpenSSF Scorecard 工作流 | | **`infra`** | 项目包含 Terraform / k8s / CloudFormation | Checkov IaC 扫描工作流、`infra/` 目录布局、`.gitignore.infra` | | **`code-intel`** | 与 Claude / Cursor 结对编程的项目，需要 code graph | GitNexus MCP 配置：ADR、`AGENTS.md` + `CLAUDE.md` 块、`make reindex` 目标、被忽略的 `.gitnexus/`、domain + policy 模板 | Addons 是**相互独立的** — 添加 `web` 不会强制要求 `devcontainer`， 添加 `ml` 不会强制要求 `academic`。它们会以非破坏性的方式合并到 tier 骨架中。 ## Recipes — 预先配置的组合 8 种最常见的项目配置已在 `recipes/*.json` 中预先命名，因此 你不必记住组合方式： | Recipe | Tier | Addons | 示例 | |---|---|---|---| | `prototype` | 1 | — | 一次性的实验 | | `private-tool` | 2 | — | 默认的个人工具 | | `ai-pair-programming` | 2 | `code-intel`、`devcontainer` | 为 Claude 结对编程优化的个人项目 | | `ml-research` | 2 | `ml`、`academic`、`code-intel` | hmm_studio 核心，加密实验 | | `web-service` | 2 | `web`、`devcontainer` | gitnexus，hmm_studio web 层 | | `oss-library` | 3 | `supply-chain` | 类似于 plane 的公开库 | | `academic-library` | 3 | `academic`、`supply-chain` | 可引用的 Python 包 | | `full-stack-research` | 3 | `ml`、`academic`、`web`、`devcontainer`、`supply-chain`、`code-intel` | hmm_studio（代表作） | | `cloud-deployment` | 2 | `web`、`devcontainer`、`infra`、`supply-chain` | 使用 Terraform 部署的 SaaS | 完整表格请参见 [recipes/README.md](recipes/README.md)。 ## 决策树 ``` Is this a one-shot script / experiment ? ├── YES → recipe: prototype └── NO ↓ Will external people see this code ? ├── NO ↓ │ ├── notebooks / models / experiments → ml-research │ ├── web service / UI / API → web-service │ ├── cloud-hosted with IaC → cloud-deployment │ └── everything else → private-tool │ └── YES ↓ ├── library on PyPI → oss-library ├── citable academic library → academic-library └── full research project (notebooks + UI) → full-stack-research ``` 如果有疑问：从 `private-tool` 开始，然后根据出现的需求添加 addons。 ## 如何使用 ``` # 发现可用内容 .\bootstrap.ps1 -List # 使用 recipe 进行 One-shot（简单路径） .\bootstrap.ps1 ` -Name "my-engine" -Title "My Engine" ` -Description "HMM toolkit." ` -Recipe "ml-research" # 或者手动 compose .\bootstrap.ps1 ` -Name "my-lib" -Title "My Lib" ` -Description "Public lib." ` -Tier 3 -Addons "supply-chain,academic" # 根据现有项目的声明对其进行 Audit .\validate.ps1 -Path "..\my-engine" # （自动加载 .repo-template-answers.json —— 无需重新声明 recipe） # 稍后为现有项目添加 capability .\add-addon.ps1 -Path "..\my-tool" -Addons "code-intel" ``` 手动操作步骤和占位符速查表请参见 [BOOTSTRAP.md](BOOTSTRAP.md)。 ## 三个脚本，一个工作流 | 脚本 | 作用 | 灵感来源于 | |---|---|---| | `bootstrap.ps1` | 从 recipe 或 tier+addons 创建新项目 | cookiecutter / copier | | `validate.ps1` | 审计现有项目；带编号的检查（RT001 / ML002 / ...） | scientific-python 的 sp-repo-review | | `add-addon.ps1` | 向已初始化的项目添加能力包 | Nx 生成器 | Bootstrap 会向每个项目写入 `.repo-template-answers.json`（copier 惯例）。`validate.ps1` 读取该文件以确定要检查的内容；`add-addon.ps1` 则会读取并更新它。 ## 开箱即用的内容 ``` repo-template/ ├── README.md # This file — philosophy + tiers + addons + recipes ├── BOOTSTRAP.md # Concrete "create new project" guide ├── PATTERNS.md # Field guide — when to apply each pattern ├── bootstrap.ps1 # Create a new project ├── validate.ps1 # Audit an existing project (numbered checks) ├── add-addon.ps1 # Add a capability pack to an existing project ├── template/ # Tier-1+2 base skeleton (incl. AGENTS.md / CLAUDE.md / GEMINI.md / CODEX.md) ├── tier-3-additions/ # Layered on top when -Tier 3 ├── addons/ │ ├── ml/ # Notebooks + Binder gallery │ ├── web/ # Docker compose + start/stop scripts │ ├── academic/ # mkdocs + papers + GH Pages deploy │ ├── devcontainer/ # VS Code / Codespaces dev environment │ ├── supply-chain/ # SBOM + Dependabot + OpenSSF Scorecard │ ├── infra/ # Checkov IaC scanning + infra/ layout │ └── code-intel/ # GitNexus MCP wiring (ADR + AGENTS/CLAUDE blocks + reindex) ├── recipes/ # Pre-baked tier+addon JSON profiles └── .github/workflows/ # CI : matrix bootstrap test for every recipe ``` ## 沿革 — 塑造该模板的来源 | 源项目 | 贡献的模式 | |---|---| | `Tools/hmm_studio` | 带有 revisit-if 的 ADR、标有日期的 spec（`YYYY-MM-DD-phase-X-name`）、作为活战略文档的 roadmap、独立于 `tests/` 的 `validation/`、Keep-a-Changelog 风格的 CHANGELOG、CITATION.cff、ml + academic addons | | `Experiment.Crypto.2026S1.RobinDenis` | 被 gitignore 的 `notes/` 实验记录本（cahier de laboratoire）、`experiments/`、`configs/`、Makefile 单行命令、ml addon | | `gitnexus` | INVENTORY.md（供 AI agent 阅读的代码库概述）、位于根目录的 ROADMAP.md、web addon（Docker compose + 启动脚本） | | `plane` | Tier-3 OSS 补充内容：CODEOWNERS、CODE_OF_CONDUCT、SECURITY、CONTRIBUTING | | **以上四个项目** | `AGENTS.md` + `CLAUDE.md` AI agent 上下文 | ## 为什么这比扁平的清单更好 最初的 Gemini“最佳实践”清单把所有东西都倒进了一堆里： SBOM、IaC 扫描、DevContainers、CODE_OF_CONDUCT、ADR、 spec、CITATION、validation、notes... 如果一开始就全做完， 在写下第一行真正的代码之前，就会面临 20 个文件的繁文缛节 — 而且其中大部分并不适用于*你的*项目。 可组合的模型是这样的：tier 处理流程成熟度（1/2/3）， addon 处理特定领域（web / ml / academic / IaC）。选择适合你情况的部分。

标签：AI合规, Libemu, SOC Prime, 开发工具, 开发规范, 版权保护, 脚手架, 请求拦截, 项目模板, 项目结构