企业官网建设流程全解析

最近两天“Superpowers”在开发圈刷屏的速度有点快。头一天我还在 GitHub 上刷到这个项目，第二天就有好几个群里在问 codex cli 怎么装 superpowers、Superpowers 如何使用、甚至有人已经在折腾 trae 里能不能装 superpowers skill。这名字起得很直白——它想给 Codex 这类命令行 AI 代理装上一整套“超能力”，让 AI 从一个只会听一句动一句的聊天机器人，变成能自己拆需求、写计划、做测试、重构代码、审查提交的工程助手。我花了两天时间把仓库拉下来，在 Codex CLI 里完整跑通，又把 skills 拆到 AI IDE 里试了试，整体感受是：它比单纯写一段 prompt 要踏实得多。这篇文章不吹不黑，把 Superpowers 是什么、怎么装、底层怎么工作、真实使用中有哪些坑，一次性说清楚，给想上车的人当块垫脚石。

1. Superpowers 解决的核心问题，以及为什么值得装

1.1 从“写一句提示词”到“给 AI 装 SOP”

以前我们让 AI 写代码，本质上是“临时工模式”。每次都要在对话里交代上下文、目标、约束、输出格式，AI 在没有任何流程约束的情况下即兴发挥。结果大家应该都有体会：同一个需求，第一遍可能写得又快又好，第二遍换个说法它就跑偏了；让它改一个函数，它经常顺带把别的模块也动了。问题不在模型不够聪明，而在于你每次都在要求模型“自己摸索一套工作方法”。

Superpowers 的思路很朴素：把成熟工程师做事的流程固化成一份份可复用的“技能说明书”，AI 一旦判断当前任务命中技能描述，就会自动按说明书里的步骤一步步执行。这相当于给新员工发了一本详细的 SOP 手册，而不是每天等他来问“老板，这一步我该干嘛”。整个机制基于 Anthropic 提出的 Agent Skills 标准，用一种叫 SKILL.md 的文件来描述技能，现在 Codex CLI 在新版本里也兼容了这个标准，Superpowers 就是在这个标准之上做了一套覆盖面很广的开源技能库。

我用一个比喻帮你理解：以前的 prompt 像你在餐厅口头点菜，厨师怎么炒全看心情；Superpowers 更像中央厨房的标准菜谱，什么时候下油、几成热、加多少盐，全是固定动作。如果你只是让 AI“写个排序算法”，这个差异不明显；一旦任务是“给一个老项目加个功能并且保证不破坏已有测试”，固定流程的价值就会被无限放大。

1.2 这套“技能体系”能干什么，适合谁

Superpowers 仓库里塞了大量工程场景相关的技能，核心能力覆盖几个方向：需求澄清与方案设计、把宏大任务拆成可执行的小步骤、测试驱动开发、调试排查、安全重构、代码审查、Git 工作流管理。它甚至内置了“planner”“builder”“reviewer”之类的 agent 角色配置，相当于让 AI 在不同阶段切换不同的“人设”：计划阶段像一个谨慎的架构师，写代码阶段像一个高效但不莽撞的工程师，审查阶段又变成一个挑刺的代码评审人。

什么人适合装？如果你平时就在用 Codex CLI 做实际项目，尤其是那种“让它负责一个完整小需求”而不是“让它补一段函数”的场景，你大概率会遇到输出不稳定、越改越乱的问题，Superpowers 值得一试。如果你喜欢让 AI 先写测试再写实现，它会让你非常舒服，因为 TDD 流程被内化成了标准动作。反过来，如果你的使用场景只是问答、翻译、写文案，或者你完全不想让 AI 自动执行 shell 命令，这套东西其实对你没啥用，装不装都行——它天生是给“愿意授权 AI 动手干活”的人准备的。

需要提醒的是，授权 AI 自动执行命令是把双刃剑。技能体系做得越完善，AI 自主性越强，你就越要留意它会动哪些文件、跑哪些命令。我后面会专门讲这部分怎么把控风险，这里先记住一个原则：任何自动化工具，控制权必须留在你手里。

2. 环境准备：在 Codex CLI 中完整安装 Superpowers

