superpowers插件：让Codex拥有持久记忆与按需技能库

1. 先搞清楚：superpowers 到底是什么

记得我第一次看到“superpowers”这个名字，是在一个 AI 编程工具的讨论帖里。当时第一反应：这又是什么营销号起的噱头名字。但后来被 Codex 的记忆问题折磨得够呛——上午还让它给某个模块写了单元测试，下午开新会话它就把项目里约定的命名规范忘得一干二净，我又得从头把背景讲一遍——才认真去翻了源码，发现这个名字起得还真不算夸张。

superpowers 是一个给 Codex CLI 用的开源插件，作者是 Jesse Vincent。它做的事情概括起来就两件：第一，给 Codex 装上持久化记忆，让它跨会话记住项目约定、用户偏好、历史决策；第二，提供一个技能库机制，把某个技术栈、某类任务、某种工作流的专家知识打包成一个个“技能”，Codex 在需要的时候按需加载，而不是把所有知识都塞进每轮对话的上下文里。

这篇文章我会按自己实际操作的顺序来写：先拆解它的设计逻辑，再讲安装和验证，然后拿 Java 开发场景完整走一遍技能配置流程，最后把踩过的坑整理成速查表。社区里经常有人问“worbuddy 怎么用 superpowers”，这类工具我也会在后面的排查部分单独说——只要底层还是 Codex 的插件体系，配置思路就是完全一致的。

如果你正在用 Codex，觉得每次对话都要重复交代背景，或者希望它能更“懂”你常用的技术栈和团队规范，那这篇内容对你应该有用。新手也不用怕，我会把每一步背后的原因一起讲清楚，照着做就行。

2. 原理拆解：为什么这套机制能跑通

2.1 SKILL.md：给 Codex 的“按需加载说明书”

技能是 superpowers 的核心概念。一个技能就是一个目录，目录里最关键的一份文件叫 SKILL.md。这份文件分成两块：头部是 YAML 格式的元信息，包含技能名称、描述、适用场景；正文是给 Codex 读的操作说明，可以写约定、步骤、示例、负面清单，什么都能放。

为什么用 Markdown 而不是代码来承载知识？因为 Codex 本身是语言模型，它对自然语言指令的“理解成本”最低。你写一个 Python 脚本让它执行，它只能看到一个执行结果，中间的逻辑它不一定真正理解；但你写一份 SKILL.md，它是能真正“读懂”并在后续对话中遵守的。这就是 superpowers 把知识封装成 Markdown 文档的核心原因，而不是做成结构化配置。

按需加载这一点也特别关键。你想象一下，如果让 Codex 每轮对话都背着一整套 Java 规范、一套团队编码约定、一个私有组件库的用法，上下文窗口很快就满了，其中大部分知识点在当前任务里根本用不上。superpowers 的做法是让 Codex 先列出当前可用的技能，根据任务判断哪几个相关，再把那个 SKILL.md 的内容读进上下文，相当于“用到哪本手册，就翻开哪一页”，其他手册继续在书架上吃灰。

2.2 记忆系统：会话、项目、用户三层各管什么

记忆是 superpowers 另一个核心卖点。它把记忆分成三层管理：用户记忆、项目记忆、会话记忆。用户记忆存的是你的全局偏好，比如“测试一律用 JUnit 5”“private 字段放在类末尾”；项目记忆跟具体目录绑定，记录这个项目的架构决策、历史坑位、命名约定；会话记忆则是当前这次对话的关键结论摘要。

这套分层的设计是有讲究的。用户记忆覆盖所有项目，适合放“我做事的习惯”；项目记忆只对当前仓库生效，适合放“这个项目自己的规矩”；会话记忆负责把一次长对话的重要结论沉淀下来，下次开新会话时还能接上。三层叠加，Codex 在每次会话开始时先读相关记忆，再开始干活，等于给模型配了一个“失忆前的小抄”。

关键点是摘要而非全文。superpowers 不会把上次几万字对话原封不动塞回来，而是把会话压缩成几条摘要，只保留最重要的决策和结论。这样既不会撑爆上下文，又保留了跨会话的连续性，这也是我实测下来觉得它比裸 Codex 省心太多的地方。

2.3 技能里藏脚本：把“文档知识”变成“可执行动作”

