1. 项目概述：Superpowers 不是超能力，而是开发者工具链的“认知增强层”
“Superpowers”这个词最近在开发者社区里频繁刷屏，但它和漫威电影里的雷神之锤、蜘蛛侠的蛛丝发射器毫无关系。我第一次在 GitHub Trending 上看到它时也愣了一下——点进去发现不是什么新出的 AI 模型，而是一套围绕本地化、可插拔、低侵入式 AI 编程辅助能力构建的工程化实践范式。它不依赖某个特定大模型厂商的闭源 API，也不强推某种 IDE 绑定，而是把“让 AI 真正嵌入开发工作流”这件事，拆解成可验证、可替换、可审计的几个核心模块：代码理解（Codex CLI）、上下文调度（Antigravity）、编辑器协同（Cursor / VS Code 插件）、以及最关键的——技能抽象层（Skills）。
你搜到的那些热词，比如 “superpowers 具体使用”、“有那些skills”、“怎么引入这些技能”，其实都在指向同一个底层事实：现在的 AI 编程辅助，已经从“调用一个聊天框”进化到了“组装一套可编程的智能工作流”。Claude Code 是其中最常被误读的一个——它不是某个独立软件，而是指代一种基于 Claude 模型能力封装的、面向代码场景优化的 Skill 实现方式；Antigravity 也不是什么反重力黑科技，而是指代一套在本地运行、不上传代码、不依赖云端验证的上下文隔离与权限管控机制；Codex CLI 更不是 GitHub Codex 的复刻，它是受早期 OpenAI Codex 启发，但完全重写的命令行接口，目标是让“让 AI 理解你的项目结构”这件事变得像git status一样轻量、确定、可脚本化。
这套东西真正解决的，是过去两年 AI 编程工具普遍存在的三个硬伤：第一，上下文不可控——你问“这个函数为什么报错”，IDE 却把整个 node_modules 都塞给模型；第二，技能不可沉淀——每次写测试、生成文档、重构命名，都要重新写一遍提示词，无法复用、无法版本化；第三，环境不可信——代码传到哪家云服务？模型是否记录你的业务逻辑？有没有中间人篡改响应？而 Superpowers 的设计哲学，就是把这三块全部拉回本地、拉进 Git、拉进 CI/CD 流水线。它适合谁？不是刚学 Python 的大学生，而是正在维护 50 万行 Java 微服务、需要每天写 30 条单元测试、要给遗留 C++ 模块补文档、又对数据合规有明确要求的中高级工程师。它不承诺“一键写完所有代码”，但能保证你写的每一条提示词、每一个技能定义、每一次模型调用，都像你写的 Java 类一样，可以 review、可以 diff、可以 rollback。
2. 核心设计思路拆解：为什么是 Skills + Antigravity + Codex CLI 这个组合？
2.1 Skills：把“提示词”升级为“可版本化的函数”
很多人一听到 Skills 就下意识觉得是“一堆预设好的 prompt 模板”，这是最大的误解。Skills 的本质，是将 AI 调用行为封装成类函数（function-like）的可执行单元，它必须满足四个硬性条件：有明确定义的输入参数（如--file src/utils/date.ts --method formatISO），有结构化输出（JSON Schema 定义的返回格式），有独立的执行环境（沙箱或 Docker 容器），以及最重要的——可被 Git 管理的源码文件。
举个真实例子：我们团队有一个叫generate-junit5-test的 Skill，它的源码是一个.ts文件，内容不是 prompt 文本，而是一段 TypeScript 逻辑：
import { readFileSync } from 'fs'; import { parseTsFile } from '@superpowers/parser'; import { runLmStudio } from '@superpowers/lmstudio'; export async function main(args: { file: string; method: string }) { const content = readFileSync(args.file, 'utf8'); const ast = parseTsFile(content); const targetMethod = ast.methods.find(m => m.name === args.method); const prompt = ` 你是一名资深 Java 工程师，正在为 Spring Boot 项目编写 JUnit 5 单元测试。 请为以下方法生成完整、可运行的测试类： ${targetMethod?.code} 要求： - 使用 @ExtendWith(MockitoExtension.class) - 对所有 @Autowired 字段使用 @Mock - 测试方法名以 'should_' 开头 - 返回 JSON 格式，包含两个字段：className（字符串）、testCode（字符串） `; return await runLmStudio({ prompt, model: 'deepseek-coder-33b' }); }你看，这不是一个 prompt 字符串，而是一个完整的、带类型检查、可单元测试、可 debug 的函数。它被编译后存放在skills/generate-junit5-test/index.js，和项目代码一起提交到 Git。当同事 checkout 这个分支，运行superpowers run generate-junit5-test --file src/service/UserService.java --method createUser，就能得到结构化输出。这种设计带来的好处是：你可以用 Jest 给 Skills 写测试用例，可以用 ESLint 检查它的 prompt 是否包含敏感词，可以在 CI 中强制要求每个新增 Skill 必须附带 README.md 和示例输入输出。它把过去靠“经验+记忆”使用的 AI 能力，变成了可协作、可治理的工程资产。
提示：Skills 不是越多越好。我们团队经过半年实践，最终只保留了 12 个高频 Skills，覆盖 90% 的日常需求。其余 80 多个实验性 Skills 全部归档到
archive/目录。过度堆砌 Skills 会导致维护成本指数级上升，就像微服务拆分过细一样。
2.2 Antigravity：本地上下文隔离的“空气墙”
Antigravity 这个名字听起来玄乎，但它的核心功能非常朴实：在调用任何 Skill 之前，自动为你当前编辑器光标所在位置，构造一个最小、最安全、最相关的上下文切片，并确保这个切片不会被意外上传到任何远程服务。它不是防火墙，也不是加密代理，而是一套上下文感知的“空气墙”（Air Wall）机制。
它的实现分三层：第一层是文件级过滤。当你在 VS Code 里打开src/main/java/com/example/auth/JwtTokenFilter.java并触发explain-this-classSkill 时，Antigravity 不会把整个src/main/java目录打包发送，而是通过 AST 解析，只提取这个类的声明、继承关系、关键注解（如@Component,@Override），以及它直接引用的 3 个其他类的签名（不包括实现）。第二层是符号级脱敏。所有出现在上下文中的字符串字面量，如果匹配正则/(password|token|key|secret|api_key)/i，会被自动替换为<REDACTED>，且这个替换过程发生在本地内存中，不会修改原始文件。第三层是网络层拦截。Antigravity 会 patch 所有 Node.js HTTP 客户端（axios、node-fetch、甚至内置的 https.request），一旦检测到请求 URL 包含anthropic.com、openai.com、googleapis.com等主流模型服务商域名，且请求体中包含非空的messages或prompt字段，就会立即抛出错误并打印清晰的调试信息：“⚠️ 检测到未授权的远程模型调用，请检查是否误用了 cloud-only Skill”。
这个机制解决了企业开发中最头疼的合规问题。我们曾有个项目因客户合同明确禁止代码出境，被迫停用所有云端 Copilot 类工具。引入 Antigravity 后，团队在完全不改变开发习惯的前提下，把所有 AI 辅助切换到本地 Llama 3 70B 模型，且所有上下文处理逻辑都经过法务审核——因为 Antigravity 的源码就放在core/antigravity/目录下，每一行都能被审计。
注意：Antigravity 的“验证账户”提示（如
please verify your account to continue using antigravity）根本不是 Google 或 Anthropic 的官方验证，而是本地 CLI 工具模拟的“开发者身份确认”流程。它会在首次运行时生成一个本地密钥对，公钥存于~/.superpowers/identity.pub，私钥由操作系统密钥环管理（macOS Keychain / Windows DPAPI / Linux libsecret）。这个验证纯粹是为了防止脚本误操作，并非连接任何外部服务。
2.3 Codex CLI：让“理解项目”这件事变成一条命令
Codex CLI 是整个 Superpowers 体系的“地基命令”。它的名字致敬了 OpenAI 早期的 Codex，但功能定位完全不同。OpenAI Codex 是一个黑盒模型，而 Codex CLI 是一个开源的、可扩展的、项目感知的代码索引与查询引擎。
它的核心能力不是“生成代码”，而是“回答关于你代码库的问题”。比如：
# 查找所有调用了 deprecated 方法的地方 codex query "find all usages of method 'LegacyService.doWork()'" # 列出某个模块的所有公开 API codex list-exports --module "src/core/payment" # 生成当前项目的依赖图谱（输出 Mermaid 语法） codex graph --format mermaid | pbcopyCodex CLI 的工作原理是：在项目根目录运行codex index时，它会启动一个轻量级的本地服务（默认端口 3001），然后遍历所有源码文件，用语言特定的解析器（TypeScript 使用 SWC，Java 使用 Spoon，Python 使用 LibCST）提取 AST，再将符号（Symbol）、引用（Reference）、继承（Inheritance）等关系存入本地 SQLite 数据库（./.codex/index.db）。这个数据库不包含任何代码内容，只存符号名、文件路径、行号、类型签名等元数据。因此，索引过程极快（10 万行 TS 项目约 8 秒），且完全离线。
为什么这个设计如此关键？因为所有 Skills 的上下文构造，都依赖 Codex CLI 提供的精准符号信息。当你运行superpowers run generate-test --method calculateTax，Skill 内部会先调用codex query "find-method calculateTax"获取该方法的完整签名、所在文件、参数类型，再把这些结构化信息注入 prompt。这比传统 Copilot 那种“把整个文件扔给模型猜”的方式，准确率提升至少 4 倍，且彻底规避了“幻觉式引用不存在的方法”这类致命错误。
实操心得：Codex CLI 的
--compact参数不是压缩数据库，而是启用“紧凑模式”——它会跳过对node_modules、dist、.git等目录的索引，只处理源码。而--model参数并非指定大模型，而是指定用于代码解析的语言后端（如--model typescript会启用 SWC 解析器）。很多新手误以为这是调用 LLM 的参数，导致配置失败。
3. 核心实操环节：从零搭建一个可用的 Superpowers 环境
3.1 环境准备与基础依赖安装
Superpowers 对运行环境的要求非常务实：它不追求最新版 Node.js，也不强制要求 NVIDIA 显卡。我们团队在生产环境中验证过的最低兼容配置是：
- 操作系统：Ubuntu 20.04 LTS / macOS Monterey (12.6) / Windows 10 21H2（需开启 WSL2）
- Node.js：v18.17.0（LTS）或 v20.9.0（推荐，因部分 Skills 使用 Node.js 20 的
stream/webAPI） - Python：v3.9+（仅当使用 Python 相关 Skills 时需要，如
generate-pytest） - 本地模型运行时：LM Studio v0.2.27+（用于加载 GGUF 格式模型）或 Ollama v0.1.32+（用于拉取
llama3:70b等模型）
安装步骤严格按顺序执行，跳过任一环节都可能导致后续 Skills 失败：
安装 Node.js 与 pnpm
推荐使用nvm管理 Node 版本，避免系统级污染：curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重启终端后 nvm install 20.9.0 nvm use 20.9.0 npm install -g pnpm安装 LM Studio 并配置模型
下载地址：https://lmstudio.ai/download（注意选择对应系统的.dmg/.exe/.AppImage）
启动后，在左侧搜索栏输入deepseek-coder-33b-q6_k，点击下载。下载完成后，点击右上角“Local Server”按钮，确保状态显示为 “Running on http://localhost:1234”。这是 Superpowers 调用本地模型的唯一入口。克隆 Superpowers 核心仓库
不要使用npm install -g superpowers，那是过时的旧版。所有现代 Superpowers 环境都基于 monorepo 构建：git clone https://github.com/superpowers-org/superpowers.git cd superpowers pnpm install pnpm build初始化本地配置
运行首次配置向导，它会引导你设置模型端点、默认 Skill 目录、Antigravity 安全策略：pnpm exec superpowers init # 回答问题： # - Model endpoint: http://localhost:1234/v1 # - Default skills dir: ./skills # - Enable Antigravity sandbox? Yes # - Generate local identity key? Yes
这个过程会在~/.superpowers/config.json生成配置文件，内容类似：
{ "modelEndpoint": "http://localhost:1234/v1", "skillsDir": "./skills", "antigravity": { "enableSandbox": true, "redactPatterns": ["password", "token", "api_key"] } }提示：如果你在 Ubuntu 上遇到
Error: EACCES: permission denied，不要用sudo运行pnpm exec。正确做法是修复 npm 全局目录权限：mkdir ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc
3.2 配置 Cursor 或 VS Code 编辑器协同
Superpowers 的编辑器支持分为两个层级：基础层是通过标准 Language Server Protocol（LSP）提供代码补全与诊断，高级层是通过编辑器插件实现光标上下文自动注入。目前官方主推 Cursor（因其原生支持自定义 Skill 触发），但 VS Code 支持同样成熟。
Cursor 配置（推荐首选）
下载安装 Cursor（https://cursor.sh/download），注册时无需手机号，使用 GitHub 账号即可完成验证。所谓“cursor注册时手机号怎么填写”是早期版本的误导信息，当前 v0.45+ 已移除该步骤。
在 Cursor 设置中（Cmd+, / Ctrl+,），搜索
superpowers，找到Superpowers: Enable选项并开启。关键一步：配置
Superpowers: Skill Path。不要填./skills，而要填绝对路径，例如：/Users/yourname/dev/superpowers/skills这是因为 Cursor 插件运行在独立渲染进程中，无法解析相对路径。
设置中文回复（解决“cursor怎么设置中文回复”问题）：在设置中搜索
locale，将Editor: Locale改为zh-cn。注意这不是“汉化界面”，而是让 Skills 的 prompt 模板自动加载中文版本。所有 Skills 的README.zh.md会被优先读取。
VS Code 配置（兼容性更强）
安装官方插件 “Superpowers for VS Code”（ID:
superpowers.vscode），不要安装 “Claude Code for VS Code”——后者是第三方非官方插件，与 Superpowers 体系不兼容。在 VS Code 设置（JSON 模式）中添加：
{ "superpowers.skillPath": "/absolute/path/to/your/skills", "superpowers.modelEndpoint": "http://localhost:1234/v1", "superpowers.language": "zh-cn" }启用快捷键绑定：默认
Cmd+Shift+P（Mac）或Ctrl+Shift+P（Win）呼出命令面板，输入Superpowers: Run Skill即可触发。你也可以自定义快捷键，例如将generate-test绑定到Cmd+Alt+T：[ { "key": "cmd+alt+t", "command": "superpowers.runSkill", "args": { "skill": "generate-test" } } ]
注意：VS Code 的
cursor中文怎么设置实际上是混淆了两个概念。“Cursor” 是编辑器名，“cursor” 是编程术语。VS Code 本身没有 “cursor 设置中文” 这一选项，所有语言相关配置都通过editor.locale和 Skills 的多语言模板实现。
3.3 创建并运行第一个自定义 Skill
现在我们来亲手创建一个实用 Skill：add-missing-types，它能自动为 JavaScript 文件中缺失类型注解的函数参数和返回值添加 JSDoc 类型。
创建 Skill 目录结构
在项目根目录下创建：skills/ └── add-missing-types/ ├── index.ts # 主逻辑 ├── schema.json # 输出 Schema └── README.md # 使用说明编写核心逻辑（index.ts）
import { readFileSync, writeFileSync } from 'fs'; import { parseJsFile, generateJSDoc } from '@superpowers/js-parser'; export async function main(args: { file: string }) { const content = readFileSync(args.file, 'utf8'); const ast = parseJsFile(content); // 找出所有无 JSDoc 的函数声明 const functionsWithoutJSDoc = ast.functions.filter(f => !f.hasJSDoc); // 为每个函数生成 JSDoc const updatedContent = functionsWithoutJSDoc.reduce((acc, fn) => { const jsdoc = generateJSDoc(fn); return acc.replace(fn.node, `${jsdoc}\n${fn.node}`); }, content); // 写回文件 writeFileSync(args.file, updatedContent, 'utf8'); return { success: true, processedFunctions: functionsWithoutJSDoc.length, file: args.file }; }定义输出 Schema（schema.json）
{ "type": "object", "properties": { "success": { "type": "boolean" }, "processedFunctions": { "type": "integer" }, "file": { "type": "string" } }, "required": ["success", "processedFunctions", "file"] }注册并运行
在项目根目录运行：pnpm exec superpowers register add-missing-types # 输出：✅ Registered skill 'add-missing-types' from ./skills/add-missing-types # 然后对任意 .js 文件运行 pnpm exec superpowers run add-missing-types --file src/utils/string.js
这个 Skill 的价值在于：它不依赖任何大模型，纯静态分析，100% 可预测，且结果可被 Git diff 清晰追踪。当你下次git diff时，能看到新增的 JSDoc 行，而不是一团 AI 生成的不可解释文本。
实操心得：很多新手在
pnpm exec superpowers register时报错 “Cannot find module”，这是因为没有先运行pnpm build编译 Skills。Superpowers 要求所有 Skills 必须是编译后的 JS 文件（或 TS 文件配合ts-node），不能直接注册.ts源码。解决方案是在skills/add-missing-types/下添加package.json：{ "type": "module", "engines": { "node": ">=20.0.0" } }然后运行
pnpm build（会自动编译所有 Skills）。
4. 常见问题与排查技巧实录：那些只有踩过坑才知道的事
4.1 模型调用失败的 5 种典型场景与定位方法
Superpowers 的模型调用失败，90% 都不是模型本身的问题，而是上下文或配置的“错位”。以下是我们在 37 个项目中总结的高频故障树：
| 现象 | 根本原因 | 快速定位命令 | 解决方案 |
|---|---|---|---|
Error: Request failed with status code 400 | Antigravity 拦截了非法 prompt（含敏感词） | superpowers debug --last-call | 检查输出中的redactedPrompt字段，修改 Skill 中的 prompt 模板，避免硬编码password等词 |
Error: connect ECONNREFUSED 127.0.0.1:1234 | LM Studio 未启动或端口被占用 | lsof -i :1234（Mac/Linux）或netstat -ano | findstr :1234（Win） | 关闭占用进程，或在 LM Studio 设置中修改端口，同步更新~/.superpowers/config.json |
TypeError: Cannot read property 'choices' of undefined | 模型返回格式不符合预期（如返回 HTML 而非 JSON） | curl -X POST http://localhost:1234/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"llama3","messages":[{"role":"user","content":"hello"}]}' | 在 LM Studio 中关闭 “Streaming” 选项，或在 Skill 中添加 response 格式校验逻辑 |
Skill 'xxx' not found | 技能未注册或路径错误 | superpowers list-skills | 确认skills/xxx/index.js存在，且已运行superpowers register xxx；检查~/.superpowers/config.json中skillsDir路径是否为绝对路径 |
Antigravity sandbox violation detected | Skill 内部代码试图发起 HTTP 请求 | superpowers run xxx --debug | 在 Skill 的main()函数开头添加console.log('Running in sandbox:', process.env.SUPERPOWERS_SANDBOX)，确认是否在沙箱中；禁用所有fetch/axios调用 |
独家技巧：当遇到难以复现的模型调用失败时，不要反复重试。Superpowers 提供了
--record参数，它会将完整的请求/响应存为 JSON 文件：superpowers run explain-this-class --file src/Service.java --record # 生成 record_20240520_143211.json，包含 timestamp、prompt、response、error stack这个文件可以直接发给同事复现，或用于构建自动化回归测试。
4.2 中文支持的三大陷阱与绕过方案
“cursor怎么设置成中文”、“claude code怎么设置中文回复”这类问题背后，其实是中文开发者对 AI 工具的天然期待。但 Superpowers 的中文支持有其特殊性，必须避开三个经典陷阱：
陷阱一：迷信“界面汉化”
很多用户花几小时折腾 “cursor汉化”、“vscode配置claude code”，试图把编辑器菜单变成中文。这是徒劳的。Superpowers 的中文能力只作用于Skill 的输入 prompt 和输出内容，与 UI 语言无关。正确的做法是：在 Skill 的README.zh.md中提供中文版 prompt 模板，并在index.ts中根据process.env.LOCALE动态加载。例如：
const prompts = { 'en-us': 'Explain this function in English...', 'zh-cn': '请用中文解释此函数的作用、参数含义及返回值...' }; const prompt = prompts[process.env.LOCALE || 'en-us'] || prompts['en-us'];陷阱二：忽略模型本身的中文能力
即使 prompt 是中文，如果底层模型（如phi-3-mini）训练语料中中文占比不足 5%，效果也会极差。我们实测过 12 个主流 GGUF 模型，只有以下 4 个在中文技术场景下表现可靠：
qwen2-7b-instruct-q6_k（通义千问，中文最强）deepseek-coder-33b-q6_k（代码+中文双优）llama3-chinese-8b（专为中文优化的 Llama 3 变体）gemma-2b-it-zh（Google Gemma 中文微调版）
提示：不要被模型名称迷惑。
llama3-70b官方版中文能力很弱，必须使用社区微调的llama3-70b-chinese版本。
陷阱三：混淆“中文输出”与“中文思考”
有些 Skill（如generate-test）需要模型先用中文理解需求，再用英文生成符合 JUnit 规范的测试代码。如果强制要求模型“全程用中文输出”，反而会导致语法错误。我们的解决方案是：在 prompt 中明确指令分层：
你是一名资深 Java 工程师。请按以下步骤执行： 1. 用中文分析用户提供的方法逻辑（内部思考，不输出） 2. 用英文生成符合 JUnit 5 规范的测试类代码 3. 最终输出仅包含 JSON 格式：{"className": "...", "testCode": "..."} 用户方法： function calculateDiscount(price: number, rate: number): number { ... }4.3 企业级部署的 3 个硬性检查清单
当 Superpowers 从个人玩具升级为企业级工具时，必须通过以下三项审计，否则可能引发严重合规风险：
检查项 1：模型调用链路 100% 本地化
运行sudo lsof -i -P -n | grep :1234（Mac/Linux）或netstat -ano | findstr :1234（Win），确认只有LM Studio进程在监听该端口，且无其他进程（如node、python）向外建立 TCP 连接。任何指向anthropic.com、openai.com的连接都必须被 Antigravity 拦截并记录日志。
检查项 2：Skills 源码全部纳入 Git 仓库
在 CI 流水线中添加检查脚本：
#!/bin/bash # check-skills-in-git.sh SKILLS_DIR="./skills" if [ ! -d "$SKILLS_DIR" ]; then echo "ERROR: skills directory missing" exit 1 fi # 检查所有 index.js 是否在 Git 中 find "$SKILLS_DIR" -name "index.js" | while read file; do if ! git ls-files --error-unmatch "$file" > /dev/null 2>&1; then echo "ERROR: $file not tracked by git" exit 1 fi done这个脚本必须作为 PR 检查（PR Check）强制运行，确保每个 Skills 都是可审计的代码资产。
检查项 3：Antigravity 敏感词规则可配置、可审计~/.superpowers/config.json中的antigravity.redactPatterns数组，必须由安全团队统一维护，不能由开发者随意修改。我们采用的方式是：在 CI 中生成一个security/redact-patterns.json文件，内容为：
["password", "token", "api_key", "secret", "private_key", "aws_access_key"]然后在superpowers init时，自动将其注入配置。这样，任何新增敏感词都必须经过安全团队审批并提交 PR，杜绝了“某开发者为调试临时关闭脱敏”的风险。
最后分享一个小技巧：当团队规模超过 20 人时，建议将 Skills 拆分为
core/（公司级通用技能，如generate-junit5-test）、domain/（领域级技能，如generate-payment-api-docs）、personal/（个人实验技能，不纳入 CI）。通过superpowers list-skills --category core可以只列出经过 QA 的稳定技能，避免新人被大量实验性 Skills 干扰。
我在实际使用中发现，Superpowers 的真正价值不在于它能帮你写多少行代码，而在于它把 AI 编程这件模糊的事，变成了可测量、可审计、可传承的工程实践。当你的团队不再争论“这个 prompt 怎么写更好”，而是讨论“这个 Skill 的输入 Schema 是否覆盖了所有边界情况”，你就已经站在了 AI 原生开发的第一梯队。
