Superpowers v5.1.0 是当前最新版本，其核心更新是完成了工作树技能（using-git-worktrees， finishing-a-development-branch）的 TDD 重写，并统一了代码审查流程，移除了 named agent。从 v5.0.0 到 v5.1.0，项目围绕基础设施稳定性（如零依赖 brainstorm server、ESM 兼容性修复）、工作流效率（如内联自评审取代子代理评审循环）以及跨平台兼容性（如支持 Copilot CLI、优化 OpenCode 注入）进行了持续迭代。理解这些版本变化有助于用户平稳升级，并充分利用 using-superpowers 所定义的技能发现与工作流闭环。

SuperPowers 版本与发布重点：从 v5.0.0 到 v5.1.0 的功能变化

Superpowers 是一个面向 coding agents 的可组合技能库。其版本迭代记录了在稳定性、跨平台兼容性、工作流效率及开发者体验上的持续改进。理解从 v5.0.0 到 v5.1.0 的核心变化，对于现有用户平稳升级、新用户选择合适版本以及贡献者理解项目方向至关重要。本文将系统梳理关键版本更新，并提供实用的版本同步指南。

如何查询并同步 Superpowers 的当前版本

在升级或排查问题前，首先需要确认仓库内各平台插件清单的版本号是否一致。Superpowers 仓库内嵌了一套版本同步工具，由配置文件 .version-bump.json 和脚本 scripts/bump-version.sh 组成。

步骤 1：运行版本检查命令

在仓库根目录下，执行以下命令以查看所有声明文件中的版本号，并检测是否存在版本漂移（drift）。

./scripts/bump-version.sh --check

此命令会读取 .version-bump.json 中 files 字段列出的所有文件（如 package.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json 等），输出每个文件的当前版本。package.json 中的当前版本为 5.1.0。如果输出中显示的版本号不一致，脚本会明确提示 DRIFT DETECTED，并列出不同版本及其对应文件数量。

步骤 2：执行版本审计

如果检查发现不一致，或想主动查找仓库中可能遗漏的旧版本字符串，可运行审计命令：

./scripts/bump-version.sh --audit

该命令会先执行 --check，然后确定当前最普遍的版本号，在整个仓库中进行 grep 扫描（排除了 node_modules、.git 以及 .version-bump.json 中 audit.exclude 列出的其他目录和文件）。如果发现有未在 .version-bump.json files 字段中声明的文件包含了该版本字符串，会列出这些文件，提示维护者决定是将其加入版本同步列表还是排除在审计之外。

步骤 3：执行版本号更新

确认需要升级到新版本（例如从 5.0.7 到 5.1.0）后，使用 bump 命令：

./scripts/bump-version.sh 5.1.0

该命令会遍历 .version-bump.json 中 files 列表里的每一个文件，使用 jq 工具更新其对应的 JSON 字段。完成后，会自动执行一次 --audit，确保没有遗漏。

错误表现与验证：如果 .version-bump.json 文件丢失，脚本会报错退出。版本同步成功的验证方法是再次运行 --check 命令，确认所有文件版本号一致且为目标版本 5.1.0。

版本演进核心要点解析

从 v5.0.0 到 v5.1.0，Superpowers 的更新围绕着“完善核心工作流”、“增强跨平台一致性”和“优化运行时性能”三条主线展开。

v5.0.0 到 v5.0.5：基础设施的稳定性与现代化

这一阶段的重点是优化 brainstorm server 等关键基础设施，解决其可靠性和兼容性问题，并重构核心工作流。

v5.0.0：工作流重构与破坏性变更
- 目录结构重组：specs 和 plans 的存储路径变更，需迁移现有文件。
- 强制子代理开发：在具有子代理能力的平台上，writing-plans 强制要求使用 subagent-driven-development。
- 斜杠命令弃用：/brainstorm、/write-plan、/execute-plan 命令被标记为弃用。
- 引入可视化头脑风暴：可选功能，允许在浏览器中展示 mockup、图表等视觉内容。
v5.0.2：零依赖重构：这是 brainstorm server 的重大重构。移除了所有 node_modules 依赖（如 Express、Chokidar），改用 Node.js 内置模块实现了完全自包含的服务器。这消除了运行时 npm install 的需要，简化了安装和部署。同时，新增了空闲 30 分钟自动退出和所有者进程跟踪机制，防止孤儿进程。
v5.0.5：ESM 兼容性修复：在 Node.js 22+ 环境中，由于仓库根 package.json 设置了 "type": "module"，导致 brainstorm server 使用的 require() 失败。修复方法是将 server.js 重命名为 server.cjs，强制将其作为 CommonJS 模块加载。

v5.0.6 到 v5.0.7：工作流优化与平台适配

后期版本继续打磨核心技能，并扩大了对新兴 AI 编码平台的支持。

v5.0.6：内联自评审取代子代理评审：这是一个效率优化。原先的 brainstorming 和 writing-plans 技能会派遣子代理对 spec 和 plan 进行多轮评审，耗时约 25 分钟。新版将其替换为内联的自评审检查清单，在约 30 秒内完成，缺陷捕获率相当，显著提升了速度。
v5.0.7：Copilot CLI 支持与 OpenCode 修复：
- GitHub Copilot CLI：正式支持 Copilot CLI v1.0.11+。通过检测 COPILOT_CLI 环境变量，session-start 钩子会以 Copilot CLI 要求的 additionalContext 格式注入上下文。
- OpenCode 修复：将启动引导注入从系统消息改为首个用户消息，避免了系统消息重复导致的 token 浪费，并解决了与 Qwen 等模型的多系统消息兼容性问题。

