Superpowers 测试体系详解：插件测试与 Drill 行为评测的双层验证架构

Superpowers 对"代码是否正确"和"Agent 行为是否正确"做了严格区分，由此形成了仓库中两套互补的测试体系：tests/ 下的非 LLM 集成测试验证插件基础设施代码（brainstorm-server、OpenCode 插件加载、Codex 插件同步等），而 evals/ 下的 drill 评测框架则驱动真实的 LLM 会话，用 LLM 扮演者加裁判的方式检验技能（skill）是否被正确遵守。读完本文，你将掌握两套测试的定位、目录结构、完整运行命令（run-*.sh / npm test / drill run）及其背后的验证机制，能独立完成从插件回归测试到技能行为评测的全链路验证。

双层测试体系：tests/ 与 evals/ 的分工

Superpowers 的测试按"被测对象是否涉及 LLM 行为"划分为两个目录，各自承担不同职责（见 docs/testing.md）：

目录	验证目标	技术栈	典型耗时
tests/	插件的非 LLM 代码是否工作正常	Bash + Node + Python 集成测试	秒级到分钟级（个别 10–30 分钟）
evals/	Agent 在真实 LLM 会话中行为是否正确	Python harness 驱动 Claude Code / Codex / Gemini CLI 的真实 tmux 会话，由 LLM actor 执行、LLM verifier 判定技能遵守情况	单个场景 3–30+ 分钟

这种分工意味着：改坏了 brainstorm-server 的 WebSocket 协议，跑 tests/ 就能发现；改了技能文案导致 Agent 不再遵守 TDD 流程，则必须靠 evals/ 的行为评测才能暴露。两层缺一不可。

插件测试（tests/）

插件测试全部位于 tests/ 目录。当前覆盖范围与原文档清单一致，下面按目录逐一说明，并结合各测试文件的实际实现补充验证细节。

测试目录总览

• tests/brainstorm-server/ — brainstorm-server JS 代码的 Node 测试套件。
• tests/opencode/ — OpenCode 插件加载、bootstrap 缓存、工具注册的 Bash 测试。
• tests/codex-plugin-sync/ — Codex 插件同步验证。
• tests/kimi/ — Kimi 插件清单（manifest）接线的 Bash/Python 检查。
• tests/claude-code/test-helpers.sh、analyze-token-usage.py — 其余 Bash 测试依赖的公共工具。
• tests/claude-code/test-subagent-driven-development.sh — "Agent 能描述 SDD"测试（无对应 drill 场景；它测的是描述回忆，不是行为）。
• tests/claude-code/test-subagent-driven-development-integration.sh — 带 token 分析的扩展 SDD 集成测试（drill 只覆盖 YAGNI 子集；Bash 测试额外断言 commit 数量、Claude Code 任务跟踪和 token 遥测）。
• tests/claude-code/test-worktree-native-preference.sh — worktree 技能的 RED-GREEN-REFACTOR 验证（drill 覆盖 PRESSURE 阶段；Bash 测试另覆盖 RED/GREEN 基线）。
• tests/explicit-skill-requests/ — Haiku 专属、多轮对话、以及按技能名提示的测试，drill 不覆盖这些场景。

此外仓库中还有若干原文档未逐项列出、但同属插件测试范畴的目录：tests/claude-code/test-sdd-workspace.sh（验证 skills/subagent-driven-development/scripts/sdd-workspace 为每个 plan 解析出自忽略的工作树目录）、tests/hooks/test-session-start.sh（验证 hooks/session-start 启动钩子与 run-hook.cmd 包装器的输出形态）、tests/codex/（Codex marketplace 清单与打包脚本）、tests/antigravity/、tests/pi/、tests/shell-lint/、tests/systematic-debugging/test-find-polluter.sh 等。

运行方式统一为：进入对应目录，执行该目录提供的 run-*.sh 或 npm test。

brainstorm-server：Node 测试套件

tests/brainstorm-server/ 是仓库中唯一的 npm 测试套件。从 package.json 可以看到其 test 脚本按固定顺序串行执行 7 个 Node 测试和 2 个 Bash 测试：

node ws-protocol.test.js && node helper.test.js && node browser-launcher.test.js \
  && node auth.test.js && node branding.test.js && node server.test.js \
  && node lifecycle.test.js && bash start-server.test.sh && bash stop-server.test.sh

对应的被测对象正是 skills/brainstorming/scripts/server.cjs 等 brainstorming 技能的可视化伴侣（visual companion）服务端代码：

