Superpowers插件：为Codex CLI装上长期记忆与技能库的完整指南

先交代一下背景这段时间开发者圈子里聊得最多的 AI 编程工具绝对绕不开 Codex CLI。但真正让我觉得它“脱胎换骨”的不是 Codex 本身而是一个叫 Superpowers 的开源插件。它不是模型不是魔改版本而是一整套给 Codex 增加长期记忆、技能库和分工机制的插件框架。装完之后Codex 从“每次对话都要重新交代背景的聪明助理”变成“懂得项目规范、记得住你的习惯、能自己拆活分活的高级同事”。这篇东西就是把我的安装过程、核心用法和踩过的坑一次说清楚适合已经用过 Codex CLI、但总觉得它差一口气的开发者。如果你还不知道 Codex CLI 是什么那建议先老老实实用一阵子再来看因为 Superpowers 解决的是“高级用户才痛点”的问题。1. 为什么 Codex 需要一个叫 Superpowers 的外挂1.1 裸 Codex 的尴尬强但不持久Codex CLI 本身已经相当能打。它不像普通聊天式 AI 那样只给你一段建议而是真的会去读仓库、跑测试、改文件能独立完成一整条开发任务流。我第一次用的时候确实被震到了感觉这就是我理想中的“代理式编程工具”。但是用久了问题就露出来了它每次会话都是一张白纸。今天在这个 Java 项目里好不容易让它记住“接口统一返回 Result 包装类”明天新开一个会话它又全忘光了。我跟朋友吐槽过这体验就像带了一个能力很强但失忆的实习生你得把同样的规矩重复交代无数遍它才能真正稳定发挥。如果你只拿 Codex 写点一次性脚本、改个独立 bug这个缺点不明显。可一旦进入真实项目开发——多模块工程、团队规范、测试基线、提交规范这些东西每天都要打交道——你就会发现每次刷新会话都意味着把整个项目的“隐性知识”重新教它一遍。时间一长人就会烦。1.2 Superpowers 补的是哪三块短板Superpowers 这个项目从名字就能看出作者的野心给 Codex 装上“超能力”。它主要补了四块裸 Codex 缺失的能力我列了个表方便对比短缺能力痛点表现Superpowers 的对应机制上下文连续性新会话不记得项目背景、个人偏好Memory 长期记忆规范一致性每次生成的代码风格、流程可能不同Skills 技能库复杂任务统筹单线程推进容易迷失没人做分工Subagents 子代理高频操作效率同样的 prompt 反复手打、还不稳定Slash Commands 命令模板说白了裸 Codex 是一个“单项能力很强、系统能力为零”的执行者而 Superpowers 把这些分散的能力串成了完整的工作流。Memor 管长期记忆Skills 管做事方法Subagents 管任务拆解Slash Commands 管效率。它没有发明新概念但把这些已经存在的东西很好地缝合到了一起。1.3 不是替代 Codex而是给 Codex 装上“操作系统”有人一听“插件框架”就担心是不是又要学一套新工具这里可以先放一百个心Superpowers 不替代 Codex也不是套壳的产品。Codex 仍然是那个推理和执行的核心Superpowers 只是运行在它外面的一层辅助系统。你可以把 Codex 想象成一台性能强劲的发动机Superpowers 则是加装的智能控制系统。发动机本身的功率没有变但它现在会在点火前先检查路况、读取导航、确认任务优先级再决定用哪种方式跑。正因为这样它才从“跑得快”变成“跑得又稳又有章法”。我个人的理解是Superpowers 改变的是 Codex 每次开工之前的“准备动作”。任务进来先看有没有匹配的技能行动之前先查记忆里有没有相关约定遇到复杂需求先分配子代理。这一套流程走下来Codex 的表现稳定度会有一个质的飞跃。2. 先把 Codex 跑起来环境准备与插件安装2.1 前置要求一个能正常工作的 Codex CLI在碰 Superpowers 之前你得有一个已经能正常运行的 Codex CLI 环境。这个环境怎么装建议大家直接看 Codex 官方 README因为不同版本的安装方式差异挺大我不在这里展开讲免得把新手带偏。装完之后先在终端确认一下版本codex --version能正常输出版本号说明基础环境没问题。如果这一步都过不去那就先别碰插件回去把 Codex CLI 本身搞定再说。我见过不少朋友装插件失败最后发现根因是 Codex 版本太旧或者根本没装全白白排查了一晚上。提示后续所有插件操作都依赖这个基础环境不要跳过。先把裸 Codex 用熟再装 Superpowers这样真出问题的时候你能分清是 Codex 的问题还是插件的问题。2.2 安装 Superpowers 插件两步走Superpowers 的安装方式官网 README 里写得很清楚而且我发现它更新过几次安装方式所以这里我特别提醒一句以你看到的最新版官方 README 为准。下面给的是社区里最常用、也相对通用的一种方式。第一步是创建 Codex 的插件目录并把 Superpowers 仓库克隆进去mkdir -p ~/.codex/plugins git clone https://github.com/obra/superpowers.git ~/.codex/plugins/superpowers cd ~/.codex/plugins/superpowers第二步是执行它自带的安装脚本./install.sh这个脚本做的事情说简单点就是把插件的技能文件、命令定义、默认记忆目录挂到 Codex 能找到的位置。如果你的环境里没有执行权限可能需要先加权限chmod x install.sh安装完建议重新启动一下 Codex 会话让插件生效。2.3 怎么确认插件真的装好了装完最怕的就是“也不知道成没成”。我一般用三步验证第一步在 Codex 交互界面里输入/help正常情况下你会看到 Superpowers 相关的命令出现在命令列表里比如/skills、/memory、/review这些。第二步输入/skills这个命令会列出当前可用的技能列表。如果插件已经初始化成功哪怕还没有任何自定义技能也会展示默认的技能目录结构而不是提示“未知命令”。第三步看一下本地目录是否生成ls -la ~/.codex/正常的目录里应该能看到plugins、skills、memory等文件夹。到这一步基本就可以确认插件挂载成功了。2.4 安装时最容易翻车的三个地方第一个坑是目录权限。用git clone到系统级目录或者权限受限的目录install 脚本会执行失败。解决办法很简单把所有东西都放到~/.codex/这个用户目录下面别动系统目录。第二个坑是 Codex 版本太旧。Superpowers 的一些功能依赖新版 Codex 的命令规范旧版本可能无法识别插件格式。这部分没有特别好的兼容办法你按官方指引升级 Codex 就完了。第三个坑是把多个插件混在一起。我试过同时挂几个不同的 Codex 插件结果它们之间的命令偶尔会互相干扰。我的建议是在把 Superpowers 用熟之前插件尽量保持单一来源别堆一堆扩展给自己埋雷。3. 核心玩法拆解Skills / Memory / Slash Commands 三件套3.1 Skills把方法写成代理能读的手册Skills 是 Superpowers 里最核心的概念也是最能提升开发体验的部分。你可以把它理解成一本代理能读的“工作手册”针对某一类任务写清楚处理步骤、注意事项和必须遵守的规范。Real 场景就是在 Java 项目里你希望 Codex 每次写代码都遵循公司规范在 Python 项目里你希望它优先使用src目录结构在写提交信息的时候你希望它严格按 Conventional Commits 来。这些事情都可以各自对应一个 Skill。Skill 本身通常是一个 Markdown 文件放在指定的技能目录下命名格式是SKILL.md。里面可以用 YAML 头写名称和描述再用正文写具体步骤。比如一个最简单的 Python 包开发技能--- name: python-package-dev description: 处理 Python 项目的功能开发时使用识别到 pyproject.toml 或 setup.py 时触发。 --- 1. 阅读项目中的 pyproject.toml先确认 Python 版本与依赖。 2. 新增功能代码必须放在 src/ 包结构下并提供类型注解。 3. 关键函数要补 docstring注释用中文。 4. 写完功能后运行 pytest确保全部通过。 5. 将测试命令和依赖变更记录到 memory。这里的 magic 在于Codex 会通过 Agent 信息自动判断某个任务是否匹配这个技能。匹配成功就先把这些步骤加载进上下文再开始干活。效果非常明显我再也不用每次重复交代“用 src 结构”“要类型注解”这些废话了。它相当于把你的团队规范、个人偏好沉淀成了一份代理每次自动加载的“操作手册”。3.2 Memory跨会话记住不该重复交代的事记忆功能解决的就是我一开头吐槽的“每次会话都失忆”问题。它的工作方式很简单粗暴把关键信息写进记忆文件下次任何时候都能读出来。我常用的记忆方式是/remember命令直接在会话里写/remember 这个项目是 Java 17接口统一返回 ResultT 包装类。 /remember 该团队要求提交信息遵循 Conventional Commits。写进去之后后续所有会话里Codex 在相关任务中都会自动参考这些信息。等于告诉它有些事情不用每次重新发现你已经知道了。我也经常让它在长时间任务结束时主动更新记忆。比如当它探索完仓库结构后我会让它“把项目的目录结构和常用命令记录到 memory”这样下一次会话它进入状态的速度会快很多。不过要注意Memory 里只记“长期事实”别记“临时状态”。比如“今天正在改登录模块的 bug”这种话任务结束就过期了写进去只会污染以后的上下文。我见过有人的记忆文件里塞满了过期任务记录结果后面每次任务都会读到一堆无关内容反而降低了效率。3.3 Slash Commands高频操作一句话完成Slash Commands 是最容易被低估的功能。说白了它就是一套可以自定义的 prompt 模板。Codex 原本也支持一些斜杠命令但 Superpowers 允许你自己去定义“遇到这条命令时按什么套路执行”。举个例子我们团队每次提交代码之前都要做代码自查。之前我都是手打一大段话“请先检查改动文件看看有没有明显的逻辑错误然后按 Conventional Commits 格式生成提交信息”。现在只需定义一个/commit命令把这套要求写进命令文件里之后每次执行提交前直接敲一行/commit就行。自定义命令文件一般就是普通的 Markdown 文件放在~/.codex/commands/下文件内容就是命令要执行的 prompt。我自己常用的是/commit和/review前者负责生成提交信息后者负责对当前改动做一轮全面 code review。这个功能最大的价值是稳定。手打 prompt 每次措辞都可能不一样AI 的理解也会有波动命令文件是固定不变的一段文字等于把“调教 AI 的行为”固化成代码每次都保持一致的标准。3.4 Subagents主代理学会分工Subagents 属于进阶玩但理解了之后会非常上瘾。它的作用是让主 Codex 代理在遇到复杂任务时可以创建专门用途的子代理来分头干活。举个例子一个开发任务往往包含“写代码、写测试、做代码审查”三个环节。以前我让 Codex 一口气全做完它经常写着写着就把质量检查环节给糊弄过去了。有了 Subagents 之后可以给它配置一个“代码审查子代理”这个子代理只负责审查逻辑缺陷和规范问题别的什么都不干。主代理写完代码再召唤审查子代理来把关分工明确质量明显更稳。我对 Subagents 的理解是它像一个项目经理在拆解任务把合适的活儿分给合适的角色。每个子代理都有自己的 persona 和技能集主代理负责统筹协调。这在长任务里特别重要因为单线程推进到后面上下文和注意力都会衰减而专门的子代理可以把某一类任务做到极致。4. 让 Superpowers 真正好用我的配置与工作流4.1 个人开发者最小配置方案用了几个月之后我攒出了一套最小可运行配置适合个人开发者直接抄作业。目录结构大概是这样的~/.codex/ ├── skills/ │ ├── coding-standards/ │ ├── git-workflow/ │ └── java-maven-service/ ├── memory/ │ ├── user.md │ └── projects/ └── commands/ ├── commit.md └── review.md我不追求一开始就把所有细节都配好因为配置越复杂踩坑的面越大。个人使用的话先建两个通用技能就够用了一个是coding-standards负责写代码的通用规范一个是git-workflow负责提交、分支、合并相关操作。先跑一个星期再慢慢往里面加项目专属技能。这种“先跑起来再优化”的方式是降低上手成本最有效的手段。4.2 团队共享一套技能库个人用熟了之后你会忍不住想把整套配置复制到团队里。这事是完全可行的因为 Skills、Memory、Commands 本质上都是纯文本文件用 Git 管理非常顺手。我们团队的做法是建了一个独立的仓库专门放共享的skills目录。每个成员把仓库 clone 到本地再软链或者直接复制到自己的~/.codex/skills/。技能文件的迭代走正常的提交流程谁想改规范就提 PRreview 通过之后所有人都能拉到新版。这么做有个额外收获团队的新成员上手 AI 工具时不需要自己从头调教 Codex而是直接继承了一套已经磨合过的行为规范。等于新同事入职第一天就带了一个“已经懂团队规则”的 AI 同事。4.3 接进外部自动化工作流还有人会把 Superpowers 再接进自己团队的自动化系统比如在 CI 流程里调用 codex 命令让代理按既定技能自动处理 issue 分类、生成 changelog或者做常规代码扫描。这里的外层工具可以是任意的自动化工作台、脚本或者协作平台原理都是一样的外层负责触发和展示Superpowers 负责给 Codex 提供记忆和技能支持。这种组合的价值在于AI 不再只是你终端里的一名“对话者”而是变成了流程里一个可复用、有规范的执行者。我见过有人把这个思路接入自己的日常工具箱效果不错。不管外层工具叫什么核心逻辑是一致的先把技能规则沉淀好再让 Codex 在具体任务里自动套用。5. 实际案例从一个 Java 仓库的“新接口”需求说起5.1 为什么拿 Java 项目举例前面提了好几次 Java Maven 微服务不是没理由的。Java 项目的约束在主流语言里算非常多的目录分层固定、依赖管理严格、Checkstyle 和 Sonar 规则无处不在、单元测试风格也有约定。裸 Codex 面对这种项目经常写出来的代码功能没问题但风格和规范一塌糊涂。这种“隐性约束多”的场景正是 Superpowers 的用武之地。所以我把 Java 项目作为第一个实战案例特别能说明问题。5.2 给仓库写一个专属 Skill我给一个 Java 微服务仓库写的专属技能长这样--- name: java-maven-service description: 在 Java Maven 微服务仓库中开发新接口时使用识别到 pom.xml 与 src/main/java 目录后触发。 --- 1. 先运行 mvn -q test确认当前基线测试是通过的。 2. 阅读 pom.xml确认 Java 版本和依赖新代码必须兼容现有版本。 3. 接口实现必须遵循仓库现有分层结构controller - service - mapper。 4. 所有对外接口统一返回 ResultT 包装类。 5. 新接口必须补对应的单元测试测试类命名规范为 XxxTest。 6. 完成编码后运行 mvn -q verify确保全量检查通过。 7. 将本次改动涉及的新依赖和约定更新到 memory。这段技能的核心不是代码本身而是把“这个仓库的隐性规则”明确写了出来。Codex 加载技能之后整个开发过程就有了约束边界而不是自由发挥。5.3 执行过程复盘我实际跑了一个“新增用户查询接口”的需求过程大概是这样的先是 Codex 自动加载了上面这个java-maven-service技能它没有问我要不要加载而是识别到仓库里有pom.xml就自动匹配了。然后它真的先老老实实跑了一遍mvn -q test确认了基线是绿的才开始动手写代码。写代码的过程中我发现它很自然地用到了ResultT包装类分层结构也没有偏离现有代码风格。这就是 memory 和 skill 共同作用的结果技能告诉它该按什么步骤走记忆告诉它项目里有哪些约定俗成的写法。最后它跑完验证自己把一些新的依赖变更写进了 memory。整个过程我几乎没怎么纠正它跟裸 Codex 时代完全不是一个体验。虽然任务总耗时没有明显缩短但人为干预的成本降了一大截这才是真正的效率提升。5.4 实测中的注意点用这个案例我也总结出了几个实际问题。第一技能描述里的触发条件一定要具体。如果把 description 写得太宽泛比如“Java 项目使用”那 Codex 在 Java 项目里的每个任务都可能加载它连改文档都会先跑一遍测试。触发条件得细化到“新增接口时”“处理 pom.xml 相关变更时”这个级别。第二自动化模式下要留个心眼。Superpowers 本身没有魔法Codex 的自律仍然有限。我的原则是危险命令删除、批量替换、发布保持人工确认日常生成代码可以交给自动模式。第三长任务里的上下文消耗会变大。技能和记忆文件都会占用 token如果你的模型预算有限尽量让技能文本精炼别写一堆废话进去。6. 踩过的坑和我的解决思路6.1 装完没反应先从版本和目录查起我遇到过最无语的一次插件装完了命令敲下去一点反应都没有。排查了一圈最后发现是 Codex CLI 版本太旧根本不认新格式的插件目录。升级 Codex 之后立刻就好了。所以遇到“装完没反应”第一件事不是重装插件而是先去查codex --version再去确认插件目录路径是不是~/.codex/plugins/下。路径写错或者版本太旧是绝大多数安装问题的根因。日志也要学会看一般在~/.codex/log目录下。插件加载失败的原因通常都会记录在里面比瞎猜效率高多了。6.2 技能文件写太厚反而“看漏”步骤我一开始想把所有规范塞进一个超大技能里一个SKILL.md写了几十条规范洋洋洒洒一大篇。结果 Codex 经常执行到一半就跑偏明显是“读”了但没“记住”全部步骤。后来我把大技能拆成了几个小技能一个管编码规范、一个管测试流程、一个管提交格式。每个技能控制在 5-10 条步骤以内。触发的时候Codex 一次只需要加载对应的小技能执行完整度明显提高。这跟操作系统里“文件越短越容易加载”是一回事。给 AI 的信息也是一样性价比最高的是把它刚好吃下的篇幅而不是越多越好。6.3 记忆里囤了一堆过期垃圾记忆功能用顺了之后很容易变成垃圾桶。有一阵子我的 memory 文件里全是“今天在改登录模块”“明天要处理支付回调”这类临时状态。结果后面不管做什么任务Codex 都会读到这些过期信息白白干扰判断。解决办法是定期清理而且我在写记忆时开始有意识地分两类一类是稳定事实比如“项目是 Java 17”“接口返回 Result 包装类”另一类是临时状态比如“当前正在做支付模块”。后者我直接不写进 memory而是放在当前任务描述里。6.4 别把 Superpowers 当魔法最后想泼一盆冷水Superpowers 不是魔法。它没有提高 Codex 的推理上限也不会让一个本来能力不足的低配模型变成天才。它的本质是“纪律性”是把稳定的事做稳把规范的事做规范。你如果期望装了它之后Codex 就能在没有人工 review 的情况下跑生产环境命令那我劝你还是清醒一点。该 review 的代码还是要 review危险操作该审批还是要审批。工具是帮你减少重复劳动不是替你放弃判断。我在实际使用里最大的体会是接手一个新项目时第一件事不是急着让它写代码而是先花十分钟把项目事实写进 memory再给它补一个项目专属的 skill。这十分钟花得极其便宜但换来的是之后每一次会话都处在“已经懂这个项目”的状态里。这个习惯比任何一项单独的功能配置都重要。