最近在折腾 Codex CLI 的时候偶然试到了 Superpowers 这个工具包一句话总结就是它把原来只会“你问我答”的 AI 编程终端变成了一套能自己拆任务、写计划、跑循环、修 bug 的流水线。项目名字起得很狂但实际用下来确实能感觉到那种“从普通助手到开了挂”的差距。这篇文章不打算照着 README 念主要聊聊我在实际安装、配置、跑项目时踩过的坑以及我最后总结出来的一套相对稳定的用法。适合那些已经在用 Codex 这类 CLI 工具、但觉得“AI 写得出来却管不住”的开发者也适合想入门 AI 辅助开发的新手看看这类增强工具到底能把效率抬到什么程度。先说清楚Superpowers 不是一个能直接帮你写代码的独立模型它更像一层“技能包”专门用来弥补终端型 AI 助手的短板。比如原生 Codex 往往只处理单次请求问一句答一句一旦任务复杂一点它就开始丢上下文。Superpowers 的做法是把任务规划、步骤拆分、上下文管理、自动测试、循环执行这些能力做成可复用的“技能”让 AI 在干活的时候能自己先编排、再执行、后复盘。下面我就从 “为什么需要它” 讲起一步步拆解安装、核心用法、配置项和排错思路。1. 为什么原生终端里的 AI 像个“实习生”——Superpowers 的定位与价值在聊安装前我想先花点篇幅说说这个工具存在的理由。很多人第一次用 Codex CLI 的感觉是“很惊艳但不太可控”。你让它写一个函数它写得很漂亮你让它实现一个完整的登录模块它可能写到一半就忘了前置假设或者直接给出一个表面上能跑、实则漏洞百出的方案。这不是模型能力不行而是交互方式有缺陷终端型 AI 没有持久记忆没有任务状态的感知也不擅长把大问题拆成小步骤。Superpowers 解决的就是这件事。它给 AI 定义了一整套“超能力”技能每个技能对应一类高频操作。我印象最深的是它内置的“任务规划”技能当你输入一个比较模糊的需求比如“给项目加上用户反馈功能”Superpowers 不会直接甩出一段代码而是先让 AI 进入规划模式生成一份包含数据模型、接口设计、页面组件、测试用例的任务清单。这个清单不是给人看的而是给 AI 自己后续执行用的。AI 会按照清单一条条往下做做完一条勾掉一条再启动下一轮。这就带来一个质变从“一次性问答”变成“多轮项目执行”。以前我需要不断手动补充上下文告诉它“上一步我们做了什么”“别忘了数据结构里有个字段叫 status”现在这些信息都沉淀在任务状态里AI 自己在执行过程中就能回顾。从实际体验来看原本需要我一两个小时的接口联调工作压缩到半小时左右而且中间 AI 自己写测试、自己跑测试、自己根据报错改代码我只需要在关键节点做 review。这种体验挺接近“带一个靠谱的实习生”——前期要花点时间教它规矩后面它就能独立干不少活。不过也要泼盆冷水Superpowers 不是万能的。我后面会详细说它的核心价值在于“让 AI 遵循流程”而不是“让 AI 变聪明”。如果你让它去处理一个连你自己都没想清楚的问题它会在错误的方向上高效地执行最后给你一个逻辑自洽但完全不符合业务的方案。所以它更适合“需求明确、步骤可拆”的任务比如重构模块、补测试、迁移接口、修 bug 这类工程化工作而不是让它去天马行空地做架构设计。2. Superpowers 安装与激活的全过程——从零跑到第一条命令2.1 安装前需要确认的环境虽然 Superpowers 本质上是一堆脚本和配置但它的运行依赖几个基础环境缺一个都可能让你在激活阶段卡住。我的建议是先把下面这几样准备齐Node.js 版本 ≥ 18。它内部不少技能脚本都是基于现代 JavaScript 写的版本太低会直接报语法错误。Codex CLI 或同类 AI 终端工具已安装并完成登录。Superpowers 不是独立运行的它需要挂载在一个能调模型的主程序上。Git 已经配置好全局用户信息因为部分技能比如“自动提交”会调用 git 命令。终端使用 bash 或 zsh并且允许写入 shell 配置文件。如果你想用 GitHub Copilot CLI 或者其他类似工具Superpowers 原则上也能适配但配置文件里需要显式指定模型接口。我本地的环境是 macOS zsh下面命令都是基于这个组合Linux 用户基本一样Windows 用户建议用 WSL在 PowerShell 里跑可能出现路径兼容问题。2.2 安装步骤安装过程其实很简单真正的坑都集中在安装之后的激活环节。官方推荐的方式是用 npm 全局安装npm install -g superpowers/core装完以后先别急着跑还有一个关键步骤把 Superpowers 的“技能目录”挂载到你的终端工具里。这个挂载不是自动完成的需要一个初始化命令superpowers init这个命令会在你的用户目录下生成一个.superpowers文件夹里面有默认配置、技能模板和日志目录。同时它会尝试检测当前终端里有没有可用的 AI CLI 配置文件如果有就自动写入一段“加载技能”的初始化脚本。接下来需要确认激活是否成功。直接跑superpowers doctor如果输出里每一项都是绿色勾说明环境没问题。如果某个检查项标红最常见的原因是它找不到 Codex CLI 的配置文件路径。你可以手动指定superpowers init --cli codex --config ~/.codex/config.toml这里需要注意--config后面的路径必须指向真实存在的配置文件。我一开始在 M1 Mac 上遇到过一个诡异问题superpowers doctor认为 Codex 没安装但明明终端里能执行codex命令。后来排查发现因为我的 Codex 是通过 Homebrew 安装的路径在/opt/homebrew/bin/codex而 Superpowers 默认扫描的是/usr/local/bin/codex。这种情况直接在配置里把 cli_path 指过去就行不用重新安装。2.3 第一条命令激活成功以后Superpowers 会注册一个全局命令一般就叫sp。你可以试一下sp 给当前项目中的所有接口调用加上超时重试机制如果一切正常你会看到输出里出现类似“加载技能任务规划、代码修改、自动测试”的字样然后进入一个交互式执行循环。没有看到技能加载日志说明配置文件里的初始化脚本没生效重新跑一遍superpowers init通常能解决。我把装好之后最常用的几个命令整理成了表格方便对照命令作用使用频率sp 需求描述进入完整任务执行循环自动规划、执行、测试最高sp --plan 需求描述只生成执行计划不实际改动代码高superpowers skill list列出当前可用的技能清单中superpowers skill add name从远程模板仓库安装新技能低superpowers logs查看最近的执行日志和错误信息排错时用需要提醒的是sp在首次执行时可能会请求你授予一些权限比如运行 shell 命令、修改文件、调用 git 提交。权限选项一般是allow、deny、always allow。我个人的习惯是前几次全部选择“allow”等确认它行为稳定之后再针对高频操作选择“always allow”避免每次都被打断。3. 核心技能拆解——Superpowers 在实战中到底在“开什么挂”搞定了安装接下来要理解它的核心能力。Superpowers 的价值全在技能Skills这个抽象层上。每个技能就是一组精心编写的 Prompt 模板和配套脚本它们组合起来形成了 AI 的“肌肉记忆”。我用的版本里默认开启了 8 个技能但真正在实战中帮我省时间的主要是下面这 5 个。3.1 任务规划先想清楚再动手这个技能解决的是“拿到一个模糊需求怎么办”。在没有 Superpowers 的时候我把需求粘给 Codex它立刻就开写写到一半才发现理解偏了。有了任务规划技能后sp会先进入一个“思考模式”把需求拆成目标、约束、输入、输出、验收标准这几个维度然后生成一个有序的任务列表。这个步骤看起来费时间实际上是在帮 AI 建立状态后续每一轮执行都在这个状态里推进。举个例子我让它“重构当前项目中所有的 API 错误处理”。它生成的计划包含扫描所有调用 API 的文件、统一错误码规范、定义通用错误响应格式、更新现有逻辑、补充异常测试。然后它真的会按这个顺序执行而不是东改一行西改一行。这种方式对中大型项目尤其有用AI 不会因为某个文件里恰好出现一个相似函数就被带偏。3.2 上下文压缩防止干着干着“失忆”用过终端型 AI 的都知道上下文窗口再大也架不住长任务。干到第 10 轮模型几乎忘了最初的代码约束。Superpowers 处理这个问题的方式很巧妙每轮执行完毕后技能系统会把当前的关键状态——已完成任务、未完成任务、重要文件路径、当前分支、最新测试结果——压缩成一段结构化摘要存到工作区的临时文件里。下一轮开始时AI 会先读这段摘要再继续干。实际体验下来这个机制让长任务的稳定性提升了不止一个量级。我跑过一个持续 47 轮的“给老项目补注释和文档”任务全程没有出现过一次上下文错乱。如果你想自己验证可以在终端里观察它每轮输出前的“加载状态摘要”这句话看到这个说明压缩技能正在生效。3.3 循环执行不用一次次手动说“继续”原生 Codex 很烦的一点是每次只能执行一个动作然后停下来等你确认。Superpowers 的“循环执行”技能允许 AI 在方案允许的范围内连续执行多步包括修改代码、运行测试、根据报错再次修改。在交互式终端里你会看到类似“执行第 3/10 轮”的进度提示。这里有一个重要参数max_loops。它控制一轮任务中最多能连续执行多少步。我一开始用的默认值 5经常出现任务没干完就退出循环的情况。后来我改成 10但发现如果任务特别复杂10 轮也不够。更合理的做法不是无脑调大而是结合任务规划技能把大任务拆成几个子任务分别跑每个子任务在 5-8 轮内解决。这对保持上下文清晰很有帮助。3.4 自动测试让 AI 替自己背“质量压力”Superpowers 里有一个针对测试的技能它的行为模式很“死板”每次改完代码必须自动定位到相关测试文件运行测试如果有报错就返工。听起来简单但正是这个死板流程救了我好多次。有一次它帮我给一个 Python 项目新增批量导入功能改完后自动跑 pytest结果发现某个旧用例失败。AI 顺着失败堆栈追到了根因——不是它新增的代码有问题而是原有代码依赖的一个第三方库版本变了。如果没有自动测试这个环节这个 bug 可能要等我自己点开页面才发现。冲这一点我强烈建议在配置里把“测试命令”设置成你项目实际的测试指令比如npm test、pytest、go test ./...这样技能才能真正接入你的工程体系。3.5 自动提交与变更摘要把成果固化下来这个技能不复杂但非常省事。它会在每个阶段性任务完成后检查当前 git diff生成规范化的 commit message并提交到当前分支。最关键的是它生成的 commit message 不是传统的 “fix: 修改bug” 这种笼统描述而是类似“处理 API 超时异常增加重试机制与日志采样更新相关单测”。这大大方便了后续回溯。不过自动提交默认是开启的我建议在你不熟悉它之前先关掉。因为你可能不想让 AI 把每次实验性的改动都提交进历史记录。等跑顺了再开配合always allow权限效果会很舒适。4. 让 Superpowers 真正可控——配置文件里的关键参数与执行边界Superpowers 的强大和风险都来自于“循环执行”和“自动改代码”。如果不控制它的权限和参数你可能会看到它在仓库里翻箱倒柜甚至提交一些你不想要的改动。所以第四部分我们专门聊聊配置文件。4.1 配置文件在哪里运行superpowers init后会在用户目录下生成~/.superpowers/config.json也可能因版本不同是config.toml。如果你在项目里运行还可以创建项目级的.superpowers.yml让不同项目拥有不同的参数。项目级配置会覆盖全局配置我建议把通用设置放全局把模型模型、测试命令、禁用技能等项目相关配置放在项目里。4.2 核心参数的含义与调参建议打开配置之后你会看到一堆参数。我挑几个最可能影响实际行为的说明一下model指定使用哪个模型。我目前在 Codex CLI 环境里用的是其默认模型你也可以配置成其他支持 tool calling 的模型。选型上建议选上下文窗口大的因为任务循环长的时候很吃上下文。temperature控制回答的随机性。默认 0.2 是比较安全的如果发现 AI 太死板可以调到 0.4如果希望它严格执行流程就保持低一点。我不建议超过 0.6否则代码质量和流程稳定性都会下降。max_loops前面提过单个任务的最大执行轮数。我通常设置为 8配合任务拆分使用。如果是一个很长的全自动任务也可以临时设到 20但要警惕上下文失控。auto_approve控制哪些操作可以免确认。常见值有none、security、all。security表示只有安全的操作比如读文件、运行测试自动批准而写系统文件或执行删除命令仍需确认。新手建议用security。skill_dirs技能目录列表可以添加自己写的技能或从外部下载的技能。这是我的重点项因为我经常把团队的代码规范写成自定义技能然后让 Superpowers 在迭代时自动遵守。表格总结一下参数默认值我的推荐值说明model跟随 CLI 默认跟随 CLI 默认建议选模型上下文窗口较大的temperature0.20.3太低执行刻板太高容易乱跑max_loops58单任务执行轮数上限auto_approvesecuritysecurity不要默认设为allskill_dirs空项目特定技能目录团队规范类技能强烈建议加4.3 通过角色设定与约束控制行为除了参数配置文件里还有一个system_prompt或instructions字段可以注入一些全局约束。我在这里写了一些对我很有效的规则比如- 每次修改代码之前先列出影响范围。 - 不要改动与任务无关的文件。 - 所有新增的逻辑都必须有对应的测试。 - 遇到不确定的设计决策时输出选项并停下等待用户选择。这些规则和技能是叠加生效的。技能负责流程而这段 prompt 负责价值观。我的体会是用来约束 AI 的规则越具体越好越利于稳定产出。抽象词汇如“保持优雅”“注意质量”它没法执行但我上面那种“列出影响范围”“先跑测试”是它能遵循的指令。你可以在项目级配置里维护一套自己的约束慢慢打磨最后会形成非常有个人风格的 AI 工作方式。4.4 执行边界如何阻止 AI 乱权限很多人刚接触这类工具时最担心的就是“AI 会不会把我整个电脑格式化了”。Superpowers 的权限机制实际上已经做了分层读文件、写文件、执行命令、访问网络、调用 git都分别有独立的权限策略。你可以通过skill_dirs和auto_approve组合把某个技能的权限限制在特定目录。例如我经常在/tmp/ai-sandbox目录里跑一些高风险实验。我在全局配置里把默认的文件调整权限限制在/tmp/ai-sandbox/*这个范围内再单独允许当前代码仓库的写操作。这样即使 AI 在实验任务中产生了不可控行为也不会污染主项目。5. 实测中踩过的三类问题——完整排查链路与解决方案工具虽好坑也不少。这一节我分享三个我在真实使用中反复遇到、最后才摸清根因的问题。相比直接给答案我更想把排查思路写出来因为这比答案本身更有迁移价值。5.1 问题一技能加载顺序错乱导致“先执行后规划”有一次我运行sp 重构 utils 模块结果 AI 直接动手改代码完全没有生成任务规划。我一度以为 Superpowers 失效了后来通过superpowers logs看到日志里有一条警告“skill dependency check skipped due to missing skill_deps field”。原来是那个自定义技能的配置里没有声明它依赖“任务规划”技能所以执行器认为它不需要前置技能。排查链路是这样的先看日志里有没有 skip 或 warning → 再查对应技能的技能清单文件。每个技能目录下有一个SKILL.md文件或 yaml 头里面有一个dependencies字段。你在那个字段里加上planning重启后问题就消失了。这也提醒我给 Superpowers 添加自定义技能时要严格声明依赖关系否则它的执行顺序是乱的。5.2 问题二长任务跑到一半上下文还是溢出了我前面夸过上下文压缩技能但实际用了几个月后我发现它也不是永远有效。特别是一次性让 AI 重构 15 个文件并补充测试的任务跑到 40 多轮时输出开始出现重复代码甚至引用不存在的变量。当时日志里已经有 “context overflow, truncating” 的提示。排查之后我意识到问题不在压缩机制而是我的任务本身超出了合理粒度。压缩机制只保留摘要但当单个文件需要反复修改时摘要不足以覆盖完整细节AI 就开始“编造”上下文。我的解决方案是在上一个任务里加上“拆分点”。比如用sp --plan先按模块生成 3 个子任务然后逐个执行sp 完成第一个子任务清空上下文后再跑第二个。虽然需要手动启动几次但稳定性大幅提高。这个策略比较符合工具的定位——它擅长单点执行不擅长真正地长时间自治。5.3 问题三与原生 Codex 指令冲突导致 AI 不听命令还有一个高频问题在 Superpowers 的循环执行中我发送了codex quit想终止任务结果 AI 直接忽略继续执行下一步。这个问题的根源是 Superpowers 加载了自己的指令解析层而codex前缀的原生命令并没有被映射到“终止执行”。排查方法其实很笨我去看了~/.superpowers/config.json里command_prefix这个字段发现默认是sp。也就是说终止命令应该也是sp --stop而我用了quit这个自然语言词AI 把它理解为“退出某个逻辑模块”而不是终止进程。后来我做了两件事一是在全局 instructions 里加入“当用户输入 stop 或 quit 时立即停止所有行动”二是记住不要混用两套命令体系。如果你也是一边用 Codex 原生模式一边用 Superpowers最好在 session 层面分开不要在同一个会话里混用否则交互状态会互相干扰。6. 从“会用”到“用得顺”——我沉淀下来的工作流与使用心得最后这部分我想分享一套目前我一直在用的工作流。它不是官方文档里的推荐而是我踩过不少坑之后优化出来的只代表个人实践。6.1 我的标准工作流对一个中等规模的开发任务我会分成四步需求解析用sp --plan把模糊的需求变成一份任务清单。这个阶段只动脑不动手我用来确认 AI 理解是否准确。人工微调计划检查任务清单删掉不合理的步骤补充必要的边界条件然后保存为项目里的.task.md文件。分段执行按计划一项一项执行每个子任务单独运行sp 执行 .task.md 中的第 N 项。每完成一项用superpowers logs快速看一眼变更摘要。整体 review任务全部完成后我再挨个看 git diff 和测试报告必要时回滚某些提交。这个流程看起来比一键式自动化麻烦但产出质量和工作体验都好很多。因为你看Superpowers 再强也是个执行器真正把握方向的人还是你。把它当成一个“能自己干活的键盘手”而不是“能替你做决定的作曲家”。6.2 适合与不适合的场景从我个人的项目经验来分个类。很适合的场景代码重构、补充单元测试、修 bug特别是能稳定复现的、接口联调、依赖升级、自动化脚本生成、技术债清理。这些任务边界清楚验收标准直白Superpowers 能发挥出很高的自主性。不太适合的场景产品原型设计阶段、跨系统架构设计、需求本身还在快速变化的项目。这类场景里 AI 容易根据它的想法“自由发挥”然后给你一个看起来完整、实则不一定符合业务目标的结果。你需要在 prompts 里反复约束或者频繁打断反而比人工更累。我举个反例有段时间我让它帮忙设计一个多租户权限模型生成的方案很漂亮但放到真实业务里底层数据模型的选择和合规审查完全不是它能理解的。折腾了一天最后我自己重写。所以不要因为工具很“强”就把认知负担完全外包这也是我用 Superpowers 之后最大的教训。6.3 一些能少走弯路的细节最后整理几个小技巧随时查看执行日志superpowers logs是你最好的朋友任何不确定性都先去翻日志。日志里会记录每一步的 prompt、工具调用、输出截断原因基本能回答 80% 的“为什么”。给 AI 设定“停手条件”在 instructions 里写清楚什么情况下它应该停下等待而不是自作主张。比如“当发现需要删除存量代码时先停下来汇报”。这会避免很多误操作。版本管理用独立分支凡是 Superpowers 跑的任务都先开一个新分支。就算它做出一堆改动你也能随时丢弃重来。我在 main 分支上跑过一次全自动重构后来回滚费了不少劲。自定义技能不要贪多技能越多加载越慢而且组合逻辑会越来越不可预测。我的经验是团队统一维护 3-5 个高质量核心技能比堆 20 个花架子技能稳定得多。用 Superpowers 这几个月我正在慢慢调整对 AI 编程工具的预期。以前总觉得“只要模型够聪明理论上什么都能干”现在更倾向于“把工具能力边界摸清楚再围绕它设计自己的工作流”。Superpowers 本身就是一个很好的例子它没有让模型变聪明但通过流程和技能让模型在复杂工程任务里变得更有用了。如果你正卡在“AI 生成代码能用但不好管”的阶段我建议你也花点时间从一个小任务开始试着把这套技能流跑通。跑通之后你可能就回不去那种一问一答的原始模式了。