• ws-protocol.test.js — WebSocket 协议层；
• auth.test.js、branding.test.js — 鉴权与品牌资源；
• server.test.js、lifecycle.test.js — 服务端行为与生命周期；
• start-server.test.sh、stop-server.test.sh — 对应 skills/brainstorming/scripts/start-server.sh / stop-server.sh 的启动/停止脚本；
• windows-lifecycle.test.sh — Windows 生命周期（未列入默认 npm test 序列，需按平台单独运行）。

套件仅依赖 ws（^8.21.0）一个包，符合项目零依赖插件的整体约束（测试目录允许测试依赖）。运行方式：

cd tests/brainstorm-server
npm install
npm test

Claude Code 技能测试：run-skill-tests.sh 与 test-helpers

tests/claude-code/ 是插件测试中体量最大的部分，其 README 给出了完整的运行手册。测试通过 Claude Code CLI 的无头模式（claude -p）发起真实提示词，再对输出做断言：

# 运行全部快速测试（推荐）
./run-skill-tests.sh

# 运行集成测试（慢，10–30 分钟）
./run-skill-tests.sh --integration

# 只跑指定测试
./run-skill-tests.sh --test test-subagent-driven-development.sh

# 详细输出 / 自定义超时
./run-skill-tests.sh --verbose
./run-skill-tests.sh --timeout 1800

run-skill-tests.sh 的默认单测试超时为 900 秒，注释中明确该预算必须覆盖最坏情况（test-subagent-driven-development.sh 的 9 个提示 × 90 秒）。

共享的断言工具在 test-helpers.sh 中，每个测试文件的编写模式是"source helpers → 用 run_claude 发提示 → 断言 → 0/非 0 退出码"：

函数	作用
run_claude "prompt" [timeout] [allowed_tools]	以 argv 数组形式执行 timeout N claude -p ...，捕获输出
assert_contains output pattern name	断言输出包含模式（大小写不敏感，因为模型会自由改变技能术语的大小写）
assert_not_contains output pattern name	断言输出不含模式
assert_count output pattern count name	断言出现次数精确匹配
assert_order output a b name	断言两个模式的先后顺序
create_test_project / create_test_plan	创建临时测试项目与示例 plan 文件

各测试文件的定位（原文档 + README 合并）：

• test-subagent-driven-development.sh（快速，约 2 分钟）：验证 SDD 技能可被正确描述——技能加载与工作流顺序（先 spec 合规、后代码质量）、自审要求、plan 读取效率、reviewer 怀疑姿态等。它测的是"描述回忆"，drill 无对应场景。
• test-subagent-driven-development-integration.sh（集成，10–30 分钟）：创建真实 Node.js 测试项目、2 个任务的实现计划，用 SDD 实际执行并验证——plan 只读一次、完整任务文本进入子代理提示、子代理先自审、spec 合规审查先于代码质量、审查者独立读码、最终代码可用且测试通过、产生规范的 git commit。原文档特别指出：drill 覆盖其中的 YAGNI 子集，而 Bash 测试额外断言 commit 数、Claude Code 任务跟踪与 token 遥测（token 数据由 analyze-token-usage.py 分析）。
• test-worktree-native-preference.sh（约 5 分钟）：对 using-git-worktrees 技能做 RED-GREEN-REFACTOR 验证——RED：技能缺少 Step 1a 时，Agent 应回退到 git worktree add；GREEN：技能含 Step 1a 时，Agent 应使用原生 EnterWorktree 工具；PRESSURE：在紧迫话术与已存在的 .worktrees/ 下复测 GREEN 场景。原文档注明 drill 的 worktree-creation-under-pressure.yaml 场景只覆盖 PRESSURE 阶段，RED/GREEN 基线由 Bash 测试补足。
• test-sdd-workspace.sh：验证 sdd-workspace 脚本为每个 plan 解析出自忽略的独立工作树目录，SDD 脚本产物写入对应 plan 目录。

OpenCode 测试：快慢分离的 run-tests.sh

tests/opencode/run-tests.sh 采用"默认快速测试 + --integration 追加集成测试"的分层结构：

• 快速测试（无外部依赖，默认执行）：test-plugin-loading.sh、test-bootstrap-caching.sh（后者还有 test-bootstrap-caching.mjs 的 Node 变体）；
• 集成测试（需要本机装有 OpenCode，--integration/-i 开启）：test-tools.sh（use_skill 与 find_skills 工具）、test-priority.sh（技能优先级解析）。

cd tests/opencode
./run-tests.sh              # 快速测试
./run-tests.sh --integration --test test-tools.sh

