技能介绍

解决什么问题

Python 包发到 PyPI 表面看只是 twine upload，真正卡住的往往是前置问题：pyproject.toml 缺字段、readme 没写 content-type 导致 README 不渲染、wheel 用 packages = ["."] 把 scripts/、tests/ 甚至本地诊断脚本一起打进去，或者版本号写成 v2.0.0 被 PyPI 拒绝。包名冲突、TestPyPI 未先验证、token 被写进 shell history，也都是发布现场常见的翻车点。

技能如何工作

该技能按发布流水线组织，而不是只给一条上传命令：

收集发布信息：确认包名、语义化版本、PyPI API Token，以及账号是否已注册；token 缺失时引导到 PyPI 后台生成，首次发新项目建议使用 Entire account scope，后续再收紧到项目级。
校验 pyproject.toml：重点检查 [project].name、version、readme、license、requires-python、dependencies、build-system 等字段，并提醒常见错误，例如 readme 缺 text/markdown、license 缺失、版本号带 v 前缀。
检查包名与构建产物：先判断包名是否已被占用；再清理旧产物并用 build 构建，要求输出 .tar.gz 与 .whl；随后用 twine check 校验元数据，必须全部 PASSED。
检查 sdist / wheel 内容：确认主模块、METADATA、entry_points.txt、LICENSE 存在，同时避免 .env、__pycache__、.git、测试数据和含 token 的字符串进入包。
安全上传并验证：通过环境变量传 token，用户名固定为 __token__，使用 --non-interactive 上传；等待 CDN 同步后验证安装，并同步 Git tag；需要时先走 TestPyPI 验证，再上正式 PyPI。

适用边界与注意点

它适合标准 pyproject.toml + hatchling 的 Python 库或应用包发布流程；不负责长期包治理、自动升级版本号，也不保证绕过 PyPI 的不可变性。同一版本号不能重复上传，metadata 出错时通常必须升版本；旧版本无法删除，只能 yank。token 不要放进命令行或仓库，上传后建议删除或缩小 scope。