
cookiecutter-uv-core:带 AI 代理开发流程与质量门禁的 uv 模板
来源标题:Show HN: Cookiecutter-uv-core – uv template with an agent SDLC and quality gates
cookiecutter-uv-core 是一个用 uv 管理 Python 服务的 Cookiecutter 模板,内置 Claude Code 和 OpenAI Codex 编码代理的指令与技能。生成的 src 布局项目包含 Pydantic 分层配置、structlog 结构化日志、异步 SQLAlchemy 访问 PostgreSQL、Click 命令行接口和多平台 Docker 镜像。Makefile 负责依赖管理、容器化、代码质量检查和测试,生成项目只需 uv 即可运行。
以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。
cookiecutter-uv-core 是一个 Cookiecutter 模板,用于管理基于 uv 的 Python 服务。它会在 src 布局中生成一个带类型注解的包,并包含:通过 Pydantic 实现分层配置、通过 structlog 实现结构化日志、异步 SQLAlchemy 访问 PostgreSQL、Click 命令行界面,以及多平台 Docker 镜像。Makefile 负责驱动依赖管理、容器化、代码质量检查和测试。生成的项目还附带面向 Claude Code 和 OpenAI Codex 编码 agent 的说明与技能。
生成项目只需要 uv,由它来运行 Cookiecutter。使用生成的项目则需要以下工具:
ripgrep 是可选的。如果已安装,Makefile 会使用它,例如通过 cargo install ripgrep 安装。
make install 会将以下工具安装为项目的开发依赖:
在生成的项目中运行以下目标,以检查工具并查看当前生效的配置:
通过 uvx 运行 Cookiecutter——uvx 是 uv 的工具运行器,首次使用时会将其安装到隔离环境中。从本仓库的本地克隆运行:
uvx cookiecutter --output-dir </path/to/dir> --overwrite-if-exists .
其中的 . 表示当前目录中的模板。Cookiecutter 会在 --output-dir 指定的目录内创建项目,-o 是该选项的短形式。--overwrite-if-exists 允许生成到此前运行已创建的项目目录中。
若要从 GitHub 仓库生成,请将 . 替换为形如 gh:<owner>/<repo> 的引用:
uvx cookiecutter -o </path/to/dir> gh:alexkey/cookiecutter-uv-core
VERSION 文件保存模板版本,Changelog 记录每个版本的变更。每个版本都有形如 v<version> 的 Git 标签。要从特定版本生成,请将其标签传给 --checkout:
uvx cookiecutter -o </path/to/dir> --checkout v0.9.0 gh:alexkey/cookiecutter-uv-core
Cookiecutter 会提示输入以下值,并显示每个值的默认值。按 Enter 接受默认值:
Cookiecutter 会根据上面的输入推导出以下值,并同样提示输入。除非项目需要其他值,否则接受推导出的默认值:
若只想用默认值生成示例项目,请传入 --no-input:
uvx cookiecutter -o </path/to/dir> --no-input .
该命令会创建示例项目 foobar_baz,可用于检查和实验。uvx cookiecutter --help 会列出所有 Cookiecutter 选项。
进入生成项目的目录,然后继续阅读“典型会话”。Features 列出了 Makefile 的各目标。
以下步骤将示例项目 foobar_baz 从环境搭建带到运行中的服务。
初始化 Git 工作树、锁定依赖、创建虚拟环境并安装项目:
cd foobar_baz
git init
make requirements
make venv
make install
make 目标不需要激活环境。在项目环境中运行其他命令时,请加上 uv run 前缀,例如 uv run foobar-baz --help。
或者,项目的 venv 辅助脚本会在当前 shell 中激活环境:
. ./venv
检查格式、运行分析工具并运行单元测试:
make check-format
make lint
make test
构建镜像并用 Compose 启动服务栈:
make docker-build
make docker-compose
make docker-compose 在前台运行,退出时会移除整个栈(包括卷)。栈运行期间,请在第二个 shell 中运行其余命令。
将数据库 URL 指向 Compose 在 localhost 上发布的 PostgreSQL 端口。为当前 shell 导出它:
export FOOBAR_DATABASE_URL="postgresql+asyncpg://database:database@localhost:5432/database"
或者,在项目的 .env.local 文件中设置相同的值,配置加载器默认会读取该文件。
针对运行中的数据库运行系统测试:
make autotest
启动服务,它会在启动时记录解析后的配置:
uv run foobar-baz run
2026-06-28 16:50:46 [debug ] Settings(LOG_LEVEL='DEBUG', LOG_FORMAT='console', LOG_COLORS=True, LOG_VERBOSE=True, DATABASE_URL=SecretStr('**********')) [foobar_baz.app.cli._decorators] filename=_decorators.py func_name=wrapper lineno=57 process=76586 thread=140704445131008
2026-06-28 16:50:46 [info ] Welcome to foobar-baz version 0.1.0 [foobar_baz.app.cli._decorators] filename=_decorators.py func_name=wrapper lineno=59 process=76586 thread=140704445131008
...
更新依赖
先查看当前状态:
make requirements-check
make requirements-try
make requirements-check 列出已安装的包并标记过时的包(包括传递依赖)。make requirements-try 列出过时的直接依赖,并预览约束允许的升级,而不写入 lockfile。
提高过时直接依赖的约束,然后锁定并安装升级:
make requirements-bump
make requirements-up
make requirements-bump 只重写 pyproject.toml。它把 ~= 和 >= 子句提升到最新版本,并保留每个依赖项的其余部分原样不变。对于其他子句会排除最新版本的依赖项,它会报告该依赖项并保持其不变。请先锁定 pyproject.toml 中任何待处理的变更,因为过时版本来自 lockfile。
make requirements-up 会重新解析每个包(包括传递依赖)到约束允许的最新版本,然后安装它们。若只想升级已提升的依赖并保留其他锁定版本,请改为运行 make requirements 和 make install。
确认结果,然后针对升级后的包运行检查和测试:
make requirements-check
make lint
make test
更改 Python 和 uv 版本
python_version 和 uv_version 提示会设置新项目的 CPython 和 uv 版本,cookiecutter.json 保存它们的默认值。生成的项目会在多个文件中固定每个版本,且各固定点互不跟随。更改 a 的每个固定点
(原文较长,此处译出前 6000 字,完整内容请点「打开原文」。)
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。