init-python-project

初始化 Python 项目

帮助用户创建可用于生产环境的 Python 项目，或升级现有项目；不要在此技能中内联大型文件正文。以随附的参考资料和模板为准。将 Python 工具链视为明确的门槛：默认运行不修改文件的检查，仅在用户要求或确有必要时运行格式化／修复命令，并在仓库指南中记录实际运行的命令。将 pre-commit 用作可选的本地门禁运行器，用于代码、Shell、机密信息、Notebook、配置、GitHub Actions 和文档链接。

技能目录结构

<installed-skill-dir>/
├── SKILL.md
├── references/
│   ├── architecture.md
│   ├── new-project.md
│   ├── fork-enhancement.md
│   └── best-practices.md
├── scripts/
│   └── scaffold_new_project.py
├── template_manifest.json
└── templates/
    ├── common/
    │   ├── .gitignore
    │   ├── .env.example
    │   ├── README.md
    │   ├── AGENTS.md
    │   ├── CLAUDE.md
    │   ├── pyproject.toml.tmpl
    │   ├── tests/
    │   └── docs/
    └── ml/
        ├── .agent/
        ├── docs/
        ├── experiments/
        ├── infra/
        ├── eval/
        └── scripts/

渐进式加载

仅阅读当前流程所需的参考资料：

• 始终阅读 references/architecture.md
• 对于新项目，阅读 references/new-project.md
• 对于分叉／增强工作，阅读 references/fork-enhancement.md
• 如果需要策略、权衡或故障处理指南，阅读 references/best-practices.md

以 templates/ 中的内容为准，而不是复现冗长的内联代码片段。 以 template_manifest.json 为准，确定脚手架支持的模板组和占位符。

步骤 1 — 收集项目信息

在一条消息中询问用户：

1. 项目类型：
   • new — 创建新项目
   • fork — 克隆并增强现有仓库
2. 如果是 new：
   • 项目名称
   • 包名称（默认：项目名称的 snake_case 形式）
   • 简短描述
   • Python 版本（默认：3.11）
   • 项目类型：ml、web、lib 或 general
3. 如果是 fork：
   • GitHub 仓库 URL
   • 用户想采用分叉工作流，还是仅在本地增强
4. 两种情况都要询问：
   • 目标仓库的 GitHub 仓库 URL（如有）
   • 作者姓名和邮箱
   • 现有工具链策略（如有）：ruff、black、isort、mypy、pyright、pytest、pre-commit、gitleaks、shellcheck、shfmt、actionlint、nbstripout、CI 或自定义命令

等待用户答复后再继续。

步骤 2 — 选择执行路径

路径 A：新项目

阅读 references/new-project.md 和 references/architecture.md。

2A.1 创建项目根目录

mkdir <project-name>
cd <project-name>
uv init --name <package_name> --python <version>

如果目录已存在，请停止并询问用户是选择新名称还是复用该目录。

2A.2 new + ml 的首选路径

对于新的 ML 项目，优先使用随附的脚手架脚本：

python3 <installed-skill-dir>/scripts/scaffold_new_project.py \
  <target-dir> \
  --project-name <project-name> \
  --package-name <package-name> \
  --description "<short-description>" \
  --python-version <version> \
  --author-name "<author-name>" \
  --author-email "<author-email>" \
  --repo-url "<repo-url-or-TBD>"

该脚本会处理：

• uv init
• 创建 source、test 和 docs 目录
• 从 templates/common/ 和 templates/ml/ 复制模板
• 替换占位符
• 创建 .env
• 为本地到远程工作流初始化远程项目记忆文件
• 写入 .gitkeep 文件

脚本运行完成后，继续执行步骤 2A.6 和 2A.7 中的安装、验证和 Git 设置。

如果用户需要非 ML 布局，或者该脚本不适用，请改用下方的手动流程。

2A.3 手动备用方案：创建目录结构

对于 ml 项目，根据 references/architecture.md 创建完整的四层结构。

至少创建：

