企业官网建设流程全解析

Archon 发布流程指南：版本管理、跨平台二进制构建与 Homebrew 分发

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon

本篇指南面向 Archon 仓库的维护者与进阶开发者，完整讲解 Archon CLI 从版本号管理、dev分支合入main、打 tag 触发 GitHub Actions 构建，到发布二进制、生成校验和、更新 Homebrew formula 的全流程。读完后你将掌握：版本号单一来源原则、/release技能与手动发布两条路径、私有仓库下的gh安装方案，以及构建脚本与发布工作流（.github/workflows/release.yml）的底层实现细节。

版本管理：SemVer 与单一来源

Archon CLI 的版本号遵循 Semantic Versioning（语义化版本规范），三段式含义如下：

• Major（如 1.0.0）：CLI 接口或工作流格式发生破坏性变更；
• Minor（如 0.1.0）：新增功能、新工作流、新命令；
• Patch（如 0.0.1）：缺陷修复、文档更新。

版本的唯一事实来源（single source of truth）是仓库根目录的 package.json，"version"字段只有一个，例如当前仓库为0.10.1。这与 dev 模式下archon version的读取逻辑一致：在 packages/cli/src/commands/version.ts 中，非编译态（BUNDLED_IS_BINARY = false）时，CLI 会向上定位到根package.json读取版本（join(SCRIPT_DIR, '../../../../package.json')），而不是读取packages/cli自身的版本——这正是"根目录单一来源"在代码层面的落实。

