企业官网建设流程全解析

1. 先搞清楚superpowers到底解决什么问题

先说结论：superpowers是一个给Codex CLI加技能的插件包，让AI从“你问一句它答一句”的被动助手，变成“你说个目标它自己规划、写测试、跑测试、修bug”的主动执行者。因为Codex CLI本身只是个跑在终端里的AI编程助手，你给它一个提示词，它生成代码，但缺少一套稳定的工作流来约束它“先干什么、后干什么、干到什么程度算完”。superpowers正是补齐这一环的。

我第一次用的时候，心里想的是“这玩意儿是不是又是给提示词套了个模板”。实际用下来发现不是。它把编程这件事拆成了几个核心技能：规划、测试驱动开发、调试、读代码、写文档，每个技能都配了完整的提示词脚本和决策树。Codex拿到这些脚本之后，行为模式会明显变化——它不再急着写代码，而是先问清楚需求边界，再列方案，然后先写失败测试，再让测试变绿。这个顺序本身就是专业开发者日常最稳的工作流。

什么人适合用这个？如果你已经在用Codex CLI写代码，觉得它生成的代码质量不稳定、经常跑偏，或者你想让AI在一个老项目上改东西却担心它不熟悉上下文，那superpowers值得一试。如果你完全没接触过Codex CLI，也没关系，前面先花几分钟把基础环境装好就行。

这套东西不是给AI换了个大脑，而是给AI换了一套工作方法。模型还是那个模型，但有了“技能”之后，它会主动调用规划、测试、调试这套流程，相当于你给一个聪明但毛躁的新人配了一份操作手册。这也是我推荐它的核心理由——不是模型变强了，是流程变规范了。

1.1 从Codex CLI说起

Codex CLI是OpenAI推出的开源终端工具，本质是个命令行版的GPT编码助手。相比在网页里聊代码，它的优势在于可以直接读写你本地文件、执行终端命令、跑测试、看报错结果，然后基于结果继续工作。它相当于给了模型一双“手”，让AI能真正操作项目。

打个比方：网页版AI像一个顾问，你给它看代码片段，它给你建议，然后你自己动手改；Codex CLI像一个远程实习生，你给它一个任务，它自己在电脑上翻文件、改代码、跑命令，然后把结果汇报给你。

Codex CLI本身有基本的Agent能力，能自主执行多步操作，但它缺少“工作规范”。一个新手实习生最可怕的地方不是不会干活，而是以为自己会干，然后闷头写出一堆不在点上的东西。superpowers做的就是给这个实习生一整套SOP：接到任务先确认需求，然后做影响面分析，再写方案，方案你确认了才动手，动手时坚持测试先行，出了错按步骤定位而不是瞎猜。

1.2 superpowers的核心设计理念

superpowers这个项目在GitHub上开源，作者是Jesse Vincent（此人是Perl社区的老将，也是K-9 Mail的开发者）。它的核心思路是把“提示词工程”从一次性、不可复用的状态，升级为一套结构化、可组合、可维护的“技能系统”。

每个技能包含两部分：一是SKILL.md，用Markdown写的操作手册；二是配套的脚本文件，比如测试项目结构、执行回归测试、处理特定技术栈的逻辑。Codex在启动时会加载这些技能定义，根据当前任务自动决定调用哪个技能。注意，这套决定机制不是硬编码的if-else，而是靠Codex自身的模型理解力+技能文档里的指令约束共同完成的。

我喜欢它的一个原因是这套东西完全透明。所有的技能文件都是纯文本，放在本地目录里，你能直接打开看它到底让AI做了什么。没有黑盒，没有远程服务器调用，这对我这种喜欢掌控全局的人来说非常友好。

1.3 这套技能包到底能做什么

从功能上看，superpowers提供的主要技能包括：

• 需求澄清与规划：任务开始前先问清楚边界和约束，输出可执行的方案。
• 测试驱动开发（TDD）：先写失败测试，再实现，再重构，形成闭环。
• 调试排障：遇到编译错误或测试挂掉，按流程化方式定位根因。
• 读代码/导航：快速理解项目结构和既有代码逻辑。
• 子代理（Subagent）执行：把复杂任务拆给多个并行Agent去研究，再汇总结果。
• 文档生成与维护：从代码生成结构化文档。

