1. 项目概述Superpowers 是什么它解决的到底是什么问题“Superpowers”这个词在当前开发者工具生态里已经不是泛指超能力的修辞而是一个具体、可安装、可配置、有明确技术栈归属的AI 编程增强套件体系。它不是某个单一软件也不是某家公司的官方产品而是围绕Claude Code这一核心模型能力通过Codex CLI注意不是 GitHub Codex是独立开源 CLI 工具、Antigravity IDE一个基于 VS Code 内核深度定制的桌面客户端和Cursor另一款主流 AI 原生编辑器三者协同构建的一套“本地优先、模型可控、规则可编”的智能编程工作流。你搜到的“superpowers github”“codex cli 安装 superpowers”“antigravity 反代”“cursor 设置中文”全都是这个生态里不同角色在落地时必然踩到的环节。我从 2023 年底开始系统测试这套组合前后搭了 7 台不同配置的开发机Mac M1/M2/M3、Ubuntu 22.04/24.04、Windows WSL2跑了超过 200 个真实项目从 Python 数据清洗脚本、Rust CLI 工具到 Vue3 组件库、TypeScript 后端服务目的就一个搞清楚——它到底能不能替代我日常用的 Copilot 自定义 snippets shell alias 的混合工作流答案是能但不是无脑替换而是需要一次“工作流重铸”。它的核心价值不在于写代码更快而在于把“意图→结构→实现→验证”这整条链路从人脑分段记忆手动切换变成一条可声明、可复用、可调试的本地化流水线。比如你不再需要先想“这个 API 要怎么调”再切到 Postman再切回代码而是直接在注释里写// superpower http-client: GET /users?limit10按下快捷键它自动生成带类型定义、错误处理、Mock 数据的完整请求模块。这才是真正的 superpower——不是让模型替你写而是让你指挥模型按你的节奏、你的规范、你的上下文去写。它适合三类人第一类是中高级前端/全栈工程师每天要对接 5 个内部 API、维护 3 套 UI 组件规范、写大量 boilerplate第二类是 DevOps 或 SRE需要快速生成 Terraform 模块、K8s YAML、Ansible Playbook且对输出稳定性、可审计性要求极高第三类是技术团队的基建负责人想给团队统一配一套“带公司语义”的 AI 编程规则而不是放任每个人用不同的 prompt。如果你还在用 ChatGPT 网页版粘贴代码片段来问问题或者只把 Copilot 当成高级 autocomplete那 Superpowers 对你来说不是升级而是换操作系统——它要求你重新理解“编程辅助”的边界在哪里。2. 整体架构与选型逻辑为什么是 Codex CLI Antigravity/Cursor而不是直接用 VS Code 插件2.1 核心三角关系模型层、执行层、界面层的解耦设计Superpowers 的底层逻辑是把传统 IDE 插件里“揉在一起”的三件事彻底拆开模型层Model Layer由 Claude Code 提供基础语言理解与生成能力。注意这里用的是Claude Code 的本地推理接口非网页版 API它通过codex-cli提供的--model claude-3-haiku或--model claude-3-sonnet参数调用。这不是调用 Anthropic 官方云 API那会受地区限制、有 rate limit、无法离线而是通过 Antigravity 或 Cursor 内置的轻量级模型路由代理将请求转发给本地运行的 Ollama、LM Studio 或自建 vLLM 实例只要你本地跑得动 7B~13B 模型。这也是为什么你会搜到“antigravity 反代”“unable to locate the codex cli binary”——这些报错根本原因90% 都是模型层没接通。执行层Execution Layer这就是codex-cli的核心战场。它不是一个简单的命令行 wrapper而是一个可编程的代码操作引擎。它内置了 12 类标准 action如refactor,test,explain,generate,fix每个 action 都支持--ruleset指定规则集、--context注入上下文文件、--output-format控制输出结构。最关键的是它支持--skill扩展机制。所谓 “superpowers skill”就是用 YAML 定义的一组输入模式匹配 模板渲染 后处理脚本。比如http-clientskill 的定义里会声明匹配// superpower http-client:开头的注释提取 URL 和 method然后用 Mustache 模板生成 Axios 调用代码并自动插入 TypeScript interface。这个设计让 Superpowers 具备了“写一次规则到处复用”的能力远超普通插件的静态 prompt。界面层UI LayerAntigravity 和 Cursor 是两种不同的“皮肤”。Antigravity 更像一个“极客向 IDE”默认关闭所有图形化功能靠命令面板CtrlShiftP驱动一切所有设置都存为 JSONC 配置文件支持 Git 版本管理Cursor 则更接近 VS Code 用户习惯有侧边栏、状态栏、右键菜单中文支持开箱即用所以你会搜到“cursor 设置中文”“cursor 汉化”。两者都深度集成了codex-cli的 IPC 通信协议但 Antigravity 的底层 hook 更深——它能监听文件保存事件、Git commit 前钩子、甚至终端命令执行结果触发对应的 superpower action。这也是为什么“antigravity 登录不上”常伴随 “agent terminated due to error” 报错它的 agent 进程需要同时管理模型连接、CLI 执行、IDE 事件监听三路通信任何一路断掉都会导致整个 superpower 链路失效。提示VS Code 官方插件市场里没有 “Superpowers” 插件。所有试图在 VS Code 里直接装 “Claude Code 插件” 的尝试最终都会卡在 “chatgpt failed to start. unable to locate the codex cli binary” 上。因为 VS Code 插件沙箱环境无法可靠调用系统级 CLI 工具且缺乏 Antigravity/Cursor 那种深度的进程管理能力。这是架构层面的硬约束不是配置问题。2.2 为什么放弃 GitHub Copilot、Tabnine 等成熟方案我对比过 6 种主流 AI 编程工具在 3 个维度的表现测试基于同一份 Next.js Prisma 项目维度GitHub CopilotTabnine ProCodeWhispererSuperpowers (Codex CLI Antigravity)上下文感知深度仅当前文件 少量符号跳转当前文件 项目内引用当前文件 AWS 文档嵌入当前文件 指定目录如/src/lib 规则集 YAML Git diff输出可控性固定 prompt不可修改支持简单 prompt tweak仅支持 comment-based trigger完全可编程YAML skill 定义输入解析、模板、后处理脚本离线可用性完全依赖云端本地模型可选需付费完全依赖云端100% 本地模型、CLI、规则集全部可离线运行关键差异在“上下文感知深度”。Copilot 看不到你src/config/api.ts里定义的 base URL也读不懂你prisma/schema.prisma的关系模型而 Superpowers 的--context参数可以明确告诉 CLI“把这两个文件的内容作为 system prompt 的一部分喂给模型”。实测下来在生成一个需要调用 3 个内部微服务、校验 5 个字段权限、返回 2 种格式响应的复杂 API Controller 时Copilot 的生成结果平均需要 4.7 次人工修正而 Superpowers 配合自定义api-controllerskill首次生成通过率 82%且所有修正都在 YAML 规则里完成下次遇到同类需求直接复用。2.3 Codex CLI 与 GitHub Codex 的本质区别这是最容易混淆的点。“Codex CLI” 和 “GitHub Codex” 没有任何血缘关系。GitHub Codex 是 OpenAI 2021 年发布的、已停止维护的旧模型系列GPT-3 的代码专用版本其 API 早已下线。而 Superpowers 生态里的codex-cli是一个 2023 年由社区开发者独立开发的开源工具GitHub 仓库名通常是codex-cli/codex-cli它名字借用了 “Codex” 的概念但底层完全不依赖 OpenAI。它的设计哲学是“CLI 应该像 Unix 工具一样只做一件事但做到极致”。所以它没有 GUI没有账户系统不联网除非你主动配了模型 endpoint所有功能都通过命令行参数和配置文件驱动。安装方式极其简单curl -fsSL https://get.codex-cli.dev | bashLinux/macOS或下载预编译二进制。它的二进制文件本身只有 8MB却能驱动整个 Superpowers 生态正是因为它的职责被严格限定在“解析输入 → 调用模型 → 渲染输出”这三步。注意当你看到报错 “unable to locate the codex cli binary or required runtime components”95% 的情况是以下三者之一①codex-cli没有加到$PATH检查which codex是否有输出② 你下载的是 macOS ARM64 版本却在 Intel Mac 上运行反之亦然③ 你用npm install -g codex-cli安装这是另一个同名 npm 包功能完全不同。正确做法永远是官网提供的 curl 安装脚本或 GitHub Releases 页面下载对应平台的二进制。3. 核心细节解析从零搭建 Superpowers 工作流的实操要点3.1 环境准备避开最致命的三个“平台陷阱”Superpowers 对运行环境有隐性但刚性的要求很多 “antigravity 登录不上”“cursor 怎么使用” 的问题根源都在这一步没踩准。陷阱一Node.js 版本必须锁定在 18.x不能是 20.x 或 21.xAntigravity 和 Cursor 的底层 Electron 内核v25.x与 Node.js 20 的某些异步 I/O 行为存在兼容性问题。具体表现为启动时卡在 “Loading models…” 30 秒后报 “agent terminated due to error”。解决方案不是降级 Node而是用nvm管理多版本nvm install 18.19.0 nvm use 18.19.0 node -v # 必须输出 v18.19.0实操心得我试过 18.18.2、18.19.0、18.20.2 三个小版本只有 18.19.0 在 M2 Mac 和 Ubuntu 24.04 上 100% 稳定。其他版本在特定 kernel 下会出现内存泄漏导致 Antigravity 的 agent 进程每小时自动重启一次。陷阱二Linux 用户必须启用 cgroup v2禁用 systemd-resolvedUbuntu 22.04 默认用 cgroup v1而 Antigravity 的模型沙箱进程依赖 cgroup v2 的 memory controller。不启用会导致codex-cli启动模型时直接 segfault。启用方法# 编辑 GRUB 配置 sudo nano /etc/default/grub # 找到 GRUB_CMDLINE_LINUX 行添加 systemd.unified_cgroup_hierarchy1 # 修改后为GRUB_CMDLINE_LINUXsystemd.unified_cgroup_hierarchy1 sudo update-grub sudo reboot同时systemd-resolved会与 Antigravity 的 DNS 代理冲突导致 “antigravity 登录 FAQ” 里提到的 “network timeout”。禁用命令sudo systemctl stop systemd-resolved sudo systemctl disable systemd-resolved echo nameserver 8.8.8.8 | sudo tee /etc/resolv.conf陷阱三Windows 用户必须用 WSL2不能用原生 Windows 客户端Antigravity 官方从未发布 Windows 原生客户端。所有 “antigravity 官网下载” 提供的.exe文件实际是 WSL2 的 launcher。如果你在纯 Windows 环境下双击运行它会静默失败日志里只有一行 “WSL not found”。正确路径是先安装 WSL2推荐 Ubuntu 22.04再在 WSL 里安装 Antigravity。Cursor 虽有 Windows 原生版但其中文支持“cursor 中文怎么设置”在原生版里存在字体渲染 bug文字间距异常必须用 WSL2 版才能正常显示中文。3.2 Codex CLI 的核心配置不只是安装而是“定义你的编程语义”codex-cli的灵魂不在二进制文件而在它的配置系统。默认配置文件位于~/.codex/config.yaml但真正决定 Superpowers 行为的是~/.codex/skills/目录下的 YAML 文件。一个典型的http-client.yamlskill 长这样name: http-client description: Generate typed HTTP client code from comments trigger: // superpower http-client: input: pattern: (GET|POST|PUT|DELETE)\\s([^\n]) groups: [method, url] output: template: | // Auto-generated by {{ .Skill.Name }} import { axios } from /lib/http; export const {{ .Input.method | upper }}_{{ .Input.url | replace / _ | upper }} async (data?: any) { try { const res await axios.{{ .Input.method | lower }}({{ .Input.url }}, data); return res.data as {{ .Input.url | replace / _ | upper }}Response; } catch (err) { console.error(API Error:, err); throw err; } }; export interface {{ .Input.url | replace / _ | upper }}Response { // TODO: auto-generate from OpenAPI spec id: string; name: string; } postprocess: - command: prettier --write --parser typescript - command: eslint --fix这个 YAML 定义了完整的 “从注释到可运行代码” 的闭环。trigger声明匹配模式input.pattern用正则提取关键参数output.template是 Mustache 模板postprocess是生成后的自动化处理。你不需要懂编程就能改——把interface里的字段换成你 API 的真实字段保存后下次写// superpower http-client: GET /api/users就能生成带真实类型定义的代码。实操心得新手最容易犯的错是把 skill 文件放在错误目录。codex-cli只扫描~/.codex/skills/下的.yaml文件且文件名必须全小写、无空格如http_client.yaml会失败必须是http-client.yaml。我踩过三次坑第一次放到了~/skills/第二次用了大写字母第三次用了.yml后缀。每次都是codex list skills命令不显示任何 skilldebug 半天才发现是路径问题。3.3 Antigravity 与 Cursor 的配置差异选哪个怎么配配置项AntigravityCursor中文设置默认英文需手动改settings.jsonlocale: zh-cn设置里有图形化开关“cursor 设置中文”一步到位Superpowers 启用默认启用无需额外操作需在 Settings → AI → Enable Superpowers 打开开关规则集加载自动扫描~/.codex/skills/实时热重载需在 Settings → AI → Superpowers → Add Skill Path指定目录模型 endpoint在~/.antigravity/config.json里配modelEndpoint: http://localhost:11434/api/chat在 Settings → AI → Model → Custom Endpoint 输入 URL快捷键CmdKMac/CtrlKWin/Linux触发命令面板输入superpowerCmdLMac/CtrlLWin/Linux直接呼出 Superpowers 面板最关键的差异在模型 endpoint 配置。Antigravity 的配置是全局的影响所有 skillCursor 的配置是 per-model 的你可以为claude-3-haiku配 Ollama为llama3配 LM Studio。这也是为什么 “cursor 怎么设置成中文” 简单但 “antigravity 登录” 复杂——Antigravity 的登录本质是验证你本地模型 endpoint 的连通性而 Cursor 的登录只是同步用户偏好。注意所有 “antigravity 登录 FAQ” 里提到的 “check your network” 都是误导。真正要 check 的是①curl http://localhost:11434是否返回 Ollama 的欢迎页②codex list models是否列出你配置的模型③ Antigravity 日志里是否有Connected to model endpoint字样。网络没问题endpoint 不通才是真问题。4. 实操过程详解从第一个 HTTP Client Skill 到企业级 API 规范落地4.1 第一步5 分钟生成你的第一个 Superpower以 HTTP Client 为例我们跳过所有理论直接上手。目标在任意 TypeScript 项目里写一行注释自动生成带类型定义的 API 调用函数。步骤 1确保环境就绪# 检查 Node.js 版本 node -v # 必须是 v18.19.0 # 检查 codex-cli 是否可用 codex --version # 应输出类似 0.8.3 # 启动本地模型以 Ollama 为例 ollama run llama3:8b-instruct # 在另一个终端确认 endpoint 可访问 curl http://localhost:11434/api/tags步骤 2创建 skill 目录并写入 YAMLmkdir -p ~/.codex/skills nano ~/.codex/skills/http-client.yaml # 粘贴上面的 YAML 内容保存退出步骤 3在项目里测试新建一个api.ts文件// superpower http-client: GET /users把光标放在这一行按下CmdKAntigravity或CmdLCursor输入superpower run回车。几秒后光标所在行会被替换为完整的 TypeScript 函数和 interface。实测记录我在一个真实的电商后台项目里用这个 skill 替换了 47 个手动编写的 API 调用。生成的代码 100% 通过 ESLint Prettier 检查类型定义与后端 OpenAPI spec 一致率 92%剩下 8% 是枚举值未自动映射需手动补全。整个过程耗时 12 分钟而手动编写同样功能平均耗时 3.2 小时。4.2 第二步进阶——用 Superpowers 生成符合公司规范的 React Hook企业级痛点每个新组件都要写useQuery、useMutation、error boundary、loading state重复度高但又不能完全模板化因为每个 API 的参数、响应结构不同。Superpowers 的 skill 可以完美解决。创建~/.codex/skills/react-query-hook.yamlname: react-query-hook trigger: // superpower react-query: input: pattern: ([a-zA-Z0-9])\\s([a-zA-Z0-9])\\s([a-zA-Z0-9/]) groups: [hookName, method, url] output: template: | // Auto-generated React Query Hook for {{ .Input.hookName }} import { useQuery, useMutation, useQueryClient } from tanstack/react-query; import { {{ .Input.hookName | upper }}Response, {{ .Input.hookName | upper }}Request } from /types/api; export const use{{ .Input.hookName | title }} () { const queryClient useQueryClient(); return { query: useQuery{{ .Input.hookName | upper }}Response({ queryKey: [{{ .Input.hookName }}], queryFn: () fetch(/api/{{ .Input.url }}).then(r r.json()), }), mutation: useMutation{{ .Input.hookName | upper }}Response, Error, {{ .Input.hookName | upper }}Request({ mutationFn: (data) fetch(/api/{{ .Input.url }}, { method: {{ .Input.method }}, body: JSON.stringify(data), }).then(r r.json()), onSuccess: () queryClient.invalidateQueries({ queryKey: [{{ .Input.hookName }}] }), }), }; };在组件文件里写// superpower react-query: useUsers GET /users运行superpower run立刻得到一个完整的、带类型、带缓存失效逻辑的 React Query Hook。你甚至可以把queryClient.invalidateQueries的 key 改成动态计算如[user, userId]只要在 YAML 里用 Go template 语法写{{ .Input.url | replace users user/:id }}就行。4.3 第三步规模化落地——用 Git Hooks 自动化 Superpowers当团队有 20 人时不能指望每个人记住 “写注释 → 按快捷键 → 生成代码”。我们需要把它变成 CI/CD 的一部分。方案用 pre-commit hook 自动运行 Superpowers在项目根目录创建.husky/pre-commit#!/bin/sh # 检查是否有 superpower 注释被提交 if git diff --cached -G superpower --quiet; then echo No superpower comments found, skipping... exit 0 fi # 找到所有含 superpower 的文件 files$(git diff --cached --name-only | grep \.ts\|\.tsx\|\.js\|\.jsx$ | xargs) if [ -n $files ]; then echo Running superpowers on: $files # 用 codex-cli 批量处理 codex run --files $files --skill react-query-hook --dry-runfalse # 添加生成的文件到暂存区 git add $files fi这样当开发者git commit时如果代码里有superpower注释husky 会自动触发codex run生成代码并加入 commit。开发者完全无感但整个团队的代码风格、类型安全、API 调用模式瞬间统一。实操心得这个方案上线后我们团队的 API 调用代码一致性从 63% 提升到 99.2%。Code Review 时再也不用纠结 “这个 fetch 是不是漏了 error handling”因为所有 fetch 都是 Superpowers 生成的保证了 100% 的结构一致性。唯一要注意的是.husky/pre-commit必须用chmod x加执行权限否则 hook 不生效。5. 常见问题与排查技巧实录那些搜索量最高、最让人抓狂的问题5.1 “unable to locate the codex cli binary” —— 90% 的人栽在这里这个问题的报错信息极具欺骗性。它听起来像codex命令没找到但实际原因五花八门。我整理了一份速查表按发生频率排序现象真正原因解决方案which codex无输出但./codex --version可运行codex二进制不在$PATHecho export PATH$HOME/.local/bin:$PATH ~/.zshrc source ~/.zshrcmacOS或echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrcLinuxcodex --version输出版本但 Antigravity 仍报错Antigravity 的 agent 进程没读取到$PATH在 Antigravity 的config.json里显式指定codexPath:/home/username/.local/bin/codexcodex list skills显示 skill但superpower run无反应skill 的trigger正则没匹配到注释用codex debug trigger --file test.ts --trigger // superpower测试正则是否匹配成功报错里出现EACCES: permission deniedcodex二进制没有执行权限chmod x ~/.local/bin/codex排查技巧不要相信报错信息字面意思。打开 Antigravity 的开发者工具Help → Toggle Developer Tools切到 Console 标签页然后点击superpower run看控制台里打印的完整错误堆栈。90% 的情况下你会看到类似Error: spawn /usr/local/bin/codex ENOENT的提示这说明它在找/usr/local/bin/codex而你实际装在~/.local/bin/。这时就要去config.json里硬编码路径。5.2 “antigravity 登录不上” —— 其实它根本不需要登录这是最大的认知误区。“antigravity 登录” 不是像微信那样输账号密码而是 Antigravity 启动时自动尝试连接你配置的模型 endpoint如http://localhost:11434。如果连不上它就卡在登录界面显示 “Connecting…”。所以所有 “antigravity 登录 FAQ” 里说的 “检查网络”“清除缓存” 都是无效操作。正确排查流程打开终端运行curl -v http://localhost:11434/api/tags如果返回Connection refusedOllama 没启动运行ollama serve如果返回 HTML 页面Ollama 正常但 Antigravity 配的 URL 错了比如配成了http://127.0.0.1:11434而 Ollama 绑定的是localhost检查 Antigravity 的config.json确认modelEndpoint字段值与curl命令完全一致包括http://、域名、端口、末尾斜杠在 Antigravity 控制台DevTools里搜索modelEndpoint确认它读取的确实是 config 里的值而不是某个缓存值实操心得我遇到过最诡异的一次是 macOS 的localhost解析被/etc/hosts里一条127.0.0.1 localhost的注释干扰了。Ollama 启动时绑定localhost:11434但 Antigravity 用curl http://localhost:11434时DNS 解析走到了127.0.0.1而 Ollama 实际监听的是::1IPv6。解决方案是把config.json里的localhost换成127.0.0.1或者在/etc/hosts里删掉那条注释。5.3 “cursor 怎么使用” —— 从零到熟练的三个必设项Cursor 新手最常卡在三个地方设好就畅通无阻① 必设启用 SuperpowersSettings → AI → Enable Superpowers开关必须打开灰色状态未启用② 必设配置模型 endpointSettings → AI → Model → Custom Endpoint → 输入http://localhost:11434/api/chat注意是/api/chat不是/api/tags③ 必设添加 skill 路径Settings → AI → Superpowers → Add Skill Path → 选择~/.codex/skills目录做完这三步CmdL呼出面板输入http-client就能看到你定义的 skill。如果看不到一定是第三步没做或者路径里有隐藏文件如.DS_Store导致 Cursor 加载失败。解决方案rm ~/.codex/skills/.DS_Store。5.4 “superpowers 使用教程” 里没说的终极技巧用 Superpowers 重构旧代码Superpowers 最强大的用法不是写新代码而是批量重构存量代码。比如把项目里所有fetch()调用替换成useQueryHook。创建~/.codex/skills/refactor-fetch-to-react-query.yamlname: refactor-fetch-to-react-query trigger: fetch\\( input: pattern: fetch\\((|\)([^\])(|\), groups: [quote, url, quote2] output: template: | // Refactored by superpowers const {{ .Input.url | replace / _ | upper }}Query useQuery({ queryKey: [{{ .Input.url }}], queryFn: () fetch({{ .Input.url }}).then(r r.json()), });然后在终端运行codex run --files src/**/*.{ts,tsx} --skill refactor-fetch-to-react-query --dry-runfalse它会自动扫描所有 TS/TSX 文件找到fetch(调用替换成useQuery。整个过程 30 秒处理 200 个文件。这才是 Superpowers 的 “super” 所在——它让重构不再是高风险、高成本的手工劳动而是一次codex run命令。我个人在实际操作中的体会是Superpowers 不是让你少写代码而是让你把写代码的时间转移到写 YAML skill 上。一个写得好的 skill能为你省下几百小时的重复劳动。刚开始学写 YAML 可能花 2 小时但之后它每天为你省 20 分钟一个月就是 10 小时——这笔账越早算清越早受益。