企业官网建设流程全解析

1. 先说结论：superpowers 到底是个什么东西

最近在折腾 Codex CLI 的时候，我越来越觉得一个纯对话式的编程助手有点“憋屈”——你让它改个文件，它经常只会给你贴一段代码让你自己粘；你让它跑个测试，它需要你一步步喂命令。直到我在 GitHub 上翻到superpowers这个开源项目，才算是找到了一个比较顺手的解决方案。

简单说，superpowers 是一套专门给编程 AI（目前主要适配 OpenAI 的 Codex CLI）扩展能力的技能包系统。它不改变模型本身，而是通过预置的一大批“技能定义”和配套脚本，让 AI 在终端环境里拥有更强的自主操作能力：比如多文件批量修改、独立子任务并行执行、写规范的 Git commit 信息、做深度的代码审查、运行测试并自动修复报错等等。你可以把它理解为给 AI 助手装了一整套“外挂工具链”，让 AI 从“只会回答问题”变成“真正能动手干活”。

这套项目特别适合这几类人：

• 日常重度使用 Codex CLI 写代码、改代码的开发者；
• 想让 AI 在终端里自主完成“改多个文件—跑测试—修 bug—提交代码”这条完整链路的人；
• 想自己定义一套技能、让 AI 按团队规范做事的人（比如统一 commit 格式、统一代码风格检查流程）。

我实际用了一段时间，最大的感受是：它把 AI 从“一对一问答”变成了“可以并行指挥多路小工”的协作模式。下面我把整个项目的设计思路、安装步骤、核心机制、自定义技能的方法，以及我踩过的坑，全部拆开讲一遍。

2. 项目核心思路拆解：为什么 AI 助手需要“技能包”？

2.1 纯对话式 AI 编程助手的局限

先聊聊背景。用过 ChatGPT 或 Claude 写代码的人应该都有体验：你让 AI 输出一段代码，它确实能写得很像样，但一旦涉及“打开 config 文件，把第 37 行的端口号改掉，然后重启服务验证一下”这种具体操作，它基本只能给出操作步骤，不能真的执行。原因在于模型本身没有终端权限，也不具备“感知当前项目结构”的能力。

Codex CLI 解决了部分问题——它能执行命令、能读文件,但官方默认的行为模式还是比较保守的：AI 倾向于用对话解释来代替实际操作，经常做一步问一步。这在复杂任务面前效率很低，尤其是在项目里有几十个文件互相引用时，AI 经常“只见树木不见森林”。

2.2 superpowers 的解法：把“能力”结构化

superpowers 的核心思路特别朴素：既然模型本身能力够了，那缺的其实是“操作规范”和“可复用的执行框架”。于是项目作者预先撰写了一大批技能文档（Skill 文件），每一个技能文档里都写清楚了：

• 这个技能是干什么的；
• 适合在什么场景下启用；
• 执行任务时应该遵循哪些步骤；
• 应该调用哪些脚本或命令；
• 有哪些注意事项和禁忌。

模型在对话中会读取这些技能文档，然后“按文档行事”。这就像一个新入职的程序员拿到一沓团队 SOP，照着做大家约定的流程，人的智商不需要变，但产出的规范化程度和自主性都会明显提升。

2.3 子代理机制（subagent）是点睛之笔

superpowers 最让我惊艳的设计，是它的subagent（子代理）机制。它允许主会话的 AI 把任务拆分成多个子任务，然后分发给独立的子代理并行执行。每个子代理有自己的上下文窗口，可以独立读取文件、执行命令、返回结果。

用生活化的类比：以前你只有一个 AI 助手，你让它查 A 文件，它看完又去看 B 文件，来回切换上下文，效率很低，而且看多了还容易“忘记”前面内容。superpowers 的做法是，你作为项目经理，把任务拆开——一个子代理去看 API 文档，一个子代理去查数据库 schema，一个子代理专门检查前端代码风格——它们同时开工，最后把结果汇总给你。

