企业官网建设流程全解析

年初那阵子我一直在用 Codex CLI 做日常编码辅助，说实话它的单点能力很强，但用着用着问题就暴露出来了：同一个任务，换一种问法，输出质量能差出好几条街。后来我把superpowers这个能力层接到了 Codex CLI 上，才感觉 AI 助手从"话痨顾问"变成了"按固定 SOP 干活的老员工"。这篇文章就是我这段时间的完整记录，包括安装、配置、核心机制，以及在 Java 项目里的实际落地姿势。如果你也在用 Codex CLI，想让它处理代码审查、测试补全、重构这类重复性任务时更稳定，可以参考这份使用教程。

说明一点：superpowers 本身不等于 Codex，它更像是一层"技能库 + 技能加载器"。下面所有操作命令和配置文件，都是基于开源社区最常见的用法整理，具体到你本机时，版本号和目录名可能会有差异，但思路完全一致。

1. superpowers到底解决的是哪类问题

1.1 只有"对话"没有"作业流程"的AI助手

聊到这件事，我先吐槽一下纯对话式 Coding Agent 的通病。你直接说"帮我修一下登录接口的报错"，模型确实会去翻代码、看日志、改文件，但它的处理路径是"自由发挥"的。运气好时一次改对，运气差时它在三个文件之间反复横跳，最后把日志打得更乱。

问题不出在模型智商，出在没有流程约束。现实团队里，任何有经验的工程师都不会直接闷头改代码：先复现问题、再定位影响范围、写一个会失败的测试、改完跑全量测试、最后整理变更说明。这一套流程是稳定的、可复用的，但纯对话模式下，AI 每次都要"重新发明一遍轮子"。

superpowers 解决的就是这件事：把高频任务沉淀成技能文件，模型在收到对应指令时，不再自由发挥，而是按技能文件里写好的步骤、检查项、输出规范去执行。

1.2 从临时指令到可复用技能

你可以把 superpowers 的能力机制想象成给实习生发了一本《部门作业手册》。没有手册时，实习生每次接到任务都来问你"下一步干什么"；有手册之后，他接到任务先翻到对应章节，按章节里的清单逐项完成，做完之后格式还和你要求的完全一致。

这一点对 Codex CLI 尤其有价值。Codex 原本就支持在配置里塞 system prompt，但 system prompt 越长，模型越容易在长上下文里丢失关键约束。superpowers 的做法是把长指令拆成按需加载的技能文件：模型先根据用户需求判断"该调用哪个技能"，再只加载对应的技能正文。这样既不需要维护一份巨无霸提示词，又能保证每个任务都有稳定的执行路径。

我在项目里实际跑了一周之后最直观的感受是：代码审查、编写提交说明、补单元测试这老三样，从"时好时坏"变成了"基本稳定"。偶尔还是会翻车，但翻车的点通常集中在技能文件之外的新场景，可排查的范围一下子小了很多。

2. 安装与前置环境：把能力层挂到Codex CLI上

2.1 环境要求与版本判断

先说前置条件。superpowers 通常以 Node.js 脚本或纯配置文件的方式分发，因此你本机至少需要满足以下环境：

• Codex CLI 已安装并能正常调用，建议版本不低于 0.20
• Node.js 18 或更高版本（如果你只用纯技能文件，不跑脚手架，Node 版本要求可以放宽）
• Git 已配置好，因为技能库的分发、更新都依赖 Git

安装之前，先确认 Codex CLI 的版本：

codex --version node --version git --version

如果 Codex CLI 版本过老，某些技能文件里用到的工具调用参数会不兼容，后面排查起来很头疼。我的建议是先把 Codex CLI 升到当前最新稳定版，再继续后续操作。

判断完版本后，还有一个容易忽略的前提：在工作目录里初始化 Git 仓库。superpowers 的很多技能动作依赖git diff、git log来理解当前代码改了什么，没有 Git 上下文，技能执行效果会大打折扣。

