最近几个月，AI 编码辅助工具的圈子里突然冒出一个名字：Superpowers。我最早是在技术社区看到有人发帖说"装了 Superpowers 之后，我把之前那个 XXX 插件彻底删了"，当时第一反应是这名字起得也太中二了，一个 VS Code 扩展而已，至于叫"超能力"？后来抱着试试看的心态装上，实际用了两周，确实有点被震到。
它不是又一个"聊天机器人式"的 AI 补全插件。Superpowers 的定位很明确：让 Claude、GPT 这类大模型真正动手改你的代码，改文件、建目录、跑命令，而且每一步都要经过你的授权。听上去像 Cursor 那种 agent 模式，但它的控制粒度、快照回滚机制和配置文件设计，比我用过的其他几个 agent 工具都要舒服。这篇文章不打算做什么软文式推荐，就按我自己的实操经历，把安装、配置、日常使用和踩坑过程完整梳理一遍。如果你正想装 Superpowers，或者装完之后用得不太顺手，这篇应该能帮上忙。
1. 为什么我弃用"聊天式补全"，转投 agent 式编辑
1.1 传统 AI 插件最大的问题：模型看得见，但改不着
先说清楚我之前的困境。用 GitHub Copilot 或者各种对话式 AI 编程插件时，最常见的交互差不多是这样的：你在侧边栏跟模型说"帮我把这段日期解析的逻辑改健壮一点"，模型会把一长段修改后的代码吐在聊天窗口里，你负责对照着原文去手动替换。改一个函数还好，一旦涉及多个文件、跨模块调用，这种"人肉复制粘贴"的模式就非常折磨。
举个例子，之前我处理一个老项目的模块拆分，要把utils.ts里的十几个工具函数按领域拆到format.ts、validate.ts、file.ts三个文件里。按理说这种需求很明确，但用对话式 AI 做的时候，模型每次只给我一个文件的建议，我却要自己记住哪些函数已经搬走了、哪些导入路径需要同步更新，还要手动修改五六处 import 语句。改了以为对的，结果实际报错，反反复复搞了快一下午。那种感觉就是：模型确实看得见我的代码，但它伸不了手，所有脏活还是我来干。
1.2 Superpowers 的核心理念：让模型动手，但每步都得过我的手
Superpowers 出现之前，我其实也试过 Cursor 的 agent 模式和 Cline 这类工具。它们的思路已经是"让 AI 直接改文件"了，但我个人的体验是控制感不够，很多时候 AI 一口气改了很多文件，我压根没来得及细看，就不得不接受它的改法，想回滚也比较麻烦，得靠 git 来兜底。
Superpowers 给我最不一样的感觉，是它把"请求建议（Ask）"和"动手执行（Act）"彻底分开了。Ask 模式下，模型只负责回答思路和展示拟修改的方案，不会碰任何文件；Act 模式下，模型才会真的调用编辑器能力去增删改文件。每次 Act，它会把将要修改的文件、具体 diff、操作理由一条条列出来，等你点了批准才执行。这意味着模型有了"手"，但这只手的控制权始终在你这。
用大白话讲，传统 AI 插件像是一个只会支招的顾问，给你出一堆主意然后让你自己去干活；Superpowers 更像是一个你盯着他干活的实习员工，每动一处都要向你汇报，你觉得不对随时叫停。对于写代码这件事，"被人盯着干活"听起来有点烦，但实际操作下来，那些授权提示其实非常快，几秒钟就能滑一遍，而且它换来的是你敢让 AI 动真格的勇气。
2. 安装前先搞清这四件事：环境、模型、密钥、预算
2.1 环境要求其实很低：VS Code 版本与网络
先说环境，Superpowers 是标准 VS Code 扩展，不要求你额外装 Node.js 环境，也不依赖 Python 侧的东西，只要你的 VS Code 版本不算太老就行。按我接触到的信息，1.90 以上的版本基本都能正常跑，如果你用的是一个更新很积极的分发版，直接装不用操心版本兼容问题。
但有一些隐藏条件容易被忽略：一是你的网络需要能正常访问扩展市场；二是运行的时候，扩展要根据你配置的模型服务商去发 API 请求。如果你是国内网络环境，建议先确认一下 VS Code 市场访问和对应模型 API 的连通性，不然装完扩展之后面板一直转圈，很容易误以为是扩展坏了。我自己的习惯是装之前先在终端里用 curl 简单测一下模型服务商的接口通不通，再决定后面怎么配置。
2.2 模型供应商怎么选：官方 API、聚合平台，还是本地模型
Superpowers 本身不内置大模型，它只是"发动机壳"，你得自己给它配一台"发动机"。目前支持的模型接入方式比我想象中全，主流的大概是这么几类：
| 接入方式 | 代表 | 优势 | 要注意的短板 |
|---|---|---|---|
| 官方 API | OpenAI、Anthropic、Google | 稳定、响应快、模型质量最高 | 需要外币信用卡或海外支付，成本略高 |
| 聚合平台 | OpenRouter 等 | 一个 key 用多家模型，方便切换 | 部分模型限流，高峰期延迟波动 |
| 本地模型 | Ollama 接 Llama、Qwen 等 | 数据不出本机，零 API 成本 | 显存要求高，小参数量模型写代码能力明显打折 |
如果你问我个人建议，第一次体验 Superpowers，最省心的不是本地模型，而是直接用 Anthropic 或 OpenAI 的官方 API。原因很简单，这个扩展本身就是按照 agent 式工具链设计的，对模型规划能力和长上下文的要求非常高，本地小模型很容易在"计划→改代码"这个多步任务里跑偏，你会误以为扩展不好用，其实是模型拖了后腿。
当然，如果你的数据比较敏感、公司有合规要求，那就必须考虑本地模型了。Ollama 跑起来不算难，但对显存是真的挑剔，跑 Llama 3 70B 这种能打的模型，你得有 48GB 以上显存，普通消费级显卡基本跑不动，只能退到 7B、8B 级别。我之前在一台 32GB 内存的 M 芯片 Mac 上试过本地小模型写代码，能用，但那种质量你不会有勇气把它派去动大项目的。
2.3 API 密钥的存放：把 key 写进 settings.json 不是好习惯
配置模型 API key 的方式，Superpowers 支持在扩展设置里填，也支持走环境变量。我看不少人直接把 key 贴在settings.json里，方便是方便，但如果这个配置文件被同步或被分享出去，密钥就相当于裸奔了，而且只要你动过一次 key，git 历史里可能还留着旧的。
正规做法是走环境变量，或者配合 VS Code 的dotenv机制。我自己是配了一个项目级的.env文件，里面放ANTHROPIC_API_KEY之类的变量，然后确保这个文件被.gitignore忽略。这样团队其他成员 clone 项目之后，只需要复制一份.env.example改成自己的.env填上 key 就能跑，不会把密钥污染到代码仓库里。
2.4 预算心里要有数：一次任务大概烧多少 token
这块不写清楚，很多人会踩"月末账单翻倍"的坑。agent 式工具不是聊天窗口，它内部是有循环的：模型先看你的代码、生成计划、改文件、再检查结果，每一步都要消耗 token。一个中等规模的任务，比如"把 3 个文件之间的错误处理方式统一成 Result 模式"，实测下来大概要吃掉 3 万到 6 万 token，偶尔复杂一点会冲到 10 万。
按 Claude Sonnet 的定价粗算一下，一个普通重构任务大概是 0.1 到 0.3 美元之间。听着不贵，但如果你一天让 Superpowers 干 20 次任务，就是每天几美元，一个月下来确实是一笔不小的开销。所以我在后面的进阶玩法部分会专门讲怎么给任务"瘦身"，这里先提醒一句：开始用之前，建议去模型服务商后台设置一个消费上限，别等账单来了才后悔。
3. 两种安装路径实测：扩展市场装与源码编译
3.1 最简单的市场安装：从插件面板直接搜
安装路径第一条，也是最推荐大部分人的方式：打开 VS Code，按Ctrl+Shift+X（Mac 上是Cmd+Shift+X）打开扩展面板，搜索Superpowers，认准那个从发布者信息看都靠谱的版本，点 Install 就可以了。
等它装完，侧边栏应该会出现对应的图标。网上很多教程会顺便告诉你"按 Ctrl+Shift+P 输入 Superpowers 打开面板"，但实际装完之后最好先重新加载一下窗口，保险起见Ctrl+Shift+P执行一下Developer: Reload Window，避免扩展激活异常。这一步是我踩过的坑之一，后面专门展开。
3.2 源码编译安装：给需要最新功能或者离线环境的同学
如果你是那种喜欢用 GitHub main 分支最新代码的人，或者公司内网不允许直接访问扩展市场，那就走源码编译路线。整个过程其实就三步：
git clone https://github.com/val-town/superpowers-extension.git cd superpowers-extension pnpm install pnpm run package打包完成后，项目目录里会生成一个.vsix文件，然后在 VS Code 里按Ctrl+Shift+P，执行Extensions: Install from VSIX...，选中这个文件就装好了。
这里插一句，我不建议没有明确需求的普通用户走编译路线。我自己试过一次，pnpm install那一步因为网络原因重试了好几回，而且源码版本有时候会混入尚未验证的功能，稳定性和市场正式版有差距。日常使用装市场版就够了，真遇到底层 bug 想验证修复，再临时编译一个来测。
3.3 首启配置：模型加载与密钥绑定
第一次点开 Superpowers 面板，它一般会引导你做两项设置：选择模型供应商和填入 API key。如果你跳过了引导，之后也可以在 Settings 里找到对应配置项补上。
这里有个小细节：Superpowers 的主模型和备选模型是分开配置的。主模型决定日常的 agent 任务走谁，备选模型会在主模型不可用时自动顶上。我个人的配置习惯是主模型放 Anthropic 的 Claude 系列（写代码综合体验好），备选模型放 OpenAI 的 GPT 系列（接口稳、兜底快）。如果你用的是聚合平台，一个 key 就能同时给主备模型用，省心不少。
首启配置填完之后，建议先在 Ask 模式下发一个简单问题试试水，比如"这个文件里最大的一段逻辑是什么"。如果模型能正常回复，说明链路是通的；如果一直转圈或者报错，先别急着折腾配置，大概率是网络或者 key 的问题，往下看到排查那一节。
4. 核心使用逻辑：从"对话式提需求"到"任务式干改造"
4.1 Ask 与 Act：请求建议和动手执行要分清楚
Superpowers 用起来和普通聊天插件最大的区别，就是你要有意识地在"Ask"和"Act"之间切换。两个词直白得很，但我发现很多人用不顺手，问题恰恰出在没分清楚这两个模式。
Ask 模式，适合需求还没完全想清楚的时候。你在面板里输入"我这段递归解析目录结构的写法有没有隐患"，模型会基于上下文给出分析和方案，但不会动你的代码。这本质上还是传统聊天工具，但好处是它借用了 agent 的上下文窗口，能把当前打开的多个文件一起装进去理解。
Act 模式，才是 Superpowers 真正开始干活的时候。你可以提"在上面的方案基础上，直接把循环改成栈式迭代，并且把相关的类型定义也建好"，这时候它会先给出一个执行计划，然后把会改动到的文件列表、每处 diff 都列出来，等你逐条批准或者一次性批准，然后才开始操作。
我的实际经验是：凡是涉及多文件、多步骤的改动，一律先 Ask 让模型出方案，仔细看一下它打算怎么改，确认大方向没问题，再切到 Act 让它执行。别一上来就直接喂给 Act，否则模型很容易在细节上跑偏，你也看不清它到底想干嘛，授权按钮就变成了无脑放行。
4.2 实操一个多文件重构：从提需求到回滚的完整流程
空讲概念没用，我拿前几天做的一个真实小重构来演示。原始需求是这样的：项目里有一个utils.ts，里面混了日期格式化、金额校验、文件路径处理三坨完全不相关的函数，我想把它们拆成三个模块，并且把所有引用到这些函数的地方都改掉。
按老办法，这就是上面说的一下午噩梦。用 Superpowers 的 Act，我做的事情很简单，在面板里输入：
把 utils.ts 按功能拆分成 format.ts、validate.ts、file.ts 三个文件，文件名暗示用途，并且自动更新整个 src 目录下所有 import 语句引用这些函数的地方。它给我的执行计划大致是：先读取utils.ts全貌，分类函数，创建三个新文件，改写原文件为纯 re-export 或者删除，然后全项目扫描 import 并逐个更新。每一条操作，面板上都会显示文件路径和改动原因。
我检查计划的时候注意到一个问题：它计划把utils.ts整个删掉，但这一步如果删了，旧引用漏改的话整个项目就编译不过。代理模式最怕的就是这种"计划里合理、实际风险高"的操作。所以我当时做了一处调整，让它先保留utils.ts作为 re-export 的迁移层，等编译通过后再单独做一次"清理迁移层"的二次任务。事实证明这个保留步骤非常值，因为真的有一个测试文件的 import 路径没有被自动扫到，如果当时直接删了老文件，那个测试文件就直接爆红。
全部执行完之后，Superpowers 给了一个任务总结，列出了改动的文件数量和每个改动点。我配合编辑器的源码管理视图扫了一遍 diff，确认没问题，再跑了一遍测试用例，收工。
4.3 Checkpoint 的快照机制：敢让 AI 大改代码的底气所在
这个功能是我认为 Superpowers 最值得说的一环，也是它敢叫"Superpowers"的底气之一。每次你启动一个 Act 任务之前，它会在项目里自动创建一个检查点（checkpoint），相当于把你当前所有文件的状态做了一次快照。
任务过程里改的五花八门也不用怕，因为检查点把底线给你兜住了。任务结束之后，你可以随时用一个命令调出检查点视图，逐文件对比"改动前"和"改动后"的内容，看哪个文件改得对，哪个文件改得让人冒汗，然后精准地对单文件做回滚，或者干脆整体回滚到任务前的状态。
我之前一度很怕让 AI 碰"有历史包袱"的老项目，因为它一跑起来经常牵连出一堆看似相关、实则不该动的地方。有了检查点机制，我相当于给 AI 装了一条安全绳。第一次用它回滚，我只花了不到一分钟，就把模型在 20 分钟里改得乱七八糟的 7 个文件全部恢复原状，那种掌控感是用普通 AI 插件完全体会不到的。
提示：检查点是 Superpowers 自己的快照，不是 git 提交。它不会污染你的 git 历史，也不依赖你已经 commit。两者并行不悖，但我更推荐把它理解成"改动保险"，你仍然应该在任务结束后用自己的 git 提交记录一次成果。
5. 实测中遇到的坑与排查过程
5.1 面板打不开：扩展没激活才是罪魁祸首
我先说一个最打击新手的现象：装完扩展，侧边栏图标也出现了，但点开之后面板一片空白，或者命令面板里输入"Superpowers"根本没反应。这种时候十有八九不是扩展坏了，而是VS Code 的工作区信任机制卡住了。
VS Code 对来自网络的项目默认是"受限模式"的，很多需要写文件的扩展在这种模式下会被禁用或半禁用。Superpowers 这种要改你文件、跑命令的工具，恰恰受限最严重。解决办法很简单：打开一个可信的本地项目目录，然后在弹窗里选择信任该文件夹，或者通过命令面板执行Workspaces: Manage Workspace Trust，把当前工作区标记为受信任，再Developer: Reload Window一次。
如果信任问题解决了还是打不开面板，那就去检查左下角状态栏有没有报错。常见的情况是扩展加载时读取不到配置文件，直接抛异常，那种一般会在输出面板里留下堆栈，按Ctrl+Shift+U打开输出，把日志拉到最底看，报错信息里通常能定位到是哪个模块出了问题。
5.2 模型一直报超时：网络、限流与并发挨个查
用过一段时间之后，我最常遇到的故障其实是"模型响应超时"。特别是用聚合平台接热门模型的时候，高峰期非常容易出现迟迟不回话的情况。排查这类问题，我的建议是一条链路一个环节地排，别上来就重启大法。
第一步，确认不是网络问题，在终端里直接调一次接口：
curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"ping"}]}'如果这条命令能快速返回结果，说明网络和 key 本身没问题。接下来去模型服务商的后台看一下当前请求的并发占用率和限流情况，很多聚合平台会在并发高时直接排队，表现在扩展里就是一直转圈。
最后再去看 Superpowers 自己的输出日志，它会在任务超时的时候打印具体的异常信息。如果日志里出现"rate limit"字样，那就没什么好说的了，要么等下一分钟，要么换一个不那么拥挤的模型，或者把任务的 token 预算调小一点，让它别一次吃那么多上下文。
5.3 授权弹窗太频繁：用白名单规则自动放行
授权机制是 Superpowers 的安全优势，但用久了也会烦。当你让它做一个跨 10 个文件的小改动时，它每改一个文件就弹一次授权请求，点起来非常磨人，体验一度让我想放弃。
后来我发现，它不是没有"自动放行"的设计，只是入口藏得比较深。在扩展设置里可以配置目录级别的 allow / deny 规则。比如常见的依赖目录和配置文件目录，你其实并不想让 AI 天天在那儿提供输出，就可以把node_modules、dist、锁文件这类直接放进元规则禁止列表。对于你自己的源码目录，你可以在足够信任的基础上，把"每次新操作都需要授权"改为"本任务内首次批准后自动放行后续变更"。
实操起来大概是这样：刚开始不熟的时候，保留全量授权确认，让你逐渐理解它每次改动可能影响哪里；等项目跑了几天，你对它的行为模式有了把握，再给src目录打开自动放行，把弹窗频率从"每次操作"降到"每次任务"。这样既保留了检查点兜底，又不会让你在审批上耗费太多精力。
5.4 上下文窗口不够用：长项目的分段策略
还有一个我用久了才总结出来的坑：当你打开一个大仓库，并且要求 Superpowers 跨多文件改一个大功能时，很快你的单次任务会触及上下文上限，模型开始忘掉前面的改动，后面给出的方案明显变"飘"。
这不能怪工具，agent 的上下文窗口是硬约束。解决办法不在"调大窗口"，因为再大的窗口也架不住你无限塞东西。我的做法是执行"任务切细"策略：一个大需求，先让它做阶段一（比如梳理结构和写计划），确认计划后再执行阶段二（改核心模块），阶段三（处理依赖与测试）单独开新任务。每一次任务让它专注在一小块改动上，既不容易超窗口，每次授权时你也更好判断它改得对不对。
另一个技巧是，别把"全仓库所有文件"都丢给模型去理解。Superpowers 支持手动把当前打开的相关文件作为上下文带进任务，你应该主动清理编辑器里的标签页，只留下跟本任务密切相关的文件，这样等于省下了大量无效 token，老项目里尤其管用。我算过一笔账，一次跨 5 个文件的重构，如果上下文里多躺 20 个无关文件，token 消耗能差出两三倍。
6. 进阶玩法与现实建议
6.1 把团队的代码规范塞进提示词模板
用了一段 Superpowers 之后，我最大的感受是：它越用越顺手，很大程度上取决于你愿不愿意帮它"预习"你的项目规范。比如你们团队要求组件必须用函数式写法、错误处理统一走自定义的AppError、测试文件命名必须带.test后缀，这些规则如果不告诉它，它每次都默认按通用最佳实践来，改出来的东西你还得自己调。
解决思路是维护一套自己的提示词模板。Superpowers 支持在项目里放一个自定义提示词目录，把团队规范写成一段系统提示，每次任务启动时它会自动加载进去。我自己的项目里会放这样一段内容：
项目规范：TypeScript 项目，禁止使用 any，错误统一使用 AppError 类型，所有对外方法必须带 JSDoc，测试文件一律放在 __tests__ 目录。就是这几行话，让模型产出的东西从"泛泛而谈的优质代码"变成了"贴合你团队口味的代码"。在我看来，agent 式编程工具的上限不是由模型决定的，而是由你喂给它的"背景知识"决定的。
6.2 多模型配置与降级策略：避免主模型挂掉就停摆
依赖单一模型的 agent 工具，最怕的事情就是服务商半路出故障。Superpowers 支持配置一个备用模型，这个功能强烈建议所有重度用户打开。我自己就把 Gemini 系列当作备胎，响应速度不错，某些长文档理解场景甚至比主模型还稳。
一个实用操作小技巧：在状态栏里，Superpowers 会显示当前任务正在使用的模型和累计 token 数。养成每次任务结束扫一眼 token 数的习惯，既能帮你看预算，也能让你大概估算当前任务的复杂度，下次拆任务的时候更有分寸。
6.3 谁适合用，谁其实没必要装
最后说点大实话。Superpowers 不是万能钥匙，它最适合的场景是：你已经在用 VS Code 写项目，且经常做跨文件重构、模块拆分、代码迁移这类"多步且机械"的体力活。这种场景下，它的 agent 执行+快照回滚简直是把生产力拉满。
但如果你平时只用 AI 问几个 API 的用法、写个一次性脚本，或者你主力语言生态对自动代码生成支持很差（比如某些领域专用语言），那装 Superpowers 属于杀鸡用牛刀，还要为了授权机制多操一份心。还有一种情况也别勉强，就是你的项目编译时间极长、单次全量编译要十几分钟那种，agent 每次改完都要靠编译来验证，效率会被拖累得非常明显。
根据我个人的实操体会，Superpowers 最值得学的其实不是某个具体功能，而是它代表了一种范式转换：AI 不是给你答案的人，而是你手里一支需要你用审批约束的笔。装它之前，建议你把"信任边界"想清楚——哪些目录随便它改、哪些目录死了都不能动。把这个边界立好，它的超能力才能真正为你所用，而不至于变成脱缰野马。
