用途：指导 hermes-hookdeck 插件维护者将新版本发布到 PyPI。人工步骤见 README.md 的 Releasing 一节（在 GitHub UI 操作），本技能补充自动化机制、必须先通过的门禁，以及草拟发布说明的研究流程。
核心机制：仓库中没有任何地方声明版本号，setuptools-scm 在构建时从 git 标签推导版本并写入 wheel 内的 hookdeck/_version.py，因此 hookdeck.version 与 PyPI 版本始终一致。版本号在创建 release 时确定，不需要提前改文件或 bump。PyPI 是只追加的，已发布的版本号无法重用或替换，即使 yank 也不行。源码检出在两次发布之间会显示类似 0.1.2.dev4+g1a2b3c4 的开发版本，属正常现象。
触发与流程：发布 GitHub Release 触发 .github/workflows/release.yml（on release: [published]），没有单独审批环节，发布 release 即决定发版。仅推送标签不会触发。build 阶段以完整历史检出标签，运行 ruff 与全部测试，构建 wheel 和 sdist 并跑 twine check；publish 阶段通过 Trusted Publishing（OIDC，无存储 token）上传 PyPI；attach-artifacts 把 wheel 与 sdist 附到 release 上。build 失败则什么都没发布，需修好 main 后重新发布；publish 失败可在 Actions 页用 gh run rerun <id> --failed 重跑，不要为同一版本再建 release。
发布前检查：确认待发布内容已合并到 main；用 git tag --sort=-v:refname | head -1 确认 PREV_TAG 并商定 NEW_TAG；用 git log PREV_TAG..origin/main 阅读完整提交信息；按 SemVer 校验最小升级幅度；确认 main 顶端 CI 全绿；草拟发布说明；经维护者批准标签名与说明后再发布。用 gh release create "vM.m.p" --repo hookdeck/hermes-hookdeck --target main --title "vM.m.p" --notes-file "$NOTES_FILE" 创建；rc/a/b 版本加 --prerelease。
SemVer 判断：破坏现有安装为 MAJOR，新增向后兼容能力为 MINOR，修复为 PATCH。hookdeck/ 下的改动（含内置 skill、plugin.yaml、dashboard bundle）会随 wheel 发布，属 patch 发布；docs/、README.md、AGENTS.md、tests/、根目录 skills/、.github/ 不打包，仅含这些的 release 没有可安装内容。可用 git diff --stat PREV_TAG..origin/main -- hookdeck/ 判断。
发布后验证：pip download --no-deps -d /tmp/verify hermes-hookdeck==M.m.p，并在干净 venv 中确认改动确实进入产物。发布说明面向运行网关的使用者，先说需要采取行动的事项，结尾附上 compare 链接。
限制与风险：标签即版本，输错标签会以错误版本号真实发布且永久占用该号；不要在 main 不绿时发布；测试通过不等于集成正确，本仓库测试针对自有 stub，交付路径相关的发布应说明实际验证层级。