2.1 第一步：装好 Codex CLI 并确认版本

安装 Superpowers 之前，你得先有一个能跑起来的 Codex CLI。安装方式我推荐用 npm 全局安装，一条命令搞定：

npm install -g @openai/codex

如果你机器上已经装过旧版本，先升级到最新版再往下走，因为 SKILL.md 和 AGENTS.md 的加载机制是近期版本才完整支持的，版本太老会导致装完 Superpowers 却发现 CLI 根本读不到技能。装完以后执行：

codex --version

看到版本号正常输出了，再执行一次codex进入交互界面。首次使用需要完成登录认证或者配置 API Key，这一步按官方提示操作即可。这里有个实际小建议：不要在装完 CLI 的第一时间就去装 Superpowers，先随便让它跑一个小任务，确认认证、联网、基本对话都正常，再进入下一步。先把地基打牢，后面排查问题会省很多事。

我见过不少人卡在“装完 Codex 之后输入codex没有反应”这类问题上，九成是 npm 的全局 bin 目录没进 PATH。如果你也遇到这种情况，执行npm prefix -g查看全局目录，再把对应的 bin 目录加到 shell 配置文件里，基本上就能解决。

2.2 第二步：拉取 Superpowers 仓库并安装 skills

环境就绪后，找一个合适的目录把 Superpowers 仓库拉下来：

git clone https://github.com/obra/superpowers cd superpowers

拉下来之后先别急着装，我建议你先看一眼目录结构。你会发现里面主要分两块：一个放的是 skills，也就是那些 SKILL.md 技能文件；另一个放的是 agents，里面是像 opcode 这样的角色配置。搞清楚结构之后，你就可以选择自动化安装或者手动安装。

自动化安装很简单，直接跑仓库根目录的安装脚本：

./install.sh

这个脚本做的事情，说白了两件：把 skills 目录下的技能文件复制到 Codex CLI 默认的技能读取目录~/.codex/skills，然后把 agent 相关的配置写进~/.codex/AGENTS.md。如果你习惯手动控制，也可以复制这两条核心命令自己来做：

