Aperant（Auto Claude）自动化发布流程实战指南：从版本号提升到多平台产物发布的完整流水线-平芜编程栈

人工智能
AI Agent
自主智能体
代码智能体
桌面应用
前端
开发工具

【免费下载链接】Aperant

Autonomous multi-session AI coding

项目地址：https://gitcode.com/gh_mirrors/au/Aperant

本指南以仓库根目录 RELEASE.md 为骨架，系统讲解 Aperant（项目内代号 Auto Claude，即桌面端 apps/desktop 所构建的自主多会话 AI 编程应用）的整套自动化发布机制：如何在 develop 分支上执行版本号提升、如何维护被流水线强校验的 CHANGELOG、如何在合并到 main 后由 GitHub Actions 自动完成打 tag、跨平台构建、病毒扫描、创建 GitHub Release 与 README 同步。读完你将掌握从“改版本号”到“发布成功”的完整操作路径，并能独立排查“发布未触发”“CHANGELOG 校验失败”“构建失败”等高频问题。

一、发布流程总览：为什么发布是“自动化”且“强校验”的

Aperant 的发布管线设计目标非常明确：只有所有平台的构建都成功之后，才允许发布真正发生。这样可以彻底避免“文档/README 显示的版本与实际上不存在的发布”之间的错位——版本号先在代码里提升，但 README 只有在构建成功、Release 真正创建后才被更新。

整条链路以develop分支为起点、main分支为汇合点、GitHub Actions 为执行引擎，流程图如下（保留自 RELEASE.md）：

┌─────────────────────────────────────────────────────────────────────────────┐ │ RELEASE FLOW │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ develop branch main branch │ │ ────────────── ─────────── │ │ │ │ │ │ │ 1. bump-version.js │ │ │ │ (creates commit) │ │ │ │ │ │ │ ▼ │ │ │ ┌─────────┐ │ │ │ │ v2.8.0 │ 2. Create PR │ │ │ │ commit │ ────────────────────► │ │ │ └─────────┘ │ │ │ │ │ │ 3. Merge PR ▼ │ │ ┌──────────┐ │ │ │ v2.8.0 │ │ │ │ on main │ │ │ └────┬─────┘ │ │ │ │ │ ┌───────────────────┴───────────────────┐ │ │ │ GitHub Actions (automatic) │ │ │ ├───────────────────────────────────────┤ │ │ │ 4. prepare-release.yml │ │ │ │ - Detects version > latest tag │ │ │ │ - Creates tag v2.8.0 │ │ │ │ │ │ │ │ 5. release.yml (triggered by tag) │ │ │ │ - Builds macOS (Intel + ARM) │ │ │ │ - Builds Windows │ │ │ │ - Builds Linux │ │ │ │ - Generates changelog │ │ │ │ - Creates GitHub release │ │ │ │ - Updates README │ │ │ └───────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘

整个发布流程分为“人肉步骤”（1～3）与“机器步骤”（4～5）两段：维护者只负责把版本提升提交合并进 main，剩下的打 tag、构建、发布、更新 README 全部交给 CI。

二、语义化版本号（Semantic Versioning）

项目遵循 Semantic Versioning 的三段式规则，这也是版本比较与自动打 tag 的基础：

MAJOR（X.0.0）：破坏性变更、不兼容的 API 变更；
MINOR（0.X.0）：新功能，向后兼容；
PATCH（0.0.X）：缺陷修复，向后兼容。

值得注意的是，项目还支持预发布版本后缀（如2.7.6-beta.1、2.8.0-alpha.1）。从 scripts/bump-version.js 的parseVersion与bumpVersion实现可以看到，版本号解析采用正则/^(\d+)\.(\d+)\.(\d+)(-[a-zA-Z0-9.]+)?$/，major/minor/patch三种提升分别产出X+1.0.0、X.Y+1.0、X.Y.Z+1，而直接传入具体版本号（含预发布后缀）则会被原样采用并做格式校验。此外 scripts/update-readme.mjs 也内置了同样的 semver 校验模式/^\d+\.\d+\.\d+(-[a-zA-Z]+\.\d+)?$/，用于 README 版本徽章与下载链接的更新。

三、维护者操作指南：创建一次发布

Step 1：提升版本号

在开发分支（通常是develop或功能分支）上执行版本号提升脚本。命令位于仓库根目录下的 scripts/bump-version.js，共有四种用法：

