test-release

测试发布版本

对已发布的 archon 二进制文件进行自动冒烟测试。涵盖三种安装路径：

• brew — macOS 上的 Homebrew tap（测试 formula 和校验和）
• curl-mac — 在 macOS 上通过 curl install.sh 安装（测试安装脚本，并将操作限制在临时目录中）
• curl-vps — 在远程 Linux VPS 上通过 curl install.sh 安装（测试 Linux 二进制文件和完整安装流程）

每种路径都会安装二进制文件、运行固定的冒烟测试套件，然后清理。开发环境中的 bun link 二进制文件不会受到影响，并且在整个过程中始终是 PATH 中默认的 archon。

以下情况请勿使用此技能：

• 尚未发布任何版本 — 通过 bash scripts/build-binaries.sh 构建本地二进制文件，然后直接从 dist/binaries/ 运行
• 想要测试开发克隆 — 使用 bun run validate，或通过 bun packages/cli/src/cli.ts 直接调用源码
• 想要测试完整的服务端 + Web UI 部署流程 — 在真实 VPS 上使用 deploy/cloud-init.yml 中的 cloud-init

发布前 QA 的本地构建

如需使用与 CI 完全相同的标志和常量在本地构建二进制文件， 请直接运行 scripts/build-binaries.sh。此脚本支持两种模式：

# Multi-target mode (builds all 4 local platforms into dist/binaries/)
VERSION=0.3.1 GIT_COMMIT=abc12345 bash scripts/build-binaries.sh

# Single-target mode (matches one CI matrix job)
VERSION=0.3.1 \
GIT_COMMIT=abc12345 \
TARGET=bun-darwin-arm64 \
OUTFILE=dist/test-archon-darwin-arm64 \
bash scripts/build-binaries.sh

# Verify the binary — use the path from the mode you built:
#   multi-target → ./dist/binaries/archon-darwin-arm64
#   single-target → the OUTFILE you passed above
./dist/test-archon-darwin-arm64 version
# Expected: Archon CLI v0.3.1, Build: binary, Git commit: abc12345

请在为发布版本打标签之前运行此脚本，以便在本地发现构建时常量问题。 该脚本是标准入口点 — 本地开发和发布工作流都会以相同方式调用它，因此本地构建成功意味着 CI 构建将执行相同的代码路径。

阶段 1 — 确定范围

解析参数。此技能最多接受三个参数：

1. 安装路径（brew | curl-mac | curl-vps）：要测试哪种安装流程
2. 预期版本（可选）：发布版本应报告的版本标签，例如 0.3.1。如果未提供，则获取该版本：

gh release list --repo coleam00/Archon --limit 1 --json tagName --jq '.[0].tagName'

3. VPS 目标（仅用于 curl-vps）：SSH 目标，格式为 user@host 或 host（使用默认 SSH 配置）

如果缺少任何参数，请先向用户确认，再执行任何操作。绝不要猜测安装路径或预期版本。

继续阶段 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)

未经明确确认，不得继续。发布测试会触及安装状态，用户应对此有所了解。

阶段 2 — 预检

在进行任何操作之前：

1. 捕获当前开发二进制文件的状态，以供参考：

which -a archon
archon version 2>&1 | head -5

记录开发二进制文件的路径和版本，以便最终报告能够说明“开发二进制文件未受影响”。

2. 验证所选路径的前置条件：

   • brew：brew --version 必须成功。如果失败，则中止并提示“未安装 Homebrew — 请参阅 https://brew.sh/”
   • curl-mac：curl --version 必须成功（在 macOS 上实际上始终成立）
   • curl-vps：ssh <target> 'uname -a' 必须成功。如果失败，则中止并提示“无法通过 SSH 连接到 ”。同时验证 ssh <target> 'command -v curl' 是否返回路径。

3. 确认 GitHub 上存在此发布版本：

gh release view v<version> --repo coleam00/Archon --json tagName,assets --jq '{tag: .tagName, assetCount: (.assets | length)}'

如果发布版本不存在或没有资源，则显示清晰的消息并中止。不要继续安装不存在的发布版本。

4. 检测持久化的 archon-stable 安装（仅限 brew 路径）。 如果用户已将之前通过 brew 安装的版本重命名为 archon-stable（双 Homebrew 安装模式 — 参见 ~/.config/fish/functions/brew-upgrade-archon.fish），阶段 5 中的 brew uninstall 会将其删除。请捕获其状态，以便阶段 5b 可以恢复：

