企业官网建设流程全解析

这款叫 Superpowers 的工具，说白了就是给 OpenAI Codex CLI 这类编程助手“加技能包”的增强层。我自己在把 Codex CLI 从“能跑”推到“真正能干活”的过程中，花了很多时间在写重复的脚手架、反复解释项目上下文、还有处理那该死的代理和测试环境上。后来我把 Superpowers 装进日常流程，才发现之前很多“AI 写代码”的糟糕体验，其实不是模型不行，而是我根本没有给它搭好一套可复用的协作骨架。这篇就从一个普通开发者的视角，聊聊 Superpowers 到底是什么、怎么装、怎么用，以及我分别在 Java 后端和 WordPress 插件开发两个完全不同的场景里，是怎么靠着它把效率提上去的。

1. superpowers 到底是什么，它解决了什么问题

1.1 从一句牢骚说起：为什么 AI 编程助手总是“差一步”

先说真实场景。你打开 Codex CLI，丢给它一个需求：“把这个 Controller 加上分页参数，顺便把响应包成统一格式”。它确实能生成代码，但大多数时候生成的是“局部正确”的代码——它不知道你项目里已有的 Result 类长什么样，不知道你的分页用的是 PageHelper 还是 Spring Data，也不知道你接口的异常处理统一在哪里兜底。于是你只能一遍遍补充上下文，甚至把整个文件粘贴进去，来回折腾好几轮，改出来的代码还得自己手动调。

说到底，这是上下文缺失和流程断裂的问题。模型本身不是不能用，而是每次会话都像让一个新同事从零接手你的项目，又没有文档可以查。Superpowers 干的事，就是把“你希望 AI 助手具备的专业能力和项目认知”固化成一系列可复用的技能、规则和自动化脚本。它不是替代 Codex CLI，而是让它变成一个真正熟悉你工作方式的搭档。

1.2 核心能力拆解：技能、上下文与自动化三板斧

Superpowers 这个名字听着中二，但拆开看核心就三块：

• 技能（Skills）：把某个具体任务的处理流程封装成一段可复用的指令 + 脚本。比如“跑一遍测试”、“按项目规范生成模块代码”、“检查代码风格”。每个技能本质上是一套 prompt 模板，外加可选的 shell 命令。
• 上下文管理：通过项目级的配置文件（通常是.codex或superpowers目录下的 markdown/JSON 文件），把项目结构、技术栈、编码规范、常见约定告诉模型。相当于给 AI 发了一本“项目入职手册”。
• 自动化执行：Codex CLI 本身就能执行 shell 命令，Superpowers 把很多“先做什么再做什么”的流程编排成固定步骤，让 CLI 可以自动完成建分支、跑测试、提交信息生成这一连串动作。

这三块叠在一起，带来的最大变化是：AI 从“被动回答”变成“按流程干活”。它不再只是生成片段，而是可以围绕你定义好的工作流，连续执行多项操作，并且每一步都参考固定的项目规范。

提示：Superpowers 本身基于 Codex CLI，所以前置条件是你得有一个 OpenAI Codex CLI 环境。它不是一个独立运行的 IDE 插件，而是配合命令行工作流的增强工具。

2. 先把环境搭好：安装与前置准备

2.1 依赖清单与版本建议

在动手装 Superpowers 之前，我建议你先确认几个基础依赖，否则装到一半很容易被各种报错打断。我的环境是 macOS + zsh，Linux 和 Windows（WSL）下的流程也大同小异，只是路径上有些差异。

• Node.js 18 或更高版本：Superpowers 的安装脚本和部分技能依赖 Node 运行时。
• Codex CLI 已安装并完成登录：确保在终端里运行codex能正常进入交互。这一步很重要，很多人全程发现codex命令不存在，实际上是压根没装过 CLI。
• Git：部分技能会调用 git 来创建分支、生成提交信息。
• 一个可用的终端（建议 iTerm2 或 Windows Terminal，主要是颜色和输出排版舒服一些）。