这在处理大型重构、跨模块排查 bug 时非常管用。我自己试过一次让 AI 同时分析后端接口和前端调用代码的匹配问题，主代理负责统筹，两个子代理分别查两侧，最后汇总出来的结果相当清晰，比单线程地“一次问一点”高效得多。

3. 快速上手：安装 superpowers 并跑通第一个任务

3.1 前置条件

在开始之前，先把环境要求列清楚。superpowers 目前主要面向 Codex CLI，所以你需要：

• Node.js 18 或更高版本（我用的是 20.x，运行稳定）；
• OpenAI Codex CLI（建议安装最新版，因为 superpowers 会调用 Codex 的子代理能力）；
• 一个能联网的终端环境（mcp 服务器和 GitHub 等操作需要网络）。

如果你还没安装 Codex CLI，先用 npm 全局装一下：

npm install -g @openai/codex

装完以后先跑一次codex确认正常初始化。

3.2 安装 superpowers 本体

官方仓库提供了非常傻瓜式的一键安装脚本，在终端里执行：

npx superpowers@latest install

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

• 创建~/.codex/skills/目录（存放技能文档）；
• 把 superpowers 内置的几十个技能文件复制进去；
• 在 Codex 的配置里注册技能目录的加载路径；
• 还会生成一个SUPERPOWERS.md文件，里面是给 Codex 主代理的“启动说明”。

装完后，你可以用一条命令验证技能是否被正确加载：

codex --list-skills

如果列表里出现apply-debugging-strategies、create-quality-pr、perform-code-review这些技能名，就说明核心技能已经就位。

3.3 第一次实战：让 AI 自主完成一个小重构

装好之后别急着上复杂任务，先跑一个小项目热热身。我的建议是找一个简单的 todo demo 项目，然后用自然语言给 Codex 一个稍微复杂一点的指令，比如：

帮我重构 userService 模块，把数据库访问部分拆到独立的 repository 层，保持接口不变，跑完测试并修复所有失败用例。

注意，这里的关键是你不要手动拆步骤，而是让它自主调用技能去完成。你会在终端里看到 Codex 的完整思考过程——它会先“阅读”相关技能文档，然后规划步骤，接着调用子代理去读取文件结构，再动手修改代码，最后自动运行测试。

我第一次跑通的时候还蛮惊讶的，因为整个过程它几乎没有“走回头路”，一步到位地完成了拆分层、调整 import、跑测试、修断言这一整套流程。

4. 核心机制深度拆解：技能文件是怎么“指挥”AI 的？

4.1 技能文件的结构与加载逻辑

在~/.codex/skills/目录下，每个子目录对应一个技能。以内置的perform-code-review为例，这个目录里一般包含：

• SKILL.md：技能的核心文档，采用 Markdown 格式，前面是 YAML frontmatter（元信息），后面是详细的执行规范；
• 若干.md文件：扩展说明、检查清单、示例等；
• 可选scripts/目录：存放一些辅助脚本，比如自动收集 git diff、解析测试报告等。

SKILL.md的 frontmatter 长这样：

--- name: perform-code-review description: 对当前分支的代码变更进行系统性审查，找出 bug、安全隐患和代码风格问题。 allowed-tools: read_file, grep, run_command, run_agent ---

description字段非常重要，因为 AI 主代理会根据这个描述来决定“什么时候该调用这个技能”。所以描述越具体、越能对应真实场景，技能被正确触发的概率就越高。这也是自定义技能时需要重点打磨的地方。

4.2 主代理是如何“学会”使用技能的？

superpowers 在安装时会往SUPERPOWERS.md里写入一段引导说明，Codex CLI 在启动时会自动把它注入到主代理的上下文里。这段说明的核心内容是：

• 告知主代理技能目录存放在哪里；
• 要求主代理在接到任务时，先检索是否有匹配的技能；
• 如果有匹配技能，必须先阅读对应的SKILL.md，再按其中的规范执行；
• 鼓励主代理在任务复杂时主动拆分并交给子代理并行处理。

这就是整个项目运作的灵魂——它不是靠模型微调，而是靠上下文工程。你喂给 AI 一套“行为准则”，它就会像一个遵守团队公约的老员工一样办事。

