人工智能AI Agent自主智能体代码智能体桌面应用前端开发工具【免费下载链接】AperantAutonomous 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 │ │ │ └───────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘整个发布流程分为“人肉步骤”13与“机器步骤”45两段维护者只负责把版本提升提交合并进 main剩下的打 tag、构建、发布、更新 README 全部交给 CI。二、语义化版本号Semantic Versioning项目遵循 Semantic Versioning 的三段式规则这也是版本比较与自动打 tag 的基础MAJORX.0.0破坏性变更、不兼容的 API 变更MINOR0.X.0新功能向后兼容PATCH0.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三种提升分别产出X1.0.0、X.Y1.0、X.Y.Z1而直接传入具体版本号含预发布后缀则会被原样采用并做格式校验。此外 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.jsonapps/desktop/package.json 与根目录 package.json版本字段被写为同一值检查 CHANGELOG.md 是否已有新版本条目仅有 warn 提醒不会阻止提交创建提交消息固定为chore: bump version to X.Y.Zgit 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 到 mainGitHub UI 或 gh CLI 均可 gh pr create --base main --title Release v2.8.0Step 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 Intelx64——代码签名 公证notarizedmacOS Apple Siliconarm64——代码签名 公证notarizedWindowsNSIS 安装器——代码签名Azure Trusted SigningLinuxAppImage .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手动触发可传forcetrue强制发布。核心步骤从源码 .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_releasetrueCHANGELOG 硬校验用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-intelmacos-15-intel原生编译 x64 应用npm run package:mac -- --x64异步提交 Apple 公证build-macos-arm64macos-15原生编译 arm64 应用npm run package:mac -- --arm64异步提交 Apple 公证build-windowswindows-latestnpm run package:win关闭 electron-builder 内置签名改用 Azure Trusted SigningOIDC签名 .exe并用Get-AuthenticodeSignature验证签名、重算latest.yml中的 SHA512 base64 校验和build-linuxubuntu-latestnpm run package:linux安装 Flatpak 工具链产物含 AppImage/.deb/.flatpak并执行npm run verify:linux验证finalize-notarizationmacos-latest等待两个 macOS 构建的公证结果并 staple装订产出已公证的 DMGcreate-releaseubuntu-latest汇总所有平台的二进制与latest.yml/latest-mac.yml/latest-linux.yml更新清单校验清单齐全缺失会导致自动更新失效而报错生成checksums.sha256用softprops/action-gh-release创建 Releasetag 含beta/alpha时自动标记为 prereleaseupdate-readmeubuntu-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、创建 tagrelease.yml推送v*tag构建二进制、提取 changelog、创建 Releaseupdate-readmerelease.yml 内Release 创建成功后用新版本更新 READMEbeta-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。八、故障排查手册合并后发布未触发检查包版本是否大于最新 taggit tag -l v* --sort-version:refname | head -1 cat apps/desktop/package.json | grep version确认合并提交确实改动了package.jsongit 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 FAILEDprepare-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 maintag 已创建但构建失败构建失败时 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与 staplingWindows 二进制通过 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都是可直接对照的完整参考。赞分享人工智能AI Agent自主智能体代码智能体桌面应用前端开发工具【免费下载链接】AperantAutonomous multi-session AI coding项目地址https://gitcode.com/gh_mirrors/au/Aperant点击查看免费下载相关推荐Monty 发布流程实战指南从版本号提升到多平台自动化发布的完整工程实践Monty 发布流程实战指南从版本号提升到多平台自动化发布的完整工程实践 本指南以仓库根目录下的 RELEASING.md https://link.gitc语言运行时编程语言Agent 沙箱人工智能fd 发布工程全流程解析从版本号升级到多平台产物发布的 Release Checklistfd 发布工程全流程解析从版本号升级到多平台产物发布的 Release Checklist 本文以 fdA simple, fast and user frCLI开发工具Claude Code Usage Monitor 发布流程指南从版本号到 PyPI 的全自动化发布实战Claude Code Usage Monitor 发布流程指南从版本号到 PyPI 的全自动化发布实战 本指南以仓库根目录的 RELEASE.md httpAI 应用CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考