这些技能单独拿出来都不稀奇，但组合在一起，效果是“1+1>2”的。最关键的是，技能的调用顺序不是随机的——比如调试技能内部会规定“先读报错信息、再缩小范围、再验证修复”，而不是让AI乱试。

我实测的感受是：用了superpowers之后，Codex的一次性通过率显著提升，尤其是修改老代码、加新功能的场景。因为它在动手前会先读相关文件和测试，做完一步会自动跑测试确认没破坏别的东西，这正是我作为开发者最关心的“别搞坏我的项目”。

2. 安装与初始化：从零到可用的完整流程

安装其实不复杂，但有几个前置条件容易卡住人。我装的时候因为Node版本太老踩了个坑，后面详细说。

2.1 准备工作：Node.js与Codex CLI

先在终端里确认node版本：

node -v npm -v

如果没装或者版本太老（v18以下），建议装一个最新的LTS版本。superpowers对Node版本有要求，太老会直接运行不起来。安装Node的推荐方式是去官网下载或使用nvm（Node版本管理器），nvm的好处是可以随意切换Node版本，避免为单个工具搞乱系统环境。

然后安装Codex CLI：

npm install -g @openai/codex

安装完跑一下codex --version确认成功。注意，Codex CLI第一次使用会要求登录OpenAI账号，终端里会打印一个登录链接，浏览器授权完回到终端继续就行。这个步骤在CI环境里没法做，所以本地先搞定。

提示：如果你之前用过其他AI编程工具（比如AI Studio、Copilot CLI之类），不要混淆。Codex CLI和它们虽然长得像，但插件体系完全不同，superpowers是针对Codex CLI的。

2.2 一键安装superpowers

Codex CLI支持通过codex install安装第三方技能包，superpowers提供了直接安装的入口：

codex install superpowers

这条命令会做几件事：下载superpowers仓库到本地、把技能文件拷贝到Codex的配置目录~/.codex/skills/下面、注册技能元信息。执行完会有“Installed skills”之类的输出，列出一串技能清单，以及哪些技能需要1Password之类的环境依赖。

如果codex install在你的版本里不可用（有些早期版本没有这个子命令），可以走手动方案：直接把GitHub仓库clone到本地，然后把skills目录下的内容软链或拷贝到~/.codex/skills/。

git clone https://github.com/obra/superpowers.git cp -r superpowers/skills/* ~/.codex/skills/

我建议优先用codex install，因为automatic upgrade能力会帮你在每次启动时检查技能更新，手动拷贝的话更新就得自己管了。

2.3 系统检查与技能注册

安装完，运行Codex CLI，照常输入提示词，它会自动加载~/.codex/skills/目录下的技能。如果想确认技能有没有被正确识别，可以在会话里输入“list available skills”，正常情况下它会列出superpowers提供的一串技能名。

注意，superpowers有一个“系统检查”机制：首次运行时，它会检查你的环境是否满足某些技能的前置条件（比如是否安装了esbuild、jest、python3等），不满足的话会在会话开始时提醒你。这不是bug，是它故意设计的——为了保证后面执行技能时不会中途翻车。

2.4 安装时容易踩的坑

我装的过程中遇到过三个比较典型的问题：

第一个是Node版本太老。几年前的系统自带Node v14，跑codex install直接报语法错误。解决方式就是升级Node或者用nvm切到新版本。

第二个是Codex CLI本身版本太低。superpowers要求Codex具有子代理和某些session管理能力，老版本没有这些接口，会出现“技能已安装但行为没有任何变化”的现象。建议安装完codex --version核对一下版本号，早于0.40的老版本最好先升上去。

第三个坑是符号链接问题。我一开始图省事，把skills目录做了个linux软链接指向仓库目录，结果Codex在某些操作时会尝试解析真实路径，然后技能文件找不到。花了一段时间排查。最终方案是老老实实拷贝文件到~/.codex/skills/下，不用软链，一了百了。