ARCHON_STABLE_WAS_INSTALLED=""
if [ -L /opt/homebrew/bin/archon-stable ] || [ -L /usr/local/bin/archon-stable ]; then
  ARCHON_STABLE_WAS_INSTALLED="yes"
  echo "Detected persistent archon-stable — will restore after Phase 5 uninstall."
fi

将 ARCHON_STABLE_WAS_INSTALLED 导出到阶段 5b 使用的环境中。仅适用于 brew 路径 — curl-mac 和 curl-vps 不会通过 brew 安装，也不会影响 archon-stable。

阶段 3 — 安装

路径：brew

brew tap coleam00/archon
brew install coleam00/archon/archon
BINARY="$(brew --prefix coleam00/archon/archon)/bin/archon"

保存 $BINARY，供阶段 4 使用。验证文件存在且具有可执行权限。

路径：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 前面。 在 VAR=x 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/archon：

ssh <target> 'command -v archon'

将远程路径记录为 $REMOTE_BINARY。在 Phase 4 的其余部分，将每条命令封装为 ssh <target> '<cmd>'。

捕获 SHA256 和版本

安装完成后立即捕获：

# Local paths (brew / curl-mac)
shasum -a 256 "$BINARY" | awk '{print $1}'
"$BINARY" version 2>&1

# Remote path (curl-vps)
ssh <target> "shasum -a 256 $REMOTE_BINARY || sha256sum $REMOTE_BINARY" | awk '{print $1}'
ssh <target> "$REMOTE_BINARY version" 2>&1

将两者记录在报告中。SHA256 可让我们稍后确认，报告 bug 的用户运行的是否与我们测试的构件完全相同。

Phase 4 — 冒烟测试

按顺序使用 $BINARY 运行这些测试（curl-vps 使用 ssh <target> $REMOTE_BINARY）。始终使用完整的二进制文件路径，绝不要使用 PATH 中的 archon，以免无法确定正在测试的是哪个二进制文件。

每项测试都应捕获完整的命令输出，以供最终报告使用。如果测试失败，仍需继续下一项测试（以确保报告完整），但要将总体结果标记为 FAIL。

测试 1 — 版本信息正确

"$BINARY" version

通过标准：

• 退出代码为 0
• 输出包含 Archon CLI v<expected-version>
• 输出包含 Build: binary（而不是 Build: source (bun)）
• 输出包含非 unknown 的 git 提交（即 Git commit: <sha>）

常见故障：

• 退出代码非 0 → pino-pretty 崩溃（#960）或类似的启动故障
• 报告的版本错误 → 二进制文件已过期，或构建脚本未能更新 bundled-build.ts
• 出现 Build: source (bun) → 构建期间未将 BUNDLED_IS_BINARY 设为 true（#979 的回归）
• 出现 Git commit: unknown → 构建脚本未能捕获提交信息

测试 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
• 输出列出捆绑的 sdlc 包工作流：archon-triage、archon-investigate、archon-plan、archon-implement、archon-pr、archon-review、archon-validate、archon-deliver、archon-upkeep、archon-ship
• 没有关于工作流文件缺失或 JSON 解析失败的错误

常见故障：

• 列表为空 → 默认捆绑内容未嵌入二进制文件（isBinaryBuild 检测路径的回归）
• 出现 Not in a git repository → 工作目录处理 bug
• 解析错误 → 嵌入的 JSON 已损坏或过期

测试 3 — SDK 路径可用（archon-investigate 工作流）

前提条件。 编译后的二进制文件要求主机上已安装 Claude Code，并已配置二进制文件路径。运行此测试前，请确保满足以下任一条件：

# Option A — env var (easy for ad-hoc testing)
# After the native installer (Anthropic's default):
export CLAUDE_BIN_PATH="$HOME/.local/bin/claude"
# Or after npm global install:
export CLAUDE_BIN_PATH="$(npm root -g)/@anthropic-ai/claude-code/cli.js"

# Option B — config file (persistent)
#   Add to ~/.archon/config.yaml:
#   assistants:
#     claude:
#       claudeBinaryPath: /absolute/path/to/claude

然后在同一个 $TESTREPO 中：

