企业官网建设流程全解析

这两年，身边用AI编程助手的人越来越多，Codex、Copilot、Cursor轮番上阵，但我真正把日常开发流程理顺，反而是因为接触了一个叫superpowers的增强工具。它不替代Codex，也不抢IDE的活儿，而是把“上下文管理”“项目规则”“任务拆解”这几个最烦人的环节统一管起来，算是一个给AI编程加buff的外挂。如果你也遇到过AI改半天改不到点上、多文件改动改一半就停、每次都要反复交代项目背景这类情况，那这篇内容值得你看完。下面从安装配置讲到Java项目落地，再聊一聊那些文档里不会写的坑，尽量一次说透。

1. 先弄明白superpowers到底解决什么问题

1.1 它和Codex不是竞品，而是上下层关系

很多人在第一次听到superpowers这个名字时，会下意识以为它是又一个AI编程助手，或者某个Codex的平替。实际上它的定位完全不同。Codex这类工具负责“生成代码”，而superpowers负责“告诉Codex该怎么生成代码”。你可以把它理解成一道工序：superpowers先摸清你这个项目的结构、规范、边界条件，再把信息整理成Codex能高效利用的格式，最后由Codex动手写代码。

裸用Codex的时候，你给它一句“帮我把订单模块加一个查询接口”，它往往会基于当前打开的那个文件去猜上下文。当前类里的字段、项目的分层方式、返回结构约定、异常处理习惯，它一概不知。所以生成结果经常是“看起来像样，但跑不起来”，或者“Controller写得像Service，Service写得像Mapper”。superpowers做的事就是把这些背景信息主动推给模型，让AI在一个明确边界内做事情。

这个想法看起来简单，实际使用中差别非常大。我试过在完全没有superpowers的情况下让Codex改一个Spring Boot项目，它对项目里自定义的注解、统一返回体、权限校验逻辑完全没概念，改出来的代码要返工好几次。而把superpowers初始化好之后，同样的需求，第一次生成的结果基本就能进入代码评审阶段。核心差异就在于模型有没有拿到足够的上下文，以及拿到的上下文是不是组织好的。

1.2 哪些人最应该立刻试试它

基于我这段时间的使用体验，下面几类人受益最明显：

• 一个人维护多个仓库的独立开发者。每个项目技术栈都不一样，记忆成本很高，superpowers把每个项目的AGENTS.md和配置固定下来，切换仓库时不掉线。
• 团队里负责定AI使用规范的人。与其反复在群里提醒“AI生成的代码要遵守我们的分层规范”，不如把这些规则写进superpowers，让规则直接作用到每次生成里。
• 以Java、Kotlin这类企业级语言为主的项目。多文件协作、分层结构多、依赖复杂，AI很容易在一堆文件里迷路，superpowers的任务队列特别适合这种场景。
• 经常让AI重构老代码的开发者。老项目没有新项目那么规整，规则文件能明确告诉模型“哪些不能动”“哪些必须兼容”。

当然，如果你只是随手写点脚本，很少改多文件，那superpowers对你来说可能有点重。它的价值恰恰在复杂场景里被放大，简单的单文件任务直接让Codex做就够了，没必要额外维护一套上下文体系。

1.3 它的核心工作流程

superpowers的核心机制可以拆成三步：收集、注入、执行。收集阶段，它读取项目里的配置文件、规则文件、源码目录结构，生成一份当前项目的“快照”；注入阶段，它把这份快照按需裁剪后塞给Codex，作为系统提示词或前置上下文；执行阶段，它接收你的自然语言指令，把大任务拆成小步骤，逐个调用Codex完成，最后把结果汇总给你。

这个流程里最关键的是“上下文按需裁剪”。一个大型Java项目可能有几百个类，全塞给模型既不现实也没必要。superpowers会基于当前任务，判断哪些文件是核心、哪些是参考、哪些可以忽略，动态组织上下文。比如你要改的是订单查询接口，它会把Controller、Service、Mapper这几个相关文件优先级提高，把配置类、工具类降为引用，把无关的模块直接过滤掉。这种组织方式比“把所有文件都丢给模型”更聪明，也更省token。

2. 安装与初始化：照着做就行

2.1 先把环境依赖检查清楚

安装之前，我建议先把基础环境确认一遍，否则后面报错会让人头大。superpowers本身是一个命令行工具加IDE插件的组合，运行时依赖不算复杂，但有几个硬性要求：