mkdir -p src/<package_name>/{models,data,utils}
mkdir -p tests/{data,outputs}
mkdir -p docs/outlines docs/dev/features docs/src docs/results docs/reports docs/runs
mkdir -p .vscode .cursor .claude/commands
touch src/<package_name>/__init__.py
touch src/<package_name>/models/__init__.py
touch src/<package_name>/data/__init__.py
touch src/<package_name>/utils/__init__.py
touch tests/__init__.py

对于非 ML 项目，保留通用项目文件；只有用户明确要求时才创建 ML 专用目录。

2A.4 填充模板

使用 templates/ 下的模板并替换占位符：

• {{PROJECT_NAME}}
• {{PACKAGE_NAME}}
• {{DESCRIPTION}}
• {{PYTHON_VERSION}}
• {{AUTHOR_NAME}}
• {{AUTHOR_EMAIL}}
• {{REPO_URL}}

从 templates/common/ 写入以下通用文件：

• .gitignore
• .env.example
• README.md
• AGENTS.md
• CLAUDE.md
• .pre-commit-config.yaml
• pyproject.toml
• tests/conftest.py
• docs/outlines/project_plan.md
• docs/outlines/progress.md
• docs/results/.gitkeep
• docs/reports/.gitkeep
• docs/runs/.gitkeep
• docs/dev/feature_template.md
• docs/src/dependencies.md
• .vscode/settings.json

对于 ml 项目，还需写入：

• experiments/config.py
• experiments/configs/base.yaml
• infra/envs/local.yaml
• infra/envs/cluster.yaml.example
• infra/remote-projects.yaml
• infra/README.md
• docs/ops/current-status.md
• docs/ops/decision-log.md
• .agent/local-overrides.yaml
• eval/baselines/README.md
• scripts/train.py
• scripts/download_data.py

如果 .env 不存在，则创建一个带简短注释头的空文件。

2A.5 为为空的目录添加占位文件

必要时使用 .gitkeep，以便跟踪空目录：

touch experiments/configs/.gitkeep
touch eval/benchmarks/.gitkeep
touch eval/baselines/reproduced/.gitkeep
touch infra/submit/slurm/.gitkeep
touch docs/results/.gitkeep
touch docs/reports/.gitkeep
touch docs/runs/.gitkeep
touch tests/data/.gitkeep
touch tests/outputs/.gitkeep

仅为所选项目类型中实际存在的目录创建占位文件。

2A.6 安装并验证工具链门禁

如果此代码仓库属于项目控制根目录布局（<ProjectName>/code/，并有同级的 <ProjectName>/code-worktrees/），则在运行任何 uv sync 或 uv run 命令之前，先使用共享的项目代码 uv 环境：

export UV_PROJECT_ENVIRONMENT=<absolute-project-root>/.uv-envs/code

此策略中不要使用相对路径的 UV_PROJECT_ENVIRONMENT；uv 会根据每个当前工作区根目录解析相对路径值，因此不同的 worktree 仍可能各自创建不同的环境。应从当前 worktree 使用 uv run 运行 Python 入口点，而不要直接调用共享环境中的 bin/python。只有在依赖、Python/CUDA 技术栈、破坏性软件包测试或真实并发同步风险有此需要时，才使用单独的阶段环境，并在 worktree 或项目说明中记录这一例外。

对于 ML 项目：

uv sync
uv pip install -e ".[dev,ml]"

对于非 ML 项目：

uv sync
uv pip install -e ".[dev]"

运行默认的非修改性门禁。省略所选项目类型中不存在的路径：

uv run ruff format --check src tests experiments scripts
uv run ruff check src tests experiments scripts
uv run mypy src
uv run pytest tests -v
uv run pre-commit run --all-files

如果尚无测试，则创建一个占位测试并重新运行：

cat > tests/test_placeholder.py <<'EOF'
def test_placeholder():
    assert True
EOF
uv run pytest tests/

不要悄悄运行 uv run ruff format ...、uv run ruff check --fix ...、shfmt -w、不带 --dry-run 的 nbstripout 或其他会修改文件的修复命令。仅在用户要求格式化/修复或项目文档规定必须执行时使用修改性命令，然后检查差异。

2A.7 初始化 git 和可选的远程仓库

