测试与发布

改动 agentrun 的代码后怎么证明它还能用：scripts/test.sh 跑哪些检查，tests/ 里的文件各负责什么，回放样本从哪里来、怎么更新，验收脚本在四种环境里怎么运行，以及 CI 与发布怎么进行。单元与集成测试不需要任何运行时与账号，验收脚本需要真实的运行时与登录。

代码位置

src/ 里每个文件末尾的 #[cfg(test)] mod tests 是该文件的单元测试，测试纯函数与适配器生成的参数。过滤代理的测试在 src/network/tests.rs，它们在测试进程内用多个线程在回环地址上启动真实的过滤代理与上游服务。跨模块的行为、真实的子进程与沙箱放在 tests/。

scripts/test.sh

一条命令运行全部检查，任何一步失败就停止并以非 0 退出。提交前在本机运行，CI 也运行它（见 CI）。

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
uv run scripts/check_comment.py
shellcheck scripts/accept/accept.sh scripts/accept/lib/*.sh   # 没装 shellcheck 时打印 shellcheck not found, skipped

cargo test 同时运行 src/ 里的单元测试与 tests/ 里的集成测试。需要 bwrap、socat 或 sandbox-exec 的测试在当前环境没有这些程序或它们启动不了时打印 skipped: 开头的一行并通过，所以在没有沙箱的容器里 cargo test 也能全部通过；要覆盖沙箱路径，在装了 bwrap 与 socat 的 Linux 或 macOS 上运行。scripts/check_docs.py 不在 test.sh 里，改动 docs/ 后单独运行，用法见 CLAUDE.md「文档规范」。

tests/ 的分工

每个文件一个主题，文件名就是主题。测试之间可以并行：每个测试用自己的临时目录，端口由系统分配，不读写用户目录与全局配置。

只在进程内调用一个模块、不启动子进程、不改进程级状态的测试写在该模块的测试模块里，过滤代理的测试在 src/network/tests.rs。运行 agentrun、真实沙箱或子进程的测试留在 tests/，每个文件是一个单独的进程。理由：src 里的函数不必为了测试公开，挪动代码时也不用改 tests/；进程级状态（subreaper、信号处理、环境变量、当前目录）在 lib 的单元测试之间共用，只有单独的进程才能互不影响。

signals.rs、concurrency.rs 与 rich.rs 在 Cargo.toml 里声明 harness = false，理由：cargo 的测试 harness 会安装自己的信号处理，这些主题需要测试程序本身就是收信号、拥有终端、能把自己重新启动成 agentrun 的那个进程。它们用 support/harness.rs 的 run_tests 运行 test_list! 列出的测试函数，输出格式与 cargo 相同。所有测试同时开始，每个测试最多运行 60 秒，超时的测试打印测试名并判为失败。run_tests 支持 --list（输出与 cargo 相同）、--exact、--quiet 与 --ignored（选中的测试为空），接受并忽略 --nocapture、--show-output、--include-ignored 与 --test-threads，其他选项报错并以 101 退出。

写假运行时脚本一律用 support/env.rs 的 write_script，它让 /bin/sh 写文件并设权限，测试进程自己不持有脚本的写描述符，所以 fork 发生在 run::run 里的 framework.rs 与 session.rs 也不会在执行脚本时得到 ETXTBSY。harness = false 的测试程序里，每一次 fork（启动子进程、调用 ps、write_script 启动的 /bin/sh）仍先拿 support/process.rs 的 spawn_lock，理由：open_pty 在 openpty 返回到两个描述符设好 FD_CLOEXEC 之间，另一个线程 fork 出的子进程会继承伪终端的描述符，读 master 要等那个子进程退出才读到结束。spawn_lock 不可重入，support/env.rs 的 write_script 与 Agentrun::spawn、support/mod.rs 的 open_pty 与 sandbox_available、support/process.rs 里调用 ps 的 process_is_gone 自己拿锁，持有锁时不能调用它们。

Agentrun 被丢弃时，如果子进程还没退出，先发 SIGTERM，最多等 TERMINATE_LIMIT（10 s），再发 SIGKILL 并回收。理由：只发 SIGKILL 时 agentrun 来不及结束它启动的假运行时，测试 panic 后会留下进程。

回放样本

tests/fixtures/<运行时>/<场景>.* 每个场景三个文件：

support::replay 读 raw.jsonl，按 meta.json 构造 Invocation 与 Exit，以 dry-run 方式调用适配器的 launch（codex 另给 AGENTRUN_CODEX_AUTH 的内容使登录检查通过），再把每行交给 translate_line，最后调用 conclude 并传入 Launch 记录的包裹方式，得到的事件去掉 time 与 duration_ms 后与 events.jsonl 逐个比较。tests/fixtures/fake/basic.* 没有 meta.json，给 FakeAdapter 用。

样本来源：在 Cloud Managed 容器、docker 与 macOS 上直接运行 claude-code、codex 与 pi 录制；dsh 的样本在 Cloud Managed 容器里用下面第 1 步的 agentrun dsh --raw 录制，沙箱打开。每个场景一个工作目录，记录原始输出、退出码与标准错误；meta.json 里 /tmp/agentrun-probe-<随机>/<场景>-<运行时> 形式的 cwd 就是录制时的工作目录。events.jsonl 是写适配器时由当时的适配器生成、逐条核对后保存的。样本记录时的运行时版本见运行页的「运行时版本」。

更新样本的步骤：

1. 在装有该运行时的环境里运行一次，--raw 写出的文件就是新的 raw.jsonl：

   agentrun <运行时> --format jsonl --raw <场景>.raw.jsonl --prompt "<提示词>" > out.jsonl 2> stderr.txt

2. 写 meta.json：cwd 取 out.jsonl 里 start 事件的 cwd（--cwd 给出的目录，没给时是当前目录）；exit_code 取 end 事件的 exit_code，它是运行时进程的退出码；stderr 取 stderr.txt 的内容，jsonl 格式下 agentrun 把运行时的标准错误原样写到自己的标准错误。
3. 运行 cargo test --test <运行时> replay_<场景>，失败输出里的实际事件与期望事件逐条比较，确认差异来自运行时的变化而不是适配器的错误，再把实际事件写进 events.jsonl。

新增或更新样本前检查 raw.jsonl 与 meta.json 里没有令牌、API key 与用户目录的路径，仓库是公开的。

验收脚本

scripts/accept/accept.sh 用真实的运行时与登录把 agentrun 跑一遍，按退出码、事件流与工作目录里的文件判定每个场景，输出一张总表。它覆盖 claude-code、codex 与 pi，不覆盖 dsh。它是「Validate」步骤的工具，不在 scripts/test.sh 里运行，理由：需要这三个运行时的账号，并且要消耗模型调用。

scripts/accept/accept.sh [--agentrun PATH] [--runtimes claude-code,pi,codex] [--sandbox on|relax|off]
                         [--label NAME] [--out DIR] [--only NAME,...] [--parallel N]
                         [--claude-model ID] [--pi-model ID]

场景按下表顺序运行，每个场景对每个运行时各跑一次，不适用的组合记为 skip。

下表的并发场景只在 --only 列出时运行，理由：它们同时调用多次模型，费用与耗时都比其他场景高；cleanup 场景比较 agentrun-* 目录集合的检查也不能与它们同时进行。前四个场景对每个运行时各跑一次，concurrent-mixed 在所有运行时之后跑一次；sandbox-check 判为沙箱不可用的运行时不参加。每个并发运行有自己的记录目录，名字是场景、运行时加序号或所放行的主机，例如 concurrent-same-pi-1；场景本身的 check.txt 与之后补跑的 basic-task 记录在不带序号的 concurrent-same-pi/ 里。

每个并发场景结束后再检查共享的状态，任何一项不满足都判 fail：跑了 claude-code 时 ~/.claude.json 是合法的 JSON，跑了 pi 或 codex 时用户的登录文件（存在时）是合法的 JSON；用同一个运行时再跑一次 basic-task 并完成，确认登录仍然有效；临时目录下的 agentrun-* 目录与场景开始前相同；工作目录在脚本私有目录之下的进程都已结束（还在的进程写进说明并结束它们）。残留进程按工作目录找，不按命令名找，理由：按 claude 这样的名字匹配会找到机器上与验收无关的进程。

输出目录 <out>/<label>-<时间戳>/：env.txt 记录运行时版本、沙箱程序与每个运行时的 --dry-run 命令；summary.md 每个场景与运行时一行，列为场景、运行时、pass|fail|skip 与说明；每个组合一个 <场景>-<运行时>/ 目录，内有 cmd.txt、stdout.jsonl（text 格式的场景为 stdout.txt）、stderr.txt、exit_code、duration_ms、raw.jsonl 与 check.txt。有任何 fail 时脚本以 1 退出。分享输出目录前先读 stderr.txt，运行时的诊断信息写在那里。

scripts/accept/Dockerfile 基于 ubuntu:24.04，装 Node 22、用 npm 装三个运行时、bubblewrap、socat、curl 与 procps，并写入一份选中 deepseek/deepseek-flash 的 pi settings.json。镜像里不含 agentrun 与凭据：agentrun 由宿主用 rust:1-bookworm 容器交叉构建后挂载，凭据只经环境变量进入，不挂载用户的 HOME。

四种环境里的验收

验收由用户执行，AI 提供步骤与脚本。每种环境里先跑 scripts/test.sh，再跑验收脚本；沙箱打开与关闭各跑一遍，因为两种模式走的是不同的代码路径。

验收结果写在对应 Task 的 issue 里，附 summary.md；失败的场景附该目录的 stderr.txt 与 check.txt。发布前的验收用 release.yml 构建的文件，见发布。

CI

.github/workflows/ci.yml 在每个 pull request 与每次推送到 main 时运行。同一分支有新的推送时，正在运行的旧任务被取消。PR 在 CI 通过后才合并。

Linux runner 上关闭 AppArmor 对用户命名空间的限制，理由：Ubuntu 24.04 默认禁止非特权进程创建用户命名空间，bwrap 启动失败，需要沙箱的测试都会跳过。cargo publish --dry-run 在 PR 上构建 crates.io 的包，理由：Cargo.toml 的 include 只列构建需要的文件，漏掉文件时 crates.io 上的包会构建失败。

CI 不运行真实的 claude-code、codex、pi 与 dsh，也不调用模型，scripts/test.sh 只用假运行时与回放样本。工具链用 rustup 直接安装，不用第三方的工具链 action，也不加缓存。

发布

.github/workflows/release.yml 在三种情况下运行：推送 v* tag；PR 改动 release.yml、about.toml、about.hbs、Cargo.toml 或 Cargo.lock；在 Actions 页面手动运行。它有三个任务。

build 构建四个可执行文件，<版本> 取 Cargo.toml 的 version。由 tag 触发时，tag 去掉 v 后必须等于这个版本，否则任务失败。

Linux 的文件用 musl 静态链接，两个架构都在各自架构的 runner 上原生构建。理由：docker 镜像的 glibc 版本各不相同，静态链接的文件在 Alpine 与较旧的发行版上也能运行。依赖里没有需要 C 编译器的包；有这样的包时，musl 目标要用 musl-tools 提供的 musl-gcc，runner 上没有安装它，构建会失败。macOS 的两个架构都在 arm64 的 macos-15 上构建，x86_64 由 Xcode 的工具链交叉编译。macOS 的文件构建后用 codesign --force --sign - 做 ad-hoc 签名，理由：链接器只给 arm64 的文件做 ad-hoc 签名，交叉编译的 x86_64 文件没有签名。文件没有 Developer ID 签名与公证，用浏览器下载的文件要先去掉 quarantine 属性。

每个文件构建后检查，任何一项不通过时任务失败：

• 运行 file 并写进日志，Linux 的文件必须是 statically linked 或 static-pie linked。
• 运行 --version，输出必须是 agentrun <版本>。Linux 的文件另在 alpine:3 容器里运行一次。
• macOS 的文件运行 codesign --verify。x86_64 的文件在 Rosetta 可用时用 arch -x86_64 运行 --version，不可用时在日志里写明跳过。

每个文件上传为 Actions 的产物，保留 14 天。

licenses 用 cargo-about 按 about.toml 与 about.hbs 生成 THIRD-PARTY-LICENSES.txt，按许可证分组列出每个依赖的名字、版本与许可证全文。依赖的许可证不在 about.toml 的 accepted 列表里时任务失败。理由：发布的可执行文件静态链接了依赖，MIT 与 Apache-2.0 都要求随二进制分发附带许可声明。about.toml 的 targets 只列四个发布目标，只在 Windows 上使用的依赖不进入文件。

release 只在 tag 上运行（推送 tag，或在 Actions 页面对 tag 手动运行），等 build 与 licenses 都通过后，对四个可执行文件写 SHA256SUMS（每行 <哈希> <文件名>），用 gh release create --draft 建标题为 agentrun <版本> 的草稿 Release，上传四个可执行文件、SHA256SUMS 与 THIRD-PARTY-LICENSES.txt。正文为空，发布说明由维护者贴入后发布。

Cargo.toml 的 [package.metadata.binstall] 让 cargo binstall agentrun 从 Release 下载这四个文件：pkg-fmt = "bin" 表示 Release 里的文件直接就是可执行文件；每个目标三元组一条 overrides.<三元组>.pkg-url，指向上表中的文件，Linux 的 gnu 与 musl 目标都指向 musl 静态链接的文件。理由：cargo-binstall 默认只认文件名里带目标三元组的文件，在 glibc 的 Linux 上先试 gnu 目标再试 musl。改文件名或增加平台时要同时改这些 override，否则 cargo binstall 找不到文件，回退到 cargo-quickinstall 的预编译文件或本机编译。这份配置随 crates.io 上的包发布，只对配置加入之后发布的版本生效。

Cargo.toml 的 [profile.release] 设 strip = true、lto = true 与 codegen-units = 1，理由：发布的文件更小，代价是 release 构建更慢。

发布一个版本的步骤：

1. 在 PR 里修改 Cargo.toml 的 version 并更新 Cargo.lock。PR 上 release.yml 的 build 与 licenses 会运行。
2. 从这个 PR 的 Actions 运行下载四个文件（gh run download <运行号>），用 accept.sh --agentrun <文件> 在四种环境里验收，并运行 agentrun doctor。下载的文件先 chmod +x；macOS 上用浏览器下载的文件先运行 xattr -d com.apple.quarantine <文件>。
3. 验收通过后合并 PR，在合并后的 main 上推送 tag：git tag v<版本> && git push origin v<版本>。
4. 等 release.yml 建好草稿 Release，把发布说明贴进草稿并发布。
5. 在本机检出这个 tag，运行 cargo publish --locked 发布到 crates.io。crates.io 的令牌只在维护者本机，不放进仓库的 secrets。
6. 运行 cargo binstall agentrun@<版本> --disable-strategies quick-install,compile --root <临时目录> --no-confirm，确认它从 Release 下载了文件，<临时目录>/bin/agentrun --version 输出新版本。--disable-strategies 禁止回退到编译，地址配置有误时命令失败。