企业官网建设流程全解析

1. superpowers 是什么：不是魔法框架，是给 Codex 的一套增强工作流

先说结论：superpowers 不是一个让你敲几个咒语就能自动生成整个项目的魔法框架，它本质上是给 OpenAI Codex CLI 套上的一层"能力增强包"——通过预置技能库、规范化上下文注入、任务编排模板和领域适配配置，把 Codex 从一个单纯"能写代码的对话工具"，改造成一个更懂你项目结构、更守规矩、能按步骤推进复杂改造任务的开发搭档。

让我用一个生活化的类比解释一下。你从店里买回来的电钻，能钻孔，但要用它精确地在一个 3 毫米厚的不锈钢板上钻出间距完全一致的 20 个孔，你得自己量尺、画线、定深度。superpowers 就是给你配好的一整套"夹具+标尺+定位模板"，让同一个电钻干起精细活来不再靠手感。对 Codex 这类 LLM 驱动的命令行工具来说，它最大的问题不是"不会写代码"，而是"不理解你的项目上下文"和"不知道按什么节奏推进任务"。superpowers 恰恰针对这两个痛点做文章。

这个项目最初在开发者社区流行起来，很大程度上是因为 Codex CLI 本身提供了足够的可扩展点——自定义指令文件、AGENTS.md 项目规范、会话工作流控制——但原生状态下的这些能力太零散，每个使用者都得从零摸索一套适合自己的配置。superpowers 就是把社区里被验证过的配置模式、提示词模板和技能定义固化下来，形成一套开箱即用的标准方案。

适合谁来用？我觉得有三类人收益最大：一是刚接触 Codex CLI 的新手，不用从零学上下文工程就能获得一个靠谱的默认配置；二是做 Java 后端、日常要处理大量规范化代码和重构任务的开发老手，它能帮你把重复劳动压缩到极致；三是团队里负责搭建 AI 辅助编程规范的技术负责人，可以直接以 superpowers 为基底做二次定制，统一小组成员的工具使用方式。

2. 安装与初始化：五分钟让 Codex"觉醒"

2.1 环境准备与前置依赖

在装 superpowers 之前，先确认本机环境是否达标。这里有个容易忽略的细节：很多人以为装这种工具只需要 Node.js，实际上它依赖的是一个完整的本机开发环境链。

• Node.js 版本要求 18 以上，推荐用 20 LTS。因为 Codex CLI 和 superpowers 的脚本层都依赖新版 Node 的 API，老版本会遇到各种莫名其妙的兼容报错。我见过有人用 16 版本硬装，结果在初始化时卡在 fetch 相关的方法上，排查半天才发现是版本太旧。
• Git 必须可用，而且建议配置好 SSH key。安装过程需要克隆仓库，后续更新技能包也得靠拉取远程分支，走 SSH 比 HTTPS 舒服得多，不用反复输凭证。
• 本机需要安装好 Codex CLI 并完成认证。如果你还没装，先执行npm install -g @openai/codex，然后运行codex login完成账号绑定。这一步必须放在前面，因为 superpowers 的初始化脚本会检测 Codex 的配置文件路径，没有它就直接报错退出。
• Java 场景的话，确认 jdk 和 maven/gradle 在 PATH 里。superpowers 的技能包有一个"构建感知"功能，需要调用实际的构建工具来解析项目结构，如果 PATH 里找不到 java 命令，技能包会把你的项目当纯文本库处理，效果大打折扣。

这些前置条件都满足之后，安装过程本身其实非常顺滑。

2.2 安装步骤与配置要点

superpowers 的安装走的是典型的开源工具套路：克隆、安装依赖、初始化。

# 克隆项目仓库到本地工作目录 git clone git@github.com:your-superpowers/superpowers.git ~/.superpowers cd ~/.superpowers # 安装依赖并执行初始化脚本 npm install npm run setup

setup脚本做两件关键的事：一是把内置的技能包和提示词模板软链到 Codex CLI 的配置目录；二是生成一份superpowers.config.json配置文件，放在你的用户目录下。这一步完成后，工具会提示你编辑~/.codex/config.toml，把 superpowers 提供的指令文件挂载进去。

我建议你在这个环节做一次手工确认。打开~/.codex/config.toml，你会看到类似这样的内容：

model = "gpt-5-coder" [instructions] files = [ ".superpowers/AGENTS.md", ".superpowers/coding-standards.md" ]

