企业官网建设流程全解析

1. 这个东西到底是干什么的：superpowers 与 Codex CLI 的定位

1.1 不装 superpowers 的 Codex CLI，最容易踩的三道坎

先聊 Codex CLI 本身。它把大模型能力搬进终端，让你在项目目录下发指令，AI 能读文件、改文件、执行命令。听起来很全能，但实际用上一段时间，你会遇到几个很具体的坎，不是模型不行，而是缺一层“操作规范”。

第一，对话感太重。你让它修一个 bug，它第一轮往往只给一个修复方案，或者改了文件但没跑测试，等你追问一句才继续验证。在长任务里，这种“挤牙膏式协作”特别累。你既要盯代码，又要盯它有没有漏步骤，基本等于自己重新做了一遍项目管理。

第二，缺少自我纠错循环。AI 改完代码后，编译报错，它不一定会自己看到错误并继续修。很多时候报错信息就在终端里，它却已经回复“修改完成”，等你手动跑起来才发现问题。一次两次还能忍，任务一多，这个“假完成”会浪费大量时间。

第三，上下文里的约定容易丢。你希望它遵守一套固定的工程纪律，比如“每次改完必须跑测试”“遇到配置变更先检查引用方”，但这些规则每次都要重新交代。一旦会话变长，它就忘了前面的约定，你会发现自己越来越频繁地重复同样的话。

superpowers 瞄准的正是这个空间：在 Codex CLI 上叠一套技能包，把项目计划、实现、验证、修复变成一套让 AI 自主执行的循环，而不是靠你一句一句喂。所以网上搜“superpowers使用指南”时，你要先明白这不是换一个模型，而是换一套工作方式。

1.2 superpowers 不是一套代码库，而是一个“工作方法外挂”

我最早以为 superpowers 是一个独立程序，后来才发现它本质上是给 Codex 准备的一批技能提示词、辅助脚本和配置模板。你可以把它理解成“给 AI 助手写好的岗位说明书”。它没有替代 Codex，而是让 Codex 在启动时加载这些技能，知道遇到什么场景应该走哪种工作流程。

装上之后最直观的变化是：你提一个任务，AI 会先列计划、确认预期，再开始改代码；改完会主动跑构建或测试，看结果；如果失败，它会把报错带回上下文，继续改，直到通过或明确告诉你卡在哪。这个体验跟裸 Codex 完全不一样，更像带一个能自己交代进度的新人。

用生活类比来解释：给新人一台电脑不意味着他会干活，你得先告诉他团队怎么分工、遇到报错找谁、提交代码前要跑什么检查。superpowers 就是把这些规则打包成机器可加载的文本。所以理解这个项目的关键，是先抛开“代码库”思维，把它当成一套“操作手册 + 自动化钩子”的组合。后面所有配置项、路径、技能清单，都是在服务这件事。

2. 安装前的脑子要清楚：版本、目录、配置三条主线

2.1 你需要的最小环境，缺一不可

在安装 superpowers 之前，先说清楚我实践的基线环境：

• 操作系统：macOS 或 Linux，路径规则一致；Windows 建议走 WSL。
• Codex CLI：已安装且能正常启动，命令行可以敲codex进入会话。
• Git：用来把 superpowers 仓库拉到本地。
• 一个测试项目：最好是 Git 仓库，改动前能提交，方便对比 AI 到底做了什么。

这三样缺一会让后面的排查变得混乱，尤其是 Git。superpowers 的工作流里有个重要习惯：动手前先让 AI 确认工作区状态，至少保证改动前能回滚。没有 Git 这个动作就会退化成“直接改，改坏了也没办法恢复”。

安装前还要检查 Codex CLI 版本。最早版本的配置结构比较旧，新版本对技能和插件支持不一样。我踩过最大的坑，就是拿旧版 Codex 加载新格式配置，启动后提示未知字段，技能静默失效。建议先跑codex --version，把版本号记下来，后面所有配置格式都以它为准。

2.2 拉取 superpowers 到本地：目录选择有讲究

项目本身不复杂，一条git clone命令就能拿到。真正有讲究的是放哪个目录。网上流传比较广的做法是放在用户目录的.codex子目录里，比如~/.codex/superpowers或~/dev/superpowers。如果你同时在多台机器同步配置，我建议固定一个位置，并在配置里写绝对路径，避免“这台机器能加载，另一台加载不上”的诡异现象。

git clone --depth 1 <superpowers仓库地址> ~/.codex/superpowers

