企业官网建设流程全解析

如果你已经在用 OpenAI 的 Codex 写代码，大概率遇到过这种尴尬：单次对话里它很强，换个新会话就瞬间“失忆”——上回说好的命名规范、测试要求、目录约定，又得从头讲一遍；它默认还不联网，碰到不熟的库只能凭记忆硬编。superpowers 这个开源项目，就是专门补这几块短板的。一句话定位：它是一个给 Codex 装“技能包”的框架，通过插件机制给 Codex 加上可复用的技能（skills）、跨会话的长期记忆（memory）、联网检索与阅读网页的能力。装完之后，你可以把团队的工程约定、常用工作流、问题排查清单，全部写成 Markdown 技能文件，让 Codex 每次开工前自动加载。这篇文章是我从安装、上手到写自定义技能的全过程记录，适合正在用 Codex 但觉得它“不够听话”的开发者，也适合想把团队编码规范变成 AI 硬约束的工程负责人。哪怕你只是好奇“给大模型配技能”这个思路怎么玩，也能从里面捡到点东西。

1. Superpowers 到底是什么：给 Codex 打工的“技能框架”

1.1 先给它定个性：不是语言，不是 IDE，是“插件+技能库”

很多人第一次听到 superpowers，第一反应是“又冒出来一个 AI 编程工具”。真不是。它本身不写代码，也不提供编辑界面，更不绑定某个特定模型，它只是一个跑在 Codex 插件机制上的技能管理框架。

那“技能”到底是个什么东西？说白了，技能就是一个带元信息的 Markdown 文件。文件顶部用 YAML 写清楚这个技能叫什么、干什么用；正文写清楚“当这个技能被触发时，模型应该按哪些步骤执行、要遵守什么约束”。Codex 启动并加载 superpowers 之后，插件会把当前项目里可用的技能清单注入到对话上下文里，模型看到你的任务跟某个技能的描述匹配，就会按技能里的步骤去执行。

这个设计最妙的地方在于：技能不是写死的程序逻辑，而是“给模型的指令手册”。你不需要会写插件、不需要懂底层实现，只要你能把一件事的流程用文字讲清楚，你就能定义一个技能。门槛低到任何能写清楚操作文档的人都能上手，这也是它能被社区快速接受的原因。

1.2 它到底解决了什么痛点

先说 Codex 原生最让我难受的短板，用四个字概括就是：记、查、规、攒。这四个字分别对应四类问题，也是我后来决定给 Codex 加装 superpowers 的核心原因。

• 记：Codex 没有跨会话记忆。上午跟它约好“日志一律用 SLF4J”，下午开新会话它就忘了。所有约定都得靠人肉重复，项目一忙就乱，有时候连自己都记不清上次到底约定过什么。长期来看，这种“每次从零开始”的体验，跟“雇了个懂编程但失忆的实习生”没什么两样。
• 查：Codex 默认不联网。不认识的库、新出的 API、私有文档，它只能靠训练数据里的印象去猜。训练数据是有时间边界的，猜错了就是编造。对大项目来说这是致命伤，因为一个废弃方法的误导成本，往往比从零开始查文档高得多。
• 规：每个项目都有自己的约定。包结构、命名规则、异常处理方式、测试风格，这些没法塞进一条 Prompt 里，塞进去也占上下文，而且每次都要重新塞。更有意思的是，这些约定往往只有团队里待得久的人才知道，新人根本无从下手。
• 攒：真正的经验应该越用越多。你今天用 Codex 排查完一个诡异的线上问题，这份排查过程有没有沉淀下来？原生 Codex 不会帮你沉淀。下次遇到同一个问题，它照样从头开始猜，你之前踩过的坑它一个都记不住。

superpowers 的思路，就是把“记、查、规、攒”这四件事分别做成能力模块，用技能去承载，用记忆去存储，用联网去补齐信息，最后让所有经验都落到 Markdown 文件里，变成可以版本管理、可以复用、可以分享的东西。我在团队里推广后最直观的感受是：新会话的 Codex 不再是个“懂编程的陌生人”，而是个“读过团队手册的老员工”。

1.3 适用人群边界

