Python 包发布工程师

你要解决的问题

在 Python 生态里，把一个模块变成可 pip install 的包并不是几行 setup.py 就能搞定的事。自 2020 年基于 setup.py 的安装方式被弃用以来，PEP 517/518/621/639 相继落地，构建后端、类型标记、许可证声明、版本管理全部搬进了 pyproject.toml。但官方文档是规范而非指南——开发者仍要面对一堆具体选择：src/ 还是 flat？setuptools 还是 hatchling？版本号写在 __init__.py 里还是交给 git tag？CI 里 OIDC 和 API token 哪个更安全？

这些决策并非孤立。目录布局影响导入路径，构建后端决定版本来源，CI 配置依赖发布治理策略。一步出错，轻则 pip install 失败，重则发布出去的包带错版本号或缺失类型信息。

这个技能做了什么

这个技能把上述选择压缩成了一套有明确决策规则的流程。

触发时机：当你需要脚手架一个新包、发布到 PyPI、配置 pyproject.toml / lint / mypy / pre-commit / GitHub Actions、理解 PEP 440 或 SemVer、使用 Trusted Publishing (OIDC) 时，就该加载它。

核心决策顺序：

1. 包类型判定——Utility、SDK、CLI、插件还是数据处理库？每种类型有对应的入口点模式和依赖建议。
2. 目录结构——新项目默认 src/ layout；1-4 个模块的小包可用 flat；多包仓库走 PEP 420 命名空间。
3. 构建后端——setuptools + setuptools_scm 适合 git-tag 发版；hatchling 面向纯 Python 新项目；flit 只适合单模块极简包；poetry 适合想要统一依赖管理的团队。
4. 版本策略——PEP 440 是规范基线，SemVer 是推荐实践，setuptools_scm 从 git tag 自动生成版本号。注意 CI 里 fetch-depth: 0 必须设，否则版本静默回退成 0.0.0+dev。

配套参考文件：9 篇 reference 分别覆盖 pyproject.toml 模板、库设计模式、测试与代码质量、CI/发布流水线、社区文档、架构模式、版本策略、发布治理、Ruff 工具链。另有 scripts/scaffold.py 一条命令生成完整目录骨架。

适用边界

• 适合新建或重构已有包到现代打包标准；不适合维护老式 setup.py-only 项目直到下一次大版本。
• 后端对比明确排除 C 扩展场景（hatchling/flit/poetry 均不支持），需要编译扩展时只能选 setuptools。
• 版本策略默认 git-tag 工作流；不用 git 的项目需要切到静态版本号。