4.3 子代理并行与上下文管理

子代理机制是 superpowers 相对其他 MCP 方案最不一样的地方。在普通模式下，AI 只有一个上下文窗口，所有对话内容都堆在里面，窗口一满它就“失忆”或者开始胡说。superpowers 的做法是：

• 主代理负责拆解任务、分配工作、汇总结果；
• 每个子代理开启一个独立的新会话，只读取自己需要的那部分文件内容，完成后只把结论返回给主代理；
• 必要时可以把子代理再次拆分成“孙代理”，形成树状执行结构。

这种设计带来的直接好处有两个：一是单次任务能处理的文件规模大幅增加，二是因为子代理上下文干净，输出质量往往更高。我实测过一个涉及 40 多个文件的前端迁移任务，单靠主代理一路读文件的话早早就“迷失”了，而拆成 3 个子代理分别处理后，效果好了几个量级。

5. 自定义技能开发实战：让 AI 按你的规范干活

5.1 什么时候需要自定义技能？

内置技能覆盖的是一些通用场景，但在真实团队里你一定会遇到“自己的特殊规矩”需要 AI 遵守。举个例子：

• 你们的 Git commit 信息必须包含需求单号前缀（比如[TICKET-123]）；
• 你们的 ESLint 规则和默认配置不同，AI 不该乱改；
• 你们有特定的部署流程，比如先构建产物再提交到 release 分支；
• 你们希望 AI 在改动代码后必须更新对应的测试用例。

这些场景通用技能不会帮你考虑，但写一个自定义技能只需要十分钟，之后 AI 每次都会自动遵守你的规则。

5.2 从零编写一个“日志分析”技能

我拿自己写的一个技能作为例子，一步步展示怎么创建。假设我希望 AI 在遇到“分析日志文件”的任务时，能够自主完成完整分析流程并输出结论。

第一步，在技能目录下创建文件夹：

mkdir -p ~/.codex/skills/analyze-log-errors

第二步，创建SKILL.md，内容如下：

--- name: analyze-log-errors description: 分析应用日志文件中的错误信息，汇总异常特征，并给出可能的根因与修复建议。当用户提到日志报错、异常排查、分析 log 时使用。 allowed-tools: read_file, grep, run_command --- # 技能说明 本技能用于系统化地分析日志文件中的错误，按以下步骤执行： 1. 先用 grep 或 read_file 确认日志文件路径是否存在，必要时先使用 `find` 查找文件名。 2. 对日志按时间排序，提取包含 ERROR、WARN、Exception、Failed 关键字的行。 3. 对提取出的错误行按关键词聚类，统计各类错误出现次数，找出频率最高的 TOP 5。 4. 对每一类错误： - 结合上下文读取至少 20 行相关日志，确认触发场景； - 推测可能根因（如配置错误、依赖超时、数据为空等）； - 给出修复建议，并附带参考代码片段。 5. 最后输出一份结构化报告，包含错误类别表、统计数量、根因与建议。 # 注意事项 - 不要只罗列原始日志行，必须输出分析结论； - 如果日志文件体积超过 5MB，应使用 `split` 或分段读取的方式，避免上下文溢出； - 不确定的根因请标注“待确认”，不要误导用户。

第三步，把这个技能加载进去。superpowers 会扫描技能目录中所有SKILL.md，所以保存后立刻生效，不需要重启。之后我对 Codex 说“帮我查一下今天 api 服务的日志报错”，它就会自动先检索到analyze-log-errors，读技能文档、按步骤执行。

5.3 自定义技能的几个写作技巧

写技能文档不像写普通文档，它是给 AI 看的操作规程，所以有几个可以明显提升效果的技巧：