2.2 安装步骤与目录结构

不同发行版的安装命令不太一样，最常见的两种方式我分别列一下。第一种是走 npm 包方式：

# 全局安装能力层（具体包名以项目仓库为准） npm install -g superpowers # 在项目目录中初始化 superpowers init

第二种是直接克隆技能库到本地，然后在 Codex CLI 配置里声明技能目录：

git clone https://github.com/your-fork/superpowers-skills.git .superpowers

我这里不贴死某个仓库地址，因为你实际使用的 fork 或内置技能集可能不同。关键是安装完成后，项目根目录下应该出现这样的结构：

.superpowers/ ├── skills/ │ ├── code-review/ │ │ └── SKILL.md │ ├── write-pr-description/ │ │ └── SKILL.md │ └── java-test-builder/ │ └── SKILL.md └── config.json

skills/下面每个子目录就是一项技能，每个技能的核心是一个SKILL.md文件。config.json负责声明技能库的加载方式、匹配规则和默认参数。这个结构非常直观，后续你自己新增技能时，只需要在skills/下新建目录、写一个 Markdown 文件即可。

2.3 最小验证：跑通第一个技能

安装完别急着上复杂任务，先创建一个最小技能验证链路。在.superpowers/skills/hello-skill/SKILL.md里写：

--- name: hello-skill description: 当用户要求演示技能系统、打招呼或测试技能加载时使用 --- # Hello Skill ## 执行步骤 1. 用中文回复"技能系统已就绪"。 2. 列出当前仓库的 Git 分支名。 3. 输出本条技能的加载状态为 OK。

然后在终端里调用：

codex run "打个招呼，顺便确认技能系统是否加载成功"

如果配置正确，Codex 的输出里会出现"技能系统已就绪"，并且能看到当前分支和 OK 状态。如果没有任何反应，优先检查config.json里技能目录路径是否正确、技能名称是否和description匹配。

跑通这个最小案例，就意味着"技能加载-意图匹配-按步骤执行"这条链路是完整的。后面真正的工作流都是在这个基础上扩展出来的。

3. 核心机制：技能文件怎么写、怎么被调用

3.1 技能的本质是"结构化提示词+可执行步骤"

第一次看技能文件时，我的第一反应是：这不就是 Markdown 版的 system prompt 吗？用了一段时间才理解，它不是简单的提示词，而是把提示词、约束、步骤、输出格式绑在一起的执行单元。

普通提示词是一次性的，A 任务写一套，B 任务再写一套，互相之间没有沉淀。技能文件则是持久化的，同一个技能可以被反复调用，而且文件里可以写条件分支：什么情况下做第一步，什么情况下直接跳到第四步。这种结构化能力是普通对话提示词难以维护的。

可以这么理解：提示词是"口头交代任务"，技能文件是"标准化作业指导书"。前者适合创造性探索，后者适合重复性执行。superpowers 的策略不是取代前一种交互方式，而是把那些你已经摸清套路的工作固化下来。

3.2 一个SKILL.md示例的逐行拆解

我拿项目里一个自写的code-review技能做例子，展示技能文件的核心结构：

--- name: code-review description: 当用户要求进行代码审查、检查合并请求、review 他人代码，或提到"看看这个改动有没有问题"时使用 --- # 代码审查技能 ## 适用范围 - 审查本地未提交的改动（推荐使用 git diff） - 审查指定 commit 区间（输入参数为 base...head） - 审查单个文件的改动 ## 输入参数 - diff_source: git diff / git log 区间 / 文件路径 - depth: 快速检查或完整审查 ## 执行步骤 1. 先运行 `git status` 和 `git diff --stat`，确认改动范围。 2. 若改动超过 200 行，按文件维度逐个审查；否则全量审查。 3. 对每个改动点，依次检查：安全性、资源释放、边界条件、命名一致性。 4. 对疑似问题，必须引用具体文件和行号，禁止只说"这里需要优化"这类空话。 5. 输出审查报告到 `docs/review/` 目录，文件名包含日期。 ## 输出格式 - 问题清单：按严重级别从高到低排列 - 每个问题包含：文件路径、起始行号、问题描述、修复建议 - 最后附一段总体评价（3 句话以内）