• Node.js 18及以上版本，主要用来跑CLI本体。老版本Node会出现一些语法兼容问题，建议直接用LTS版本。
• 一个可用的Codex环境。无论是Codex CLI还是IDE插件版，必须已经完成登录认证，superpowers本身不负责认证，只负责调用。
• Python 3.11以上。部分分析脚本和规则校验器依赖Python环境，如果你完全不想装Python，需要在配置里显式关闭相关功能。
• 如果是Java项目，本地要有JDK 17+和对应的构建工具，Gradle或Maven都行。superpowers在执行任务后会调用构建命令做验证，没有这个环境就没法自动检查编译。

安装之前最好先跑一下codex --version，确认Codex本体可用。因为很多人装完superpowers之后发现命令不生效，查到最后是Codex那边没登录或者版本太旧。这个顺序能省很多排查时间。

2.2 安装和初始化只有几步命令

superpowers的安装方式很常规，我用npm装过，也用Homebrew装过，两者都正常。安装命令如下：

# npm 方式 npm install -g @superpowers/cli # 或者 macOS / Linux 下用 Homebrew brew install superpowers/tap/superpowers

装完之后先跑一个环境自检：

superpowers doctor

这个命令会检查Node版本、Codex连接、Python环境、Git仓库状态等。如果某一项标红，按提示处理即可，不需要手动排查。

接下来进入你的项目目录，执行初始化：

cd your-project superpowers init --template java-spring

--template参数用来指定项目类型，superpowers内置了java-spring、java-maven、python-fastapi、node-express等常见模板。它会自动扫描项目结构，生成.superpowers/目录，里面包含AGENTS.md、superpowers.config.json以及一些规则片段。生成之后我建议花十分钟打开这些文件看一眼，因为模板只是通用规则，你需要在里面补充你这个项目特有的约定。

2.3 第一次跑通“自检”很重要

初始化完成之后，别急着提需求，先跑一遍：

superpowers check

这个命令会验证三件事：配置文件的格式是否合法、AGENTS.md是否能被正确加载、Codex连接是否工作正常。它会发一个极短的测试请求给模型，确认整条链路是通的。每次我升级版本或者换新电脑之后，都会先跑这个命令，至少能排除八成以上的“莫名其妙不可用”问题。

这里有个小提示：superpowers check虽然消耗的token很少，但如果你用的是按量付费的账号，也记得留意一下费用。我自己一般会在一个小模型配置下跑自检，等确认没问题再切回主力模型。后面我会专门讲模型怎么配。

3. 核心功能与日常配置

3.1 上下文注入：让AI真正“懂”你的项目

superpowers最基础也最重要的能力，是管理项目的AGENTS.md。这个名字沿用了AI编程社区里常见的“给代理看的说明文档”，可以理解成一份专门写给AI看的项目说明书。

它长这样：

# AGENTS.md ## 项目信息 - 语言: Java 17, Spring Boot 3.x - 构建: Gradle, 使用 `./gradlew build` 编译 ## 架构约定 - Controller只处理参数校验和路由 - Service负责业务逻辑，禁止直接访问Repository - Mapper接口对应XML文件，SQL不能写在注解里 ## 返回格式 - 所有接口返回 Result<T> 统一结构 - 错误码定义在 ErrorCode 枚举中 ## 禁止事项 - 不要修改 pom.xml 中的依赖版本 - 不要生成无意义的分页插件

你写完这些之后，每次提出需求，superpowers都会把AGENTS.md中的内容作为前置上下文注入给Codex。模型在动手之前就会“知道”自己面对的是一个什么项目、有什么规矩。这个效果非常明显，尤其是在多人维护的大型项目里，AI不会再把项目里约定好的统一返回体改成FreeMarker模板里的Map。

我个人的经验是：AGENTS.md不要一开始就写很长，写了十条规则，模型不一定每条都重视。先写必须遵守的硬约束，比如“禁止直接访问Repository”“统一返回Result”。等遇到问题再逐步补充，让AI的“行为规范”和你的项目一起演进。

3.2 任务队列：多文件改动不再做一半就停

日常开发中需求很少是单文件级别的，一个接口往往要同时动Controller、Service、Mapper、XML、DTO。直接让Codex一次改完，它很容易改到第三个文件时“忘了”前面两个文件改了什么。superpowers的任务队列把这个问题拆解了。

当我输入一个需求：

superpowers run "为订单模块新增按用户查询历史订单的REST接口，返回包含订单号和商品列表的明细，并补充单元测试"

它会先分析需求，拆成一个计划列表，类似：