• 描述字段里多埋几个触发词。比如“日志”“报错”“异常”“log”“ERROR”，描述里把这些都写上,被正确唤醒的概率高很多。
• 步骤要编号，流程要线性。AI 最擅长的是按顺序执行。如果你写“先按情况 A 处理，再视情况 B 决定是否跳过某步”，它在判断分支时容易迷糊。最好的写法是把它拆成无条件顺序的步骤,或者明确写出 if-then 式判断。
• 每个步骤备注执行命令或读取范围。比如“使用grep ERROR -rn logs/统计错误行”，比干巴巴地写“统计错误”要可执行得多。
• 写清输出格式。我在每个技能里都要求最后输出结构化报告，否则 AI 可能会在回答到一半时就开始“发挥”，输出一些不太严谨的总结。

5.4 带脚本的高级技能：把重复劳动交给脚本

有些技能光靠自然语言指令让 AI 手动执行还是太慢，不如直接让它跑脚本。比如内置技能里有一个create-quality-pr，它就会调用脚本自动拉取当前分支的 diff，生成 PR 标题和描述草稿。

自定义技能时也可以这样：把一段 Python 或 Shell 脚本放进scripts/子目录，然后在SKILL.md里写明“切换到项目根目录，执行python3 scripts/fetch_log_summary.py”。AI 会乖乖照做，然后把脚本输出整理成结论。

这样一来，你的技能就不仅仅是“行为规范”，而成了带执行能力的工具包。我见过有团队把性能分析、依赖安全检查、数据库迁移校验都做成这种技能，团队的 AI 使用效率是肉眼可见地提升。

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

6.1 技能没有触发，AI 还是按普通方式回答

这个是我遇到的最多的一个问题，主要表现为：你明明要求 AI“用日志分析技能处理”，它却完全没检索技能，直接当成普通问题回答了。

排查思路：

• 先确认技能目录位置是否正确。如果~/.codex/skills/下的目录层级不对（比如多套了一层目录），加载会失败。技能路径的规则是skills/<技能名>/SKILL.md，不能是skills/<分类>/<技能名>/SKILL.md（除非该目录本身能被识别）。
• 检查SUPERPOWERS.md是否还在配置的加载路径里。有时候重新初始化 Codex 配置时会把这块覆盖掉。
• 描述字段里的触发词不够准确，导致 AI 不认为这个任务匹配。可以用codex --list-skills查看描述是否成功注入。

6.2 子代理执行时经常“找不到文件”

这是子代理上下文隔离带来的一个副作用。主代理可能知道文件在src/services/user.ts，但子代理新开上下文后，直接拿这个相对路径去读文件可能会失败——尤其是在当前工作目录和项目根目录不一致的时候。

我的解决办法是在技能文档里加一条铁律：“执行任何文件读取前，先调用pwd确认当前目录，如非项目根目录则使用cd <project_root>。”另外，需要跨子代理共享的文件列表，我会在主代理分配任务时显式把完整绝对路径写进任务指令里。

6.3 AI 改代码后测试跑不过，反复修改仍失败

有时候 AI 会陷入“改一个错误，引入另一个错误”的死循环。我观察到的原因往往是它在修改时上下文太短，没有充分理解模块的整体逻辑。建议做法是：

• 在任务描述里专门强调“修改前需调用read_file完整读取目标模块及相关依赖文件（至少 200 行）”，强制它全局了解后动手；
• 如果发现 AI 在连续 2 次修改后测试仍然失败，我会主动中断会话，手动把报错信息和相关文件内容发过去，把它“拉回正轨”。

6.4 与 MCP 工具共存时的冲突

如果你同时配置了其他 MCP 服务器（比如 GitHub MCP、数据库 MCP），偶尔会遇到技能脚本和 MCP 工具“抢资源”的情况。比如数据库迁移脚本被莫名执行了两次。

我的教训是：自定义技能里涉及写操作（写文件、执行命令、改动数据库）的步骤，都加上一句“执行前向用户确认”，让 AI 在关键节点停下来等你点头。这是成本最低、最稳妥的防护措施。

6.5 一个速查表

7. 几个值得单独说说的内置技能

7.1 perform-code-review：让 AI 当一次正式的代码审查员

内置的代码审查技能不是一个简单“挑错”工具，它更像一个严格的评审流程：先拉取当前分支相对于主分支的 diff 范围，再按文件逐个读取变更，分类检查逻辑正确性、性能隐患、安全漏洞和代码风格。最后输出的审查意见带有严重级别标签，比如[S1-Blocking]、[S2-Important]、[S3-Nit]。

