跳转至

08 测试与演进：把方法论也当软件维护

一、为什么 Markdown 项目仍然需要测试

Superpowers 的失败不一定表现为编译错误，也可能是：

  • manifest 指向了错误目录；
  • hook 输出了错误 JSON 字段；
  • skill description 不再能触发发现；
  • 平台工具名已经变化，但适配说明没有更新；
  • 迁移到新 harness 后某个工作流在关键节点丢失。

所以测试目录不是“验证代码库”的附属品，而是在验证过程协议是否仍可被宿主加载和执行。

二、测试矩阵

静态结构
  ├── plugin manifest / marketplace manifest
  ├── skill 目录与 frontmatter
  └── shell lint

运行时桥接
  ├── hooks/session-start
  ├── OpenCode plugin loading / tools / priority
  └── Pi extension

工作流行为
  ├── explicit skill requests
  ├── Claude Code skill tests
  ├── SDD workspace / task review
  └── brainstorm server lifecycle

这几层分别防御不同问题，不能只运行一类测试就得出“插件可用”的结论。

三、Manifest 测试：防止“能装但不能用”

tests/codex/test-marketplace-manifest.sh 和 test-package-codex-plugin.sh 检查 Codex manifest、市场信息和打包结果；tests/kimi/test-plugin-manifest.sh 检查 Kimi 入口；tests/claude-code 则覆盖 Claude 相关安装和技能行为。

这类测试通常应关注：

  • JSON 可解析；
  • 必填字段存在；
  • skills 指向真实目录；
  • 版本和名称一致；
  • 打包后路径不丢失。

它们成本低、失败定位清楚，应该在完整集成测试前运行。

四、Hook 测试：验证输出协议而不是文案

tests/hooks/test-session-start.sh 的重点不是检查每个英文句子，而是验证：

  1. 脚本能从插件根目录找到 using-superpowers；
  2. 内容中的反斜杠、引号和换行被正确转义；
  3. 不同环境变量得到正确 JSON 字段；
  4. 输出可被 JSON parser 读取；
  5. 错误路径不会产生半截或非法 JSON。

这是一个很好的测试边界：行为是“宿主能消费额外上下文”，而不是“实现必须使用某种 shell 写法”。

五、显式技能请求测试：验证发现机制

tests/explicit-skill-requests/ 里有多个 prompt 场景，例如用户直接说“请使用 brainstorming”“请用 subagent-driven-development”“我知道 SDD 是什么”。这些场景测试 Agent 是否会在不同表达方式下识别和调用正确技能。

为什么要区分这些 prompt？因为技能发现不是字符串匹配这么简单：

  • 用户可能直接点名技能；
  • 用户可能只描述问题，不说技能名；
  • 用户可能试图跳过流程；
  • 用户可能在多轮会话中间才提出使用技能。

覆盖这些压力场景，可以发现 description、using-superpowers 和多轮规则之间的断裂。

六、平台集成测试：先测最窄路径

tests/opencode/ 包含 bootstrap caching、plugin loading、priority 和 tools 等测试；tests/pi/test-pi-extension.mjs 验证 Pi 扩展。它们的价值在于检查“适配层是否仍保持薄”：

  • 是否只加载一次必要内容？
  • 插件优先级是否正确？
  • tool 名称和参数是否能完成预期调用？
  • extension 是否在宿主生命周期中注册成功？

平台测试失败时，优先检查 manifest、入口脚本和工具映射，而不是立即修改核心技能正文。

七、Brainstorm server 与可视化能力

skills/brainstorming/scripts/ 下的 server、start/stop 脚本和 tests/brainstorm-server/ 测试说明，Superpowers 也包含一个可选的视觉 companion 能力。它有自己的认证、branding、browser launcher、生命周期和 WebSocket 测试。

这部分说明一个重要边界：可视化能力是 brainstorming 的可选增强，不应该阻塞纯文本设计流程。server 的测试覆盖独立生命周期，正是为了让 companion 出问题时，核心 brainstorming 仍可工作。

八、版本与同步脚本

仓库包含：

  • scripts/bump-version.sh：版本变更；
  • scripts/package-codex-plugin.sh：打包 Codex 插件；
  • scripts/sync-to-codex-plugin.sh：同步适配内容；
  • scripts/lint-shell.sh：shell 脚本静态检查。

这些脚本把跨文件一致性和发布重复动作自动化。对一个以 Markdown 为主的项目而言，脚本的价值不在于“有更多代码”，而在于减少人工漏改 manifest、漏带资源和忘记 lint 的概率。

九、从设计文档到实现计划的历史

docs/plans/ 和 docs/superpowers/plans/ 里保存了多次功能设计与实施计划，例如 OpenCode 支持、Codex 兼容、视觉 brainstorming、worktree、SDD review loop 等。它们提供了一个很有价值的演进证据：

  1. 先写设计，确认范围和取舍；
  2. 再写按任务拆分的实现计划；
  3. 实现后保留计划和结果，形成下一次迭代的上下文；
  4. 测试文件随功能一起增加，而不是事后补一层。

这让仓库本身成为 Superpowers 方法论的 dogfooding：它用自己的工具和文档流程维护自己。

十、推荐的发布前检查表

[ ] 所有 manifest 都能解析，版本一致
[ ] 所有 skills/*/SKILL.md 都有 name + description
[ ] hook 在各环境下输出合法 JSON
[ ] shell lint 通过
[ ] 平台加载测试通过
[ ] 关键 explicit skill request 通过
[ ] 版本 / 变更说明已更新
[ ] 新鲜测试输出已保存
[ ] Git diff 只包含本次变更

小结

Superpowers 把“方法论”当成一个需要回归测试和版本管理的软件产品。它不仅验证代码能跑，还验证技能能被发现、hook 能被宿主消费、适配层能正确映射，以及新功能不会破坏现有开发流程。