什么人不适合用？我先把丑话说在前面。如果你只是偶尔拿 Codex 跑个脚本、写个一次性代码片段，superpowers 对你来说太重了，装完你大概率觉得“就这”。它的真正价值要在持续进行的项目里才体现得出来。另外，如果你所在的公司对第三方插件有严格的合规审查，尤其是对数据流向要求不清晰的环境，别急着装，先让安全团队把插件的行为审一遍。这类框架会往模型上下文里塞额外的提示词、可能在本地读写文件，合规红线要先确认。

什么人强烈建议试？两类。第一类是重度使用 Codex 做真实项目的开发者，你已经被“重复交代背景”折磨过，装完会有一种“早该如此”的感觉。第二类是带团队的工程负责人，你可以把代码规范、评审要求、构建流程全部固化成技能文件，放进 Git 仓库，团队每个人拉下来就是一套统一的“AI 行为准则”，新人也跟着受益。

2. 核心设计拆解：为什么“技能即 Markdown”这条路走得通

2.1 技能的本质：给模型一本“操作手册”

我们直接看一个技能文件长什么样，这是我实际项目里的简化版：

--- name: maven-build-check description: Use when Maven build fails, to diagnose and fix compilation errors step by step. --- # Maven 构建排查 1. 先运行 `mvn -q compile -DskipTests` 复现错误。 2. 只看第一处编译错误，不要尝试同时修多个问题。 3. 定位到具体文件和行号后，先说清楚原因，再动手改。 4. 改完重新编译，确认通过后再运行相关测试类。 5. 如果连续三次修复失败，停下来向用户说明现状并请示。

看到没，技能文件干的事，就是把你平时“希望 AI 按这个套路干活”的话，变成一份结构化文档。YAML 里的 name 和 description 是给模型做匹配用的，正文才是它真正执行的步骤。

这里有几个关键点值得单独说一下。第一，description 一定要写成“模型一眼能判断什么时候该用”的句式。模型不会把每个技能全文都读一遍，它拿到的是技能清单，靠 description 来匹配。你写“关于 Maven 的说明”，模型看了也白看；你写“Use when Maven build fails”，它立刻知道触发条件。第二，正文步骤要具体到可执行，像“看看哪里错了再改”这种话等于没写。第三，技能步骤不要贪多，一个技能聚焦一个场景，宁可拆成两个技能，也不要写成一个大杂烩。

2.2 记忆系统：让 Codex 不再是金鱼

记忆功能我刚上手的时候觉得没啥，用了一周才发现是隐藏的重点功能。它的机制分两层：短期记忆服务当前会话，长期记忆跨会话持久化。长期记忆存储在本地文件里，Codex 每次启动时可以读取和更新。

实际用法是这样的：你在对话里说一句“记住：我们项目的数据库表名一律小写下划线，禁止驼峰”，模型配置正常的话，就会调用记忆相关技能把这条规范写进长期记忆文件。下次新会话它读到这条记忆，自然就遵守了。我习惯每隔一段时间就翻一下记忆文件，清理过期的、合并重复的，避免时间长了堆积成垃圾场。

需要提醒的是，记忆不是自动发生的。模型不会主动把每次对话都存下来，它需要被技能指示“什么内容值得记”：团队规范、命令习惯、关键决策，这些都是值得记的；你把“今天午饭吃了啥”告诉它，它也会傻乎乎存下来，那就纯属浪费上下文。

2.3 联网检索：从“写代码”到“查资料+干活”

web-research 是我另一个离不开的技能。它让 Codex 能够根据关键词发起搜索、抓取网页内容、提取正文，再把结果作为上下文带给模型分析。对我来说最大的应用场景是：让 Codex 去查某个依赖库的最新文档，然后按新 API 改代码，这比它凭记忆瞎写强太多了。

但这里有个使用边界要讲清楚。web-research 能拿到的是公开网页内容，内部文档、需要登录的系统、动态渲染的页面它大概率抓不到。所以别拿它去查你们公司的内部 Wiki，也别指望它能读某个需要复杂认证的系统。另外，搜索到的内容不代表权威，模型很容易“看着像就信”，你最好在技能里加一条约束：“引用外部信息时必须标注来源和日期，拿不准就明说不知道”。

2.4 功能对比：装 superpowers 前后的 Codex 差别有多大

我用一张表复盘一下装 superpowers 前后的差异，方便你判断值不值得花这半小时：