拆解下来，关键点有三个：

• Frontmatter（开头的---块）里的name和description是模型判断"是否该启用此技能"的依据。description写得越具体，误触发越少。这条我后面专门踩过坑，稍后细说。
• 执行步骤是技能的灵魂。它尽量用可验证的动作来描述，比如"先运行 git status""超过 200 行就按文件维度审查"。模型执行时，会把每个动作和真实环境一一对应。
• 输出格式决定了 AI 干完活后交付什么产物。没有这个部分，模型很容易在一片分析里结束，不给文件和行号，后面人没法跟进。

3.3 技能的优先级、作用域与冲突处理

技能多了之后，一定会遇到"多个技能同时想被触发"的情况。superpowers 的常见处理原则是：

同名技能在不同层级存在时，项目级覆盖用户级，用户级覆盖全局内置。所以在团队项目里，我建议把通用审查技能放用户级，把带团队特定规范（比如命名规范、目录约定）的技能放项目级，这样既不影响个人其他仓库的使用，又能让团队规范天然嵌进 AI 工作流。

冲突时还有一个隐藏问题：如果两个技能的description都匹配了当前输入，模型会怎么选？经验是，描述越长的技能通常匹配越精确，所以写技能时不要在 description 里堆一堆近义词，而是要写清楚"什么场景下用、什么场景下不要用"。反面例子是："当用户要求审查代码、检查代码、分析代码、review 代码时使用"，这种描述几乎每次都会触发，反而压缩了其他技能的激活空间。

4. 高频实战：拿superpowers做一次深度代码审查

4.1 触发方式与上下文准备

代码审查是我用 superpowers 做得最多的场景。以前靠人肉 review，眼睛盯着 diff 看半天；现在我把流程交给技能，自己只负责在关键节点把关。

触发很简单，在项目目录下执行：

codex run "对当前未提交的改动做一次深度代码审查，按 code-review 技能执行"

注意"按 code-review 技能执行"这个说法，它会帮助模型锁定技能，而不是自由发挥。执行前我会先确认两件事：

• 当前改动是否已保存，工作区是否干净
• 如果只想审查某一次提交，需要提前知道 commit 区间，比如git log --oneline -5看一下最近的提交哈希

上下文明确之后，技能内部会先跑git status和git diff --stat，自动界定审查范围。这一步很重要，它保证了 AI 不会把整个项目的存量代码都拿来评论一遍。

4.2 审查维度的拆解

深度审查不等于"从头到尾把代码读一遍"。我在技能文件里把审查维度拆成五块，每一块都有明确的检查动作：

1. 安全边界：外部输入是否经过了校验，有没有把用户可控数据直接拼进命令或 SQL。
2. 资源释放：新打开的连接、流、临时文件是否在异常路径下也能关闭。
3. 并发正确性：共享变量是否有锁保护，异步回调里是否改了共享状态。
4. 边界条件：数组下标、分页参数、空集合、超时时间这些位置是否处理了极端情况。
5. 可维护性：新增代码和周边代码的风格是否一致，函数是否过长，命名是否表达意图。

为什么拆这么细？因为纯靠模型自然输出时，它最爱抓的是"命名不好""函数太长"这类软性问题，那些真正能导致线上事故的硬伤，反而容易一晃而过。技能文件里明确列出安全边界、资源释放、并发正确性这些硬指标后，模型的注意力会被强制分配到这些位置。

实测下来，一次 300 行以内的 diff，深度审查大概在 3 到 5 分钟出报告，生成的问题清单里大约七成是有真实价值的，另外三成是误报或低优先级建议。即便是误报，也比以前"完全漏掉"要好得多，因为至少有人类复查的抓手。

4.3 审查结果落盘与后续动作

