1. 从“superpowers”这个标题说起它到底是什么第一次看到“superpowers”这个词很多人脑子里蹦出来的可能是超级英雄电影里的超能力或者某些游戏里的技能系统。但如果你是在技术社区、开发群或者效率工具圈里看到这个词那它大概率指向的是一个完全不同的东西——一个围绕 AI 编程助手构建的扩展能力框架或者更通俗地说是一套让 AI 助手从“能聊天”变成“能干活”的技能包。我最早接触这个概念是在一个开发者群里有人发了一句“装上 superpowers 之后codex 终于不只会写 hello world 了”。当时我就来了兴趣因为用过 AI 编程助手的人都知道默认状态下的助手往往只能给你一些通用建议或者写一些片段代码真正要让它完成一个完整任务比如“帮我搭一个 REST API 并写好测试”它要么跑偏要么半途而废。而 superpowers 这类框架要解决的就是这个“最后一公里”的问题。简单来说superpowers 是一套面向 AI 编程助手的技能扩展机制。它通过预定义的指令集、工作流模板和上下文注入让 AI 助手能够按照特定领域的规范去执行任务。你可以把它理解成给 AI 助手装了一本“操作手册”手册里写清楚了遇到什么场景该用什么工具、按什么步骤走、输出什么格式。这样一来AI 助手就不再是随机发挥而是有章可循。它适合谁呢如果你是一个经常用 AI 助手写代码的开发者不管是 Java、Python 还是前端superpowers 都能帮你把 AI 的输出质量提升一个档次。如果你是一个团队的技术负责人想统一团队里 AI 助手的使用方式superpowers 也提供了一个可定制的框架。甚至如果你只是刚接触 AI 编程还没搞明白怎么让助手写出能跑的代码那从 superpowers 入手会比你自己摸索快得多。我写这篇东西的目的就是把我自己从安装、配置到实际使用的整个过程梳理一遍包括踩过的坑、试过的参数、以及一些官方文档里不会写的细节。你不需要有很深的 AI 背景只要会用命令行、能看懂基本的配置文件就能跟着走下来。2. 核心机制拆解superpowers 为什么能让 AI 助手变聪明2.1 技能注入把“通用助手”变成“领域专家”AI 编程助手默认状态下是一个通才它知道很多语言、很多框架但每个都不够深。你问它“怎么用 Spring Boot 写一个带分页的查询接口”它能给你一个大概的代码框架但分页参数怎么传、Pageable 怎么用、返回体怎么封装这些细节它可能就含糊了。superpowers 的核心思路就是通过“技能注入”来解决这个问题。所谓技能注入就是在 AI 助手的上下文里预先塞入一套结构化的知识。这套知识不是简单的文档堆砌而是按照“触发条件—执行步骤—输出规范”来组织的。比如有一个技能叫“REST API 生成”它的触发条件可能是用户输入里包含“创建接口”“写一个 API”这类关键词执行步骤会明确告诉助手先确认实体类、再生成 Controller、然后补 Service 和 Repository、最后写测试输出规范则规定了代码风格、注释格式和文件命名。这种机制的好处在于它把 AI 的“自由发挥”限制在了一个可控的范围内。我实测下来同一个模型在没有技能注入的时候写一个用户注册接口可能会漏掉参数校验、密码加密、重复用户名检查这些关键点而注入技能之后它会自动把这些步骤都补上因为技能定义里就写了“必须包含参数校验和异常处理”。2.2 工作流编排让多步任务不再断片AI 助手有一个通病就是处理多步任务时容易“断片”。你让它先分析需求、再设计数据库、然后写代码、最后写测试它可能在第二步就忘了第一步的结论或者在第四步写测试的时候把前面定义的接口路径都搞错了。superpowers 通过工作流编排来解决这个问题。工作流编排的本质是把一个大任务拆成多个小步骤每个步骤的输出都作为下一个步骤的输入并且在整个过程中维护一个共享的上下文。这个上下文里记录了已经做出的决策、已经生成的文件、已经定义的接口。当助手执行到下一步时它会先读取这个上下文确保自己不会偏离之前的约定。我举个例子。有一次我用 superpowers 让助手帮我做一个“订单管理模块”工作流是这样的第一步分析需求输出一个需求清单第二步根据需求清单设计数据库表输出 SQL第三步根据表结构生成实体类和 Mapper第四步生成 Service 和 Controller第五步生成单元测试。整个过程里助手在第三步生成的实体类字段和第二步的 SQL 是完全对应的因为工作流引擎会把 SQL 里的字段名和类型传递给第三步。如果没有这个编排助手很可能在第三步自己“发明”一些字段导致后面全对不上。2.3 上下文管理解决“聊着聊着就忘了”的老毛病用过 AI 助手的人都知道对话一长助手就开始忘事。前面刚说过的接口路径后面就写错了前面定好的命名规范后面就抛到脑后了。superpowers 在上下文管理上做了不少工作它会把关键信息提取出来单独存储并且在每次请求时都重新注入。具体来说它会维护几个层次的上下文全局上下文比如项目名称、技术栈、代码规范、任务上下文当前正在做的任务、已经完成的步骤、会话上下文最近的几轮对话。当助手需要生成代码时它会优先读取全局和任务上下文确保输出符合项目整体约定。会话上下文则用来保持对话的连贯性但权重会低一些避免最近的闲聊干扰到核心任务。这个机制在实际使用中效果很明显。我之前做一个 Java 项目项目规范要求所有接口返回体必须用ResultT包装所有日期字段必须用LocalDateTime。在没有上下文管理的时候助手写着写着就忘了一会儿返回裸对象一会儿用Date。用了 superpowers 之后我把这些规范写进全局上下文后面生成的代码就再也没跑偏过。2.4 与 codex 的集成为什么大家总把这两个词放一起热搜词里有一个是“codex superpowers”这说明很多人是在 codex 这个场景下接触 superpowers 的。codex 本身是一个 AI 编程助手它的强项是代码生成和补全但默认状态下它更像一个“高级自动补全”而不是一个“能独立完成任务的代理”。superpowers 在 codex 的基础上加了一层技能层和工作流层让 codex 能够理解更复杂的指令并且按照预定义的流程去执行。集成的具体方式通常是通过配置文件或者插件机制。你需要在 codex 的配置里指定 superpowers 的技能目录然后 codex 在收到用户请求时会先经过 superpowers 的解析器判断应该激活哪些技能、走哪个工作流然后再把增强后的请求发给模型。模型返回的结果也会经过 superpowers 的后处理比如格式化代码、检查是否符合规范、生成对应的文件等。这种集成方式的好处是你不需要改变原有的使用习惯还是在 codex 的界面里输入指令但背后的处理逻辑已经完全不同了。我自己的体验是集成之后 codex 写出的代码从“能跑但需要大改”变成了“基本能直接用只需要微调”。3. 安装与配置从零把 superpowers 跑起来3.1 环境准备别急着敲命令先把这几样东西确认好在开始安装之前有几样东西你需要先确认好不然装到一半发现缺东西来回折腾很浪费时间。第一是运行环境。superpowers 本身通常是一个 Node.js 包或者 Python 包具体取决于你用的版本。我用的版本是 Node.js 的所以需要 Node 16 以上。你可以用node -v看一下版本如果低于 16建议先升级。升级 Node 版本我推荐用 nvm比直接覆盖安装干净得多。第二是包管理器。npm 和 yarn 都可以但我个人更推荐 pnpm因为 superpowers 的依赖树比较深pnpm 的硬链接机制能省不少磁盘空间安装速度也快一些。如果你还没装 pnpm可以用npm install -g pnpm装一个。第三是 AI 助手的访问凭证。superpowers 本身不提供模型能力它需要调用后端的 AI 服务。所以你需要准备好对应的 API Key 或者访问令牌。这个 Key 通常在你使用的 AI 平台的账户设置里可以找到。拿到之后先放一边后面配置的时候要用。第四是网络环境。因为安装过程中需要从包仓库拉取依赖所以确保你的网络能正常访问这些仓库。如果公司网络有代理记得提前配好 npm 或 pnpm 的代理设置。提示如果你之前装过其他 AI 助手相关的工具建议先检查一下有没有端口冲突或者全局命令冲突。我就遇到过 superpowers 的 CLI 命令和另一个工具重名的情况后来改了 PATH 顺序才解决。3.2 安装步骤一条命令背后的完整流程安装 superpowers 本身通常就是一条命令的事但这条命令背后做了不少事情了解这些能帮你在出问题的时候快速定位。如果你用 npm命令是npm install -g superpowers-cli如果你用 pnpmpnpm add -g superpowers-cli执行之后包管理器会做这几件事首先解析依赖树superpowers 依赖了一些解析库、模板引擎和 HTTP 客户端然后下载这些依赖到本地缓存接着把 superpowers 的可执行文件链接到全局 bin 目录最后运行 postinstall 脚本这个脚本通常会做一些初始化工作比如创建默认的配置目录、下载内置的技能包。安装完成后你可以用superpowers --version来验证是否成功。如果输出了版本号说明安装没问题。如果提示命令找不到那大概率是全局 bin 目录不在 PATH 里。你可以用npm bin -g或者pnpm bin -g看一下全局 bin 目录在哪里然后把它加到 PATH 里。接下来是初始化配置。运行superpowers init这个命令会在你的用户目录下创建一个.superpowers文件夹里面包含默认的配置文件config.json和技能目录skills/。配置文件里有一些基础设置比如默认的模型、超时时间、日志级别等。技能目录里则预置了一些常用技能比如代码生成、代码审查、单元测试生成等。3.3 配置文件详解每个参数都值得看一眼.superpowers/config.json是核心配置文件我挑几个关键参数说一下。{ model: gpt-4, apiKey: your-api-key-here, timeout: 30000, maxTokens: 4096, skillsDir: ./skills, workflowsDir: ./workflows, logLevel: info, autoFormat: true, language: zh-CN }model指定默认使用的模型。如果你用的是 codex这里可能填的是 codex 对应的模型标识。apiKey就是前面让你准备好的访问凭证。timeout是单次请求的超时时间单位毫秒默认 30 秒。如果你网络比较慢或者任务比较复杂可以调到 60000。maxTokens控制单次生成的最大 token 数调大一些可以让助手一次生成更多内容但也会增加响应时间和费用。skillsDir和workflowsDir分别指定技能和工作流文件的存放目录。默认是相对路径相对于.superpowers目录。如果你想把技能文件放在项目里方便团队共享可以改成绝对路径或者相对于项目根目录的路径。autoFormat是一个很实用的开关。打开之后助手生成的代码会自动经过格式化处理比如 Java 代码会用 google-java-format 格式化JavaScript 会用 prettier。这样你拿到的代码就是整洁的不需要自己再手动调整。language控制助手回复的语言。设成zh-CN之后助手的解释性文字会用中文但代码和注释还是按项目规范来。这个设置对英文不太好的同学很友好。3.4 技能包的选择与加载不是越多越好superpowers 预置了一批技能包但我不建议你一次性全部加载。技能包太多会占用大量上下文空间反而降低助手的响应质量。我的做法是按需加载用到什么加什么。加载技能的方式有两种。一种是直接在配置文件里指定要加载的技能列表{ enabledSkills: [rest-api, unit-test, code-review] }另一种是把技能文件放到skillsDir目录下superpowers 启动时会自动扫描并加载。我更喜欢第二种因为可以随时增删文件不用改配置。每个技能文件通常是一个 JSON 或者 YAML 文件里面定义了技能的元信息、触发条件和执行步骤。你可以自己写技能文件也可以从社区下载。写自定义技能的时候触发条件要尽量精确不然容易误触发。比如你写了一个“生成 Java 实体类”的技能触发条件如果只写“实体类”那用户说“实体类有什么作用”的时候也会触发这就很尴尬。更好的做法是加上动作词比如“生成实体类”“创建实体类”。4. 实战操作用 superpowers 完成一个完整任务4.1 任务定义从一句模糊需求到可执行指令假设我要做一个用户管理模块包含增删改查接口。如果直接跟 AI 助手说“帮我写一个用户管理模块”它大概率会给你一个很粗糙的代码片段缺东少西。但用 superpowers 的时候我会把需求拆解成结构化的指令。我的做法是先写一个任务描述文件放在项目根目录下叫task.md# 任务用户管理模块 ## 技术栈 - Java 17 - Spring Boot 3.2 - MyBatis-Plus - MySQL 8.0 ## 需求 1. 用户表包含字段id, username, email, password_hash, created_at, updated_at 2. 提供以下接口 - POST /api/users 创建用户 - GET /api/users/{id} 查询用户 - PUT /api/users/{id} 更新用户 - DELETE /api/users/{id} 删除用户 - GET /api/users 分页查询用户列表 3. 所有接口返回 ResultT 包装 4. 密码需要加密存储 5. 需要参数校验 6. 需要单元测试然后运行superpowers run --task task.md --workflow rest-api这个命令告诉 superpowers读取task.md里的需求按照rest-api工作流来执行。superpowers 会先解析任务描述提取出技术栈、需求列表和约束条件然后激活相关的技能开始逐步执行。4.2 执行过程看着助手一步步把活干完执行开始后superpowers 会输出每一步的进展。我截取了一段实际的日志[INFO] 解析任务描述... 完成 [INFO] 识别技术栈Java 17, Spring Boot 3.2, MyBatis-Plus, MySQL 8.0 [INFO] 激活技能rest-api, java-entity, unit-test, code-review [INFO] 开始工作流rest-api [STEP 1/6] 分析需求并生成接口清单... [STEP 2/6] 设计数据库表结构... [STEP 3/6] 生成实体类和 Mapper... [STEP 4/6] 生成 Service 和 Controller... [STEP 5/6] 生成单元测试... [STEP 6/6] 代码审查与格式化... [INFO] 任务完成共生成 12 个文件每一步的输出都会保存到.superpowers/output/目录下按步骤编号存放。比如第一步的输出是01-api-list.md里面列出了所有接口的路径、方法、请求参数和返回结构。第二步的输出是02-schema.sql里面是建表语句。第三步开始就是实际的 Java 代码文件了。我特别喜欢的是第六步的代码审查。superpowers 会自动检查生成的代码是否符合规范比如有没有漏掉Valid注解、有没有正确处理异常、命名是否符合驼峰规范等。如果发现问题它会自动修复并在日志里说明改了什么。这个功能帮我省了不少手动检查的时间。4.3 参数调优让生成结果更符合预期默认参数下superpowers 的生成结果已经不错了但如果你有特殊需求可以调整一些参数来优化。第一个是temperature。这个参数控制生成的随机性值越低越保守值越高越有创意。对于代码生成我建议设成 0.2 到 0.4 之间。太低会导致代码千篇一律太高又容易跑偏。我一般用 0.3。第二个是maxTokens。如果你要生成的文件比较大比如一个包含很多方法的 Service 类默认的 4096 可能不够会导致生成被截断。这时候可以调到 8192 甚至更高。但要注意token 数越高响应时间越长费用也越高。第三个是topP。这是另一种控制随机性的参数和 temperature 配合使用。我一般保持默认的 0.95不太需要调。你可以在命令行里临时覆盖这些参数superpowers run --task task.md --workflow rest-api --temperature 0.3 --maxTokens 8192也可以把它们写进配置文件作为全局默认值。4.4 生成结果分析哪些能直接用哪些需要改任务完成后我打开生成的文件看了一下。整体质量比我预期的好但也不是完美无缺。实体类User.java生成得很规范字段名和类型都和 SQL 对应注解也加对了。TableName、TableId、TableField这些 MyBatis-Plus 的注解都用上了日期字段也正确地用了LocalDateTime。Controller 层基本可以直接用接口路径、请求方法、参数校验注解都写对了。Valid加在了请求体参数上NotNull、Email这些校验注解也加在了 DTO 的字段上。返回体统一用了ResultT包装符合我的要求。Service 层稍微有点问题。生成的分页查询方法里分页参数的默认值没有处理如果前端不传page和size会报空指针。这个需要手动补一下默认值。另外删除接口用的是物理删除但我其实想要逻辑删除。这个是因为我在任务描述里没写清楚不能怪助手。单元测试生成得比较基础只覆盖了正常流程没有覆盖异常情况。比如创建用户时用户名重复的情况、查询不存在的用户的情况这些都没有对应的测试用例。我后来手动补了几个。提示superpowers 生成的结果一定要自己过一遍尤其是业务逻辑相关的部分。它擅长的是按照模板和规范生成代码但业务规则这种东西还是得你自己把关。5. 常见问题与排查技巧实录5.1 安装阶段的高频问题问题一superpowers命令找不到。这个最常见原因通常是全局 bin 目录不在 PATH 里。你可以用npm bin -g或pnpm bin -g找到全局 bin 目录然后把它加到 PATH。如果是 Windows还要注意路径里不要有空格不然容易出问题。问题二安装过程中卡在 postinstall 脚本。这个通常是因为网络问题postinstall 脚本需要从远程下载技能包。你可以先跳过脚本安装npm install -g superpowers-cli --ignore-scripts然后手动运行superpowers init来下载技能包。如果手动也下载不了可以设置 npm 的 registry 为国内镜像源。问题三Node 版本不兼容。superpowers 对 Node 版本有要求太低会报语法错误。用node -v确认版本建议用 nvm 管理多个 Node 版本切换起来方便。5.2 运行阶段的典型故障问题四助手生成的代码不完整被截断了。这个一般是maxTokens设得太小。调大maxTokens或者把任务拆成更小的步骤分多次生成。我一般会把一个大的 Service 类拆成多个小任务每个任务只生成几个方法。问题五技能没有触发。检查技能文件的触发条件是否匹配你的输入。如果触发条件写的是“生成接口”而你输入的是“写一个 API”那可能就匹配不上。你可以用superpowers skills list查看已加载的技能用superpowers skills test 你的输入来测试哪些技能会被触发。问题六生成的代码不符合项目规范。这个通常是因为全局上下文里没有写清楚项目规范。你可以在.superpowers/context/global.md里详细描述你的代码规范比如命名规则、注释格式、异常处理方式等。写得越具体助手越能遵守。问题七工作流执行到一半报错退出。先看日志里的错误信息。常见的原因有API Key 过期、网络超时、某个步骤的输出格式不符合预期导致下一步无法解析。如果是 API Key 问题更新配置即可。如果是网络问题调大timeout。如果是输出格式问题可以手动修改上一步的输出文件然后从出错的那一步重新执行superpowers resume --from-step 3。5.3 常见问题速查表问题现象可能原因解决方法命令找不到全局 bin 不在 PATH把npm bin -g的输出加到 PATH安装卡住网络问题跳过 postinstall手动 init代码被截断maxTokens 太小调大 maxTokens 或拆分任务技能不触发触发条件不匹配检查技能文件调整触发词代码不规范全局上下文缺失在 global.md 里写清楚规范工作流中断API Key 过期或超时更新 Key 或调大 timeout生成结果跑偏temperature 太高调低 temperature 到 0.2-0.45.4 几个我踩过的坑第一个坑是技能包加载顺序。superpowers 会按照技能文件的字母顺序加载如果两个技能的触发条件有重叠后加载的会覆盖先加载的。我有一次同时加载了“rest-api”和“graphql-api”两个技能结果因为字母顺序graphql 的技能把 rest 的覆盖了导致生成的接口全是 GraphQL 风格的。后来我把不用的技能文件移出目录问题就解决了。第二个坑是上下文长度超限。superpowers 会把全局上下文、任务上下文和会话上下文一起发给模型如果这些内容加起来超过了模型的上下文窗口就会报错。我有一次在全局上下文里写了几千行的项目规范结果每次请求都超限。后来我把规范精简到最核心的几十条问题就没了。所以全局上下文不是越多越好要精炼。第三个坑是自动格式化把代码改坏了。autoFormat打开之后superpowers 会用配置的格式化工具处理生成的代码。但有些格式化工具对某些语法支持不好比如 Java 的 record 类型早期版本的 google-java-format 会把它格式化得面目全非。如果你用了比较新的语法特性建议先关掉autoFormat手动格式化。6. 进阶玩法把 superpowers 用出花来6.1 自定义技能写一个适合自己团队的技能包预置技能虽然好用但每个团队都有自己的特殊需求。比如我们团队要求所有 Controller 方法必须加 Swagger 注解所有 Service 方法必须打日志。这些规范预置技能里没有我就自己写了一个。自定义技能的格式很简单就是一个 JSON 文件{ name: team-java-standard, description: 团队 Java 代码规范, triggers: [生成 Java 代码, 写一个 Java 类], steps: [ { action: inject-context, content: 所有 Controller 方法必须加 Operation 注解所有 Service 方法入口必须打 info 日志。 }, { action: generate, template: java-standard }, { action: validate, rules: [has-operation-annotation, has-service-log] } ] }这个技能会在生成 Java 代码时注入团队规范并且在生成后校验是否遵守了规范。如果校验不通过superpowers 会自动重新生成或者提示你手动修改。写自定义技能的关键是触发条件要精确步骤要清晰校验规则要可执行。我建议先从简单的技能开始比如只做代码格式校验跑通了再逐步增加复杂度。6.2 工作流组合把多个技能串成流水线superpowers 的工作流可以把多个技能串起来形成一个完整的流水线。比如我定义了一个“新功能开发”工作流包含以下步骤需求分析技能把模糊需求转成结构化需求清单数据库设计技能根据需求清单生成表结构代码生成技能根据表结构生成实体、Mapper、Service、Controller测试生成技能根据接口定义生成单元测试代码审查技能检查代码规范和质量文档生成技能根据代码生成 API 文档这个工作流跑一遍一个新功能从需求到代码到文档就全齐了。我实测下来一个中等复杂度的模块原本需要半天的工作量用这个工作流大概二十分钟就能搞定初版剩下的时间主要花在业务逻辑的微调上。工作流的定义文件放在workflowsDir目录下格式也是 JSON 或 YAML。你可以用superpowers workflow list查看所有工作流用superpowers workflow run name来执行。6.3 与 CI/CD 集成让 superpowers 在流水线里干活superpowers 不仅可以本地用还可以集成到 CI/CD 流水线里。比如你可以在代码提交时自动运行代码审查技能检查新代码是否符合规范。如果不符合流水线就失败阻止合并。集成的关键是让 superpowers 以非交互模式运行。它提供了一个--ci参数加上之后不会输出交互式提示而是直接返回退出码。退出码为 0 表示检查通过非 0 表示有问题。一个典型的 CI 配置片段steps: - name: Run superpowers code review run: | superpowers review --ci --rules team-java-standard continueOnError: false这样每次提交代码superpowers 都会自动跑一遍审查把问题扼杀在合并之前。我们团队用了这个之后代码审查的返工率明显下降了。6.4 性能优化让 superpowers 跑得更快更稳superpowers 用久了之后你可能会觉得响应变慢。这通常是因为技能包太多、上下文太长、或者模型本身响应慢。我总结了几个优化技巧。第一定期清理不用的技能包。技能包加载时会占用内存和上下文空间不用的就移出目录。我一般只保留当前项目需要的三到五个技能。第二精简全局上下文。全局上下文每次请求都会发送内容越多请求越大响应越慢。把不常用的规范移到项目级别的上下文里只在需要的时候加载。第三使用缓存。superpowers 支持对模型响应进行缓存相同的请求第二次会直接返回缓存结果。你可以在配置里打开cache: true并设置缓存过期时间。对于重复性高的任务比如生成标准的 CRUD 代码缓存能省不少时间。第四选择合适的模型。不是所有任务都需要用最强的模型。简单的代码格式化、命名检查用轻量级模型就够了。复杂的业务逻辑生成再用强模型。superpowers 支持在技能级别指定模型你可以根据任务复杂度灵活配置。7. 一些个人体会和后续可以玩的方向用 superpowers 这段时间我最大的感受是它把 AI 编程助手从“玩具”变成了“工具”。以前用助手写代码我得反复调整提示词还得自己检查生成的每一行代码。现在有了技能和工作流的约束助手的输出稳定了很多我只需要关注业务逻辑对不对不用再操心代码规范的问题。不过它也不是银弹。superpowers 擅长的是标准化、重复性的代码生成比如 CRUD、单元测试、文档。对于需要创造性设计的部分比如架构选型、复杂算法实现它还是得靠人来主导。我的做法是把这些任务拆开让 superpowers 做它擅长的部分我自己做需要思考的部分配合起来效率最高。后续我打算试试把 superpowers 和代码仓库的 issue 系统打通。比如在 issue 里打上特定标签superpowers 就自动读取 issue 描述生成对应的代码分支和 PR。这样从需求到代码的链路就更短了。另外我也想试试用 superpowers 做代码迁移比如把老项目的 Java 8 代码批量升级到 Java 17这种重复性高、规则明确的任务应该很适合它。如果你也在用 superpowers或者准备开始用我的建议是先从一个小任务入手把安装和基本流程跑通然后再逐步增加技能和工作流。不要一上来就搞一个大而全的配置那样容易出问题也不好排查。一步一步来遇到问题看日志大部分问题都能解决。