看完这张表你应该能理解我为什么说它“值得半小时”：它相当于把原来每次开工前都要做的“背景交代”，一次性做成了基础设施。后面所有会话都在吃这套基础设施的红利。

3. 安装与初始化：从零到能跑通，全程实操记录

3.1 前置条件：Codex CLI 装好没有

superpowers 是 Codex 的插件，所以前提是本地已经装好 Codex CLI，并且能正常对话。装好之后先敲一下命令确认环境：

codex --version

如果这条命令报 not found，先去把 Codex CLI 装好再来。不建议在没有确认基础环境的情况下直接装插件，否则后面排查问题会多一层干扰。顺便说一句，我装的时候用的是较新的 Codex 版本，如果你手里的版本比较老，插件机制可能不完整，建议先升级。

3.2 安装插件：一条命令的事

安装本身很简单：

codex plugins install superpowers@latest

这个命令会把 superpowers 插件拉取并注册到 Codex 的插件体系里。安装过程一般很快，如果网络状况不好，可能要等一会儿。装完后可以用下面的命令确认它能被识别：

codex plugins list

能看到 superpowers 在列表里，就算装上了。这里有个小建议：安装前先看一眼官方仓库的 README。这类工具迭代很快，今天的命令可能明天就变了，以官方文档为准永远是最稳妥的做法。

3.3 初始化：codex superpowers 干了什么

装完插件还不算完，还要初始化：

codex superpowers

我第一次跑这个命令的时候，它做了几件事：创建了技能目录、往我的 Codex 配置目录里写入了一套默认技能、在当前项目目录生成了一个 SUPERPOWERS.md 文件（相当于技能索引，里面列出当前可用的技能清单和一句话描述），还问我要不要修改一些配置项。不同版本的交互细节可能不一样，比如中间可能会问你是否要开启某个功能，我建议第一次全选默认，跑通之后再去调。

这里有个容易忽略的点：SUPERPOWERS.md 是 Codex 上下文里实际加载的那份清单。每次启动 Codex 时，它通过这个文件知道现在有哪些技能可用，再按需去读具体技能文件。所以这个文件很重要，最好别删，也别随手改坏格式。

3.4 验证安装是否成功

初始化完成后，我习惯做三步验证。第一步，查看技能目录结构，确认内置技能已经落盘：

ls ~/.codex/skills

第二步，打开项目目录下的 SUPERPOWERS.md，看一眼技能清单是不是完整。第三步，启动 Codex，直接问一句：“你现在有哪些技能可以用？分别什么时候用？”如果模型能列出 skill-editor、memory、web-research 等技能并说清用途，说明 superpowers 已经在上下文中生效了。如果模型一脸茫然，多半是初始化没跑完，或者你启动 Codex 的目录跟生成 SUPERPOWERS.md 的目录不一致，后面排查章节会细说。

4. 核心技能逐个拆解与实战用法

4.1 skill-editor：造技能的技能

superpowers 内置了一套“元技能”，其中 skill-editor 是我用得最多的。它的作用就是帮你创建、修改、审查技能文件。我一般这么用：直接跟 Codex 说“我想写一个技能，功能是 XXX，帮我按 superpowers 的规范生成一个技能文件”，它会自动调起 skill-editor，生成带 YAML frontmatter 的 Markdown，还会提示我放在哪个目录。

生成之后不要直接就用，一定要做两步人工检查：一是检查 description 的触发条件写得够不够清楚，二是检查正文步骤是不是可执行。我自己犯过的错是让 skill-editor 一次帮我写三个技能，结果每个都写得很泛，后来改成一次只写一个、写完立刻实测，质量立刻上来了。记住：skill-editor 是提效工具，不是免责工具，最终质量责任在你。

4.2 memory：记忆的正确打开方式

再说说记忆的正确用法。长期记忆不是让你把整个项目文档都塞进去，那就把上下文撑爆了。我的经验是只记四类东西：长期有效的项目约定、用户明确说过的偏好、反复出现的技术决策、以及那些“你花半小时才查明白”的关键结论。

用的时候也有技巧。想让 Codex 记住一件事，说清楚是“长期还是本次会话”：“记住（长期）：我们项目禁止使用 System.out.println 打日志”比含糊地说“记住啊”要好得多。查询记忆的时候同样要具体，比如“我们之前对数据库迁移是怎么约定的”，模型会去检索记忆文件而不是凭空编一个。最后，记忆文件要定期清理。我见过有人把记忆当垃圾桶，堆了几百条，结果每次会话都要读一堆无用内容，反而拖慢了响应。