[1/5] 创建 orderHistory 相关的 DTO 和 VO [2/5] 在 OrderMapper 中新增查询方法及 XML SQL [3/5] 修改 OrderService 实现分页查询逻辑 [4/5] 新增 OrderController 的 REST 接口 [5/5] 补充 OrderServiceTest 单元测试

每一步它都会调用Codex执行，执行完自动做编译检查或测试，失败的任务会标记为失败，你可以单独重试，不需要从头再来。这个机制对长任务特别友好，我再也不用盯着对话窗口里“改一半然后模型开始聊别的”。

用的时候我一般建议一次只给一个“内聚”的需求，比如“新增查询接口”是一个完整任务，而“新增查询接口并顺手优化一下日志框架”听起来就很分裂，容易让AI在多个目标里摇摆。任务队列的优势在于拆解和执行，前提是你给出的需求本身边界清晰。

3.3 常用命令速查

下面整理了我平时高频使用的一组命令，省得翻文档：

其中superpowers context这个命令我很推荐没事就看看。它会把当前项目里会被注入给模型的信息直接打印出来，你能直观看到AI到底“看到”了什么。大部分“AI生成结果离谱”的问题，其实都能在这里找到答案——往往是上下文里有和你预期不一致的内容。

4. Java项目实战：一个Spring Boot接口的完整改造

4.1 把需求说清楚，后续才不返工

理论讲再多，不如看一次完整流程。我拿一个真实的改造场景来演示：假设现在有一个订单模块，需要新增一个“按用户查历史订单”的接口，要求返回订单号、订单状态、下单时间和商品明细列表，只显示有效订单，分页返回。

如果直接把这个需求丢给Codex，它可能会直接生成一个Controller方法，然后随便补一个Service方法，但分页逻辑、状态过滤、DTO结构这些关键点很可能不符合项目现状。有了superpowers之后，我会把需求描述的颗粒度收紧一点，告诉它约束条件，然后让它去执行。

superpowers run "在订单模块新增接口 GET /api/orders/history?userId=xxx&page=1&size=10，只返回状态为VALID的订单，按下单时间倒序，分页对象使用项目已有的PageResult，补充Service层单元测试"

注意我在这句话里给了四个关键信息：接口路径和入参、状态过滤规则、排序规则、已有的分页类型。这些信息不是废话，而是给任务规划器提供拆解依据。它拆出来的步骤，会比“帮我加个接口”要准确得多。

4.2 从生成到验证的完整过程

执行之后，superpowers先做了上下文分析，输出下面这个计划：

[1/4] 新增 OrderHistoryVO 和 OrderHistoryItemVO [2/4] 在 OrderMapper 增加 orderHistoryList 方法以及对应 XML [3/4] 在 OrderService 增加分页查询逻辑，过滤 VALID 状态 [4/4] 在 OrderController 增加 history 接口并补充测试

第一步生成DTO的时候，它自动读取了项目里已有的VO风格，字段用了Java 17的record，还加了@ApiModel注解，这显然是从我刚才写的AGENTS.md里读到了“REST接口DTO统一使用record并加Swagger注解”这条。这一步很说明问题：没有规则注入之前，AI可能会生成老式class加一堆Setter/Getter，有了规则之后，它输出的代码风格和手写代码一致性很高。

真正的分页逻辑也在Service层自动实现了。生成的结果里写的是：

public PageResult<OrderHistoryVO> getHistory(Long userId, int page, int size) { Page<Order> orderPage = orderMapper.selectHistoryPage(userId, OrderStatus.VALID, PageRequest.of(page - 1, size)); List<OrderHistoryVO> items = orderPage.getContent().stream() .map(orderHistoryMapper::toVO) .toList(); return PageResult.of(items, orderPage.getTotal()); }

关键是它没有把SQL写成注解，而是放到了Mapper对应的XML文件里，因为AGENTS.md里有明确约定。整体改完之后，superpowers自动执行了./gradlew build触发编译和测试，第一次编译没过，原因是XML里一个resultMap字段名写错了。它在输出里标出失败原因，我直接执行superpowers retry 2，只把Mapper那一步重试了一次，后续步骤不受影响。

4.3 Java项目里的常见坑

Java项目复杂度高，遇到坑是必然的。我整理几个高频问题：