技能执行完，默认会在docs/review/下生成类似20250612-code-review.md的报告文件。我习惯再加一个后续动作：用另一个技能把报告中"严重"级别的问题自动拆成修复任务。

codex run "读取 docs/review/20250612-code-review.md，把严重问题整理成带验证步骤的修复任务，输出到 TODO.md"

这一步等于把一个纯审查流程变成了"发现问题 -> 生成任务 -> 逐个修复 -> 人工确认"的闭环。修复任务里必须附带验证步骤，比如"修改后运行mvn -Dtest=LoginServiceTest test验证登录流程回归"，这样修复时不会出现"改完就跑、错了再改"的盲目循环。

我做了一版本地测试对比：同样一批代码改动，人工认真 review 大概需要 40 分钟；用技能审查加人工复核，总耗时降到 20 分钟左右，而且覆盖到的维度更均匀。耗时减少主要不是因为 AI 更快，而是因为技能接管了"逐行巡检"这种机械性工作，把人的精力解放出来处理真正需要判断力的部分。

5. Java项目里的落地姿势：从Maven构建到单测补全

5.1 为什么Java项目最容易受益

如果要说 superpowers 在哪种技术栈里收益最明显，我首推 Java 项目。原因很现实：Java 项目有标准化的构建流程、明确的生命周期和相对规整的目录结构，这些正好是技能文件最擅长固化的东西。

Maven 项目的生命周期是固定的：compile -> test -> package，Gradle 也类似。技能文件里把这一串固定动作写成模板，模型不需要每次重新猜测"Java 项目应该怎么构建"，直接从技能里读步骤即可。再加上 JUnit 在 Java 生态中的地位，测试的写法高度统一，非常容易让 AI 按固定套路补全单元测试。

身边同事问得最多的一个问题是："Java 项目这么啰嗦，AI 能搞定吗？"我的回答是：正因为啰嗦、规整，AI 反而更容易搞定。它不需要面对 20 种风格不同的前端目录结构，也不用猜模块之间怎么引依赖，一切都有既定路径。superpowers 就是把这些既定路径刻进技能里，让模型照着走。

5.2 典型操作序列

我在一个内部微服务里试过一个高频场景：修 bug 并补测试。先写了一个java-hotfix技能，核心步骤是这样组织的：

--- name: java-hotfix description: 当用户要求修复 Java 项目中的某个缺陷、异常或测试失败时使用 --- # Java 缺陷修复技能 ## 前置条件 - 确认当前在 Maven 或 Gradle 项目根目录 - 确认 JDK 版本已通过 sdk 或 JAVA_HOME 正确设置 ## 执行步骤 1. 运行 `mvn -q compile` 判断项目是否能编译。 2. 定位缺陷对应的类和测试类。 3. 先为缺陷场景补一个会失败的单元测试，运行确认失败。 4. 修改源码，使刚才的测试通过。 5. 运行 `mvn -q test` 做全量单测回归。 6. 若有 Checkstyle 或 SpotBugs 插件，运行对应 `mvn verify` 校验。 ## 输出 - 修改的源码和测试文件列表 - 每个文件的变更摘要 - 测试运行结果摘要

然后实际执行：

codex run "订单模块在金额为 0 时会错误地发送通知，用 java-hotfix 修复并补测试"

技能会先把编译跑通，然后把失败测试写出来，确认测试确实失败后才去改源码。这个"先红后绿"的顺序是技能里写得最死的一步，不能颠倒。正因为这一步被固定下来了，AI 才不容易出现"看似改完了，但其实测试没覆盖到真正问题"的情况。

跑完mvn -q test之后，模型还会把变更文件、变更摘要、测试结果统一输出。这个输出我通常会直接贴到 MR 描述里，省去重新整理的时间。

5.3 需要额外看住的几个点

Java 项目里用技能，有几个点是你必须额外留意的，否则很容易翻车：

