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连续执行一串命令时，如果某个命令超出了你预期的范围，它是不会停下来问你的。所以我把直接模式的使用范围控制在单一命令上，比如"只允许运行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的执行过程。终端里有一组快捷键，我常用的大概这几个：

具体按键名可能因版本而异，运行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 常见问题速查表

把这几个高频问题整理成一张表，遇到的时候照着查就行：

6. 个人经验与最后提醒

我个人用了大概一个月之后最深的体会是，工具本身不神奇，神奇的是它把AI开发逼到了"先沟通、再动手"的轨道上。以前AI自动改代码，你事后review；现在它在动手前就告诉你我要改什么、为什么改，你来做决策。这种感觉在Java项目里尤其明显——本来构建链路就长，测试也多，AI一头扎进去乱跑，不如让它每一步都跟你对一遍。

最后一个实用技巧：别急着在项目第一天就建知识库，先跑两轮让AI摸清项目，然后明确告诉它"把现有约定写入知识库"。之后的会话体验会明显上一个台阶，它不会每次都是个"金鱼记忆"。说真的，唯一后悔的是没早点把授权模式用起来。