• 依赖冲突被“背锅”给AI。有时候编译失败看起来像生成的代码有问题，其实是项目里某个老依赖和最新版Spring Boot不兼容。superpowers无法解决依赖冲突，它只会如实报告编译错误。排查时要先分清是代码问题还是依赖问题。
• 模型没读XML文件。MyBatis的SQL写在XML里，但XML和Java类之间的映射关系，模型有时候会忽略。现在我习惯在AGENTS.md里写明“所有Mapper必须配套XML”，并禁止在注解里写复杂SQL，这样模型的误判概率会明显降低。
• 上下文窗口被大量代码撑爆。大型Java项目里，模型一次能处理的token有限。如果当前上下文被无关类占满，AI会“选择性失忆”。我的做法是尽量用superpowers的计划拆解，别让一次任务涉及过多文件，必要时主动在描述里加上“不要读取XX包下的文件”。
• 测试代码风格不统一。项目里的测试可能有老式的JUnit 4，也有新的JUnit 5。如果不写清楚，AI可能生成不匹配的测试注解。我建议把测试框架版本和示例写法也写进AGENTS.md，一次配置长期受益。

5. 进阶技巧：让superpowers变成团队基础设施

5.1 自定义命令模板，把重复劳动交给AI

用了一段时间之后，你就会发现很多需求是重复的，比如“新增一个实体和对应的Mapper/XML”“给Service补充一个分页查询”。你可以把这类型需求固化为命令模板。

在.superpowers/commands下新建一个create-entity.md文件：

# 新增实体及持久层 当用户使用 /create-entity 命令时，执行以下步骤： 1. 读取数据库表结构或实体类定义 2. 生成 Entity、Mapper 接口、Mapper XML 中的基础 CRUD 3. 遵守项目既有命名规范 4. 编译验证

之后直接调用：

superpowers run "/create-entity OrderItem"

它就会按固定套路执行。这个机制对团队特别有用：有经验的开发者把规范沉淀成命令，新人和AI都直接复用，而不是每个人各显神通。团队里用上这套之后，新人写持久层代码的质量下限会明显提高，因为AI已经被规则“训练”过了。

5.2 模型选型和成本控制

superpowers支持不同的模型组合，一个常见的配置是“规划用小模型，执行用大模型”。规划阶段的任务是拆解需求、分析影响面，不容易出大错，但省token效果好；执行阶段要生成代码，必须用能力强的模型。

你在superpowers.config.json里可以这样配：

{ "planner": { "model": "codex-mini", "max_tokens": 2000 }, "executor": { "model": "codex-plus", "max_tokens": 12000 } }

这个配置对日常消费影响很大。我自己的使用数据是，开启规划小模型之后，整体token消耗比全部用大模型少了大约三成，而生成质量几乎没有下降。毕竟拆解任务本来就消耗不了多少token，真正的开销在执行阶段。

另外建议给max_tokens设一个合理的上限。不设上限的后果是，AI在生成一个超长文件时无拘无束，可能把大量注释和无关代码都写进来。设了上限之后它会更克制，反而让输出更精炼。

5.3 把踩过的坑写回规则里

superpowers最好用的一点，是在不断使用的过程中“越用越懂你”。每当你遇到AI反复犯同一个错误，别急着骂，把对应的约束写进AGENTS.md或项目规则文件里。

比如我发现AI经常给时间字段生成Date类型，而我项目里使用的是LocalDateTime。于是我在规则里加了一条：所有时间字段强制使用LocalDateTime，禁止使用java.util.Date。从那以后，这个问题几乎再没出现过。再比如某次AI自动引入了一个测试框架，导致运行时错误，我就在规则里补充：“测试代码统一使用项目现有的JUnit 5，不要新增测试依赖”。规则是逐步长出来的，不需要一开始就追求全面。

这个习惯也可以推广到团队协作里。每星期花十分钟把团队评审中经常提出的代码规范问题，翻译成几条简洁的AI规则，日积月累下来，AI生成的代码会越来越像你们团队的风格。代码评审从“和AI反复拉扯”变成“确认AI有没有遵守规则”，效率提升非常明显。

我在实际使用中一个很重要的体会是：superpowers的价值不是它自己有多聪明，而是它逼着你把项目的边界和规则梳理清楚。以前我总觉得项目背景在脑子里，不用写下来，但用了它之后才发现，很多隐性约定连团队里的人类开发者也未必完全清楚。把规则写下来之后，不仅是AI受益，新同学上手也快了很多。如果你正打算入手，建议先在一个不算复杂的项目中试点，把AGENTS.md写好、把基础命令跑通，再慢慢加到日常主力项目里。工具本身很简单，真正花时间的，是你对自己项目的那份梳理。