我试过在一个不算太复杂的 PR 上跑这个技能，结果它真的找出了一处空指针隐患（我们人审都没注意到），它给出的修复建议更是连具体的代码行列都标好了。现在我的团队已经在 Codex 工作流里加入了“合并前必须由 AI 审查”的环节，虽然听起来有点玄幻，但它确实抓到了几次潜在问题。

7.2 create-quality-pr：把 commit 和 PR 质量拉满

这个技能会先让 AI 查看当前改动涉及的文件，然后用脚本提取git diff概要，再根据改动内容生成一个规范的 PR 标题、描述、变更清单和测试说明。如果你团队有 PR 模板，它还能自动套用模板填写。

它生成 commit message 时也很有讲究——不是简单把git diff草草总结一句“fix bug”，而是按“原因 + 变更内容 + 影响范围”的结构写清楚。团队协作时，这种高质量的提交记录配合普通 Jira/GitLab 都能极大减少沟通成本。

7.3 apply-debugging-strategies：一个包含完整排查流程的“方法论”

这个技能把调试方法论写成了可执行流程：先复现问题 – 采集日志/报错 – 二分定位 – 最小化验证 – 修复验证 – 防回归。它最有价值的地方在于——AI 不会在没复现问题前就瞎猜原因。它甚至会主动建议在代码里埋 log 点来验证假设，而不是直接改代码。这种“严谨”对 AI 来说真的很难得。

8. 个性化配置建议与工作流模板

8.1 我的配置备份清单

如果你打算长期使用 superpowers，我会建议维护以下几类自定义文件：

• 项目级的AGENTS.md：放在项目根目录，Codex 会自动读取，里面写团队约定和模块说明；
• 团队共用的技能包目录：放在~/.codex/skills/下，用 git 管理，推送到内部仓库后同事拉下来就能用；
• 自定义脚本目录：固定在每个技能目录的scripts/里，保证路径约定不被破坏。

8.2 适合日常使用的三条工作流

我日常使用下来觉得这三条工作流性价比最高：

• bug 修复流：让 AI 使用apply-debugging-strategies定位问题，修好后自动跑相关测试，最后调用create-quality-pr生成提交。
• 代码审查流：切到功能分支，输入“用 perform-code-review 审查当前分支”，然后人工复核 AI 给出的审查意见，重点处理 S1/S2 级别问题。
• 跨文件重构流：明确告诉主代理“把模块 A 的划线部分移动到模块 B，保持接口兼容”，子代理会并行读取与修改，最后集中跑全量测试。

8.3 对模型选择和小参数配置的一点思考

superpowers 在较新的模型上效果最明显，毕竟上下文工程再完善，也得模型本身有足够的指令遵循能力。如果你是本地模型或者老版本的 GPT 模型，建议在 Codex 配置中把model参数调成新版模型；如果任务涉及大量子代理并行，需要留意 Codex 的并发任务数配置，适当调低，避免一次开太多子代理导致资源紧张。

写在最后的实际体会

玩 superpowers 这几个月，我最深的感受是：它并没有让 AI 变聪明，但是让 AI 变得更专业了。就像同一个程序员，光有智商但没流程，和拿了 SOP、有工具链、知道什么时候该问人、什么时候该放手做的状态，完全是两种产出质量。

如果你正打算在团队里推广 Codex CLI，我建议先别急着让所有人背命令，先花一两个小时把 superpowers 装好，把团队规范写成三五个技能文件，然后再让成员用自然语言去指挥它干活。这套组合拳打下来，你会明显感觉到 AI 编程助手从一个“问答玩具”变成真正能分担活的队友。

有一个小技巧再补充一下：没事的时候多去看内置技能文件是怎么写的，特别是SKILL.md的步骤设计,它把复杂任务拆解成线性步骤的方式很值得模仿。看完几个之后，你再写自己的技能文档就会顺手很多，触发率和成功率都会有明显提升。