Superpowers技能包：扩展AI编程助手的代码审查与自动化测试

1. Superpowers到底是什么一套能把AI助手变强的技能包先说结论Superpowers 是一套开源的技能包集合专门用来扩展 AI 编程助手或命令行工具的能力。你可以把它理解成给 AI 装了一整箱外挂装备不再只靠大模型自己临场发挥而是用预制好的、经过反复验证的流程去处理重复性任务。我知道你看到这个标题可能会想这不就是个插件吗其实不太一样。插件的核心是接工具比如连数据库、调接口Superpowers 的核心是接技能它封装的是完整的工作流——比如审查这段代码有没有安全隐患把这段逻辑重构得更清晰按照团队规范生成单元测试。这些任务不是单一工具调用而是多步骤的推理与操作组合普通插件很难做到。适合谁来用两类人最值得关注一类是每天要写大量代码、做大量代码评审的开发者另一类是正在搭建内部 AI 工具链的团队负责人。前者能直接用现成技能省时间后者能拿它当底座往里面塞自己的团队规范。小白也不用慌安装和引入过程并不复杂后面我会一步步带你走。值得一提的是Superpowers 的设计思路是声明式技能调用。你不用在每次提问时把需求描述得又臭又长只要在文件或命令行里声明我要用哪个技能剩下的细节由技能本身去执行。这种思路特别适合团队统一 AI 行为避免十个人问同一个问题得到十种不同风格的答案。2. 拆解Superpowers的技能清单你拿到的是一整箱超能力2.1 按工作流分类的核心技能一览Superpowers 默认带了一套经过整理的技能库覆盖了从写代码到发版的完整链路。我把它分成五大类方便你心里先有个地图。第一类是代码理解类包含 explain解释代码、trace调用链追踪、impact变更影响分析。这类技能解决的是这段代码在干什么、改了会炸哪里的问题尤其适合接手陌生项目时用。第二类是代码质量类包含 review代码审查、refactor安全重构、lint-fix自动修复风格问题。它们不是简单跑个 linter 或者做静态检查而是会结合上下文给出带解释的修改建议。第三类是测试类包含 generate-tests生成单元测试、test-cases生成测试用例、coverage-gap补测试盲区。第四类是文档类包含 docgen生成接口文档、changelog生成变更日志、readme-update更新 README。第五类是工程效率类包含 dep-analyze依赖分析、perf-check性能隐患检查、security-scan常见漏洞扫描。这五大类技能不是互相孤立的它们可以串联使用。比如我用 trace 看一条调用链发现问题后用 review 定位风险点再调 refactor 做重构最后用 generate-tests 补测试。这也是 Superpowers 比单点工具强的地方技能之间可以像流水线一样配合。2.2 哪些技能最常用我实测的优先级排序基于我在真实项目里跑过几十次的经验给你一个安装后值得优先试用的排序优先级技能名适用场景给我的体感1review提交 MR/PR 前自查能发现真问题不是凑数2explain看陌生代码讲解有层级不啰嗦3generate-tests补单测骨架直接可用需要少量微调4refactor老代码整理改动保守不会乱飞5security-scan上线前检查能扫出硬编码密钥和注入风险6changelog发版前整理省了回忆一周改了啥的时间实际用下来review 和 explain 的性价比最高。因为这两个技能几乎不依赖项目特定配置装上就能用而且每次输出的结构化报告都很稳定。generate-tests 的效果则取决于你项目的可测性代码耦合严重的旧模块需要先手工拆一拆否则生成的测试会一直想 mock 整条链路。changelog 这个技能看似不起眼但到了周五下午要发版时你就会庆幸有它。3. 环境准备与安装两步走把Superpowers装进你的工作台3.1 前置要求操作系统、运行时与版本选择Superpowers 本身是用 Node.js 写的所以第一道门槛就是装 Node.js。我这里给个硬指标Node.js 18 或更高版本npm 9 以上。Node 16 也能跑但部分技能会用到新的 fetch API 和 Web Stream老版本会报奇怪的错。你可以在终端里跑node -v npm -v先确认。操作系统的要求很宽松macOS、Linux、Windows 都能装。Windows 上如果你用的是 PowerShell注意执行策略需要允许脚本运行建议直接开一个管理员窗口执行Set-ExecutionPolicy RemoteSigned再继续。这个细节容易卡住新人先给你打个预防针。另外有一个选择要提前做Superpowers 有两种形态——CLI 工具和语言服务器协议LSP服务。CLI 适合人手动敲命令来调用技能LSP 服务适合给编辑器或 AI 助手提供编程接口。如果你想先自己体验装 CLI 就够了如果想让团队共用建议后续再跑 LSP 服务。下文先讲 CLI 的安装因为最直观。3.2 详细安装步骤用包管理器一键搞定安装过程我用一个全局安装命令打通npm install -g superpowers-skills装完以后先别着急用跑一下自检命令superpowers doctor这个命令会帮你检查 Node 版本、网络连通性、本地 Git 配置、以及有没有安装可选的补全引擎比如 ripgrep。如果有项标红它会直接告诉你缺什么。我把这个步骤比作买电器先通电测试能省掉后面排查问题的大半时间。如果你不想全局安装也可以放进某个项目的devDependencies里然后通过npx superpowers来调用。我建议团队项目用这种方式因为可以锁版本个人机器上全局装反而方便。两条路都支持按你习惯来。安装完之后你会在用户目录下看到一个.superpowers目录Windows 上是%USERPROFILE%\.superpowers。这里面默认存放技能清单和全局配置不要乱删。3.3 安装后的目录结构与验证方法装完第一步建议先看一下默认技能列表是否完整superpowers list正常情况下会输出十几个技能名称对应我前面说的五大类。如果你看到列表为空多半是安装时网络中断重新跑一次npm install即可。还有一个验证方法直接跑一个最轻量的技能superpowers run explain --input console.log(hello)这个命令会调用 explain 技能给你解释这段代码。只要它能正常输出一段说明文字说明整个运行链路是通的。千万别一上来就跑 refactor 或 security-scan那些技能对项目上下文有要求容易因为环境问题报错打击士气。目录结构里还有一个重要文件是skills.json它定义了每个技能的元数据名称、描述、入口脚本、参数签名。这个文件是只读的系统升级时会覆盖你想自定义技能应该放到~/.superpowers/custom-skills下别直接改默认文件。4. 如何引入和调用这些技能4.1 引入技能的最简方式配置文件的写法光装好还不够你需要告诉 Superpowers我要在哪个项目里启用哪些技能。这一步通过项目根目录下的superpowers.config.json来实现。我直接给一个最小可用的例子{ version: 1.0, skills: { enabled: [review, explain, generate-tests] }, context: { projectRoot: ., language: javascript } }这个配置的意思是在当前项目里只启用三个技能其余默认技能虽然在全局装好了但不会在这里生效。如果你希望某个技能对当前项目禁用可以在disabled数组里加名字显式禁用比隐式不启用更安全因为团队的公共配置可能会把技能加回来你能一眼看到有人把它关掉了。context里的language不是必填但强烈建议你填上。它的作用是让技能提前知道目标语言比如生成测试时它会优先选择对应语言的主流测试框架。如果你不填很多技能会先做一次语言探测多花几秒不说碰到混合项目还容易探测错。4.2 在项目中按需加载白名单与别名机制Superpowers 支持把技能绑定到短命令上这个机制叫别名。比如你不想每次敲superpowers run generate-tests --input src/utils/format.js这么长一串可以在配置里加一个aliases段{ aliases: { t: generate-tests, r: review, x: explain } }之后就能用superpowers t src/utils/format.js代替原来的整串命令。我以前觉得别名是花架子直到有一天连续跑了二十多次测试生成才意识到这个设计多重要。如果你是在编辑器里通过快捷键调用别名还能简化键盘输入的负担。更值得关注的是技能组合的引入方式。你可以定义一条工作流把多个技能串起来。比如{ workflows: { pre-commit: [review, generate-tests] } }这样每次提交前只需执行superpowers run-pre-commit它会按顺序先做代码审查再生成测试。技能会共享同一个上下文对象第二步能看到第一步的输出结果所以不是简单的命令拼接而是真正的流水线。4.3 调用技能时的参数约定与实际示例每个技能都有自己的参数签名但所有技能都遵守几个通用约定--input指定输入文件或目录--output指定输出位置。如果什么都不传大部分技能支持从标准输入读内容这在管道场景下特别有用。拿 review 技能举例我常用两种调用方式# 方式一审查某个文件 superpowers run review --input src/controllers/user.js # 方式二审查两次提交之间的改动 superpowers run review --input diff://main..featurediff://这个前缀是 Superpowers 特有的输入类型它会自动算出两个 Git 分支之间的差异然后只对差异部分做审查。这个功能非常实用因为全量审查一个几万行的老文件输出会又长又散而基于 diff 的审查能精准定位新增的风险。我实测下来审查一个 300 行文件大约耗时 8 秒审查一个 diff 则只要 3 秒左右因为上下文窗口精简了很多。输出格式也支持配置比如指定 JSON 输出方便程序继续处理superpowers run review --input src/controllers/user.js --output jsonJSON 输出会包含问题级别、文件位置、问题描述、修改建议四个字段。如果你要做 CI 集成强烈建议用 JSON 输出再配合 CI 脚本把结果贴到 MR 评论里整个流程自动化就闭环了。5. 实操过程从零到一让Superpowers在真实项目中跑起来5.1 场景改造一个遗留的后端服务口说一百遍不如自己跑一遍。接下来我带你走一个真实案例对一个遗留的 Express 后端服务做上线前体检。这个项目是一个老旧的用户中心服务代码差不多有五年历史路由文件里塞了大量业务逻辑几乎没有单元测试。以前每次发版都要靠人肉回归出事风险很大。我的目标有三个定位明显的安全问题、给核心模块补上基础测试、输出一份能提交给团队的审查报告。整个过程我只用 Superpowers全程大概花十五分钟。第一步进入项目目录并初始化配置cd legacy-user-center superpowers initinit命令会引导你生成superpowers.config.json。我被问到要启用哪些技能时直接全选了 security-scan、review、generate-tests 和 docgen。初始化完成后它会自动扫描项目结构并把识别到的技术栈信息补充到 context 里。5.2 逐步演示代码审查、重构、生成测试与文档我先跑安全扫描目标是整个src目录superpowers run security-scan --input src --output security-report.json命令执行完后终端会立刻给出一个概要表。真正让我眉头一皱的是它标出的一条 High 风险src/utils/auth.js里硬编码了一个 JWT 密钥。这个文件我翻了半天都没注意到因为密钥藏在第 47 行一个看似无关的常量后面。安全扫描能找到这种问题比单纯靠人眼靠谱太多。然后我针对这个文件跑 reviewsuperpowers run review --input src/utils/auth.jsreview 返回了一份 14 行的报告其中第 6 条建议把密钥从环境变量中读取并补充了process.env.JWT_SECRET的写法。这种建议本身不稀奇但省去了我在 IDE 里来回跳转的时间。紧接着我调 refactor 技能把src/routes/user.js里一段 120 行的验证逻辑抽成了独立模块。重构结果保留了原有行为几乎没有破坏性修改。测试生成这一步最有意思。我原以为对于这种没测试的老项目generate-tests 会直接报错。没想到它先分析了src/services/userService.js的依赖关系然后生成了带 mock 的测试骨架mock 了数据库层和日志层连beforeEach都按构造函数注入的依赖顺序排好了。我只需要补齐几个断言的具体值这个文件的测试就能跑通。文档生成放到最后superpowers run docgen --input src/routes --output docs/api.md它把四个路由文件梳理成了一份包含路径、方法、参数、响应示例的接口文档。虽然格式比较朴素但作为内部参考完全够用。5.3 效果对比引入前后的体验差异这轮实操下来最直观的变化是时间。按我以前手工流程审查 补测试 写文档至少需要大半天这次从安装到产出报告一共不到二十分钟。当然生成出的内容不是零成本可用测试需要微调断言文档需要补充业务背景但骨架搭建的部分已经完全被技能接管了。更重要的变化是遗漏率的下降。以前代码审查靠个人经验看多了会麻痹硬编码密钥这种问题很容易漏掉有了 security-scan 强制检查等于给流程加了一道机械保险。团队合作时也方便因为 Superpowers 的输出格式稳定不管谁来跑都能得到结构一致的结果评审效率自然就上去了。6. 常见问题与排查实录6.1 安装失败或命令找不到最常见的坑是安装完成后敲superpowers提示 command not found。这是 npm 全局安装目录没写进系统PATH。解决方案npm config get prefix比如输出是/usr/local那你就把/usr/local/bin加入PATH。macOS 上如果使用 nvm 管理 Node全局包通常会落在~/.nvm/versions/node/vxx.x.x/bin这个路径一般已经自动配置没必要手动改。如果你使用 zsh执行完修改后记得source ~/.zshrc。另一个常见问题是安装时出现 EACCES 权限错误。说到底就是 npm 没有足够的目录权限。我建议不要直接用sudo npm install -g因为会带来权限混乱和依赖被意外篡改的风险。更好的做法是用 nvm 或者 volta 管理 Node 版本它们会把全局目录放在用户目录下从根源上避开权限问题。6.2 技能执行超时或内存溢出当你处理的文件特别大比如上万行的压缩文件跑 review 或 security-scan 时可能会报超时。默认超时是 60 秒可以通过传入--timeout 300调整。内存问题可以通过命令行参数解决NODE_OPTIONS--max-old-space-size4096 superpowers run refactor --input src但这里要提醒一句超时和 OOM 有时候是技能对内容规模的一次预警。如果一份文件大到需要 4GB 内存来处理你真正应该拆解的是文件的复杂度而不是硬扛着让技能跑完。我遇到过一位同事强行调大内存跑一个遗留的单文件模块结果生成的测试因为 mock 层级过深根本没法用最后还是要先拆模块。技能只是工具不能替代工程治理。6.3 与本地工具链冲突的解决思路Superpowers 在生成测试时会优先选择项目中已经配置的测试框架。如果你的项目用了比较冷门的测试工具它可能识别不了导致生成的测试风格和项目里其他测试不一致。解决办法是在superpowers.config.json的context里显式声明{ context: { testFramework: jest, testPattern: **/*.test.js } }如果你用了 ESLint 的严格规则生成的代码可能触发一堆警告。不用慌让 review 技能再扫一遍生成出来的测试代码就行它知道如何适配常见的 lint 规则。版本冲突也是有点烦的问题特别是别让 Superpowers 自己集成的依赖和你项目的依赖打架遇到这种情况改成npx superpowers调用本地的项目级版本而不是全局版本通常就能解决。7. 一些额外的使用心得与避坑建议7.1 别把什么都交给AI技能也要分轻重缓急我见过不少朋友装完 Superpowers 以后恨不得每个步骤都让它跑一遍结果生成了一堆自己都懒得看的报告。这不是工具的错是使用思路的问题。我自己的原则是机械性的、规则明确的、允许试错的任务交给技能判断性的、影响面大的、需要拍板的决策留给人。比如 generate-tests 这活儿生成错了重跑成本很低适合全自动而 review 的结果必须有人复核因为它是建议不是圣旨。工具的价值在于把白纸黑字的工作自动化让自己腾出精力去处理那些灰纸黑字的问题。这也是我反复跟团队讲的一句话AI 技能包负责把效率提起来但责任始终在写代码的人身上。别因为输出看起来专业就失去判断力这是对工具最大的尊重。7.2 自定义技能的入口不只是用还能造Superpowers 的第三个级别是自定义技能。它支持你用 JavaScript 或 TypeScript 写一个入口文件放到~/.superpowers/custom-skills里然后在配置文件中声明即可。一个最简单的自定义技能只需要三步新建文件夹~/.superpowers/custom-skills/say-hello在里面创建skill.json填写技能名称和入口创建main.js导出一个 async 函数技能函数会接收一个参数对象里面有input、output、context等字段。你完全可以手动实现一个只属于你们团队的代码规范检查器然后让所有技能一起工作。这对团队的意义特别大。很多团队积累了几百条自己的 code review 经验但都散落在文档和聊天记录里。把这些经验写成自定义技能之后每次 review 都会自动执行等于是把团队记忆固化到了工具链里。新手加入团队时跑一遍技能就能快速沿用团队的约定比啃三个月文档高效得多。7.3 后续扩展把你的技能包分享给团队当你调好了一套适合团队的技能组合下一步就是让它变成团队公共资产。推荐的做法是创建一个 npm 包把配置、自定义技能和文档都放进去然后让队友通过一条命令安装。Superpowers 支持从配置文件离线加载本地技能所以不需要造复杂的服务端一个小工具包就够了。我在自己的团队里就是这么做的。我们用 Git 仓库维护一套 team-superpowers 包里面包含统一的superpowers.config.json、三个自定义技能、以及一份如何安装的 README。新同学入职第一天跑三条命令就能获得和老员工一致的 AI 工作流那种体验真的比发 50 页入职手册强太多。我自己跑了一段时间以后最大的感触是技能包这个东西真正难的不是安装和调用而是想清楚哪些工作值得固化、哪些值得放手。Superpowers 给你的是一个框架用它来放大和扩展你原有的能力而不是替你做主。只要你守住人在回路的底线它就会成为你日常开发中最得力的同事。