• JDK 版本切换。技能里可以写"确认 JDK 版本"，但模型不会主动帮你装 JDK。建议在技能文件里要求先执行java -version并判断是否与项目要求一致。
• Maven 本地仓库的依赖解析。第一次构建可能因为要下载依赖而很慢。给技能里加一个超时认知：依赖不可用时不要反复重试，直接报错并列出缺失依赖坐标，交给人工判断。
• 不要写死仓库内部地址。内部依赖的 groupId、artifactId 可以写进技能，但仓库 URL 这种环境相关配置应该走本机的settings.xml，技能里写死了反而会让其他环境的协作者跑不起来。
• 测试方法命名规范。很多 Java 项目要求测试方法按方法名_测试场景_预期结果的格式命名。把这个规范写进技能的说明部分，生成的测试会自然贴合团队风格，省掉后续大量改名工作。

最开始我也没在意这些细节，结果技能生成的测试很多都用了自定义的随机名字，结果 Codex 自己生成的测试和项目既有风格完全不搭。把规范固化进技能文件之后，这个问题基本绝迹。

6. 我踩过的坑和长期使用建议

6.1 最常见的坑

把 superpowers 正式接进工作流之后，我前前后后踩了不少坑，挑几个最有代表性的列出来，都是教训换来的。

第一个坑我最开始完全没意识到。我给某个技能写的 description 是"分析代码问题、检查代码质量、代码审查"，结果每次让 AI 写新功能时，它也觉得自己该"分析代码问题"，于是深度审查技能频频上线，既浪费 token 又干扰主线任务。后来我把 description 改成"当用户明确要求 review 未提交改动、检查合并请求或输出问题清单时使用"，误触发率降了很多。

token 消耗的问题也很典型。一开始我把一份完整的团队编码规范塞进了某个技能的 SKILL.md 里，结果技能一被触发就要消费大量 token 去读这份规范，一次小修复愣是吃掉平常两倍多的量。后来我把规范拆成单独的 REFERENCE 文件，技能文件里只写"如遇规范相关冲突，读取 docs/style-guide.md 再判断"，按需加载，消耗立刻回落。

6.2 长期使用建议：从复制到内化

如果你现在刚开始接触 superpowers，我的建议是先别贪多，把下面三个任务做进技能文件就够用了：

• 代码审查（最通用，收益最快）
• 提交说明生成（每次 Git 提交都用得上）
• 失败测试修复（Java 或前端都适用，流程非常固定）

这三个跑顺之后，再慢慢扩展自己的技能库。这里有个方法论：每次使用 Codex 时，如果发现某个任务的表现不稳定，就值得把它固化成技能。所谓不稳定，指的是同一类输入，结果时好时坏、时快时慢。稳定表现的任务不需要固化，因为它已经在按默认方式好好干活了。

另外，技能文件一定要纳入版本管理。我自己吃过亏，某次改技能时没备份，随后一次实验把它改坏了，整个下午的代码生成质量都受影响。把.superpowers/skills/提交到 Git 仓库后，每次调整都能 diff、能回滚，心理负担小很多。

还想多说一句收藏习惯。网上有不少现成的技能仓库，看到好的技能拉下来用没问题，但建议用之前通读一遍 SKILL.md，理解它的执行步骤，再按自己项目的实际情况调整。盲目堆技能和当年盲目收藏书签没有区别，存了一堆，关键时刻一个都不好使。

superpowers 这套东西真正的价值不在于某个具体技能写得多漂亮，而在于它逼着你去思考：哪些任务是稳定重复的，哪些步骤是可以标准化的。想清楚这件事，AI 工具在你手里就不再是"厉害的玩具"，而是真正能交付结果的同事。

最后分享一个小技巧：在每个 SKILL.md 的末尾加一条"工作结束后，用三句话总结本次执行结果"。这一条能让模型在收尾时主动交代改动范围、测试结果和遗留风险。这个设计的收益不是一点半点——相当于每个自动化流程都自带一份执行摘要，复盘的时候根本不用翻完整对话记录。