注意：如果你用的是Windows环境，路径会有差异。技能目录一般在%USERPROFILE%\.codex\skills下，命令行的体验也会稍弱。能用Linux或macOS的话，体验会好很多。

3. 核心技能拆解：规划、调试与测试

这一章是重点中的重点。很多人装了superpowers但用不出效果，原因就是不了解技能的触发条件，也不知道该怎么配合它。我把几个最常用的技能逐个拆开讲。

3.1 规划技能：先想清楚再动手

规划技能的逻辑很简单：任何需求进来，AI首先要做的是“澄清”，而不是“动手”。Codex会向你提问，比如“这个功能是新增还是替换”“性能指标有无要求”“兼容哪些浏览器版本”等等。回答完以后，它会输出一份简要的规划文档，包含影响面分析、实现步骤、风险点。

这套设计的心理学基础是：模型在上下文信息不完整时直接生成代码，大概率会基于错误假设写出一堆返工的东西。通过强制性的澄清环节，把模糊性前置消灭。

实操上，我建议不要在第一次提问时把所有需求细节都写全，留一点模糊性反而更能触发规划技能。比如你直接说“给用户模块加一个导出功能”，它会追问导出格式、字段范围、权限要求，这些都是你可能根本没想清楚但实际必须确认的点。等它问完了，你再补充回答，方案会比一上来全说明更扎实。

不过注意，规划技能的澄清环节有时会显得啰嗦。简单的任务（比如“给这个函数加个参数”）没必要走全套规划。好在Codex能根据任务复杂度判断——我碰到的情况是，简单任务它只列个要点，只有大功能才走完整规划。

3.2 测试驱动开发的三段式工作流

TDD技能是整个superpowers里含金量最高的一块。它把“红-绿-重构”的标准TDD循环内化为AI的执行逻辑：

1. 红：先写一个会失败的测试，跑一遍确认失败原因正是“功能缺失”。
2. 绿：以最小改动让测试通过，不允许顺手改不相关的东西。
3. 重构：在测试保护下优化代码结构，消除重复。

每个阶段之间，AI会主动跑测试给你看结果。我实际体验中很大的一个收获是：它写完测试后会跑一次给你看“测试失败”，这个失败不是做戏，是真的因为功能没实现所以失败；然后写功能代码，再跑一次，这次测试过了。整个过程可审计，每一步的输入输出都清清楚楚。

这套流程逼着AI用“可验证”的方式工作，好处是它不会对着空气写代码。测试挂在哪儿，问题就在哪儿，产出的代码质量也因为测试的保护而变得更容易迭代。

需要注意的是，TDD技能默认假设你的项目里已有测试框架。如果是个没有测试基础设施的老项目，AI会先问你“要装哪个测试框架”，或者建议引入一个。别拒绝这个提议——没有测试基础设施，TDD技能根本跑不起来。

3.3 调试技能：让AI自己定位问题

调试技能是另一个干掉我大量日常操作的功能。以前遇到编译报错，我得自己读报错、查文件、猜原因。现在Codex会做这件事：自动读取报错信息里的文件路径与行号，打开相关源码，缩小排查范围，定位到具体函数，再带着修复方案回来。

它的判定逻辑是“基于证据，而非猜测”。调试技能脚本里明确要求AI不得“凭经验猜测”，必须先用读文件、查日志、跑最小复现等手段拿到证据。这个设计非常符合专业调试方法论——大多数调试失败源于“看起来像是XX问题”的直觉驱动。

有一次我在一个Python项目里遇到诡异的AttributeError，Codex顺着调用链找到原因是一个装饰器改变了函数签名，修复方式也合理。如果换我自己来查，得花十分钟；用superpowers后，整个定位修复加验证不到三分钟。

3.4 读代码与文档技能

这个技能适合刚接手不熟悉的项目场景。你给Codex一个模块路径，它会自动阅读入口文件、结构目录、关键函数，然后生成一份摘要：这个模块是干什么的、核心依赖是什么、哪些函数是关键路径、有什么历史包袱。

文档技能还能从代码生成解释文档，或者更新已有README。它对维护开源项目特别管用——每次发版前让AI扫一遍新增接口，生成变更说明，能省不少整理时间。

4. 在Java项目里的实战演示