版本方面，我个人建议直接用最新的稳定版 Node。早期版本的 Superpowers 和一些技能的兼容性有点一言难尽，凡是遇到node: internal/module这类报错，多半是 Node 版本太老，先把 Node 升上去再排查。

2.2 superpowers 安装三步走

安装方式很简单，核心就是一条命令。官方 README 里推荐用npx来安装：

npx superpowers install

这条命令会自动做几件事：

1. 检查本机 Codex CLI 是否存在；
2. 将 Superpowers 的 hook 配置写入 Codex 的配置文件（默认是~/.codex/config.toml）；
3. 克隆一份默认的技能仓库到本地，路径通常为~/.codex/superpowers。

装完之后，我建议你重启终端，或者手动重新加载 shell 配置，然后直接跑一个命令验证是否生效：

codex

如果 Codex CLI 在启动时能看到类似 “Superpowers loaded” 的日志输出，就说明安装成功了。

2.3 第一印象：目录结构里藏着哪些东西

装好之后，我建议你花 10 分钟浏览一下~/.codex/superpowers这个目录。它本质上是一堆 markdown 文件和少量脚本的集合。第一次看到时你会觉得“就这？”，但耐心看下去会发现门道：

• skills/：存放每个技能的定义文件，格式通常是skill-name/SKILL.md。这文件里写清楚了这个技能在什么场景下用、需要什么前置条件、应该按什么步骤执行。
• context/：项目上下文模板文件夹。你可以把项目背景、技术栈、架构说明、编码规范长期放在这里，每次会话开始的时候让 Codex CLI 自动加载。
• scripts/：可选的辅助脚本。部分技能需要实际执行命令（比如运行测试、格式化代码）时，会去调用这些脚本。
• config.md或类似命名的全局配置文件：定义全局默认行为，比如默认语言、默认测试命令、默认代码风格。

理解这个目录结构很重要，因为后面你自己扩展技能、维护项目上下文时，改的就是这些文件。很多用户把它当成黑盒，出了问题不会调，其实就是没搞懂它的文件组织逻辑。

3. 核心机制：技能（Skills）到底是怎么工作的

3.1 技能注册表：从 prompt 到执行

Superpowers 里最核心的概念是“技能”。每一个技能都有一个注册文件，描述了技能的名称、描述、触发条件和执行步骤。当你在 Codex CLI 里和模型对话时，模型会根据你当前表达的任务意图，自动匹配相关的技能，然后将其中的指令和规范注入到当前对话里。

打个比方，你把技能理解成“操作手册”就行。比如有一个update-changelog技能，它里面写的是：先读取最近 git log，分析提交信息，按语义化版本规范更新 CHANGELOG.md，然后提交修改。如果没有技能，你要把这些步骤一点一点告诉模型；有了技能，你只需要说“更新一下 changelog”，模型就会自动按照手册里的步骤执行。

这里还有一个关键机制：技能可以嵌套调用。也就是说，一个技能的执行过程中，模型可以调用另一个技能来完成子任务。这种组合方式让复杂工作流也能被拆成一块块可复用的能力，而不是写一个巨大无比的 prompt。

3.2 内置技能清单与适用场景

Superpowers 默认仓库里带了一批开箱即用的技能，覆盖了开发中高频的杂事。我列一下我实际用过的几个，和它们对应的典型场景：

这些技能在真实项目中帮我省下了大量“手把手教 AI”的时间。尤其是write-tests和run-tests的联动：以前让 AI 写测试，它写完就完了，你还得手动跑一遍看红不红；现在它会自己调用命令，跑挂了再自己修，循环到通过为止。这个体验是我觉得质变的地方。

3.3 自己写一个技能脚本

如果内置技能不够用，完全可以自己写。一个技能本质上就是一个目录 + 一个 markdown 文件。下面我用一个“生成 mybatis mapper 接口”的小场景示范一下。

先在skills/下建目录：

mkdir -p ~/.codex/superpowers/skills/generate-mapper

然后用编辑器创建skill.md（文件名看版本，有的仓库用SKILL.md）：