技能目录下面除了 SKILL.md，还可以放一个 scripts 子目录，里面是可以直接执行的小工具，比如构建辅助脚本、批量重命名工具、数据库结构对比脚本。Codex 在执行技能指导时，如果发现某个操作适合用脚本完成，它会主动调用，相当于给技能安上了手脚。

这个设计的意义在于，技能不只是“教你做”，还能“替你做”。单纯的知识说明有个问题：Codex 读完规范和约定，动手时还是有可能记岔某个命令参数。但如果技能里附带一个封装好的脚本，它只需要知道“跑 scripts/format.sh 就行”，结果就是稳定的。我后来给团队做了一堆这样的技能，把格式化、依赖检查、版本号同步这种重复劳动全塞进脚本，Codex 的实际可用性立刻上了一个台阶。

3. superpowers 安装与初始化实操

3.1 安装前的前置检查

装之前先确认三件事：Codex CLI 已经装好并且能正常对话；本机有 Node.js 环境，因为 superpowers 本体是 TypeScript 写的，编译和运行都依赖 Node；git 得有，安装过程需要拉仓库。

还没升级过 Codex 的，建议先升级到较新版本。插件机制在不同版本里一直在调整，旧版本可能根本不认识 superpowers，或者加载方式对不上。我的习惯是先codex --version看一眼，再决定走哪个安装路线。这一步虽然不起眼，但能省掉后面一半的排查时间。

3.2 方式一：插件市场安装

我自己用的版本是走 Codex 插件市场装的，整体流程大概是先把超级技能对外的市场清单加进来，然后执行安装命令，最后用列表命令确认加载状态。不同小版本的具体命令名会有一点差别，最简单的方法是打开项目 README 找到 INSTALL 一节，照着最新的来。

这里我想强调一个原则：如果你用的 Codex 版本已经提供了插件市场的标准命令，优先走官方市场路线。因为市场清单会跟着版本更新，后续升级省心。我一开始嫌麻烦想手动装，结果后面每次 Codex 发布新版本都要检查一遍兼容性，反而更费劲。

3.3 方式二：手动克隆安装

手动安装适合想搞清楚原理、或者网络环境不方便用市场命令的情况。思路就是把仓库克隆下来，编译出可执行文件，再让 Codex 在启动时加载这个插件。我常用的做法是这样：

git clone https://github.com/obra/superpowers.git ~/.codex/plugins/superpowers cd ~/.codex/plugins/superpowers npm install npm run build

编译完会在目录里生成可执行文件，然后把插件路径注册到 Codex 的配置里。配置文件的写法我以常见格式为例：

[plugins] superpowers = "~/.codex/plugins/superpowers"

写完之后重启 Codex 会话让配置生效。这里有个容易踩的坑：配置文件如果之前没写过 plugins 段，不要手滑把整个文件覆盖了，Codex 的其他配置项还躺在里面，丢失了很难恢复。建议先备份，再编辑。

3.4 安装后必做的三件事

不管用哪种方式装完，我建议立刻做三件事，确认它真的生效了。

第一，检查记忆目录有没有被创建。正常情况下，只要 superpowers 插件加载成功，~/.codex/memories这类目录会自动生成，里面按项目、用户分开。

第二，跑一个探针对话。随便开个新会话，直接问 Codex“你有哪些可用的技能？”。如果它能列出技能列表或者提到 superpowers，说明插件已经进入它的视野了。如果它一脸茫然，说明插件压根没加载，回到配置排查。

第三，故意让它记住一句话。比如告诉它“记住我习惯用 4 个空格缩进”，然后结束会话重开，问它我有什么习惯。能答上来，说明记忆链路通了。这三件事做完，才敢说安装真正成功。

4. 实战：给 Codex 配一个 Java 技能

4.1 先明确技能边界，别一上来就写文件

给 Codex 配技能的通用场景，我拿 Java 开发来演示，因为 Java 项目的特点是规约多、工具链重，特别适合让 Codex“背规矩”。

动手写 SKILL.md 之前，先想清楚这个技能要覆盖什么范围。我的建议是拆成一个技能管一件事，别做一个“Java 大而全”。比如我这次的目标很明确：让 Codex 在写 Java 代码时遵守三条规定——测试用 JUnit 5 加 AssertJ、业务代码用 slf4j 打日志、Maven 依赖版本统一在父 pom 的 dependencyManagement 里管理。边界一旦定了，后面写出来的 SKILL.md 才不会变成又臭又长的说明书。

