1. 为什么原生 Codex 会“只动嘴不动手”如果你一直用 Codex 这类 AI 编程助手大概率遇到过这个场景你把一段编译报错贴进对话希望它直接把代码改掉、跑通测试、再顺手生成一条 commit message结果它只回给你一段“建议使用如下方案”的说明文字。你没看错问题不在模型本身而在工具链缺了一层“从建议到动作”的转换层。这就是我折腾 superpowers 的起点。superpowers 是一个社区驱动的开源工具箱目标很直接给 AI 编程助手装上可复用的“技能”。它不是一个新模型也不替代 Codex而是一套脚本、配置和编排规则。它让 AI 不只是“告诉你该怎么做”而是按你定义好的步骤去执行命令、读写文件、跑测试、收集结果再决定下一步。如果你手里已经有 Codex 或其他类似助手但又嫌它“动嘴不动手”那 superpowers 基本就是冲着你这个痛点来的。热词里经常能看到“codex superpowers”“superpowers 使用指南”说明这工具在 AI 编程圈子里已经有了一批固定用户。今天我就把这段时间的安装、使用、踩坑经历摊开聊涉及 Java 项目的实战配置以及和 worbuddy 这类本地编排工具的配合方式。1.1 原生工作流为什么会卡住先说原生 Codex 的工作流。传统上你和它的交互是“对话式”的你提需求模型给方案然后你自己去终端执行命令、打开文件修改代码、再手动验证结果。模型当然可以在某些模式下直接调用工具但大多数情况下它缺少一个稳定的“能力框架”。你没有告诉它该用哪个命令清理依赖它可能就只会建议你运行mvn clean你不知道它能安全地批量替换文件它就不会主动去搜代码库里的重复模式。问题的本质是模型有“知识”但没有“手”。它知道许多操作的最佳实践却无法保证每次都用同一套经过验证的流程去完成。尤其在一个多模块项目里改一个公共接口可能波及五个调用方如果没有脚本化的步骤AI 很容易只改完第一处就往回交差。你可能也试过在 prompt 里写“请帮我修改所有相关调用处”模型确实会答得很好但实际执行时经常漏文件、漏测试因为它拿到的上下文始终不完整。superpowers 把这件事拆成了两层底层是已经存在的 CLI 能力比如执行 shell、读文件、调用编译器上层是“技能库”。每个技能是一份人类可读的 Markdown 文件里面写了触发条件、执行步骤、校验规则和失败处理方式。模型读到这份文件就是在按一份标准操作规程SOP干活。这比单纯靠 prompt 稳定得多因为技能文件不依赖模型当天的“理解状态”它只要按步骤解析和执行输出结果就可控许多。1.2 能力分层与“超能力”到底指什么我习惯把它理解成三层能力第一层是“感知”AI 能列目录、读文件、搜索符号。原生工具也多少能做但 superpowers 会让你显式声明“这个技能需要先收集哪些上下文”第二层是“执行”AI 能运行构建命令、修改文件、执行测试。superpowers 用明确的步骤模板限制 AI 不要自由发挥第三层是“编排”AI 能根据结果自动决定下一步。例如编译失败后自动重试、把日志丢给另一个技能分析。不少教程把它叫作“超能力”不是模型突然变聪明了而是它可以从你的技能库里选用经过验证的工具。好比一个人没有三头六臂但给他一套顺手的外骨骼很多重体力活就能稳稳落地。用在你自己的项目里就是那堆“你不想每天重复十遍”的操作依赖检查、代码格式修复、自动生成 Java Bean 的单元测试初稿等。有人会问这些能力我全写在系统 prompt 里不行吗表面上可以但 prompt 会越写越长改起来也容易互相冲突。superpowers 把技能拆成独立文件每个文件只解决一个具体问题既能单独复用也能组合调用。更重要的是Markdown 文件可以被 review可以被测试可以被不同项目共享。这个设计思路和代码模块化的逻辑是一模一样的。现在对 superpowers 有了概念下一步就是把它装进环境。这地方看起来简单实际坑不少。2. 安装 superpowers环境准备与最容易踩的三个坑我是在一台 macOS 机器上做的安装Node.js 18 和 Python 3.10 都常驻。之所以强调这两个运行时是因为目前社区常见版本的 superpowers 需要 Node 侧做技能调度Python 侧负责一部分文件分析和代码解析。如果你只跑纯 Markdown 技能Python 不一定必需但集成 Java 项目时建议都配齐。2.1 前置条件与版本选择安装前先确认几件事你的系统里有没有 Node.js 16 以上版本很多技能依赖node:fs、child_process和 npm 包版本太低会出现Error: Cannot find module一类问题有没有可用的包管理器npm、pnpm 或 yarn 均可建议统一用 npm因为多数示例给的命令是 npm如果要在 Java 项目里用确认JAVA_HOME已正确设置superpowers 在调用 Maven 或 Gradle 时会通过子进程继承环境变量JAVA_HOME如果指向旧 JDK后面跑出的结果会很迷。版本选择上我见过有人直接 clone 仓库跑 dev 分支结果每天都要拉更新。我的建议是优先用发布稳定版本。那么怎么区分稳定版看包名是否带latest标签或者安装时是否显示版本号。对新手来说直接使用包管理器装 release 版本最稳妥。如果你所在团队已经有统一的 Node 版本管理工具比如 nvm、fnm我建议在项目根目录加一个.nvmrc文件写明当前验证过的 Node 版本。superpowers 对 Node 版本差异比较敏感团队统一版本能减少很多“在我电脑上可以用”的鬼故事。2.2 三种安装方式与推荐路径第一种是全局安装适合个人电脑npm install -g superpowers/cli superpowers --version执行完后如果输出类似1.x.x的版本号说明核心调度器装好了。第二种是项目级安装适合团队协作时锁定版本npm install --save-dev superpowers/cli npx superpowers initinit会生成一个.superpowers/目录里面放着默认技能和配置文件。推荐团队用这种因为它把技能文件直接纳入版本库其他人 clone 后不需要额外全局安装减少版本漂移。第三种是手动 clone 仓库适合想改技能源码的深度用户。这一步需要你把skills/目录软链到自己的用户目录或项目目录。命令就不展开仓库 README 里写得很清楚。但我不建议新手一上来就 clone因为你会被无数分支干扰反而搞不清什么是稳定的。初始化完成后的目录结构大概长这样your-project/ ├─ .superpowers/ │ ├─ config.yml │ └─ skills/ │ ├─ check-maven-conflicts.md │ ├─ generate-junit-test.md │ └─ fix-compile-error.md ├─ pom.xml └─ src/config.yml在这里起到总闸门的作用技能执行时的命令白名单、输出大小限制、默认编码都可以在里面配置。skills/目录下放的就是一个个可复用的技能文件。把这个目录提交到 Git相当于团队所有人都能共享同一套“操作手册”。2.3 安装过程中的常见报错与处理我安装时踩过三个比较典型的坑列成表格供你快速对照。现象原因处理办法superpowers: command not foundnpm 全局 bin 目录不在 PATH执行npm prefix -g找到路径添加到 shell 的 PATHError: Cannot find module superpowers/coreNode 版本过低或依赖没装上先npm install -g npmlatest再重装 global 包运行技能时中文路径乱码终端字符集和文件编码不一致在 shell 配置里强制export LANGen_US.UTF-8技能文件统一 UTF-8 编码第一个坑几乎所有人都会遇到。macOS 上 nvm 安装的 Node全局包目录通常不在默认 PATH 里安装完还要手动在~/.zshrc里补一行export PATH$(npm prefix -g)/bin:$PATH。Windows 上则常见于 npm 全局目录权限不够建议用cmd以管理员身份重装或者改用npx superpowers触发。第二个坑是升级 Node 后才出现的。因为旧版本 Node 加载不了新的 ESM 语法superpowers/cli装上了但启动就报错。把 Node 升到 18 以上基本能解决。第三个坑其实不算工具的问题更多是项目文件编码。Java 项目里如果代码注释是 UTF-8而终端默认读成 GBKAI 在执行搜索时会把字符匹配错乱表现就是“明明关键词存在但技能报告没找到”。装好之后的第一件事不是急着写技能而是把官方示例跑一遍确认调度器能正常调起命令。等跑通一个最小闭环再考虑接入自己的项目。这也是我喜欢这个工具的地方它不会强制你先看一堆文档而是用示例技能把你带入使用语境。3. 核心用法从“问一句答一句”到“跑一个多步骤自动化任务”安装算是热身真正拉开差距的是用法。superpowers 的核心价值不在于多了一个聊天窗口而在于它能把多步操作固化成一个可重复的技能。下面我按从浅到深的顺序讲。3.1 最基础的调用逻辑清单、查看与运行我习惯先看当前环境里有哪些技能可用superpowers list输出会列出一堆技能名比如fix-compile-error、generate-junit-test、scan-dependency-tree等。想知道具体技能怎么用不一定要打开文件superpowers show fix-compile-error它会打印技能的 frontmatter 和步骤摘要相当于看说明书。真正执行一条技能也很直接superpowers run fix-compile-error --file src/main/java/com/example/Demo.java如果你用的是 Codex 作为前端还可以在对话里直接说“用 fix-compile-error 技能处理当前编译错误”Codex 会去技能库匹配。superpowers 的作者在示例中很喜欢这种“自然语言触发”的方式因为它最贴近人的思维。有个细节要注意技能内部会定义它需要几个参数比如--file是必填项。如果漏填它不会傻傻执行而是返回参数校验错误。这比让 AI 自己猜路径靠谱得多。实际用下来这个校验机制帮我挡住了大概一半的误操作。比如generate-junit-test如果不传--class参数AI 很可能随便找一个类来生成测试最后产出一堆没用的文件。有了参数校验它宁可停下来问你要参数也不会自作主张。3.2 自定义技能把重复工作固化成“超能力”这才是 superpowers 真正值钱的地方。一个技能本质上就是一个带规范结构的 Markdown 文件通常放在.superpowers/skills/下。我给你看一个精简的示例用来扫描 Maven 项目的依赖冲突--- name: check-maven-conflicts description: 检查 Maven 依赖树中的版本冲突输出冲突列表 arguments: - name: modulePath required: true description: 目标模块的目录路径 steps: - run: | cd {{modulePath}} mvn dependency:tree capture: depTree - analyze: | 从 {{depTree}} 中识别同一 groupId:artifactId 出现多个 version 的行 - output: | 将冲突列表写成 markdown 文件 conflict-report.md failure: - run: echo 技能执行失败这个例子是我平时很常用的形态。steps里的每一条既可以是run去执行 shell 命令也可以是analyze让 AI 解读上一步的输出还可以是output生成交付物。AI 在运行技能时会严格按 steps 顺序执行而不是自由发挥。我建议第一次自定义技能时不要贪多。先挑一个你每周至少做三次的操作比如“清理 target 目录中的过期快照包”或者“为指定 Service 类生成 Controller 模板”。写好后跑一遍再根据失败日志迭代。这个过程会让你的项目沉淀出一套属于团队自己的操作手册后面新同事上手也会更快。另外要注意变量插值的转义问题。{{modulePath}}这种方式虽然方便但如果技能描述里本身就有双大括号比如要讲解 Java 模板字符串就会导致解析错乱。我的经验是在步骤里尽量避免直接出现看起来像变量的双大括号必要时可以拆成两行写或者在技能文件里加一行注释标明“这不是变量”。这类问题第一次遇到时会觉得很莫名其妙但只要记住“从外到内替换”的原则就能排查清楚。3.3 在 Java 项目里的实战配置热词里有“superpowers java”我也确实主要拿它来处理 Java 项目。最常用的组合是这样用scan-dependency-tree技能自动收集依赖情况用generate-junit-test技能给工具类生成边界测试用fix-compile-error技能做编译失败后的自动修复。先给 Java 项目的根目录运行初始化cd your-java-project npx superpowers init --java--java参数会在.superpowers/skills里多生成几个 Java 相关技能模板同时把.superpowers/config.yml里的build_tool自动识别为 maven 或 gradle。有一次我项目里同时存在pom.xml和build.gradle它优先识别了 maven导致一些 Gradle 模块的技能参数报错。解决方案是在配置文件里显式声明java: buildTool: gradle然后跑一个比较复杂的任务让超级技能 “add-unit-test-for-module” 给某个模块新增测试并且执行gradle test --tests验证。整个流程大概是这样superpowers run add-unit-test-for-module \ --module core \ --class UserService \ --testFramework junit5它会自动完成定位UserService.java、读取方法签名、生成UserServiceTest.java、在build.gradle加入 JUnit 依赖如果有需要、运行测试并把结果反馈回来。这个过程中 AI 会多次读取文件、写入文件、执行命令等于一口气做完以前需要半小时的机械劳动。这里要特别提醒一点Java 项目中最容易翻车的不是生成代码而是 Lombok 注解。如果项目用了 LombokAI 读源码时看不到 getter/setter生成测试时可能会直接调用user.getName()导致编译失败。我的办法是给技能文件里加一条前置步骤- analyze: | 检查类是否标注了 Data 或 Getter若存在则假设 getter 已生成并在生成测试代码时直接使用。这个细节很有用能避免一半的“AI 写测试跑不过”问题。4. 与 worbuddy 等辅助工具协同组合拳的打法在实际工程里superpowers 很少单独出场它更像是“技能执行引擎”。而热词里还出现了 “worbuddy 怎么用 superpowers”我理解是在问如何把 superpowers 挂到本地工作流工具中使用。我自己的做法是把 superpowers 和 worbuddy 这类编排界面结合起来。4.1 worbuddy 到底是什么角色我接触的 worbuddy 是一个偏本地化的工作流管理工具它可以把多个 CLI 工具、脚本和 AI 助手的操作统一到一个面板上。你可以简单把它理解成一个“命令驾驶舱”它关注的是什么时候触发什么任务、任务之间怎么流转而 superpowers 关注的是每个任务内部怎么高质量完成。两者并不冲突。打个比方worbuddy 是交通调度中心superpowers 是城市里每个专项作业车队。调度中心下发“处理这个 Maven 模块的构建问题”车队内部的技能流程就会自动拆解、执行、回报结果。没有调度中心你还能手动呼叫车队有了调度中心整个流程就能半自动串起来。4.2 集成方式与工作流设计我在本地把 superpowers 接入 worbuddy 时走了两步在 worbuddy 的任务定义里把执行命令指向 superpowerssuperpowers run {{skill_name}} --module {{module_path}}在 worbuddy 的触发条件里配置监听 Git 分支的 push 事件。比如 push 到dev分支时自动对变更目录跑一轮fix-compile-error和generate-junit-test。实际跑起来之后一个常见的多任务流程可能是这样的提交代码worbuddy 监听到变更调用scan-dependency-tree收集依赖信息识别出新增的Service类调用generate-junit-test生成初版测试运行mvn test -Dtest*ServiceTest测试失败后自动调起fix-compile-error尝试修复最后把结果汇总推送到群里或者生成报告。这套链路的好处是每次迭代都一样不会因为 AI 今天状态好就多干一步状态不好就少干一步。“可重复”是我觉得超级技能最难得的品质。在集成时我还建议先跑一次“最小闭环”只监听一个非常安全的目录比如src/test/java让技能只做测试生成。确认流程稳定后再逐渐放开到src/main/java等核心目录。如果你一上来就让工作流监听整个仓库AI 可能在一次 push 后面临几十个文件的变更技能执行时间过长容易半路超时。4.3 集成时的权限与安全边界组合起来之后权限问题会放大。因为 worbuddy 可以监听 Git 事件来自动执行它拥有的权限可能覆盖多个项目。这里我的建议是把 superpowers 的运行目录严格限制在项目根目录内并给技能设置白名单命令。比如在.superpowers/config.yml里这样配security: allowedCommands: - mvn - gradle - git - node maxOutput: 20000我把allowedCommands限制到项目需要的那几个命令AI 想跑rm -rf或者访问外部路径就会直接报错。有朋友觉得这一步太保守但有一次我让 AI 自动修复测试它大概是想清旧文件差点把.git目录当 target 清理掉。幸好白名单挡住了。从这以后我每次接新工具的第一件事就是先把安全边界画清楚。还要注意 secret 文件。Java 项目里经常有application-dev.yml这类数据库配置如果技能允许 AI 读取任意文件这些敏感信息就可能混入日志或 commit message。我的做法是在 config 里加一条 exclude 规则明确禁止技能读取**/application-*.yml和**/.env。安全这个东西宁可多挡一次也不要在事后补救。5. 实测后的心得哪些场景真能提效哪些场景别指望它工具用了大概三周从“看着新鲜”到“形成肌肉记忆”有些感受挺真实。最后这一部分我不打算做全面总结就说几个亲测过的场景和边界帮你少走弯路。5.1 真正能解放时间的三个场景第一跨文件批量重构。比如把一个接口的返回类型从ListString改成ListRecordsuperpowers 可以先用搜索技能把所有调用点找出来再逐文件修改并编译验证。这件事人工做要非常小心但技能文件一旦写好AI 能按固定顺序一个个处理中途还可以停下来让人确认。我曾经拿一个 8 万行代码的老项目试验让 AI 把某个工具类从Date迁移到LocalDateTime它先后定位了 47 个文件除了 2 个因为自动生成代码确实不需要改以外其余全部处理正确。第二测试脚手架生成。尤其是 Java 项目里的 DTO、Controller、Service 的单元测试大多数是模板代码。让 superpowers 生成初版我再改边界条件和 Mock 逻辑效率提升非常明显。写测试的痛点从“从零开始写”变成“审阅微调”。以前一个 Service 测试要写四十分钟现在十分钟内完成初稿剩下的时间全部花在回滚业务逻辑的商量上。第三本地依赖分析。以前排查依赖冲突我要mvn dependency:tree再肉眼扫现在技能直接整理成报告并标出冲突版本。看几行输出就知道该排除哪个依赖。这个事如果手工做每次都要开一个终端窗口把树形输出复制到文本编辑器里慢慢找。技能化之后AI 会先跑命令再解析输出最后生成一张 markdown 表格表格里按冲突严重程度排序体验好了不是一点半点。5.2 不建议硬上的场景依赖外部服务的行为不要轻易自动化。比如单元测试里需要连测试环境的数据库或者调用第三方支付接口这类任务一旦被技能自动执行出问题时容易把脏数据写进环境。我建议这类技能只做到“生成测试脚本”不要自动执行真实调用。说白了superpowers 可以做任何你手动能做的事但要不要让它做取决于你是否承受得起错误带来的成本。写文件、跑编译、生成代码都属于低风险操作但往数据库里插数据、调外部接口发消息都属于高风险操作至少要在技能步骤里加一个人工确认节点。还有一类是架构决策。AI 可以帮你列出方案利弊、生成对比代码但不要让它直接决定“模块A应该改用事件驱动还是继续同步调用”。这种决策需要结合团队技术栈和业务规划不是靠技能流程能框定的。superpowers 是放大器如果你的判断不清晰它会让错误决策执行得飞快。我有一次让 AI 自动把一个接口从 REST 改造成 gRPC它确实做完了整个链路但后来发现这个接口的调用方有大量事务性的需求gRPC 流式调用反而更复杂。最后只能花双倍时间回滚。所以“能不能自动化”和“该不该自动化”是两件事。5.3 下一步可以扩展的方向我接下来打算把技能库按团队共享的方式管理起来放进 Git 仓库用 code review 来迭代技能内容。不只是给自己用也方便同事直接复用。另外一个方向是把技能的输入输出接到项目里的 CI 流程比如每次提交代码后自动跑一轮“低风险修复”只改格式和补测试不碰业务逻辑。如果你刚开始接触 superpowers我的建议还是那句先别急着搞复杂编排挑一个最痛的点写一条技能跑通整个链路。等你体会到“写一次、用无数次”的感觉自然会想继续扩展。工具不在多能理顺工作流的那个才是真正的“超能力”。