# Generate MyBatis Mapper 你是一个熟悉 MyBatis 的 Java 开发者。根据用户提供的实体类和表结构，生成对应的 Mapper 接口和 XML 映射文件。 ## 步骤 1. 从项目上下文中读取实体类位置。 2. 分析实体字段与数据库表字段映射关系。 3. 生成 Mapper 接口，包含 insert、update、selectByPrimaryKey、deleteByPrimaryKey 方法。 4. 生成对应 XML 文件，放到 resources/mapper 目录。 5. 如果项目中有测试数据库连接配置，生成一个简单的 CRUD 冒烟测试并执行。

写完后保存。在 Codex CLI 会话里，你只要说“给 User 实体生成一个 MyBatis Mapper”，模型就会先读取这个技能的定义，然后照着里面的步骤走。如果你有更多细节要约束，比如“方法命名必须要用insertUser而不是addUser”，直接写进技能里就行。

注意：技能文件里的描述写得越具体，模型执行越稳定。不要只写“生成 mapper 文件”，至少要写清楚输入是什么、输出在哪里、要遵循什么命名规范。

4. 实战一：Java 项目里怎么用 Superpowers

4.1 Java 工作流痛点：上下文重、规范多、验证慢

Java 后端项目大概是代码生成类 AI 最头疼的场景之一。原因很简单：Java 项目上下文重，类多、依赖多、约定多。你让模型生成一个 Service 实现类，它得知道你 Controller 的返回结构、异常处理方式、Mapper 的接口风格、甚至实体类用的是 Lombok 还是手写 getter/setter。没有这些上下文，生成的代码就是用不了。

另外一个痛点是 Java 项目通常有强约束的工程规范，比如 Checkstyle、Spotless、统一返回体。以前我用 Codex CLI 生成完代码，需要手动跑mvn compile检查能不能编过，再跑格式化工具，改完再手动提交。一次完整的改动往往要十几分钟。

Superpowers 在这个场景能解决两个问题：一是通过项目上下文文件，把工程全貌一次性告诉模型；二是通过技能串联，让“生成代码 → 编译 → 测试 → 格式化”变成一个自动流程。

4.2 用 superpowers 重构一个 Spring Boot 接口的完整过程

我举一个实际的例子。假设当前项目里有一个旧的 Controller 方法，返回值直接是List<User>，但项目规范要求所有接口返回统一包装类Result<T>。我的目标是把接口改成返回Result<List<User>>并同步修改 Service 层。

首先，确保项目根目录下有 Superpowers 的上下文文件。我在.codex/context.md里写了类似这样的内容：

# 项目上下文 - 技术栈：Java 17, Spring Boot 3.2, MyBatis-Plus, Lombok - 统一返回类：com.example.common.Result<T>，包含 code, message, data 字段。 - 全局异常处理器：GlobalExceptionHandler，业务异常抛出 BizException。 - 代码格式：使用 Spotless + Google Java Format。 - 测试框架：JUnit 5 + Mockito。

然后我打开 Codex CLI，直接给指令：

用统一返回类重构 UserController 的 listUsers 接口，让它返回 Result<List<User>>，同步修改 UserService 实现类。改完跑一遍测试。

这里因为上下文文件已经把工程规范告诉模型了，它不需要我再补充“Result 类在哪”“异常怎么抛”这种基础问题。它会直接动手改代码，改完调用测试命令。中间如果编译失败，它会自己读错误信息再修。

我实测下来，这类重构任务在有上下文的情况下，一次就过编译的概率高很多。而且因为我在指令里已经说了“跑一遍测试”，它执行完代码改动后会调用 Maven 测试命令，把测试结果贴出来。如果测试挂了，它会继续修，而不是把烂摊子丢给你。

4.3 Java 专属技能配置：让生成代码更贴合工程规范

默认技能可以跑，但如果你想让 AI 生成的代码更贴合团队规范，建议给它加一层“Java 专属技能”。我自己的做法是在skills/下建了一个java-spring-boot技能，里面不写具体业务，而是写死了代码规范：