4.2 编写 SKILL.md 的完整示例

下面是我实际用的一个简化版，放在技能目录里就叫 SKILL.md：

--- name: java-dev description: Java 开发规约，适用于 Maven 项目。当需要编写、修改或测试 Java 代码时使用。 --- # Java 开发技能 ## 适用项目 - 使用 Maven 构建的 Java 项目 - 目标 JDK 17 或以上 ## 强制约定 - 单元测试使用 JUnit 5，断言统一用 AssertJ - 业务代码禁止 System.out.println，日志走 slf4j - 新依赖版本先查 Maven Central 稳定版，再加到父 pom 的 dependencyManagement ## 常见任务 - 新增依赖：查版本 -> 改父 pom -> 子模块引用不写版本号 - 运行测试：mvn test -Dtest=类名 ## 反面例子 - 不要给所有测试类都加上 @SpringBootTest，纯单元测试用 Mockito 即可

头部的 description 非常重要，Codex 就是靠这段描述来决定“要不要用这个技能”的。写得越具体，触发得越准。我见过很多人把 description 写成“Java 开发技能”，太泛了，Codex 经常判断不出来该不该加载，等于白挂。

4.3 放对位置，再验证效果

写好的技能目录要放到超级技能的技能库路径下。用户级技能放在~/.codex/skills/java-dev/，只针对某个项目的技能可以放到项目根目录的.codex/skills/java-dev/。两级都支持，看你希望它全局生效还是只在特定仓库生效。

验证方法很直接：开一个 Java 项目会话，让它写一个 Service 的单元测试，然后逐条对照 SKILL.md 里的约定。我那次实测，Codex 会主动问“项目里有没有现成的测试基类”，写出来的测试用了 AssertJ 而不是 JUnit 自带断言，日志也自动用的 slf4j。这说明技能确实被加载了，而且遵循度比单纯在对话里口头交代要高得多。

5. 记忆系统怎么用才不白装

5.1 主动让 Codex“记住这一点”

很多人装好 superpowers 之后有个误区，以为它会自动记住一切都明明白白。实际上它不是神，它的记忆主要还是靠会话过程中 Codex 按指令沉淀下来的。想让某个约定跨会话生效，最有效的方法是对话里明确要求它记忆，直接说“请记住这一点：私有字段统一放类末尾”，效果比暗示它“注意一下风格”好太多。

我养成的习惯是，在项目开始或者接到新需求时，先花一轮对话把关键约定交代完，然后加一句“以上全部写入项目记忆”。后面新会话里再提相关任务，它基本都能接上上下文。这个习惯一开始觉得麻烦，一个月之后就离不开了。

5.2 记忆文件在哪里、怎么手动改

记忆落盘的位置在~/.codex/memories下面，按用户、项目分目录放。有时候我发现某条记忆写错了，或者 Codex 沉淀的内容不是我想要的，直接改文件反而比让它重新学习快。打开对应项目记忆文件，把那条错误的约定删掉，把准确的写进去，保存即可。

这里有个细节值得注意：手动改文件之后，最好再开一次会话让它重新读取一遍记忆，确认新内容已经被消化。因为 Codex 很可能读取了旧记忆但还没注意到文件改动，重新触发一次读取就踏实了。

5.3 会话日志和自动摘要

superpowers 会把每次会话的关键内容记录成摘要，存在会话日志里。我理解它的作用不只是存档，更是为下一次会话提供接续的基础。每次新对话开始，它读到的“上次说了什么”，其实主要就是这些摘要，而不是原始聊天记录。

一开始我以为摘要会很粗糙，但实际用下来，它能把“我们决定改用 vector 存储、前端组件库换成半像素”这种关键结论提炼出来，比我自己记笔记还勤快。如果有跨会话协作的重活，这个功能真是救命级的体验。

6. 我踩过的坑：常见问题与排查速查

6.1 插件没被加载，Codex 压根不提超级技能

症状是装完之后，Codex 对技能和记忆毫无反应，问什么都像失忆。我在排查这类问题时，优先看配置文件的 plugins 段有没有写对路径，再看是不是版本兼容问题。

