面向 superpowers 的行为评估实验室。 Quorum 驱动真实的编码代理 CLI（Claude, Codex, Antigravity, Gemini, Kimi, OpenCode, Pi 和 Copilot）通过 Gauntlet QA 代理，并根据场景 验收标准以及确定性后检查进行评分。
代码、CLI、路径和内联文本均使用小写 quorum；大写形式 Quorum
出现在标题和角色表中。
这不是一个通用的基准测试套件。它是一个面向工作流合规性的评估实验室： 技能触发、工作树行为、子代理协调、验证反射、审查质量和成本塑造模式。
quorum 有两种截然不同的执行模式：
biome、tsc 和
bun test。它们不调用模型 API，也不启动代理 CLI。公共 CI 必须保持在该线的静态/单元侧。切勿向公共 CI 添加 API 密钥、实时
quorum run … 调用或危险模式代理启动。
实时评估运行被测的编码代理，具有广泛的执行权限：
--dangerously-skip-permissions。--dangerously-bypass-approvals-and-sandbox。--dangerously-skip-permissions，并依赖本地
浏览器/钥匙串认证进行 agy。--skip-trust --approval-mode=yolo；API 密钥认证为默认，
可选 OAuth 认证用于受信任的本地运行。--yolo。--dangerously-skip-permissions。--allow-all。quorum 将每个编码代理的 HOME（以及 XDG 基础目录和 TMPDIR）固定到
<run>/home 下的单次运行的临时主目录 — 启动器将 src/agents/home-env.ts
（xdgHomeEnv，单一事实来源）构建的 $QUORUM_HOME_ENV 令牌拼接进去。
每个代理的配置目录折叠在该主目录下（Claude 的 .claude，Codex 的 .codex，
Gemini 的 .，OpenCode 的 .，Antigravity 的 .，Copilot 的 .copilot，
Kimi 的 .kimi-code，Pi 的 .pi/agent），因此编码代理通过自己的 $HOME
默认值找到其配置，并且永远不会看到主机的真实 ~/.claude、~/.codex、
~/.gemini、~/.kimi-code、~/.pi、~/.copilot、~/.config
或其他与主目录相关的状态、已安装的插件或先前的会话。
预配在启动前将配置 — 以及每个代理所需的主机 OAuth 凭据 — 安装到该临时
主目录中，因此没有运行时登录。Copilot 还将本地 Superpowers 插件放置在
隔离的主目录下，使用允许列表的外部环境，并在运行目录内写入一个包含机密的
chmod-0600 .copilot-env。这缩小了爆炸半径，但并非沙箱。OpenCode 和
Copilot 启动器还使用允许列表环境，但实时编码代理仍然以广泛的文件系统和
命令执行权限运行。
仅在受信任的本地环境中运行实时评估：
results/、原始会话日志、会话状态/工具调用产物以及
Gauntlet 代理输入视为敏感信息。安装并运行静态门禁：```bash bun install bun run check bun run quorum check
在容器外运行一个本地或紧急访问场景：```bash
export SUPERPOWERS_ROOT=/path/to/superpowers
export ANTHROPIC_API_KEY=...
bun run quorum run scenarios/triggering-writing-plans --coding-agent claude
bun run quorum show <run-dir>
Gauntlet-Agent（QA 驱动程序）默认通过 ANTHROPIC_API_KEY 向 Anthropic 进行身份验证。如果想改用已登录的 Claude 订阅来驱动它，请在环境（例如 .env）中设置 CLAUDE_CODE_OAUTH_TOKEN（从 claude setup-token 获取）；测试工具会传递该令牌，而 gauntlet 优先使用它而不是 API 密钥。注意：订阅具有针对交互式使用设计的用量限制——高并发 run-all 批次可能会达到这些限制，因此 API 密钥仍然是处理高负载的更好选择。
代理名称包括 claude、codex、antigravity、gemini、kimi、opencode、pi 和 copilot。并非每个场景都适用于每个代理。
重大变更（凭证维度）：claude-haiku 和 claude-sonnet 不再是独立的代理名称。要针对 Sonnet 或 Haiku 运行 Claude 测试工具：```bash
bun run quorum run scenarios/ --coding-agent claude --credential sonnet
bun run quorum run scenarios/ --coding-agent claude --credential haiku
The `claude` agent's default credential is `opus`.
## 共享评估设备
共享远程实时评估设计为从受信任的设备主机运行，具有一个经过批准的凭据包、精确的仓库/引用来源、主机锁定和可恢复的任务记录。一旦存在，代理应在配置的主机上使用设备助手：```bash
evals-appliance doctor --json
evals-appliance prepare --json --superpowers-ref <branch-tag-or-sha>
evals-appliance run-all --json --detach \
--superpowers-ref <branch-tag-or-sha> \
-- --tier sentinel \
--coding-agents claude,codex,kimi \
--jobs 4
evals-appliance status --json <job-id>
evals-appliance show --json <job-id>
evals-appliance costs --json <job-id>
evals-appliance cancel --json <job-id>
目标接口和操作规则位于
docs/appliance-runbook.md，并由
docs/superpowers/specs/2026-06-18-shared-eval-appliance-design.md 提供支撑。
doctor 是只读的。prepare 返回 lock_busy，而不是在实时作业活跃时更改引用。
主机访问和特定于提供商的应急程序有意未包含在此公共仓库中；有关详细信息，请使用私有运维手册。
原始的 bun run quorum ... 和 scripts/evals-container exec quorum ... 仍作为共享实时评估的本地或可信应急工作流保留。
Docker 运行时是实际套件运行的主要方案。它在主机上保留评估检出、正在测试的 Superpowers 检出、凭据、认证源以及所有运行工件，而 quorum 则在丰富的 Ubuntu 工作空间容器内运行。
创建 .env.container 或将显式环境文件传递给 up：```dotenv
ANTHROPIC_API_KEY=...
OPENAI_API_KEY=...
OPENROUTER_API_KEY=... # Pi default: OpenRouter GLM 5.2
GEMINI_API_KEY=... # or GEMINI_AUTH_TYPE=oauth-personal
KIMI_MODEL_API_KEY=... # unless using mounted Kimi OAuth
PI_PROVIDER=... # only for raw/custom Pi env auth outside the default credential
PI_MODEL=...
PI_API_KEY=...
COPILOT_GITHUB_TOKEN=...
然后构建、启动并验证容器：```bash
scripts/evals-container build
scripts/evals-container down || true
scripts/evals-container --env-file .env.container up
scripts/evals-container exec evals-tool-versions
scripts/evals-container exec quorum check
包装器将此 evals 检出点挂载到 /workspace/evals，父级 Superpowers 检出点挂载到 /workspace/superpowers，主机的 results/ 挂载到 /workspace/evals/results。当默认父级路径不是被测系统时，使用 --superpowers-root <dir> 覆盖 Superpowers 检出点。
镜像构建需要本地的 Gauntlet 检出点。包装器从 GAUNTLET_ROOT 或 Bun 全局 bun link 安装中自动发现；使用 --gauntlet-root <dir> 连同 build 显式选择。
凭据是只读挂载。默认情况下，up 首先使用 .env.container，然后使用 .env，并将第一个找到的文件挂载到 /run/evals/credentials.env。在 up 之前传递 --env-file <file> 来显式选择。包装器不会整体传递主机环境；只有容器内的 quorum 垫片会加载 dotenv 文件，因此 scripts/evals-container exec bash ... 不会自动接收到实时的 eval 凭据。在更改现有容器上的 env-file 挂载之前使用 down。
OAuth/文件认证源也是只读的。现有的 ~/.codex、~/.gemini、~/.kimi-code 和 ~/.pi 目录分别挂载到 /auth/codex、/auth/gemini、/auth/kimi-code 和 /auth/pi。使用 --auth codex=<dir>、--auth gemini=<dir>、--auth kimi=<dir> 或 --auth pi=<dir> 来覆盖某个源。
从哨兵套件开始：```bash
scripts/evals-container exec quorum run-all
--tier sentinel
--coding-agents claude,codex,kimi
--jobs 4
for agent in gemini opencode pi copilot; do
scripts/evals-container exec quorum run-all
--tier sentinel
--coding-agents "$agent"
--jobs 1
done
对于完整的就绪套件，运行相同的命令但不带 `--tier sentinel`。
`run-all` 将每个批次写入 `results/batches/<batch-id>/` 目录下，并将每次运行写入 `results/<scenario>-<agent>-<os>-<timestamp>-<nonce>/` 目录下；使用以下命令渲染一个批次：```bash
scripts/evals-container exec quorum show <batch-id>
run-all 会定期打印运行状态的心跳信息（⋯ … · 运行中 N/任务 · 已完成 D · 排队中 Q · [agent:scenario, …]）；可通过 --heartbeat-seconds <n> 调整（0 表示禁用）。
中断一个批次（Ctrl-C 或 exec 会话关闭）会优雅地停止它：队列被取消，正在运行的任务会收到 SIGINT 信号（并记录为已停止），批次页脚仍会写入，因此 finished_at 永远不会为空。
容器运行时不会挂载 Docker 套接字、发布仪表板端口或包含桌面 IDE。镜像省略了 Antigravity 的桌面 agy 安装程序；在出现无头安装路径之前，请在主机端运行 Antigravity：```bash
bun run quorum run-all --coding-agents antigravity --jobs 1
对于分组全代理主机扫描、每个代理的凭据、认证挂载详情以及故障排除，请参阅 [docs/coding-agent-care-and-feeding.md](https://github.com/prime-radiant-inc/superpowers-evals/blob/main/docs/coding-agent-care-and-feeding.md)。
## Windows 运行时
对于 Windows 11 上的评估，使用 `--os windows`（仅限 Linux+KVM 主机）：```bash
bun run quorum run scenarios/<name> --coding-agent claude --os windows
请参阅 docs/windows/eval-runtime.md 了解设置与部署。
务必分清角色；混淆它们是最常见的分类错误。 这些名称在文档、CLI 输出、代码、文件名以及提交信息中随处可见。
| 角色 | 是什么 | 所在位置/文件 |
|---|---|---|
| Gauntlet | 通用 QA 框架；gauntlet CLI。一个黑盒测试工具。 | 仓库 github.com/prime-radiant-inc/gauntlet；PATH 上作为 gauntlet（通过 bun link 或 GAUNTLET_ROOT） |
| Gauntlet-Agent | Gauntlet 内部的 LLM，驱动 Coding-Agent 并基于故事的 AC 进行自评分。 | 模型例如 claude-sonnet-4-6；事件流 → <run>/gauntlet-agent/results/<runId>/run.jsonl；判定 → result.{json,md} |
| Coding-Agent | 被测智能体——即 SUT。实例：Claude、Codex、Antigravity、Gemini、Kimi、OpenCode、Pi、Copilot。 | 配置与会话日志位于其一次性 $HOME，路径为 <run>/home/…；其写入的文件 → <run>/coding-agent-workdir/ |
| Quorum | TypeScript/Bun 封装器。负责设置、Coding-Agent 适配、确定性检查以及最终判定。 | 仓库 superpowers-evals/src/；<run>/verdict.json |
一次运行涉及两个 LLM——Gauntlet-Agent（QA 测试者）和 Coding-Agent（被测对象）。模型独立、日志独立、Token 成本独立。