最近在折腾 AI 编程工具的时候挖到了一个很有意思的开源项目名字就叫superpowers。初看还以为是某种超级英雄题材的娱乐仓库结果仔细翻了文档才发现它是一套专门给 Codex 这类命令行 AI 编程助手加“超能力”的工具集。简单说它把原本只能一问一答的编码 AI改造成了一个能记住项目上下文、能按技能流程干活、能自动拆分任务的“老员工”。我装上之后实测了一个周末今天这篇文章就把它的设计思路、安装配置、实战用法和踩过的坑一次讲清楚。这篇文章适合谁看如果你已经在用 Codex CLI、Claude Code 或 Cursor 这类工具但总觉得它们“每次都要重新说一遍需求”“干到一半就忘了背景”“只能写零碎代码没法完整干一个需求”那superpowers很可能就是你要的补丁。如果你还停留在“让 AI 帮我写个函数”的阶段这篇文章也能帮你打开思路AI 编程迟早要从“问答式”走向“任务式”而 superpowers 就是这条路上一个很值得参考的实现。1. 项目概述superpowers 到底给 AI 编程加了什么料1.1 一句话说清 superpowers 是什么把官方仓库和社区讨论里反复出现的描述综合一下可以这样给它下定义superpowers是一套面向命令行 AI 编码助手的技能与工作流增强框架。它不替代 Codex 本身而是以插件、配置、技能脚本的形式挂载在 AI 助手之上让 AI 在回答代码问题之外具备“按既定流程执行复杂开发任务”的能力。我自己的理解更直白一点普通模式下Codex 就像一个记忆力只有几轮对话的实习生你问一句它答一句上下文一长就开始胡说。而 superpowers 给它配了一本“工作手册”、一套“任务清单机制”和一个“项目背景记忆库”让它从临时工变成了能独立跟进一个需求、主动检查中间产物、遇到问题会回头修正的准正式员工。这个定位在它的项目结构里体现得很明显。整个仓库的核心不是一堆 API 封装而是大量按场景划分的“技能包”代码审查、重构、写测试、读文档、跑构建、修 bug每个技能包都定义了 AI 该先看什么、后做什么、输出什么格式的结果。这种设计思路本质上是把“老师傅的经验”沉淀成了结构化流程再让 AI 按流程执行。1.2 它解决的三个真实痛点我先说三个我在日常使用 AI 编程助手时最头疼的问题你会更容易理解 superpowers 为什么值得装第一上下文断裂。Codex 默认的记忆窗口虽然不小但实际干活的时候只要你让它多读几个文件、多改几轮代码它就开始搞混变量名和业务逻辑。更烦的是它不会主动记住你项目里哪些目录是生成的、哪些文件不能动、代码风格是什么样的每个新会话都要重新交代一遍。第二任务粒度失衡。你自己拆过需求就知道一个“给订单模块加导出功能”的需求可能要拆成看表结构、写查询、写导出逻辑、生成文件、加权限控制、写测试这么六步。但直接问 Codex它通常只会给你一个大而全的实现方案或者只做其中一小部分很少能按正确的顺序和依赖关系一步步执行完。第三结果无法验证。AI 写完代码它自己觉得没问题但有没有跑过测试、构建能不能通过、改动有没有破坏别的模块它是不管的。superpowers 里的大量技能和检查项就是冲着这个问题来的它逼着 AI 把“完成”定义为“通过检查”而不是“代码看起来像那么回事”。这三个痛点凑齐了其实就指向一个结论AI 编程工具缺的不是模型能力而是工程化外壳。superpowers 几乎把我能想到的外壳功能都做了包括技能注册、任务编排、上下文持久化、结果校验、多模型适配。这也是我愿意花一个周末去研究它的根本原因。1.3 项目适配的模型与工具链在具体讲安装和使用之前先把适配情况说清楚。从仓库 README 和社区反馈来看superpowers目前主要适配 OpenAI Codex CLI 这一系的工具链同时也支持通过配置方式接入其他支持 MCP 或 Skill 机制的编码助手。你不需要换掉正在用的 Codex它就是在 Codex 基础上叠加一层。如果你用的是 Claude Code也有社区成员提供了适配脚本但官方支持力度不如 Codex。我个人的建议是第一优先用 Codex CLI省心第二选择是你非常熟悉 Claude Code 的话也可以折腾但要做好遇到边界问题的准备。项目本身对操作系统没有太多限制macOS、Linux、Windows通过 WSL都能跑。依赖主要是 Node.js 环境和相应的 CLI 工具。安装方式很常规没有需要自己编译的 C 扩展所以对新手也友好。下面第 3 节我会给完整的安装和初始化流程。2. 核心能力拆解技能系统、上下文引擎与任务编排2.1 技能Skills系统把经验变成可复用资产superpowers 最核心的设计就是技能系统。所谓“技能”你可以理解为一个结构化的执行脚本它告诉 AI 在特定场景下应该按照什么顺序、调用什么命令、检查哪些条件、产出什么格式的结果。一个技能通常由三个部分组成说明文件、指令模板、校验清单。说明文件的作用是让 AI 判断“什么时候该用这个技能”。比如你告诉它“帮我校验一下今天写的订单模块”它会先扫描可用技能列表找到一个叫validate-code或类似名字的技能然后读取这个技能的说明确认匹配当前任务。这部分非常像工具函数里的路由逻辑先匹配意图再分发到具体处理函数。指令模板是技能的核心它在最大程度上消除了 AI 发挥的不确定性。它会给 AI 一个明确的“开工准备清单”和“执行步骤清单”比如第一步读取项目 README 和模块目录结构确认功能边界第二步找到最近的改动文件列出改动清单第三步逐个检查新增函数是否包含边界校验第四步执行测试命令并收集结果。有了这套模板AI 不会凭感觉自由发挥而是会像遵照 checklist 一样逐步执行。校验清单决定技能是否成功完成。它要求 AI 在结束任务前把所有校验项逐条过一遍测试是否通过、是否处理了空指针、是否更新了相关文档等。如果校验不通过AI 要回到对应的执行步骤重新处理而不是直接宣布完成。我把这三段式结构做成表格方便你对照理解组成部分解决的问题实际作用说明文件AI 该什么时候用这个技能提供触发条件、适用场景指令模板AI 按什么顺序干活提供执行步骤、命令、约束校验清单干到什么程度算完成提供验收标准形成闭环2.2 上下文引擎让 AI 真正记住你的项目如果说技能系统决定了 AI 干活的“套路”那上下文引擎决定的是 AI 的“记忆”。用过 Codex 的都知道每个新会话开始时它对你的项目一无所知每次都要从零开始读文件、猜目录结构、猜模块间的关系。superpowers 的上下文引擎就是来解决这个问题的。它会把项目的关键信息固化成一个项目档案主要包括项目技术栈说明、目录结构摘要、架构约定、代码风格规范、常用命令、禁止改动的文件清单、历史决策记录。这个档案可以理解为项目的“入职手册”AI 每次开新会话都会被要求先读它。项目档案的生成过程很直接superpowers 提供了一段脚手架逻辑扫描项目根目录的配置文件如 pom.xml、package.json、pyproject.toml识别技术栈读取 README 和文档提取业务描述分析目录结构生成模块地图结合用户补充的自定义规则生成初始档案。这套逻辑不追求一次做到完美而是先把骨架搭起来之后每次执行任务都会自动更新档案内容。在实际使用中这个机制带来的体验提升非常明显。我举个例子以前让 Codex 在 Spring Boot 项目里加一个新接口它经常问“你们的包名是什么”“Controller 放在哪个包下”虽然能答但效率低。而接入 superpowers 之后它第一次就跑对了包结构和命名风格因为项目档案里已经把“controller 放在com.example.controller下、统一返回ApiResult”这种约定写清楚了。上下文引擎还会维护一个会话内的“短时记忆”记录当前任务已经执行到哪一步、哪些检查已经通过、哪些文件已经改动过。这相当于给 AI 加了一份草稿纸任务只要没结束它就不会忘记前面的中间结果。2.3 任务编排与多模型适配任务编排是 superpowers 另一个让我看重的能力。它把一个大需求拆成多个技能节点按依赖关系串联形成一个任务流水线。比如“为新模块补全测试”这个任务会被拆成读取需求文档、分析现有代码结构、编写单元测试、运行测试并修复失败、更新测试覆盖率报告五个节点。每个节点都对应一个或多个技能节点之间可以传递中间产物。这种设计让 AI 可以在一个完整任务里自主穿梭而不是像普通对话那样永远在回答“当前这个问题”。我在实测中让它帮我重构一个工具类它真的会先写重构方案、再改代码、再跑测试、再根据测试失败结果回退修改最后给我一份改动摘要。整个过程里我只输入了一句话。多模型适配方面项目本身的架构对模型层做了抽象核心逻辑是“技能定义 工具调用 上下文本地化”不依赖某个模型的特定能力。也就是说即便今天 Codex 换了更强的模型版本或者你想切到别的助手技能包和项目档案这些资产依然可以复用。唯一要改的是适配层的调用方式。这里也给一个重要的选型提示如果你追求开箱即用那就选官方适配度最高的 Codex CLI如果你本身是 Claude Code 的重度用户可以先在沙盒项目里试跑一遍再看要不要切换。不要为了套一个工具把日常流程搞得过于复杂。3. 安装与配置从零开始跑起来3.1 环境准备与依赖安装正式开始动手之前先把环境准备好。你本机至少要有以下东西Node.js 18 及以上版本因为项目核心脚本依赖较新的 Node APICodex CLI 或兼容的 AI 编码命令行工具且已完成基本的登录与配置git用来拉取仓库和后续更新技能包一个真实的项目目录最好不要拿生产项目练手先用小项目验证。Node.js 版本这一条我单独强调一下因为我自己踩过坑。最初我的开发机上装的是 Node 16安装到一半就报语法错误翻了 issues 才知道项目要求最低 18。如果你懒得查版本直接跑node -v看一眼不是 18 以上就先升级。依赖装完之后建议顺手确认一下 Codex CLI 能不能正常对话。新建一个空目录随便让它写个 Hello World如果这一步都通不过后面装了 superpowers 也没法工作。这一步看起来多余但能帮你把“codex 本身的问题”和“superpowers 的问题”分开后续排查会省很多时间。3.2 安装 superpowers 并初始化环境正常之后安装过程其实不复杂。以 npm 方式为例在项目根目录执行安装命令然后运行初始化脚本。初始化脚本会做几件事拉取默认技能包、扫描当前项目生成初始档案、生成配置文件、把调用入口挂载到 Codex 的工具列表里。初始化完成之后你可以直接在当前目录启动 Codex然后输入一句测试指令比如“看看这个项目的结构告诉我它是什么技术栈”看它是否会优先读取项目档案。如果它回答里出现了你项目特有的目录名和技术栈信息说明初始化已经生效。如果初始化脚本报错不要急着卸载先看报错信息里提到哪一步失败。八成的情况是 Node 版本低、当前目录没有 git 初始化、或者 Codex 配置路径不对。这三个问题对应三种解法下表直接列出来报错关键词根本原因解决方式SyntaxError或Unexpected tokenNode 版本过低升级到 Node 18 后重试not a git repository项目未初始化 git先执行git initcodex not foundCodex CLI 不在 PATH重装 Codex 并添加环境变量3.3 关键配置项说明安装完不要急着上手先花几分钟把配置文件过一遍。superpowers 的配置文件通常是一个 JSON 或 YAML 格式的文件放在项目根目录的隐藏目录下。它控制着工具的核心行为改对了后面能省很多心。第一个值得关注的是技能包路径。默认情况下首次拉取的技能包缓存在全局目录里所有项目共用一套。如果你有多个项目但技术栈差异很大比如一个 Java 后端、一个 React 前端、一个 Node 脚本仓库建议给每个项目单独指定技能包路径。这样不会出现“前端项目加载了 Java 技能包”的浪费和干扰。第二个是项目档案的更新策略。默认策略是每次任务结束自动更新但如果你在一个非常稳定的基础项目里工作不想让 AI 频繁往档案里塞噪音可以把更新策略改成手动更新或者按需更新。项目档案太臃肿之后AI 读档本身就消耗不少时间这个很影响效率。第三个是输出详细度。调试阶段建议开到最详细AI 每一步干了什么、调用了哪个技能、校验结果是什么你都能看到。等流程稳定了再调低输出级别保持终端干净。这个习惯能帮你建立对工具的信任感因为它做的事情不再是黑盒。4. 实战用 superpowers 驱动 AI 完成一个 Java 任务4.1 场景设定与任务目标纸上谈兵没意思我拿一个真实的小项目场景来演示。假设我本地有个基于 Maven 的 Spring Boot 宠物商城项目有一个ProductController当前只能在内存里读写商品数据。我的目标是让 Codex 借助 superpowers给这个控制器增加一个“分页查询商品列表”的接口并且补上对应的单元测试。这个任务包含多个环节读现有控制器、读服务层代码、确认分页依赖是否已经引入、写新接口、写测试、跑测试、修失败用例。这不正是 2.3 节里讲的任务编排最擅长的场景吗而且用 Java 项目来演示正好回应了热词里大家一直在搜的superpowers java。在执行之前我需要先把项目档案初始化好。实测中我发现Java 项目的档案质量直接决定后续 AI 的表现。因为 Spring Boot 项目里“包结构”“Controller 规范”“统一返回体”这些东西如果档案里没有AI 很容易写出风格不一致的代码。4.2 编写技能定义与任务分解为了让 AI 按最合理的顺序干活我不直接甩给它一句“帮我加分页功能”而是先定义好任务编排。在 superpowers 的场景里任务定义文件长什么样可以很简单就是指定目标、涉及模块、验收标准剩下的执行拆分交给 AI 和技能包。我给这个任务写了一个类似这样的定义内容task_name: add_product_pagination goal: 为商品模块增加分页查询接口 GET /api/products?page1size10 entry: ProductController acceptance: - 接口参数包含 page 和 size并带默认值 - 返回体为 ApiResultPagedResultProduct - 有对应的单元测试测试覆盖正常分页和空列表两种情况 - mvn test 全部通过这段配置交给 Codex 之后它通过 superpowers 的技能编排逻辑会把任务拆成这样几步先读取ProductController和ProductService判断现有代码结构检查pom.xml是否已有 Spring Data 分页依赖如果没有补充依赖然后修改 Controller 和 Service最后补测试并运行mvn test。整个拆分和执行的链路这么顺核心原因就是技能系统把每一步的操作模式都框好了AI 不需要凭空思考“怎么写分页接口更合适”而是按照技能里沉淀下来的模板在走。4.3 执行过程与结果验证实际执行过程里有两个值得记录的细节。第一个是 AI 在检查依赖时发现pom.xml里没有引入spring-boot-starter-data-jpa的分页支持于是它主动先增加了依赖然后再开始改代码。这个过程放在我之前直接用 Codex 的流程里是很容易被跳过的但 superpowers 的校验清单会在“修改代码”之前强制检查“基础依赖是否就绪”。这个小环节帮我避免了一次编译失败。第二个是它写完测试之后第一次跑mvn test有两个用例失败。原因是我原来在ProductService里返回的是一个不可变 List它新增的分页逻辑试图对这个 List 做截断操作直接抛了UnsupportedOperationException。如果是一问一答的模式AI 到这里就已经“完成任务”了。但这次它的执行循环里包含“测试失败则回退修改”的节点AI 读到失败结果后回去把 Service 实现改成使用可变列表再重新跑测试直到全部通过。最终代码改动摘要列出来大概是这样的pom.xml新增分页相关依赖ProductController新增/api/products接口参数带默认值ProductService新增分页查询逻辑返回PageProduct的适配结构ProductControllerTest新增两个测试用例项目档案记录“商品模块已支持分页查询”。这整个过程中我实际手动输入的内容不超过五句话。我观察到的关键点是superpowers 并不是让 AI 更“聪明”而是让 AI 更“靠谱”。它通过流程约束和验证闭环把 AI 的完成度从一个模糊的概念变成了一个可验收的状态。5. 常见问题与排查实录5.1 技能不生效或加载失败很多人在群里反馈“装完之后 AI 还是老样子根本不按技能走”这个问题我一开始也遇到过而且排查了很久。绝大多数情况是技能包路径配置不对AI 找不到技能包里的技能定义自然就只能退回默认对话模式。排查建议按这个顺序来执行命令查看当前加载的技能列表确认技能包是否已加载检查配置里技能包路径是否指向了真实存在的目录确认该项目是否被 superpowers 识别项目档案是否存在手动触发一个特定技能比如要求 AI “使用 validate-code 技能检查当前代码”看它是否响应。其中前两步几乎能解决八成的问题。特别是刚安装完就换过项目目录的技能包路径很容易失效因为默认路径是写在安装时的全局配置里的。5.2 项目档案过时导致 AI 用旧规则写代码项目档案的机制很好用但也有副作用。我踩过的一个坑是某个模块的重构已经完成了但档案里还保留着旧的技术描述结果 AI 按旧描述写代码白白浪费了一轮修改。解决办法有两个方向。一是严格按照 3.3 节说的把档案更新策略从“自动更新”改成“按需更新”大重构之后手动触发一次档案重建。二是定期审查档案内容把已经过时的架构决策删掉或者手动修正。我个人的习惯是每完成一个较大的改动就顺手清理一次档案里的相关段落。因为这个坑我现在对项目档案的定位就是它是一份活文档不是一次性生成的静态说明。必须花一点心思去维护AI 才能长期稳定发挥。5.3 长任务中断与恢复AI 执行长任务时偶尔会因为终端断连、网络波动或者模型输出超时导致任务中断。superpowers 好在会尽量把中间状态落盘所以中断后可以通过恢复机制接着跑而不是从头再来。但恢复机制有个前提你不要清空中间日志。它主要依赖上下文引擎保存的短时记忆和项目档案里的任务执行记录来判断“哪些步骤已经完成”。如果你手贱把中间数据清理了恢复时它就只能重新开始。这里给一个经验建议跑长任务前先把终端会话留好不要开着太多占用资源的程序如果任务超过几分钟建议定期看一眼日志确认 AI 没有陷在某个循环里。AI 工具不是完全自动驾驶适当干预能避免它把时间浪费在无谓的重试上。6. 个人使用心得与几个值得一试的场景6.1 技能包维护从小而专开始对 superpowers 这类工具来说技能包是你的核心资产。默认技能包提供的是通用流程但真正好用的技能往往是根据你自己项目定制的。我的建议是不要一开始就写抽象的大技能而是抓住一个具体、重复、有标准答案的活儿来练手。比如“检查所有 Controller 是否统一返回ApiResult”就是一个非常适合固化成技能的任务。它有明确的检查对象、检查规则和合格标准AI 完全可以每天帮你扫一遍。等这类小技能积累多了再慢慢把它们组合成更大的任务流程整个开发过程的自动化程度就会有质的提升。6.2 与现有开发流程结合的思路用 superpowers 不一定非要让它直接改代码。我现在更常用的场景是让它做“预检”和“复盘”提交代码之前让 AI 跑一遍代码审查技能检查边界条件和异常处理发版之后让 AI 根据 git log 生成变更摘要自动更新项目档案中的模块状态。这种做法的好处是风险低、收益稳定。即便 AI 偶尔漏检了某个点也不会直接破坏线上代码。它更像是给团队加了一个自动化程度很高的代码 review 助理。我身边已经有好几个同事开始尝试这种方式普遍反馈“至少能把重复性检查从人肉流程里解放出来”。6.3 下一步扩展方向如果你已经把基础功能用顺了下一步可以向两个方向发展。一个方向是把 MCP 服务接进来让 AI 能访问数据库、调用接口做更深的验证另一个方向是结合 CI/CD把技能校验做成代码提交前的强制门禁。我目前正在折腾的是第一个方向因为只靠本地文件扫描AI 对运行时状态的感知还是太弱。如果能在测试环境里真正调用一下新写的接口验证返回数据对不对那任务闭环的可靠性会再上一个台阶。这个方向踩出结果之后我再单独写一篇实操记录聊聊细节。最后说点实在的用 superpowers 这一个多星期我对 AI 编程工具的信心提升了不少。它没有改变模型的智能程度但把“让 AI 真正干完一个活”这件事从碰运气变成了走流程。哪怕你今天只是装来玩玩我也建议你好好研究一下项目档案和技能机制这两个概念对你日常使用任何 AI 编码工具都有启发给 AI 立规则、给任务定终点它才能从“会说话的编译器”变成“能交付的同事”。 
长河君 · 2026/11/4 21:55:42 · 阅读 1.2k superpowers：给 Codex CLI 装上技能系统与任务编排的 AI 编程超能力
最近在折腾 AI 编程工具的时候挖到了一个很有意思的开源项目名字就叫superpowers。初看还以为是某种超级英雄题材的娱乐仓库结果仔细翻了文档才发现它是一套专门给 Codex 这类命令行 AI 编程助手加“超能力”的工具集。简单说它把原本只能一问一答的编码 AI改造成了一个能记住项目上下文、能按技能流程干活、能自动拆分任务的“老员工”。我装上之后实测了一个周末今天这篇文章就把它的设计思路、安装配置、实战用法和踩过的坑一次讲清楚。这篇文章适合谁看如果你已经在用 Codex CLI、Claude Code 或 Cursor 这类工具但总觉得它们“每次都要重新说一遍需求”“干到一半就忘了背景”“只能写零碎代码没法完整干一个需求”那superpowers很可能就是你要的补丁。如果你还停留在“让 AI 帮我写个函数”的阶段这篇文章也能帮你打开思路AI 编程迟早要从“问答式”走向“任务式”而 superpowers 就是这条路上一个很值得参考的实现。1. 项目概述superpowers 到底给 AI 编程加了什么料1.1 一句话说清 superpowers 是什么把官方仓库和社区讨论里反复出现的描述综合一下可以这样给它下定义superpowers是一套面向命令行 AI 编码助手的技能与工作流增强框架。它不替代 Codex 本身而是以插件、配置、技能脚本的形式挂载在 AI 助手之上让 AI 在回答代码问题之外具备“按既定流程执行复杂开发任务”的能力。我自己的理解更直白一点普通模式下Codex 就像一个记忆力只有几轮对话的实习生你问一句它答一句上下文一长就开始胡说。而 superpowers 给它配了一本“工作手册”、一套“任务清单机制”和一个“项目背景记忆库”让它从临时工变成了能独立跟进一个需求、主动检查中间产物、遇到问题会回头修正的准正式员工。这个定位在它的项目结构里体现得很明显。整个仓库的核心不是一堆 API 封装而是大量按场景划分的“技能包”代码审查、重构、写测试、读文档、跑构建、修 bug每个技能包都定义了 AI 该先看什么、后做什么、输出什么格式的结果。这种设计思路本质上是把“老师傅的经验”沉淀成了结构化流程再让 AI 按流程执行。1.2 它解决的三个真实痛点我先说三个我在日常使用 AI 编程助手时最头疼的问题你会更容易理解 superpowers 为什么值得装第一上下文断裂。Codex 默认的记忆窗口虽然不小但实际干活的时候只要你让它多读几个文件、多改几轮代码它就开始搞混变量名和业务逻辑。更烦的是它不会主动记住你项目里哪些目录是生成的、哪些文件不能动、代码风格是什么样的每个新会话都要重新交代一遍。第二任务粒度失衡。你自己拆过需求就知道一个“给订单模块加导出功能”的需求可能要拆成看表结构、写查询、写导出逻辑、生成文件、加权限控制、写测试这么六步。但直接问 Codex它通常只会给你一个大而全的实现方案或者只做其中一小部分很少能按正确的顺序和依赖关系一步步执行完。第三结果无法验证。AI 写完代码它自己觉得没问题但有没有跑过测试、构建能不能通过、改动有没有破坏别的模块它是不管的。superpowers 里的大量技能和检查项就是冲着这个问题来的它逼着 AI 把“完成”定义为“通过检查”而不是“代码看起来像那么回事”。这三个痛点凑齐了其实就指向一个结论AI 编程工具缺的不是模型能力而是工程化外壳。superpowers 几乎把我能想到的外壳功能都做了包括技能注册、任务编排、上下文持久化、结果校验、多模型适配。这也是我愿意花一个周末去研究它的根本原因。1.3 项目适配的模型与工具链在具体讲安装和使用之前先把适配情况说清楚。从仓库 README 和社区反馈来看superpowers目前主要适配 OpenAI Codex CLI 这一系的工具链同时也支持通过配置方式接入其他支持 MCP 或 Skill 机制的编码助手。你不需要换掉正在用的 Codex它就是在 Codex 基础上叠加一层。如果你用的是 Claude Code也有社区成员提供了适配脚本但官方支持力度不如 Codex。我个人的建议是第一优先用 Codex CLI省心第二选择是你非常熟悉 Claude Code 的话也可以折腾但要做好遇到边界问题的准备。项目本身对操作系统没有太多限制macOS、Linux、Windows通过 WSL都能跑。依赖主要是 Node.js 环境和相应的 CLI 工具。安装方式很常规没有需要自己编译的 C 扩展所以对新手也友好。下面第 3 节我会给完整的安装和初始化流程。2. 核心能力拆解技能系统、上下文引擎与任务编排2.1 技能Skills系统把经验变成可复用资产superpowers 最核心的设计就是技能系统。所谓“技能”你可以理解为一个结构化的执行脚本它告诉 AI 在特定场景下应该按照什么顺序、调用什么命令、检查哪些条件、产出什么格式的结果。一个技能通常由三个部分组成说明文件、指令模板、校验清单。说明文件的作用是让 AI 判断“什么时候该用这个技能”。比如你告诉它“帮我校验一下今天写的订单模块”它会先扫描可用技能列表找到一个叫validate-code或类似名字的技能然后读取这个技能的说明确认匹配当前任务。这部分非常像工具函数里的路由逻辑先匹配意图再分发到具体处理函数。指令模板是技能的核心它在最大程度上消除了 AI 发挥的不确定性。它会给 AI 一个明确的“开工准备清单”和“执行步骤清单”比如第一步读取项目 README 和模块目录结构确认功能边界第二步找到最近的改动文件列出改动清单第三步逐个检查新增函数是否包含边界校验第四步执行测试命令并收集结果。有了这套模板AI 不会凭感觉自由发挥而是会像遵照 checklist 一样逐步执行。校验清单决定技能是否成功完成。它要求 AI 在结束任务前把所有校验项逐条过一遍测试是否通过、是否处理了空指针、是否更新了相关文档等。如果校验不通过AI 要回到对应的执行步骤重新处理而不是直接宣布完成。我把这三段式结构做成表格方便你对照理解组成部分解决的问题实际作用说明文件AI 该什么时候用这个技能提供触发条件、适用场景指令模板AI 按什么顺序干活提供执行步骤、命令、约束校验清单干到什么程度算完成提供验收标准形成闭环2.2 上下文引擎让 AI 真正记住你的项目如果说技能系统决定了 AI 干活的“套路”那上下文引擎决定的是 AI 的“记忆”。用过 Codex 的都知道每个新会话开始时它对你的项目一无所知每次都要从零开始读文件、猜目录结构、猜模块间的关系。superpowers 的上下文引擎就是来解决这个问题的。它会把项目的关键信息固化成一个项目档案主要包括项目技术栈说明、目录结构摘要、架构约定、代码风格规范、常用命令、禁止改动的文件清单、历史决策记录。这个档案可以理解为项目的“入职手册”AI 每次开新会话都会被要求先读它。项目档案的生成过程很直接superpowers 提供了一段脚手架逻辑扫描项目根目录的配置文件如 pom.xml、package.json、pyproject.toml识别技术栈读取 README 和文档提取业务描述分析目录结构生成模块地图结合用户补充的自定义规则生成初始档案。这套逻辑不追求一次做到完美而是先把骨架搭起来之后每次执行任务都会自动更新档案内容。在实际使用中这个机制带来的体验提升非常明显。我举个例子以前让 Codex 在 Spring Boot 项目里加一个新接口它经常问“你们的包名是什么”“Controller 放在哪个包下”虽然能答但效率低。而接入 superpowers 之后它第一次就跑对了包结构和命名风格因为项目档案里已经把“controller 放在com.example.controller下、统一返回ApiResult”这种约定写清楚了。上下文引擎还会维护一个会话内的“短时记忆”记录当前任务已经执行到哪一步、哪些检查已经通过、哪些文件已经改动过。这相当于给 AI 加了一份草稿纸任务只要没结束它就不会忘记前面的中间结果。2.3 任务编排与多模型适配任务编排是 superpowers 另一个让我看重的能力。它把一个大需求拆成多个技能节点按依赖关系串联形成一个任务流水线。比如“为新模块补全测试”这个任务会被拆成读取需求文档、分析现有代码结构、编写单元测试、运行测试并修复失败、更新测试覆盖率报告五个节点。每个节点都对应一个或多个技能节点之间可以传递中间产物。这种设计让 AI 可以在一个完整任务里自主穿梭而不是像普通对话那样永远在回答“当前这个问题”。我在实测中让它帮我重构一个工具类它真的会先写重构方案、再改代码、再跑测试、再根据测试失败结果回退修改最后给我一份改动摘要。整个过程里我只输入了一句话。多模型适配方面项目本身的架构对模型层做了抽象核心逻辑是“技能定义 工具调用 上下文本地化”不依赖某个模型的特定能力。也就是说即便今天 Codex 换了更强的模型版本或者你想切到别的助手技能包和项目档案这些资产依然可以复用。唯一要改的是适配层的调用方式。这里也给一个重要的选型提示如果你追求开箱即用那就选官方适配度最高的 Codex CLI如果你本身是 Claude Code 的重度用户可以先在沙盒项目里试跑一遍再看要不要切换。不要为了套一个工具把日常流程搞得过于复杂。3. 安装与配置从零开始跑起来3.1 环境准备与依赖安装正式开始动手之前先把环境准备好。你本机至少要有以下东西Node.js 18 及以上版本因为项目核心脚本依赖较新的 Node APICodex CLI 或兼容的 AI 编码命令行工具且已完成基本的登录与配置git用来拉取仓库和后续更新技能包一个真实的项目目录最好不要拿生产项目练手先用小项目验证。Node.js 版本这一条我单独强调一下因为我自己踩过坑。最初我的开发机上装的是 Node 16安装到一半就报语法错误翻了 issues 才知道项目要求最低 18。如果你懒得查版本直接跑node -v看一眼不是 18 以上就先升级。依赖装完之后建议顺手确认一下 Codex CLI 能不能正常对话。新建一个空目录随便让它写个 Hello World如果这一步都通不过后面装了 superpowers 也没法工作。这一步看起来多余但能帮你把“codex 本身的问题”和“superpowers 的问题”分开后续排查会省很多时间。3.2 安装 superpowers 并初始化环境正常之后安装过程其实不复杂。以 npm 方式为例在项目根目录执行安装命令然后运行初始化脚本。初始化脚本会做几件事拉取默认技能包、扫描当前项目生成初始档案、生成配置文件、把调用入口挂载到 Codex 的工具列表里。初始化完成之后你可以直接在当前目录启动 Codex然后输入一句测试指令比如“看看这个项目的结构告诉我它是什么技术栈”看它是否会优先读取项目档案。如果它回答里出现了你项目特有的目录名和技术栈信息说明初始化已经生效。如果初始化脚本报错不要急着卸载先看报错信息里提到哪一步失败。八成的情况是 Node 版本低、当前目录没有 git 初始化、或者 Codex 配置路径不对。这三个问题对应三种解法下表直接列出来报错关键词根本原因解决方式SyntaxError或Unexpected tokenNode 版本过低升级到 Node 18 后重试not a git repository项目未初始化 git先执行git initcodex not foundCodex CLI 不在 PATH重装 Codex 并添加环境变量3.3 关键配置项说明安装完不要急着上手先花几分钟把配置文件过一遍。superpowers 的配置文件通常是一个 JSON 或 YAML 格式的文件放在项目根目录的隐藏目录下。它控制着工具的核心行为改对了后面能省很多心。第一个值得关注的是技能包路径。默认情况下首次拉取的技能包缓存在全局目录里所有项目共用一套。如果你有多个项目但技术栈差异很大比如一个 Java 后端、一个 React 前端、一个 Node 脚本仓库建议给每个项目单独指定技能包路径。这样不会出现“前端项目加载了 Java 技能包”的浪费和干扰。第二个是项目档案的更新策略。默认策略是每次任务结束自动更新但如果你在一个非常稳定的基础项目里工作不想让 AI 频繁往档案里塞噪音可以把更新策略改成手动更新或者按需更新。项目档案太臃肿之后AI 读档本身就消耗不少时间这个很影响效率。第三个是输出详细度。调试阶段建议开到最详细AI 每一步干了什么、调用了哪个技能、校验结果是什么你都能看到。等流程稳定了再调低输出级别保持终端干净。这个习惯能帮你建立对工具的信任感因为它做的事情不再是黑盒。4. 实战用 superpowers 驱动 AI 完成一个 Java 任务4.1 场景设定与任务目标纸上谈兵没意思我拿一个真实的小项目场景来演示。假设我本地有个基于 Maven 的 Spring Boot 宠物商城项目有一个ProductController当前只能在内存里读写商品数据。我的目标是让 Codex 借助 superpowers给这个控制器增加一个“分页查询商品列表”的接口并且补上对应的单元测试。这个任务包含多个环节读现有控制器、读服务层代码、确认分页依赖是否已经引入、写新接口、写测试、跑测试、修失败用例。这不正是 2.3 节里讲的任务编排最擅长的场景吗而且用 Java 项目来演示正好回应了热词里大家一直在搜的superpowers java。在执行之前我需要先把项目档案初始化好。实测中我发现Java 项目的档案质量直接决定后续 AI 的表现。因为 Spring Boot 项目里“包结构”“Controller 规范”“统一返回体”这些东西如果档案里没有AI 很容易写出风格不一致的代码。4.2 编写技能定义与任务分解为了让 AI 按最合理的顺序干活我不直接甩给它一句“帮我加分页功能”而是先定义好任务编排。在 superpowers 的场景里任务定义文件长什么样可以很简单就是指定目标、涉及模块、验收标准剩下的执行拆分交给 AI 和技能包。我给这个任务写了一个类似这样的定义内容task_name: add_product_pagination goal: 为商品模块增加分页查询接口 GET /api/products?page1size10 entry: ProductController acceptance: - 接口参数包含 page 和 size并带默认值 - 返回体为 ApiResultPagedResultProduct - 有对应的单元测试测试覆盖正常分页和空列表两种情况 - mvn test 全部通过这段配置交给 Codex 之后它通过 superpowers 的技能编排逻辑会把任务拆成这样几步先读取ProductController和ProductService判断现有代码结构检查pom.xml是否已有 Spring Data 分页依赖如果没有补充依赖然后修改 Controller 和 Service最后补测试并运行mvn test。整个拆分和执行的链路这么顺核心原因就是技能系统把每一步的操作模式都框好了AI 不需要凭空思考“怎么写分页接口更合适”而是按照技能里沉淀下来的模板在走。4.3 执行过程与结果验证实际执行过程里有两个值得记录的细节。第一个是 AI 在检查依赖时发现pom.xml里没有引入spring-boot-starter-data-jpa的分页支持于是它主动先增加了依赖然后再开始改代码。这个过程放在我之前直接用 Codex 的流程里是很容易被跳过的但 superpowers 的校验清单会在“修改代码”之前强制检查“基础依赖是否就绪”。这个小环节帮我避免了一次编译失败。第二个是它写完测试之后第一次跑mvn test有两个用例失败。原因是我原来在ProductService里返回的是一个不可变 List它新增的分页逻辑试图对这个 List 做截断操作直接抛了UnsupportedOperationException。如果是一问一答的模式AI 到这里就已经“完成任务”了。但这次它的执行循环里包含“测试失败则回退修改”的节点AI 读到失败结果后回去把 Service 实现改成使用可变列表再重新跑测试直到全部通过。最终代码改动摘要列出来大概是这样的pom.xml新增分页相关依赖ProductController新增/api/products接口参数带默认值ProductService新增分页查询逻辑返回PageProduct的适配结构ProductControllerTest新增两个测试用例项目档案记录“商品模块已支持分页查询”。这整个过程中我实际手动输入的内容不超过五句话。我观察到的关键点是superpowers 并不是让 AI 更“聪明”而是让 AI 更“靠谱”。它通过流程约束和验证闭环把 AI 的完成度从一个模糊的概念变成了一个可验收的状态。5. 常见问题与排查实录5.1 技能不生效或加载失败很多人在群里反馈“装完之后 AI 还是老样子根本不按技能走”这个问题我一开始也遇到过而且排查了很久。绝大多数情况是技能包路径配置不对AI 找不到技能包里的技能定义自然就只能退回默认对话模式。排查建议按这个顺序来执行命令查看当前加载的技能列表确认技能包是否已加载检查配置里技能包路径是否指向了真实存在的目录确认该项目是否被 superpowers 识别项目档案是否存在手动触发一个特定技能比如要求 AI “使用 validate-code 技能检查当前代码”看它是否响应。其中前两步几乎能解决八成的问题。特别是刚安装完就换过项目目录的技能包路径很容易失效因为默认路径是写在安装时的全局配置里的。5.2 项目档案过时导致 AI 用旧规则写代码项目档案的机制很好用但也有副作用。我踩过的一个坑是某个模块的重构已经完成了但档案里还保留着旧的技术描述结果 AI 按旧描述写代码白白浪费了一轮修改。解决办法有两个方向。一是严格按照 3.3 节说的把档案更新策略从“自动更新”改成“按需更新”大重构之后手动触发一次档案重建。二是定期审查档案内容把已经过时的架构决策删掉或者手动修正。我个人的习惯是每完成一个较大的改动就顺手清理一次档案里的相关段落。因为这个坑我现在对项目档案的定位就是它是一份活文档不是一次性生成的静态说明。必须花一点心思去维护AI 才能长期稳定发挥。5.3 长任务中断与恢复AI 执行长任务时偶尔会因为终端断连、网络波动或者模型输出超时导致任务中断。superpowers 好在会尽量把中间状态落盘所以中断后可以通过恢复机制接着跑而不是从头再来。但恢复机制有个前提你不要清空中间日志。它主要依赖上下文引擎保存的短时记忆和项目档案里的任务执行记录来判断“哪些步骤已经完成”。如果你手贱把中间数据清理了恢复时它就只能重新开始。这里给一个经验建议跑长任务前先把终端会话留好不要开着太多占用资源的程序如果任务超过几分钟建议定期看一眼日志确认 AI 没有陷在某个循环里。AI 工具不是完全自动驾驶适当干预能避免它把时间浪费在无谓的重试上。6. 个人使用心得与几个值得一试的场景6.1 技能包维护从小而专开始对 superpowers 这类工具来说技能包是你的核心资产。默认技能包提供的是通用流程但真正好用的技能往往是根据你自己项目定制的。我的建议是不要一开始就写抽象的大技能而是抓住一个具体、重复、有标准答案的活儿来练手。比如“检查所有 Controller 是否统一返回ApiResult”就是一个非常适合固化成技能的任务。它有明确的检查对象、检查规则和合格标准AI 完全可以每天帮你扫一遍。等这类小技能积累多了再慢慢把它们组合成更大的任务流程整个开发过程的自动化程度就会有质的提升。6.2 与现有开发流程结合的思路用 superpowers 不一定非要让它直接改代码。我现在更常用的场景是让它做“预检”和“复盘”提交代码之前让 AI 跑一遍代码审查技能检查边界条件和异常处理发版之后让 AI 根据 git log 生成变更摘要自动更新项目档案中的模块状态。这种做法的好处是风险低、收益稳定。即便 AI 偶尔漏检了某个点也不会直接破坏线上代码。它更像是给团队加了一个自动化程度很高的代码 review 助理。我身边已经有好几个同事开始尝试这种方式普遍反馈“至少能把重复性检查从人肉流程里解放出来”。6.3 下一步扩展方向如果你已经把基础功能用顺了下一步可以向两个方向发展。一个方向是把 MCP 服务接进来让 AI 能访问数据库、调用接口做更深的验证另一个方向是结合 CI/CD把技能校验做成代码提交前的强制门禁。我目前正在折腾的是第一个方向因为只靠本地文件扫描AI 对运行时状态的感知还是太弱。如果能在测试环境里真正调用一下新写的接口验证返回数据对不对那任务闭环的可靠性会再上一个台阶。这个方向踩出结果之后我再单独写一篇实操记录聊聊细节。最后说点实在的用 superpowers 这一个多星期我对 AI 编程工具的信心提升了不少。它没有改变模型的智能程度但把“让 AI 真正干完一个活”这件事从碰运气变成了走流程。哪怕你今天只是装来玩玩我也建议你好好研究一下项目档案和技能机制这两个概念对你日常使用任何 AI 编码工具都有启发给 AI 立规则、给任务定终点它才能从“会说话的编译器”变成“能交付的同事”。