经验上最容易出错的是配置文件格式。Codex 升级后配置文件结构会变，旧的配置写法可能直接失效。我的建议是把配置先备份，再对照最新文档重写 plugins 段，不要凭记忆手搓。

6.2 技能存在，但 Codex 就是不调用

技能文件明明放在了技能库目录里，可对话时 Codex 就是不理会它。这种问题九成出在描述写得不够具体，导致 Codex 压根判断不出“当前任务跟这个技能有关”。

我试过最有效的修正方法：在 description 里写明触发条件。比如“当用户要求新增接口、修改 VO、处理 JSON 序列化时使用”，这样它一看任务关键词就能对上。改完描述立刻在对话里再试一次，命中率明显提高。

6.3 记忆“丢了”，跨会话想不起来

明明让 Codex 记住了约定，第二天开新会话它又装傻。先别急着怪插件，检查记忆目录的写入权限。我碰到过一次目录权限没配对，文件写不进去，它自己也不知道自己“没记住”。

另外要注意手动清理：记忆文件是有体积的，攒太多了读取效率会下降，摘要也可能过滤掉一些不太显眼但有用的约定。定期整理记忆文件，把过时的删掉，比一直堆着更可靠。

6.4 superpowers: command not found

运行时提示命令找不到，基本上就是 PATH 的问题。手动安装很容易遇到，因为编译产物没被放进 PATH。解决方法是在 PATH 里加上 superpowers 可执行文件所在的目录，或者做个软链接到已有目录。

我自己的做法是把编译产物软链到~/.local/bin下，这样新开的终端窗口都能直接找到。链接完记得重新打开终端验证，别在旧终端里白忙活。

6.5 worbuddy 这类包装工具怎么用 superpowers

最近群里总是有人问“worbuddy 怎么用 superpowers”，这个问题的答案比想象中简单：包装工具只要底层还是 Codex 的那一套会话和插件机制，superpowers 作为一个标准插件，配置方式基本不变。你按照前面介绍的方式，在 Codex 的配置和技能目录里装好，包装工具就能享受到技能和记忆的能力。

唯一要注意的是，有些包装工具会给 Codex 单独指定一套配置目录，而不是默认的~/.codex。这种情况下，你需要找到它实际使用的配置路径，把插件配置和技能目录都放到对应位置。怎么找？看包装工具的文档里有没有提到“codex 配置目录”或者“plugins 配置段”，基本就是这个入口。核心思路一句话：插件读哪里的配置，就把 superpowers 装到哪里。

我把常见问题和解决方向整理成一张速查表，方便你遇到症状直接对着查：

7. 用了一个月后的几条实在心得

最后分享几条用了大概一个月之后，我觉得值得说的经验。

第一，技能和记忆是“养”出来的，不是一次配好就完事。我第一个技能写得又长又空，Codex 根本不愿加载。后来改成短小精悍、每条约定都有场景描述，它才真正用起来。每周花十分钟翻一翻技能库，删掉过期的、补充新踩的坑，效果远比一次性投入大。

第二，别把代码注释里的规约当记忆。Codex 会自动读项目文件，但它能记住并遵守的规约，和它“知道有这个规约”是两码事。想让某些约定真正稳定生效，最高效的方式还是写进技能或记忆，而不是指望它每次都能从代码里领悟出来。

第三，团队规约也可以做成技能。我给团队把 Git 提交规范、Code Review 检查清单都做成了技能文件，新同事上手时让 Codex 辅助工作，产出的代码风格从一开始就对齐。这个价值已经超越了“给自己写脚本”的范畴，变成了团队知识沉淀的一种新形式。

最后再提一个我个人的小技巧：技能和记忆文件我全部用 git 管理，放进一个私有仓库。这样换机器、重装系统，几分钟就能把所有配置拉回来。而且每次改动都有历史，哪天发现某个技能改坏了，直接回退到上一版，省了很多冤枉调试。

superpowers 这东西，本质上不是魔法，它只是给了 Codex 一个“备忘录”和一个“工具箱”。但恰恰是这两个朴素的能力，让 AI 编程助手从一个“每次都要重新认识的临时工”，变成了“知根知底的老搭档”。建议你装一个，哪怕只是从最简单的项目记忆开始用，体验完再回来告诉我你踩了什么新坑。