"$BINARY" workflow run archon-investigate --no-worktree "say hello and nothing else" 2>&1 | tee /tmp/archon-test-investigate.log

通过标准：

• 退出代码为 0
• Claude 子进程成功启动（早期输出中没有 spawn EACCES、ENOENT 或 process exited with code 1）
• 没有 Claude Code CLI not found 错误（这表示解析器拒绝了已配置的路径——请确认 cli.js 确实存在）
• 生成了响应（任何响应都可以——即使只有 “hello”，也能证明 SDK 往返调用正常）

常见故障：

• Claude Code not found → CLAUDE_BIN_PATH / claudeBinaryPath 未设置，或指向不存在的文件。修正路径后重新运行。
• Module not found "/Users/runner/..." → #1210 回归：解析器被绕过，SDK 的 import.meta.url 回退逻辑泄露了构建主机路径。请检查 packages/providers/src/claude/provider.ts 和解析器。
• Credit balance is too low → 身份验证指向了余额不足的 API 密钥（检查 CLAUDE_USE_GLOBAL_AUTH 和 ~/.archon/.env）
• unable to determine transport target for "pino-pretty" → #960 回归，二进制文件在 TTY 上崩溃
• package.json not found (bad installation?) → #961 回归，isBinaryBuild 检测失效
• 进程在生成输出前退出 → 通用启动失败，请捕获标准错误输出

测试 3b — 解析器错误路径（不设置 CLAUDE_BIN_PATH 运行）

快速验证未配置任何路径时，解析器会明确报错：

