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 使用 SWCJava 使用 SpoonPython 使用 LibCST提取 AST再将符号Symbol、引用Reference、继承Inheritance等关系存入本地 SQLite 数据库./.codex/index.db。这个数据库不包含任何代码内容只存符号名、文件路径、行号、类型签名等元数据。因此索引过程极快10 万行 TS 项目约 8 秒且完全离线。为什么这个设计如此关键因为所有 Skills 的上下文构造都依赖 Codex CLI 提供的精准符号信息。当你运行superpowers run generate-test --method calculateTaxSkill 内部会先调用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需开启 WSL2Node.jsv18.17.0LTS或 v20.9.0推荐因部分 Skills 使用 Node.js 20 的stream/webAPIPythonv3.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 ~/.bashrc3.2 配置 Cursor 或 VS Code 编辑器协同Superpowers 的编辑器支持分为两个层级基础层是通过标准 Language Server ProtocolLSP提供代码补全与诊断高级层是通过编辑器插件实现光标上下文自动注入。目前官方主推 Cursor因其原生支持自定义 Skill 触发但 VS Code 支持同样成熟。Cursor 配置推荐首选下载安装 Cursorhttps://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 }启用快捷键绑定默认CmdShiftPMac或CtrlShiftPWin呼出命令面板输入Superpowers: Run Skill即可触发。你也可以自定义快捷键例如将generate-test绑定到CmdAltT[ { key: cmdaltt, command: superpowers.runSkill, args: { skill: generate-test } } ]注意VS Code 的cursor中文怎么设置实际上是混淆了两个概念。“Cursor” 是编辑器名“cursor” 是编程术语。VS Code 本身没有 “cursor 设置中文” 这一选项所有语言相关配置都通过editor.locale和 Skills 的多语言模板实现。3.3 创建并运行第一个自定义 Skill现在我们来亲手创建一个实用 Skilladd-missing-types它能自动为 JavaScript 文件中缺失类型注解的函数参数和返回值添加 JSDoc 类型。创建 Skill 目录结构在项目根目录下创建skills/ └── add-missing-types/ ├── index.ts # 主逻辑 ├── schema.json # 输出 Schema └── README.md # 使用说明编写核心逻辑index.tsimport { 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 }; }定义输出 Schemaschema.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 400Antigravity 拦截了非法 prompt含敏感词superpowers debug --last-call检查输出中的redactedPrompt字段修改 Skill 中的 prompt 模板避免硬编码password等词Error: connect ECONNREFUSED 127.0.0.1:1234LM Studio 未启动或端口被占用lsof -i :1234Mac/Linux或netstat -ano | findstr :1234Win关闭占用进程或在 LM Studio 设置中修改端口同步更新~/.superpowers/config.jsonTypeError: Cannot read property choices of undefined模型返回格式不符合预期如返回 HTML 而非 JSONcurl -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 detectedSkill 内部代码试图发起 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-zhGoogle 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 :1234Mac/Linux或netstat -ano | findstr :1234Win确认只有LM Studio进程在监听该端口且无其他进程如node、python向外建立 TCP 连接。任何指向anthropic.com、openai.com的连接都必须被 Antigravity 拦截并记录日志。检查项 2Skills 源码全部纳入 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 21; then echo ERROR: $file not tracked by git exit 1 fi done这个脚本必须作为 PR 检查PR Check强制运行确保每个 Skills 都是可审计的代码资产。检查项 3Antigravity 敏感词规则可配置、可审计~/.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 原生开发的第一梯队。