mkdir -p ~/.codex/skills cp -r skills/* ~/.codex/skills/ cp agents/opcode/AGENTS.md ~/.codex/AGENTS.md

我个人的习惯是先看脚本做了什么再执行，因为开源脚本有时候会顺手改掉一些 shell 配置。这个项目还算克制，主要就是复制文件和处理配置目录。但不管怎样，手动装一次能让你清楚每个文件去了哪里，后面排查问题会更有感觉。

2.3 第三步：验证安装是否生效

装完之后千万别急着开始写代码，先验证一下技能到底有没有被加载。重新启动codex，进入交互对话后直接问它一句：

请列出你当前加载了哪些可用的 skills？你了解 Superpowers 吗？

如果安装成功，它通常会在回答中提到自己掌握了一批技能，比如 brainstorming、writing-plans、test-driven-development 等。这里有个很常见的现象：如果你是在安装之前就打开了 Codex 会话，新装的技能不会自动热加载，退出重进一次就好。

如果想要更确定的验证方式，可以在某个测试项目目录下执行：

codex exec "用一句话总结一下 superpowers 项目里 skills 目录的用途"

如果它能准确回答，说明技能文件已经被读取到了。另外，你在实际项目里使用 Superpowers 时，建议在项目根目录放一个自己的AGENTS.md，Codex 在进入项目目录时会读取这个文件，并把里面的规则注入到对话上下文中。这相当于给每个项目单独交代“本项目有哪些约定”，配合全局安装的 skills，效果会更好。

3. 核心机制拆解：SKILL.md、agent 与 TDD 工作流是怎么运作的

3.1 SKILL.md 里到底写了什么

SKILL.md 是整套机制的核心文件，格式上很接近我们平时写 Markdown 文档，但头部有一段 YAML 格式的元信息，用来描述这个技能的名称、用途、触发条件等。我找一个典型的例子给你拆开看：

--- name: test-driven-development description: 当一个任务涉及实现新的功能或修改现有功能时使用，通过先写失败测试再写实现代码的方式，保证行为可验证。 when_to_use: 用户要求编写新功能、修复 bug、或者需要对现有行为增加测试保障 version: 1.0.0 model: recommended ---

正文部分就是具体的执行流程，通常包含步骤列表、检查清单、以及一些硬性约定。比如 TDD 技能会明确要求：先写一个会失败的测试；运行测试确认是红灯；写最简实现让测试变绿；最后做重构。每一步还会附带“为什么这么做”的解释，让模型理解规则背后的意图，而不是机械照做。

这个设计的妙处在于，模型不是靠“记忆”来遵守流程，而是每一次都从文件里重新读取规则。所以只要你修改了 SKILL.md，下一次执行就立刻生效，不需要重新训练模型。你可以把“技能”理解成给模型外挂的一份知识库：prompt 是一次性传递，会随着对话上下文被冲淡；SKILL.md 则像一本随时可以翻的工具书，AI 在需要的时候去查。

需要注意的是，description和when_to_use这两个字段直接影响匹配效果，它们决定了 AI 什么时候会加载这个技能。写得太宽泛，会导致无关任务频繁误触发；写得太窄，又会导致该用的时候找不到。我在自建技能文件时，会尽量把description压缩在几句话以内，覆盖最常见的触发场景，但不过度承诺能力范围。

3.2 “agent”在 Superpowers 里的角色

skills 负责定义“做什么”，agent 负责定义“以什么角色去做”。Superpowers 仓库里的 agents 目录放了一些配置，比如 opcode 这个 agent，它本质上也是一份 AGENTS.md 风格的规则文件，但内容和全局规则不同——它更聚焦于工程执行的纪律性。当 Codex 以某个 agent 模式运行时，它会把这个 agent 的规则注入上下文，让模型在回答时保持特定的行为风格。

你可以把 agent 理解成给同一个 AI 换“人设”：全局技能是通用的方法论，agent 则是执行方法论时的“行为准则”。比如默认的 Codex 可能更倾向于直接给代码，而 opcode 则被要求“不要急着写代码，先计划、再测试、后实现”。这种角色分离的价值在于，你可以针对不同项目选择不同 agent，而不必每次都在对话里用一大段话去约束它。

实际使用中，我在跑一个小需求时，经常会在对话开头加上一句“请以 opcode 的工作方式处理这个任务”。这句话就像触发开关，AI 会去读取对应的 agent 配置，然后整个执行节奏立刻变得不一样——它会更主动地拆解步骤，更倾向于先展示计划而不是直接甩代码。

3.3 内置了哪些常用技能

Superpowers 仓库内置的技能数量不少，覆盖了从需求到上线的完整链路。我把实际使用频率比较高的几个整理成了表格，方便你对照自己的场景查看：

这几个技能并不是彼此孤立的。实际执行一个任务时，AI 会像人一样按需调用多个技能：先 brainstorming 澄清需求，再 writing-plans 拆解步骤，进入开发后启用 test-driven-development，中途可能穿插 debugging 和 refactoring，最后用 code-review 收尾。这种组合调用能力，才是 Superpowers 比单条 prompt 强大得多的根本原因——它不是给你一个技能，而是给你一套完整的工程方法论。

4. 实操：用 Superpowers 跑通一个真实开发任务

4.1 任务场景与启动方式

理论讲再多，不如亲手跑一遍。我拿一个非常典型的场景来演示：需要给一个 Python 小工具增加一个带 TTL 的缓存装饰器，要求缓存同一个参数的返回值，超过指定秒数后自动失效。

这个任务难度适中，又有明确的测试点——缓存命中、过期刷新、不同参数互不干扰。如果在没有 Superpowers 的情况下让 Codex 直接写，它大概率会直接给你一段装饰器代码。但如果我们用 Superpowers 的流程来跑，整个节奏会很不一样。

启动方式很简单，直接在项目目录下运行codex，然后在对话里给出需求。注意，你不需要自己指定要调用哪个技能，AI 会根据技能文件里的description自动匹配。我实际的输入差不多是这样：

请按照你的标准工作流帮我实现一个带 TTL 的缓存装饰器，要求支持设置过期时间，并且要保证不同参数的调用不会被错误复用。建议先测试后实现。

后面加的那句“建议先测试后实现”，其实只是为了让 AI 更明确地走 TDD 路径。它的技能系统本身就能判断出来，但明确说出来可以降低匹配过程的不确定性。

4.2 从需求到落地方案的执行过程

第一个阶段，AI 没有直接写代码，而是先做需求澄清。它会读取 brainstorming 或 writing-plans 技能，输出类似这样的一段计划：

1. 定义装饰器接口：cache_ttl(seconds) 2. 确定缓存 key 的设计：基于函数名 + 参数值 3. 实现线程安全的缓存读写（可选，取决于目标场景） 4. 先编写测试用例： - 同参数重复调用应命中缓存 - 超过 TTL 后应重新执行函数 - 不同参数应互不影响 5. 运行测试确认失败 6. 实现装饰器逻辑 7. 运行测试确认通过 8. 检查边界情况：如 seconds<=0 时的行为

看到这份计划，你应该能感受到它和我直接让 AI“写个装饰器”时的差别：它先把验收标准定义出来了，后面每一步都有据可依。在这个阶段，AI 还会在计划里注明需要你确认的关键决策点，比如“缓存是否需要线程安全”“装饰器是用于同步函数还是也支持异步函数”。这种“先对齐再开工”的习惯，恰恰是工程中最昂贵也最容易被省略的一环。

确认方案后，AI 会进入测试编写阶段。这一步的输出通常是这样的：

import time from cache_ttl import cache_ttl def test_same_argument_hits_cache(): calls = {"count": 0} @cache_ttl(seconds=10) def add(a, b): calls["count"] += 1 return a + b assert add(1, 2) == 3 assert add(1, 2) == 3 assert calls["count"] == 1

它会明确告诉你：现在运行测试应该是红灯，因为cache_ttl模块还不存在。你可能会问，为什么不让 AI 直接写实现然后一起跑？这正是 TDD 的核心——先让测试失败，才能确认测试本身有验证能力。如果测试一开始就通过，你根本无法判断是代码写对了，还是测试写得太弱、什么都没测到。

4.3 TDD 循环里我在现场看到了什么

确认测试是红灯之后，AI 才会开始写实现。这个阶段它读的应该是 test-driven-development 技能，具体的执行节奏是：写最简实现让当前测试变绿，然后停一下，看有没有明显可以重构的点。以下是我在终端里实际看到的一段执行输出（简化版）：

$ pytest -q _____________________________ test_same_argument_hits_cache ___ test_cache_ttl.py:18: in test_same_argument_hits_cache assert add(1, 2) == 3 E TypeError: 'NoneType' object is not callable 1 failed, 0 passed # 红灯，符合预期

然后 AI 开始补实现代码，再跑一遍测试：

$ pytest -q 3 passed in 0.32s # 绿灯

整个过程中它不会一股脑把所有功能写完，而是每完成一个验证点就跑一次测试。这种“小步快跑”的节奏，在需要保证代码行为可控的场景里非常可靠。跑绿之后的 output 可能会附带一段重构建议，比如“这段缓存 key 的序列化逻辑可以抽成一个辅助函数”。如果它判断当前代码足够清晰，也会明确说“当前实现无需重构”。

这些信号本身的价值很大：它让你知道 AI 每一步在做什么，而不是突然给你一堆代码然后让你自己 review。我在现场最大的感受是：它不急着写功能代码了，而是像一个心里有谱的工程师，先铺路再走车。这种节奏对于测试驱动开发的老手来说很熟悉，但 AI 能主动按这个节奏跑，确实是 Superpowers 给我最大的惊喜。

5. 常见问题与避坑实录

5.1 装完了但 Codex 完全不认识 skills

这是装上之后最常见的挫败场景：明明安装脚本跑完了，问它有哪些技能，它一脸茫然。我先说排查顺序。第一步检查~/.codex/skills目录到底有没有文件，很多情况下是安装脚本执行时机不对，或者用户主目录不一致导致复制到了错误的路径。第二步确认你的 Codex CLI 版本足够新，SKILL.md 功能是老版本不具备的，升级后重试。第三步看~/.codex/AGENTS.md是否存在，Superpowers 的 agent 配置依赖这个文件注入行为规则。

我还遇到过一个很隐蔽的问题：skills 目录下如果有子目录带了中文名或者特殊符号，某些版本的 CLI 解析会直接跳过整个目录。我当时的解决办法是把所有技能目录名改成纯英文小写加连字符，问题立刻消失。另外，如果你在安装之后让 Codex 一直在同一个会话里，它不会自动发现新技能，退出重新进一次是最简单的办法。

5.2 SKILL.md 写错了，没人会主动告诉你

SKILL.md 的格式看起来简单，但容错率没有想象中高。最容易踩的坑有三个：YAML frontmatter 后面没有留空行就直接写正文，这会导致解析失败或整个文件被忽略；description写得过长，超过了模型读取时的有效范围，导致匹配结果飘忽不定；when_to_use写得太抽象，AI 在判断“当前任务是否该触发”时产生了误判。

我的建议是，如果你要自己扩展技能，第一次先别急着写复杂的，从一个只有十几行的技能文件开始，跑通之后再逐步丰富。一个简单有效的自检方式是：修改完 SKILL.md 之后，在 Codex 对话里用一句和你技能描述高度相关的需求去触发它，看它有没有按流程执行。如果没触发，大概率是description写得不够精准或被其他技能的描述覆盖了。

5.3 agent 跑着跑着陷入循环，上下文越吃越多

用 Superpowers 跑复杂任务时，模型可能出现“陷入流程”的问题：计划写了一堆，测试写了一堆，就是迟迟不进入实现阶段；或者在重构时反复修改代码但测试一直没有真正通过。这个不一定是 bug，更像是模型在长步骤执行中的“注意力漂移”。一旦出现这种苗头，我的止血方法是立刻按 Ctrl+C 终止当前步骤，把已经完成的部分保存下来，然后补一句新的指令，比如“停，不要再重写计划了，从第 3 步继续”。

更根本的解决方案是任务一开始就拆得更小。Superpowers 的 writing-plans 技能其实默认就会拆分任务，但如果你给的需求本身跨度过大，比如“帮我重构这个项目并加三个新功能”，再好的 skill 也容易把上下文窗口塞满。我的经验是一个会话只处理一个核心需求，其他需求开新会话做。这样既能避免上下文爆炸，也方便你在每个阶段审查 AI 的输出，不会因为信息过载而漏看风险点。

5.4 在 Trae 这类 AI IDE 里使用 Superpowers 的经验

不少人在问 trae 里能不能装 superpowers skill。我实际试过一种通用方案，核心思路其实很简单：Superpowers 的 skills 本质上是文本文件，只要你的 IDE 支持读取类似 AGENTS.md 的规则文件，并且能在项目上下文中加载外部规则，你就能把它接进去。具体操作上，我会在项目根目录创建一个.codex/skills目录，把当前项目需要的几个技能文件复制进去，然后在项目根目录的 AGENTS.md 里明确声明这些技能的存在。

之所以强调“只复制需要的那几个”，是因为 IDE 的上下文管理方式和命令行 CLI 不完全一样，技能文件太多会占用大量上下文窗口，反而降低回答质量。另外，IDE 里的模型选择、自动执行命令的权限策略和 Codex CLI 是两套体系，首次在 IDE 中使用时，一定要看清它弹出的是不是需要执行 shell 命令的授权。我个人的建议是：先在 Codex CLI 里把某一套 skill 流程跑通，再拿到 IDE 里去用，这样你至少清楚正常流程应该长什么样，出了问题也好判断是 skill 的问题还是 IDE 环境的问题。

最后再分享一个小技巧。我给自己维护了一个“技能清单”文档，记录每个技能文件的上次修改日期和触发测试结论，没事就打开看一眼，保证自己改过的技能都能正常触发。说实话，Superpowers 让我对 AI 编程的预期从“它会写代码”变成了“它会按流程把事做完”。如果你已经装了 Codex CLI，花半小时把这套技能体系跑通，大概率能让你的命令行 AI 助手换一种工作气质。