运行器对每个测试记录耗时，非 verbose 模式下失败才打印完整输出，最终以 STATUS: PASSED/FAILED 和退出码收尾——这一模式与 Claude Code 测试运行器一致，体现了仓库内 Bash 测试的统一风格。

其余插件测试

• tests/codex-plugin-sync/test-sync-to-codex-plugin.sh：在 mktemp -d 沙箱中调用被测的 scripts/sync-to-codex-plugin.sh，用 assert_equals/assert_contains 校验同步产物，并用 PACKAGE_VERSION/MANIFEST_VERSION 等哨兵值验证版本传递。
• tests/hooks/test-session-start.sh：对 hooks/session-start 和 run-hook.cmd 在不同模拟 HOME 下的输出做形状断言（assert_command_output 支持 contains/not_contains 双向检查）。
• tests/explicit-skill-requests/：用户按名字直接点名技能的触发测试。run-test.sh 接受 技能名 + 提示词文件 + 最大轮数 三个参数，使用隔离的 HOME 避免用户上下文干扰，会话转录落盘到 /tmp/superpowers-tests/<时间戳>/ 供复盘；prompts/ 下提供 9 个提示词变体（如"我知道 SDD 是什么""跳过客套""中途执行计划"等压力场景），run-all.sh、run-multiturn-test.sh、run-haiku-test.sh 分别覆盖批量、多轮与 Haiku 模型场景——这些正是原文档所说"drill 不覆盖"的显式技能请求面。
• tests/kimi/：run-tests.sh 驱动的 Kimi 插件 manifest 检查（test-plugin-manifest.sh）。
• 其余 tests/antigravity/、tests/codex/、tests/pi/、tests/shell-lint/、tests/systematic-debugging/ 分别覆盖 Antigravity 工具接入、Codex marketplace 清单与打包脚本、Pi 扩展、shell 脚本 lint、以及 find-polluter.sh 调试脚本本身。

技能行为评测（evals/）：drill 框架

快速上手

技能行为评测位于 evals/ 目录，drill 是其中的 harness，场景文件存放在 evals/scenarios/*.yaml。原文档给出的快速启动流程：

cd evals
uv sync --extra dev
export ANTHROPIC_API_KEY=sk-...
uv run drill run triggering-test-driven-development -b claude

其中 -b claude 指定被测后端（drill 支持 Claude Code / Codex / Gemini CLI 三类后端），uv run drill run <场景名> 执行指定场景：drill 在真实 tmux 会话中启动目标 CLI，由 LLM actor 扮演用户驱动会话，再由 LLM verifier 判定 Agent 是否遵守了目标技能（如本例中是否触发了 test-driven-development 技能）。

适用前提与 CI 策略

有两点必须注意：

1. evals/ 不在本仓库内。它是独立仓库 superpowers-evals 克隆到 evals/ 用于本地开发的，.gitignore 中明确标注该目录"不属于发布的插件的一部分"，因此整目录被忽略；CLAUDE.md 的 "Eval harness" 一节也说明 drill（harness）驱动真实 tmux 会话并用 LLM verifier 判定技能遵守，插件基础设施测试仍在 tests/。克隆后应查阅其中的 evals/README.md 完成环境配置。
2. drill 场景很慢且消耗真实 LLM 调用。每个场景 3–30+ 分钟，因此当前不纳入 CI；原文档指出的自然演进是分层模型：PR 上跑快速子集，夜间全量扫描加按需触发。

运行建议与验证对照

结合两套体系的定位，推荐的验证顺序是：

1. 改动 JS 基础设施（如 brainstorm-server）→ cd tests/brainstorm-server && npm test；
2. 改动某个 harness 的插件接线（OpenCode / Codex / Kimi / hooks）→ 运行对应目录的 run-*.sh（OpenCode 无外部依赖部分可默认运行，需 OpenCode 本体的加 --integration）；
3. 改动技能文案或工作流指令 → 先跑 tests/claude-code/run-skill-tests.sh 快速回归，行为级验证再跑对应 drill 场景，并注意 Bash 测试与 drill 场景的互补关系（如 SDD 的 commit 数/token 断言只在 Bash 侧、worktree 的 PRESSURE 阶段只在 drill 侧）；
4. 所有测试均以退出码为结论：0 为通过，非 0 为失败，可直接接入 CI 或 pre-commit 流程。

这套"基础设施测试管代码、行为评测管 Agent"的双层设计，正是 Superpowers 作为技能框架保证其方法论声明可被验证、而非仅停留在文档层面的关键机制。