git rev-parse --git-dir >/dev/null 2>&1 || git init
git add .
git commit -m "Initial Python project structure"

如果用户提供了 GitHub URL，则添加 origin、显示 git remote -v，并在推送前征求确认：

git remote add origin <github-ssh-url>
CURRENT_BRANCH="$(git branch --show-current)"
project-push --set-upstream . origin "$CURRENT_BRANCH"

路径 B：Fork / 现有项目

阅读 references/fork-enhancement.md、references/architecture.md 和 references/best-practices.md。

2B.1 克隆并检查

git clone <github-ssh-url> <project-name>
cd <project-name>
ls -la

检查以下内容：

• pyproject.toml、setup.py、requirements.txt
• src/、tests/、docs/、scripts/
• .env.example、AGENTS.md、CLAUDE.md、.vscode/settings.json

2B.2 批量编辑前报告缺漏

提供一份简明报告，说明：

• 现有结构
• 缺少的高价值组件
• 仓库是否已可安装
• 已有哪些工具链门禁
• 文档/测试隔离是否缺失

然后询问是否要：

1. 添加所有缺失组件
2. 仅添加选定组件
3. 生成检查清单，不进行编辑

2B.3 仅添加缺失组件

用户批准修改后，使用 templates/common/ 下的模板补齐缺失内容：

• .env.example
• AGENTS.md
• CLAUDE.md
• .pre-commit-config.yaml
• tests/conftest.py
• 文档模板
• .vscode/settings.json
• 从 requirements.txt 迁移时使用 pyproject.toml

除非用户明确要求进行迁移，否则不要强行将完整的 ML 布局套用到现有仓库上。 保留现有且运行良好的工具链。不要仅因新脚手架默认使用 ruff、mypy、pytest 和本地 pre-commit 钩子，就替换 black、isort、pyright、pre-commit、gitleaks、shellcheck、shfmt、actionlint、nbstripout 或 CI 命令。

模板应用规则

• 如果现有的重要文件已经足够完善，就保留它们。
• 优先进行精细修改，而不是覆盖文件。
• 对于模板文件，统一替换占位符。
• 如果模板只有部分内容适用，就复制相关章节，不要原样照搬整个文件。

最终摘要

报告：

✓ Python project initialized or enhanced: <project-name>
✓ Project type: <new|fork> / <ml|web|lib|general>
✓ Common scaffolding applied
✓ UV environment configured
✓ Toolchain gates configured: format / lint / type-check / test / secrets / shell / notebooks / configs / docs links
✓ Git status: initialized / existing repo reused
✓ Remote: <configured or skipped>

Project location: <full-path>

Next steps:
1. cd <project-name>
2. cp .env.example .env
3. Fill in project-specific settings
4. Start implementing in src/<package_name>/
5. Put stable experiment summaries in docs/results/, reports in docs/reports/, and run pointers in docs/runs/
6. Run the toolchain gates before the next commit:
   `uv run ruff format --check src tests experiments scripts`
   `uv run ruff check src tests experiments scripts`
   `uv run mypy src`
   `uv run pytest tests -v`
   `uv run pre-commit run --all-files`

重要说明

• 遇到边缘情况时，使用 references/best-practices.md。
• 让此 SKILL.md 专注于编排；详细文件内容应放在 templates/ 和 references/ 中。
• experiments/ 用于可运行的实验逻辑，而不是归档结果。原始输出、检查点、日志以及 wandb/tensorboard 缓存应保存在忽略路径或外部存储中，并在 docs/runs/ 中保留简短引用。
• 如果此代码仓库属于项目控制根目录，应优先在 <ProjectName>/code-worktrees/ 下创建同级代码工作树，而不是在 code/ 内嵌套工作树。
• 完成预检后，常规最终分支推送应使用 project-push <repo> <remote> <branch>，而不是直接使用 git push、git -C <repo> push、cd <repo> && git push 或由 shell 包装的推送命令。
• 如果此代码仓库属于项目控制根目录，应在根目录的 memory/project.yaml 和组件指南中记录工具链门禁命令。除非已在当前分支或工作树中验证，否则门禁状态均为过期。