这里[instructions]是 Codex CLI 原生支持的自定义指令加载机制，路径可以填绝对路径也可以填相对路径。强烈建议在项目里创建.superpowers/目录，把这些 md 文件拷到项目内，而不是直接用全局路径。原因很简单：指令文件如果和项目在一个仓库里，整个团队都能共享同一套规范，而且随代码评审一起演进，不会出现你电脑上有一份配置、同事电脑上是另一份的情况。

2.3 验证安装是否生效

装没装好，不要看报错信息，直接做一个快速实测。在任意项目目录里启动 codex：

codex "简单介绍下你当前能做什么，以及你加载了哪些技能"

如果 superpowers 生效了，Codex 会在回复里列举出它加载的技能列表，比如"项目结构分析""构建感知""安全审查""测试生成"等。如果回复里没有任何技能相关的内容，说明指令文件没有被正确加载，回到上一步检查 config.toml 的路径写法。

还有一个更直观的验证方式：让 Codex 执行一次"项目体检"技能。输入codex "用健康检查技能分析当前目录的项目状态"，正常情况下它会先扫描目录结构、读取构建文件、分析依赖树，然后输出一份结构化的项目健康状况报告。这一步能同时验证技能调用链路和构建感知功能是否工作。我实测下来，第一次跑出完整报告大概需要 20 到 30 秒，再往后就会快很多。

3. 核心能力拆解：技能包、AGENTS.md 与任务编排

3.1 技能包：让模型拥有"领域直觉"

技能包是 superpowers 最核心的设计。你可以把它理解为一系列高度结构化的提示词模板，但比单纯的提示词复杂得多。每个技能包包含三部分：技能触发条件、执行步骤清单、输出格式约束。

举个例子，superpowers 内置的"重构安全网"技能包，触发条件是用户要求"重构某个模块"或"修复某处复杂逻辑"。触发后，它不会直接甩给你一段重构后的代码，而是按固定步骤走：先要求 Codex 梳理目标模块的入口和出口调用关系；再生成一份依赖图说明哪些外部模块会受影响；然后列出重构方案和风险点；最后才动手改代码，并且每改完一个函数都要自测一遍。

这个设计背后的逻辑是，LLM 直接写代码的成功率其实不低，但直接"按需求改完整个模块"的成功率极低，因为中间跳过了分析环节。技能包强制把分析步骤前置，相当于给模型戴上了一个"先想清楚再动手"的紧箍咒。我用下来的体会是，加了这层约束之后，重构类任务的返工率至少降了一半。

3.2 AGENTS.md：项目级上下文规范

AGENTS.md 是另一个关键环节。它本质上是给 AI 助手看的项目说明书，和 README 给人类看是两套逻辑。你会发现很多项目宿主目录下根本没有 AGENTS.md，这直接导致 Codex 进了项目就像新入职没看文档的员工，全靠试错。

superpowers 对 AGENTS.md 的推荐格式有一套自己的方法论，我把它精简为三层结构：

• 第一层：项目是什么。两到三句话说清楚项目定位、语言栈、核心依赖。
• 第二层：代码组织约定。目录结构怎么分层、命名规范是什么、数据库访问走哪层、有没有框架强制的代码风格。
• 第三层：AI 协作红线。哪些目录禁止 AI 直接改、哪些操作必须先询问、生成代码时必须遵循什么模板。

实际落地的时候，我建议你把 AGENTS.md 的第三层写细一点。AI 不像人，它不会觉得"这里没写应该也能猜到"，它只会按字面理解。比如你写"不要修改 test 目录下的 fixture 文件"，它就会老老实实绕过那些文件。如果你只写"注意测试数据完整性"，那它大概率会该改不该改的都碰一遍。

3.3 Java 场景的专项增强

superpowers 的 Java 适配做得比较深，这也是它能在 Java 开发者圈子里传开的重要原因。所谓"superpowers java"，我理解下来包含三个层面的增强。

第一个层面是构建感知。技能包会主动读取 pom.xml 或 build.gradle，解析出项目依赖树、模块结构和 Java 版本，然后把这些信息注入到 Codex 的上下文里。你不需要在提示词里手动描述"这个项目用了 Spring Boot 3.2 和 Java 21"，它自己就知道了。在生成代码时，导入的包名、注解的用法、依赖的版本，都会自动对齐项目实际使用的版本，不会给你写出 javax 还是 jakarta 混乱的代码。