(unset CLAUDE_BIN_PATH; "$BINARY" workflow run archon-investigate --no-worktree "hello" 2>&1 | 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。

测试 4 — 环境泄漏防护会从 .env 中移除敏感键

创建第二个临时仓库，并放入一个虚假的敏感键：

LEAKREPO=/tmp/archon-test-leak-$(date +%s)
mkdir -p "$LEAKREPO"
cd "$LEAKREPO"
git init -q
git commit -q --allow-empty -m init
printf 'ANTHROPIC_API_KEY=sk-ant-test-fake\n' > .env
"$BINARY" workflow run archon-investigate --no-worktree "hello" 2>&1 | tee /tmp/archon-test-leak.log

通过标准（当前行为——防护会移除，而非拒绝）：

• 输出中包含一行移除提示，指出仓库和源文件，格式如下： [archon] stripped N keys from <repo> (.env) to prevent target repo env from leaking into Archon processes
• N 等于植入的键数量（上面的 .env 中为 1）——计数为 0 表示根本没有读取该文件，这是实际回归问题
• 工作流随后可以继续并正常完成

验证移除提示行——断言限定为此仓库和此键数量，因此其他目录中的移除操作不会造成假通过。同时捕获退出状态：按照移除设计，工作流应当成功，因此非零退出状态本身就是一个失败。

"$BINARY" workflow run archon-investigate --no-worktree "hello" > /tmp/archon-test-leak.log 2>&1
leak_exit=$?

# $LEAKREPO may be a symlinked path (/tmp -> /private/tmp on macOS); the binary
# logs the resolved form, so compare against that.
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 这样的宽松模式，对任何路径中的任何正数计数都会通过，因此属于其他仓库的移除操作——或由无关 .env 导致的计数虚高——都会被视为成功，而本测试旨在捕获的回归问题却不会被发现。

历史说明——不要重新断言旧标准。 此测试之前预期会 拒绝（Cannot add codebase / Cannot run workflow，退出状态非零），这是 #1036/#1038/#983 中的行为。当前设计采用两层移除防护：读取目标仓库的 .env，从传递给 Archon 子进程的环境中移除危险键，然后继续运行。在 0.7.1 测试中，旧断言针对一个防护正常工作的二进制报告了 FAIL——它恰好移除了植入的 1 个键。请验证安全属性（该键不会传递给子进程），而不是已过时的修复提示文本。

常见失败：

• 完全没有移除提示行 → 防护未启用；.env 内容会传递给子进程
• stripped 0 keys → 已定位文件，但未能解析
• 移除提示行指出错误的文件或仓库 → 路径解析回归问题

清理泄漏测试仓库：

rm -rf "$LEAKREPO"

测试 5 — 隔离列表正常工作（健全性检查）

在同一个 $TESTREPO 中：

"$BINARY" isolation list

通过标准：

• 退出代码为 0
• 没有错误（如果尚未创建工作树，列表为空也没问题）

此测试可以发现其他测试无法暴露的隔离子系统回归问题。

测试 6 — 清理测试仓库

rm -rf "$TESTREPO"

对于 curl-vps 路径，还要通过 SSH 清理创建的任何远程测试仓库。

阶段 5 — 卸载

务必运行卸载，即使阶段 4 失败也一样。 目标是让系统恢复到测试前的状态。

路径：brew

brew uninstall coleam00/archon/archon
brew untap coleam00/archon

确认开发版二进制仍是默认版本：

which -a archon
# should show only the ~/.bun/bin/archon path, not a brew path

archon version | head -1
# should match the dev version captured in Phase 2

如果测试前存在 archon-stable，请恢复它（双 Homebrew 模式——见阶段 2 第 4 项）：

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_DIR"

路径：curl-vps

ssh <target> "sudo rm -f /usr/local/bin/archon || rm -f \$HOME/.local/bin/archon"

可选：用户可能希望保留已安装的 VPS 二进制，以便持续进行 QA。移除前请先询问。

阶段 6 — 报告

生成结构化报告，包含：

• 标题：已测试的发行版本、安装路径、时间戳、已测试二进制文件的 SHA256
• 环境：开发二进制文件路径 + 版本（证明开发环境的安装未受影响）
• 测试结果表：每项测试占一行，并标注 PASS / FAIL / SKIP
• 捕获的输出：对于任何 FAIL，包含准确的命令、退出代码以及 stderr/stdout 的最后 20 行
• 总体结论：如果所有测试均通过，则为 PASS；如果任何测试失败，则为 FAIL
• 后续步骤：如果 FAIL，建议具体操作（提交热修复问题、重新打标签、检查构建工作流等）

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 archon-investigate produced output
  [PASS]  Test 4  env-leak guard stripped exactly the planted key
  [PASS]  Test 5  isolation list executed without errors
  [PASS]  Cleanup brew uninstall + untap clean, dev binary unchanged

Overall: PASS

This release is safe to announce. Next steps:
  - Update release notes on GitHub if not done already
  - Announce on whatever channels you use

FAIL 报告示例：

Test Release Report — archon v0.3.1 via curl-vps
────────────────────────────────────────────────
Tested at:    2026-04-08 15:42 UTC
Binary SHA:   0cf83e15e6af228e3c3473467ca30fa7525b6d7069818d85f97a115ea703d708
Binary path:  user@vps:/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 guard test skipped because Test 2 failed
  [PASS]  Test 5  isolation list executed without errors
  [PASS]  Cleanup VPS binary removed

Overall: FAIL

Likely cause: bundled workflows were not embedded in the binary.
Check the build workflow for missing asset embedding, or verify that
BUNDLED_WORKFLOWS in packages/workflows/src/defaults/bundled-defaults.ts
was populated at build time.

Next steps:
  1. File a P0 hotfix issue with the captured output
  2. Do NOT announce v0.3.1 until the hotfix ships as v0.3.2
  3. Consider adding a CI guard that blocks releases if BUNDLED_WORKFLOWS is empty

关键行为

• 绝不触碰开发环境中的 bun link 二进制文件。 阶段 4 测试始终使用已安装的二进制文件路径。安装前后都要验证。
• 失败时进行清理。 如果阶段 4 中途失败，仍要运行阶段 5，确保下次运行时环境干净。
• 安装后立即捕获 SHA256。 这样错误报告就能引用正在测试的确切构件。
• 安装前明确确认。 绝不在用户不知情的情况下安装第二个二进制文件。
• 在前后文中都报告开发二进制文件状态。 证明测试未影响开发环境。
• 如果任何测试失败，则以非零状态退出。 技能应传递失败状态，以便自动化包装程序（CI、脚本）检测到失败。

相关内容

• scripts/build-binaries.sh — 构建最终用于发行版的二进制构件
• .github/workflows/release.yml — 在推送标签时构建并发布二进制文件
• homebrew/archon.rb — Homebrew tap 公式（按发行版本更新）
• scripts/install.sh — curl 安装脚本
• scripts/install-local.sh / install-local.ps1 — 本地文件安装测试工具（用于对从分支构建的二进制文件进行预发行 QA，而非对 GitHub 发行版进行测试）
• /release 技能 — 发行流程本身（流程的另一端）