好多人问“superpowers在Java项目里好不好用”，毕竟网上教程大多是围绕Node、Python的。我拿一个真实的Java项目场景走了一遍，把过程拆给大家看。

4.1 为什么Java项目特别适合这套流程

Java项目的特点是：强类型、编译期检查严格、测试框架成熟（JUnit是标配）。这些特性对TDD技能极其友好——因为有类型系统兜底，编译错误就能暴露大部分接口问题；有成熟的测试框架，AI写测试时不太容易迷路。

另外，Java项目的构建工具（Maven/Gradle）给了Codex清晰的“验证路径”：跑mvn test可以看到编译错误、测试失败、覆盖率报告。superpowers在执行TDD循环时，会主动调用这些命令作为验证环节。整个流程就跟资深Java工程师手工干活一样：改代码、跑编译、跑测试。

4.2 一个真实场景：给旧模块加新功能

假设有个Spring Boot项目，里面有个OrderService，我现在要让它支持“批量查询订单状态”。我启动Codex CLI后输入需求，Codex先加载了项目结构：

codex > 查看一下项目的入口结构和OrderService相关的类

它先扫描pom.xml确认依赖，再定位OrderService.java和对应的测试文件OrderServiceTest.java。接下来问了我几个问题：“批量查询的入参是订单ID列表还是订单号列表”“返回结果要保持顺序吗”“空列表怎么处理”。这些问题都是边界情况，直接影响到实现方案。

回答完，它输出了一份简短规划：新增findOrdersByIds方法，复用已有的findOrderById逻辑，避免直接改数据库查询层以降低风险。然后进入TDD循环，先在OrderServiceTest里新增测试方法：

