Archon 发布版二进制冒烟测试实战指南从 brew / curl 安装到端到端验证【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon本篇指南系统讲解 Archon 开源项目中的test-release技能.claude/skills/test-release/SKILL.md它是一条面向已发布二进制的自动化冒烟测试流程覆盖brew、curl-mac、curl-vps三种安装路径每条路径都会安装真实发行版、执行固定冒烟测试套件并彻底清理现场。读完本文你将掌握如何在发版前用与 CI 完全一致的参数本地构建二进制做预发布 QA如何安全地在 macOS 与远程 Linux VPS 上对已发布版本执行版本、内置工作流、Claude SDK 通路、环境变量防泄漏门与隔离子系统五项冒烟测试以及如何在不扰动开发用bun link二进制的前提下完成卸载还原并输出结构化测试报告。适用前提本技能面向 Archon 已打 tag 的 release 产物验证。若尚无可测试的发布版本应先用 scripts/build-binaries.sh 本地构建并直接运行dist/binaries/下的产物若要验证开发态代码则应使用bun run validate或直接以bun packages/cli/src/cli.ts调用源码。技能定位与三种安装路径test-release是发版流程的验收侧技能它测试的是发布出去的二进制而不是开发中的源码。技能核心覆盖三条安装路径路径平台验证目标brewmacOSHomebrew tap 公式与校验和对应 homebrew/archon.rbcurl-macmacOScurl install.sh安装脚本沙箱到临时目录执行curl-vps远程 Linux VPSLinux 二进制与完整安装路径三条路径的共同原则是安装真实二进制 → 运行固定冒烟测试套件 → 清理卸载。全程绝不触碰开发用的bun link二进制它始终是 PATH 上的默认archon。这一点在源码层面有据可查发布二进制通过BUNDLED_IS_BINARY构建常量与开发态区分见 packages/paths/src/bundled-build.ts开发态默认BUNDLED_IS_BINARY false、版本为dev而构建脚本会在编译前将其改写为true并在结束后通过 EXIT trap 恢复。什么时候不要用本技能还没有发布版本——应运行bash scripts/build-binaries.sh本地构建直接从dist/binaries/执行要测试开发克隆——用bun run validate或直接bun packages/cli/src/cli.ts调用源码要测试完整 server web UI 部署链路——用 deploy/cloud-init.yml 在真实 VPS 上走云初始化。Phase 0 — 发版前本地构建预发布 QA在任何 tag 之前用与 CI 完全一致的构建入口做一次本地构建可以提前暴露构建期常量问题。scripts/build-binaries.sh是唯一规范入口本地开发与 release workflow 都以相同方式调用它本地构建绿色即代表 CI 构建走的是同一代码路径。# 多目标模式构建全部 4 个本地平台到 dist/binaries/ VERSION0.3.1 GIT_COMMITabc12345 bash scripts/build-binaries.sh # 单目标模式匹配某个 CI matrix 任务 VERSION0.3.1 \ GIT_COMMITabc12345 \ TARGETbun-darwin-arm64 \ OUTFILEdist/test-archon-darwin-arm64 \ bash scripts/build-binaries.sh构建脚本的关键行为对应 scripts/build-binaries.sh环境变量VERSION默认取根 package.json 的 version、GIT_COMMIT默认git rev-parse --short HEAD失败回退unknown、TARGET与OUTFILE两者必须同时设置否则报错退出。重生成内置默认值构建前运行bun run scripts/generate-bundled-defaults.ts保证编译进二进制的默认 workflow/command 与磁盘当前内容一致对应 scripts/generate-bundled-defaults.ts。构建期常量注入编译前改写packages/paths/src/bundled-build.ts写入BUNDLED_IS_BINARY true、BUNDLED_VERSION、BUNDLED_GIT_COMMIT并用 EXIT trap 在结束包括失败时git checkout恢复保证开发树永远不被弄脏——这正是 issue #979 的修复动机。web 产物校验和若存在archon-web.tar.gz则计算其 SHA-256 嵌入常量在 CI/release 模式下缺失或非法会直接拒绝构建fail-closed开发模式则告警并回退远程拉取。编译参数bun build --compile --minify禁用--bytecode因为 Bun 1.3.11 对当前模块图会产生损坏的字节码入口为packages/cli/src/cli.ts。产物自检每个目标构建后校验文件存在且大小不小于 1MB 下限Bun 编译产物通常 50MB。构建完成后验证产物——多目标模式用./dist/binaries/archon-darwin-arm64单目标模式用你传入的OUTFILE./dist/test-archon-darwin-arm64 version # 期望输出Archon CLI v0.3.1, Build: binary, Git commit: abc12345version命令的实现packages/cli/src/commands/version.ts从archon/paths读取构建常量当BUNDLED_IS_BINARY为 true 时直接输出嵌入的版本与 commit否则回退到读取根 package.json 与运行时git rev-parse此时显示Build: source (bun)。因此版本报错 /Build: source (bun)/Git commit: unknown分别对应二进制陈旧 / 构建时BUNDLED_IS_BINARY未置 true#979 回归/ 构建脚本未捕获 commit。Phase 1 — 确定测试范围技能最多接收三个参数安装路径brew|curl-mac|curl-vps要演练的安装流程期望版本可选发布应报告的版本号如0.3.1。未提供则自动获取gh release list --repo coleam00/Archon --limit 1 --json tagName --jq .[0].tagNameVPS 目标仅curl-vpsSSH 目标形如userhost或host使用默认 SSH 配置。任何参数缺失都必须先向用户澄清再动手绝不猜测安装路径或期望版本。随后以如下形式向用户确认计划得到明确确认y后才能进入 Phase 2——因为发布测试会触碰安装状态About to test: Path: brew (Homebrew tap on macOS) Version: 0.3.1 (expected) Cleanup: will uninstall after tests (brew uninstall untap) If archon-stable symlink is detected in Phase 2, it will be restored at the end of Phase 5 by reinstalling the tap formula. Proceed? (y/N)Phase 2 — 预检动手前先做四项预检1. 记录当前开发二进制状态用于最终报告中证明开发二进制未被扰动which -a archon archon version 21 | head -52. 校验所选路径的前置条件brewbrew --version必须成功否则中止并提示安装 Homebrewcurl-maccurl --version必须成功macOS 上通常恒真curl-vpsssh target uname -a必须成功同时确认ssh target command -v curl有返回。3. 确认发布存在于 GitHub 且带资产gh release view vversion --repo coleam00/Archon --json tagName,assets --jq {tag: .tagName, assetCount: (.assets | length)}发布不存在或没有资产就中止绝不安装不存在的发布。4. 检测持久化archon-stable安装仅 brew 路径若用户此前将 brew 安装重命名为archon-stable双 brew 模式见~/.config/fish/functions/brew-upgrade-archon.fishPhase 5 的brew uninstall会将其一并清除。因此预先捕获状态供 Phase 5 的恢复逻辑使用ARCHON_STABLE_WAS_INSTALLED if [ -L /opt/homebrew/bin/archon-stable ] || [ -L /usr/local/bin/archon-stable ]; then ARCHON_STABLE_WAS_INSTALLEDyes echo Detected persistent archon-stable — will restore after Phase 5 uninstall. fi将该变量导出到 Phase 5 使用的环境中。此步仅对brew路径生效——curl-mac与curl-vps不经过 brew不会干扰archon-stable。Phase 3 — 安装brew 路径brew tap coleam00/archon brew install coleam00/archon/archon BINARY$(brew --prefix coleam00/archon/archon)/bin/archon捕获$BINARY供 Phase 4 使用并确认文件存在且可执行。公式本体homebrew/archon.rb按平台/架构从 GitHub Releases 下载预编译产物darwin-arm64 / darwin-x64 / linux-arm64 / linux-x64 四个资产install阶段将其重命名为archon并内置一个test断言archon version退出码为 0。curl-mac 路径安装到专用临时目录确保开发用bun link二进制在 PATH 上保持原样INSTALL_DIR/tmp/archon-test-release-$(date %s) mkdir -p $INSTALL_DIR curl -fsSL https://raw.githubusercontent.com/coleam00/Archon/main/scripts/install.sh | INSTALL_DIR$INSTALL_DIR bash BINARY$INSTALL_DIR/archon环境变量必须前缀bash而不是curl。在VARx cmd1 | cmd2中赋值只作用于cmd1所以INSTALL_DIR… curl … | bash只把变量给了下载环节安装器仍走/usr/local/bin默认值。失败方式极具迷惑性脚本能下载并通过校验和验证随后索要 sudo 并以sudo: a terminal is required to read the password死掉在 0.7.1 测试中实际观测到。注意 scripts/install.sh 头部示例里也带着同样的错误写法INSTALL_DIR~/.local/bin curl -fsSL ... | bash照抄该示例的用户同样会踩坑见 issue #2436。确认$BINARY存在且可执行并记录安装目录以备清理。curl-vps 路径在 VPS 上运行安装脚本ssh target curl -fsSL https://raw.githubusercontent.com/coleam00/Archon/main/scripts/install.sh | bash确定二进制落点——install.sh默认装到/usr/local/bin/archon若/usr/local/bin不可写则回退到$HOME/.local/bin/archonssh target command -v archon将远程路径捕获为$REMOTE_BINARYPhase 4 中每条命令都包成ssh target cmd。安装脚本其余值得注意的行为安装前在临时目录先执行一次version探针确认能运行mv到位后再对已安装路径重跑一次version检查防止装好了却跑不起来对应 #2295/#2338set -u下用${BASH_SOURCE[0]:-$0}而非裸$BASH_SOURCE[0]保证curl … | bash经 stdin 执行时不会因变量未绑定而提前崩溃同样见 #2338x64 平台还会检查 CPU 是否支持 AVX2检测不到时默认拒绝安装仅在显式设置ARCHON_SKIP_CPU_CHECK1时放行。捕获 SHA256 与版本安装后立即记录用于后续确认用户报告的 bug 是否来自我们测试过的同一产物# 本地路径brew / curl-mac shasum -a 256 $BINARY | awk {print $1} $BINARY version 21 # 远程路径curl-vps ssh target shasum -a 256 $REMOTE_BINARY || sha256sum $REMOTE_BINARY | awk {print $1} ssh target $REMOTE_BINARY version 21Phase 4 — 冒烟测试测试按顺序针对$BINARYcurl-vps 为ssh target $REMOTE_BINARY执行。始终使用完整二进制路径绝不用 PATH 上的archon确保被测对象无歧义。每条测试都应捕获完整输出用于最终报告单条失败不中断后续测试保证报告完整但整体结果标记为 FAIL。Test 1 — 版本正确上报$BINARY version通过标准退出码 0输出包含Archon CLI v期望版本输出包含Build: binary而非Build: source (bun)输出包含非unknown的 git commit即Git commit: sha。常见失败退出码非零→pino-pretty 启动崩溃#960等启动类故障版本错误→二进制陈旧或构建脚本未更新bundled-build.tsBuild: source (bun)→构建时BUNDLED_IS_BINARY未置 true#979 回归Git commit: unknown→构建脚本未捕获 commit。Test 2 — 内置工作流可加载创建临时 git 仓库让 CLI 有可操作对象TESTREPO/tmp/archon-test-repo-$(date %s) mkdir -p $TESTREPO cd $TESTREPO git init -q git commit -q --allow-empty -m init $BINARY workflow list通过标准退出码 0输出至少列出 20 个内置工作流archon-assist、archon-fix-github-issue、archon-comprehensive-pr-review 等无工作流文件缺失或 JSON 解析错误。常见失败空列表→内置默认值未嵌入二进制isBinaryBuild检测路径回归Not in a git repository→工作目录处理 bug解析错误→内嵌 JSON 损坏或陈旧。workflow list的实现在 packages/cli/src/commands/workflow.ts 中其workflow run支持--detach分离运行与--resume续跑等能力输出提示信息见该文件 1605、2572 行附近。Test 3 — SDK 通路可用assist 工作流前置条件编译二进制要求宿主机装有 Claude Code并配置二进制路径。测试前确保满足其一# 方案 A — 环境变量临时测试最方便 # 使用 Anthropic 原生安装器后的默认路径 export CLAUDE_BIN_PATH$HOME/.local/bin/claude # 或 npm 全局安装后 export CLAUDE_BIN_PATH$(npm root -g)/anthropic-ai/claude-code/cli.js # 方案 B — 配置文件持久化 # 在 ~/.archon/config.yaml 中加入 # assistants: # claude: # claudeBinaryPath: /absolute/path/to/claude然后在同一个$TESTREPO中$BINARY workflow run assist say hello and nothing else 21 | tee /tmp/archon-test-assist.log通过标准退出码 0Claude 子进程成功 spawn早期输出无spawn EACCES、ENOENT或process exited with code 1无Claude Code CLI not found错误出现即代表 resolver 拒绝了配置路径——需核实 cli.js 真实存在产生响应任何响应哪怕只是一句 hello就证明 SDK 往返链路打通。常见失败Claude Code not found→CLAUDE_BIN_PATH/claudeBinaryPath未设置或指向不存在的文件修正路径后重跑Module not found /Users/runner/...→#1210 回归resolver 被绕过SDK 的import.meta.url回退泄漏了构建机路径。排查 packages/providers/src/claude/provider.ts 与 resolverCredit balance is too low→认证指向已耗尽的 API key检查CLAUDE_USE_GLOBAL_AUTH与~/.archon/.envunable to determine transport target for pino-pretty→#960 回归二进制在 TTY 上崩溃package.json not found (bad installation?)→#961 回归isBinaryBuild检测失效进程在产出任何输出前退出→通用 spawn 失败捕获 stderr。resolver 的优先级与行为可从 packages/providers/src/claude/binary-resolver.ts 及其测试 binary-resolver.test.ts 印证依次尝试CLAUDE_BIN_PATH环境变量、assistants.claude.claudeBinaryPath配置、自动探测路径指向不存在的文件或缺少可执行文件的目录时会给出明确的定向报错最终全部不可用时抛出Claude Code not found并同时提示CLAUDE_BIN_PATH与claudeBinaryPath两种补救方式——这正是 Test 3b 要验证的错误路径。Test 3b — resolver 错误路径不设 CLAUDE_BIN_PATH 运行快速验证未配置任何路径时 resolver 能大声失败(unset CLAUDE_BIN_PATH; $BINARY workflow run assist hello 21 | tee /tmp/archon-test-no-path.log)通过标准当~/.archon/config.yaml未配置claudeBinaryPath时错误信息包含Claude Code not found同时提及CLAUDE_BIN_PATH与claudeBinaryPath两种补救方式无引用 CI 文件系统的Module not found堆栈。若你全局配置了claudeBinaryPath跳过此测试或临时重命名~/.archon/config.yaml。Test 4 — 环境泄漏门拒绝泄漏的 .env可选针对含 #1036/#1038/#983 的发布创建第二个一次性仓库植入伪造敏感 keyLEAKREPO/tmp/archon-test-leak-$(date %s) mkdir -p $LEAKREPO cd $LEAKREPO git init -q git commit -q --allow-empty -m init printf ANTHROPIC_API_KEYsk-ant-test-fake\n .env $BINARY workflow run assist hello 21 | tee /tmp/archon-test-leak.log通过标准当前行为——守卫是剥离而不是拒绝输出包含剥离行格式为[archon] stripped N keys from repo (.env) to prevent target repo env from leaking into Archon processesN等于植入的 key 数上面的.env为 1——计数为 0 说明文件根本没被读取是真实回归工作流随后正常继续并完成。断言必须精确匹配这一行——它锁定到本仓库与本 key 数因此其他目录产生的剥离不会造成假通过。同时捕获退出状态剥离设计下工作流预期成功非零退出本身就是失败$BINARY workflow run assist hello /tmp/archon-test-leak.log 21 leak_exit$? # $LEAKREPO 可能是符号链接路径macOS 上 /tmp - /private/tmp二进制记录的是解析后路径需对比解析结果 resolved_repo$(cd $LEAKREPO pwd -P) expected[archon] stripped 1 keys from ${resolved_repo} (.env) to prevent target repo env from leaking into Archon processes if [ $leak_exit -ne 0 ]; then echo FAIL: workflow exited $leak_exit — the guard strips and proceeds, it should not abort elif grep -qxF $expected /tmp/archon-test-leak.log; then echo PASS: env-leak guard stripped exactly the planted key from this repo else echo FAIL: expected strip line absent. Got: grep -F [archon] stripped /tmp/archon-test-leak.log || echo (no strip line at all — guard inactive) fi采用精确匹配是有意为之宽松模式如stripped [1-9][0-9]* keys .*\.env会放过任意路径上的任意正数 key导致属于其他仓库的剥离、或被无关.env虚增的计数都被当作成功而真正要抓的回归反而被掩盖。历史提醒——不要重拾旧断言。此测试此前预期拒绝Cannot add codebase/Cannot run workflow、非零退出那是 #1036/#1038/#983 的行为。当前设计是两层剥离守卫目标仓库的.env被读取危险 key 从交给 Archon 子进程的环境中移除运行继续。0.7.1 测试中旧断言对一个守卫实际工作正常精确剥离了植入的 1 个 key的二进制报了 FAIL。请验证安全属性本身key 永不抵达子进程而不是过时的补救文案。常见失败完全没有剥离行→守卫未激活.env正流向子进程stripped 0 keys→文件被定位但未解析剥离行指向错误文件或仓库→路径解析回归。守卫的底层实现在 packages/paths/src/strip-cwd-env.ts由于 Bun 会在用户代码运行前无条件从 CWD 加载.env/.env.local/.env.development/.env.production在目标仓库内调用archon时这些变量会泄漏进 Archon 进程该模块在启动最早阶段任何模块初始化读 env 之前用dotenv.config({ processEnv: {} })解析上述四类文件、收集 key 后从process.env删除并输出上文那行剥离日志同时还会按模式而非硬编码清除CLAUDE_CODE_*嵌套会话标记、NODE_OPTIONS、VSCODE_INSPECTOR_OPTIONS与BUN_INSPECT*调试变量防止它们传导到子进程引发崩溃。清理泄漏测试仓库rm -rf $LEAKREPOTest 5 — isolation list 可用健全性检查仍在同一个$TESTREPO$BINARY isolation list通过标准退出码 0无错误列表为空也是正常的——尚未创建任何 worktree 即可。此测试用于捕获其他测试暴露不出来的 isolation 子系统回归。Test 6 — 清理测试仓库rm -rf $TESTREPOcurl-vps路径下还需通过 SSH 清理远程创建的测试仓库。Phase 5 — 卸载即使 Phase 4 失败也必须执行卸载目标是把系统恢复到测试前状态。brew 路径brew uninstall coleam00/archon/archon brew untap coleam00/archon验证开发二进制仍是默认which -a archon # 应只显示 ~/.bun/bin/archon 路径不含 brew 路径 archon version | head -1 # 应与 Phase 2 捕获的开发版本一致若测试前检测到archon-stable恢复它双 brew 模式if [ -n $ARCHON_STABLE_WAS_INSTALLED ]; then echo Restoring archon-stable (detected before test)... brew tap coleam00/archon brew install coleam00/archon/archon BREW_BIN$(brew --prefix)/bin if [ -e $BREW_BIN/archon ]; then mv $BREW_BIN/archon $BREW_BIN/archon-stable echo archon-stable restored: $(archon-stable version 2/dev/null | head -1) else echo WARNING: brew install succeeded but $BREW_BIN/archon missing — check formula fi fi关于恢复版本的说明恢复操作从 tap 当前提供的公式重新安装通常是刚测过的那个发布archon-stable会指向新测版本——这正是操作者通常想要的刚验证过新版本可用希望archon-stable指向它。若你是在为旧版本做回溯 QA恢复出的archon-stable会是当前tap 公式而非测试前版本。对这种罕见场景操作者应在测试后手动重跑brew-upgrade-archon。curl-mac 路径rm -rf $INSTALL_DIRcurl-vps 路径ssh target sudo rm -f /usr/local/bin/archon || rm -f \$HOME/.local/bin/archon可选用户可能希望保留VPS 上的二进制用于持续 QA——移除前先询问。Phase 6 — 结构化报告报告应包含头部被测发布版本、安装路径、时间戳、被测二进制 SHA256环境开发二进制路径 版本证明开发安装未被扰动测试结果表每个测试一行标注 PASS / FAIL / SKIP捕获输出任何 FAIL 都附上确切命令、退出码与 stderr/stdout 最后 20 行总体结论全部通过为 PASS任一失败为 FAIL后续步骤FAIL 时给出具体行动建议提 hotfix issue、重新打 tag、检查构建 workflow 等。PASS 报告示例Test Release Report — archon v0.3.1 via brew ──────────────────────────────────────────── Tested at: 2026-04-08 15:42 UTC Binary SHA: e62eb73547b3740d56f242859b434a91d3830360a0d18f14de383da0fd7a0be6 Binary path: /opt/homebrew/Cellar/archon/0.3.1/bin/archon Dev binary: /Users/rasmus/.bun/bin/archon → ../install/.../cli.ts (unchanged) [PASS] Test 1 version reports 0.3.1, Build: binary, commit abc1234 [PASS] Test 2 workflow list returned 21 bundled workflows [PASS] Test 3 workflow run assist produced output [PASS] Test 4 env-leak gate refused leaky .env with context-aware error [PASS] Test 5 isolation list executed without errors [PASS] Cleanup brew uninstall untap clean, dev binary unchanged Overall: PASSFAIL 报告示例Test Release Report — archon v0.3.1 via curl-vps ──────────────────────────────────────────────── Tested at: 2026-04-08 15:42 UTC Binary SHA: 0cf83e15e6af228e3c3473467ca30fa7525b6d7069818d85f97a115ea703d708 Binary path: uservps:/usr/local/bin/archon Dev binary: /Users/rasmus/.bun/bin/archon (unchanged) [PASS] Test 1 version reports 0.3.1, Build: binary [FAIL] Test 2 workflow list returned 0 workflows Command: archon workflow list Exit: 0 Output: Discovering workflows in: /tmp/archon-test-repo-1712590923 Found 0 workflow(s): [SKIP] Test 3 SDK test skipped because Test 2 failed [SKIP] Test 4 env-leak gate test skipped because Test 2 failed [PASS] Test 5 isolation list executed without errors [PASS] Cleanup VPS binary removed Overall: FAIL关键行为准则绝不触碰开发bun link二进制Phase 4 一律使用已安装二进制路径测试前后均需验证失败也要清理Phase 4 中途失败仍要执行 Phase 5保证下一次运行从干净状态开始安装后立即捕获 SHA256让 bug 报告能精确引用被测产物安装前显式确认绝不擅自给用户装第二个二进制前后都报告开发二进制状态作为测试未扰动开发环境的证明任一测试失败即非零退出让 CI 等自动化包装层能检测到失败。相关资产索引scripts/build-binaries.sh — 构建发布产物的二进制homebrew/archon.rb — Homebrew tap 公式每次发版更新scripts/install.sh — curl 安装脚本scripts/install-local.sh 与 scripts/install-local.ps1 — 本地文件安装封装用于分支构建产物的发版前 QA而非 GitHub releasepackages/paths/src/bundled-build.ts — 构建期常量BUNDLED_IS_BINARY等二进制/开发态判定的依据packages/cli/src/commands/version.ts —version命令的二进制/开发态双路径实现packages/paths/src/strip-cwd-env.ts — 环境泄漏剥离守卫实现packages/providers/src/claude/binary-resolver.ts 与 binary-resolver.test.ts — Claude 二进制解析器及测试deploy/cloud-init.yml — 完整 server web UI 部署链路本技能不覆盖属于另一个测试场景.claude/skills/release/SKILL.md— 发版流程本身本技能的对侧。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考