SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场init-python-project

init-python-project

编程与开发

查看项目

更新于 10-15 10:58

技能介绍

用途

init-python-project 用于初始化或增强一个 Python/ML 项目。它适用于两类场景：一是创建全新仓库，二是对已有仓库（如 fork）进行生产化改造。其目标是在不把大段文件正文内联进技能本身的前提下，借助捆绑的 references 和 templates 作为文件内容的唯一来源，帮助用户搭建可用的项目骨架。

主要能力

  • 项目结构初始化：为新项目创建目录布局，ML 项目按四层结构生成 src、tests、docs、experiments、infra、eval、scripts 等目录；非 ML 项目保留通用文件，仅在用户明确需要时才创建 ML 专属目录。
  • 模板物化：基于 templates/common/ 与 templates/ml/ 写出 .gitignore、.env.example、README.md、AGENTS.md、CLAUDE.md、.pre-commit-config.yaml、pyproject.toml、tests/conftest.py、docs 模板、.vscode/settings.json，以及 ML 项目专属的 experiments、infra、eval、scripts 等文件，并统一替换占位符（如 {{PROJECT_NAME}}、{{PACKAGE_NAME}}、{{DESCRIPTION}}、{{PYTHON_VERSION}}、{{AUTHOR_NAME}}、{{AUTHOR_EMAIL}}、{{REPO_URL}}）。
  • uv 环境配置：使用 uv init、uv sync、uv pip install -e ".[dev,ml]"（ML）或 ".[dev]"（非 ML）建立并安装环境。
  • 工具链关卡：配置并运行格式、静态检查、类型检查、测试、密钥、shell、notebook、配置、文档链接等检查，默认使用非破坏性命令，如 ruff format --check、ruff check、mypy、pytest、pre-commit run --all-files。
  • fork/既有项目增强：克隆并检查现有仓库，报告结构、缺失的高价值组件、是否可安装、已有工具链关卡、文档与测试隔离情况，然后由用户选择补齐全部、部分或仅生成清单。
  • 脚手架脚本：对新 ML 项目优先使用 scripts/scaffold_new_project.py，由脚本处理 uv init、目录创建、模板复制、占位符替换、创建 .env、引导远程项目记忆文件、写 .gitkeep 等工作。
  • Git 初始化与远程配置：按需执行 git init、提交初始结构，并在用户提供 GitHub URL 时添加 origin、展示 git remote -v、推送前先询问。

使用方式

第一步是收集项目信息，在一条消息内向用户询问：项目类型（new 或 fork）；新建时提供项目名、包名（默认项目名的 snake_case）、简短描述、Python 版本（默认 3.11）、项目类型（ml、web、lib、general）；fork 时提供 GitHub 仓库 URL、采用 fork 工作流还是本地增强；两者都需仓库 URL（若有）、作者姓名与邮箱，以及已有的工具链政策（ruff、black、isort、mypy、pyright、pytest、pre-commit、gitleaks、shellcheck、shfmt、actionlint、nbstripout、CI 或自定义命令）。等待回答后再继续。

第二步选择执行路径。

路径 A（新项目）：读取 references/new-project.md 与 references/architecture.md。创建项目根目录：mkdir <project-name>；cd <project-name>；uv init --name <package_name> --python <version>。若目录已存在，停止并询问是换名还是复用。对新的 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>"。若用户需要非 ML 布局或脚本不适用，则回退到手动路径，创建目录、物化模板、补充 .gitkeep、安装并验证工具链关卡、初始化 git。

安装后默认运行非破坏性关卡（省略不存在的路径）：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。若尚无测试，先创建占位测试再重跑。不要静默运行会修改文件的修复命令（如 ruff format、ruff check --fix、shfmt -w、nbstripout 不带 --dry-run），除非用户要求格式化或修复，或项目政策有明确规定，并在之后检查 diff。

Git 初始化：git rev-parse --git-dir 检查是否已是仓库，否则 git init；然后 git add . 与提交“Initial Python project structure”。若用户提供了 GitHub URL，添加 origin、展示远程列表，并在推送前询问。

路径 B（fork/既有项目）：读取 references/fork-enhancement.md、references/architecture.md、references/best-practices.md。克隆并检查仓库（pyproject.toml、setup.py、requirements.txt、src、tests、docs、scripts、.env.example、AGENTS.md、CLAUDE.md、.vscode/settings.json 等）。在批量编辑前先产出一份简洁报告，列出既有结构、缺失的高价值组件、仓库是否已可安装、已有哪些工具链关卡、文档或测试隔离是否缺失；随后询问用户是补齐全部、只补选定组件，还是仅生成清单而不编辑。获得批准后，只补齐缺失项，并使用模板填充空白。不要强行把完整 ML 布局套用到既有仓库，除非用户明确要求该迁移；保留既有健康工具链，不要因为新脚手架默认 ruff、mypy、pytest 就替换掉 black、isort、pyright、pre-commit、gitleaks、shellcheck、shfmt、actionlint、nbstripout 或 CI 命令。

适用场景

  • 从零开始搭建一个结构完整、便于协作与复现的 Python 或 ML 项目。
  • 将 fork 或遗留仓库升级为具备生产结构、uv 环境和研究证据文档的项目。
  • 需要统一团队工具链关卡（格式、静态检查、类型检查、测试、密钥、shell、notebook、配置、文档链接）并记录实际命令的场景。
  • 需要将实验配置、运行指针、结果与报告分离管理的 ML 研究场景。

限制与注意事项

  • 默认只运行非破坏性检查，修改型修复命令必须在用户要求或项目政策要求下才执行，且需复核 diff。
  • 模板内容以 templates/ 为准，模板组与占位符能力以 template_manifest.json 为准；不要把长文件正文内联到技能里。
  • experiments/ 是可运行的实验逻辑，不是结果存档；原始输出、检查点、日志和 wandb/tensorboard 缓存应放在被忽略的路径或外部存储，仅在 docs/runs/ 放小的指针。
  • 若代码仓库属于项目控制根布局（<ProjectName>/code/ 与同级 <ProjectName>/code-worktrees/），应先设置共享的 uv 项目环境（export UV_PROJECT_ENVIRONMENT=<absolute-project-root>/.uv-envs/code），不要使用相对值；Python 入口应通过活动 worktree 的 uv run 运行，而不是直接调用共享环境的 bin/python；仅在依赖、Python/CUDA 栈、破坏性包测试或真实并发同步风险需要时使用独立 stage 环境，并在 worktree 或项目指导中记录该例外。
  • 该布局下优先使用同级的 code worktrees，而不是嵌套在 code/ 内。
  • 预检后的常规最终分支推送，使用 project-push <repo> <remote> <branch>，而不是原始 git push、git -C <repo> push、cd <repo> && git push 或 shell 包装的变体。
  • 属项目控制根时，应将工具链关卡命令记录在根 memory/project.yaml 和组件指导中；除非在当前分支/worktree 中验证过，否则关卡状态视为过期。
  • 遇到边缘情况时参考 references/best-practices.md。
  • 以上之外的细节，如具体收费、价格、平台覆盖范围等，资料中暂未提供。