命令里的<superpowers仓库地址>换成你从项目主页复制的真实地址。--depth 1只拉最新版本，技能包这类项目的历史提交对日常使用没意义，能省时间和磁盘。

拉下来之后别急着配置，先花十分钟看目录结构。通常会有几个明显的部分：skills目录存放各类技能提示词，scripts目录放辅助脚本，还有 README 和示例配置。先读 README 和示例配置，它会告诉你哪些字段是必需项，哪些是可选增强。

这里额外提醒一句：不要盲目把示例配置整体复制。如果你已经有自己的 Codex 配置文件，直接合并很容易出现重复字段，后面我会专门讲怎么合才干净。

2.3 最简配置：先让 superpowers 被 Codex 看见

配置入口是 Codex CLI 的 config 文件，路径通常在~/.codex/config.toml。新版本也可能用目录式配置，取决于你的版本。最简做法是在 config 里把技能目录指过去，让 Codex 启动时能发现它们。

以我用的版本为例，config.toml里需要有一段类似这样的内容，具体字段以你本地 README 为准：

[profiles] [profiles.superpowers] skills = ["/Users/你的名字/.codex/superpowers/skills"]

配置完并不代表马上生效。Codex CLI 一般启动时才读取配置，所以你要退出当前会话再重新进入。验证方法很直接：在会话里问它“你有没有加载 superpowers 相关技能”，或者换个更可靠的方式，让它描述当前可用的工作流程。如果它讲得出“计划-实现-验证-修复”这个循环，说明加载成功。

这里有个通用经验：不要一上来就追求完整配置。先让技能被看到，再逐步加命令执行权限、Java 参数这些增强项。分步配置会让你知道到底是哪一步出了问题，而不是整份配置黑盒式地失效，到时候想排查都无从下手。

3. 核心机制拆解：技能会话来龙去脉

3.1 技能包不是插件：加载与执行的边界

很多文章把 superpowers 称为插件，其实不准确。Codex 的插件机制更偏程序化扩展，而 superpowers 主要靠“技能注入”，也就是把一批精心写的提示词放到 AI 的上下文里，让它按照方法论行动。插件是代码逻辑，技能是行为规范。这个区别决定了排查方向：技能没生效，查路径、文件名、加载顺序；插件出问题，查版本兼容和 API 调用。

那为什么技能这种方式有效？因为大模型在对话里即兴发挥时，很容易遵循明确写出来的工作流。就像你给新员工一份 SOP，他照着执行一定比靠猜稳定。superpowers 干的事，就是把项目计划、测试先行、错误修复流程写成极为具体的文本，并设计触发条件：当任务匹配某种场景时，让 AI 优先使用对应技能。

但技能也有边界。它不改变模型本身的推理能力，也不能让 Codex 获得它本来没有的工具权限。比如，AI 能不能执行 git 命令，取决于 Codex 的执行环境和审批配置，而不是技能包里写了“你可以执行 git”。这个误区非常常见，很多人装完发现 AI 还是不能自动跑命令，就开始怀疑技能有问题，其实应该先检查执行权限配置。

3.2 关键配置项解读：照着抄也要知道在改什么

下面这张表整理了我实际用到的几个核心配置维度，不是让你盲目填空，而是理解每一项在干什么：

举一个实际例子：审批策略设成auto后，AI 确实能自主跑命令，但代价是它可能在错误方向执行一堆操作。我的实践是先on-request跑几天，观察 AI 的意图是否靠谱，再决定对哪些命令放开自动执行。一上来就全自动，等于把方向盘完全交给一个还不熟悉你项目的实习生，胆子可以大，但不能这么玩。

配置还有一个容易忽略的点：技能加载顺序会影响 AI 的决策优先级。如果你有多个技能目录，注意看项目文档里有没有排序规则。我自己就经历过两个技能相互冲突，AI 在“先写测试”和“先重构接口”之间摇摆，最后是调整目录命名优先级才解决。

3.3 Java 场景的额外配置：maven/gradle 与 JVM 参数

热词里专门有“superpowers java”，这个组合很常见，因为 Java 项目的编译、测试、依赖管理链路比脚本语言长，AI 更容易在中间断掉。用 superpowers 跑 Java 任务，我建议额外关注三件事：

第一，构建工具选择要明确。项目里同时存在 Maven 和 Gradle 时，AI 不知道该用哪个。你最好在项目说明里写清楚“构建命令是./mvnw test或./gradlew test”，否则它可能随机选一个，然后因为版本差异报一堆莫名其妙的错。

