把 Agent 方法论框架 superpowers 装到你的工具上：多平台接入差异与不生效排查
本文基于 superpowers 仓库 commit 44c9b2d（2026-07-27）梳理，该项目仍在持续迭代，具体行为以仓库 https://github.com/obra/superpowers 最新代码与文档为准。
装 superpowers 的成败不在于技能文件有没有落到磁盘上，而在于会话一开始有没有一段固定文本被塞进模型的上下文。 仓库里的 docs/porting-to-a-new-harness.md 把这句话写得比任何安装说明都直白：bootstrap 就是整个接入本身，没有它，技能文件躺在磁盘上也永远不会被调用。你在各个平台上看到的那些形态各异的安装命令，本质上都是在换一种方式完成同一件事。理解了这一点，“我按文档装了但模型完全没反应”这类问题的排查路径就只剩一条。
站内已经有 Claude Code 教程 和 Cursor 教程，那两篇讲的是工具本身怎么用、通用方法论怎么组织；这一篇不重复它们，只讲 superpowers 这个具体的开源项目，怎么把那套方法论落到你手里那个工具上，以及落不下去的时候该看哪个文件。
一、你装进去的到底是哪几样东西
从 README.md 的描述看，这个项目是”一套可组合的技能，加上一些确保 Agent 真的会去用它们的初始指令”。翻译成工程语言，就是三个耦合度很低的部分，各自装在仓库的不同位置。
技能内容本身是跨平台共享的。skills/ 目录下我数到 14 个技能目录：brainstorming、writing-plans、executing-plans、subagent-driven-development、dispatching-parallel-agents、test-driven-development、systematic-debugging、verification-before-completion、requesting-code-review、receiving-code-review、using-git-worktrees、finishing-a-development-branch、writing-skills、using-superpowers。所有平台读的都是同一份，一个字都不改。
之所以能做到一个字不改，是因为技能正文里刻意不出现任何一个具体工具名。docs/porting-to-a-new-harness.md 把这条列为第一条规则：技能描述的是动作——“调用一个技能""读一个文件""派发一个子代理""建一个待办”——而不是工具。真实工具名放在第二部分，也就是每个平台各自的工具映射里。第三部分才是 bootstrap，负责在会话开始把 skills/using-superpowers/SKILL.md 的全文包在 <EXTREMELY_IMPORTANT> 标签里推到模型面前。
| 组成部分 | 它负责什么 | 对应仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| 技能库 | 14 个技能的正文，跨平台共享、逐字相同 | skills/ | 想看某个流程到底怎么规定的；写自己的技能 |
| bootstrap 内容源 | 会话开始被整体注入的那份”你有 superpowers”指令 | skills/using-superpowers/SKILL.md | 装完模型毫无反应时，第一个要确认它有没有进上下文 |
| 平台工具映射 | 把”派发子代理""建待办”翻译成该平台真实工具名 | skills/using-superpowers/references/ 下的 codex-tools.md、gemini-tools.md、pi-tools.md、antigravity-tools.md | 技能触发了，但里面提到的动作落不到真实工具上 |
| 平台清单文件 | 告诉平台去哪找技能目录、加载哪个钩子配置（Claude Code 那份两个字段都不设，按约定自动发现 skills/ 和 hooks/hooks.json） | .claude-plugin/plugin.json、.cursor-plugin/plugin.json、.codex-plugin/plugin.json、.kimi-plugin/plugin.json、gemini-extension.json、仓库根 package.json | 平台压根列不出这些技能 |
| 钩子脚本 | 读 SKILL.md，按各平台要求的 JSON 形状打印到标准输出 | hooks/session-start、hooks/hooks.json、hooks/hooks-cursor.json | 钩子型平台上注入失败或重复注入 |
| 跨平台包装脚本 | 同一个文件既是 Windows 批处理又是 Unix shell 脚本 | hooks/run-hook.cmd | Windows 上装完没动静 |
| 进程内插件 | 直接在平台进程里注册技能目录并改消息数组 | .opencode/plugins/superpowers.js、.pi/extensions/superpowers.ts | OpenCode 或 pi 上排查注入时机 |
看完这张表就能明白：所谓”各平台装法不同”，差的从来不是技能内容，只是第五到第七行这几个投递壳子。
二、四种接入形态，分别长什么样
docs/porting-to-a-new-harness.md 把接入方式归成三种结构形态，按”bootstrap 怎么到模型面前”来分，另外还有一种混合情况。你手上的工具属于哪一种，决定了排查时该翻哪个文件。
钩子型。 平台在会话开始执行一条 shell 命令，读它的标准输出。Claude Code、Cursor、GitHub Copilot CLI 走的是这条路。真正干活的是 hooks/session-start：它把 SKILL.md 整个 cat 出来，做一遍 JSON 转义，然后根据环境变量判断当前是哪个平台，打印三种不同形状之一——Cursor 要的是 additional_context，Claude Code 要的是嵌套的 hookSpecificOutput.additionalContext，其余按 SDK 标准输出顶层的 additionalContext。这个判断顺序有讲究，脚本里的注释写明 Cursor 可能同时设置 CLAUDE_PLUGIN_ROOT，所以 Cursor 那个分支必须排在前面。
进程内插件型。 平台加载一个 JS/TS 模块，你在生命周期回调里改消息数组。OpenCode 和 pi 是这一类。.opencode/plugins/superpowers.js 用 config 钩子把技能目录推进 config.skills.paths，再用 experimental.chat.messages.transform 注入；.pi/extensions/superpowers.ts 则是 resources_discover 事件返回 skillPaths，context 事件负责注入，并用一个 injectBootstrap 标志在 session_start 和 session_compact 时置位、在 agent_end 时清掉。两者回调频率不一样，去重策略也就不一样，这是移植文档专门点名的坑之一。
指令文件型。 平台既没有 shell 钩子也没有代码插件，只有一个它每次都会加载的上下文文件。Gemini CLI 就是这样：gemini-extension.json 里一个 contextFileName 字段指向扩展自带的 GEMINI.md，而那个 GEMINI.md 全文只有两行，两条 @ 引用，一条指向 using-superpowers/SKILL.md，一条指向 gemini-tools.md。这里没有任何组装代码，平台把引用的内容原样加载。
清单声明型。 Kimi Code 的 .kimi-plugin/plugin.json 是个干净的例子：skills 字段指向 ./skills/，sessionStart.skill 直接写 using-superpowers，工具映射则以一大段 skillInstructions 字符串内联在清单里——里面明确写了”技能说 TodoWrite 时用 Kimi Code 的 TodoList”、“要派实现或评审子代理时用 Agent 工具并传 subagent_type: coder，不要传 general-purpose”。整个接入没有拷贝技能、没有软链、没有钩子，也没有额外运行时依赖。
Codex 又是另一种情况。.codex-plugin/plugin.json 里有一行 "hooks": {}，移植文档解释得很清楚：这个空对象是故意的，用来抑制 Codex 对 hooks/hooks.json 的自动发现，因为 Codex 原生就会呈现技能，不跑会话开始钩子。所以在 Codex 上看不到钩子执行，不代表装坏了。
Factory Droid 则连新文件都不需要——它用自己的 droid plugin install 命令消费现成的清单。移植文档专门留了一段说这种情况：有些”新平台”其实只是换了个安装器的既有接入，最好的移植结果可能就是给 README 加一段话。
顺带一提，这份移植文档在引用 Antigravity 时提到了一个 .antigravity-plugin/ 目录，但这个提交里的仓库根目录下并没有它，只有 references/antigravity-tools.md。文档自己在开头就写了处理原则：文档和代码打架时以代码为准。你排查任何平台的时候都该按这个原则来。
三、“装完不生效”最常卡在哪一步
先说结论：绝大多数情况卡在注入这一环，而不是技能内容那一环。判断方法是现成的——开一个干净会话，问模型”你有哪些 superpowers”。它要是知道，注入成功；不知道，后面的验收测试就别做了，先修注入。移植文档把这个叫冒烟检查，还给了 OpenCode 的另一种做法：opencode run --print-logs "hello" 2>&1 | grep -i superpowers，并且特意标了 2>&1 很关键，因为日志走的是标准错误。
真正的验收标准只有一条，在干净会话里发这句话：Let’s make a react todo list。合格的安装应该在写任何代码之前先触发 brainstorming。docs/README.kimi.md 的排障章节把这句原话列成了验收提示词，移植文档更是把它定为提交移植 PR 时必须附上的证据。
具体到平台，几个高频卡点各有各的原因。
Windows 上装了钩子型平台却毫无动静，多半是 bash 没找到。hooks/run-hook.cmd 是个既能当批处理又能当 shell 脚本的双面文件，Windows 分支会依次找 C:\Program Files\Git\bin\bash.exe、C:\Program Files (x86)\Git\bin\bash.exe，再找 PATH 上的 bash；三处都没有的话，它的注释写得很明白——干净退出，插件照常工作，只是没有会话开始的上下文注入。也就是说这是个静默降级，你不会看到任何报错。同一个文件的注释还解释了为什么钩子脚本必须是无扩展名的 session-start 而不是 session-start.sh：Claude Code 的 Windows 处理会给包含 .sh 的命令前面自动加 bash，加了就重复调用。
Kimi Code 上装完没反应，往往只是没开新会话。docs/README.kimi.md 反复强调，Kimi Code 的插件变更只对新会话生效，安装、更新、启用、禁用、重载之后都要用 /new 开一个新会话。它的排障清单还提了另一件事：对裸仓库 URL，Kimi Code 会装最新的 GitHub 发布版，想验证未发布的改动得显式指定分支。
OpenCode 上更新不生效是另一类问题。docs/README.opencode.md 说明它是通过 git 包规格安装的，某些 OpenCode 与 Bun 版本会把解析后的 git 依赖钉在锁文件或缓存里，重启也拿不到新提交，得清包缓存或重装。同一份文档还记了 Windows 上的一个上游安装器问题：git+https 的缓存路径处理，以及 Bun 在正常终端里能用 git 却找不到 git.exe——绕法是用系统 npm 装到 $HOME\.config\opencode 再把 opencode.json 指向本地包路径。
至于跨工具的那个基本前提，README.md 在安装章节第一句就写了：安装方式因平台而异，用了多个就得为每个单独装一遍。这条被 OpenCode 的文档又强调了一遍。经常有人在 Claude Code 里装好了，切到别的工具发现”没了”，原因就这么朴素。
四、这套设计放弃了什么
先说流程本身的代价。这套方法论的默认路径是：先 brainstorming 逼你把需求问清楚、出设计文档，再开 worktree、写计划、把工作拆成 2 到 5 分钟一个的任务，然后派子代理逐个做、两阶段评审、红绿重构、最后走完分支收尾。对一个改三行配置的活儿，这是明显的过度设计。它会让开发变慢，会让 Agent 变啰嗦——你想直接要代码，它先反过来问你一串问题。README 说得毫不含糊：Agent 在做任何任务前都会检查有没有适用的技能，这些是强制流程而不是建议。真觉得吵，只能显式让它跳过，而不是指望它自己识趣。
第二个代价是内容不归你改。README.md 的贡献章节明确写着，项目一般不接受新技能的贡献，且任何技能改动都必须在所有支持的平台上都成立。移植文档更是把”不许为了适配自己的平台去改技能正文”列成硬规则，说这类改动会被直接拒。你要定制，正确入口是平台工具映射和你自己的个人技能目录——docs/README.opencode.md 就写了在 ~/.config/opencode/skills/ 建个人技能、在项目 .opencode/skills/ 建项目技能，优先级是项目 > 个人 > superpowers。
第三，有些能力是可降级的，降级之后相应技能就不完整。移植文档的能力清单里，文件读写、跑 shell 是硬要求，没有替代方案；子代理派发、待办跟踪、联网抓取都标了”可降级”——比如没有子代理能力时，dispatching-parallel-agents 和 subagent-driven-development 会让模型改为内联执行或直接报告能力缺失，而不是去伪造一个工具调用。文档还提到某些平台需要额外开配置才有多 Agent 能力。
第四，有一条硬门槛决定了某些工具根本装不了：会话开始必须能自动注入，且不需要你每次手动触发。移植文档说得很绝——如果唯一的办法是让人每个会话手动粘一段提示词或者开个模式，这个平台就没法被正确支持，验收测试会挂。这不是懒得做，是这套东西的生效前提。
最后是它明确不管的事。这个项目不碰模型选型、不管 token 成本、不提供任何后端服务，安装之外的一切都交给你的工具本身。另外有一处需要你自己拍板：README.md 最后一节写明，brainstorming 的可选可视化伴随功能里那个 logo 默认从项目方网站加载，会带上正在使用的 superpowers 版本，不含项目、提示词或所用工具的信息；想关的话把环境变量 SUPERPOWERS_DISABLE_TELEMETRY 设成任意真值即可，它同时也认 Claude Code 的 DISABLE_TELEMETRY 与 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC。默认开、可关、可查证——这三点你自己判断能不能接受。
五、上手与避坑清单
按你的工具选安装命令，别照搬别人的。 README 给每个平台都列了对应命令：Claude Code 用 /plugin install superpowers@claude-plugins-official，或先 /plugin marketplace add obra/superpowers-marketplace 再装；Cursor 在 Agent 聊天里用 /add-plugin superpowers；Gemini CLI 用 gemini extensions install；Factory Droid 和 Copilot CLI 各有自己的 plugin marketplace add 加 plugin install 两步；pi 用 pi install git:github.com/obra/superpowers；OpenCode 在 README 里只让你把 .opencode/INSTALL.md 交给它自己去读，而 docs/README.opencode.md 写明了实质动作——往 opencode.json 的 plugin 数组里加一行 git 包规格再重启。会踩的原因是这些工具的插件生态看起来很像，命令却互不通用，抄错了往往不报错，只是什么都没发生。
多工具用户逐个装一遍。 会踩是因为”我装过了”这个直觉，而各平台的安装是完全独立的。避法是把安装当成每工具一次的动作，装完各跑一遍冒烟检查。
Windows 上先确认有 bash。 会踩是因为缺 bash 时 run-hook.cmd 是静默退出的，界面上没有任何异常。避法是照它找的那几个路径确认一下 Git for Windows 在不在，或者 PATH 上有没有 bash，再去问模型”你有哪些 superpowers”验证。
装完先开新会话再判断。 会踩是因为 bootstrap 只在会话开始注入，你在装插件之前就开着的那个会话永远不会有它。Kimi Code 的文档直接给了 /new，其他工具就重启或新开一个。
别去手改自己的全局配置来”帮它一把”。 会踩是因为看到没注入，很自然想往 ~/.gemini/config/AGENTS.md 或者某个 settings 文件里塞两句。移植文档把这条列成第二规则：一切都得通过平台自己的安装机制投递，不许动用户的文件。你手改出来的效果和真正装好不是一回事，下次更新还会和安装器打架，问题更难查。
更新路径要单独确认一次。 会踩是因为 README 只含糊说了更新往往是自动的、且依赖具体平台。实际上 Gemini CLI 有 gemini extensions update superpowers，Antigravity 按 README 是用同一条安装命令重装来更新，Kimi Code 走 /plugins 里的更新入口且更新后要 /new，OpenCode 则可能被缓存钉住需要清缓存。装完顺手把自己那条更新路径记下来。
排查顺序固定为：注入 → 发现 → 映射。 先问模型知不知道自己有 superpowers，这一步过不了就别看别的；过了但技能列不出来，去看清单文件里技能目录有没有被正确指向；技能能触发但里面说的动作落不到真实工具上，那是工具映射的事，去看 references/ 下对应平台那个文件或清单里的内联映射。这个顺序能省掉大量瞎试。
结尾：三个文件足够定位绝大多数问题
真要动手，接入本身的信息量其实不大。你只需要认准三样东西：skills/using-superpowers/SKILL.md 是被注入的那份内容，你那个平台的清单文件或插件模块是投递壳子，skills/using-superpowers/references/ 下对应的文件是工具映射。绝大多数”装完不生效”都能在这三处之一定位到。
给自己留一份最小自检：装完新开一个会话 → 问”你有哪些 superpowers” → 发 Let’s make a react todo list → 看 brainstorming 是不是在任何代码之前先触发。三步都过了才算装好。要往下读，docs/porting-to-a-new-harness.md 是这个仓库里对机制讲得最透的一份，哪怕你不打算移植新平台，它的附录里那张各平台对照表和”踩过的坑”清单也比安装说明更有用。
流程类工具的收益向来不在第一天。想先把判断建起来，可以顺着 Claude Code 技能机制 和 Claude Code hooks 理解注入与触发这两层，再看 Agent 框架调试 里排查思路怎么落到具体框架上。
本文属于 superpowers 方法论专题（共 30 篇，含三篇与其它开源 Agent 项目的对照）。想看把资产铺满的另一种取向，见 ECC 开源 Agent 套件专题。