版本发布Skill：版本号管理与发布流程

一、版本发布Skill的设计

版本发布是软件开发中最关键的环节之一。一个成熟的版本发布Skill应当以标准化流程为目标，将人工操作降到最低，从而减少人为失误，确保每次发布的质量和一致性。设计这样的Skill时，首先需要梳理团队当前的发布流程，识别出所有可自动化的步骤，再将其封装成可复用的 Skill 指令。

一个完整的版本发布Skill通常涵盖以下核心阶段：版本号规划、变更记录整理、代码打 Tag、构建产物、发布到目标平台、发布后验证以及异常回滚。将这些环节串联成一个或一组 Skill 指令后，开发者只需执行一条命令即可完成完整发布流程，大幅提升效率。

版本发布Skill的设计目标包括：标准化发布流程，确保每次发布步骤一致；减少人为错误，避免漏掉关键步骤；确保每次发布质量，自动运行检查和测试；提高发布效率，一键完成多平台发布。

标准化发布流程

将发布步骤固化为技能指令，确保每次执行一致

减少人为错误

自动检查版本号一致性、Tag 冲突、变更记录完整性

确保发布质量

发布前自动运行测试套件和静态分析，拦截问题于发布前

提高发布效率

一条命令完成多平台同步发布，免去重复手动操作

二、语义化版本号管理

语义化版本号（Semantic Versioning，简称 SemVer）是版本发布的基础规范，格式为 MAJOR.MINOR.PATCH。MAJOR 版本在做出不兼容的 API 修改时递增；MINOR 版本在向下兼容的功能性新增时递增；PATCH 版本在向下兼容的问题修正时递增。版本发布Skill需要自动读取当前版本号，根据变更类型计算新版本号，并更新项目中的版本号文件。

读取当前版本号

Skill需要支持从多种来源读取当前版本号，包括 package.json、pyproject.toml、Cargo.toml、VERSION 文件或 Git Tag。可以通过正则表达式或 JSON/YAML 解析器提取版本号字符串。推荐将版本号集中管理在单一源文件中，避免多处维护导致不一致。

根据变更类型计算新版本号

发布时需要明确本次变更类型：major、minor 或 patch。Skill接收一个参数指定变更类型，然后根据当前版本号自动计算新版本号。例如，当前版本为 1.3.2，选择 minor 发布则新版本号为 1.4.0；选择 patch 发布则新版本号为 1.3.3。如果存在预发布版本号（如 1.0.0-alpha.1），Skill也应当能正确处理。

更新版本号文件

计算出新版本号后，Skill需要自动更新项目中所有记录了版本号的文件。常见的更新目标包括：package.json 中的 version 字段、pyproject.toml 中的 version 字段、Cargo.toml 中的 version 字段、VERSION 常量文件、Changelog 中的版本标题以及文档中的版本引用。更新完成后应验证所有文件中的版本号是否一致。

# 版本号计算示例
# 输入：当前版本 1.3.2，变更类型 minor
function bump_version() {
    local current=$1
    local type=$2
    local major=$(echo $current | cut -d'.' -f1)
    local minor=$(echo $current | cut -d'.' -f2)
    local patch=$(echo $current | cut -d'.' -f3)
    case $type in
        major) echo "$((major+1)).0.0" ;;
        minor) echo "${major}.$((minor+1)).0" ;;
        patch) echo "${major}.${minor}.$((patch+1))" ;;
    esac
}

最佳实践：在项目的 CI 配置中增加版本号一致性检查步骤，确保在合并 PR 时 package.json 和 Changelog 中的版本号保持同步，避免发布时才发现不一致问题。

三、Git Tag和分支管理

Git Tag 是版本发布的锚点，每个正式发布版本都应当有一个对应的 annotated tag，包含发布说明。版本发布Skill需要自动创建 annotated tag、创建 release 分支（如需要）、执行合并策略，并将 tag 推送到远程仓库。规范的 tag 和分支管理是团队协作的基础，也是后续回滚的依据。

创建Annotated Tag

Annotated Tag 与 Lightweight Tag 的区别在于前者包含了标签作者、日期和消息，适合作为正式发布的标记。Skill在创建 tag 时应自动生成 tag 消息，内容包含版本号和发布日期。tag 命名规范建议使用 v{MAJOR}.{MINOR}.{PATCH} 格式，例如 v1.4.0。

# 创建 annotated tag 并附带发布说明
git tag -a v1.4.0 -m "Release v1.4.0

- 新增用户权限管理功能
- 优化数据查询性能
- 修复登录页面样式问题"

# 推送 tag 到远程仓库
git push origin v1.4.0

创建Release分支

对于需要长期维护的版本，推荐创建 release 分支（如 release/v1.4.x）。Release 分支从 develop 分支创建，在 release 分支上进行最终的 Bug 修复和文档更新，完成后合并到 main 分支并打 tag。这种方式将发布准备工作与日常开发隔离，避免了未完成的功能被意外发布。

合并策略

发布完成后，Skill应当自动执行合并操作：将 release 分支合并回 main 分支（打 tag），再将 main 分支合并回 develop 分支（确保 develop 包含发布时的修复），或者采用 squash merge 保持提交历史整洁。推荐使用 --no-ff 方式合并，保留分支历史信息。