4.3 web-research：联网查资料的正确姿势

web-research 适合干的事我排个优先级：查库的最新文档、查某个 API 的用法示例、确认某个技术方案是否可行、调研同类项目的做法。不适合干的事：查内部系统资料、抓需要登录才能看的内容、看动态渲染的复杂页面。

在使用上我有一条硬性要求，写进了项目技能里：“所有来自网页的信息，必须给出来源 URL；如果网页内容与已有知识冲突，以网页为准但要说明差异。”这么做的好处是 Codex 就算引用错了，我也能顺着来源去核，不会把错误信息一路带进代码里。

4.4 其他基础技能：plan、git-workflow、thinking 要不要装？

superpowers 还附带了一些基础技能，比如 plan（先做计划再执行）、thinking（复杂问题先展开思考再回答）、git-workflow（按规范流程操作 Git）。我的观点是：不要全装，按需启用。这些技能本身不是越多越好，每多一个，清单就长一分，匹配的干扰也大一分。

我当时先留了 skill-editor、memory、web-research 三个，外加自己写的两个项目技能。跑了两三个真实任务之后，才决定要不要加 plan 这类流程型技能。这种“最小可用”的启动方式，能帮你更快看清 superpowers 到底解决了什么问题，而不是被一堆功能淹没。

5. 把 Superpowers 用在 Java 项目里：一个完整的实战案例

5.1 为什么单独聊 Java

搜索热词里“superpowers java”热度不低，说明很多人在意它跟 Java 生态怎么配合。这并不奇怪——Java 项目恰恰是最适合技能化的一类项目：约定多（包结构、分层、命名）、样板多（POJO、Mapper、DTO）、构建链路繁琐（Maven/Gradle、测试、打包）。如果你让裸奔的 Codex 去改一个 Spring Boot 项目，它大概率会给你写出“能用但不像团队风格”的代码。有了技能就不一样了，你等于把团队的《开发规范手册》直接放进模型的脑子里。

5.2 场景设定：一个需要约束的 Spring Boot 项目

假设我们接手的项目有这些约定（很典型）：包结构以 com.example 开头，分层严格——Controller 只做参数校验和路由，Service 层写业务逻辑，数据访问走 Mapper；使用 Lombok 减少样板代码；测试用 JUnit 5 加 AssertJ；构建用 Maven，提交前必须编译且测试全绿。

在没有技能的时候，我让 Codex 加一个接口，它可能直接在 Controller 里写业务逻辑、手动写 getter/setter、测试风格跟项目里旧的测试对不上。每次都要我在 Review 阶段反复纠正，非常烦。这个场景就是写技能的完美动机。

5.3 动手写两个 Java 项目技能

我先写一个规范类技能 java-spring-conventions，内容大概是这样的：

--- name: java-spring-conventions description: Use when writing or modifying Java code in this Spring Boot project. Enforces layering, naming, Lombok usage and exception handling conventions. --- # 项目 Java 编码约定 - 包名前缀统一为 com.example，新增类必须先放在正确的子包下。 - Controller 只做参数校验、路由和响应封装；业务逻辑一律在 Service 层。 - Service 接口定义方法，Impl 类实现；禁止在 Controller 里直接操作 Repository。 - 使用 Lombok 的 @Data / @Builder / @Slf4j，禁止手写 getter/setter。 - 日志使用 @Slf4j 的 log，禁止 System.out.println。 - 异常：业务异常抛自定义 BizException，禁止裸抛 RuntimeException。 - 方法命名：查询用 get/find 开头，新增用 create/add，修改用 update，删除用 delete。

然后是构建与测试流程技能 maven-safe-build：

--- name: maven-safe-build description: Use after modifying Java code to verify the build and relevant tests. Run compile first, then targeted tests, then full build if time permits. --- # Maven 构建与测试流程 1. 运行 `mvn -q compile -DskipTests`，确保编译通过。 2. 针对改动的类，运行相关测试：`mvn -q test -Dtest=XXXTest`。 3. 若失败，先阅读第一处失败信息，定位原因后再修复，禁止盲目反复重跑。 4. 相关测试通过后，如果改动涉及公共层，再跑 `mvn -q test` 全量回归。 5. 任何一步失败，都要停下来向用户说明失败原因，而不是绕过测试。