# 进入项目根目录 cd /path/to/auto-claude # 提升版本（四选一） node scripts/bump-version.js patch # 2.7.1 -> 2.7.2（缺陷修复） node scripts/bump-version.js minor # 2.7.1 -> 2.8.0（新功能） node scripts/bump-version.js major # 2.7.1 -> 3.0.0（破坏性变更） node scripts/bump-version.js 2.8.0 # 直接指定具体版本（含预发布如 2.7.6-beta.1）

从 scripts/bump-version.js 的实现看，脚本会依次完成：

检查 git 工作区是否干净（git status --porcelain，有未提交改动直接报错退出）；
读取当前版本：以 apps/desktop/package.json 中的version字段为准；
计算新版本并拒绝“新版本等于当前版本”的无意义操作；
预校验发布安全：调用node scripts/validate-release.js v<新版本>，防止分支/tag 命名冲突（详见第七节）；
同步更新两处package.json：apps/desktop/package.json 与根目录 package.json，版本字段被写为同一值；
检查 CHANGELOG.md 是否已有新版本条目（仅有 warn 提醒，不会阻止提交）；
创建提交，消息固定为chore: bump version to X.Y.Z（git add apps/desktop/package.json package.json后提交）。

关键设计：README 在此阶段不会被更新——注释明确说明 README 由发布流水线在 GitHub Release 成功发布后自动更新，避免 README 展示一个尚不存在的版本号；同样地，tag 也绝不在此阶段创建，而是由 GitHub Actions 在合并到 main 后自动创建，确保发布只会发生在构建成功之后。

Step 2：更新 CHANGELOG.md（必做项）

重要：如果 CHANGELOG.md 没有新版本的条目，发布将会失败。

在 CHANGELOG.md 文件顶部追加如下格式的发布说明：

## 2.8.0 - Your Release Title ### ✨ New Features - Feature description ### 🛠️ Improvements - Improvement description ### 🐛 Bug Fixes - Fix description ---

然后将改动并入版本提升提交：

git add CHANGELOG.md git commit --amend --no-edit

之所以必须“amend 进同一个提交”，是因为 prepare-release.yml 的触发条件是推送到main且paths命中apps/desktop/package.json或package.json——把 changelog 与版本号放进同一提交，可以保证流水线校验 changelog 时两者同时存在。

Step 3：推送并创建 PR

# 推送你的分支 git push origin your-branch # 创建 PR 到 main（GitHub UI 或 gh CLI 均可） gh pr create --base main --title "Release v2.8.0"

Step 4：合并到 main，让 CI 接管

PR 审批通过并合并到main后，GitHub Actions 会自动执行以下 9 个环节（详见 .github/workflows/prepare-release.yml 与 .github/workflows/release.yml）：

检测版本提升（prepare-release.yml）：比较apps/desktop/package.json中的版本与最新v*tag；
校验 CHANGELOG.md：为新版本必须有条目，缺失则直接失败；
提取发布说明：从 CHANGELOG.md 抽取对应版本段落；
创建 git tag（如v2.8.0）并推送，从而触发release.yml；
触发发布流水线（release.yml）；
为全平台构建二进制产物：
- macOS Intel（x64）——代码签名 + 公证（notarized）；
- macOS Apple Silicon（arm64）——代码签名 + 公证（notarized）；
- Windows（NSIS 安装器）——代码签名（Azure Trusted Signing）；
- Linux（AppImage + .deb + .flatpak）；
使用 VirusTotal 扫描二进制文件；
创建 GitHub Release，发布说明取自 CHANGELOG.md；
更新 README：刷新版本徽章与下载链接。

Step 5：发布后验证

合并后请确认三项状态：

GitHub Actions 工作流全部通过；
Releases 页面确认发布已创建；
README 确认版本号已更新。

四、流水线内部原理：prepare-release 与 release 的分工

prepare-release.yml：版本判定 + CHANGELOG 硬校验 + 打 tag

该工作流的触发条件是推送到 main 且变更了package.json，同时支持workflow_dispatch手动触发（可传force=true强制发布）。核心步骤从源码 .github/workflows/prepare-release.yml 可见：