分支	用途	生命周期
main	生产就绪代码，每个提交对应一个发布版本	永久
develop	集成开发分支，包含下一个版本的功能	永久
release/*	发布准备分支，用于最终修复和文档更新	临时，发布后删除
feature/*	功能开发分支，从 develop 分出	临时，合并后删除
hotfix/*	紧急修复分支，从 main 分出	临时，修复后删除

注意：推送 tag 到远程仓库的操作不可逆。如果 tag 名称或内容有误，需要先删除本地 tag（git tag -d v1.4.0）再删除远程 tag（git push origin :refs/tags/v1.4.0），但这会破坏其他开发者已拉取的 tag。因此 tag 创建前应增加确认环节。

四、Release发布到各平台

现代软件往往需要发布到多个平台，包括 GitHub Release、npm 注册表、PyPI、Docker Registry 等。版本发布Skill需要支持多平台同时发布编排，确保所有平台上的发布包版本一致、内容同步。发布流程应当包含构建、签名、上传和验证四个阶段。

GitHub Release创建

GitHub Release 是开源项目最常用的发布形式。Skill通过 GitHub CLI 或 API 创建 Release，自动关联对应的 Git Tag，并从 CHANGELOG.md 或约定提交历史中提取 Release Notes。Release Notes 应包含本次发布的所有变更分类（Features、Bug Fixes、Breaking Changes 等），方便用户了解更新内容。

# 使用 gh CLI 创建 GitHub Release
gh release create v1.4.0 \
    --title "v1.4.0 - 用户权限管理" \
    --notes "## 新增功能

- 用户权限管理模块
- 数据导出支持 CSV/Excel

## Bug修复

- 修复登录页面样式问题
- 修复分页查询超时缺陷" \
    --target main \
    dist/*.zip

npm publish

对于 JavaScript/TypeScript 项目，Skill需要自动执行 npm publish。发布前应确保：构建产物已生成、版本号已更新、package.json 的 files 字段已配置、已执行 npm login（或配置了 NPM_TOKEN 环境变量）。建议在 CI 环境中使用自动化 token 进行发布，避免交互式登录。

PyPI publish

对于 Python 项目，发布到 PyPI 需要先构建 wheel 包（python -m build），然后使用 twine 上传（twine upload dist/*）。Skill应自动处理版本号同步、构建产物清理以及 PyPI 凭证管理。推荐在 CI 中使用 Trusted Publishing（OIDC）方式，无需管理 API Token。

Docker镜像构建和推送

对于容器化部署的项目，Skill需要自动构建 Docker 镜像并使用语义化版本号和 latest 标签进行推送。镜像标签策略建议采用多标签方式：v1.4.0（精确版本）、v1.4（次要版本，跟随补丁更新）和 latest（最新稳定版）。多标签策略让用户可以根据需要选择固定的版本或跟随最新更新。

# 多平台发布编排示例
function release_all() {
    local version=$1
    local notes=$2

    # 1. 构建产物
    npm run build

    # 2. 创建 GitHub Release
    gh release create "v${version}" \
        --title "v${version}" \
        --notes "${notes}" \
        dist/*.zip

    # 3. 发布到 npm
    npm publish

    # 4. 构建并推送 Docker 镜像
    docker build -t myapp:${version} .
    docker tag myapp:${version} myapp:latest
    docker push myapp:${version}
    docker push myapp:latest

    # 5. 验证发布
    verify_release ${version}
}

提示：多平台发布时如果某个平台发布失败，应当终止后续发布流程并回滚已成功的发布。使用幂等性设计可以简化回滚操作——重新执行发布命令即可覆盖已成功发布的版本。

五、发布后验证和回滚

发布完成不代表流程结束。版本发布Skill需要包含发布后自动验证环节，包括运行 smoke test、监控应用健康状态、检查关键指标。当发现问题时，Skill应能自动触发回滚流程，恢复到上一个稳定版本。完善的验证和回滚机制是生产环境发布的安全网。

Smoke Test

发布完成后立即运行一组轻量级的 smoke test，覆盖核心业务流程。Smoke test 应当快速（通常在几分钟内完成）、全面（覆盖主要功能路径）且可重复。技能可以调用现有的测试套件或专门的发布验证脚本。Smoke test 失败时应立即阻止流量切到新版本，并触发告警通知团队。

监控和健康检查

发布后的持续监控同样重要。Skill可以集成应用健康检查端点（如 /health 或 /readyz）、错误率监控（如 5xx 响应比例上升）、延迟监控（如 P99 延迟异常增长）以及业务指标监控（如订单量或注册量异常下降）。建议设置多个维度的监控阈值，避免单一指标误判。

回滚策略

当监控系统检测到异常时，回滚流程应当自动启动。回滚策略分为三种级别：快速回滚（切换负载均衡器流量到旧版本）、完整回滚（重新部署上一个稳定版本的 artifacts）以及数据库回滚（执行数据库迁移的回滚脚本）。版本发布Skill需要保留历史版本的构建产物和 Docker 镜像，确保在需要时能够快速回退。

核心要点总结：一个成熟的版本发布Skill应当覆盖从版本号规划到发布后验证的完整生命周期。核心关注点包括：语义化版本号自动管理、Git Tag 和分支规范化、多平台发布编排、发布后自动化验证以及快速回滚能力。将这些步骤固化为可重复执行的技能指令，能够显著提升发布效率和质量。

"版本发布不是终点，而是新版本的起点。好的发布流程应当让每次发布都无感、可靠、可追溯。"