第二个层面是模板代码生成。Java 项目里充斥着大量样板代码：DTO、Entity、Mapper、Service、Controller。superpowers 内置的 Java 技能包会要求 Codex 严格按照项目现有代码的风格生成新类，比如 Builder 模式用没用、Lombok 用没用、异常统一处理走哪个类，这些都会先扫描现有代码再模仿。用我同事的话说，"它生成的 Controller，风格和我们团队自己写的一模一样"。

第三个层面是测试策略。技能包会识别被测代码的类型，给 Service 层代码生成基于 Mockito 的单元测试，给 Controller 层生成基于 MockMvc 的集成测试，而不会用一个模板打天下。这个细节很见功力，因为盲目生成的单测往往要么太重跑不动，要么太轻没意义，按层级匹配测试策略才是 Java 项目的正确姿势。

4. 真实项目实战：用 superpowers 重构一个 Java 服务模块

4.1 任务规划与提示词设计

理论说了一堆，不如动手跑一遍。这次我拿一个实际场景来演示：把一个老旧的订单服务模块从 Spring Boot 2.7 升级到 Spring Boot 3.2，同时把 MyBatis 的 XML 映射迁移到 MyBatis-Plus 注解方案。这个任务包含依赖升级、代码迁移、API 兼容性处理、回归测试四块内容，非常适合展示 superpowers 的完整工作流。

开始前，我没有直接丢一句"帮我升级订单模块"。按照 superpowers 的技能触发规则，我用了更明确的任务声明：

使用「结构化迁移」技能，将 order-service 模块从 Spring Boot 2.7 升级到 3.2， 迁移 MyBatis XML 到 MyBatis-Plus 注解，先输出影响评估和安全风险清单，再进行代码改造。 迁移完成后，必须执行 mvn test 验证 order-service 模块的全部单元测试通过。

这里的关键是"先输出影响评估和安全风险清单，再改造"这一句。不看 superpowers 的文档，新手很容易忽略这种明确的阶段划分。实际上技能包内部已经有一套标准流程，但我特意把流程声明出来，是为了让 Codex 不要自作聪明地跳过评估阶段。

4.2 执行过程中的关键节点

Codex 拿到任务后，执行链路大概是这样的：

第一步，它自动激活了"结构化迁移"技能，调用构建感知能力解析 pom.xml。这一步非常快，几秒钟就识别出项目依赖了spring-boot-starter-web、mybatis-spring-boot-starter、mysql-connector-java等多达 30 个直接依赖项。它随即输出了影响评估报告，里面把高风险项——如springfox-swagger2这个在 Spring Boot 3 下已经无法直接工作的组件——用红字标了出来。

第二步是改造配置文件。这一步我注意到一个细节：Codex 不是直接改 pom.xml，而是先打印出将要执行的依赖坐标变更清单，在去掉过时依赖的同时，补充了mybatis-plus-boot-starter对应的版本。它没有去查 Maven 中央仓库，而是直接依赖 AGENTS.md 里我预埋的"项目统一依赖版本管理"说明，用了我们团队在 properties 里集中管理的版本号。

第三步是批量迁移 Mapper XML。这是整个过程中最耗时的环节。Codex 把 XML 文件里的 SQL 一句句改写成 MyBatis-Plus 的注解写法。让我比较意外的是，它没有机械地直接翻译，而是识别出了几个高频 SQL 模式——比如一个selectByUserIdAndStatus的方法，它自动推荐改用LambdaQueryWrapper的组合查询，并在注释里说明了原因：原 SQL 每次都要手写条件拼装，换成 wrapper 之后代码量能减少 40%，而且能利用 MyBatis-Plus 的逻辑删除机制。

全程执行完，Codex 生成了 19 个文件的改造，其中有 5 个文件它标了"建议人工复核"，原因是涉及自定义的 TypeHandler 和动态 SQL 中的<script>标签，这两个特性在注解模式下需要特殊处理。说实话，看到这个标记我是有点欣慰的——知道什么情况下该停下来请示人类，这正是它作为 AI 搭档最可贵的素质。

4.3 成果对比与效率量化

实测跑完，升级后的模块所有单元测试一次通过。原本我一个人手动干这个活，正经估计要两到三个工作日，其中大部分时间耗在查 Spring Boot 3 的 breaking changes 和适配 MyBatis-Plus 的新写法上。这次整个流程 Codex 加我的协作时间，大概两小时。代码评审的时候，团队同事对生成代码的质量评价是"超出预期"，尤其是 LambdaQueryWrapper 那几处改写，完全是资深工程师的手笔。