PAT_TOKEN 前置校验：若secrets.PAT_TOKEN未配置会立刻exit 1。这里刻意使用 PAT 而非默认的GITHUB_TOKEN，因为 GitHub 出于安全考虑，用GITHUB_TOKEN推送的 tag 不会触发其它工作流，只有 PAT 才能让 tag 推送自动唤醒release.yml；
版本比较：读取包版本与最新 tag，用npx -y semver做语义化比较（能正确处理2.7.3 > 2.7.3-beta.1这类预发布排序），只有“包版本 > 最新 tag”时才置should_release=true；
CHANGELOG 硬校验：用awk定位## X.Y.Z头部并截取到下一个##或---为止，若找不到条目则以醒目的CHANGELOG VALIDATION FAILED报错并退出（同时在$GITHUB_STEP_SUMMARY中给出修复指引）；
上传 changelog 产物：把提取出的发布说明存为changelog-extract.mdartifact（保留 1 天），供release.yml复用；
创建并推送 tag：校验通过后用github-actions[bot]身份git tag -a vX.Y.Z && git push origin vX.Y.Z，随即触发发布流水线。

release.yml：按 tag 构建全平台产物并发布

该工作流由v*形式的 tag 推送触发，同样支持dry_run手动参数（只构建不发布）。从 .github/workflows/release.yml 可以看出它的任务拓扑：

Job	运行环境	职责
`build-macos-intel`	`macos-15-intel`	原生编译 x64 应用，`npm run package:mac -- --x64`，异步提交 Apple 公证
`build-macos-arm64`	`macos-15`	原生编译 arm64 应用，`npm run package:mac -- --arm64`，异步提交 Apple 公证
`build-windows`	`windows-latest`	`npm run package:win`，关闭 electron-builder 内置签名，改用 Azure Trusted Signing（OIDC）签名 .exe，并用`Get-AuthenticodeSignature`验证签名、重算`latest.yml`中的 SHA512 base64 校验和
`build-linux`	`ubuntu-latest`	`npm run package:linux`，安装 Flatpak 工具链，产物含 AppImage/.deb/.flatpak，并执行`npm run verify:linux`验证
`finalize-notarization`	`macos-latest`	等待两个 macOS 构建的公证结果并 staple（装订），产出已公证的 DMG
`create-release`	`ubuntu-latest`	汇总所有平台的二进制与`latest.yml`/`latest-mac.yml`/`latest-linux.yml`更新清单，校验清单齐全（缺失会导致自动更新失效而报错），生成`checksums.sha256`，用`softprops/action-gh-release`创建 Release（tag 含`beta`/`alpha`时自动标记为 prerelease）
`update-readme`	`ubuntu-latest`	仅在真实发布时运行，调用 scripts/update-readme.mjs 更新 README 徽章与下载链接，识别`-`预发布后缀走`--prerelease`分支，提交`docs: update README to vX.Y.Z [skip ci]`并推回 main

构建期间注入的SENTRY_DSN、SENTRY_TRACES_SAMPLE_RATE、SENTRY_PROFILES_SAMPLE_RATE等环境变量用于桌面端错误监控（sentry 采集）的初始化；macOS 侧依赖MAC_CERTIFICATE、APPLE_ID、APPLE_APP_SPECIFIC_PASSWORD、APPLE_TEAM_ID等 secrets 完成签名与公证。

五、CHANGELOG 管理规范

发布说明统一维护在 CHANGELOG.md 中，并作为 GitHub Release 的正文来源。

Changelog 格式

每个版本条目必须遵循固定结构，且版本头部以## X.Y.Z - Release Title开头（流水线按此定位版本段落）：

## X.Y.Z - Release Title ### ✨ New Features - Feature description with context ### 🛠️ Improvements - Improvement description ### 🐛 Bug Fixes - Fix description ---

Changelog 校验规则

发布流水线会对将要发布的版本执行强校验（在 prepare-release.yml 中实现）：

条目缺失→ 发布被阻断，并以清晰错误信息提示（CHANGELOG VALIDATION FAILED）；
条目存在→ 其内容被提取用作 GitHub Release 的发布说明。

bump-version.js本地也会做同样的事先检查：通过字符串前缀匹配查找## X.Y.Z头部（刻意避免对用户输入的版本串使用正则，防止注入风险），未命中时打印醒目的提示框，提醒维护者在创建 PR 前补齐 changelog。注意本地检查只是“警告”，真正强制失败的是合并后的 CI 校验。

写好发布说明的四个原则

具体化：不要写 “Fixed bug”，而要写 “Fixed crash when opening large files”；
按影响分组：功能（Features）优先，其次改进（Improvements），最后修复（Fixes）；
致谢贡献者：重大变更中提及贡献者；
关联 issue：在合适处引用 GitHub issue，例如Fixes #123。

六、工作流触发一览

