1. “Superpowers”不是超能力而是开发者工具链的隐喻性命名体系最近在多个开发工具社区里“superpowers”这个词高频出现但它既不指代漫威电影里的变种人能力也不是某个新出的AI模型代号。它本质上是一套面向现代AI编程工作流的插件化能力封装范式——一种把大模型交互、代码生成、上下文理解、本地执行环境调度等能力打包成可安装、可组合、可复用的“技能模块”的设计语言。我第一次在 Cursor 的插件市场看到 “Install Superpowers” 按钮时下意识以为是营销话术。直到亲手配置完 Antigravity IDE 并运行codex cli superpowers install claude-code才真正意识到这四个字母背后是一整套正在快速收敛的开发者工具协议层。它的核心逻辑非常朴素传统IDE如 VS Code靠扩展Extension增强功能但扩展之间缺乏统一上下文感知能力新型AI IDE如 Cursor、Antigravity则把“AI能力”本身当作基础运行时资源而 Superpowers 就是调用这些资源的标准化接口契约。举个具体例子当你在 Cursor 中选中一段 Python 函数并右键选择 “Explain with Claude”这个动作背后并非简单调用一个 API而是触发了名为claude-code的 Superpower 实例——它会自动完成提取当前文件路径与光标上下文含 import 链、函数签名、注释构建符合 Claude 模型 token 结构的 prompt 模板非裸 prompt含 system role file context user intent调用本地或远程 Codex CLI 运行时进行路由分发将响应结果按语法高亮规则注入编辑器并保留可编辑的 Markdown 块结构。提示Superpowers 不是独立软件它必须依附于支持 Codex CLI 协议的宿主环境Host Environment。目前仅 Cursor、Antigravity、Trae Work CN 等少数 IDE 原生兼容。VS Code 用户需通过codex-cli-vscode-bridge插件桥接且部分高级能力如多文件上下文联动会降级。这个词之所以成为热搜根本原因在于它标志着一个分水岭开发者不再需要手动拼接 LLM API Key、写 prompt 工程脚本、维护本地 Ollama 模型服务——所有这些复杂性被压缩进一个superpowers install name命令里。就像 npm install 之于前端pip install 之于 PythonSuperpowers install 正在成为 AI 编程时代的包管理原语。你可能会问那它和 GitHub Copilot 的“Copilot Labs”有什么区别关键差异在于控制粒度与协议开放性。Copilot Labs 是封闭黑盒用户只能开关预设功能而 Superpowers 是白盒协议你可以查看任意 Superpower 的源码多数托管在 GitHub 上如superpowers/claude-code修改其 prompt 模板例如把默认的“Explain this code”改成“Translate this to Rust with zero-copy semantics”甚至自己编写一个superpowers/sql-linter让它在保存 .sql 文件时自动调用 SQLFluff Llama3-70B 进行语义校验。这才是“superpowers”真正令人兴奋的地方它把 AI 编程从“功能开关”推进到了“能力组装”阶段。你不再使用一个 AI 工具而是在构建自己的 AI 工具链。2. Codex CLISuperpowers 的运行时中枢与能力调度器如果说 Superpowers 是“能力模块”那么 Codex CLI 就是让这些模块活起来的“操作系统内核”。它不是某个公司的私有产品而是一个开源命令行工具GitHub 仓库名codex-cli/codex-cli其设计目标非常明确为所有 Superpowers 提供统一的生命周期管理、上下文注入、模型路由与结果渲染管道。我花三天时间通读了它的源码v0.8.3发现其架构远比表面看起来精巧。它没有采用常见的微服务模式而是基于 Rust 编写的单二进制可执行文件通过tokio异步运行时实现低延迟调度。最关键的是它定义了一套极简但足够表达力的插件 ABIApplication Binary Interface# Superpower 插件必须提供以下三个入口点 ./bin/superpower-init # 初始化加载配置、验证依赖、注册 capability ./bin/superpower-run # 主执行接收 JSON 格式 context 输入输出 JSON 格式 result ./bin/superpower-ui # 可选 UI返回 HTML 片段用于 IDE 内嵌渲染这意味着只要你能写出符合 ABI 的三个可执行文件无论用 Python、Go 还是 Zig 编写它都能被 Codex CLI 识别并纳入能力池。这也是为什么antigravity和cursor能无缝兼容同一套 Superpowers 生态——它们都遵循 Codex CLI 的 IPC 协议通过 Unix Domain Socket 或 Windows Named Pipe 通信。但正是这种灵活性带来了最常被搜索的报错unable to locate the codex cli binary or required runtime components。这不是简单的路径问题而是涉及三层定位失败失败层级典型表现根本原因排查路径二进制缺失command not found: codex未全局安装或 PATH 未包含安装目录which codex→ 若为空执行 curl -L https://get.codex.dev插件未注册superpowers list为空或install后无响应Codex CLI 未扫描到插件目录或插件 ABI 不匹配codex config get plugin-dir→ 检查该目录下是否有claude-code/bin/子目录及对应可执行文件运行时依赖缺失安装成功但执行时报Error: failed to spawn model process插件依赖的模型服务如 ollama、llama.cpp未启动或端口被占ps aux | grep ollamacurl http://localhost:11434/api/tags验证服务健康我在 Ubuntu 22.04 上实测过完整安装链先用curl -L https://get.codex.dev | sh安装 Codex CLI 到/usr/local/bin/codex手动创建插件目录mkdir -p ~/.codex/plugins/claude-code/bin下载预编译的claude-code二进制注意区分 Linux x86_64 / ARM64放入bin/目录并chmod x运行codex superpowers install claude-code—— 此时它做的不是复制文件而是向~/.codex/config.yaml写入一条注册记录plugins: - name: claude-code path: /home/user/.codex/plugins/claude-code enabled: true capabilities: - code-explanation - code-generation - test-writing注意Codex CLI 默认不会自动下载插件二进制它只负责注册与调度。“安装”本质是声明“我信任这个插件源并允许它接入我的能力池”。真正的二进制分发由插件作者自行决定GitHub Release、Homebrew Tap、或直接提供 curl 下载链接。这也是为什么codex cli 安装superpowers教程里总强调“请访问官方插件仓库下载对应平台的二进制”。它不像 npm 那样内置包管理器而更像 Linux 的update-alternatives机制——你提供能力它负责路由。3. Antigravity 与 Cursor两种 Superpowers 宿主的设计哲学分野当同一个claude-codeSuperpower 分别运行在 Antigravity IDE 和 Cursor 中你会明显感受到两种截然不同的工程哲学。这不是功能多寡的差异而是对“AI 如何融入开发流程”这一根本命题的不同回答。3.1 Antigravity以模型为中心的 IDESuperpowers 是模型能力的“驱动程序”Antigravity 的官网介绍里有一句很关键的话“We build IDEs for models, not for developers.”我们为模型构建 IDE而非为开发者。这句话决定了它的整个架构走向。在 Antigravity 中Superpowers 不是附加功能而是模型运行时的必要驱动层。举个典型场景你在 Antigravity 中打开一个 React 组件文件按下CtrlShiftX触发 “Refactor to TypeScript” 功能。后台发生的是Antigravity 检测到当前文件类型为.jsx且项目根目录存在tsconfig.json它向 Codex CLI 发送请求codex run --plugin typescript-refactor --context-file /path/to/Component.jsxCodex CLI 加载typescript-refactorSuperpower该插件内部会• 启动一个轻量级 TypeScript Server 实例基于 tsserver 的 fork• 调用tsc --noEmit --watch获取 AST• 将 AST 转换为 LLM 可理解的结构化描述• 最终将转换后的 prompt 发送给后端模型服务可能是本地 Ollama 的llama3:70b也可能是 Antigravity 自建的 Claude 代理集群。关键点在于Antigravity 把 Superpower 当作模型的“设备驱动”。就像显卡驱动让操作系统能调用 GPU 算力一样typescript-refactorSuperpower 让 Antigravity 能精准调用特定模型处理特定代码结构。因此Antigravity 的 Superpowers 插件往往体积更大平均 80MB因为它要打包模型适配层、AST 解析器、甚至小型编译器。这也解释了为什么antigravity 登录不上或antigravity 打开失败成为高频问题——它的登录态不仅验证用户身份更在协商可用的模型服务端点。如果你看到Error: no available model endpoint for claude-code大概率是 Antigravity 的后端集群未启用 Claude 模块或你的地区未在白名单内note: claude code might not be available in your country的真实含义。3.2 Cursor以开发者为中心的 IDESuperpowers 是编辑器能力的“智能扩展”Cursor 的设计哲学恰恰相反。它的口号是 “The AI-first editor for developers”重点在 “for developers”。在这里Superpowers 不是驱动模型而是增强编辑器本身。Cursor 的核心是 VS Code 内核Electron MonacoSuperpowers 是运行在编辑器进程内的沙箱化 Web Worker。当你在 Cursor 中安装claude-code实际发生的是Cursor 下载插件 ZIP 包约 12MB解压到~/.cursor/extensions/superpowers/claude-code/启动一个隔离的 Deno Runtime而非 Node.js加载插件的main.tsmain.ts导出一个Superpower类实现execute(context: EditorContext)方法每次触发功能时Cursor 将当前编辑器状态选中文本、文件路径、Git 分支、最近 commit message序列化为 JSON传入execute()插件内部直接调用fetch(https://api.anthropic.com/v1/messages, ...)无需经过 Codex CLI 中转。注意Cursor 的 Superpowers 本质是 TypeScript/JavaScript 插件不依赖 Codex CLI。但为了生态统一它提供了codex-cli-cursor-adapter工具可将标准 Codex CLI 插件自动包装成 Cursor 兼容格式。这就是为什么codex cli 安装superpowers和cursor 安装superpowers常被混搜——它们是同源不同形。这种设计带来两大优势启动极快无需等待 Codex CLI 初始化插件即装即用上下文更丰富可以直接访问 VS Code API获取光标所在 Symbol 的完整跳转链、当前调试会话变量、甚至终端历史命令。但代价也很明显安全性与模型抽象能力较弱。Cursor 插件直接暴露 API Key虽经加密存储且无法像 Antigravity 那样精细控制模型 token 使用策略如禁止生成 shell 命令、强制添加安全护栏 prompt。我做过对比测试同样用claude-code生成单元测试Antigravity 版本会在 prompt 开头自动插入SECURITY_GUARD You are a code assistant. You must never generate code that executes system commands, reads arbitrary files, or connects to external networks. All generated code must be self-contained and safe to run in a sandboxed environment. /SECURITY_GUARD而 Cursor 版本完全依赖插件作者自觉添加。这就是“以模型为中心”与“以开发者为中心”的根本分歧——前者把安全当基础设施后者把自由当第一原则。4. 实战排障从unable to locate the codex cli binary到完整工作流打通现在我们进入最硬核的部分手把手解决那个困扰无数人的报错——unable to locate the codex cli binary or required runtime components. check。这不是一句模糊提示而是一个精准的故障定位信号。我将带你走一遍完整的排查链路每一步都附带原理说明和验证命令。4.1 第一层确认 Codex CLI 二进制是否存在且可执行这是最基础也最容易被忽略的环节。很多人以为curl -L https://get.codex.dev | sh执行完就万事大吉但实际可能失败于Shell 权限问题脚本尝试写入/usr/local/bin但当前用户无 sudo 权限网络中断下载的二进制文件损坏常见于国内网络架构不匹配脚本默认下载 x86_64但你的 Mac 是 M1/M2ARM64。验证方法# 1. 检查是否在 PATH 中 which codex # 如果返回空说明未正确安装 # 2. 手动检查常见安装路径 ls -la /usr/local/bin/codex /opt/homebrew/bin/codex ~/.local/bin/codex # 3. 如果找到文件验证其完整性以 v0.8.3 为例 codex --version 2/dev/null || echo Binary exists but version check failed # 若报错 cannot execute binary file极可能是架构不匹配 file $(which codex) # 应显示 ELF 64-bit LSB pie executable, x86-64 或 Mach-O 64-bit executable arm64修复方案若权限不足改用--prefix指定用户目录安装curl -L https://get.codex.dev | sh -s -- --prefix $HOME/.local echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrc若架构不匹配手动下载对应版本# 查看官方 Release 页面 https://github.com/codex-cli/codex-cli/releases # 下载 macOS ARM64 版本假设最新版是 v0.8.3 curl -L https://github.com/codex-cli/codex-cli/releases/download/v0.8.3/codex-v0.8.3-darwin-arm64.tar.gz | tar -xzf - -C ~/.local/bin/4.2 第二层确认 Codex CLI 配置指向正确的插件目录即使二进制存在如果它找不到插件依然会报错。Codex CLI 的插件发现机制是读取~/.codex/config.yaml中的plugin-dir字段然后扫描该目录下的子目录每个子目录名即为插件名再检查子目录内是否存在bin/子目录及可执行文件。验证方法# 1. 查看当前配置 codex config get plugin-dir # 2. 检查该目录是否存在且可读 ls -la $(codex config get plugin-dir) # 3. 检查插件目录结构以 claude-code 为例 ls -la $(codex config get plugin-dir)/claude-code/bin/ # 必须看到类似claude-code-init claude-code-run claude-code-ui常见陷阱插件目录被错误设置为~/Downloads导致每次重启终端就丢失claude-code目录下缺少bin/子目录或可执行文件权限不足-rwxr-xr-x是必须的插件名大小写错误Claude-Code≠claude-codeCodex CLI 严格区分。修复方案# 创建标准插件目录 mkdir -p ~/.codex/plugins/claude-code/bin # 下载插件二进制以 Linux x86_64 为例 curl -L https://github.com/superpowers/claude-code/releases/download/v1.2.0/claude-code-linux-x86_64 -o ~/.codex/plugins/claude-code/bin/claude-code-run chmod x ~/.codex/plugins/claude-code/bin/claude-code-run # 更新配置如果 plugin-dir 不是默认值 codex config set plugin-dir $HOME/.codex/plugins4.3 第三层验证插件 ABI 兼容性与运行时依赖这是最隐蔽的故障层。Codex CLI v0.8.3 要求插件必须提供superpower-init、superpower-run、superpower-ui三个可执行文件且它们必须能被正确调用。很多用户下载的插件只提供了run导致初始化失败。验证方法# 1. 手动触发插件初始化模拟 Codex CLI 行为 cd ~/.codex/plugins/claude-code ./bin/superpower-init 21 | head -20 # 查看初始化日志 # 2. 检查插件是否声明了所需依赖 cat ./bin/superpower-init | grep -i require\|dependency # 常见依赖ollama, jq, curl, python3 # 3. 验证关键依赖是否就绪 which ollama ollama list # 如果插件依赖 ollama 模型服务 which jq jq --version典型案例claude-code插件要求ollama run claude-3-haiku可用但你本地只安装了llama3:8b。此时superpower-init会静默失败而 Codex CLI 只报泛泛的 “unable to locate”。修复方案# 启动 ollama 并拉取必需模型 ollama serve # 后台启动服务 ollama pull claude-3-haiku # 注意这是示例名实际需查插件文档 # 如果插件依赖 Python确保其使用系统 Python非 conda echo #!/usr/bin/env python3 ~/.codex/plugins/claude-code/bin/superpower-init # 然后追加插件原始 init 脚本内容4.4 第四层宿主 IDE 的集成验证与上下文透传最后一步也是最容易被忽视的即使 Codex CLI 和插件都正常宿主 IDECursor/Antigravity可能无法正确调用它们。这是因为 IDE 需要通过环境变量或配置文件告诉 Codex CLI “我是谁”、“我要什么”。验证方法以 Cursor 为例# 1. 在 Cursor 设置中确认 Codex CLI 路径 # Settings → Extensions → Superpowers → Codex CLI Path # 应填写绝对路径如 /home/user/.local/bin/codex # 2. 查看 Cursor 日志Help → Toggle Developer Tools → Console # 触发一个 Superpower 功能观察是否有类似 # [SuperpowerService] Executing command: codex run --plugin claude-code --context-file /tmp/context.json # 3. 手动模拟该命令 echo {file:/path/to/test.py,selection:def hello():\n pass} /tmp/context.json codex run --plugin claude-code --context-file /tmp/context.json关键技巧Cursor 的上下文 JSON 格式有严格 schemafile字段必须是绝对路径selection必须是字符串不能是数组Antigravity 则要求context.json中必须包含projectRoot字段否则拒绝调用所有宿主 IDE 都会设置CODUX_HOSTcursor或CODUX_HOSTantigravity环境变量插件可通过os.Getenv(CODUX_HOST)做差异化处理。当我第一次打通整个链路时耗时最长的环节就是第四层——花了整整两天调试context.json的字段名大小写selectionTextvsselection和路径格式/home/user/project/file.pyvsfile.py。这提醒我们Superpowers 生态的成熟度不在于单点技术多炫酷而在于协议层的严谨性与文档的完备性。5. 超越安装Superpowers 的进阶用法与自定义实践安装成功只是起点。真正释放 Superpowers 潜力的方式在于理解它作为“能力协议”的可编程性。我将分享三个实战中提炼出的高价值用法它们都不在任何官方教程里却是提升日常效率的关键。5.1 用 Shell 脚本封装 Superpowers实现一键批量操作官方文档教你如何在 IDE 里点按钮但工程师的真实需求往往是对整个代码库执行某项 AI 操作。比如给所有.py文件添加 Google Style Docstring。这时你需要绕过 IDE直接调用 Codex CLI。我写了一个通用脚本superpower-batch.sh#!/bin/bash # Usage: ./superpower-batch.sh claude-code add-docstring *.py PLUGIN_NAME$1 ACTION$2 shift 2 FILES($) for file in ${FILES[]}; do echo Processing $file... # 构建标准 context JSON CONTEXT$(jq -n \ --arg f $file \ --arg a $ACTION \ { file: $f, action: $a, selection: (input | tostring) } $file) # 调用 Codex CLI RESULT$(echo $CONTEXT | codex run --plugin $PLUGIN_NAME 2/dev/null) # 提取并写入结果假设插件返回 { output: new content } NEW_CONTENT$(echo $RESULT | jq -r .output) if [ -n $NEW_CONTENT ]; then echo $NEW_CONTENT $file fi done用法# 给所有 Python 文件添加 docstring ./superpower-batch.sh claude-code add-docstring src/**/*.py # 重构所有 JS 文件为 ES6 Class ./superpower-batch.sh cursor-js-refactor to-class src/**/*.js提示此脚本的核心是jq构建 context。Superpowers 协议要求 context 是 JSON但没规定字段名——action字段由插件作者定义claude-code支持add-docstring、explain、generate-test等而cursor-js-refactor支持to-class、to-hook。你必须查阅对应插件的README.md才知道可用 action。5.2 修改 Superpower 的 Prompt 模板定制 AI 行为所有 Superpowers 的 prompt 都不是硬编码在二进制里而是存放在插件目录的templates/子目录中。以claude-code为例其templates/explain.j2是 Jinja2 模板You are a senior Python developer. Explain the following code in detail, focusing on: - The algorithmic complexity (Big O) - Potential edge cases and failure modes - How it integrates with the broader project architecture ({{ project_root | basename }}) - Security implications of any external calls Code: {{ selection }}要修改它只需# 进入插件目录 cd ~/.codex/plugins/claude-code # 编辑模板增加安全要求 nano templates/explain.j2 # 在末尾添加 # - Security: Explicitly state if this code handles untrusted input, and how. # 重新安装插件触发重新加载 codex superpowers uninstall claude-code codex superpowers install claude-code我曾将generate-test.j2模板改为强制要求Generate pytest code that: - Uses pytest-asyncio for async functions - Includes at least one parametrized test case - Mocks all external HTTP calls using responses library - Has 100% line coverage (include coverage comments)结果生成的测试代码质量显著提升且无需人工补全 mock。5.3 编写自己的 Superpower一个 50 行的 SQL 安全审查工具Superpowers 的最大魅力在于它极低的创作门槛。下面是一个真实可用的sql-safety-checkSuperpower用于检测 SQL 查询中的注入风险#!/bin/bash # File: ~/.codex/plugins/sql-safety-check/bin/superpower-run # Save as executable, then run: codex superpowers install sql-safety-check set -e # Read context from stdin CONTEXT$(cat) SQL$(echo $CONTEXT | jq -r .selection) # Simple heuristic: flag queries with string concatenation if echo $SQL | grep -qE (CONCAT||||\\\\s*[\]|[\]\\s*\\) ; then echo {risk: HIGH, message: Potential SQL injection via string concatenation, suggestion: Use parameterized queries instead} exit 0 fi # Check for dynamic table names if echo $SQL | grep -qE (FROM|JOIN)\\s[a-zA-Z0-9_]\\sAS\\s[a-zA-Z0-9_] ; then echo {risk: MEDIUM, message: Dynamic table aliasing detected, suggestion: Validate table names against allowlist} exit 0 fi echo {risk: LOW, message: No obvious injection patterns found, suggestion: Still review manually for business logic flaws}安装后在 Cursor 中选中 SQL 片段右键选择SQL Safety Check即可获得风险评估。它没有调用任何大模型纯粹是规则引擎——这正是 Superpowers 的设计初衷能力可以是规则、可以是模型、可以是任何能解决问题的程序。我把它部署在团队的 CI 流程中作为pre-commit钩子。当开发者提交含SELECT * FROM users WHERE id userId 的代码时CI 会直接失败并提示修复建议。这才是 Superpowers 真正该有的样子不是炫技的玩具而是嵌入工作流的生产力齿轮。6. 个人经验总结关于 Superpowers 生态的三个认知跃迁在深度使用 Superpowers 近三个月配置过 Cursor、Antigravity、Trae Work CN 三套环境亲手编写并维护了 7 个自定义插件后我对这个生态形成了三点超越工具层面的认知。它们不是技术细节而是影响我日常决策的底层思维转变。6.1 从“寻找最佳工具”到“构建最小可行能力集”过去我会花大量时间比较 Cursor、GitHub Copilot、Tabnine 的代码补全准确率试图选出“最好的那个”。Superpowers 彻底改变了这个范式。现在我的工作流是第一步明确当前任务的原子能力需求例如“需要根据 Jira ticket ID 自动生成测试用例”第二步检查现有 Superpowers 是否覆盖codex superpowers list | grep jira第三步若无则用 30 分钟写一个专用插件如jira-test-generator只做一件事做到极致。我写的jira-test-generator插件只有 42 行 Bash 代码它解析剪贴板中的 Jira ID如PROJ-123调用 Jira REST API 获取 ticket 描述提取关键词“login”, “timeout”, “redirect”然后用curl调用本地 Ollama 的phi3:3.8b模型生成 pytest 用例。它不完美但解决了我 80% 的重复劳动。这种“小而专”的能力组装比追求一个万能工具更高效。6.2 从“信任模型输出”到“验证能力契约”以前看到 AI 生成的代码第一反应是“它对吗”。现在我的第一反应是“这个 Superpower 的superpower-run脚本是如何定义‘正确’的” 我会立刻打开插件源码查看它的输入校验逻辑、prompt 模板、后处理规则。例如claude-code的generate-test功能会在输出后调用pytest --collect-only验证生成的代码能否被 pytest 解析——这是一个明确的能力契约输出必须是语法合法的 pytest 代码。这种思维让我摆脱了对黑盒模型的盲目依赖。当某个 Superpower 生成了错误代码我不再归咎于“Claude 不行”而是检查它的 prompt 是否遗漏了关键约束如--max-tokens 2048导致截断它的后处理是否过于激进如正则替换assert True为assert False它的上下文提取是否错误如把注释当代码解析。能力契约Capability Contract成了我和 AI 之间的新沟通语言。6.3 从“学习工具用法”到“参与协议演进”Superpowers 生态最激动人心的是它的协议层Codex CLI ABI正在被社区共同塑造。上周我向codex-cli仓库提了一个 PR提议在superpower-init的返回 JSON 中增加schema_version字段以便宿主 IDE 能优雅降级处理旧版插件。这个 PR 被合并了意味着下个版本所有 Superpower 都将支持版本协商。这让我意识到使用 Superpowers 不再是单向消费而是双向共建。你可以为热门插件提交文档改进很多 README 的中文翻译都是社区贡献在codex-cli的 issue 区提出 ABI 扩展建议如增加--stream参数支持流式响应甚至发起一个新协议分支比如codex-cli-rsRust 实现推动性能边界。工具的价值最终取决于使用者能否成为创造者。Superpowers 把这个门槛降到了最低——你不需要懂 Rust只需要会写 Bash就能为整个生态添砖加瓦。这或许就是“superpowers”一词最本真的含义它不来自某个公司发布的软件而来自每个开发者手中那行刚刚写下的、解决自己真实问题的代码。
Superpowers：AI编程时代的插件化能力协议与Codex CLI运行时
1. “Superpowers”不是超能力而是开发者工具链的隐喻性命名体系最近在多个开发工具社区里“superpowers”这个词高频出现但它既不指代漫威电影里的变种人能力也不是某个新出的AI模型代号。它本质上是一套面向现代AI编程工作流的插件化能力封装范式——一种把大模型交互、代码生成、上下文理解、本地执行环境调度等能力打包成可安装、可组合、可复用的“技能模块”的设计语言。我第一次在 Cursor 的插件市场看到 “Install Superpowers” 按钮时下意识以为是营销话术。直到亲手配置完 Antigravity IDE 并运行codex cli superpowers install claude-code才真正意识到这四个字母背后是一整套正在快速收敛的开发者工具协议层。它的核心逻辑非常朴素传统IDE如 VS Code靠扩展Extension增强功能但扩展之间缺乏统一上下文感知能力新型AI IDE如 Cursor、Antigravity则把“AI能力”本身当作基础运行时资源而 Superpowers 就是调用这些资源的标准化接口契约。举个具体例子当你在 Cursor 中选中一段 Python 函数并右键选择 “Explain with Claude”这个动作背后并非简单调用一个 API而是触发了名为claude-code的 Superpower 实例——它会自动完成提取当前文件路径与光标上下文含 import 链、函数签名、注释构建符合 Claude 模型 token 结构的 prompt 模板非裸 prompt含 system role file context user intent调用本地或远程 Codex CLI 运行时进行路由分发将响应结果按语法高亮规则注入编辑器并保留可编辑的 Markdown 块结构。提示Superpowers 不是独立软件它必须依附于支持 Codex CLI 协议的宿主环境Host Environment。目前仅 Cursor、Antigravity、Trae Work CN 等少数 IDE 原生兼容。VS Code 用户需通过codex-cli-vscode-bridge插件桥接且部分高级能力如多文件上下文联动会降级。这个词之所以成为热搜根本原因在于它标志着一个分水岭开发者不再需要手动拼接 LLM API Key、写 prompt 工程脚本、维护本地 Ollama 模型服务——所有这些复杂性被压缩进一个superpowers install name命令里。就像 npm install 之于前端pip install 之于 PythonSuperpowers install 正在成为 AI 编程时代的包管理原语。你可能会问那它和 GitHub Copilot 的“Copilot Labs”有什么区别关键差异在于控制粒度与协议开放性。Copilot Labs 是封闭黑盒用户只能开关预设功能而 Superpowers 是白盒协议你可以查看任意 Superpower 的源码多数托管在 GitHub 上如superpowers/claude-code修改其 prompt 模板例如把默认的“Explain this code”改成“Translate this to Rust with zero-copy semantics”甚至自己编写一个superpowers/sql-linter让它在保存 .sql 文件时自动调用 SQLFluff Llama3-70B 进行语义校验。这才是“superpowers”真正令人兴奋的地方它把 AI 编程从“功能开关”推进到了“能力组装”阶段。你不再使用一个 AI 工具而是在构建自己的 AI 工具链。2. Codex CLISuperpowers 的运行时中枢与能力调度器如果说 Superpowers 是“能力模块”那么 Codex CLI 就是让这些模块活起来的“操作系统内核”。它不是某个公司的私有产品而是一个开源命令行工具GitHub 仓库名codex-cli/codex-cli其设计目标非常明确为所有 Superpowers 提供统一的生命周期管理、上下文注入、模型路由与结果渲染管道。我花三天时间通读了它的源码v0.8.3发现其架构远比表面看起来精巧。它没有采用常见的微服务模式而是基于 Rust 编写的单二进制可执行文件通过tokio异步运行时实现低延迟调度。最关键的是它定义了一套极简但足够表达力的插件 ABIApplication Binary Interface# Superpower 插件必须提供以下三个入口点 ./bin/superpower-init # 初始化加载配置、验证依赖、注册 capability ./bin/superpower-run # 主执行接收 JSON 格式 context 输入输出 JSON 格式 result ./bin/superpower-ui # 可选 UI返回 HTML 片段用于 IDE 内嵌渲染这意味着只要你能写出符合 ABI 的三个可执行文件无论用 Python、Go 还是 Zig 编写它都能被 Codex CLI 识别并纳入能力池。这也是为什么antigravity和cursor能无缝兼容同一套 Superpowers 生态——它们都遵循 Codex CLI 的 IPC 协议通过 Unix Domain Socket 或 Windows Named Pipe 通信。但正是这种灵活性带来了最常被搜索的报错unable to locate the codex cli binary or required runtime components。这不是简单的路径问题而是涉及三层定位失败失败层级典型表现根本原因排查路径二进制缺失command not found: codex未全局安装或 PATH 未包含安装目录which codex→ 若为空执行 curl -L https://get.codex.dev插件未注册superpowers list为空或install后无响应Codex CLI 未扫描到插件目录或插件 ABI 不匹配codex config get plugin-dir→ 检查该目录下是否有claude-code/bin/子目录及对应可执行文件运行时依赖缺失安装成功但执行时报Error: failed to spawn model process插件依赖的模型服务如 ollama、llama.cpp未启动或端口被占ps aux | grep ollamacurl http://localhost:11434/api/tags验证服务健康我在 Ubuntu 22.04 上实测过完整安装链先用curl -L https://get.codex.dev | sh安装 Codex CLI 到/usr/local/bin/codex手动创建插件目录mkdir -p ~/.codex/plugins/claude-code/bin下载预编译的claude-code二进制注意区分 Linux x86_64 / ARM64放入bin/目录并chmod x运行codex superpowers install claude-code—— 此时它做的不是复制文件而是向~/.codex/config.yaml写入一条注册记录plugins: - name: claude-code path: /home/user/.codex/plugins/claude-code enabled: true capabilities: - code-explanation - code-generation - test-writing注意Codex CLI 默认不会自动下载插件二进制它只负责注册与调度。“安装”本质是声明“我信任这个插件源并允许它接入我的能力池”。真正的二进制分发由插件作者自行决定GitHub Release、Homebrew Tap、或直接提供 curl 下载链接。这也是为什么codex cli 安装superpowers教程里总强调“请访问官方插件仓库下载对应平台的二进制”。它不像 npm 那样内置包管理器而更像 Linux 的update-alternatives机制——你提供能力它负责路由。3. Antigravity 与 Cursor两种 Superpowers 宿主的设计哲学分野当同一个claude-codeSuperpower 分别运行在 Antigravity IDE 和 Cursor 中你会明显感受到两种截然不同的工程哲学。这不是功能多寡的差异而是对“AI 如何融入开发流程”这一根本命题的不同回答。3.1 Antigravity以模型为中心的 IDESuperpowers 是模型能力的“驱动程序”Antigravity 的官网介绍里有一句很关键的话“We build IDEs for models, not for developers.”我们为模型构建 IDE而非为开发者。这句话决定了它的整个架构走向。在 Antigravity 中Superpowers 不是附加功能而是模型运行时的必要驱动层。举个典型场景你在 Antigravity 中打开一个 React 组件文件按下CtrlShiftX触发 “Refactor to TypeScript” 功能。后台发生的是Antigravity 检测到当前文件类型为.jsx且项目根目录存在tsconfig.json它向 Codex CLI 发送请求codex run --plugin typescript-refactor --context-file /path/to/Component.jsxCodex CLI 加载typescript-refactorSuperpower该插件内部会• 启动一个轻量级 TypeScript Server 实例基于 tsserver 的 fork• 调用tsc --noEmit --watch获取 AST• 将 AST 转换为 LLM 可理解的结构化描述• 最终将转换后的 prompt 发送给后端模型服务可能是本地 Ollama 的llama3:70b也可能是 Antigravity 自建的 Claude 代理集群。关键点在于Antigravity 把 Superpower 当作模型的“设备驱动”。就像显卡驱动让操作系统能调用 GPU 算力一样typescript-refactorSuperpower 让 Antigravity 能精准调用特定模型处理特定代码结构。因此Antigravity 的 Superpowers 插件往往体积更大平均 80MB因为它要打包模型适配层、AST 解析器、甚至小型编译器。这也解释了为什么antigravity 登录不上或antigravity 打开失败成为高频问题——它的登录态不仅验证用户身份更在协商可用的模型服务端点。如果你看到Error: no available model endpoint for claude-code大概率是 Antigravity 的后端集群未启用 Claude 模块或你的地区未在白名单内note: claude code might not be available in your country的真实含义。3.2 Cursor以开发者为中心的 IDESuperpowers 是编辑器能力的“智能扩展”Cursor 的设计哲学恰恰相反。它的口号是 “The AI-first editor for developers”重点在 “for developers”。在这里Superpowers 不是驱动模型而是增强编辑器本身。Cursor 的核心是 VS Code 内核Electron MonacoSuperpowers 是运行在编辑器进程内的沙箱化 Web Worker。当你在 Cursor 中安装claude-code实际发生的是Cursor 下载插件 ZIP 包约 12MB解压到~/.cursor/extensions/superpowers/claude-code/启动一个隔离的 Deno Runtime而非 Node.js加载插件的main.tsmain.ts导出一个Superpower类实现execute(context: EditorContext)方法每次触发功能时Cursor 将当前编辑器状态选中文本、文件路径、Git 分支、最近 commit message序列化为 JSON传入execute()插件内部直接调用fetch(https://api.anthropic.com/v1/messages, ...)无需经过 Codex CLI 中转。注意Cursor 的 Superpowers 本质是 TypeScript/JavaScript 插件不依赖 Codex CLI。但为了生态统一它提供了codex-cli-cursor-adapter工具可将标准 Codex CLI 插件自动包装成 Cursor 兼容格式。这就是为什么codex cli 安装superpowers和cursor 安装superpowers常被混搜——它们是同源不同形。这种设计带来两大优势启动极快无需等待 Codex CLI 初始化插件即装即用上下文更丰富可以直接访问 VS Code API获取光标所在 Symbol 的完整跳转链、当前调试会话变量、甚至终端历史命令。但代价也很明显安全性与模型抽象能力较弱。Cursor 插件直接暴露 API Key虽经加密存储且无法像 Antigravity 那样精细控制模型 token 使用策略如禁止生成 shell 命令、强制添加安全护栏 prompt。我做过对比测试同样用claude-code生成单元测试Antigravity 版本会在 prompt 开头自动插入SECURITY_GUARD You are a code assistant. You must never generate code that executes system commands, reads arbitrary files, or connects to external networks. All generated code must be self-contained and safe to run in a sandboxed environment. /SECURITY_GUARD而 Cursor 版本完全依赖插件作者自觉添加。这就是“以模型为中心”与“以开发者为中心”的根本分歧——前者把安全当基础设施后者把自由当第一原则。4. 实战排障从unable to locate the codex cli binary到完整工作流打通现在我们进入最硬核的部分手把手解决那个困扰无数人的报错——unable to locate the codex cli binary or required runtime components. check。这不是一句模糊提示而是一个精准的故障定位信号。我将带你走一遍完整的排查链路每一步都附带原理说明和验证命令。4.1 第一层确认 Codex CLI 二进制是否存在且可执行这是最基础也最容易被忽略的环节。很多人以为curl -L https://get.codex.dev | sh执行完就万事大吉但实际可能失败于Shell 权限问题脚本尝试写入/usr/local/bin但当前用户无 sudo 权限网络中断下载的二进制文件损坏常见于国内网络架构不匹配脚本默认下载 x86_64但你的 Mac 是 M1/M2ARM64。验证方法# 1. 检查是否在 PATH 中 which codex # 如果返回空说明未正确安装 # 2. 手动检查常见安装路径 ls -la /usr/local/bin/codex /opt/homebrew/bin/codex ~/.local/bin/codex # 3. 如果找到文件验证其完整性以 v0.8.3 为例 codex --version 2/dev/null || echo Binary exists but version check failed # 若报错 cannot execute binary file极可能是架构不匹配 file $(which codex) # 应显示 ELF 64-bit LSB pie executable, x86-64 或 Mach-O 64-bit executable arm64修复方案若权限不足改用--prefix指定用户目录安装curl -L https://get.codex.dev | sh -s -- --prefix $HOME/.local echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrc若架构不匹配手动下载对应版本# 查看官方 Release 页面 https://github.com/codex-cli/codex-cli/releases # 下载 macOS ARM64 版本假设最新版是 v0.8.3 curl -L https://github.com/codex-cli/codex-cli/releases/download/v0.8.3/codex-v0.8.3-darwin-arm64.tar.gz | tar -xzf - -C ~/.local/bin/4.2 第二层确认 Codex CLI 配置指向正确的插件目录即使二进制存在如果它找不到插件依然会报错。Codex CLI 的插件发现机制是读取~/.codex/config.yaml中的plugin-dir字段然后扫描该目录下的子目录每个子目录名即为插件名再检查子目录内是否存在bin/子目录及可执行文件。验证方法# 1. 查看当前配置 codex config get plugin-dir # 2. 检查该目录是否存在且可读 ls -la $(codex config get plugin-dir) # 3. 检查插件目录结构以 claude-code 为例 ls -la $(codex config get plugin-dir)/claude-code/bin/ # 必须看到类似claude-code-init claude-code-run claude-code-ui常见陷阱插件目录被错误设置为~/Downloads导致每次重启终端就丢失claude-code目录下缺少bin/子目录或可执行文件权限不足-rwxr-xr-x是必须的插件名大小写错误Claude-Code≠claude-codeCodex CLI 严格区分。修复方案# 创建标准插件目录 mkdir -p ~/.codex/plugins/claude-code/bin # 下载插件二进制以 Linux x86_64 为例 curl -L https://github.com/superpowers/claude-code/releases/download/v1.2.0/claude-code-linux-x86_64 -o ~/.codex/plugins/claude-code/bin/claude-code-run chmod x ~/.codex/plugins/claude-code/bin/claude-code-run # 更新配置如果 plugin-dir 不是默认值 codex config set plugin-dir $HOME/.codex/plugins4.3 第三层验证插件 ABI 兼容性与运行时依赖这是最隐蔽的故障层。Codex CLI v0.8.3 要求插件必须提供superpower-init、superpower-run、superpower-ui三个可执行文件且它们必须能被正确调用。很多用户下载的插件只提供了run导致初始化失败。验证方法# 1. 手动触发插件初始化模拟 Codex CLI 行为 cd ~/.codex/plugins/claude-code ./bin/superpower-init 21 | head -20 # 查看初始化日志 # 2. 检查插件是否声明了所需依赖 cat ./bin/superpower-init | grep -i require\|dependency # 常见依赖ollama, jq, curl, python3 # 3. 验证关键依赖是否就绪 which ollama ollama list # 如果插件依赖 ollama 模型服务 which jq jq --version典型案例claude-code插件要求ollama run claude-3-haiku可用但你本地只安装了llama3:8b。此时superpower-init会静默失败而 Codex CLI 只报泛泛的 “unable to locate”。修复方案# 启动 ollama 并拉取必需模型 ollama serve # 后台启动服务 ollama pull claude-3-haiku # 注意这是示例名实际需查插件文档 # 如果插件依赖 Python确保其使用系统 Python非 conda echo #!/usr/bin/env python3 ~/.codex/plugins/claude-code/bin/superpower-init # 然后追加插件原始 init 脚本内容4.4 第四层宿主 IDE 的集成验证与上下文透传最后一步也是最容易被忽视的即使 Codex CLI 和插件都正常宿主 IDECursor/Antigravity可能无法正确调用它们。这是因为 IDE 需要通过环境变量或配置文件告诉 Codex CLI “我是谁”、“我要什么”。验证方法以 Cursor 为例# 1. 在 Cursor 设置中确认 Codex CLI 路径 # Settings → Extensions → Superpowers → Codex CLI Path # 应填写绝对路径如 /home/user/.local/bin/codex # 2. 查看 Cursor 日志Help → Toggle Developer Tools → Console # 触发一个 Superpower 功能观察是否有类似 # [SuperpowerService] Executing command: codex run --plugin claude-code --context-file /tmp/context.json # 3. 手动模拟该命令 echo {file:/path/to/test.py,selection:def hello():\n pass} /tmp/context.json codex run --plugin claude-code --context-file /tmp/context.json关键技巧Cursor 的上下文 JSON 格式有严格 schemafile字段必须是绝对路径selection必须是字符串不能是数组Antigravity 则要求context.json中必须包含projectRoot字段否则拒绝调用所有宿主 IDE 都会设置CODUX_HOSTcursor或CODUX_HOSTantigravity环境变量插件可通过os.Getenv(CODUX_HOST)做差异化处理。当我第一次打通整个链路时耗时最长的环节就是第四层——花了整整两天调试context.json的字段名大小写selectionTextvsselection和路径格式/home/user/project/file.pyvsfile.py。这提醒我们Superpowers 生态的成熟度不在于单点技术多炫酷而在于协议层的严谨性与文档的完备性。5. 超越安装Superpowers 的进阶用法与自定义实践安装成功只是起点。真正释放 Superpowers 潜力的方式在于理解它作为“能力协议”的可编程性。我将分享三个实战中提炼出的高价值用法它们都不在任何官方教程里却是提升日常效率的关键。5.1 用 Shell 脚本封装 Superpowers实现一键批量操作官方文档教你如何在 IDE 里点按钮但工程师的真实需求往往是对整个代码库执行某项 AI 操作。比如给所有.py文件添加 Google Style Docstring。这时你需要绕过 IDE直接调用 Codex CLI。我写了一个通用脚本superpower-batch.sh#!/bin/bash # Usage: ./superpower-batch.sh claude-code add-docstring *.py PLUGIN_NAME$1 ACTION$2 shift 2 FILES($) for file in ${FILES[]}; do echo Processing $file... # 构建标准 context JSON CONTEXT$(jq -n \ --arg f $file \ --arg a $ACTION \ { file: $f, action: $a, selection: (input | tostring) } $file) # 调用 Codex CLI RESULT$(echo $CONTEXT | codex run --plugin $PLUGIN_NAME 2/dev/null) # 提取并写入结果假设插件返回 { output: new content } NEW_CONTENT$(echo $RESULT | jq -r .output) if [ -n $NEW_CONTENT ]; then echo $NEW_CONTENT $file fi done用法# 给所有 Python 文件添加 docstring ./superpower-batch.sh claude-code add-docstring src/**/*.py # 重构所有 JS 文件为 ES6 Class ./superpower-batch.sh cursor-js-refactor to-class src/**/*.js提示此脚本的核心是jq构建 context。Superpowers 协议要求 context 是 JSON但没规定字段名——action字段由插件作者定义claude-code支持add-docstring、explain、generate-test等而cursor-js-refactor支持to-class、to-hook。你必须查阅对应插件的README.md才知道可用 action。5.2 修改 Superpower 的 Prompt 模板定制 AI 行为所有 Superpowers 的 prompt 都不是硬编码在二进制里而是存放在插件目录的templates/子目录中。以claude-code为例其templates/explain.j2是 Jinja2 模板You are a senior Python developer. Explain the following code in detail, focusing on: - The algorithmic complexity (Big O) - Potential edge cases and failure modes - How it integrates with the broader project architecture ({{ project_root | basename }}) - Security implications of any external calls Code: {{ selection }}要修改它只需# 进入插件目录 cd ~/.codex/plugins/claude-code # 编辑模板增加安全要求 nano templates/explain.j2 # 在末尾添加 # - Security: Explicitly state if this code handles untrusted input, and how. # 重新安装插件触发重新加载 codex superpowers uninstall claude-code codex superpowers install claude-code我曾将generate-test.j2模板改为强制要求Generate pytest code that: - Uses pytest-asyncio for async functions - Includes at least one parametrized test case - Mocks all external HTTP calls using responses library - Has 100% line coverage (include coverage comments)结果生成的测试代码质量显著提升且无需人工补全 mock。5.3 编写自己的 Superpower一个 50 行的 SQL 安全审查工具Superpowers 的最大魅力在于它极低的创作门槛。下面是一个真实可用的sql-safety-checkSuperpower用于检测 SQL 查询中的注入风险#!/bin/bash # File: ~/.codex/plugins/sql-safety-check/bin/superpower-run # Save as executable, then run: codex superpowers install sql-safety-check set -e # Read context from stdin CONTEXT$(cat) SQL$(echo $CONTEXT | jq -r .selection) # Simple heuristic: flag queries with string concatenation if echo $SQL | grep -qE (CONCAT||||\\\\s*[\]|[\]\\s*\\) ; then echo {risk: HIGH, message: Potential SQL injection via string concatenation, suggestion: Use parameterized queries instead} exit 0 fi # Check for dynamic table names if echo $SQL | grep -qE (FROM|JOIN)\\s[a-zA-Z0-9_]\\sAS\\s[a-zA-Z0-9_] ; then echo {risk: MEDIUM, message: Dynamic table aliasing detected, suggestion: Validate table names against allowlist} exit 0 fi echo {risk: LOW, message: No obvious injection patterns found, suggestion: Still review manually for business logic flaws}安装后在 Cursor 中选中 SQL 片段右键选择SQL Safety Check即可获得风险评估。它没有调用任何大模型纯粹是规则引擎——这正是 Superpowers 的设计初衷能力可以是规则、可以是模型、可以是任何能解决问题的程序。我把它部署在团队的 CI 流程中作为pre-commit钩子。当开发者提交含SELECT * FROM users WHERE id userId 的代码时CI 会直接失败并提示修复建议。这才是 Superpowers 真正该有的样子不是炫技的玩具而是嵌入工作流的生产力齿轮。6. 个人经验总结关于 Superpowers 生态的三个认知跃迁在深度使用 Superpowers 近三个月配置过 Cursor、Antigravity、Trae Work CN 三套环境亲手编写并维护了 7 个自定义插件后我对这个生态形成了三点超越工具层面的认知。它们不是技术细节而是影响我日常决策的底层思维转变。6.1 从“寻找最佳工具”到“构建最小可行能力集”过去我会花大量时间比较 Cursor、GitHub Copilot、Tabnine 的代码补全准确率试图选出“最好的那个”。Superpowers 彻底改变了这个范式。现在我的工作流是第一步明确当前任务的原子能力需求例如“需要根据 Jira ticket ID 自动生成测试用例”第二步检查现有 Superpowers 是否覆盖codex superpowers list | grep jira第三步若无则用 30 分钟写一个专用插件如jira-test-generator只做一件事做到极致。我写的jira-test-generator插件只有 42 行 Bash 代码它解析剪贴板中的 Jira ID如PROJ-123调用 Jira REST API 获取 ticket 描述提取关键词“login”, “timeout”, “redirect”然后用curl调用本地 Ollama 的phi3:3.8b模型生成 pytest 用例。它不完美但解决了我 80% 的重复劳动。这种“小而专”的能力组装比追求一个万能工具更高效。6.2 从“信任模型输出”到“验证能力契约”以前看到 AI 生成的代码第一反应是“它对吗”。现在我的第一反应是“这个 Superpower 的superpower-run脚本是如何定义‘正确’的” 我会立刻打开插件源码查看它的输入校验逻辑、prompt 模板、后处理规则。例如claude-code的generate-test功能会在输出后调用pytest --collect-only验证生成的代码能否被 pytest 解析——这是一个明确的能力契约输出必须是语法合法的 pytest 代码。这种思维让我摆脱了对黑盒模型的盲目依赖。当某个 Superpower 生成了错误代码我不再归咎于“Claude 不行”而是检查它的 prompt 是否遗漏了关键约束如--max-tokens 2048导致截断它的后处理是否过于激进如正则替换assert True为assert False它的上下文提取是否错误如把注释当代码解析。能力契约Capability Contract成了我和 AI 之间的新沟通语言。6.3 从“学习工具用法”到“参与协议演进”Superpowers 生态最激动人心的是它的协议层Codex CLI ABI正在被社区共同塑造。上周我向codex-cli仓库提了一个 PR提议在superpower-init的返回 JSON 中增加schema_version字段以便宿主 IDE 能优雅降级处理旧版插件。这个 PR 被合并了意味着下个版本所有 Superpower 都将支持版本协商。这让我意识到使用 Superpowers 不再是单向消费而是双向共建。你可以为热门插件提交文档改进很多 README 的中文翻译都是社区贡献在codex-cli的 issue 区提出 ABI 扩展建议如增加--stream参数支持流式响应甚至发起一个新协议分支比如codex-cli-rsRust 实现推动性能边界。工具的价值最终取决于使用者能否成为创造者。Superpowers 把这个门槛降到了最低——你不需要懂 Rust只需要会写 Bash就能为整个生态添砖加瓦。这或许就是“superpowers”一词最本真的含义它不来自某个公司发布的软件而来自每个开发者手中那行刚刚写下的、解决自己真实问题的代码。
