前阵子刷到一个叫 superpowers 的开源项目名字起得够嚣张但用下来确实对得起这个名号。你可以把它理解成一套基于 Codex CLI 的增强方案给终端里的编程助手加上“计划、分工、审查、复盘”这些原本只存在于人类团队协作里的能力。它没有做成花哨的 GUI而是通过一堆精心设计的 slash 命令和 subagent 子代理机制让一个单线程的 AI 助手变成一支各司其职的“虚拟开发小队”。这篇文章我就围绕 superpowers 的安装、核心功能、Java 场景实战和日常排坑写一份完整记录适合已经用过 Codex CLI、但觉得单次问答式交互不够用的开发者也适合刚听说这个工具、想一步到位搭好环境的新手。里面所有步骤和参数都是我实测后整理出来的照着抄就行。1. 整体设计与思路拆解1.1 superpowers 到底解决了什么问题先说说我为什么觉得它戳中了痛点。单独用 Codex CLI 的时候你毕竟是在跟一个“有记忆但容易跑偏”的助手对话。它擅长处理单点任务比如“帮我写个函数”“修复这个编译错误”但一旦任务变成“我要为这个 Spring Boot 项目补一套单元测试顺便把潜在的安全风险列出来”对话就开始失控了。失控的原因有几个。首先是上下文碎片化问着问着它忘了最开始的要求其次是缺少任务拆解AI 一口气想做完所有事结果每个环节都做得不深入最后是缺少质量审查它写完代码后不会主动质疑自己安全隐患和边界问题都得靠人肉眼盯。superpowers 的思路不是去改 Codex CLI 的底层推理而是在外面包了一层“流程管理”把大任务拆成小步骤每一步让专门的子代理去执行最后还有审查代理把关。本质上是用工程化方法去约束 AI 的发挥。1.2 核心设计slash 命令、子代理与持久化配置整个项目最核心的三个东西是 slash 命令、subagent 子代理和配置文件。slash 命令相当于给 Codex CLI 定义了“快捷指令”。你在对话里输入/audit-codebase它不会只做字面意义上的“看看代码”而是会读取一个预定义的 Markdown 说明文件里面的指令再结合当前项目的代码内容去执行。这个设计很聪明相当于把“如何做一次合格的代码审计”总结成了标准操作流程AI 每次执行都是按流程走不会发挥失常。子代理是更进阶的玩法。superpowers 允许一个主代理把任务拆解后分发给不同的子代理比如一个子代理负责读代码、一个子代理负责写文档、一个子代理专门做安全审查。它们各自有独立的系统提示词和职责边界互不干扰最后再由主代理汇总结果。你在终端里看到的不是一个 AI 在跟你对话而是一堆 AI 在协同干活。配置文件则藏在~/.codex/目录下。它决定了哪些 slash 命令可用、每个子代理的模型参数和行为偏好、以及上下文窗口怎么分配。想调整 superpowers 的行为大部分时候你不用改代码改配置就行。1.3 为什么选这套方案而不是“对话式硬怼”我自己也试过不用 superpowers直接在 Codex CLI 里用一大段话描述复杂需求。效果不稳定因为提示词写得再好模型也很容易在长对话中途遗忘前置条件。superpowers 把“任务定义”和“任务执行”分开之后每次执行命令都基于同一个标准模板结果的可复现性就高很多。这套方案还有个额外优势可沉淀。你在项目里积累的经验、踩过的坑、团队的编码规范都能写成 slash 命令的描述文件或配置模板后续不管是自己复用还是交接给同事都是现成的。相比之下用对话方式总结出来的“经验”只存在于聊天记录里下次换个任务就失效了。这也是我最终决定把 superpowers 作为主力工具的原因它更像是把 AI 用成了“可编程的员工”而不是“随叫随到的实习生”。2. 环境准备与安装配置2.1 前置依赖与版本要求开始装之前先把环境理顺。我这边实测稳定通过的组合是macOS 14、Node.js 20 LTS、Git 2.39、Codex CLI 最新版。Node.js 版本不能太老因为 superpowers 依赖现代的 JavaScript API18 以下会直接报语法错误。Windows 用户建议先用 WSL原生 PowerShell 环境跑通整套工具链的代价比较大新手容易在环境变量上卡住。还要确认 Codex CLI 本身能正常工作。装好后在终端敲一下codex --version如果提示找不到命令说明 Codex CLI 没有正确安装。常见原因有两个一是 npm 全局安装目录不在 PATH 里二是装完之后没重启终端。检查 PATH 的做法是执行npm config get prefix把这个路径加入 shell 的 PATH 配置再重开终端就好。2.2 安装 superpowers 核心步骤安装超级简单本质上是克隆一个 GitHub 仓库到本地然后运行它的安装脚本。我建议把仓库放在一个固定位置比如~/code/superpowers避免今天装完明天找不到目录。mkdir -p ~/code git clone https://github.com/ohsai/superpowers.git ~/code/superpowers cd ~/code/superpowers npm install npm run install:globalinstall:global这一步会把superpowers命令链接到全局环境并自动向 Codex CLI 的配置目录写入初始化文件。如果这一步没报错你可以检查一下配置目录ls -la ~/.codex/正常情况下你会看到config.toml、superpowers.json以及一堆以slashtasks、subagents开头的目录。我建议刚装完先别急着使用先看一眼config.toml里有没有被正确写入模型配置免得后面跑命令时才发现模型没有授权。2.3 Codex 认证API Key 还是 OAuthsuperpowers 本身不负责认证它调用的是 Codex CLI 的登录态。Codex CLI 支持两种模式一种是 OpenAI 账号的 OAuth 登录一种是直接填 API Key。我强烈建议日常使用用 OAuth 登录因为 API Key 有泄漏风险而且计费逻辑不直观。OAuth 登录的方式是在终端执行codex login浏览器会弹出授权页面同意后终端就自动持有凭证了。API Key 模式则适合在 CI/CD 或远程服务器上跑脚本你需要先在 OpenAI 后台创建密钥然后写入环境变量export OPENAI_API_KEYsk-xxxx然后在~/.codex/config.toml里确认模型配置。superpowers 默认会设置一个主模型和一个快速模型主模型负责复杂推理快速模型负责一些简单子任务。以我个人的使用习惯主模型用gpt-4o或同等档位快速模型用gpt-4o-mini就够性价比比较稳。2.4 安装后的第一条验证命令装完之后先别搞大工程跑一条轻量命令看看链路通不通。进入任意一个项目目录启动 Codexcodex然后输入/help如果 superpowers 正确集成你会在命令列表里看到至少十几个以/开头的命令比如/audit-codebase、/create-java-project、/todo等。看不到的话大概率是安装阶段没有成功写入 Codex 配置目录重跑npm run install:global基本能解决。跑通/help之后再试一条实际命令比如/init-agents它会让主代理初始化一组子代理的状态文件。这一步成功后说明 superpowers 的运行时环境已经就绪可以正式开工了。3. 核心功能深度解析与实操要点3.1 Slash Tasks把常用流程变成“随身指令”slash 命令是 superpowers 最常用的交互入口理解它就等于理解了整个工具的使用哲学。每一个 slash 命令实际上对应~/.codex/slashtasks/里的一个 Markdown 文件。比如audit-codebase.md的内容会告诉 Codex你要做什么、输出什么格式、需要关注哪些风险类型。AI 执行命令时会把该文件里的指令载入上下文再结合当前项目的文件列表开始干活。我自己用得最频繁的几个命令是命令作用适合场景/init-agents初始化子代理状态新项目开工前/audit-codebase全仓库安全与质量审计接手遗留代码时/create-java-project生成 Java 项目脚手架快速起新项目/test-generation为现有代码补单元测试提升测试覆盖率/todo把需求拆解为可执行任务清单复杂功能开发前看到这里你应该明白了slash 命令本质上就是把“人写需求文档”这件事变成了 AI 可读取的模板。你在对话里下一道指令AI 就按照模板里的检查清单逐项执行。这种方式的好处是结果稳定不会出现“这次让它做审计它却跑去重构代码”的跑偏。如果你有自己团队特有的规范也可以照着现有模板的格式新建一个.md文件比如team-review.md把团队的代码评审要点写进去。这样后续每次做内部评审AI 都会拿着这份清单走流程。3.2 子代理机制让 AI 学会“分工协作”子代理subagent是 superpowers 最容易被忽略但价值最高的能力。简单说主代理在接到复杂任务时会按需创建多个子代理每个子代理专注于一个子任务它们共享上下文状态但系统提示词各不相同。以/audit-codebase为例它的执行过程大概是这样的主代理先扫描项目结构然后启动一个“代码阅读代理”去抓取关键文件内容再启动一个“安全审查代理”去检查敏感信息泄漏、依赖漏洞和危险函数的使用最后是“报告生成代理”负责把结果汇总成结构化文档。整个过程你在终端里能看到类似 “[subagent:security-review] 正在检查 authentication 模块” 的日志。实操中我有两个经验。第一不要给子代理安排过于模糊的任务比如“检查所有代码”要给明确边界比如“检查所有包含 SQL 语句的文件”。第二子代理的模型等级可以通过配置调整简单任务用快模型、复杂任务用强模型能显著降低 token 消耗。具体的配置在~/.codex/config.toml的[subagents]段里按需修改就好。3.3 与 WorBuddy 配合使用的思路我最近在研究 WorBuddy 怎么和 superpowers 搭配。WorBuddy 这类工具擅长的是把零散的文档、笔记、项目资料组织成结构化的知识库而 superpowers 强在代码执行与项目实操两者组合起来刚好形成“知识整理 代码执行”的闭环。实际运行模式可以这样先用 WorBuddy 沉淀项目的背景信息、架构说明和编码规范形成一份 Markdown 文档然后把这个文档路径告诉 superpowers 的 slash 命令让 AI 在执行代码任务前先加载这份文档。比如你可以在~/.codex/slashtasks/目录下新建一个project-aware.md其中明确写上一句话执行任何代码任务前先读取docs/project-context.md。这样 WorBuddy 整理的资料就不会躺在笔记里吃灰而是真正变成了 AI 的“项目背景记忆”。我自己的习惯是把 WorBuddy 当作“人的知识层”把 superpowers 当作“AI 的执行层”。人的知识层负责给方向AI 的执行层负责落地。这套组合做完之后新成员加入项目时只要让 AI 跑一条命令就能基于项目知识库和代码现状输出一份定制化的开发计划比自己翻文档高效太多了。3.4 Java 项目的专项适配与常用命令superpowers 对 Java 项目的支持不是靠内置 IDE而是靠预设的模板和命令。对 Java 开发者来说最省心的是/create-java-project命令它可以直接生成基于 Maven 或 Gradle 的 Spring Boot 项目骨架。我自己跑过一次生成的目录结构大致是. ├── build.gradle ├── settings.gradle ├── src │ └── main │ ├── java │ │ └── com/example/demo │ │ ├── DemoApplication.java │ │ ├── controller │ │ ├── service │ │ └── repository │ └── resources │ └── application.yml └── src/test └── java这个骨架质量在线不是光创建一个空 Gradle 文件就完事Controller、Service、Repository 分层都帮你搭好了还带一个最基本的测试类。对于 Java 项目后续最常用的命令是/test-generation和/audit-codebase。前者会分析现有代码结构基于业务逻辑生成 JUnit 测试后者会检查常见的 Java 安全问题包括 SQL 注入风险、不安全的反序列化、敏感配置硬编码等。有一点要特别留意superpowers 生成的 Java 代码并不保证一定能直接编译。它毕竟不是编译器有时生成的依赖版本会和本地环境冲突。我每次用它生成骨架或代码后都会先跑一遍./gradlew compileJava确认无误再继续往下做。4. 实战记录用 superpowers 审计并优化一个 Java Spring Boot 项目4.1 任务背景与初始指令为了写这篇记录我专门从旧仓库里翻出一个半年没动的 Spring Boot 项目这个项目用的是 Java 17、Spring Boot 3.2、PostgreSQL 数据库。目标很明确让它帮我做一轮整体代码审计并把审计出来的高风险问题修复掉。启动 Codex 后我输入第一条命令/audit-codebase这条命令不需要我额外描述上下文因为 superpowers 的模板里已经定义了审计范围。它会先扫描仓库文件结构识别语言组成、依赖管理和关键配置。执行日志里我能看到它列出了src/main/java下面所有业务模块以及pom.xml中的依赖清单。值得注意的是审计过程不是一次扫描就完事它会按模块分批进行。就像人做代码审查一样先看整体目录再逐个包去检查。我当时注意到它对controller层和service层的关注度明显高于repository层因为业务逻辑中的安全风险大多集中在接口层和服务层。4.2 审计执行过程的核心观察点审计跑到一半时superpowers 生成了初步的发现报告框架包含四个维度安全风险、代码质量、架构问题、测试覆盖。通过终端输出的子代理日志我观察到它至少拆解出三个子代理并行工作一个在处理安全扫描一个在检查代码规范一个在分析测试覆盖率。为了了解详细过程我用/todo命令查看当前任务分解。它给出的任务清单长这样检查全局配置文件是否存在硬编码密码审查 Controller 的输入校验逻辑分析 JPA Repository 是否存在 N1 查询检查异常处理是否统一确认 CORS 配置是否合理统计测试覆盖率标记缺失模块如果你用纯对话方式让 AI 做同样的事它很可能只挑两三个点就草草收场因为缺少这种强制任务分解机制。superpowers 的优势就在这里即使部分任务执行得不够深入至少每个维度都有覆盖。大概跑了三分钟审计报告的首个版本出来了。安全风险部分的结论让我有点意外但也合理项目里不存在硬编码密码属于侥幸但 CORS 配置确实太宽松允许了所有来源跨域这个在依赖配置里确实不好主动发现。测试覆盖部分更直接service 层覆盖率不到 20%很多核心方法完全没有测试隐患不小。4.3 人工介入与后续修复审计报告出来后我没有让它自动修复所有问题而是挑优先级最高的三个处理。第一步让它修复 CORS 配置把允许的来源改成显式白名单并加上允许的方法和 Header 限制。命令很简单/execute-task 5它的意义在于“只修这一件事”而不是顺带碰其他代码避免 AI 在一次操作里改动过多文件导致问题难回滚。这一步执行完成后我立刻用git diff检查了改动确认只动了CorsConfig.java一个文件。这也给了我一个很重要的心得不管 AI 工具多聪明改动范围务必保持最小化方便审查和回溯。第二步是给 service 层补测试。我选中一个关键的业务方法让它生成对应的 JUnit 测试覆盖正常入参、边界入参和异常场景。生成的测试代码质量不错但有个地方需要手工调整就是 Mock 数据的构造有些嵌套对象的依赖关系它没有完整模拟导致一个测试用例编译失败。我调整了 Mock 结构后测试全部通过。最后一步是让它修复一个 N1 查询问题。它给出的方案很标准把OneToMany的默认 fetch 策略改成JOIN FETCH或者使用EntityGraph。我选择了EntityGraph方案因为对已有查询逻辑的影响最小。修复完成后我用本地数据库跑了一遍核心接口的回归验证接口响应数据与修复前完全一致只是查询 SQL 里多了一次关联查询性能明显改善。5. 常见问题与排查技巧实录5.1 安装或初始化报错遇到的第一个常见问题是npm run install:global执行到一半报错日志里出现EACCES: permission denied。这通常是 npm 全局目录没有写权限导致的尤其是用 nvm 管理 Node 版本时容易碰到。解决办法有两条一是用 sudo 执行安装命令一劳永逸但不推荐二是把 npm 全局路径改到用户目录下执行npm config set prefix ~/.npm-global再把~/.npm-global/bin加到 PATH 里。我推荐第二种干净利落。第二种常见问题是安装完superpowers命令后在 Codex 里却看不到任何 slash 命令。原因是 Codex 的配置目录下的slashtasks文件夹没有被正确读取。我一开始也遇到这个问题后来发现是安装脚本写路径时用了旧版本 Codex 的配置路径而新版 Codex 已经把配置目录从~/.codex改到了~/.config/codex。确认版本后手动把配置目录复制过去问题就解决了。如果你也遇到这种情况先执行codex --version然后去版本对应的配置目录检查文件是否存在比盲目重装快得多。5.2 认证失败与模型无权访问运行时最常见的是 401 认证失败或 403 模型无权访问。401 一般是 token 过期重新执行一下codex login就能解决。403 相对麻烦通常是你当前账号没有开通某个模型的访问权限。比如你在config.toml里把主模型配成了o1或o1-mini但账号本身没有权限访问这个模型调用时就会报错。排查思路是打开~/.codex/config.toml查看当前的model和model_provider配置。如果你不确定自己的账号支持哪些模型把配置改成gpt-4o或gpt-4o-mini这类模型兼容性最高。我自己的主模型长期用gpt-4o快速模型用gpt-4o-mini日常开发没有碰到过权限限制。5.3 子代理返回空结果或重复执行子代理机制偶尔会出现“空转”现象表现是终端里能看到[subagent:xxx] started但迟迟看不到输出最后返回空结果。这种情况大多发生在旧版本 Codex CLI 上因为子代理依赖的上下文传递方式有过一次较大的调整。优先升级 Codex CLI 到最新版npm update -g openai/codex升级后仍然有问题的话检查任务描述是否给了子代理足够的上下文。比如你让它做“代码审计”但没有告诉它从哪个目录开始、需要关注什么语言子代理确实可能不知道从何入手。给它加上明确的信息执行的成功率会高很多。5.4 token 消耗控制与上下文管理还有一个容易被忽视的问题token 消耗失控。superpowers 的 slash 命令通常会拉入大量上下文如果项目文件很多一次审计可能消耗惊人的 token。我试过对一个中等规模项目大概 300 个文件执行/audit-codebase一次下来消耗了几万 token虽然结果很充实但成本确实不低。控制消耗的办法有三个。第一使用子代理时把不相关的目录排除掉比如node_modules、target、dist这些构建产物目录。第二设置单次命令的最大 token 上限在配置文件里的token_budget字段做好限制。第三按子模块审计而不是全仓库审计把任务范围缩小。比如只审计controller层命令里明确写清楚范围AI 就不会跑去读repository层的全部代码了。另外我建议不要同时在多个终端窗口开多个 Codex 会话去跑 superpowers那样 token 消耗是叠加的而且上下文彼此独立任务之间还可能产生冲突。一个窗口跑完再开下一个成本和心态都更可控。6. 我个人的使用心得与小技巧前面几节基本把 superpowers 的方方面面都聊完了最后说几个我在实际使用中攒下的个人心得不算什么正规方法论但挺管用。第一个心得是别把 slash 命令当成“一键生成器”它更准确的定位是“流程标准化”。你给它多大的任务范围它就按多大的范围去执行而不会自动判断哪些工作其实没必要做。所以我每次用/audit-codebase之前都会花两分钟把范围想清楚甚至临时改一改模板里的描述。虽然多了一步但执行质量和 token 开销的差距非常大。第二个心得是子代理的明确输出格式很重要。我一开始用的时候子代理返回的结果都是长篇大论信息密度低看得人头疼。后来我改了 slash 模板里的输出要求强制让子代理按“问题描述、风险等级、建议方案、涉及文件”四列输出可读性瞬间提升。这个习惯现在已经带到了我所有的 AI 工具使用中明确输出格式永远比单纯让 AI“自由发挥”更高效。最后分享一个小技巧养成“先审计、后修改、再补测”的顺序。这个顺序来自我踩过的一次坑当时我让 AI 直接“帮我优化代码”结果它一口气重构了十几个文件改动面大得没法 review。后来我严格要求自己必须先让它出审计报告再逐条执行修复修复完立刻补对应测试。这样每次改动都是可控的、可验证的AI 再聪明也不至于把项目搞得一团糟。这套习惯配合 superpowers 的 slash 命令我现在接手的每个项目都能在两三个小时内完成一轮高质量体检和重点修复效率比单纯硬怼 Codex CLI 高了一截。