第二，JVM 环境要正确。Codex 执行子进程时，JAVA_HOME和PATH必须可用。常见坑是你在当前 shell 里能跑java，但 Codex 启动的子进程找不到 JDK，报command not found: java。解决办法是把环境变量显式写进启动方式，或者确保 Codex 由同一个配置好的 shell 拉起。

export JAVA_HOME=/path/to/your/jdk export PATH=$JAVA_HOME/bin:$PATH codex

第三，测试日志要控制长度。Java 测试失败时的堆栈很长，AI 上下文有限，最好让技能引导它先抓核心异常，而不是把整段日志贴回去。我见过 AI 因为上下文被撑爆，在同一个错误里反复绕圈，效率极低。Java 项目还有个特点：改完后的验证时间明显长于脚本语言。如果技能里没有“先跑受影响模块的测试，而不是全量测试”的约束，AI 每轮都全量编译，一个任务能跑十几分钟。我自己在技能描述里加了这条规则后，效率提升非常明显。

4. 实操实录：从计划到自测的一整轮

4.1 一个典型的 superpowers 工作流长什么样

下面是我在一个真实项目里跑过的流程。项目是一个简单的 Java 命令行工具，任务描述只有一句话：“给现有命令增加一个--dry-run参数，并补充测试。”

进入 Codex 会话，加载 superpowers 技能后，AI 的表现和裸 Codex 有明显不同。它没有立刻改代码，而是先输出一段计划：先读入口类确认参数解析逻辑，再查配置文件了解现有结构，然后设计 dry-run 模式下的输出格式，最后补测试并运行。这一步就是技能里“计划先行”规则在起作用。

计划确认后，AI 开始改动。因为我在配置里设置了on-request审批，它每次执行命令前都会征求我的同意，我能看到完整命令，再决定是否放行。这个过程虽然多几次确认，但让我对 AI 的操作有掌控感。

你: 给现有命令增加一个 --dry-run 参数，并补充测试。 AI: 计划如下： 1. 读取入口类，确认参数解析逻辑。 2. 查找现有测试结构。 3. 实现 dry-run 模式，不执行实际写入。 4. 添加测试用例并运行 ./mvnw test。 5. 如果测试失败，根据报错继续修复。 是否开始？ 你: 开始。

跑完测试后，如果有一个用例挂了，它不会像裸 Codex 那样停在“已修改完成”，而是把测试输出带回来，定位到具体断言，继续修改并再次运行。这一轮下来，我的体感是：它更像一个会主动汇报进度的远程实习生，而不是一个聊完就走的顾问。

4.2 命令自动执行的授权策略怎么配

很多人装完 superpowers 后最想开的是“全自动”。配置里对应的是审批策略调整，允许 Codex 自动执行命令。但我强烈建议分三档走。

第一档，完全手动。所有命令都要你确认，适合第一次体验，安全但效率一般。你会在确认过程中逐渐了解 AI 习惯执行哪些命令，这本身就是一种学习。

第二档，白名单自动。只允许自动执行低风险命令，比如git status、git diff、测试命令。不同版本的 Codex 对白名单字段写法不同，核心思路是把“只读操作”和“验证操作”放进自动列表，把“写操作”“网络操作”留给人审。

第三档，特定项目全自动。在一个你信任、改动可回滚的仓库里，打开 auto。我的建议是作为兜底，仍在每次会话开始前用git status确认工作区干净，或让 AI 先建一个分支。

下面是一个示意性的白名单写法，不要照抄，要根据你的 Codex 版本调整字段名：

[sandbox] auto_approve_commands = ["git status", "git diff", "./mvnw test", "./gradlew test"]

让我印象很深的一次教训是：我曾在全自动模式下让 AI 重构一个模块，它每完成一步就自动格式化和提交，其中一次提交信息写得莫名其妙。代码虽然没坏，但提交历史很脏，回滚时增加了认知负担。所以我现在坚持：全自动模式也必须在技能里明确要求“每个逻辑变更独立提交，提交信息写清楚”，而不是放任 AI 用fix stuff这类消息。

4.3 多轮自愈循环：遇到失败怎么让它接着修

superpowers 给我的最大价值，是把“失败后继续修”变成了标准流程，而不是靠碰运气。有一次我让它修改一个 JSON 配置，它在循环里连续改了三轮。原因不是模型笨，而是第一轮改完后关联检查工具报了一处命名不规范，第二轮修好这个，另一个文件的引用又没同步，直到第三轮才真正全绿。裸 Codex 很可能会在第一轮后就草率给出“完成”结论。

