前阵子接手一个老项目代码结构乱到让人想摔键盘同事甩给我一个叫 Superpowers 的开源工具说“装上它至少能让你在 AI 编码助手上找回一点尊严”。我抱着试试看的心态折腾了两天结果发现这东西确实像名字说的那样给 Codex 这类 AI 助手直接装了一套“外挂技能包”。如果你也玩 Codex、Cursor 或者类似的 AI 编程工具正愁怎么让 AI 更听话、更稳定地干复杂活那这篇 Superpowers 使用指南值得你花几分钟读完。它本质上是一个开源技能库和运行时框架把平时散落在各种提示词里的“高难度动作”做成了可复用、可编排、可共享的技能包。我不需要每次重新写一大段 prompt只要调用技能名称AI 就会按技能里定义好的步骤、约束、检验规则去干活。最让我意外的是它对 Java 项目的支持多模块 Maven 工程的代码审查、重构建议、单元测试生成比我以前靠对话“挤牙膏”靠谱得多。下面我会从设计思路、安装配置、实际用法和踩坑记录这几个方面完整讲一遍保证你照着做就能跑起来。1. 为什么它叫 Superpowers解决 AI 编程的最大痛点1.1 AI 编码助手的现状与瓶颈用过 Codex 或类似 AI 助手的人应该都有同感在简单问题上它很惊艳但一旦遇到“改完 A 模块还要同步更新 B 模块的测试、C 模块的文档”这种多步骤任务它就开始飘了。原因很简单AI 对话本身是无状态的每个回合都得靠你重新解释背景步数一多就很容易自相矛盾。我自己踩过最惨的一次坑是让 AI 改一个接口签名结果它只改了实现类忘了改所有调用方导致编译直接炸掉。这种问题的根源不是 AI 智力不够而是缺少“任务结构”。就像你给一个聪明但没有任何工具的新员工安排工作他只能靠脑子记但如果你给他一份标准作业程序、一份检查清单、一套验证脚本他就能稳定发挥。Superpowers 解决的正是这个“缺工具、缺流程”的问题。1.2 Superpowers 的核心设计技能而不是提示词Superpowers 最核心的概念是“技能Skill”。一个技能就是一个目录里面包含了三个关键文件SKILL.md用来描述这个技能适合什么场景、有什么输入输出steps.md定义执行步骤verify.sh或verify.py用来在执行结束后做自动化校验。说白了它把“给 AI 的提示词”升级成了“给 AI 的操作手册 质量测试”。举个例子以前让 AI “给这段 Java 代码写单元测试”它可能会自由发挥生成一个没有 Mock、没有边界断言的测试。但如果你在 Superpowers 里装一个java-test-generator技能它会强制 AI 先分析被测类的所有公开方法再列出依赖和 Mock 点最后按项目既有的测试风格生成 JUnit 5 测试。每一个环节都有明确的检查项AI 的执行结果会稳定很多。1.3 我选择它的三个理由第一社区技能包够全。默认技能市场里已经有几十个常用包覆盖 Java、Python、前端、文档、数据库迁移等场景。第二它不绑定特定编辑器或 AI 服务。Codex、Cursor、甚至自研的 Agent 框架都能通过命令行或者插件方式挂进来我不需要为了它换工具。第三自定义成本极低。如果你有自己团队的代码规范只需要写一个 Markdown 文件加一个验证脚本就能做出一个私有技能。2. 安装与初始化5分钟跑通第一个技能2.1 环境要求与前置准备在动手安装之前让我先盘一下基础环境。Superpowers 主程序是用 Node.js 写的所以要求机器上有 Node.js 18 或更高版本。如果你平时也跑 Java、Maven 和 Gradle那正好因为部分 Java 技能包执行时会在本地起一个轻量分析器需要 Maven 与 JDK 11 以上。我自己的机器是 macOS但安装过程在 Windows 和 Linux 上也是一样的只是脚本路径细节略有不同这点后面会专门讲。还有一个容易被忽略的前置条件Superpowers 默认通过调用 Codex CLI 来执行技能里的“思考”和“操作”部分所以建议你先装好 Codex CLI 并且完成登录。如果你用的是 Cursor 或者其他插件也可以通过适配层接入但第一次跑通时最好先用 Codex因为官方文档对 Codex 的集成是最成熟的。2.2 安装主程序npm、Homebrew、源码三选一最省事的方式是用 npm 全局安装在终端里执行npm install -g superpowers/cli安装完成后检查一下版本能看到superpowers --version输出版本号就说明主程序没问题。如果你在 macOS 上更习惯用 Homebrew也可以用brew tap superpowers/tap brew install superpowers这两个方式二选一即可。我最初是 npm 装的后来想升级到 nightly 版本就改用源码方式跑克隆仓库后装上依赖就完事。但源码方式不适合所有人普通人用 npm 稳定版就够了。2.3 初始化工作区并验证技能装好主程序后进入你的项目目录执行superpowers init这条命令会在项目下创建一个.superpowers目录里面包含默认的配置文件config.json和技能注册表registry.json。初始化过程会问你要不要顺手安装“基础技能包”base-set里面包含code-review、refactor、test-generator这三个最常用的技能建议直接选 yes。验证是否成功也简单先运行superpowers skill list正常会看到code-reviewlatest、refactorlatest、test-generatorlatest之类的条目。如果列表是空的多半是网络问题或者 npm 源没有同步后面我会给排查方法。2.4 把技能挂到 Codex CLI 上这一步是很多教程没讲清楚的地方。只安装 Superpowers 还不够Codex 并不知道这个技能库的存在。我的做法是修改 Codex 的配置文件~/.codex/config.toml在[plugins]段加入 Superpowers 的适配器[plugins] superpowers npx superpowers codex-plugin保存后重启 Codex然后在对话中试着打一条带魔法前缀的指令 superpowers:code-review 检查 src/main/java 下的最近改动如果 Codex 返回了一段“正在加载技能 code-review……”的提示说明挂载成功。没有提示也别急检查下 npx 是否能正常找到superpowers/codex-plugin必要时直接全局安装它。3. 核心配置与技能管理让 AI 按你的规则干活3.1 配置文件逐字段拆解.superpowers/config.json是整个工具的灵魂我截一段自己项目的配置来讲{ version: 2, model: codex-default, timeoutSeconds: 120, skillsPath: ./skills, registries: [https://skills.superpowers.dev/registry.json], allowedTools: [shell, read, write, patch], hooks: { beforeExecute: echo 开始执行技能, afterVerify: echo 验证完成 } }model字段指定技能调用时默认使用的 AI 模型codex-default表示用 Codex 本身配置的默认模型timeoutSeconds很关键如果技能步骤多120 秒不够用我一般调到 300 秒skillsPath告诉 Superpowers 去哪里找本地自定义技能allowedTools是安全边界决定 AI 在执行技能时可以调用哪些外部工具为了稳妥我通常只开放read、write、patch和shell。这个配置还有一个容易坑人的地方timeoutSeconds如果设得太短复杂技能会在中途被强制中断而且不会返回任何有用的日志。建议初次使用先设 300 秒跑通后再根据实际步骤数做减法。3.2 技能市场与自定义技能Superpowers 有一个线上技能市场在线搜索的体验比手动写配置友好得多superpowers search test javac superpowers install javac-test-guru安装后技能会被自动放到skillsPath目录下。你也可以直接去 GitHub 上扒一个技能包放到本地目录后运行superpowers registry add ./path/to/skill来注册。自定义技能其实不难。比如我想让 AI 严格按团队规范写接口文档就新建一个目录skills/api-doc-writer里面放一个SKILL.md# API 文档编写技能 适用于 RestController 中新增接口的文档生成。 输入接口方法名、请求参数、响应实体。 步骤 1. 读取该 Controller 的类注释和已有接口文档模式。 2. 分析请求和响应 DTO 所有字段。 3. 按照团队模板输出中文 Markdown 文档。 约束不得杜撰字段含义必须标出来源代码文件。再配一个verify.sh检查文档里是否包含所有字段名如果缺失就退出非 0 状态码。这样 AI 想偷懒都不行验证脚本会在最后一步把关。3.3 Java 项目实战Maven 多模块重构案例热词里特别提到superpowers java我估计很多人在 Java 项目上踩过坑所以单独拿一个实际场景出来讲。上周我处理了一个 Maven 多模块项目结构是parent下面有core、api、admin三个子模块其中api模块大量依赖core的某个旧接口。我需要做的是把旧接口重构为新接口并且让所有调用方都跟着改。以前纯靠对话AI 经常只改一个模块就停手。现在我用的组合是先安装并加载java-module-hunter和refactor-safe-java两个技能。执行命令是superpowers:java-module-hunter 分析整个项目对 OldService 的引用这个技能会先在本地用 Maven 做一次全量编译然后利用grep和 Java 解析器找出所有引用点生成一个引用清单。接下来再调用superpowers:refactor-safe-java 将 OldService.retrieve 重命名为 NewService.load它会把之前生成的清单作为输入逐个模块执行修改每改完一个模块就尝试编译一次。如果某个模块编译失败技能会自动回滚该模块的改动并输出失败原因。我跑完一遍20 个引用点全部改完最后全项目mvn -q compile一次通过。这种体验靠裸 prompt 是很难复现的因为它没法做“改一个模块编译一次”的条件循环。我还试过让这个技能生成 Spring Boot 项目的单元测试。它默认会检查项目里有没有Mockito如果没有就会先在pom.xml里加依赖。生成的测试方法会带上DisplayName和边界断言覆盖率统计能达到项目设定的阈值。对比我以前手动纠正 AI 测试代码的体验这确实称得上“超级能力”。3.4 把技能装进 WorkBuddy 团队频道搜索热词里还有人问 “worbuddy 怎么用 superpowers”这里我说一下。WorkBuddy 是一个团队 Agent 编排工具主要用来把多个 AI 任务串联成工作流。Superpowers 官方提供了一款桥接插件叫superpowers/workbuddy-bridge安装后可以在 WorkBuddy 的节点里直接调用技能。配置也是一条命令的事superpowers workbuddy connect --channel dev-bot连好之后团队成员在 WorkBuddy 频道的任务描述里写superpowers skill:code-review 模块api技能就会作为整体任务进入 WorkBuddy 的任务队列。它最大的价值是让团队共享同一套技能配置不会出现两个工程师用同一个 AI 工具却产出不同风格结果的情况。不过这个桥接插件还比较年轻我实际用下来在并发数高的时候会出现任务重复执行建议用的时候把 WorkBuddy 的并发上限调到 2。4. 我这周遇到的三道坑与排查实录4.1 技能找不到路径与注册表问题我刚开始自定义技能时明明把目录放在了skills/api-doc-writer下但执行superpowers skill list就是看不到。后来发现是config.json里的skillsPath被我写成了绝对路径/Users/me/.superpowers/skills而实际上我的技能已经在项目本地。Superpowers 默认会用项目相对路径改成./skills后再superpowers registry scan --force就能发现。还有一个问题是技能市场的注册表如果某个时段拉不下来会出现“skill not in registry”。这时候不要慌先跑superpowers registry refresh如果还是不行就绕开线上市场直接从 GitHub 下载技能包放在本地skillsPath下面然后用superpowers registry add local临时注册。4.2 Codex 调用超时技能颗粒度拆得不够细有一个技能在我本地执行总是到 80 秒左右被中断查~/.superpowers/logs/superpowers.log发现错误是TimeoutError: execution exceeded 120s。我当时顺着日志看执行记录发现这个技能把“读取文件、生成分析报告、修改代码、执行测试”全放一起做步骤又长又串行。解决办法是把任务拆成两个技能先用analysis-report生成改动方案再用apply-patch执行修改并测试。这样每一步的操作量小了不再超时。4.3 Java 技能在 Windows 上无法执行Shell 兼容性坑Java 技能包里的校验脚本大多是.sh文件在 Windows 上如果直接执行会报/bin/bash找不到。我的解决方法是安装Git Bash并把它配置到系统PATH里然后修改config.json加一段execution: { shell: C:\\Program Files\\Git\\bin\\bash.exe }这样 Superpowers 所有技能脚本都会走 Git Bash问题就解决了。如果你在用 Windows 自带的 PowerShell也可以把verify.sh全部改成verify.ps1但这是个体力活我暂时没做。4.4 常用问题速查表现象可能原因解决办法skill list为空网络无法访问技能市场执行superpowers registry refresh或本地安装技能后registry add local技能执行中途卡住AI 模型上下文太长或步骤过多调大timeoutSeconds到 300或拆分技能Codex 不响应superpowers:指令插件未加载或 npx 找不到包直接全局安装superpowers/codex-plugin重启 CodexJava 校验脚本失败缺少 Maven 或 JDK 版本不匹配运行mvn -v和java -version检查升级到 JDK 11Windows 下.sh脚本报错Shell 解释器缺失配置config.json使用 Git Bash 路径5. 给新手的 Superpowers 使用建议5.1 先做减法只需要三个基础技能我见过很多新手把技能市场里能装的包全部装进去结果反而不知道怎么调。我的建议是先装三个code-review用于日常改动审查refactor用于结构重构test-generator用于补测试。等这三个用顺手了再按实际项目需要扩展。技能不是越多越好每多一个包配置文件和验证脚本的维护成本就多一分。5.2 用版本管理你的技能配置把.superpowers目录纳入 Git 管理是特别重要的操作。因为技能包的版本升级可能会改变调用方式如果你不同机器的配置不一致很容易出现“本地没问题、同事报错”的情况。我还会给config.json和自定义技能单独拉分支每次升级技能前先跑一遍现有项目的回归验证确认没问题再合并到主干。5.3 我目前的工作流参考现在我的日常开发流程已经很固定了。接到需求后先让superpowers:code-review扫描改动范围再让superpowers:refactor生成重构方案最后用superpowers:test-generator补测试。整个过程基本不用我写大段提示词我只需要决定什么时候接受 AI 的建议。最后再分享一个小技巧。如果你和我一样要长时间开着 Codex 跑技能一定要在config.json里开hooks.afterVerify比如让它自动把验证结果写入日志文件。这样就算你走开了一会儿回来后也能通过日志复盘 AI 到底干了什么不会两眼一抹黑。Superpowers 这个工具的价值就在于把“AI 玄学”变成了“可验证的工程流程”提前祝你也玩得顺手。