这两个技能文件就是团队的硬约束。放在项目的技能目录里，All 就绪。

5.4 实测过程：让 Codex 按技能干活

技能文件放好后，我重启 Codex（确保新技能被加载），给了一个真实任务：“在 UserService 里增加一个根据邮箱查询用户的方法，并补一个测试。”然后观察它的行为。

没加技能之前，它可能会在 Controller 里顺手写查询逻辑、用 JPA 的 findByEmail 直接在接口里定义、测试类里用 System.out 打印结果。加了技能之后，它明显先检索了 java-spring-conventions，然后给出的代码：Controller 只暴露端点、Service 接口加方法、Impl 里实现、用 Optional 处理查不到的情况、测试用 AssertJ 断言、日志用 @Slf4j。代码风格跟项目完全一致，我 Review 起来几乎不用改。

这个对比让我很受触动：不是 Codex 写不了符合规范的代码，是你没给它规范。superpowers 的价值就是让规范的传递不再是每次对话前的一段临时提示词，而是项目的一部分。

5.5 把技能沉淀为团队资产

技能文件是可以进 Git 的。我把这两个技能文件放到一个 skills 目录，并在项目的 README 里写了说明：“用 Codex 干活前先确认技能已安装。”新同事拉到项目，初始化一下 Codex，就自动获得整套团队 AI 行为准则。后面再有人发现 Codex“不听话”，第一反应不是改提示词，而是看技能哪里写得没覆盖到，然后更新技能，所有人同步受益。

这个过程其实就是在把“隐性经验”变成“显性资产”。你可以把它类比成原来团队里的《开发规范文档》，只不过这份规范不是给人看的，是给 AI 看的，而且 AI 真的会执行。

6. 常见问题、避坑指南与排查思路

6.1 安装与初始化问题速查

我整理了一张表，覆盖我见到过的大部分问题：

6.2 运行时的典型翻车现场

翻车现场一：技能加载了，但模型不按技能走。我遇到过 Codex 明明看到技能清单，还是自顾自地回答。后来发现原因是我把技能描述写得太泛，任务描述又多又乱，模型选择了自由发挥。解决办法：任务描述写清楚点，或者在对话里直接指定“按 xxx 技能执行”。

翻车现场二：记忆写崩了。有一次我让 Codex 记住的东西太多，包括一些临时任务，结果后面每次对话它都要读一堆没用的长期记忆，响应又慢又容易跑偏。后来我养成习惯：每周日花十分钟清理记忆文件，把过期的、临时的、已经失效的条目删掉。

翻车现场三：联网查出来的资料是过时的。web-research 搜到一个博客讲的是旧版 API，Codex 信了，写出来的代码用到已废弃的方法。这就是为什么我坚持在上面提到的技能里加“必须标注来源和日期”。信息带来源，你才能核、才能纠。

6.3 这个月踩过的坑，希望你别再踩

最后说几个最有代表性的坑。第一个是“技能描述用词太文艺”。我最早写的一个技能描述是“帮助处理项目中遇到的常见问题”，结果模型根本不知道什么时候该触发；改成“Use when the user reports a build failure or test failure in the Maven project”之后立刻精准命中。触发条件要写场景，不要写能力。

第二个坑是“一个技能塞了太多东西”。我试图写一个“全流程开发技能”，从建表到部署全在里面，结果模型执行到第三步就忘了后面内容。拆成独立技能之后，每个都短小聚焦，执行完整度大幅提升。

第三个坑是在团队里直接全量推，没给过渡期。有人新装的 Codex 突然“变得不听话”，其实是技能和记忆还没跟他本人磨合好。后来我调整了策略：新成员先装基础技能，用一周顺手了，再根据自己的工作流逐步加新技能。superpowers 这东西，适合渐进式引入，不适合一步到位。

我个人在实际操作里的体会是：superpowers 最值钱的地方不是某一个技能，而是它逼你把“想让 AI 怎么干活”这件事想清楚了。技能写得越具体，Codex 干活越可靠。如果你还在观望，我建议先花二十分钟装起来，写一个你最头疼场景的小技能，跑完一个真实任务再下结论。这个投入，大概率不会亏。