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 写的编译和运行都依赖 Nodegit 得有安装过程需要拉仓库。还没升级过 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 装到哪里。我把常见问题和解决方向整理成一张速查表方便你遇到症状直接对着查症状可能原因排查方向插件完全没加载配置文件路径写错、版本不兼容检查 config 的 plugins 段升级 Codex技能列表为空技能目录不对、描述太泛检查~/.codex/skills结构重写 description技能没被调用描述没有触发词在 description 写明触发条件再对话测试记忆不跨会话目录权限、摘要未生成检查~/.codex/memories写入权限命令找不到PATH 没配好软链编译产物到 PATH 覆盖的目录包装工具不识别使用了自定义配置目录查包装工具文档定位插件配置入口7. 用了一个月后的几条实在心得最后分享几条用了大概一个月之后我觉得值得说的经验。第一技能和记忆是“养”出来的不是一次配好就完事。我第一个技能写得又长又空Codex 根本不愿加载。后来改成短小精悍、每条约定都有场景描述它才真正用起来。每周花十分钟翻一翻技能库删掉过期的、补充新踩的坑效果远比一次性投入大。第二别把代码注释里的规约当记忆。Codex 会自动读项目文件但它能记住并遵守的规约和它“知道有这个规约”是两码事。想让某些约定真正稳定生效最高效的方式还是写进技能或记忆而不是指望它每次都能从代码里领悟出来。第三团队规约也可以做成技能。我给团队把 Git 提交规范、Code Review 检查清单都做成了技能文件新同事上手时让 Codex 辅助工作产出的代码风格从一开始就对齐。这个价值已经超越了“给自己写脚本”的范畴变成了团队知识沉淀的一种新形式。最后再提一个我个人的小技巧技能和记忆文件我全部用 git 管理放进一个私有仓库。这样换机器、重装系统几分钟就能把所有配置拉回来。而且每次改动都有历史哪天发现某个技能改坏了直接回退到上一版省了很多冤枉调试。superpowers 这东西本质上不是魔法它只是给了 Codex 一个“备忘录”和一个“工具箱”。但恰恰是这两个朴素的能力让 AI 编程助手从一个“每次都要重新认识的临时工”变成了“知根知底的老搭档”。建议你装一个哪怕只是从最简单的项目记忆开始用体验完再回来告诉我你踩了什么新坑。