这个自愈循环能跑通，依赖两个前提。一是上下文里保留报错信息，二是技能里明确写了“未通过验证不得宣称完成”。如果你发现自己用的 superpowers 没有这种坚持，先检查技能描述里有没有类似的强制条款。很多第三方改版为了“听话”，会把这种刚性要求去掉，结果 AI 变得很顺从，但完成质量大幅下降。

真正用起来之后，你会慢慢学会怎么给 AI 留出足够的信息。我发现任务描述里写“如果测试失败，把失败用例和堆栈贴回来再改”比“请修复问题”有效得多。机制一样，但提示词的质量决定了这个循环能转多快。

5. 常见问题与排查技巧实录

5.1 技能加载不上：目录、版本、字段三大元凶

我见过最多的报障是“我配置了但 AI 完全没变化”。按优先级排查三个地方。首先是 skills 路径，检查绝对路径是否真实存在，目录名不能带空格；其次是 Codex CLI 版本，太老或太新的版本对技能配置的读取规则可能有差异，结合项目文档确定版本支持区间；最后是配置格式，TOML 只要缩进或引号错一点，整个配置就会跳过，而 CLI 不一定报错，这一点最阴。

这里有个实用排查技巧：用 Codex 的能力询问功能，直接问它“你有哪些可用技能”。如果它答不出来，问题基本在加载层；如果它能说出来但行为没变化，问题一般在触发条件，也就是实际任务没有命中技能描述。

5.2 审批设了全自动却还是追问：安全策略覆盖问题

另一个常见困惑是：我明明设置了自动审批，为什么执行构建命令时 Codex 还是要问？原因是新版 Codex 的审批策略不止一层，会话内还有附加确认策略，可能限制某些危险命令必须经过人类确认。解决方式不是硬改成 auto，而是先看命令分类，给相关命令追加允许自动执行的规则。

我后来意识到一个更稳的思路：与其追求“所有命令自动”，不如拆分。只读、测试、lint 这类验证命令放自动；文件删除、依赖安装、大规模重构保留确认。这个折中方案既保留效率，又留了一道安全闸。毕竟 AI 自动执行 100 次，只要搞坏一次，成本可能超过之前省下的全部时间。

5.3 自定义技能文件不生效：命名与优先级

当你开始自己写技能文件时，会遇到一个隐藏规则：文件名的前缀会影响优先级或加载顺序。有些实现里数字或字母前缀控制顺序，有的按目录层级决定。你必须严格按示例来，否则技能文件存在，但永远不会被 AI 选中。

我写过一支“提交信息规范”技能，文件名起得很随意，结果 AI 一直没表现出遵守的迹象。后来对照项目示例改成约定前缀才生效。这里也想提醒喜欢深度定制的人：改技能内容前，先跑通一个自带技能，确认基础链路没问题，再加自己的规则。这能大大降低定位成本，不然你会陷入“到底是配置问题还是技能内容问题”的泥潭。

5.4 升级 Codex 后技能失效：接口惯性

最后提醒一个跟使用习惯有关的问题。Codex CLI 自身更新很频繁，某次升级后可能改变技能读取约定，导致以前配置好的环境突然失效。遇到这类情况，不要急着重装，先看项目主页有没有兼容性说明，再查升级日志里涉及技能的部分。

我自己处理过一次：更新 Codex 后，技能在会话里时有时无，最后发现新版要求技能目录里必须有一个索引文件，旧的布局不再被扫描。解决方案不是回滚，而是按新版规范补一个索引文件。玩这类增强项目，这种跟随社区节奏的维护成本是省不掉的，也是和其他普通工具最大的区别。

6. 最后分享一点个人体会

玩 superpowers 这段时间，我最大的体会不是写代码变快了，而是它改变了我和 AI 协作的方式。以前我把 Codex 当成高级搜索引擎，问一句答一句；装上 superpowers 之后，我开始把一整块任务交给它，然后像带新人一样检查它的计划和结果。这种转变带来的效率提升，远超过“改代码速度”本身。

如果让我给刚接触的人一个建议，我会说：第一次配置千万别追求完美。先把技能加载起来，用一个小任务跑通“计划-实现-验证”循环，再逐步开命令自动执行、增加 Java 或其他语言专用配置。很多人在第一步就卡在完美配置上，反而错过了这个工具真正好用的地方。

还有一个小技巧是我后来才养成的：每次任务开始前，让 AI 先读一遍当前加载的技能清单。这个动作看起来多花几秒，但能有效防止会话中途技能失忆，尤其是切换项目类型时非常管用。我目前把这件事当成了使用 superpowers 的标准开场动作，也推荐你试试看。