superpowers实战：为Codex CLI构建可控的授权与知识体系

以前用Codex CLI干活的时候我总觉得它像个聪明但手很欠的实习生——脑子确实灵光但一上来就改文件、跑命令、往pom.xml里塞依赖拦都拦不住。后来发现社区里有人在整superpowers这类增强工具专门治这个毛病。说白了superpowers是套在Codex CLI外面的一层包装器核心思路是把AI的超能力收进一个可控的流程里默认只读动手前先申请授权你点了头它才继续。这篇东西不是简单翻译README而是把我从安装、配置、授权管理到在Java项目里实战的完整过程过一遍。适合正在用Codex或其他AI编程CLI又觉得原生的放养式协作不够稳的朋友。1. superpowers到底是什么给AI助手装上可控的双手1.1 从一次日常开发会话说起我接手过一个老旧的Java服务代码库大概二十多万行。第一次把Codex放到那个仓库里它上来就准备写代码。我跟它说先别动帮我把模块依赖关系理一遍。它确实干得不错但给出的结论里混着一堆猜的成分而且它默认的交互方式根本拦不住它下一步的冲动——那种感觉就像你在驾驶座上副驾却时不时伸脚来踩油门。后来我换成superpowers启动会话本质上还是那个Codex但交互方式变了所有AI打算执行的操作先变成一个个带编号的请求你在终端里逐个放行。第一次跑起来我让AI以只读模式看完整个项目结构确认无误后才授权它打开pom.xml和源码改。整个过程我都有参与感它不再是那个乱来一气的实习生更像一个会提前跟你对方案的同事。这个项目在GitHub上不算难找搜superpowers就能看到。它能做的比原生Codex多不少包括文件读写、命令行执行、知识沉淀甚至AI还能自己维护一套能力文档来扩展自己。对日常开发来说最直接的收益就是你不再需要事后去review那些AI自作主张的改动因为它在动手之前就跟你把每一步对齐了。1.2 核心设计思路授权模式与能力插件化superpowers不是重写一个模型它重新定义了AI与终端的权限边界。它通过包装AI的指令请求把读取文件写文件跑命令这些原始动作拆成可授权的单元。默认级别是只读AI可以在代码库里随便看但想落笔就得向你申请口令。这背后借鉴的是真实团队里的代码评审流程AI是提议者你是审批者。另一个设计是能力插件化。阅读、搜索、执行shell、知识沉淀这些操作都抽象成一个个power以Markdown文档的形式定义AI在需要时会主动申请调用某个power。你甚至可以新建一个Markdown文档告诉AI下次遇到这类任务就去调用这个能力。开始我还担心它会不会理解不了实测下来只要文档写得足够明确它能自己照着执行甚至还会反过来问我补充细节。这种能力用文档驱动而不是写死在代码里的思路最大的好处是扩展成本极低。你不需要改一行代码就能教会AI一个新技能。我在Java项目里常用的分析Maven依赖冲突运行指定测试类这些能力都是后来自己补的AI照样用得顺。1.3 为什么我现在更推荐wrapper类工具有不少人问原生Codex不是也有approval mode吗为什么还要套一层superpowers我的回答是原生approval mode管的是确认之后执行但它没有把AI的思考过程、工具调用意图和你的决策流程串起来。superpowers把这层做成了类似驾驶舱的东西——你能看到AI打算发起哪些操作、每个操作会改什么、为什么要改然后再决定放不放行。对于团队场景这更关键。以前让AI直接动代码出了问题很难追溯到底它改了什么、为什么改。现在每个改动都有申请记录相当于天然的变更日志。我甚至会在Session结束后把对话记录存下来出问题时直接把记录丢给同事看。这种可追溯性是原生CLI很难给你的。2. superpowers安装与首次启动全流程2.1 前置条件Codex CLI与运行环境先明确一件事superpowers本身不包含AI模型它只是导演和调度器真正干活的是底层的Codex CLI。所以你得先把Codex装好并且保证它在你终端的PATH里。检查方式很简单打开终端依次跑三条命令codex --version python3 --version git --version我建议Python版本不低于3.10因为一些能力文档的解析和会话管理功能依赖相对较新的语法和标准库。Git则是用来克隆项目源码的不装的话后面操作会卡住。如果你本机恰好是Windows尽量在Git Bash或者Windows Terminal里操作避免PowerShell的路径解析问题。这里有个很容易踩的坑很多人装好了Codex但codex命令是在某个虚拟环境或者npm全局目录里superpowers启动时找不到它会直接报错退出。所以装superpowers之前先确认which codex有输出。如果你是通过npm全局安装的Codex通常不会有大问题如果是用某个包管理器装的可能得手动把路径加进PATH。2.2 安装superpowers我推荐从源码安装官方的安装方式在项目README里写得很清楚我习惯从源码装因为能直接看到它是怎么调用codex的出问题时方便排查。步骤如下git clone https://github.com/jlowin/superpowers.git cd superpowers pip install -e .pip install -e .的意思是可编辑安装相当于在本地以开发模式把这个包挂到Python环境里。好处是以后你拉取最新代码不用重新安装就能生效对经常跟进更新的人来说很省事。装完后验证一下superpowers --help如果看到帮助信息说明安装成功。如果提示command not found多半是Python脚本目录不在PATH里后面第5章里我会专门讲排查方法。需要连云的时候直接运行superpowers就行它会自动去调用你本机的Codex CLI。注意不要同时开原生codex和superpowers操作同一个目录两个会话同时改文件容易冲突。2.3 首次启动与基础配置首次运行superpowers交互式向导会问你要工作目录和默认授权级别。工作目录建议直接指向你项目的根目录AI会以这个目录为基准来读文件、跑命令。授权级别第一次先选只读最稳让AI先把这个项目结构盘清楚后续需要改代码时再切换。配置会写在一个以.superpowers开头的目录里具体路径各版本略有差异一般在你的用户主目录下比如~/.superpowers/。里面主要有一份配置文件和一个存放能力文档的文件夹。你可以手动编辑配置文件里的默认授权级别、模型名称、会话保存开关等字段。我建议把会话日志打开默认保存到项目本地目录这样每次AI做了什么都有据可查。首次配置完成后可以试试让AI做一个纯阅读任务比如请读取当前目录下的README.md并总结项目结构。看到它以只读模式完成后不自动动手说明整个链路已经通了。3. 核心功能拆解授权模式、能力与知识沉淀3.1 授权模式把手滑变成过问授权模式是superpowers最核心的机制直接把AI的工作流拆成提议—审批—执行三段。不同版本的模式命名可能不太一样但核心就三种我整理成表格方便对照模式行为适用场景只读AI只能读文件、搜索、分析不能写入或执行命令刚进新仓库、需求澄清、代码审查建议/按请求AI可以提出写入和执行请求由用户逐个放行日常开发、修改业务代码、重构直接/全自动在用户限定的范围内直接执行命令和写入不逐条确认跑测试、批量重命名、格式化等机械操作我自己的使用习惯是刚进一个陌生仓库用只读让AI先把模块结构、构建方式、测试命令摸清楚理解完之后切到建议模式改代码、加依赖都走审批只有跑测试和批量整理这种确定性高的操作才临时切到直接模式。切换授权级别不需要重启会话直接在输入框里敲快捷指令就行代价很低。有一种情况要特别小心在直接模式下AI连续执行一串命令时如果某个命令超出了你预期的范围它是不会停下来问你的。所以我把直接模式的使用范围控制在单一命令上比如只允许运行mvn test和./mvnw test而不是放开运行任意命令的权限。这种细粒度的控制恰恰是superpowers比原生CLI舒服的地方。3.2 能力体系让AI真的能干活superpowers把AI能调用的工具抽象成一个个power。每个power就是一份Markdown文档里面有触发条件、执行步骤和注意事项。AI在会话里遇到对应场景时会主动申请调用。常见的预置能力大致有读取文件、查找文件、全文搜索、执行终端命令、写入文件、保存/加载知识等。为了让AI不乱用能力它会先向你描述打算调用哪个能力、目的是什么。你在终端里看到类似申请调用run_command能力执行./mvnw compile的提示就可以决定放行还是拒绝。这一步跟授权模式是配合在一起的能力是怎么干授权是能不能干两者分开管理逻辑很清晰。我之前给一个Java项目写过一份分析Maven依赖冲突的能力文档内容大致是这样的# power: 分析Maven依赖冲突 description: 当Java项目出现依赖冲突时使用本能力定位问题并给出解决方案 trigger: 用户要求排查依赖冲突、mvn dependency:tree 报错 steps: 1. 读取根目录 pom.xml列出全部直接依赖 2. 运行 mvn dependency:tree 获取实际依赖树 3. 找出同一 groupId/artifactId 下的多个版本 4. 给出排除(exclusion)或升级建议 5. 在输出结论前先征求用户确认是否修改 pom.xml notes: - 业务代码模块多时优先分析目标模块自身的 pom.xml - 不要在没有用户确认的情况下直接改版本号这份文档放到能力目录后第二次会话里我提了一句看看依赖冲突AI自己就读了这份Markdown按照里面的步骤执行了。它不是死记硬背地生搬步骤而是在做完第三步后真的把冲突列表列出来问我要不要修。这种用文档教会AI新技能的方式比改代码、写插件要轻得多也是我特别喜欢这个工具的原因之一。3.3 知识沉淀让AI记住这个项目的规矩知识沉淀是superpowers另一个让我觉得真香的功能。AI会话默认是没记忆的今天聊的明天就忘。但superpowers允许AI把项目的关键信息写入知识库下次会话再启动时AI会先读取知识库相当于给AI装了一份项目简报。我在第一次分析某个项目构建流程时会明确告诉AI请把以下内容保存到知识库项目使用Maven管理依赖测试命令是mvn test代码风格是Google Java Format模块说明见docs/modules.md。之后每次会话AI开场就会自动去读知识库不会再犯用Gradle命令跑Maven项目的低级错误。实际操作里我更喜欢主动引导AI沉淀信息。比如让它读完单元测试的组织方式后加一句把测试目录结构和命名约定写入知识库。这样过几天再开新会话AI直接就能说出测试怎么跑而不需要重新摸索一遍。知识库文件也是Markdown格式你可以随时打开看、改、删不会像黑盒一样不可控。3.4 会话管理的快捷键体系用superpowers和用原生Codex的另一个明显差别是你在会话里可以随时介入AI的执行过程。终端里有一组快捷键我常用的大概这几个按键作用我的使用频率p放行当前请求高s跳过当前请求低r让AI重新描述或修订方案高d查看当前请求的详细操作内容中q退出会话中具体按键名可能因版本而异运行superpowers help或者看会话底部提示就能确认。刚开始比较容易手忙脚乱因为终端里同时出现AI的思考、能力申请和命令输出你要快速判断是放行还是拒绝。用几天习惯之后这套节奏会变成肌肉记忆。有两个小技巧值得试。第一当AI连续发起多个请求时不用急着逐条放行先按d看一遍所有请求的内容再决定哪些放行、哪些拒绝避免放行了方向错误的操作。第二如果发现AI正在做一件你不希望它做的事直接按s跳过当前请求然后在输入框里重新描述你的意图比让它继续执行再纠正要省得多。4. superpowers实战Java项目从搭建到修测试4.1 生成项目骨架与依赖管理很多人搜superpowers java其实就是想在Java生态里用它。我实际试过让AI从零搭一个Spring Boot 3项目过程比我想象的顺利。先让它查一下本机JDK版本和Maven版本把版本对齐的要求写清楚然后切到建议模式让它写pom.xml、Application类、一个REST Controller。每一步它都会提交写文件请求我审完再放行。当时我给的指令大致是请先查看知识库和本机环境然后生成一个基于Spring Boot 3.2的Maven项目 - package: com.example.demo - 仅包含一个GET /hello接口 - 使用Java 21 在生成之前先列出你要创建的文件清单等待我的确认。AI按顺序做了先检查环境再列出文件清单然后逐个申请写入。我在第三步时发现它漏了spring-boot-maven-plugin插件配置让它补上它接受了并先更新了pom.xml再继续。整个过程没有出现它擅自下载一堆依赖、改了全局Maven settings的情况。依赖管理方面我建议在授权时多留一个心眼。AI申请执行mvn dependency:tree这类只读命令可以放行但申请执行mvn install这类会把产物装进本地仓库的命令最好先确认它是不是真的需要。因为这类命令一旦跑多了本地仓库会被一堆中间版本污染后面排查依赖问题会麻烦。4.2 编译、测试与错误修复循环Java开发里最常用到的能力就是run_command。让AI跑./mvnw compile、./mvnw test把授权级别设成直接但限定只对测试命令放行。AI拿到编译错误后通常会先去读源码、看配置然后提出修改点你再决定放不放行写文件。我在升级Spring Boot版本时让AI反复循环了七次跑测试、看报错、改配置、再跑。它不会一次性把所有坑都踩完但每一轮都能把问题范围缩小一圈。最关键的体验是我没有让它直接改版本号而是看它怎么说再批。等于请了个特别有耐心的结对程序员它负责跑腿和找线索我负责拍板。这个循环里最容易出问题的是测试用例太慢。如果项目里测试很多AI每次都会老老实实跑全量测试一次下来可能十几分钟。我后来会在指令里明确只运行与本次改动相关的测试类例如OrderServiceTest、OrderControllerTest。这样既满足验证需求又不会把时间浪费在无关用例上。还有一个Java特有的坑AI有时候会建议修改target/generated-sources目录下的文件或者把.class文件当成源码去改。遇到这种情况直接在授权阶段拒绝就行没必要去纠正它因为它本质上是被项目的庞大目录结构带偏了。只要你的能力文档里写明不要修改target目录下任何文件这类错误会大幅减少。4.3 大型Java仓库的注意事项如果你的Java项目有几十个模块直接让AI分析整个项目它很容易在搜索和读取文件阶段就超时。我建议先保持只读模式然后指定具体模块路径比如重点分析order-service模块的依赖忽略其他模块。或者先让AI用查找文件能力列出模块列表再逐个深入而不是一次塞给它全部内容。Java项目里大量样板代码非常吃上下文窗口。让它输出完整类文件前先要求它用diff式修改只展示改动片段能够显著降低Token消耗。这个概念对AI和人都适用你不需要把整个500行的类打印出来只需要看到改哪几行、改成什么样。把指令写成请直接给出需要修改的代码块不要贴完整文件效果立竿见影。另外提醒一句知识库在大型项目里尤其重要。把每个模块的职责、构建顺序、部署方式存进知识库之后AI新会话里的响应速度和准确率都会明显提升。我习惯在项目开始的头两天分批次把模块信息写进知识库而不是一口气全塞给它。这样每次对话都只涉及当前任务需要的部分上下文干净AI也不容易犯迷糊。5. 常见问题与排查技巧实录5.1 命令找不到或启动报错最常遇到的报错是superpowers: command not found。先用pip show superpowers确认包到底装没装再用which codex看看Codex是否在PATH里。如果你是用sudo pip install装的装进的是系统级Python目录普通用户终端可能不在PATH里这种情况下建议改用python3 -m pip install -e .然后确认Python脚本目录在你的PATH里。还有一类启动报错是Failed to start codex通常是当前工作目录不对或者Codex授权令牌没配置好。我建议在一个空目录里先手动跑一次codex确认它能正常对话再回到项目目录跑superpowers。这能把问题分成Codex本身的问题和superpowers包装层的问题两层排查起来会简单很多。如果你是用Windows环境装完之后可能会发现codex命令生效了但superpowers找不到它。这种情况多半是PATH路径里的代码执行环境切换导致的把Codex可执行文件所在的目录追加到环境变量PATH里就能解决。实测下来Windows下最稳的做法是全程在Git Bash里操作而不是混用PowerShell和CMD。5.2 AI反复请求同一操作怎么打断循环有时候AI会陷入一种循环想读一个文件但被拒绝了于是换个说法又来申请一次第二次又被拒再换说法……看着很头疼。这种循环多半是授权级别太低或者你的指令没有把边界说清楚。AI不是故意抬杠它是真的没搞明白哪些能碰、哪些不能碰。解决办法是切到建议模式然后明确告诉它读取src/main/java下所有文件无需授权写入和运行命令才需要授权。如果工具支持细粒度权限配置直接在设置里给读操作开个白名单。还有一种更省事的思路冷启动时先用只读模式让AI把它需要了解的内容一次性都看完之后再做需要写操作的任务这样它就不用在读文件和申请授权之间来回折腾。如果你的提示词已经说得够清楚AI还是反复请求同一操作那就不是授权级别的问题而是AI对上下文的理解产生了偏差。按r让它重新描述一下当前的执行计划通常能打破僵局。要是还不行直接退出会话重新开一个把前一轮的分析结果保存到知识库新的会话就能站在之前的肩膀上继续干活效率比反复纠正要高。5.3 大仓库下搜索超时或结果截断大仓库场景下AI的搜索能力容易超时尤其是Java项目里带着一个巨大的target目录或者.git历史文件时。很多搜索能力实现是递归遍历一旦碰到这些庞大的目录性能会急转直下。解决方案是在能力文档的notes里写上忽略规则明确跳过target/、node_modules/、build/等目录AI执行搜索时会按规则过滤。如果某个搜索任务实在太大我倾向于引导AI先跑一个更精准的find命令而不是用全仓库的全文搜索。比如让它先执行find . -name OrderService.java -not -path */target/*拿到具体文件路径后再只读那个文件。这样既快又省Token。把大任务拆成若干个小任务也是我一直坚持的做法。还有一点可能很多人忽略不要在一个超大会话里持续累积搜索和读取结果。当会话上下文接近上限时AI的行为会变得飘忽比如漏看之前的结论、反复要求重复信息。此时最好的策略是让AI把关键结论写入知识库然后新开会话。这个习惯在大型Java项目里尤为重要。5.4 与Codex原生配置的冲突superpowers作为包装器会去读取Codex的配置和认证信息。如果你之前对Codex做过深度定制比如改过模型、调整过approval mode、或者用了一些插件升级Codex之后有可能出现superpowers行为异常。我遇到过两次一次是Codex升级后superpowers传给它的某个CLI参数失效另一次是两边配置文件里的模型名称对不上导致AI一直在启动阶段打转。遇到这类问题先看superpowers的日志。运行superpowers --verbose能看到详细的调用过程包括传给codex的参数和输出内容定位起来非常直观。如果确认是参数失效检查superpowers是否有新版本通常社区跟进很快。升级之后还不行的就把Codex退回上一个稳定版本然后等wrapper侧修复再升。建议养成一个习惯在调整Codex配置文件之前先把相关配置备份一份。毕竟superpowers和原生Codex共用一层底层配置两边不是完全隔离的。备份起来不过一条命令的事等到配置被覆盖再想找回那才真是麻烦。5.5 常见问题速查表把这几个高频问题整理成一张表遇到的时候照着查就行问题可能原因快速处理superpowers找不到PATH未配置或未安装pip show、which codex、检查PATH启动报错Failed to start codexCodex本身未认证或目录不对空目录先手动跑codexAI反复请求同一操作授权级别太低或指令边界不清切建议模式、明确读写边界、按r重新描述大仓库搜索超时遍历了target等大目录能力文档加忽略规则、改用find缩小范围与Codex配置冲突版本升级或参数失效看verbose日志、升级wrapper、备份配置6. 个人经验与最后提醒我个人用了大概一个月之后最深的体会是工具本身不神奇神奇的是它把AI开发逼到了先沟通、再动手的轨道上。以前AI自动改代码你事后review现在它在动手前就告诉你我要改什么、为什么改你来做决策。这种感觉在Java项目里尤其明显——本来构建链路就长测试也多AI一头扎进去乱跑不如让它每一步都跟你对一遍。最后一个实用技巧别急着在项目第一天就建知识库先跑两轮让AI摸清项目然后明确告诉它把现有约定写入知识库。之后的会话体验会明显上一个台阶它不会每次都是个金鱼记忆。说真的唯一后悔的是没早点把授权模式用起来。