工作流	触发条件	职责
`prepare-release.yml`	推送到`main`（且改动`package.json`）	检测版本提升、校验 CHANGELOG.md、创建 tag
`release.yml`	推送`v*`tag	构建二进制、提取 changelog、创建 Release
`update-readme`（release.yml 内）	Release 创建成功后	用新版本更新 README
`beta-release.yml`	手动触发（workflow_dispatch）	从`develop`分支创建 beta/alpha/rc 预发布 tag 并构建发布，支持`dry_run`

预发布版本的格式在 .github/workflows/beta-release.yml 中被正则严格限定为X.Y.Z-(beta|alpha|rc).N，例如2.8.0-beta.1，校验不合法会直接失败。

七、发布安全预检：validate-release.js

在bump-version.js提交前，会调用 scripts/validate-release.js 对目标版本做冲突预检，防止更新器因分支/tag 同名产生 HTTP 300 类错误：

tag 冲突：检查git tag -l中是否已存在同名 tag，存在则终止；
本地分支冲突：检查git branch中是否有同名本地分支；
远端分支冲突：检查git branch -r中是否有origin/<版本>或fork/<版本>同名分支（对远端检查失败仅警告，不阻断）。

全部通过后输出Version X.Y.Z is safe to release。

八、故障排查手册

合并后发布未触发

检查包版本是否大于最新 tag：

git tag -l 'v*' --sort=-version:refname | head -1 cat apps/desktop/package.json | grep version

确认合并提交确实改动了package.json：

git diff HEAD~1 --name-only | grep package.json

如果版本不高于最新 tag，流水线会输出 “No release needed (package version not newer than latest tag)” 并跳过；此时应重新用node scripts/bump-version.js <patch|minor|major>提升版本。

发布被阻断：缺少 changelog 条目

若工作流中看到CHANGELOG VALIDATION FAILED：

prepare-release.yml已校验确认 CHANGELOG.md 中没有新版本的条目；
修复方式：按## X.Y.Z - Title格式在 CHANGELOG.md 顶部补充条目；
提交并推送 changelog 更新；
推送后工作流会自动重试。

# 补充 changelog 条目后： git add CHANGELOG.md git commit -m "docs: add changelog for vX.Y.Z" git push origin main

tag 已创建但构建失败

构建失败时 Release不会被发布；
修复问题后创建一个新的 patch 版本；
切勿复用失败的版本号（tag 已存在，validate-release.js也会拦截）。

README 显示错误的版本

README只在发布成功后才更新；
如果发布失败，README 保持上一版本（这是刻意设计，保证 README 展示的始终是真实存在的最新版）；
一旦成功发布，README 会由update-readmejob 自动同步（提交信息docs: update README to vX.Y.Z [skip ci]，见 scripts/update-readme.mjs）。

九、紧急情况下的手动发布（仅限应急）

极少数需要绕过自动化流程的场景：

# 手动创建 tag（不推荐） git tag -a v2.8.0 -m "Release v2.8.0" git push origin v2.8.0 # 这会直接触发 release.yml

警告：只有当你确定package.json中的版本与 tag 完全一致时才可执行此操作；手动打 tag 会跳过 CHANGELOG 校验环节，容易造成发布说明缺失或版本错位。

十、发布物安全与完整性

为保证分发渠道的可信度，发布流水线对所有产物执行以下安全措施（见 .github/workflows/release.yml）：

所有 macOS 二进制使用 Apple Developer 证书代码签名，并经 Apple公证（notarize）与 stapling；
Windows 二进制通过 Azure Trusted Signing代码签名，签名后用Get-AuthenticodeSignature校验有效性，再重算latest.yml的 SHA512 校验和；
Linux 产物在构建后执行verify:linux验证步骤；
所有二进制均交由VirusTotal 扫描（另有独立工作流 .github/workflows/virustotal-scan.yml），扫描结果会在 Release 发布后追加；
为所有产物生成SHA256 校验和文件checksums.sha256，供用户下载后核验完整性。

结语

Aperant 的发布体系把“人工判断”压缩到了最小：维护者只需执行一次版本提升、补一份 changelog、合并一个 PR，之后 tag 创建、四平台构建、签名公证、病毒扫描、Release 发布与 README 同步全部由 GitHub Actions 按 prepare-release.yml → release.yml 的顺序自动完成。理解这套流程的关键在于把握三个“护栏”：CHANGELOG 硬校验保证发布说明不会缺失、构建成功才发版保证不会出现“文档先于产物”的版本错位、PAT 打 tag保证 tag 推送能正确触发后续流水线。无论你是维护者要发版，还是想复刻这套管线到自己的 Electron 项目，本文的脚本与工作流实现（scripts、.github/workflows）都是可直接对照的完整参考。