# Java Spring Boot 编码规范 编写或修改 Java 代码时，必须遵守以下规则： 1. Controller 层只负责参数接收和响应包装，不允许出现业务逻辑。 2. Service 接口命名统一以 Service 结尾，实现类以 ServiceImpl 结尾。 3. 所有返回数据使用统一返回类 Result<T> 包装，禁止直接返回裸对象。 4. 依赖注入使用构造器注入，禁止使用 @Autowired 字段注入。 5. 实体类统一使用 Lombok @Data 注解，禁止手写 getter/setter。 6. 日志使用 Slf4j Logger，禁止使用 System.out.println。 7. 新增方法必须补充对应单元测试。

这个技能文件会被模型自动读取并约束行为，效果比你每次对话重新叮嘱“记着用构造器注入”稳定得多。时间一长，这个技能文件就是团队的“活规范”，新同事接手项目时也能直接受益。

我还发现一个很实用的组合方式：把 Spotless 格式化技能和代码生成技能绑定起来。模型改完代码后自动运行mvn spotless:apply，这样生成的代码风格统一，不会出现“AI 生成的排版和你手写风格完全不一样”的割裂感。

5. 实战二：WordPress 开发场景（worbuddy 工作流）

5.1 worbuddy 到底是干什么的

除了 Java 后端，我还拿 Superpowers 跑过一段时间的 WordPress 开发。你如果搜过worbuddy这个词，会发现它是社区里专门针对 WordPress 开发场景的一套 Codex CLI 工作流封装。它解决的问题很实际：WordPress 开发主要是 PHP + 主题 + 插件，项目里既有业务代码，又有大量 WordPress 钩子、全局函数和数据库表结构约定。裸用 Codex CLI 去生成插件代码，经常生成出不存在的函数，或者把add_action和add_filter用反。

worbuddy 的做法，是把 WordPress 的核心 API 文档、钩子命名规范、插件开发标准都转换成 Superpowers 可以加载的技能和上下文。这样当你让模型“写一个自定义文章类型的注册代码”时，它会根据技能里的规范，正确使用register_post_type，并且处理好 rewrite 规则、自定义分类法和固定链接刷新。

5.2 用 superpowers 驱动 WordPress 代码生成

实际使用中，我在一个 WordPress 插件项目里配置了如下上下文：

# WordPress 项目上下文 - 项目类型：WordPress 插件，目录结构采用 PSR-4 自动加载。 - 主文件：my-plugin.php，插件头注释必须完整。 - 所有对外输出必须通过 WordPress 钩子，禁止直接 echo。 - 数据库操作使用 $wpdb，必须做好 prepare 防注入。 - 代码兼容 PHP 7.4+，注意避免新语法在不支持的服务器上报错。 - 启用插件时必须 flush_rewrite_rules()，确保自定义文章类型伪静态生效。

然后我给 Codex CLI 下了个指令：

给这个插件新增一个 book 自定义文章类型，同时加一个 genre 自定义分类法，并生成对应的重写规则刷新代码。

模型加载上下文后，会先检查当前插件主文件里的钩子结构，再根据技能文件里对register_post_type的参数规范生成代码。生成完，它还会建议我把重写规则刷新挂在after_switch_theme或插件激活钩子上，而不是直接裸奔调用，这个细节如果只靠模型自己猜，很容易忽略。

我另外一个常用场景是生成 Gutenberg 块。WordPress 块开发涉及block.json、前端脚本、服务端渲染回调，结构冗余又讲究。用worbuddy的技能包后，模型能按照官方 block 开发规范搭建完整文件，而不是只给一个残缺的block.json就完事。

5.3 模板与上下文注入：让 AI 写出“带记忆”的代码

WordPress 项目的另一个特点是重复性极强。你新写一个插件功能时，代码风格要和旧功能保持一致，至少命名、注释风格、错误处理方式要统一。Superpowers 的上下文管理在这里能派上大用场。

