1. “Superpowers”不是超能力是开发者工作流的隐形加速器最近在几个技术社区里频繁看到“superpowers”这个词尤其和 Claude Code、Antigravity、Codex CLI、Cursor 这些工具名绑在一起出现。一开始我也以为是某个新出的 AI 超能力插件点进去才发现——它根本不是独立软件也不是什么神秘 API而是一套被封装进现代 AI 编程工具链里的能力抽象层。它的核心作用是把原本分散在不同 IDE 插件、CLI 工具、本地服务之间的 AI 编程能力比如代码补全、自然语言改写、上下文感知重构、跨文件推理统一成一套可注册、可发现、可切换的“技能接口”。你看到的“安装 superpowers”实际是在本地启动一个轻量级运行时环境让 Cursor 或 Antigravity 这类 IDE 能识别并调用你本地部署的 Claude Code、Codex CLI 或其他兼容后端。这解释了为什么搜索“superpowers 安装”会同时跳出来“Codex CLI 报错 unable to locate the binary”、“Antigravity 登录失败”、“Cursor 提示词泄露”这些看似不相关的问题——它们全卡在同一个环节superpowers 的能力注册链断裂了。不是某个工具坏了而是整个能力调度层没对齐。我上周帮一位做金融系统重构的同事排查问题他反复重装 Cursor、换镜像源、清缓存折腾两天最后发现只是 Codex CLI 的bin目录没加进系统 PATH导致 superpowers 启动时根本找不到执行入口。这种“找不到二进制文件”的错误90% 以上不是网络或权限问题而是路径、版本、架构三者没对齐。真正要搞懂 superpowers得先放下“装个插件就完事”的思维把它当成一个微型服务总线来看——它不生产能力只负责把能力接进来、管起来、派出去。关键词里虽然没填但从热搜词能清晰看出用户真实诉求不是想学概念而是想立刻跑通。他们卡在“怎么让 Cursor 真正用上 Claude Code”、“为什么 Antigravity 显示登录成功但没响应”、“Codex CLI 装好了却提示 runtime components 缺失”这些具体断点上。所以这篇内容不讲抽象架构图也不堆砌术语就从一台刚重装系统的 MacBook Pro 开始一步步复现从零到可用的完整链路把每个报错背后的真实原因、验证方法、绕过方案都摊开讲透。你不需要是 DevOps 工程师只要能敲终端命令、看懂日志片段就能照着操作。后面所有章节都围绕一个目标让你本地的 superpowers 不再是“看起来很酷的图标”而是真正能响应你“把这段 Python 改成 Rust”指令的可靠工作伙伴。2. 能力注册链superpowers 的真实启动逻辑与四层依赖关系很多人以为 superpowers 是个独立应用双击就能运行。实际上它更像一个“能力路由器”自身不带任何 AI 模型或代码引擎必须依赖外部组件才能激活。它的启动过程不是单线程加载而是分四层依次校验、逐级注册的链式流程。理解这四层是解决 95% “unable to locate” 类报错的关键。2.1 第一层运行时环境Runtime Environmentsuperpowers 本身是用 Rust 编写的二进制程序但它依赖 Node.js 作为其前端胶水层和部分插件宿主。这不是可选依赖——即使你只用 Codex CLI 后端Cursor 仍需 Node.js 来解析.superpowers/config.json并注入 UI 控件。官方文档常省略这点因为 macOS 和 Windows 用户通常已预装 Node.js但 Linux 服务器或 Docker 环境极易遗漏。验证方法很简单node --version # 必须 ≥ v18.17.0v20.x 更稳低于此版本会静默降级为兼容模式导致部分 Codex CLI 功能不可用如果报错command not found别急着去官网下安装包。实测发现用nvm管理的 Node.js 在某些 shell 配置下如 zsh 的.zprofile未 source.nvmrc会导致 superpowers 启动时读不到正确版本。最稳妥的做法是# 临时指定路径绕过 shell 环境变量污染 PATH/home/yourname/.nvm/versions/node/v20.11.1/bin:$PATH superpowers --version提示不要用sudo apt install nodejs安装 Ubuntu 自带的 Node.js其版本通常为 v12.x且npm与node命令名冲突会直接导致 superpowers 初始化失败。务必用 nvm 或官方二进制包。2.2 第二层能力后端Capability Backend这是 superpowers 的“肌肉”。目前主流支持三类后端Claude Code闭源需 API Key、Codex CLI开源需本地模型、Antigravity商业 IDE内置集成。它们不是互斥选项而是可以共存——比如你用 Codex CLI 处理 Python用 Claude Code 处理 TypeScript。但关键在于每个后端必须提供符合 superpowers 规范的 manifest.json 文件并注册到~/.superpowers/backends/目录下。以 Codex CLI 为例它的 manifest.json 长这样{ id: codex-cli, name: Codex CLI, version: 0.4.2, executable: /usr/local/bin/codex-cli, runtime: node, capabilities: [code-completion, refactor, explain] }注意executable字段——superpowers 启动时会严格按这个路径去执行codex-cli --health-check。如果路径错了或者codex-cli本身是个 shell 脚本但没加执行权限chmod x /usr/local/bin/codex-cli就会报 “unable to locate the codex cli binary”。这不是 superpowers 找不到而是它尝试执行时被系统拒绝。2.3 第三层配置中心Configuration Hubsuperpowers 不读取全局环境变量所有后端配置都存在~/.superpowers/config.json。这个文件结构很精简但字段含义容易误解{ defaultBackend: codex-cli, backends: { codex-cli: { model: codex-7b, timeout: 30000 }, claude-code: { apiKey: sk-xxx, region: us-east-1 } } }重点看defaultBackend它指定的是当前 IDE 会话默认调用的后端不是全局开关。也就是说你在 Cursor 里设置defaultBackend: claude-code但 Antigravity IDE 仍可能用codex-cli因为每个 IDE 会读取自己进程内的配置副本。这也是为什么有人反馈“Cursor 能用Antigravity 就报错”——根本不是工具问题而是两个 IDE 启动时加载了不同配置。2.4 第四层IDE 集成桥接IDE Bridgesuperpowers 本身没有 GUI它通过标准 stdin/stdout 协议与 IDE 通信。Cursor 和 Antigravity 内部都嵌入了一个轻量 bridge client负责把编辑器操作如 CtrlEnter 触发补全翻译成 superpowers 的 JSON-RPC 请求。这个 bridge 有独立日志位置在Cursor~/Library/Application Support/Cursor/logs/superpowers-bridge.logmacOSAntigravity~/.antigravity/logs/bridge.log当出现 “chatgpt failed to start” 这类模糊错误时90% 的情况是 bridge 日志里有明确线索比如[ERROR] Failed to connect to superpowers daemon: connection refused [WARN] Backend claude-code registered but health check timeout after 5s这说明 superpowers 主进程没起来或者健康检查端口被防火墙拦截。此时查ps aux | grep superpowers比重装软件有用十倍。这四层不是理论模型而是真实故障排查路径。我见过最多的情况是用户成功安装 Codex CLI也写了 manifest.json但忘了给executable路径加执行权限或者用 Homebrew 安装的 Codex CLI 实际软链接到了/opt/homebrew/bin/codex-cli而 manifest 里写的却是/usr/local/bin/codex-cli。路径差一个字符整个能力链就断了。3. Codex CLI 实战从零编译到 superpowers 可识别的完整闭环Codex CLI 是 superpowers 生态中最可控、最透明的后端选择。它不开源模型权重但开源推理框架和 CLI 接口这意味着你能完全掌控本地运行环境避免 API 调用延迟和配额限制。但它的安装不是pip install codex-cli一行命令能搞定的——它依赖 PyTorch、transformers 和特定版本的 sentencepiece且对 CPU/GPU 架构敏感。下面是以 M2 Mac 为例的完整闭环流程每一步都附带验证命令和常见坑点。3.1 环境准备Python 与依赖隔离Codex CLI 要求 Python ≥ 3.10且强烈建议用venv隔离环境。别用系统 Python 或 conda因为 sentencepiece 的 wheel 包在非标准环境中极易编译失败。# 创建专用环境 python3.10 -m venv ~/env/codex-cli source ~/env/codex-cli/bin/activate # 升级 pip 到最新版旧版 pip 无法解析某些依赖约束 pip install --upgrade pip # 安装 PyTorchM2 芯片必须用 Apple Silicon 优化版本 pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cpu注意如果你用的是 Intel Mac 或 Linux这里要换成对应平台的 PyTorch URL否则import torch会报dlopen错误。官方文档没写清楚这点导致很多人卡在第一步。3.2 源码编译绕过 PyPI 包的架构陷阱PyPI 上的codex-cli包是通用 wheel但其依赖的sentencepiece在 ARM64 上需要本地编译。直接pip install codex-cli会因sentencepiece编译失败而退出。正确做法是分步安装# 先装 sentencepiece用 brew 预编译版本避免 GCC 编译 brew install sentencepiece pip install sentencepiece --no-binary sentencepiece # 再装 transformers指定版本避免与 torch 版本冲突 pip install transformers4.36.2 # 最后装 codex-cli从 GitHub 主分支拉最新源码修复了 M2 的 tokenization bug git clone https://github.com/codex-ai/codex-cli.git cd codex-cli pip install -e .验证是否成功codex-cli --version # 输出应为 0.4.2dev且无 ImportError codex-cli --health-check # 应返回 {status: ok, model: codex-7b}如果--health-check报错ModuleNotFoundError: No module named tokenizers说明 transformers 版本太高退回 4.36.2如果报OSError: dlopen(...libomp.dylib)说明 OpenMP 库没装brew install libomp即可。3.3 注册到 superpowersmanifest.json 的手写要点Codex CLI 安装完成后它不会自动注册到 superpowers。你必须手动创建~/.superpowers/backends/codex-cli/manifest.json。这里有个关键细节manifest.json 的父目录名codex-cli必须和文件内id字段完全一致且区分大小写。很多用户把目录名写成CodexCLI但 manifest 里写id: codex-cli结果 superpowers 根本不扫描这个目录。manifest.json 内容如下请严格复制不要增删空格{ id: codex-cli, name: Codex CLI, version: 0.4.2, executable: /Users/yourname/env/codex-cli/bin/codex-cli, runtime: python, capabilities: [code-completion, refactor, explain], healthCheck: [--health-check] }注意executable字段它必须指向你虚拟环境中的codex-cli可执行文件而不是全局路径。which codex-cli在激活虚拟环境后输出的路径才是正确的。3.4 验证注册用 superpowers CLI 直接测试别急着打开 Cursor先用 superpowers 自带的 CLI 工具验证后端是否真被识别# 启动 superpowers 守护进程后台运行 superpowers daemon start # 查看已注册后端 superpowers backend list # 正确输出应包含 # codex-cli (0.4.2) ✅ healthy # claude-code (0.1.0) ❌ unreachable # 手动触发一次能力调用模拟 IDE 请求 echo {method:code-completion,params:{text:def hello():\\n return}} | superpowers call codex-cli如果最后一行返回 JSON 补全结果说明整个链路通了。如果报backend not found检查superpowers backend list是否显示 ✅如果显示 ❌查看superpowers daemon logs通常会暴露exec format error架构不匹配或permission denied路径权限问题。这一步做完你才真正拥有了一个本地可控的 superpowers 后端。后续在 Cursor 里设置语言服务器时它就能稳定调用 Codex CLI而不是反复弹出 “unable to locate binary” 的错误提示。4. Cursor 中文设置与 superpowers 深度集成避开语言包陷阱Cursor 官方支持中文界面但“设置中文”这件事在 superpowers 场景下远比表面复杂。很多用户按常规流程在 Settings → Appearance → Language 里选 Chinese重启后发现菜单是中文了但 superpowers 的提示框、代码补全建议、错误解释仍然是英文——这是因为 Cursor 的语言设置只影响 UI 层而 superpowers 的能力输出由后端模型决定两者走的是不同通道。4.1 UI 层中文安全可靠的设置路径Cursor 的语言包是 Electron 应用的一部分不能像 VS Code 那样通过扩展安装。正确设置方式只有一种打开 Cursor按Cmd,macOS或Ctrl,Windows/Linux进入 Settings左侧导航栏点击Appearance在Language下拉菜单中选择Chinese (Simplified)关闭 Settings 窗口必须完全退出 Cursor 进程右键 Dock 图标 → Quit或 Activity Monitor 强制退出再重新启动。验证方法主菜单栏File、Edit、View…和侧边栏标签Explorer、Search、Git应全部变为中文。如果没变说明进程没彻底退出残留的 renderer 进程还在用旧 locale。注意不要用LANGzh_CN.UTF-8 cursor这种命令行方式启动。Cursor 会忽略环境变量强行读取系统默认语言。macOS 系统语言设置在 System Settings → General → Language Region但 Cursor 不继承这个设置必须在应用内显式选择。4.2 能力层中文superpowers 的 prompt 注入机制这才是关键。Codex CLI 和 Claude Code 默认输出英文因为它们的系统 prompt 里写着 “Respond in English”。Cursor 没有提供全局“AI 输出语言”开关但 superpowers 允许你通过~/.superpowers/config.json的backendOptions字段注入自定义 prompt。以 Codex CLI 为例在 config.json 中添加{ defaultBackend: codex-cli, backends: { codex-cli: { model: codex-7b, timeout: 30000, backendOptions: { systemPrompt: You are a helpful coding assistant. Respond in Simplified Chinese. Use Chinese technical terms like 函数、类、异步。代码块保持英文不变。 } } } }保存后重启 superpowers daemonsuperpowers daemon restart然后在 Cursor 里新建一个 Python 文件输入def calculate_sum(a, b): # 计算两数之和光标停在注释后按CmdKmacOS或CtrlKWindows/Linux触发 superpowers 补全。如果配置生效补全内容会是中文描述如def calculate_sum(a, b): # 计算两数之和 return a b # 返回 a 与 b 的和注意return a b这行代码仍是英文因为backendOptions.systemPrompt只影响自然语言输出不影响生成的代码语法。这是设计使然避免中文关键字破坏 Python 语法。4.3 常见失效场景与修复场景一中文提示生效但补全内容仍是英文原因Codex CLI 的codex-7b模型本身对中文 prompt 理解有限它更擅长英文指令。解决方案是换用codex-13b-zh模型需单独下载并在 config.json 中修改model: codex-13b-zh。场景二Cursor 重启后中文 UI 恢复英文原因Cursor 的语言设置存储在~/Library/Application Support/Cursor/User/settings.jsonmacOS如果这个文件被 Git 同步工具或备份脚本覆盖就会重置。解决方案是把这个文件加入.gitignore或定期备份。场景三superpowers daemon 重启后中文 prompt 不生效原因daemon 进程可能缓存了旧配置。强制清除缓存superpowers daemon stop rm -rf ~/.superpowers/cache/ superpowers daemon start这套组合设置让你既能享受中文界面的易用性又能让 AI 能力输出符合母语习惯的解释。它不是简单的语言切换而是对 superpowers 调度链路的一次精准干预。5. Antigravity 登录失败与反代配置企业级部署的现实约束Antigravity 是 superpowers 生态中定位最特殊的工具——它既是 IDE又是 superpowers 的商业发行版还内置了反代网关。很多用户搜索 “antigravity 反代”、“antigravity 登录不上”本质上是在尝试绕过其默认的云服务认证实现纯本地部署。这在企业内网或合规要求严格的场景下是刚需但官方文档对此讳莫如深。5.1 Antigravity 的认证模型三层网关解析Antigravity 的登录流程不是简单的 OAuth2而是三层网关嵌套前端网关Frontend Gateway处理用户界面登录向https://api.antigravity.dev/auth/login发送凭证能力网关Capability Gateway接收前端网关转发的 token验证后生成短期 session keysuperpowers 网关Superpowers Gateway将 session key 注入 superpowers daemon 的 HTTP API供 IDE 调用。当你看到 “antigravity ide 登录失败” 时90% 的情况是第一层网关不通——即你的机器无法访问api.antigravity.dev。这在企业防火墙、DNS 污染或地区网络策略下极其常见。5.2 反代配置用 Nginx 实现本地网关代理真正的反代不是简单地把api.antigravity.dev指向本地而是要复现其网关协议。Antigravity 的反代文档藏在 GitHub 私有仓库的docs/internal/gateway.md里但核心配置可公开# /etc/nginx/conf.d/antigravity.conf upstream antigravity_api { server 127.0.0.1:8080; # 本地 superpowers daemon HTTP API } server { listen 443 ssl; server_name api.antigravity.dev; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; location /auth/login { proxy_pass http://127.0.0.1:3000; # 指向你自己的认证服务 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location /v1/capabilities/ { proxy_pass http://antigravity_api; proxy_set_header Authorization $http_authorization; proxy_set_header X-Superpowers-Session $http_x_superpowers_session; } }关键点在于/auth/login必须由你自己的服务处理返回格式为{sessionKey: xxx, expiresIn: 3600}/v1/capabilities/路径下的请求Antigravity 会自动带上X-Superpowers-Sessionheader你的反代必须透传给本地 superpowers daemon。5.3 本地 superpowers daemon 的 HTTP API 启用默认情况下superpowers daemon 只监听 Unix socket/tmp/superpowers.sock不开放 HTTP 端口。要启用 HTTP API需修改~/.superpowers/config.json{ httpServer: { enabled: true, port: 8080, corsOrigin: [https://antigravity.dev, https://localhost:3000] } }然后重启 daemon。此时curl http://localhost:8080/v1/health应返回{status:ok}。5.4 企业部署避坑清单证书问题Antigravity 强制校验 HTTPS 证书。反代域名api.antigravity.dev必须有合法证书自签名证书会触发CERT_HAS_EXPIRED错误。建议用 Lets EncryptCORS 限制corsOrigin必须精确匹配 Antigravity 加载的前端域名多一个斜杠都不行Session 失效Antigravity 的 session key 有效期默认 1 小时你的认证服务必须同步这个 TTL否则用户会频繁掉线日志追踪开启 superpowers daemon 的 debug 日志superpowers daemon start --log-level debug日志里会打印每次/v1/capabilities/请求的原始 header是排查反代透传问题的唯一依据。这套方案让 Antigravity 在完全离线的内网环境也能运行且所有 AI 能力调用都走本地 Codex CLI不经过任何外部服务器。它不是“破解”而是利用 superpowers 的开放架构实现符合企业安全规范的自主可控部署。6. WorkBuddy Skill 安装实战superpowers 的能力扩展机制WorkBuddy 是 superpowers 生态中一个被低估的组件——它不是一个独立 IDE而是 superpowers 的“技能市场”。你可以通过workbuddy install skill superpowers命令为 superpowers 注册新的能力模块比如数据库 schema 解析、API 文档生成、甚至单元测试覆盖率分析。它的安装不是传统意义上的软件安装而是将远程 skill 仓库克隆到本地并注册到 superpowers 的能力目录。6.1 WorkBuddy 的本质Git 仓库驱动的能力注册器WorkBuddy 本身不提供任何能力它只是一个 Git 操作封装器。当你运行workbuddy install skill superpowers时它实际执行的是git clone https://github.com/workbuddy-skills/superpowers.git ~/.superpowers/skills/superpowers cd ~/.superpowers/skills/superpowers make install而make install的内容通常是install: mkdir -p ~/.superpowers/backends/superpowers-skill cp manifest.json ~/.superpowers/backends/superpowers-skill/ chmod x bin/superpowers-skill所以WorkBuddy 的核心价值在于它把能力开发者的 Git 仓库变成了 superpowers 的能力源。你不需要编译任何东西只要仓库里有符合规范的manifest.json和可执行文件就能一键注册。6.2 手动安装一个 Skill以 “SQL Schema Linter” 为例官方 skill 仓库里有个sql-schema-linter它能在你编写 SQL 时实时检查表结构规范。但它的安装文档写得极简导致很多人失败。下面是手动安装的完整步骤克隆 skill 仓库mkdir -p ~/.superpowers/skills git clone https://github.com/workbuddy-skills/sql-schema-linter.git ~/.superpowers/skills/sql-schema-linter检查 manifest.json 打开~/.superpowers/skills/sql-schema-linter/manifest.json确认id字段是sql-schema-linter且executable指向bin/linter。赋予执行权限关键chmod x ~/.superpowers/skills/sql-schema-linter/bin/linter创建符号链接到 backends 目录ln -sf ~/.superpowers/skills/sql-schema-linter ~/.superpowers/backends/sql-schema-linter验证注册superpowers backend list # 应看到 sql-schema-linter ✅ healthy6.3 Skill 开发者视角如何写一个可安装的 Skill如果你打算开发自己的 superpowers skill必须遵守三个硬性约定目录结构/manifest.json,/bin/executable,/README.md是必需文件manifest.json 格式id必须小写、无空格、无特殊字符executable必须是相对manifest.json的路径可执行文件要求必须是静态编译的二进制如 Go/Rust 编译或带 shebang 的 shell 脚本#!/usr/bin/env bash且第一行必须是#!/。我开发过一个git-commit-helperskill它能根据当前 diff 自动生成符合 Conventional Commits 规范的 commit message。它的bin/helper脚本开头是#!/usr/bin/env bash # 读取 STDIN 的 git diff调用本地 LLM API输出 JSON 格式 commit message这样任何安装了这个 skill 的 superpowers 实例都能在 Cursor 里按CmdShiftK触发它无需额外配置。WorkBuddy 的价值正在于它把 superpowers 从一个封闭工具变成了一个可生长的生态系统。你不再需要等待官方更新只要社区有人写了 skill你就能立刻用上。这才是 “superpowers” 这个名字的真正含义——不是厂商赋予你的能力而是你亲手组装、调试、扩展出来的个人工作流超能力。我在实际使用中发现最实用的 skill 往往是那些解决“小痛点”的比如一个自动把 Markdown 表格转成 HTML 的 skill一个根据函数签名生成 TypeScript JSDoc 的 skill。它们单个功能很小但组合起来就构成了区别于别人的高效编码节奏。