@Test void findOrdersByIds_ShouldReturnOrdersInSameOrder() { // given Long[] ids = {1L, 3L, 2L}; // when List<Order> result = orderService.findOrdersByIds(ids); // then assertEquals(3, result.size()); assertEquals(1L, result.get(0).getId()); }

写完测试，它运行mvn test -Dtest=OrderServiceTest，测试红了（方法不存在导致编译失败），然后把实现补上：

public List<Order> findOrdersByIds(Long[] ids) { return Arrays.stream(ids) .map(this::findOrderById) .toList(); }

再跑一次，测试通过。最后它扫了一遍代码，建议把Arrays.stream(ids)的空值安全处理补上。整个过程，我只需要在几个关键节点回应它的确认，其余时间看着它干活就行。

4.3 技能包是如何处理编译与依赖的

在Java项目里，最大的风险是依赖解析和编译环境问题。Codex会自动调用mvn dependency:resolve或gradle dependencies来确认依赖是否就绪。如果编译报错是因为缺少某个依赖，它会尝试在pom.xml里加对应坐标，然后重新编译验证。

这里注意一个细节：如果项目用的还是Java 8或老版本Spring，Codex需要准确的JDK环境信息才能给出对应代码。最好在项目根目录放一个.codex.md文件（Codex的项目级说明文件），写清楚JDK版本、构建命令、测试命令、包结构约定。这样Codex不会在环境信息上浪费上下文窗口，直接进入干活状态。

4.4 Java项目的注意事项

我在Java项目里还遇到过一个典型问题：项目里有大量生成的代码（比如MapStruct生成的实现类），Codex有时会误读这些生成文件，把不存在的类当作真实实现。解决办法是在.codex.md里明确排除target/、build/等目录，或者给Codex强调“生成代码不要读、不要改”。

另外一个点是Java项目的测试命名规范。superpowers的TDD技能默认按“given-when-then”风格写测试，和常见的JUnit命名习惯兼容性不错，但如果你的项目用的是别的命名风格，建议在.codex.md里写清楚，AI会遵守项目约定。

5. 常见问题与排查实录

这里把我自己和朋友安装使用过程中踩过的坑集中整理一下，按问题出现频率排个序。

5.1 superpowers命令找不到

常见原因有两个：Node版本太老导致安装脚本失败；~/.codex/skills/目录权限不对。排查步骤：

1. 执行npm ls -g --depth=0确认@openai/codex已安装。
2. 执行codex --version确认CLI能正常运行。
3. 检查ls ~/.codex/skills/是否有内容。
4. 确认技能目录权限是当前用户可读。

如果是权限问题，chmod -R u+rX ~/.codex/skills就能解决。

5.2 技能没有被加载

Codex没有输出“Available skills”或行为上跟没用superpowers一样，常见原因：

• Codex CLI版本太旧，不支持skills目录。
• 技能文件放在了错误位置（比如放到了~/.codex/agents而不是skills）。
• 技能文件名不符合规范（superpowers要求每个技能有SKILL.md文件）。

检查方式很简单：在Codex会话里输入“what skills are available”，如果回答说没有技能，基本就是目录或版本问题。更新Codex后重新跑一次codex install superpowers通常能解决。

5.3 Codex CLI卡在审批环节

这属于new bing界面体验层面上的问题，很多人反馈Codex会“一直等用户确认”。原因是在auto模式下，Codex每执行一条命令都会询问用户是否允许。如果你对它比较信任，可以切换为full-auto模式（在~/.codex/config.toml里配置model_agent="full-auto"），让它做完一整个流程再汇报。不过我不太推荐盲目全自动，遇到会删文件或改权限的命令还是要停下来看看。

5.4 上下文窗口不够用

如果任务复杂，Codex会读入大量文件内容，把上下文塞满。症状是它开始“遗忘”早期信息，或者行为变得混乱。解决办法：

• 把需求拆小，分多次会话做。
• 在.codex.md里精简项目说明，减少重复扫描。
• 用codex workshop清理或开启新会话。
• superpowers的Subagent技能可以把大型调研任务拆出去，主Agent保留核心决策，减少上下文压力。

5.5 模型选择问题

Codex CLI支持多个模型，superpowers在GPT-5类模型上表现得更好，因为技能的执行依赖模型的指令遵循能力和多步推理水平。如果你用的是免费的旧模型，会感觉技能经常执行不到位——不是superpowers的问题，是模型理解力支撑不住这么复杂的提示词。建议至少使用带“agent”能力的模型，测试下来效果更稳定。

6. 一些实操心得与扩展玩法

最后聊点我在实际使用中的真实感受，以及怎么把这套东西用得更好。

第一个心得是：别迷信“一键全自动”。superpowers强是强在“它知道每一步该做什么”，而不是“它能完全替代你”。它不会替你确认需求，业务判断和验收最终还是要自己来。与其让它全自动跑一个半小时，不如在关键决策点插进来看看它准备怎么做，这样最终效果最稳。

第二个心得是：一定要在项目里维护好.codex.md。这个文件相当于你给AI写的团队新人手册。项目用什么构建工具、测试命令是什么、包结构有什么约定、哪些目录不能动、有没有特殊编码规范——写清楚之后，superpowers的技能执行准确度会明显上一个台阶。没有这个文件的维护意识，AI再强也是在盲人摸象。

第三个心得是：技能本身是可以改的。superpowers的SKILL.md是纯文本，你觉得TDD流程里“跑测试前先让我确认一下”太多了，可以直接删掉那一步；你觉得调试技能里“必须先写最小复现”太严格，也可以注释掉。我改过一次，把公司内部统一用的代码规范写进了PLANNING技能的前置检查步骤，效果立竿见影。

顺便回答一个最近不少人问的话题：worbuddy这类工具怎么使用superpowers。其实核心机制是一样的，大多数CLI封装都遵循Codex的skills目录加载逻辑，你只要找到工具内部的config目录，把superpowers的skills文件放进去，然后调用方式参考该工具的skill激活指令即可。但不同工具对SKILL.md格式的支持程度不同，有的工具只认简版技能头，需要你把技能文件里的extended部分去掉或改造一下，这个就看具体工具的实现了。

总的来说，superpowers对我来说最大的价值不是某个单一功能，而是它把AI编程从“随机生成代码拼运气”变成了“有流程、有验证、可追溯”的工程实践。每次看到它跑完测试再进入下一步，我心里是有底的，这感觉和以前看着代码飞出来完全不一样。如果你也在用Codex CLI，建议装上它，花半小时跑一个熟悉的项目感受一下，大概率回不去。