当然，不是说有了 superpowers 就能完全甩手。我在关键节点依然保持了人工介入：影响评估报告出来之后，我审了一遍风险清单；代码改造完成后，我没有立刻提交，而是滚了一遍全量测试再加人工 code review。这些环节省不了，但它们从"我要是漏看了怎么办"变成了"我只需要关注 AI 标出的风险点"，精神压力完全不是一个量级。

5. 高频问题与排查技巧实录

5.1 环境与安装问题速查表

用 superpowers 这段时间，我陆陆续续踩了一些坑，也帮身边同事排查过不少问题。我把最常碰到的几个整理成一张速查表，遇到问题先对着查一遍，能省很多时间。

这里我想单独强调一下最后一条。很多人觉得指令文件放在全局配置就行，但实际在团队项目里，"全局配置只在你自己电脑上生效"这个问题会逐渐显现出来。项目内放置指令文件，意味着团队成员所有人在跑同一个任务时，Codex 读取的是同一个 AGENTS.md 和同一套技能约束，生成结果才会稳定可控。

5.2 上下文丢失与"胡言乱语"的排查

Codex 在长会话里处理大型重构时，偶尔会出现"前面刚定好的约定，后面就忘了"的情况。比如迁移过程中，第一轮 Codex 主动提出"所有 XML 里的小写user_id列名统一改为下划线命名"，但执行到中段的时候，它又在新生成的代码里用了驼峰命名。这不是 superpowers 的 bug，而是 LLM 上下文窗口的固有限制——长对话中早期信息被逐渐挤压出去。

遇到这种问题，我的排查思路是：先检查当前会话是否已经到了上下文上限，如果是，直接开启新会话，把 AGENTS.md 和当前迁移进度重新喂进去；如果不是上下文长度问题，那就检查是不是技能包内部步骤太多，导致模型在中间步骤丢失约束。最后一招是给 Codex 一个"契约文件"，把关键约定写进一个migration-contract.md，在提示词里明确要求它每个阶段结束前读一遍这个文件。实测下来，这一招对维持长任务的一致性非常有效。

5.3 自定义扩展的常见坑

superpowers 本身是可扩展的，你可以往技能包目录里塞自己的技能定义。这个过程我试过几次，也掉过两次坑。

第一个坑是技能触发条件写得过于模糊。我给团队写过一个"依赖安全检查"技能，触发条件用的是"如果发现可疑依赖就执行"，结果 Codex 把"不认识的依赖"也判断成可疑依赖，逢项目就启动安全扫描，又慢又吵。后来我改成带明确信号的条件，比如"如果 pom.xml 或 build.gradle 中出现已声明编外依赖，或依赖版本低于指定基线，则触发依赖安全检查"。模型对明确信号的理解能力比对模糊语义的判断能力可靠得多。

第二个坑是输出格式约束不到位。自定义技能生成报告的时候，如果不规定输出格式，它会自由发挥，有时候是一段话，有时候是表格，有时候是代码块。这在单个任务里问题不大，但如果你像我们一样把 AI 生成报告接入 CI 流程做自动化归档，格式不稳定就是灾难。我在技能定义里加了严格的输出模板，用 Markdown 表格固定字段顺序和命名，之后问题就消失了。

6. 写在最后：几点真实的个人体会

把 superpowers 用顺手之后，我最明显的感觉是：Codex 从一个"每次说话都得把上下文重新捋一遍的实习生"，变成了一个"记得住项目规矩、知道轻重缓急的搭档"。这种转变不是模型变聪明了，而是工具链补上了"项目理解"这一课。

我个人在实际操作中比较推荐的做法是，把 superpowers 的配置当成项目资产来管理，而不是个人的本地收藏。AGENTS.md 和技能定制文件跟着代码仓库走，随着项目演进持续更新，让它变成团队知识库的一部分。新成员入职的时候，甚至不用人肉给他讲项目约定，让他对着 Codex 问一遍就能学个七七八八。

最后分享一个小技巧：如果你同时维护多个项目，每个项目的 .superpowers 目录可以各放各的，但全局的 superpowers.config.json 里建议关掉你不需要的通用技能，只保留高频使用的几个。技能包多了之后，Codex 每次启动都要花额外时间扫描技能库，响应会变慢。我一开始全量启用，一个简单问题要等它思考十几秒；后来精简到五六个核心技能，启动速度和回复速度都快了一截。工具是为流程服务的，装得越多不代表越好用，找准自己的核心场景，让 superpowers 专注解决那几个最痛的问题，才是它真正的价值所在。