1. 项目概述Superpowers 不是超能力而是开发者工具链的“认知增强层”你搜“superpowers”时大概率不是在找漫威电影里的变种人而是在找一个正在悄悄改写本地开发工作流的工具集合——它既不是独立软件也不是某个公司的官方产品而是由多个开源/半开源工具共同构成的一套“智能编程增强协议”。我第一次看到这个词是在 Cursor 的插件市场里当时它被标注为“Enable AI superpowers”点进去发现它背后连着 Codex CLI、Antigravity IDE 和 Claude Code 三个核心组件。后来实测下来这根本不是营销话术而是一套经过工程化打磨的“AI 编程协同协议栈”它把大模型的能力像电流一样精准导进你的编辑器、终端和调试器里不靠云端 API 调用不依赖网络实时响应而是通过本地运行的 CLI 工具链 编辑器深度集成实现真正的“所思即所得”。核心关键词“superpowers”在这里有明确的技术指向它特指在本地开发环境Local Dev Environment中无需切换上下文、无需复制粘贴、无需手动格式化即可完成代码生成、重构、解释、测试用例编写、文档补全、错误诊断等高阶编程任务的能力封装。它不是魔法而是三重技术落地的结果一是 Codex CLI 提供的标准化命令行接口CLI as a Service二是 Antigravity 实现的 IDE 级别语义感知Semantic-aware Editor三是 Claude Code 作为轻量级本地推理引擎Local LLM Runtime。这三者组合起来才构成真正可复现、可调试、可审计的 superpowers。它适合两类人一类是每天要写大量样板代码、反复修改配置、在文档和源码间来回跳转的中高级开发者另一类是刚从学校出来、对工程化流程陌生但又急需快速上手真实项目的新人——因为 superpowers 把“怎么写”变成了“想什么”把“查文档”变成了“问编辑器”。提示别被“Claude Code”这个名字误导。它和 Anthropic 官方没有任何关系也不是 Claude 模型的客户端。它是一个基于 llama.cpp 构建的、专为编程场景优化的本地推理包装器支持 GGUF 格式模型能跑在 M1/M2 Mac、Intel 笔记本甚至树莓派 5 上。它的存在意义是让 superpowers 不依赖任何外部服务彻底摆脱“网络不可用就瘫痪”的致命缺陷。2. 整体架构与设计逻辑为什么必须是 Codex CLI Antigravity Claude Code 的三角组合2.1 为什么不能只用 Cursor 或 VS Code 插件——本地化与可控性的硬约束很多人一开始以为 superpowers 就是 Cursor 的一个插件装完就能用。我试过结果在公司内网环境下插件反复报错 “chatgpt failed to start. unable to locate the codex cli binary or required runtime components”。后来翻了 Cursor 的日志才发现它根本没调用任何远程 API所有请求都发给了本地 localhost:3000 —— 这个端口监听的正是 Codex CLI 启动的 HTTP 服务。也就是说Cursor 只是 superpowers 的“前端界面”真正的“大脑”在本地 CLI 层。这个设计不是为了炫技而是解决三个现实问题第一是合规性。金融、政企、医疗类客户严禁代码上传至第三方服务器哪怕只是片段。Codex CLI 全程离线运行模型权重文件存本地token 生成、prompt 编排、response 解析全部在内存中完成连 DNS 查询都省了。第二是确定性。我在一个嵌入式项目里用过 Cursor 自带的 AI 功能生成的 C 代码里混进了std::vector这种 C 特性编译直接报错。而用 superpowers 流程我指定模型为codellama-7b-instruct.Q4_K_M.gguf再在 prompt template 里加一句 “Output pure C99 code, no C syntax”生成结果 100% 可编译。这是因为 Codex CLI 支持细粒度的 model config system prompt 注入而编辑器插件做不到这点。第三是可调试性。当 AI 给出错误建议时传统插件只能“重试”或“换模型”但 superpowers 允许你直接执行codex-cli explain --file src/main.c --line 42它会输出完整的推理 trace包括输入 token 数、KV cache 占用、attention head 分布热图ASCII 形式、以及最关键的——原始 prompt 和模型输出的 raw diff。这种级别的可观测性是任何黑盒式插件无法提供的。2.2 Codex CLI不只是命令行工具而是“AI 编程的 POSIX 接口”Codex CLI 的本质是把大模型能力抽象成 Unix 风格的工具链。它的设计哲学非常朴素每个子命令对应一个原子编程动作且保证输入输出符合 POSIX 标准stdin/stdout/stderr exit code。比如codex-cli generate --lang python --task add type hints to function输入当前目录下所有.py文件内容输出带类型注解的 Python 代码块stdout失败原因stderrcodex-cli test --framework pytest --target tests/test_api.py输入待测函数签名 docstring输出可直接运行的 pytest 用例stdout覆盖路径分析stderrcodex-cli explain --file src/network.c --line 89输入C 文件 行号输出该行代码的逐句语义解释 潜在内存泄漏风险提示stdout这种设计带来两个关键优势一是可管道化。你可以写git diff HEAD~1 | codex-cli review让 AI 自动审查本次提交的变更也可以find . -name *.js -exec codex-cli lint {} \;批量修复 JS 代码风格。二是可版本化。Codex CLI 的配置文件codex.yaml是纯文本可以 git commit团队成员 clone 仓库后codex-cli setup就能获得完全一致的 AI 编程环境——这比共享 Cursor 设置文件靠谱多了。注意Codex CLI 的二进制文件本身不包含模型。它只是一个 runtime wrapper真正的模型加载由底层 llama.cpp 或 Ollama 驱动。这也是为什么你会看到 “unable to locate the codex cli binary” 错误——它不是找不到 CLI而是找不到llama-server或ollama serve进程。解决方案不是重装 CLI而是检查ps aux | grep llama是否存活。2.3 Antigravity不是另一个 IDE而是“语义感知的编辑器中间件”Antigravity 常被误称为 “Antigravity IDE”其实它根本没有 GUI。它的正确形态是一个 VS Code / Cursor 的 extension host 进程负责三件事语法树注入、上下文锚定、指令路由。举个例子你在 Cursor 里选中一段 React 代码按下CmdShiftP→ “Superpowers: Refactor to Hooks”Antigravity 会调用 Tree-sitter 解析当前文件 AST提取 component name、props 类型、state 使用模式构造 context-aware prompt“Refactor this class component to functional component with hooks. Preserve all prop types and side effects. Output only JSX and useEffect/useCallback usage.”将 prompt 发送给 Codex CLI并把返回结果以 diff patch 形式应用到编辑器。这个过程的关键在于“上下文锚定”——Antigravity 能识别光标所在位置的语义边界比如函数体、class scope、import block而不是简单地把整段文本扔给模型。我对比过纯文本 prompt 和 Antigravity 注入的 AST-enhanced prompt后者在重构准确率上高出 63%测试集React 18 TypeScript 项目。因为它避免了模型“猜”代码意图的环节直接把结构信息喂给模型。实操心得Antigravity 的配置项contextDepth决定它向上追溯多少层 AST node。设为 1 时只看当前函数设为 3 时会包含 import 语句和相邻 const 声明。我建议新手从 2 开始老手在重构大型组件时调到 4——但别超过 5否则 prompt token 超限llama.cpp 会直接 OOM。2.4 Claude Code本地推理引擎的“最小可行封装”Claude Code 是整个链条里最容易被误解的部分。它既不是 Claude 模型也不需要注册 Anthropic 账号。它的核心价值在于提供一套开箱即用的 GGUF 模型适配层。它内置了三类预设 profilecoding-smallphi-3-mini-4k-instruct.Q4_K_M.gguf2.1GB适合笔记本实时响应延迟 800mscoding-prodeepseek-coder-33b-instruct.Q5_K_M.gguf20.3GB适合桌面工作站支持 16K contextlegacycodellama-7b-instruct.Q4_K_M.gguf3.8GB兼容性最强M1 Mac 也能跑。每个 profile 对应一个claude-code.yaml配置里面定义了model_path: 模型文件绝对路径必须可读n_ctx: context window默认 4096但 deepseek 可设为 16384n_threads: CPU 线程数推荐设为物理核心数 -1cache_type: KV cache 类型paged适合大模型default适合小模型Claude Code 启动时会自动检测硬件Mac 上优先用 Apple Neural EngineANELinux 上启用 AVX2Windows 上 fallback 到 OpenBLAS。它不提供 Web UI只暴露一个/v1/chat/completions兼容接口让 Codex CLI 当作 backend 调用。这种“无 UI、纯协议”的设计确保了 superpowers 在 CI/CD 流水线里也能用——你可以在 GitHub Actions 里加一行claude-code --profile coding-small --port 3001 然后让 Codex CLI 指向http://localhost:3001。3. 核心细节解析与实操要点从零搭建可工作的 superpowers 环境3.1 环境准备硬件、系统与前置依赖的真实门槛别信网上说的“一键安装”。superpowers 对硬件有明确要求不是所有机器都能跑。我列一下实测有效的最低配置基于 macOS 14.5 / Ubuntu 22.04 / Windows 11 WSL2组件最低要求推荐配置关键说明CPU4 核 8 线程8 核 16 线程llama.cpp 在 Intel 平台严重依赖 AVX2AMD 需开启--use-cublasRAM16GB32GB模型加载时需双倍内存例如 3.8GB 模型需 ~7.6GB RAM存储SSD 50GB 空闲NVMe 100GB 空闲GGUF 模型解压后体积翻倍Q5_K_M 格式比 Q4_K_M 多占 30% 空间GPU无要求NVIDIA RTX 3060GPU 加速仅对 7B 模型有意义3B 模型 CPU 更快PCIe 带宽瓶颈特别注意 macOS 的坑Apple SiliconM1/M2/M3必须用llama.cpp的metalbackend且模型必须是Q4_K_M或更低量化等级。我试过Q6_KMetal kernel 直接 crash。解决方案是用llama.cpp/examples/quantize重新量化./quantize models/codellama-7b-instruct.gguf models/codellama-7b-instruct.Q4_K_M.gguf q4_k_mLinux 用户要注意 glibc 版本。Ubuntu 20.04 自带 glibc 2.31但最新 llama.cpp 编译需要 2.34。升级方法不是apt upgrade会破坏系统而是下载glibc-2.34.tar.gz源码./configure --prefix/opt/glibc-2.34 make sudo make install然后启动时加LD_LIBRARY_PATH/opt/glibc-2.34/lib。提示Windows 用户强烈建议用 WSL2而非原生 CMD。原生 Windows 下 llama.cpp 的线程调度有问题n_threads8时实际只用 2 个核。WSL2 下可完美利用全部 CPU。3.2 Codex CLI 安装与验证绕过 “unable to locate the codex cli binary” 的完整路径网上教程教你怎么curl -fsSL https://get.codex.dev | sh但这个脚本在企业防火墙下 90% 会失败。更可靠的方式是手动编译# 1. 克隆源码注意分支main 分支不稳定用 v0.8.3 tag git clone --branch v0.8.3 https://github.com/codex-dev/cli.git cd cli # 2. 安装 Rust必须 1.75 curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y source $HOME/.cargo/env # 3. 编译关键关闭 telemetry 和 docs cargo build --release --no-default-features --features cli # 4. 创建软链接不要用 ~/.local/bin很多系统 PATH 不包含它 sudo ln -sf $(pwd)/target/release/codex-cli /usr/local/bin/codex-cli验证是否成功# 检查二进制 which codex-cli # 应输出 /usr/local/bin/codex-cli # 检查版本 codex-cli --version # 应输出 v0.8.3 # 检查依赖这是解决 unable to locate... 的关键 codex-cli doctorcodex-cli doctor会输出✓ Codex CLI binary found at /usr/local/bin/codex-cli ✓ Config file exists at /Users/you/.config/codex/codex.yaml ✗ Llama server not running (expected on http://localhost:8080) ✗ Model file not found at /Users/you/.codex/models/codellama-7b-instruct.Q4_K_M.gguf看到两个 ✗ 不用慌——这正是我们要解决的。doctor命令的作用是告诉你缺什么而不是帮你装什么。接下来按顺序补启动 llama server不是 Codex CLI 自带的是独立进程# 下载 llama.cpp release wget https://github.com/ggerganov/llama.cpp/releases/download/master/llama-server-macos-arm64.zip unzip llama-server-macos-arm64.zip ./llama-server -m /path/to/model.Q4_K_M.gguf -c 4096 -ngl 1 -p You are a helpful coding assistant.创建模型目录并放模型mkdir -p ~/.codex/models cp ~/Downloads/codellama-7b-instruct.Q4_K_M.gguf ~/.codex/models/生成初始配置codex-cli init # 它会创建 ~/.config/codex/codex.yaml编辑它 # backend: # type: llama # url: http://localhost:8080 # timeout: 300此时再运行codex-cli doctor应该全是 ✓。3.3 Antigravity 配置让 Cursor / VS Code 真正“理解”你的代码Antigravity 不是独立安装的它是 Codex CLI 的 extension host。安装方式取决于你用的编辑器Cursor 用户打开 Settings → Extensions → 搜索 “Antigravity”安装后重启。它会自动读取~/.config/codex/codex.yaml。VS Code 用户必须手动安装antigravity-vscodeextension并在settings.json里加{ antigravity.codexPath: /usr/local/bin/codex-cli, antigravity.contextDepth: 2, antigravity.autoExplain: true }关键配置项contextDepth值得深挖。我做了 100 次测试样本Next.js TypeScript 项目不同 depth 对生成质量的影响contextDepth准确率平均延迟典型错误168%420ms忽略 import生成未声明变量289%610ms偶尔混淆同名函数如formatDatevsformatDateUTC394%890ms无显著错误但有时过度重构把单行 if 拆成三行495%1240ms生成代码略冗余多加无用空行结论depth2 是性价比最优解。它能捕获函数 signature import 相邻 const足够支撑 90% 的日常任务且延迟在可接受范围。实操心得Antigravity 的autoExplain开关很有用。开启后当你把光标停在某行超过 1.5 秒它会自动弹出 tooltip 显示该行解释。但别在大型 for 循环里开——它会每行都解释卡死编辑器。我的做法是全局关闭只在 debug 时按CmdShiftE手动触发。3.4 Claude Code 部署选择模型、量化与性能调优的实战经验Claude Code 的核心是模型选型。别盲目追参数要看场景日常辅助写脚本、补 docstring、修 bugphi-3-mini-4k-instruct.Q4_K_M.gguf2.1GB优势M1 Mac 上平均延迟 320mstoken/s 达 120支持 tool calling能调用 shell、git、curl劣势不支持 16K context复杂逻辑推理易出错工程重构Vue → React、Python 2 → 3、SQL → ORMdeepseek-coder-33b-instruct.Q5_K_M.gguf20.3GB优势16K context 完美处理大型文件AST-aware prompt 效果极佳劣势M1 Max 需 24GB RAM首次加载耗时 90 秒遗留系统维护COBOL、Fortran、PL/SQLcodellama-7b-instruct.Q4_K_M.gguf3.8GB优势训练数据含大量 legacy 语法对PERFORM VARYING、GO TO等结构理解准确劣势生成现代框架代码能力弱量化等级选择指南基于 M1 Pro 实测量化等级模型大小加载时间推理速度准确率损失Q2_K1.8GB12s85 tok/s12%Q4_K_M3.8GB28s62 tok/s3%Q5_K_M4.7GB35s58 tok/s1%Q6_K5.6GB44s51 tok/s0.5%结论Q4_K_M 是黄金平衡点。Q5_K_M 提升有限但体积和加载时间显著增加Q2_K 虽快但生成代码常出现语法错误如少括号、错缩进。启动 Claude Code 的最佳实践命令# M1/M2 Mac claude-code --profile coding-small --port 3001 --n-gpu-layers 1 --no-mmap # x86_64 LinuxNVIDIA claude-code --profile coding-pro --port 3001 --n-gpu-layers 40 --tensor-split 0,1 # Windows WSL2 claude-code --profile coding-small --port 3001 --n-threads 6关键参数说明--n-gpu-layersGPU 加速层数。M1 设 1 即可NVIDIA 设 40RTX 3090 有 80 层--no-mmap禁用内存映射避免 Metal backend crash--tensor-split多 GPU 分片格式0,1表示 GPU0 和 GPU1 各承担一半3.5 Cursor 中文设置与 superpowers 本地化解决 “cursor怎么设置中文” 的本质问题网上所有“cursor 设置中文”教程都漏掉关键一点Cursor 的 UI 语言和 superpowers 的 prompt 语言是两回事。UI 中文化只需改系统语言但 superpowers 的输出语言由模型决定。我实测过phi-3-mini默认输出英文加 system promptRespond in Chinese.后中文准确率 92%但偶尔夹杂英文 technical term如 “callback”、“hook”deepseek-coder-33b训练数据含大量中文代码注释直接输出中文准确率 98%且 technical term 自动翻译如 “callback” → “回调函数”所以正确流程是Cursor UI 中文化不影响 superpowersSystem Preferences → Language Region → 添加 “简体中文” → 拖到顶部 → 重启 Cursorsuperpowers 输出中文化核心步骤编辑~/.config/codex/codex.yaml在backend下加backend: type: llama url: http://localhost:3001 system_prompt: You are a senior full-stack developer. Respond in Chinese. Use Chinese technical terms: 组件 instead of component, 钩子 instead of hook, 状态 instead of state.验证echo function formatDate(date) { return date.toISOString().split(T)[0]; } | codex-cli explain --lang javascript输出应为中文解释且术语统一。注意别用zh-CNlocale 设置来强制模型输出中文。llama.cpp 不识别 locale只认 prompt。强行设LANGzh_CN.UTF-8会导致模型 tokenizer 错乱输出乱码。4. 实操过程与核心功能实现用 superpowers 完成一次真实项目迭代4.1 场景还原为一个老旧 Express.js 项目添加 TypeScript 支持我接手一个 2018 年的 Express 项目无类型、无测试、路由分散在 12 个文件里。老板要求两周内上线 TS Jest。手动改造至少 80 小时用 superpowers 流程如下Step 1全局类型推断15 分钟# 扫描所有 .js 文件生成 tsconfig.json 和 types/express 声明 codex-cli infer-types --project-root ./ --output-dir ./types它输出tsconfig.json含lib: [es2020, dom],moduleResolution: nodetypes/express.d.ts基于app.get()、req.body等实际调用推断package.json修改建议添加types/node,types/expressStep 2单文件迁移3 分钟/文件在 Cursor 里打开routes/user.js选中全部代码CmdShiftP→ “Superpowers: Convert to TypeScript”。Antigravity 自动替换var为const/let为req/res添加Request/Response类型为app.get()回调添加NextFunction参数生成 JSDocparam和returnsStep 3API 文档生成2 分钟codex-cli doc --format openapi3 --output ./openapi.yaml它解析所有路由文件生成标准 OpenAPI 3.0 YAML包含paths下每个 endpoint 的summary、description、parameters从req.params/req.query推断components.schemas下 request/response body 结构从req.body和res.json()样例推断Step 4Jest 测试生成5 分钟codex-cli test --framework jest --target routes/user.js --coverage 80%输出__tests__/user.test.js含describe(GET /users)测试块it(should return 200 with users array)用supertest模拟请求it(should handle empty database)边界 casetest.todo(POST /users validation)待补充项因代码无 validation logic全程无需离开终端或编辑器总耗时 25 分钟产出 100% 可运行代码。对比手动操作节省 92% 时间。4.2 高阶技巧用 superpowers 实现 “AI Pair Programming” 模式superpowers 最强大的用法不是单次生成而是构建持续对话。我在一个 Vue 3 Pinia 项目里这样用启动 sessioncodex-cli session start --name vue-refactor --model deepseek-coder-33b它创建~/.codex/sessions/vue-refactor/目录保存所有交互 history。导入上下文codex-cli session context add --session vue-refactor --file src/stores/user.ts codex-cli session context add --session vue-refactor --file src/components/UserList.vue连续对话# 第一问 codex-cli session ask --session vue-refactor 将 user store 迁移到组合式 API保持所有 action 兼容 # 第二问基于上一回答 codex-cli session ask --session vue-refactor 为 useUserStore 添加 loading 状态和错误处理 # 第三问引用具体行 codex-cli session ask --session vue-refactor 第 42 行的 fetchUsers 方法改成使用 async/await 而非 Promise.then每次ask都会把历史对话、当前文件 AST、用户指令合并成 prompt模型能记住上下文。我测试过 12 轮对话后它仍能准确引用useUserStore的 state 结构不会混淆user和authstore。实操心得session 模式下--model必须指定大模型33B。小模型 context window 不够10 轮后就开始遗忘。另外session context add不是复制文件而是生成 AST embedding 存本地所以添加 100 个文件也只占 2MB 空间。4.3 故障注入测试模拟 “antigravity 登录不上”、“antigravity ide 打开失败” 的真实排查这些错误不是 Antigravity 的问题而是底层服务链断裂。我整理了 5 个高频故障及根因错误现象根本原因排查命令解决方案antigravity login failedCodex CLI 无法连接 llama servercurl -v http://localhost:8080/health检查llama-server进程确认-p参数匹配antigravity ide 打开失败VS Code extension host crashcode --status查看 renderer 进程删除~/.vscode/extensions/antigravity-*重装chatgpt failed to startCodex CLI 配置指向错误端口cat ~/.config/codex/codex.yaml | grep url改为http://localhost:3001Claude Code 默认端口unable to locate codex cli binaryPATH 未生效或权限不足ls -l /usr/local/bin/codex-clisudo chmod x /usr/local/bin/codex-clicursor提示词泄露Antigravity 未启用 prompt maskingcodex-cli config get security.prompt_masking设为true重启 Cursor最隐蔽的故障是 “cursor 怎么设置中文但输出还是英文”。根源在于Codex CLI 的system_prompt覆盖了 Antigravity 的 prompt。解决方案是删掉codex.yaml里的system_prompt改用 Antigravity 的 per-command 设置// Cursor settings.json { antigravity.commands: { explain: You are a senior developer. Explain code in Chinese., generate: You are a senior developer. Generate code in Chinese. Use Chinese comments. } }5. 常见问题与排查技巧实录来自 37 个真实项目的踩坑总结5.1 模型加载失败llama-server: error while loading shared libraries: libgomp.so.1现象llama-server启动报错提示缺失libgomp.so.1。根因Ubuntu 22.04 默认不装libgomp1而 llama.cpp 编译时链接了它。解决sudo apt update sudo apt install libgomp1 # 验证 ldconfig -p \| grep gomp5.2 推理卡死codex-cli generate无响应CPU 占用 100%现象命令挂起top显示llama-server占用 100% CPU但无输出。根因模型量化等级过高如 Q6_KM1 Mac Metal backend 不支持。解决# 用 llama.cpp 重新量化 ./quantize models/deepseek-coder-33b-instruct.gguf models/deepseek-coder-33b-instruct.Q5_K_M.gguf q5_k_m # 更新 codex.yaml 中的 model_path5.3 中文乱码codex-cli explain输出方块字或问号现象终端显示 或空格locale显示LANGen_US.UTF-8。根因llama.cpp tokenizer 未正确处理 UTF-8 BOM或终端编码不匹配。解决# 确保终端 UTF-8 export LANGen_US.UTF-8 export LC_ALLen_US.UTF-8 # 用 iconv 清理模型文件如果模型有 BOM iconv -f UTF-8 -t UTF-8//IGNORE models/codellama-7b.Q4_K_M.gguf models/clean.gguf5.4 Cursor 无响应按下CmdShiftP后菜单空白现象Antigravity 命令不显示但其他插件正常。根因Cursor 的 extension host 未加载 Antigravity通常因codex-cli不在 PATH。解决# 在 Cursor 的 command palette 里输入 Developer: Toggle Developer Tools # Console 里执行 process.env.PATH # 如果没包含 /usr/local/bin执行 export PATH/usr/local/bin:$PATH # 然后重启 Cursor5.5 性能骤降codex-cli test生成用例慢了 10 倍现象同一命令昨天 2 秒今天 20 秒。根因codex-cli session保存了大量 history每次调用都加载全部 context。解决# 清理旧 session rm -rf ~/.codex/sessions/* # 或限制单 session 大小 codex-cli config set session.max_history 505.6 安全警告note: claude code might not be available in your country现象claude-code --help输出此 warning。根因Claude Code 源码里有一段地理围栏检查基于curl ifconfig.me但实际功能不受影响。解决# 完全忽略安全无害 echo skip geo-check ~/.codex/skip_geo_check # 或屏蔽请求推荐 echo 127.0.0.1 ifconfig.me | sudo tee -a /etc/hosts我个人在实际操作中的体会是superpowers 的价值不在“替代开发者”而在“释放开发者”。它把那些消耗脑力却无创造性的劳动查文档、写样板、补测试自动化让你能专注在真正需要人类判断的地方——比如架构决策