我的做法是维护一份code-style.md，放在项目根目录的.codex/skills/下，里面记录了：

• PHP 文件头注释格式；
• 函数名统一使用prefix_function_name形式（前缀用插件名缩写）；
• 所有数据库查询必须走$wpdb->prepare；
• 前端资源通过wp_enqueue_script/wp_enqueue_style加载，版本号使用插件版本常量；
• 所有钩子注册集中在主插件文件或单独的 hooks 文件中，禁止散落在各个类里。

这样模型每次生成新模块时，都会先读取这份风格指南，再结合用户需求动手。你几乎不需要反复提醒“按之前的风格来”，它天然会遵守。后续维护别人写的代码时，也更容易保持一致性。

我还尝试过将多站点（Multisite）的注意事项写进上下文，比如“在站点切换时必须切换$wpdb->blogid”这类你不想每次重新交代的细节。效果很明显，代码里关于多站点的坑少了一大半。

6. 常见问题与排查手记

6.1 报错速查表

使用 Superpowers 这几个月，我积累了一些常见问题的排查经验。先列一张速查表，按我遇到的频率排序：

6.2 上下文窗口与性能管理：不是塞得越多越好

很多人以为上下文文件写得越长越好，把整个项目 README、架构文档、接口列表全塞进去。实际体验下来，这是个误区。模型上下文窗口有限，内容塞得太多，反而会稀释对本次任务的注意力，导致模型对一个简单问题也开始“长篇大论”或忽略核心指令。

我现在的经验是：全局上下文文件控制在 50 行以内，只写最关键的技术栈、目录结构、编码规范。对某一个模块的特殊说明，放到模块目录下的局部上下文文件里，需要时再加载。这就和你给新同事介绍项目一样，第一次只聊大框架，具体模块细节等到要上手时再看文档。

如果感觉模型开始“忘事”，比如前面刚告诉它的规范后面就不遵守了，我会把关键规范里最重要的两三句话，直接放到技能定义的规则列表最前面。这种重复强化对模型的效果很明显。

6.3 实测小技巧：如何让 Superpowers 真正“会用”

最后分享几个我实测有效的小技巧：

• 指令里带上技能名前缀。比如“使用 generate-commit-message 技能生成提交信息”，比单纯说“提交代码”更可靠。技能名相当于给模型一个精确的触发信号。
• 给技能加“默认值”。在技能文件里写清楚“如果没有特别说明，测试命令是mvn test或npm test”，这样模型就不需要每次向你确认用什么命令跑测试。
• 把验证动作写进技能。比如要求生成代码后必须编译/测试，否则技能不会自动验证。我在所有代码生成类技能里都会加上一句“完成后执行一次项目测试并报告结果”。
• 定期更新技能仓库。老版本的技能定义可能跟不上新功能，git pull一下官方仓库或者自己维护的 fork，保持技能版本更新。

7. 写在最后：一点真实使用感受

用 Superpowers 大概四个月，我最大的感受是：它没有让 AI 突然变得“更聪明”，但让我和 AI 之间的协作从“对话”真正变成了“工作流”。以前用 Codex CLI，每次都是从一个空白的上下文开始，反复喂信息；现在打开终端，项目规范、工程约定、测试命令这些东西都是现成的，我只需要把注意力放在“我要做什么”而不是“AI 需要知道什么”。

如果你也想在项目里引入这套东西，我建议不要一上来就追求把整个团队规范全部数字化。先挑一个你最常重复的场景，比如“生成提交信息”或者“跑测试并修复”，把它做成技能，跑顺了再慢慢扩展。我自己的路线图是从 commit 信息、单测生成、代码审查到重构，一步步才把 Java 和 WordPress 两套工作流建起来。

最后一个小建议：这些技能文件和上下文配置，本身就是项目资产。我现在的做法是把它们提交进项目仓库，后续无论是同事接手还是我自己半年后回来看，都能快速重建同样的 AI 协作环境。那些“写死”在技能文件里的规范，比口头约定可靠得多。