v5.1.0：TDD 重写与流程统一

v5.1.0 是一个重要的功能版本，其更新内容直接关联到 Superpowers 的核心方法论与开发者贡献体验。

Legacy slash commands 移除：v5.0.0 中弃用的 /brainstorm、/execute-plan 和 /write-plan 命令被彻底移除。用户现在必须直接调用对应的技能（如 superpowers:brainstorming）。
Code Review Consolidation：移除了 superpowers:code-reviewer 这个唯一的 named agent。现在，代码审查流程统一为派遣 Task (general-purpose) 并附带一个位于 skills/requesting-code-review/code-reviewer.md 中的自包含提示模板。这简化了子代理的调度，并修复了之前独立维护的审查者人格与检查清单可能漂移的问题。
工作树技能的 TDD 重写：using-git-worktrees 和 finishing-a-development-branch 技能经过了测试驱动开发（TDD）的重写。新版本增加了环境检测（判断是否已在隔离工作树中）、在创建工作树前明确要求用户同意、优先使用平台原生工作树工具等改进，提升了跨平台兼容性和用户体验。
贡献者指南新增 AI Agent 预提交检查：在 CLAUDE.md（符号链接到 AGENTS.md）顶部新增了针对 AI 代理的指南，包括提交 PR 前的检查清单和明确不接受的变更类型，旨在提高由 AI 代理生成的 PR 质量。
Codex 插件同步工具：新增 sync-to-codex-plugin 脚本，用于将 Superpowers 仓库自动同步到 OpenAI Codex 插件市场。
OpenCode bootstrap 缓存：修复了 OpenCode 插件中 getBootstrapContent() 每次代理步骤都重复读取文件的性能问题，现在该函数在会话生命周期内只读取一次文件并缓存结果。

版本同步机制详解

Superpowers 通过 .version-bump.json 和 scripts/bump-version.sh 确保所有平台插件清单的版本号保持一致。

.version-bump.json 是版本同步的核心配置文件。其 files 字段声明了需要进行版本同步的文件列表以及每个文件中版本号所在的 JSON 路径：

{
  "files": [
    { "path": "package.json", "field": "version" },
    { "path": ".claude-plugin/plugin.json", "field": "version" },
    { "path": ".cursor-plugin/plugin.json", "field": "version" },
    { "path": ".codex-plugin/plugin.json", "field": "version" },
    { "path": ".claude-plugin/marketplace.json", "field": "plugins.0.version" },
    { "path": "gemini-extension.json", "field": "version" }
  ],
  "audit": {
    "exclude": [
      "CHANGELOG.md",
      "RELEASE-NOTES.md",
      "node_modules",
      ".git",
      ".version-bump.json",
      "scripts/bump-version.sh"
    ]
  }
}

scripts/bump-version.sh 脚本基于此配置工作，其核心逻辑如下：

--check：读取每个声明文件的指定 JSON 字段，比较它们的版本值，报告是否一致。这是检测版本漂移的第一道防线。
--audit：在 --check 基础上，确定当前主流版本号，然后在整个仓库中扫描（排除 audit.exclude 中的路径），查找包含该版本字符串但未在 files 中声明的文件。这有助于发现可能被遗漏的版本引用。
bump <new-version>：遍历 files 列表，使用 jq 工具更新每个文件的指定字段为新版本号。这是执行版本升级的实际操作。

这套机制确保了当版本号变更时（如从 5.0.7 升至 5.1.0），所有关联的插件清单都能被一次性、无遗漏地更新，保证了用户通过各平台安装 Superpowers 时，获得的技能库版本是确定且一致的。

FAQ

Q: 如何验证我当前安装的 Superpowers 版本？ A: 最直接的方法是检查你所用平台对应的插件清单文件（如 Claude Code 的 .claude-plugin/plugin.json 或 OpenCode 的 package.json）中的 version 字段。也可以在仓库中运行 ./scripts/bump-version.sh --check，确认所有文件版本一致且为你期望的版本（当前最新为 5.1.0）。

Q: 升级到 v5.1.0 后，我还能使用 /brainstorm 命令吗？ A: 不能。从 v5.1.0 开始，/brainstorm、/write-plan、/execute-plan 等斜杠命令已被彻底移除。你应该直接描述你的意图，让 using-superpowers 工作流自动调度合适的技能（如 brainstorming）。这是为了引导代理更自然地使用技能系统。

Q: 为什么我在 Node.js 22+ 环境下无法启动 brainstorm server？ A: 这是 v5.0.5 之前的一个已知兼容性问题。由于仓库根 package.json 的 "type": "module" 设置，导致 brainstorm server 原先的 server.js 中的 require() 调用失败。解决方法是确保你使用的是 v5.0.5 或更高版本的 Superpowers，该版本已将服务器文件重命名为 server.cjs 以解决此问题。

SuperPowers 版本与发布重点：从 v5.0.0 到 v5.1.0 的功能变化 #

如何查询并同步 Superpowers 的当前版本 #

版本演进核心要点解析 #

v5.0.0 到 v5.0.5：基础设施的稳定性与现代化 #

v5.0.6 到 v5.0.7：工作流优化与平台适配 #

v5.1.0：TDD 重写与流程统一 #

版本同步机制详解 #

FAQ #