仓库采用 Bun workspace 结构（workspaces: ["packages/*"]），各子包（@archon/core、@archon/cli、@archon/server等）的版本号也需要与根版本保持一致。发布技能在 bump 根版本后会调用 scripts/sync-versions.sh：该脚本遍历packages/*/package.json，用 Node 跨平台地（避免 sed 可移植性问题）把每个子包版本同步为根版本。

发布流程总览

发布的核心铁律：通过把dev合并进main来发布，绝不直接向main提交。整体链路为：

1. 在dev上准备发布（更新版本与 CHANGELOG）；
2. 从dev向main开 PR 并合并；
3. 在main上打 tag 并推送，触发 GitHub Actions 发布工作流；
4. （可选）更新 Homebrew formula；
5. 验证发布产物。

下面按步骤展开。

第一步：准备发布

建议优先使用/release技能（维护者日常命令），也可以完全手动执行。无论哪种方式，第一步都是确保dev分支最新并通过全量校验：

# Ensure dev is up to date git checkout dev git pull origin dev # Run full validation bun run validate

bun run validate并不是单个检查，而是仓库里一串门禁的串行执行。查看根 package.json 的"validate"脚本定义，它会依次运行：

• check:cli-import-boundary：检查 CLI 包依赖边界（scripts/check-cli-import-boundary.ts）；
• check:bundled、check:bundled-skill、check:bundled-schema：校验各种"捆绑生成物"与源码是否漂移（generate-*-ts --check模式）；
• check:pi-vendor-map、check:capability-matrix、check:api-types：厂商映射、能力矩阵与 API 类型一致性；
• type-check：全 workspace 的 TypeScript 类型检查；
• lint --max-warnings 0：零警告门槛的 lint；
• format:check：Prettier 格式检查；
• test:install：安装脚本冒烟测试（见下文）；
• test：全量测试套件（scripts/repo-tests.ts）。

/release技能在手动步骤之上自动化了四件事：

1. 对比dev与main，生成 changelog 条目；
2. 提升根 package.json 的版本号（默认 patch 级；/release minor或/release major可指定其他增量）；
3. 按 Keep a Changelog 格式更新 CHANGELOG.md（仓库的 changelog 已按该格式组织，含## [Unreleased]、### Breaking、### Changed、### Fixed等分组）；
4. 创建从dev到main的 PR。

提示：版本号提升后，务必同步运行bash scripts/sync-versions.sh（发布技能会自动处理），否则 workspace 子包版本会与根版本脱节。

第二步：合并与打 Tag

发布 PR 评审并合并后，切到main拉取最新代码，然后创建并推送 tag：

# Create and push the tag from main git checkout main git pull origin main git tag vX.Y.Z git push origin vX.Y.Z

推送v*格式的 tag 会触发 .github/workflows/release.yml 发布工作流，其产物为：

1. 为所有平台构建二进制（macOS arm64/x64、Linux arm64/x64、Windows x64）；
2. 生成 SHA-256 校验和（checksums.txt）；
3. 创建 GitHub Release，附带全部制品与安装说明。

发布工作流内部：从 Web 产物到二进制

实际的release.yml比文档描述的"构建 + 发布"多出几个关键环节，值得展开：

web-dist作业（先行）：先构建 Web UI（bun --filter @archon/web build），再打包成archon-web.tar.gz。打包使用确定性 tar 参数（--sort=name --owner=0 --group=0 --numeric-owner --mtime='@0'），保证从源码独立重建得到与发布产物字节一致、SHA-256 相同的 tarball。该压缩包会被嵌入每个平台的二进制，使 CLI 在离线时也能服务内置 Web 界面。

build作业（并行矩阵，依赖 web-dist）：5 个平台组合并行构建：

每个矩阵作业下载 web dist，通过环境变量VERSION、GIT_COMMIT、TARGET、OUTFILE调用 scripts/build-binaries.sh 的单目标（CI）模式。注意工作流会对workflow_dispatch与 tag push 两种触发方式分别取版本号（tag 用github.ref_name，手动触发用inputs.version），并剥离v前缀、截取 8 位短 commit SHA。

冒烟测试：Linux x64 作业还会对构建出的二进制做三层验证——version命令必须输出预期版本且报告Build: binary（证明BUNDLED_IS_BINARY已正确写入）；workflow list必须能加载捆绑工作流（证明内置 JSON 已嵌入）；Claude binary-path 解析器的正反用例（未设CLAUDE_BIN_PATH时给出明确报错，设置后能正常 spawn 子进程）。这些测试直接复用了 scripts/test-install.sh 里对安装脚本同样的"先验证、后报告成功"精神。

release作业（等待所有构建完成）：下载全部制品 → 用sha256sum archon-* > checksums.txt生成校验和 → 通过softprops/action-gh-release创建 Release，附件包含全部二进制、archon-web.tar.gz、checksums.txt，并自动生成发布说明；版本号含-（如v0.3.0-beta.1）时自动标记为 prerelease。

update-homebrew作业（依赖 release）：以dev分支检出，等待 30 秒让 Release 资产就绪后运行 scripts/update-homebrew.sh，自动提交更新后的 formula 到dev。

第三步：更新 Homebrew Formula（可选）

发布工作流完成（尤其是 CI 未自动处理时）可手动更新 Homebrew formula：

# Update checksums in the Homebrew formula ./scripts/update-homebrew.sh vX.Y.Z # Review and commit git diff homebrew/archon.rb git add homebrew/archon.rb git commit -m "chore: update Homebrew formula for vX.Y.Z" git push origin main

如果你维护自己的 Homebrew tap（homebrew-archon），把更新后的 formula 复制过去即可。

scripts/update-homebrew.sh 的实现相当严谨：它会先从 Release 下载checksums.txt，用awk提取四个平台的 SHA-256（darwin-arm64、darwin-x64、linux-arm64、linux-x64），逐项校验是否为 64 位十六进制，然后用sed更新 homebrew/archon.rb 中对应的sha256（同时兼容首次的PLACEHOLDER_*占位符和已存在的 64 位哈希两种形态）。formula 本身按on_macos/on_linux×on_arm/on_intel四个分支声明 URL 与校验和，安装时按当前平台选二进制重命名为archon，test块通过archon version校验版本输出。

第四步：验证发布

# Test the install script (only works if repo is public) curl -fsSL https://raw.githubusercontent.com/coleam00/Archon/main/scripts/install.sh | bash # Verify version archon version

curl | bash方式依赖 scripts/install.sh，要求仓库公开可匿名访问。该脚本会动态检测 OS 与 CPU 架构（含 Apple Silicon 上 Rosetta 转译的sysctl.proc_translated识别），选择正确的 Release 资产下载，下载后强制做 SHA-256 校验（可用SKIP_CHECKSUM=true显式跳过但会警告），并在覆盖既有安装前先执行一次version探针——确认新二进制可运行才替换旧文件，失败则保持原安装不变。此外对 x64 平台还会检查 CPU 是否支持 AVX2（不支持时拒绝下载，可用ARCHON_SKIP_CPU_CHECK=1强制放行）。archon version在编译二进制下直接读取构建时嵌入的版本与 commit（见 packages/paths/src/bundled-build.ts 与 packages/cli/src/commands/version.ts），输出形如：

Archon CLI v0.10.1 Platform: linux-x64 Build: binary Database: sqlite Git commit: abc12345

私有仓库安装

如果仓库是私有的，curl安装脚本对匿名用户不可用，改用 GitHub CLI：

# Download and install using gh (requires GitHub authentication) gh release download v0.2.0 --repo coleam00/Archon \ --pattern "archon-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/x64/;s/aarch64/arm64/')" \ --dir /tmp/archon-install # Install the binary chmod +x /tmp/archon-install/archon-* sudo mv /tmp/archon-install/archon-* /usr/local/bin/archon # Verify archon version

--pattern中的$(uname -s)/$(uname -m)组合动态拼出与 Release 资产一致的平台名（darwin/linux + x64/arm64），与 scripts/install.sh 的detect_platform逻辑同一套命名约定。

手动发布：GitHub Actions 不可用时

当 GitHub Actions 无法运行（计费问题、私有仓库额度限制等），可完全手动发布：

# 1. Build binaries locally (only builds for your current platform) ./scripts/build-binaries.sh # 2. Create the release with binaries gh release create vX.Y.Z dist/binaries/* \ --title "Archon CLI vX.Y.Z" \ --generate-notes # 3. Verify the release gh release view vX.Y.Z

需要强调的是：本地构建只会为当前平台生成二进制。scripts/build-binaries.sh 的无环境变量（本地）模式默认构建全部 4 个本机 target 到dist/binaries/，但由于单台机器只能交叉编译到当前 OS 的两种架构，Windows 二进制与其余平台仍需 GitHub Actions 或逐一在对应平台构建。跨平台二进制必须依赖 CI。

手动构建（仅测试）

不发布、只在本地验证构建产物时：

# Build all platform binaries ./scripts/build-binaries.sh # Binaries are in dist/binaries/ ls -la dist/binaries/ # Generate checksums ./scripts/checksums.sh

scripts/build-binaries.sh 的本地模式会执行以下关键步骤：

1. 重新生成捆绑默认值：先运行generate-bundled-defaults.ts，把.archon/{commands,workflows}/defaults/当前磁盘内容嵌入编译产物，保证二进制内置的最新工作流不漂移；
2. 重写构建时常量：把 packages/paths/src/bundled-build.ts 临时改写为BUNDLED_IS_BINARY = true、真实版本、短 commit 及archon-web.tar.gz的 SHA-256，然后注册 EXIT trap 在脚本退出时用git checkout恢复该文件——即使构建中途失败也不会污染工作树；
3. 逐平台编译：以bun build --compile --minify --target=<target>从 packages/cli/src/cli.ts 编译。脚本明确禁用了--bytecode（Bun 1.3.11 对当前模块图会产生损坏字节码），并校验输出文件存在且不小于 1MB（Bun 编译产物通常 50MB+），防止静默失败；
4. 嵌入 web dist 校验和策略：release/CI 构建时若拿不到合法的archon-web.tar.gzSHA-256 会直接拒绝构建（fail-closed），本地开发构建则降级为警告并回退远程拉取。

scripts/checksums.sh 则要求dist/binaries/下四个平台二进制全部存在（darwin-arm64、darwin-x64、linux-arm64、linux-x64），缺任何一个都会报错退出，最后用shasum -a 256 archon-*生成checksums.txt。这与 Release 工作流里sha256sum生成的文件格式一致，可被安装脚本与 Homebrew 更新脚本直接消费。

故障排查

构建在 GitHub Actions 上失败

查看 Actions 页签的具体报错，常见原因：

• 依赖安装失败：确认bun.lock已提交（CI 使用bun install --frozen-lockfile，锁文件缺失或与package.json不一致会直接失败）；
• 类型错误：先在本地运行bun run type-check再推送（validate脚本会跑全量类型检查）。

安装脚本失败

scripts/install.sh 的依赖要求：

• curl：用于下载二进制与校验和文件；
• sha256sum或shasum：用于校验和验证（两者都缺失时脚本报错，不支持跳过校验）；
• 对/usr/local/bin的写权限（脚本会自动尝试sudo，或用INSTALL_DIR环境变量指定自定义目录，例如INSTALL_DIR=~/.local/bin bash）。

另外注意VERSION=v0.2.0 curl ... | bash的写法是无效的：变量必须放在bash之前（curl ... | VERSION=v0.2.0 bash），否则环境变量只作用于curl进程，安装脚本会静默使用默认的 latest。

校验和不匹配

用户反馈校验失败时，按序排查：

1. 检查 Release 制品是否完整（四个平台二进制与checksums.txt是否齐全）；
2. 确认checksums.txt生成正确（可对照 scripts/checksums.sh 的格式）；
3. 确认二进制在生成校验和之后未被修改（上传/存储过程中的任何改动都会导致哈希变化）。

预发布版本

正式公告前需要测试版时，直接打预发布 tag：

# Create a pre-release tag git tag v0.3.0-beta.1 git push origin v0.3.0-beta.1

含-的 tag（如v0.3.0-beta.1）在 Release 工作流中会被 .github/workflows/release.yml 的prerelease: ${{ contains(steps.version.outputs.version, '-') }}自动标记为预发布（prerelease）。

Hotfix 流程

已发布版本出现紧急缺陷时的修复路径——基于 tag 拉分支、修复、打 tag、合回dev：

# Create hotfix branch from tag git checkout -b hotfix/0.2.1 v0.2.0 # Make fixes, then tag git tag v0.2.1 git push origin v0.2.1 # Merge fixes back to dev git checkout dev git merge hotfix/0.2.1 git push origin dev

推送v0.2.1tag 即触发同一套发布工作流，完成补丁版本的二进制构建与发布；修复随后合回dev，避免dev与最新发布脱节。

小结

Archon 的发布链路围绕"dev汇入main、tag 驱动构建"设计：版本号收敛在根 package.json 单一来源，scripts/build-binaries.sh 负责把版本、commit 与内置 Web 产物连同校验和一并编译进各平台二进制，.github/workflows/release.yml 完成并行构建、冒烟测试与 Release 生成，scripts/install.sh、homebrew/archon.rb 与 scripts/update-homebrew.sh 则打通了最终用户侧的安装分发。理解这条链路后，无论是日常 patch 发布、预发布测试，还是 CI 故障下的手动兜底，都能按同一套可复现的流程完成。

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon