企业官网建设流程全解析

如果你最近在折腾 Codex CLI，多半会碰到一个让人上火的场景：这个号称能独立写代码的智能代理，每开一个新会话就瞬间失忆。你上周花一整天教给它的项目结构、接口规范、测试习惯，它一个都不记得。于是你跟我一样，开始在搜索框里敲"codex superpowers""superpowers 安装""superpowers 使用教程"这些词。我最初也以为 superpowers 是什么玄学配置，装完才发现，它解决的就是这个最痛的痛点：给失忆的 Codex 配上一套"职业技能库"，让它像一位有工龄的老工程师一样干活。

这篇不打算写成官方文档的复述。我会把 superpowers 是什么、怎么装、技能系统怎么运作、怎么在 Java 项目里用起来、以及和其他工具怎么配合，全部按我实际操作下来的顺序讲一遍。你照着做，大概率能在一个小时内跑通第一个自建技能。

1. superpowers 不是模型也不是客户端，它是一套"工作制度"

1.1 为什么纯靠 Prompt 会那么累

Codex 这类 AI 编程代理最大的优点是单次会话里理解能力强；最大的缺点，恰恰是它的无状态。每次新会话，它只知道系统提示、当前目录和你的输入。你项目里的隐性知识——构建命令、代码风格、目录约定、上个月刚踩过的坑——它一概不知道，只能靠你反复粘贴。

我算过一笔账：一个中型项目的"废话上下文"大概有 2000 到 3000 字。每开一次会话就粘一遍，浪费 token 不说，还会稀释真正要改的代码。更麻烦的是，不同项目之间的约定还不一样：A 项目用 Maven 多模块，B 项目是 Gradle 单模块；同一个 Codex 分身乏术，只会拿最近一次对话的习惯去套所有项目。

superpowers 的思路，就是把这类散落在人脑里的项目知识抽出来，变成 Codex 可以按需加载的"工具卡"。它不是提示词技巧，而是一套让 Codex 具备长期工作记忆和行为规范的结构化框架。这也是它和单纯写一个 system prompt 的本质区别：知识被拆成了独立的、可维护的模块。

1.2 核心组成：技能、记忆、子代理、检查点

这四个组件里，最核心也最值得花时间研究的是技能系统。记忆是它的基础设施，子代理和检查点是增强项。我后面会分别拆开讲，但请你记住一个总原则：superpowers 的价值不取决于装没装上，而取决于你的技能库有没有内容、内容够不够贴近真实工作流。

1.3 适合谁用

先说清楚它不是什么。superpowers 不能替代 Codex，也不改变 API 调用方式。它适合的是下面几种人：

• 已经装了 Codex CLI，但觉得每次都要教它项目背景、效率上不去的人；
• 同时维护多个项目、每个项目约定都不一样的开发；
• 想让 AI 干活风格更可控、输出更稳定，而不是每次随缘的团队；
• 以及，愿意花一点时间打磨模板、而不是只想"装完就自动变强"的人。

如果你是第一次听说 Codex，纯新手，我的建议是先正常跑通一次 Codex 基础会话再装 superpowers。否则出了问题你很难判断是模型问题、网络问题还是技能配置问题。工具是好工具，但排查成本也得算进去。

2. 从零装到能用：安装流程与验证方法

2.1 前置条件检查

安装 superpowers 之前，请先确认三件事。第一，Node.js 版本在 18 以上，很多插件脚本依赖较新的运行时特性；第二，Codex CLI 已经装好并且能正常跑通一次对话，执行codex --version能看到版本号；第三，本机装了 git，因为检查点功能要依赖本地 git 仓库做快照。

还想多说一句：别跳过基础验证。我见过太多人装完 superpowers 后发现 Codex 本身就没配好，结果把所有问题都归到插件头上。先跑通基础链路，再谈增强，排查会省力很多。

2.2 安装步骤

我安装的时候走的是 npm 全局安装加初始化脚本的路线。执行下面两条命令：

npm install -g superpowers superpowers init

init会在你的用户目录下创建 superpowers 需要的目录结构，包括技能目录、记忆目录和配置文件模板。如果你更喜欢源码方式，也可以把官方仓库 clone 到本地再执行 make install。不同版本对安装路径的细节要求可能不一样，强烈建议以当前官方 README 为准。

装完之后，要让 Codex 加载插件。以我当时用的版本为例，需要在~/.codex/config.toml里追加这样一段配置：

[plugin] enabled = true

然后重启 Codex 会话，让配置生效。如果你的 Codex 版本较新，配置文件位置可能从~/.codex迁移到了~/.config/codex，路径以你本机实际输出为准。这不是含糊，而是这类插件工具的常态：主程序一升级，路径就变。

注意：不同版本的配置路径可能从~/.codex迁到~/.config/codex，以你本机的实际输出为准。插件没加载时，先查路径，不要急着改技能内容。

2.3 怎么确认装好了

验证安装不需要看日志，直接在 Codex 会话里做三件事。第一，输入/plugins之类的管理命令，看有没有 superpowers 的条目；第二，直接问一句"你现在加载了哪些技能"，看它能不能列出技能清单；第三，让 Codex 执行一次最简单的技能动作，比如让它"列出可用的技能"。三件事都能正常回应，基本就是装好了。

我自己的习惯是再额外测试一下记忆目录有没有生成。装完跑了几轮对话之后，去用户目录下看一眼 memory 文件夹，里面如果开始出现 markdown 文件，就说明记忆链路也通了。

2.4 安装过程中最常见的三个报错

这三个坑我一个不落全踩过。尤其是第三个，它最阴的地方在于表面静默，你以为技能没写好，实际上插件压根没加载。所以排查前先确认加载，再动技能内容。

3. 核心机制拆解：技能、记忆、子代理和检查点各管什么

3.1 技能是怎么被"命中"的

整个技能系统的核心是 Markdown 文件加一个索引。启动时，Codex 读取技能目录里的所有技能文件，生成一份目录，这份目录通常叫 SKILLS.md。用户提问后，模型根据每个技能文件里的描述信息判断当前需求要不要调用技能；一旦命中，就读取那个技能文件全文，严格按里面的步骤执行。

所以技能文件里最关键的部分不是正文，而是开头那段 YAML 元信息，尤其是description和when_to_use两个字段。写得太宽泛，模型会在不该用的时候乱用；写得太窄，该用的时候又完全想不起来。我的经验是，把用户可能使用的自然说法直接列进when_to_use，比如"代码乱了""review 一下""这个 PR 有问题"，比写一句抽象的"当用户要求代码审查时"管用得多。

3.2 记忆机制：解决"AI 失忆"的地基

记忆目录本质上是一个 markdown 知识库。Codex 在会话中会把重要结论、用户的偏好、项目的特殊约定，按规则沉淀成带日期或带主题的文件；新会话启动时再自动加载。你可以把它理解成给 Codex 配了一本自动更新的工作笔记。

但记忆不是越多越好。我见过有人开了记忆功能之后，brain 文件里什么都有，包括"今天天气不错"这类废话，结果模型读取时反而被噪音干扰。记忆的价值在于结论，不在于过程。项目里真正稳定的约定、踩过坑之后得出的规则，才值得写进去。

提示：记忆的价值在于结论，不在于过程。只让模型沉淀稳定的事实，别让它记录聊天细节。

3.3 子代理和检查点：规模化和兜底

子代理的设计思路是把一个大任务拆给多个 Codex 实例并行去做，各自跑各自的 context，再把结果汇总回来。适合代码审查、多文件重构这类天然可以分块的任务。当然并行也带来资源占用翻倍的问题，所以别什么事都开子代理。

检查点则是另一个方向的兜底：在每次关键工具调用之前，superpowers 会在本地仓库创建一个快照提交。这样如果 AI 中途把代码改乱了，你随时可以回退到操作前状态。注意它是本地提交，不会推到远程，不影响同事的 git 历史。这一点我特别喜欢，等于给每次 AI 操作都配了后悔药。

4. 手写第一个技能：一个代码审查技能从零到跑通

4.1 先选一个高频场景

写技能别从"看起来很酷"开始，要从"你每周都在重复的事"开始。对我来说，最典型的高频场景是代码审查。每次要 review 分支改动，我都要重新告诉 Codex：先看哪些文件、重点检查什么、输出什么格式。这些话说了无数遍，写成一个技能一劳永逸。

4.2 技能文件长什么样

--- name: code-review description: 对当前分支的代码改动做一次系统检查，输出风险清单和修改建议 when_to_use: 当用户要求审查代码、检查 PR、评估 diff 改动质量时 version: 1.0.0 --- # 执行步骤 1. 先运行 git diff HEAD --stat 了解改动范围 2. 按文件逐个阅读 diff，不要跳过大文件 3. 对照下面的检查清单逐项排查： - [ ] 是否引入新的外部依赖 - [ ] 异常吞掉后是否有日志 - [ ] 是否有明显的性能风险点 - [ ] 改动是否覆盖了边界条件 # 输出格式 输出三部分：改动概览、风险清单（按风险从高到低）、建议的下一步操作。

把文件存到 superpowers 的技能目录下（init 时会生成一个 custom_skills 之类的目录），文件名最好和技能名一致，方便检索。光给出文件还不够，我有必要解释一下为什么这么写。

4.3 每个字段为什么重要

description是模型的"广告位"。它决定了用户在说什么样的话时，模型会想起这个技能。所以要把用户可能的表达都写进去。when_to_use更具体一些，相当于触发条件的集合。version不是摆设，技能的策略会迭代，版本号能让你在出问题时快速回溯。

正文部分更像给员工下的工作指令，而不是科普文档。你要明确写出"先做什么、再做什么、每步产出什么、用什么格式输出"。模型不会自动补全你省略的细节，你写得越具体，执行越稳定。

4.4 注册、触发和调试

技能文件放好后，重启 Codex 会话或者执行技能重载命令，让索引更新。然后用一句自然的话触发："用 code-review 技能看一下当前分支改动"。如果它正确地输出了改动概览和风险清单，说明链路通了。

如果没触发，最常见的两个原因：一是技能目录结构不对，索引没扫到文件；二是when_to_use写得和你的触发语句对不上。调试技巧是在正文最后加一步"结束时说明本次调用了哪个技能"，这样你能立刻确认它是否真的读了技能文件，而不是凭感觉乱答。

提示：如果技能没触发，先确认索引到底有没有扫到文件，再检查触发条件写法。这两个原因占了九成。

5. Java 项目里的实战沉淀：把 Maven、JUnit 和异常排查变成技能

5.1 Java 场景为什么值得单独做技能

Java 项目的复杂度往往不在语言本身，而在工具链：Maven 多模块、Gradle 多仓库、依赖冲突、Surefire 测试报告，每一层都有自己的一套规则。Codex 虽然懂这些概念，但每次都要在上下文里重新拼装一次，效率和稳定性都很差。

更现实的问题是，Java 项目的异常堆栈信息噪音太大。一个线上报错能有一两百行堆栈，外层全是框架包装，真正的业务根因藏在某一处 "Caused by" 里。如果每次都要临时指导 Codex 怎么剥洋葱，不如直接把这个过程写成技能。

5.2 一个可复用的 Java 异常排查技能

--- name: java-stacktrace-triage description: 分析 Java 异常堆栈并定位根因，给出可执行的修复建议 when_to_use: 用户贴出 Java 异常堆栈、报错日志，或询问线上故障原因时 version: 1.1.0 --- # 工作流程 1. 从堆栈底部向上找第一处 "Caused by"，不要被外层包装异常误导 2. 过滤 JDK 内部方法，重点看业务包名下出现频率最高的类 3. 按异常类型分流处理： - NullPointerException：沿调用链找最可能为 null 的对象 - ClassNotFoundException：执行 mvn dependency:tree -Dverbose 查依赖冲突 - SQLException：检查连接池配置和事务边界，区分数据库与业务层问题 4. 给出修复建议时，必须附上对应的代码位置和改动思路 # 输出格式 根因一句话概括、完整调用链摘要、按可能性排序的修复建议。

我在实际使用中给这个技能升过两次版本。第一次是加上了mvn dependency:tree -Dverbose这个排查依赖冲突的具体命令；第二次是要求它区分数据库层和业务层的问题，避免每次都在错误的方向上浪费两轮对话。版本迭代的记录全写在 frontmatter 里，回头看非常清晰。

5.3 Java 技能的调优经验

第一，技能里可以直接写命令，让 Codex 自己执行。比如依赖冲突排查，与其让它猜，不如直接告诉它跑哪条 Maven 命令、看输出哪一段。第二，不要做一个"Java 万能技能"，要拆成 build-fix、test-write、stacktrace-triage 这样粒度更小的技能，每个只解决一类问题。技能颗粒度越细，命中率越高，内容也越好维护。第三，如果团队项目里有自定义的代码规范，一定要单独开一个技能记录规范原文和检查方式，这比在系统提示里塞一大段话有效得多。

6. 和其他工具协同：worbuddy 这一类场景怎么接

6.1 为什么总有人问"worbuddy 怎么用 superpowers"

我在开发者社区里没少看到 "worbuddy 怎么用 superpowers" 这个问题，搜索热度还不低。稍微拆一下就知道，问这种问题的人多半不是从原生 Codex CLI 入手的，而是用某个封装好的图形化工具或对话外壳。工具不同，但问题本质是一样的：我这边已经有一套 Agent 工作流了，superpowers 这套技能体系能不能也在这里面生效。

6.2 接入的通用原则

superpowers 的插件机制不是跟某一个客户端绑死的，它生效的前提是两条：底层跑的是 Codex 的 agent 引擎，并且引擎能读取你本地的 Codex 配置和插件目录。只要这两条满足，无论你是用官方命令行、IDE 里的 Codex 面板，还是 worbuddy 这类第三方封装工具，技能和记忆都能生效，只是外壳不同。

反过来，如果某个封装工具自带独立的会话隔离，不读本机~/.codex的配置，那 superpowers 对它就是透明的，技能自然不会被触发。这种情况的处理办法不是硬改工具，而是在那个工具里找有没有"加载外部配置"或"自定义配置文件"的入口，让它指向同一份配置。我不具体评价任何一款产品，但这个接入原理对绝大多数工具都适用。

6.3 我推荐的三种协同姿势

第一种，重活交给原生 CLI。需要跑技能高频的场景，直接开官方 Codex 会话，技能体系最完整。第二种，日常轻量对话留在封装工具里，查资料、解释概念这种不需要项目上下文的活，随便哪个外壳都行。真遇到"用 code-review 技能审查当前改动"这类需求，再切回 CLI。第三种，把 superpowers 接进脚本和 CI，用类似codex exec "用 code-review 技能审查当前改动"的方式，在流水线里批量执行技能。这样技能不只服务于交互式对话，还能变成整个研发流程的一部分。

7. 我踩过的坑，和我现在离不开的几个效率习惯

7.1 高频坑清单

这些坑我在前文里其实都零散提过，这里集中列出来是因为它们最常被归错因。尤其是最后一个，Codex 一升级插件就失效的情况，我遇过不止一次。遇到先别怀疑自己写错了技能，先查加载。

7.2 我现在离不开的几个效率习惯

第一，新项目落地第一件事，就是建一个项目级记忆目录和三个基础技能：构建技能、测试技能、规范技能。花二十分钟建好，后面几百次会话都在受益。第二，每周翻一次 brain 文件，删掉过时结论。AI 不会自己整理记忆，这件事必须人来做，否则知识库会像无人打理的 wiki 一样慢慢废掉。

第三，技能升级时把变更原因写进 frontmatter，比如加一个changelog字段，记一行"v1.1.0 增加依赖冲突排查命令"。这不是仪式感，是几个月后你自己回看时唯一能依赖的线索。第四，给高频技能准备一个固定测试输入，每次改完技能就用同一段话触发一遍，对比输出是否稳定。这一步能帮你快速抓住"改坏了哪里"，而不是在真实需求里试错。

最后再说一个我自己的习惯。每次新建仓库，我都会先把 .gitignore、依赖安装命令、测试命令这些最基础最容易让 Codex 犯错的常识，写成三个平平无奇的技能。名字一点都不炫，但正是这三个技能，让 Codex 从"每次都要重新解释一遍"变成了"上手就能干活"。superpowers 不是什么魔术，它更像一套手工打磨的流程。你花在技能上的每一分钟，都会在之后无数次的会话里翻倍捞回来。照着这篇文章把它跑通之后，剩下的版本迭代，就该是你自己的故事了。