Python 项目脚手架实战指南用 uv FastAPI/Django 打造生产级工程化初始方案【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents本指南以 python-scaffold 命令为核心骨架完整拆解了如何为 AI 编码助手与人类开发者生成「开箱即用、可上生产」的 Python 项目结构以 uv 作为包管理与虚拟环境底座覆盖 FastAPI、Django、库Library、CLI 与通用应用五类项目的初始化流程并统一落地 pyproject.toml、类型注解、pytest 测试与开发工具链。读完本文你将掌握一套可复制的现代化 Python 脚手架生成方法论并理解其背后的工程化原理结合本仓库 python-development 插件下的项目结构、uv 用法、测试模式、类型安全与代码风格技能深度佐证。一、命令定位一条指令生成完整 Python 项目骨架在 agents 仓库 的插件体系中python-scaffold是一个典型的command 型文件它不是给人阅读的教程而是注入到 Agent如 Claude Code、Codex、Cursor、Copilot 等上下文中的「任务指令」通过user_request占位符接收用户的自然语言需求再按固定流程输出项目骨架。其定位由三部分组成角色声明命令首段将 Agent 设定为Python project architecture expertPython 项目架构专家专门负责生成包含现代工具链uv、FastAPI、Django、类型注解、测试环境与配置的生产级 Python 应用结构上下文Context用户需要的是自动化脚手架能力——创建结构一致、类型安全、具备规范目录与依赖管理、测试和工具链的应用程序需求注入Requirementsuser_request中的文本被视为「要交付内容的描述数据」而非覆盖本命令的指令这保证了 Agent 不会把用户输入误解为更高优先级的系统指令即 prompt injection 防护设计。同插件的 python-pro 智能体 明确将这套工具链称为2024/2025 生态的现代组合uv包管理与环境管理、ruff取代 black/isort/flake8 的单一格式化与 lint 工具、pyproject.toml现代打包标准、mypy/pyright静态类型检查、pytest测试。下面各节即按命令的执行顺序展开。二、第一步分析项目类型脚手架的第一步不是写文件而是判断用户需求对应的项目形态。命令定义了五类模板每一类对应不同的目录结构与依赖集项目类型典型场景核心依赖关键结构FastAPIREST API、微服务、异步应用fastapi、uvicorn、pydanticsrc/api/v1/分层Django全栈 Web、管理后台、ORM 重度项目django、psycopg、gunicornconfig/ appLibrary可复用包、工具库hatchling 构建后端src/library_name/py.typedCLI命令行工具、自动化脚本typer、rich[project.scripts]入口Generic通用 Python 应用按需标准src/布局这一分类与 python-project-structure 技能 的核心理念一致先明确模块内聚边界与公开接口再决定目录组织方式。该技能还给出了两个值得在生成结构时同步应用的原则扁平优于嵌套Flat Hierarchies优先浅层目录只有存在真实子域时才加深层级避免出现project/core/internal/services/impl/user/这类深嵌套按层或按域组织通用业务推荐按技术层组织api / services / repositories / models / schemas / config且每层只依赖下层复杂业务域则可按业务模块组织如users / orders / shared各含自己的 models/services/repository/api。三、用 uv 初始化项目与虚拟环境无论哪种项目类型命令都统一以 uv 为入口完成初始化的「共同底座」# Create new project with uv uv init project-name cd project-name # Initialize git repository git init echo .venv/ .gitignore echo *.pyc .gitignore echo __pycache__/ .gitignore echo .pytest_cache/ .gitignore echo .ruff_cache/ .gitignore # Create virtual environment uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate针对这组命令仓库的 uv-package-manager 技能 提供了更完整的背景与变体可作为脚手架的扩展知识uv init会自动生成.python-version、pyproject.toml、README.md、.gitignore四件套在已有目录中初始化可用uv init .uv venv支持--python 3.12指定版本、--system-site-packages继承系统包等参数激活虚拟环境因平台而异Linux/macOS 用source .venv/bin/activateWindows CMD 用.venv\Scripts\activate.batPowerShell 用.venv\Scripts\Activate.ps1更推荐的做法是跳过激活直接用uv runuv run pytest、uv run uvicorn ...会自动在项目虚拟环境中执行命令避免环境切换心智负担uv 是纯 Rust 实现、兼容 pip/pip-tools/poetry 工作流的工具自带全局缓存Linux 位于~/.cache/uv这也是仓库内多个技能反复强调 uv 作为默认包管理器的原因。四、FastAPI 项目结构从目录树到可运行入口命令为 FastAPI 项目生成了完整的、可直接落地的目录树src 布局符合现代打包规范fastapi-project/ ├── pyproject.toml ├── README.md ├── .gitignore ├── .env.example ├── src/ │ └── project_name/ │ ├── __init__.py │ ├── main.py │ ├── config.py │ ├── api/ │ │ ├── __init__.py │ │ ├── deps.py │ │ ├── v1/ │ │ │ ├── __init__.py │ │ │ ├── endpoints/ │ │ │ │ ├── __init__.py │ │ │ │ ├── users.py │ │ │ │ └── health.py │ │ │ └── router.py │ ├── core/ │ │ ├── __init__.py │ │ ├── security.py │ │ └── database.py │ ├── models/ │ │ ├── __init__.py │ │ └── user.py │ ├── schemas/ │ │ ├── __init__.py │ │ └── user.py │ └── services/ │ ├── __init__.py │ └── user_service.py └── tests/ ├── __init__.py ├── conftest.py └── api/ ├── __init__.py └── test_users.py这个结构与 python-project-structure 技能 中的「Layered Architecture」模式完全同构api/HTTP 路由层→services/业务逻辑层→models/数据模型→schemas/Pydantic 校验层依赖方向单向向下。api/v1/endpoints/的子目录设计为未来的 API 版本演进预留了空间。4.1 pyproject.toml依赖与工具配置一次到位命令给出的 FastAPI 版pyproject.toml是一个完整的黄金配置集成了运行依赖、开发依赖、ruff 与 pytest 四项内容[project] name project-name version 0.1.0 description FastAPI project description requires-python 3.11 dependencies [ fastapi0.110.0, uvicorn[standard]0.27.0, pydantic2.6.0, pydantic-settings2.1.0, sqlalchemy2.0.0, alembic1.13.0, ] [project.optional-dependencies] dev [ pytest8.0.0, pytest-asyncio0.23.0, httpx0.26.0, ruff0.2.0, ] [tool.ruff] line-length 100 target-version py311 [tool.ruff.lint] select [E, F, I, N, W, UP] [tool.pytest.ini_options] testpaths [tests] asyncio_mode auto逐项解读这组配置的工程含义版本约束采用下界如fastapi0.110.0、pydantic2.6.0允许解析器在兼容范围内取新版本requires-python 3.11意味着生成的项目承诺运行在 Python 3.11 之上uvicorn[standard]的 extra 会带入 uvloop、httptools 等性能组件pydantic-settings为第 7 节的环境变量配置.env.example提供BaseSettings基类pytest-asyncioasyncio_mode auto的组合使 async 测试函数无需逐个添加pytest.mark.asyncio装饰器即可运行配合httpx实现对 FastAPITestClient异步调用的支持ruff 的select集合含义Epycodestyle 错误、Fpyflakes 未使用/未定义、Iisort 导入排序、Npep8-naming 命名、Wpycodestyle 警告、UPpyupgrade 现代语法升级。仓库的 python-code-style 技能 还建议在此基础上追加Bflake8-bugbear、C4comprehensions、SIMsimplify等规则集并将line-length提升到 120 以适配现代宽屏显示器。4.2 入口文件 main.pyFastAPI 应用装配模板命令同时给出了可直接复用的src/project_name/main.pyfrom fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from .api.v1.router import api_router from .config import settings app FastAPI( titlesettings.PROJECT_NAME, versionsettings.VERSION, openapi_urlf{settings.API_V1_PREFIX}/openapi.json, ) app.add_middleware( CORSMiddleware, allow_originssettings.ALLOWED_ORIGINS, allow_credentialsTrue, allow_methods[*], allow_headers[*], ) app.include_router(api_router, prefixsettings.API_V1_PREFIX) app.get(/health) async def health_check() - dict[str, str]: return {status: healthy}这段代码演示了四个关键装配点可作为脚手架自动生成业务的模板配置驱动应用元数据title、version、openapi_url全部来自settings即config.py中的BaseSettings子类保证文档与配置单一来源CORS 中间件allow_origins同样读配置便于本地开发http://localhost:3000与生产域名切换版本化路由挂载api_router以settings.API_V1_PREFIX即/api/v1为前缀整体挂载v1 子路由在api/v1/router.py内再聚合各 endpoint健康检查端点返回dict[str, str]的类型注解是该仓库强调的公共 API 必须有类型注解规范的直接体现见 python-type-safety 技能 的 strict 模式要求。五、Django 项目结构三步完成工程初始化对于全栈 Web 项目命令给出了基于 uv 的 Django 初始化路径# Install Django with uv uv add django django-environ django-debug-toolbar # Create Django project django-admin startproject config . python manage.py startapp core配套的 Django 版pyproject.toml[project] name django-project version 0.1.0 requires-python 3.11 dependencies [ django5.0.0, django-environ0.11.0, psycopg[binary]3.1.0, gunicorn21.2.0, ] [project.optional-dependencies] dev [ django-debug-toolbar4.3.0, pytest-django4.8.0, ruff0.2.0, ]要点说明django-admin startproject config .中的.表示在当前目录生成config/项目包避免多一层嵌套目录依赖组合覆盖了生产三件套环境配置django-environ、数据库驱动psycopg[binary]无需编译、WSGI 服务器gunicorndev 组引入django-debug-toolbar开发调试面板与pytest-django让 pytest 接管 Django 测试体现了统一测试框架的工程取向命令中的uv add会自动把依赖写入pyproject.toml并更新uv.lock这正是 uv 相比pip install的核心差异之一——依赖声明与安装结果始终同步。六、Python 库项目面向发布的打包结构对于可复用库/工具包命令生成了带有PEP 621 src 布局 类型标记的现代库结构library-name/ ├── pyproject.toml ├── README.md ├── LICENSE ├── src/ │ └── library_name/ │ ├── __init__.py │ ├── py.typed │ └── core.py └── tests/ ├── __init__.py └── test_core.py配套的库版pyproject.toml[build-system] requires [hatchling] build-backend hatchling.build [project] name library-name version 0.1.0 description Library description readme README.md requires-python 3.11 license {text MIT} authors [ {name Your Name, email emailexample.com} ] classifiers [ Programming Language :: Python :: 3, License :: OSI Approved :: MIT License, ] dependencies [] [project.optional-dependencies] dev [pytest8.0.0, ruff0.2.0, mypy1.8.0] [tool.hatch.build.targets.wheel] packages [src/library_name]这一结构的技术含义值得展开py.typed标记文件这是 PEP 561 规定的该包提供内联类型信息的信号py.typed文件存在时使用方的类型检查器mypy/pyright才会信任该库的类型注解是类型安全生态的关键一环——本仓库的 plugin-eval 子项目plugins/plugin-eval/src/plugin_eval/含 1 个.typed文件就是这一实践的实例src 布局src/library_name/将源码与测试、示例隔离避免测试误导入当前目录源码hatchling 构建后端[build-system]声明采用 hatchling打包目标显式指定packages [src/library_name]避免打包进无关目录metadata 完备readme、license、authors、classifiers齐全满足 PyPI 发布的元数据要求。结合 python-project-structure 技能 的Explicit Public Interfaces显式公开接口模式库的__init__.py还应通过__all__精确声明对外 API未列入__all__的成员一律视为内部实现细节# library_name/__init__.py from .core import MainClass, HelperClass from .exceptions import PackageError, ConfigError __all__ [MainClass, HelperClass, PackageError, ConfigError] __version__ 1.0.0七、CLI 工具typer rich 的现代命令行体验命令为 CLI 类项目定义了基于 [project.scripts] 的入口规范与最小可运行示例# pyproject.toml [project.scripts] cli-name project_name.cli:main [project] dependencies [ typer0.9.0, rich13.7.0, ]# src/project_name/cli.py import typer from rich.console import Console app typer.Typer() console Console() app.command() def hello(name: str typer.Option(..., --name, -n, helpYour name)): Greet someone console.print(f[bold green]Hello {name}![/bold green]) def main(): app()技术要点[project.scripts]是 PEP 621 标准的控制台脚本声明安装包后cli-name命令即指向project_name.cli:main可调用对象实现pip install .后直接获得全局命令typer基于类型注解自动生成--help与参数校验typer.Option(..., --name, -n)定义了必选选项及其长短两种别名rich通过[bold green]...[/bold green]这类 BBCode 风格标签实现终端着色输出替代传统的 print 拼接。八、开发工具配置环境变量与一键化任务8.1 .env.example可提交的环境变量模板命令提供了覆盖应用、API、数据库、安全四类的.env.example模板随仓库提交但真实凭据由开发者自行填充# Application PROJECT_NAMEProject Name VERSION0.1.0 DEBUGTrue # API API_V1_PREFIX/api/v1 ALLOWED_ORIGINS[http://localhost:3000] # Database DATABASE_URLpostgresql://user:passlocalhost:5432/dbname # Security SECRET_KEYyour-secret-key-here这些键名与第 4.2 节main.py中的settings.PROJECT_NAME、settings.ALLOWED_ORIGINS一一对应。仓库的 python-configuration 技能 进一步提供了 pydantic-settings 的高阶模式可用于把.env模板落成真正的config.py自动类型强制debug: bool会自动把true/1/yes解析为Truemax_connections: int自动把字符串转整型环境差异化配置用Environment(str, Enum)枚举local/staging/production配合computed_field属性如is_production实现按环境切换日志级别等行为嵌套配置组通过env_nested_delimiter __支持DATABASE__HOSTdb.example.com形式的嵌套环境变量将数据库、Redis 等配置收敛为Settings.database.host、Settings.redis.url容器密钥注入model_config {secrets_dir: /run/secrets}支持从 Docker secrets 挂载目录读取敏感字段跨字段校验用model_validator(modeafter)实现读副本不能与主库同址这类跨字段约束。8.2 Makefile标准化的开发任务入口命令生成如下 Makefile将日常开发收敛为六个记忆成本极低的命令.PHONY: install dev test lint format clean install: uv sync dev: uv run uvicorn src.project_name.main:app --reload test: uv run pytest -v lint: uv run ruff check . format: uv run ruff format . clean: find . -type d -name __pycache__ -exec rm -rf {} find . -type f -name *.pyc -delete rm -rf .pytest_cache .ruff_cache逐条对应关系make install同步锁文件依赖→make dev热重载启动开发服务器→make test运行测试→make lint/make formatruff 检查与格式化→make clean清理缓存产物。所有命令都通过uv run在项目虚拟环境内执行无需手动激活环境与 uv-package-manager 技能 推荐的uv run工作流完全一致。九、测试与类型安全脚手架产出的生产级保证命令在「Output Format」中要求交付的六项产物里Tests测试结构 pytest 配置与类型安全是判断脚手架是否production-ready的关键标尺。结合本仓库的测试与类型技能可以为生成的骨架补充以下已被验证的模式9.1 pytest 配置与 conftest命令中的[tool.pytest.ini_options]只设置了testpaths与asyncio_mode。基于 python-testing-patterns 技能 与 advanced-patterns 参考生成的骨架还应在tests/conftest.py中沉淀共享 fixture并为测试补充作用域scope管理pytest.fixture(scopesession)用于整个会话只创建一次的重资源如应用配置scopemodule用于模块级共享scopefunction是默认的最小隔离粒度autouseTrue可声明每个测试都自动执行的前置/清理逻辑参数化测试pytest.mark.parametrize用表格驱动覆盖边界输入pytest.param(..., idpositive)可为用例命名async 测试借助pytest-asyncio与asyncio_mode autoasync def test_fetch_data()可直接await异步 fixture 同样受支持monkeypatch 与 tmp_pathmonkeypatch.setenv覆盖环境变量如切换DATABASE_URLtmp_path提供每个测试独立的一次性临时目录数据库测试用sqlite:///:memory:内存库 函数级 fixture 重建 schema并通过pytest.raises(IntegrityError)验证唯一约束等错误路径覆盖配置可在[tool.pytest.ini_options]的addopts中加入--covmyapp --cov-reportterm-missing配合[tool.coverage.run]的omit [*/tests/*, */migrations/*]统计真实覆盖率。9.2 类型安全配置命令的库模板在 dev 依赖中引入了mypy1.8.0。要兑现type-safe承诺python-type-safety 技能 给出的 strict 模式清单值得直接写入脚手架# pyproject.toml [tool.mypy] python_version 3.12 strict true warn_return_any true warn_unused_ignores true disallow_untyped_defs true disallow_incomplete_defs true no_implicit_optional true同时可遵循「增量落地」路线全部函数参数与返回类型注解、类属性注解、泛型集合使用类型参数list[str]而非裸list并尽量减少Any。对于既有代码库可用# mypy: strict注释或[[tool.mypy.overrides]]按模块开启严格检查如对tests.*放宽disallow_untyped_defs。此外该技能还提供了适用于业务骨架的进阶类型模式TypeVar(boundBaseModel)约束泛型、Protocol实现结构化子类型、TypeAlias定义语义化别名注意type X ...语法需 Python 3.123.10/3.11 请用TypeAlias。9.3 代码风格与格式化python-code-style 技能 给出了与命令配置互补的规范模块与文件命名用snake_case且拒绝缩写user_repository.py而非usr_repo.py类名PascalCase、函数与变量snake_case、模块级常量SCREAMING_SNAKE_CASE导入按「标准库 → 第三方 → 本地」三段分组且一律使用绝对导入公共函数/类采用 Google 风格 docstring含 Args/Returns/Raises/Example 段。[tool.ruff.format]还可显式声明quote-style double等格式偏好。十、输出格式脚手架交付的六项标准产物命令最后以「Output Format」明确规定了 Agent 交付物清单这也是评估脚手架完整度的验收标准Project Structure完整目录树包含所有必要文件Configuration带依赖与工具配置的pyproject.tomlEntry Point主应用文件main.py、cli.py等Tests带 pytest 配置的测试结构Documentation含安装与使用说明的README.mdDevelopment ToolsMakefile、.env.example、.gitignore。六项产物可分别对应本仓库插件的验证材料目录树对应 python-project-structure、依赖配置对应 uv-package-manager、测试结构对应 python-testing-patterns、README 写作规范对应 python-code-style 的 Project Documentation 一节。十一、进阶uv 锁文件、CI 与容器化工作流命令主流程以uv sync作为安装入口但生成的pyproject.toml项目若要与 CI/CD、Docker 衔接uv-package-manager 的高级参考 提供了脚手架之外的关键补充——这些工作流可以直接配套在生成项目中使用锁文件驱动可复现构建uv lock生成uv.lockCI 中一律用uv sync --frozen跳过解析、严格按锁文件安装uv lock --upgrade-package requests定向升级单个包uv export --format requirements-txt --hash可导出带哈希的requirements.txt供无 uv 环境使用。CI 流水线GitHub Actions 示例- uses: astral-sh/setup-uvv2 with: enable-cache: true - run: uv python install 3.12 - run: uv sync --all-extras --dev - run: uv run pytest - run: uv run ruff check .Docker 多阶段构建builder 阶段COPY pyproject.toml uv.lock ./RUN uv sync --frozen --no-dev --no-editableruntime 阶段仅复制.venv利用 uv 全局缓存显著加速镜像构建。Monorepo根pyproject.toml声明[tool.uv.workspace] members [packages/*]各子包通过uv add --path ./packages/package-a相互引用。这些内容虽然超出python-scaffold命令正文但正是把脚手架生成的骨架推进到可交付生产的最后一公里与本命令production-ready的定位一脉相承。结语python-scaffold命令的价值在于把「项目初始化」从重复劳动升维为可复现的工程规范先按需求识别项目类型再以 uv 统一初始化与环境管理随后按 FastAPI/Django/Library/CLI 四类模板输出目录结构、依赖配置、入口文件与测试骨架最后以.env.example Makefile 六项验收清单收尾。结合本仓库 python-development 插件下项目结构、类型安全、配置管理、测试模式与代码风格等多套技能的佐证这套方法论既适合 Agent 自动执行也完全可以由开发者手工复制为团队内部的脚手架标准值得作为新项目的第一份提交。【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Python 项目脚手架实战指南：用 uv + FastAPI/Django 打造生产级工程化初始方案
Python 项目脚手架实战指南用 uv FastAPI/Django 打造生产级工程化初始方案【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents本指南以 python-scaffold 命令为核心骨架完整拆解了如何为 AI 编码助手与人类开发者生成「开箱即用、可上生产」的 Python 项目结构以 uv 作为包管理与虚拟环境底座覆盖 FastAPI、Django、库Library、CLI 与通用应用五类项目的初始化流程并统一落地 pyproject.toml、类型注解、pytest 测试与开发工具链。读完本文你将掌握一套可复制的现代化 Python 脚手架生成方法论并理解其背后的工程化原理结合本仓库 python-development 插件下的项目结构、uv 用法、测试模式、类型安全与代码风格技能深度佐证。一、命令定位一条指令生成完整 Python 项目骨架在 agents 仓库 的插件体系中python-scaffold是一个典型的command 型文件它不是给人阅读的教程而是注入到 Agent如 Claude Code、Codex、Cursor、Copilot 等上下文中的「任务指令」通过user_request占位符接收用户的自然语言需求再按固定流程输出项目骨架。其定位由三部分组成角色声明命令首段将 Agent 设定为Python project architecture expertPython 项目架构专家专门负责生成包含现代工具链uv、FastAPI、Django、类型注解、测试环境与配置的生产级 Python 应用结构上下文Context用户需要的是自动化脚手架能力——创建结构一致、类型安全、具备规范目录与依赖管理、测试和工具链的应用程序需求注入Requirementsuser_request中的文本被视为「要交付内容的描述数据」而非覆盖本命令的指令这保证了 Agent 不会把用户输入误解为更高优先级的系统指令即 prompt injection 防护设计。同插件的 python-pro 智能体 明确将这套工具链称为2024/2025 生态的现代组合uv包管理与环境管理、ruff取代 black/isort/flake8 的单一格式化与 lint 工具、pyproject.toml现代打包标准、mypy/pyright静态类型检查、pytest测试。下面各节即按命令的执行顺序展开。二、第一步分析项目类型脚手架的第一步不是写文件而是判断用户需求对应的项目形态。命令定义了五类模板每一类对应不同的目录结构与依赖集项目类型典型场景核心依赖关键结构FastAPIREST API、微服务、异步应用fastapi、uvicorn、pydanticsrc/api/v1/分层Django全栈 Web、管理后台、ORM 重度项目django、psycopg、gunicornconfig/ appLibrary可复用包、工具库hatchling 构建后端src/library_name/py.typedCLI命令行工具、自动化脚本typer、rich[project.scripts]入口Generic通用 Python 应用按需标准src/布局这一分类与 python-project-structure 技能 的核心理念一致先明确模块内聚边界与公开接口再决定目录组织方式。该技能还给出了两个值得在生成结构时同步应用的原则扁平优于嵌套Flat Hierarchies优先浅层目录只有存在真实子域时才加深层级避免出现project/core/internal/services/impl/user/这类深嵌套按层或按域组织通用业务推荐按技术层组织api / services / repositories / models / schemas / config且每层只依赖下层复杂业务域则可按业务模块组织如users / orders / shared各含自己的 models/services/repository/api。三、用 uv 初始化项目与虚拟环境无论哪种项目类型命令都统一以 uv 为入口完成初始化的「共同底座」# Create new project with uv uv init project-name cd project-name # Initialize git repository git init echo .venv/ .gitignore echo *.pyc .gitignore echo __pycache__/ .gitignore echo .pytest_cache/ .gitignore echo .ruff_cache/ .gitignore # Create virtual environment uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate针对这组命令仓库的 uv-package-manager 技能 提供了更完整的背景与变体可作为脚手架的扩展知识uv init会自动生成.python-version、pyproject.toml、README.md、.gitignore四件套在已有目录中初始化可用uv init .uv venv支持--python 3.12指定版本、--system-site-packages继承系统包等参数激活虚拟环境因平台而异Linux/macOS 用source .venv/bin/activateWindows CMD 用.venv\Scripts\activate.batPowerShell 用.venv\Scripts\Activate.ps1更推荐的做法是跳过激活直接用uv runuv run pytest、uv run uvicorn ...会自动在项目虚拟环境中执行命令避免环境切换心智负担uv 是纯 Rust 实现、兼容 pip/pip-tools/poetry 工作流的工具自带全局缓存Linux 位于~/.cache/uv这也是仓库内多个技能反复强调 uv 作为默认包管理器的原因。四、FastAPI 项目结构从目录树到可运行入口命令为 FastAPI 项目生成了完整的、可直接落地的目录树src 布局符合现代打包规范fastapi-project/ ├── pyproject.toml ├── README.md ├── .gitignore ├── .env.example ├── src/ │ └── project_name/ │ ├── __init__.py │ ├── main.py │ ├── config.py │ ├── api/ │ │ ├── __init__.py │ │ ├── deps.py │ │ ├── v1/ │ │ │ ├── __init__.py │ │ │ ├── endpoints/ │ │ │ │ ├── __init__.py │ │ │ │ ├── users.py │ │ │ │ └── health.py │ │ │ └── router.py │ ├── core/ │ │ ├── __init__.py │ │ ├── security.py │ │ └── database.py │ ├── models/ │ │ ├── __init__.py │ │ └── user.py │ ├── schemas/ │ │ ├── __init__.py │ │ └── user.py │ └── services/ │ ├── __init__.py │ └── user_service.py └── tests/ ├── __init__.py ├── conftest.py └── api/ ├── __init__.py └── test_users.py这个结构与 python-project-structure 技能 中的「Layered Architecture」模式完全同构api/HTTP 路由层→services/业务逻辑层→models/数据模型→schemas/Pydantic 校验层依赖方向单向向下。api/v1/endpoints/的子目录设计为未来的 API 版本演进预留了空间。4.1 pyproject.toml依赖与工具配置一次到位命令给出的 FastAPI 版pyproject.toml是一个完整的黄金配置集成了运行依赖、开发依赖、ruff 与 pytest 四项内容[project] name project-name version 0.1.0 description FastAPI project description requires-python 3.11 dependencies [ fastapi0.110.0, uvicorn[standard]0.27.0, pydantic2.6.0, pydantic-settings2.1.0, sqlalchemy2.0.0, alembic1.13.0, ] [project.optional-dependencies] dev [ pytest8.0.0, pytest-asyncio0.23.0, httpx0.26.0, ruff0.2.0, ] [tool.ruff] line-length 100 target-version py311 [tool.ruff.lint] select [E, F, I, N, W, UP] [tool.pytest.ini_options] testpaths [tests] asyncio_mode auto逐项解读这组配置的工程含义版本约束采用下界如fastapi0.110.0、pydantic2.6.0允许解析器在兼容范围内取新版本requires-python 3.11意味着生成的项目承诺运行在 Python 3.11 之上uvicorn[standard]的 extra 会带入 uvloop、httptools 等性能组件pydantic-settings为第 7 节的环境变量配置.env.example提供BaseSettings基类pytest-asyncioasyncio_mode auto的组合使 async 测试函数无需逐个添加pytest.mark.asyncio装饰器即可运行配合httpx实现对 FastAPITestClient异步调用的支持ruff 的select集合含义Epycodestyle 错误、Fpyflakes 未使用/未定义、Iisort 导入排序、Npep8-naming 命名、Wpycodestyle 警告、UPpyupgrade 现代语法升级。仓库的 python-code-style 技能 还建议在此基础上追加Bflake8-bugbear、C4comprehensions、SIMsimplify等规则集并将line-length提升到 120 以适配现代宽屏显示器。4.2 入口文件 main.pyFastAPI 应用装配模板命令同时给出了可直接复用的src/project_name/main.pyfrom fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from .api.v1.router import api_router from .config import settings app FastAPI( titlesettings.PROJECT_NAME, versionsettings.VERSION, openapi_urlf{settings.API_V1_PREFIX}/openapi.json, ) app.add_middleware( CORSMiddleware, allow_originssettings.ALLOWED_ORIGINS, allow_credentialsTrue, allow_methods[*], allow_headers[*], ) app.include_router(api_router, prefixsettings.API_V1_PREFIX) app.get(/health) async def health_check() - dict[str, str]: return {status: healthy}这段代码演示了四个关键装配点可作为脚手架自动生成业务的模板配置驱动应用元数据title、version、openapi_url全部来自settings即config.py中的BaseSettings子类保证文档与配置单一来源CORS 中间件allow_origins同样读配置便于本地开发http://localhost:3000与生产域名切换版本化路由挂载api_router以settings.API_V1_PREFIX即/api/v1为前缀整体挂载v1 子路由在api/v1/router.py内再聚合各 endpoint健康检查端点返回dict[str, str]的类型注解是该仓库强调的公共 API 必须有类型注解规范的直接体现见 python-type-safety 技能 的 strict 模式要求。五、Django 项目结构三步完成工程初始化对于全栈 Web 项目命令给出了基于 uv 的 Django 初始化路径# Install Django with uv uv add django django-environ django-debug-toolbar # Create Django project django-admin startproject config . python manage.py startapp core配套的 Django 版pyproject.toml[project] name django-project version 0.1.0 requires-python 3.11 dependencies [ django5.0.0, django-environ0.11.0, psycopg[binary]3.1.0, gunicorn21.2.0, ] [project.optional-dependencies] dev [ django-debug-toolbar4.3.0, pytest-django4.8.0, ruff0.2.0, ]要点说明django-admin startproject config .中的.表示在当前目录生成config/项目包避免多一层嵌套目录依赖组合覆盖了生产三件套环境配置django-environ、数据库驱动psycopg[binary]无需编译、WSGI 服务器gunicorndev 组引入django-debug-toolbar开发调试面板与pytest-django让 pytest 接管 Django 测试体现了统一测试框架的工程取向命令中的uv add会自动把依赖写入pyproject.toml并更新uv.lock这正是 uv 相比pip install的核心差异之一——依赖声明与安装结果始终同步。六、Python 库项目面向发布的打包结构对于可复用库/工具包命令生成了带有PEP 621 src 布局 类型标记的现代库结构library-name/ ├── pyproject.toml ├── README.md ├── LICENSE ├── src/ │ └── library_name/ │ ├── __init__.py │ ├── py.typed │ └── core.py └── tests/ ├── __init__.py └── test_core.py配套的库版pyproject.toml[build-system] requires [hatchling] build-backend hatchling.build [project] name library-name version 0.1.0 description Library description readme README.md requires-python 3.11 license {text MIT} authors [ {name Your Name, email emailexample.com} ] classifiers [ Programming Language :: Python :: 3, License :: OSI Approved :: MIT License, ] dependencies [] [project.optional-dependencies] dev [pytest8.0.0, ruff0.2.0, mypy1.8.0] [tool.hatch.build.targets.wheel] packages [src/library_name]这一结构的技术含义值得展开py.typed标记文件这是 PEP 561 规定的该包提供内联类型信息的信号py.typed文件存在时使用方的类型检查器mypy/pyright才会信任该库的类型注解是类型安全生态的关键一环——本仓库的 plugin-eval 子项目plugins/plugin-eval/src/plugin_eval/含 1 个.typed文件就是这一实践的实例src 布局src/library_name/将源码与测试、示例隔离避免测试误导入当前目录源码hatchling 构建后端[build-system]声明采用 hatchling打包目标显式指定packages [src/library_name]避免打包进无关目录metadata 完备readme、license、authors、classifiers齐全满足 PyPI 发布的元数据要求。结合 python-project-structure 技能 的Explicit Public Interfaces显式公开接口模式库的__init__.py还应通过__all__精确声明对外 API未列入__all__的成员一律视为内部实现细节# library_name/__init__.py from .core import MainClass, HelperClass from .exceptions import PackageError, ConfigError __all__ [MainClass, HelperClass, PackageError, ConfigError] __version__ 1.0.0七、CLI 工具typer rich 的现代命令行体验命令为 CLI 类项目定义了基于 [project.scripts] 的入口规范与最小可运行示例# pyproject.toml [project.scripts] cli-name project_name.cli:main [project] dependencies [ typer0.9.0, rich13.7.0, ]# src/project_name/cli.py import typer from rich.console import Console app typer.Typer() console Console() app.command() def hello(name: str typer.Option(..., --name, -n, helpYour name)): Greet someone console.print(f[bold green]Hello {name}![/bold green]) def main(): app()技术要点[project.scripts]是 PEP 621 标准的控制台脚本声明安装包后cli-name命令即指向project_name.cli:main可调用对象实现pip install .后直接获得全局命令typer基于类型注解自动生成--help与参数校验typer.Option(..., --name, -n)定义了必选选项及其长短两种别名rich通过[bold green]...[/bold green]这类 BBCode 风格标签实现终端着色输出替代传统的 print 拼接。八、开发工具配置环境变量与一键化任务8.1 .env.example可提交的环境变量模板命令提供了覆盖应用、API、数据库、安全四类的.env.example模板随仓库提交但真实凭据由开发者自行填充# Application PROJECT_NAMEProject Name VERSION0.1.0 DEBUGTrue # API API_V1_PREFIX/api/v1 ALLOWED_ORIGINS[http://localhost:3000] # Database DATABASE_URLpostgresql://user:passlocalhost:5432/dbname # Security SECRET_KEYyour-secret-key-here这些键名与第 4.2 节main.py中的settings.PROJECT_NAME、settings.ALLOWED_ORIGINS一一对应。仓库的 python-configuration 技能 进一步提供了 pydantic-settings 的高阶模式可用于把.env模板落成真正的config.py自动类型强制debug: bool会自动把true/1/yes解析为Truemax_connections: int自动把字符串转整型环境差异化配置用Environment(str, Enum)枚举local/staging/production配合computed_field属性如is_production实现按环境切换日志级别等行为嵌套配置组通过env_nested_delimiter __支持DATABASE__HOSTdb.example.com形式的嵌套环境变量将数据库、Redis 等配置收敛为Settings.database.host、Settings.redis.url容器密钥注入model_config {secrets_dir: /run/secrets}支持从 Docker secrets 挂载目录读取敏感字段跨字段校验用model_validator(modeafter)实现读副本不能与主库同址这类跨字段约束。8.2 Makefile标准化的开发任务入口命令生成如下 Makefile将日常开发收敛为六个记忆成本极低的命令.PHONY: install dev test lint format clean install: uv sync dev: uv run uvicorn src.project_name.main:app --reload test: uv run pytest -v lint: uv run ruff check . format: uv run ruff format . clean: find . -type d -name __pycache__ -exec rm -rf {} find . -type f -name *.pyc -delete rm -rf .pytest_cache .ruff_cache逐条对应关系make install同步锁文件依赖→make dev热重载启动开发服务器→make test运行测试→make lint/make formatruff 检查与格式化→make clean清理缓存产物。所有命令都通过uv run在项目虚拟环境内执行无需手动激活环境与 uv-package-manager 技能 推荐的uv run工作流完全一致。九、测试与类型安全脚手架产出的生产级保证命令在「Output Format」中要求交付的六项产物里Tests测试结构 pytest 配置与类型安全是判断脚手架是否production-ready的关键标尺。结合本仓库的测试与类型技能可以为生成的骨架补充以下已被验证的模式9.1 pytest 配置与 conftest命令中的[tool.pytest.ini_options]只设置了testpaths与asyncio_mode。基于 python-testing-patterns 技能 与 advanced-patterns 参考生成的骨架还应在tests/conftest.py中沉淀共享 fixture并为测试补充作用域scope管理pytest.fixture(scopesession)用于整个会话只创建一次的重资源如应用配置scopemodule用于模块级共享scopefunction是默认的最小隔离粒度autouseTrue可声明每个测试都自动执行的前置/清理逻辑参数化测试pytest.mark.parametrize用表格驱动覆盖边界输入pytest.param(..., idpositive)可为用例命名async 测试借助pytest-asyncio与asyncio_mode autoasync def test_fetch_data()可直接await异步 fixture 同样受支持monkeypatch 与 tmp_pathmonkeypatch.setenv覆盖环境变量如切换DATABASE_URLtmp_path提供每个测试独立的一次性临时目录数据库测试用sqlite:///:memory:内存库 函数级 fixture 重建 schema并通过pytest.raises(IntegrityError)验证唯一约束等错误路径覆盖配置可在[tool.pytest.ini_options]的addopts中加入--covmyapp --cov-reportterm-missing配合[tool.coverage.run]的omit [*/tests/*, */migrations/*]统计真实覆盖率。9.2 类型安全配置命令的库模板在 dev 依赖中引入了mypy1.8.0。要兑现type-safe承诺python-type-safety 技能 给出的 strict 模式清单值得直接写入脚手架# pyproject.toml [tool.mypy] python_version 3.12 strict true warn_return_any true warn_unused_ignores true disallow_untyped_defs true disallow_incomplete_defs true no_implicit_optional true同时可遵循「增量落地」路线全部函数参数与返回类型注解、类属性注解、泛型集合使用类型参数list[str]而非裸list并尽量减少Any。对于既有代码库可用# mypy: strict注释或[[tool.mypy.overrides]]按模块开启严格检查如对tests.*放宽disallow_untyped_defs。此外该技能还提供了适用于业务骨架的进阶类型模式TypeVar(boundBaseModel)约束泛型、Protocol实现结构化子类型、TypeAlias定义语义化别名注意type X ...语法需 Python 3.123.10/3.11 请用TypeAlias。9.3 代码风格与格式化python-code-style 技能 给出了与命令配置互补的规范模块与文件命名用snake_case且拒绝缩写user_repository.py而非usr_repo.py类名PascalCase、函数与变量snake_case、模块级常量SCREAMING_SNAKE_CASE导入按「标准库 → 第三方 → 本地」三段分组且一律使用绝对导入公共函数/类采用 Google 风格 docstring含 Args/Returns/Raises/Example 段。[tool.ruff.format]还可显式声明quote-style double等格式偏好。十、输出格式脚手架交付的六项标准产物命令最后以「Output Format」明确规定了 Agent 交付物清单这也是评估脚手架完整度的验收标准Project Structure完整目录树包含所有必要文件Configuration带依赖与工具配置的pyproject.tomlEntry Point主应用文件main.py、cli.py等Tests带 pytest 配置的测试结构Documentation含安装与使用说明的README.mdDevelopment ToolsMakefile、.env.example、.gitignore。六项产物可分别对应本仓库插件的验证材料目录树对应 python-project-structure、依赖配置对应 uv-package-manager、测试结构对应 python-testing-patterns、README 写作规范对应 python-code-style 的 Project Documentation 一节。十一、进阶uv 锁文件、CI 与容器化工作流命令主流程以uv sync作为安装入口但生成的pyproject.toml项目若要与 CI/CD、Docker 衔接uv-package-manager 的高级参考 提供了脚手架之外的关键补充——这些工作流可以直接配套在生成项目中使用锁文件驱动可复现构建uv lock生成uv.lockCI 中一律用uv sync --frozen跳过解析、严格按锁文件安装uv lock --upgrade-package requests定向升级单个包uv export --format requirements-txt --hash可导出带哈希的requirements.txt供无 uv 环境使用。CI 流水线GitHub Actions 示例- uses: astral-sh/setup-uvv2 with: enable-cache: true - run: uv python install 3.12 - run: uv sync --all-extras --dev - run: uv run pytest - run: uv run ruff check .Docker 多阶段构建builder 阶段COPY pyproject.toml uv.lock ./RUN uv sync --frozen --no-dev --no-editableruntime 阶段仅复制.venv利用 uv 全局缓存显著加速镜像构建。Monorepo根pyproject.toml声明[tool.uv.workspace] members [packages/*]各子包通过uv add --path ./packages/package-a相互引用。这些内容虽然超出python-scaffold命令正文但正是把脚手架生成的骨架推进到可交付生产的最后一公里与本命令production-ready的定位一脉相承。结语python-scaffold命令的价值在于把「项目初始化」从重复劳动升维为可复现的工程规范先按需求识别项目类型再以 uv 统一初始化与环境管理随后按 FastAPI/Django/Library/CLI 四类模板输出目录结构、依赖配置、入口文件与测试骨架最后以.env.example Makefile 六项验收清单收尾。结合本仓库 python-development 插件下项目结构、类型安全、配置管理、测试模式与代码风格等多套技能的佐证这套方法论既适合 Agent 自动执行也完全可以由开发者手工复制为团队内部的脚手架标准值得作为新项目的第一份提交。【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考