SuperPowers 的测试体系是一套通过自动化脚本验证 AI 编码代理能否正确发现、加载并执行技能流程的系统，它通过技能触发、显式请求、子代理集成与平台插件四个测试层，确保技能在各种编程环境中的行为一致性与可靠性。
SuperPowers 测试体系总览：技能触发、显式请求、子代理集成与 OpenCode 测试
对于使用 SuperPowers 来规范 AI 编码代理行为的开发者而言，确保技能按预期工作是整个流程的基石。SuperPowers 项目为此构建了一套严谨的自动化测试体系。这套体系并非单一测试，而是四个相互补充的层次，分别验证技能在不同场景下的触发与执行。理解这套测试体系，不仅能帮助你排查技能失效的问题，也能在贡献新技能时知道如何编写测试。
1. 技能触发测试：模拟用户自然提示，验证代理的自动发现能力
此测试层的核心是验证当用户发出一个隐含某技能适用场景的请求时，AI 代理能否“自主”识别并调用正确的技能，而非直接开始编码。测试脚本位于 tests/skill-triggering/ 目录。
工作流程：运行 run-all.sh 脚本会批量测试多个技能（如 systematic-debugging、test-driven-development）。它会为每个技能读取一个对应的自然语言提示文件（.txt），然后使用 claude -p 命令以无头模式启动会话，将输出保存为 stream-json 格式的日志。最后，脚本会分析日志，检查是否存在对目标技能的 Skill 工具调用记录。
关键验证逻辑：脚本通过在日志中搜索特定的 JSON 结构来判断技能是否被触发。它会查找 "name":"Skill" 的工具调用，并确认其参数中包含目标技能名（支持带或不带命名空间，如 "skill":"systematic-debugging" 或 "skill":"superpowers:systematic-debugging"）。通过这个测试，可以确保代理的技能发现机制（using-superpowers）是有效的。
2. 显式技能请求测试：确保用户直接点名时，代理能立即、准确响应
当用户明确说出技能名称时（例如“请使用 subagent-driven-development”），代理的反应必须快速且无误。显式技能请求测试专门针对这种场景，并且增加了对“过早行动”这一关键失败模式的检查。
测试场景与脚本：该测试涵盖多种情况，由不同脚本负责：
- 基本请求：
run-test.sh用于验证最基本的显式请求场景。 - 多轮对话：
run-multiturn-test.sh模拟在经过几轮规划对话后，用户才提出技能请求的场景，验证代理在较长上下文中的响应能力。 - 扩展上下文：
run-extended-multiturn-test.sh构建更长的对话历史，进一步测试边界情况。 - 廉价模型验证：
run-haiku-test.sh使用更便宜的模型进行测试，检查能力较弱的模型是否也遵循流程。 - 先描述后请求：
run-claude-describes-sdd.sh模拟了一个经典失败场景：首先让 Claude 自己描述subagent-driven-development技能是什么，然后用户再请求执行它，验证代理不会因为“觉得自己已经知道”而跳过加载步骤。
核心检查项：“过早行动”。在显式请求场景下，代理必须在加载技能指令后再开始实质性工作。测试脚本会分析日志时间线：定位第一次 Skill 工具调用的行号，检查在该行之前是否已出现其他工具调用（如写入文件、执行命令）。TodoWrite 这类规划工具除外。如果发现过早行动，说明代理在未遵循技能指引的情况下就擅自开工。
3. Claude Code 集成测试：运行真实的工作流闭环，验证端到端行为
这是最耗时但也最贴近真实开发的一层测试，专注于验证像 subagent-driven-development 这类复杂技能的完整执行流程。
测试结构与执行：集成测试通过 tests/claude-code/run-skill-tests.sh --integration 触发。核心测试脚本会执行一个端到端的验证，例如 test-subagent-driven-development-integration.sh 会：
- 准备：自动创建一个临时的 Node.js 项目和一份简单的实施计划。
- 执行：以
claude -p运行完整的技能流程。 - 验证：测试的精髓在于解析 Claude Code 生成的
.jsonl会话记录文件（而非终端输出），验证点包括：技能工具是否被调用；是否派遣了足够数量的子代理（通过Task工具）；子代理是否收到了完整的任务描述；实现顺序是否正确（如规格合规性审查在代码质量审查之前）；子代理是否进行了自我审查；最终生成的代码文件是否存在且测试通过；Git 提交历史是否符合预期。
Token 分析与成本透明度：集成测试会调用 analyze-token-usage.py 工具解析会话记录，给出主会话和每个子代理的详细 token 消耗及预估费用。这为优化技能和控制成本提供了数据视角。测试最佳实践强调：始终使用 trap 清理临时目录；必须从 SuperPowers 仓库根目录运行测试以确保技能能被发现；使用 --permission-mode bypassPermissions 和 --add-dir 授予测试所需权限；合理设置超时（如 --timeout 1800）。
4. OpenCode 插件测试：验证跨平台适配层的正确性
OpenCode 是 SuperPowers 支持的重要平台之一，其测试位于 tests/opencode/。测试分为无需启动 OpenCode 的基础验证和需要 OpenCode 实际参与的集成测试。
插件加载验证 (test-plugin-loading.sh)：此脚本在隔离环境中检查插件是否就绪，执行一系列关键检查：
- 插件注册：验证符号链接存在于 OpenCode 配置目录的
plugins/下，且目标文件存在。 - 技能目录：确认
skills/目录下存在SKILL.md文件，且数量大于 0。 - 关键技能存在：验证
using-superpowers技能是否存在，这是整个技能发现机制的引导技能。 - 语法与配置：验证插件 JavaScript 文件语法正确，且未包含误导性的旧路径配置。
通过 tests/opencode/run-tests.sh 脚本，可以运行基础测试（test-plugin-loading.sh 和 test-bootstrap-caching.sh），或加入 --integration 标志运行需要 OpenCode 实际参与的工具与优先级测试。
测试排错与最佳实践
综合各测试脚本，可以提炼出几条核心实践：
- 环境一致性：确保在 SuperPowers 仓库根目录下运行测试，并在
~/.claude/settings.json中启用本地开发市场插件。 - 权限授予：无头测试中必须使用
--permission-mode bypassPermissions和--add-dir授予文件系统访问权限。 - 验证真相来源：解析
.jsonl会话记录文件，而不是依赖终端输出。 - 合理设置超时：集成测试可能耗时 10-30 分钟，需通过
--timeout参数给予充足时间。
当测试失败时，结合 --verbose 标志查看完整输出，优先检查 Claude Code 是否安装、插件是否启用、技能文件是否存在于正确目录。
通过这四个层次的测试，SuperPowers 项目系统地保障了其技能在不同 AI 编程代理和平台上的行为一致性，为开发者将 TDD、系统化调试等工程实践固化到 AI 工作流中提供了坚实的质量基石。对于希望为 SuperPowers 贡献新技能或测试的开发者，可以参考如何提交高质量 PR 的指南，从编写测试开始。
FAQ
Q: 运行一次完整的集成测试大概需要多久？
A: 根据 docs/testing.md 文档，运行 subagent-driven-development 的集成测试通常需要 10 到 30 分钟，因为它会在无头模式下执行真实的实现计划并派遣多个子代理。
Q: 测试失败时，最常见的错误原因是什么？
A: 最常见的原因是环境配置问题：1) 没有在 SuperPowers 仓库根目录下运行测试；2) 本地开发市场插件（superpowers@superpowers-dev）未在 ~/.claude/settings.json 中启用；3) 没有使用 --permission-mode bypassPermissions 授予测试所需的文件权限。
Q: 显式技能请求测试中的“过早行动”具体指什么？
A: 它指代理在用户明确要求加载某个技能后，未等技能指令完全生效，就先执行了文件修改、命令运行等实质性的开发动作。测试脚本会检查在第一次调用 Skill 工具之前，是否存在这类非规划性的工具调用，以此判断代理是否遵循了“先学习技能再行动”的流程。