尧图网站建设 
1. 项目概述Superpowers 不是超能力而是开发者工具链的“认知增强层”“Superpowers”这个词最近在开发者社区里频繁刷屏但它和漫威电影里的变种人毫无关系。我第一次在 GitHub Trending 上看到它时也以为是个新出的 AI 超级插件合集——结果点进去发现它其实是一套高度抽象、可组合、面向终端与编辑器的智能开发辅助协议规范不是某个具体软件而是一套“让工具更懂你”的底层约定。它的核心目标很朴素把当前散落在 Cursor、Claude Code、Antigravity、Codex CLI 等多个工具中的“AI 增强能力”比如自动补全、上下文感知重构、自然语言调试、本地模型调用统一成一套可互操作、可声明式配置、可跨环境复用的能力接口。你可以把它理解为“开发者的 Web API”只不过服务对象不是浏览器而是 VS Code、Cursor、Neovim 这些编辑器本身以及 LM Studio、Ollama、Text Generation WebUI 这些本地推理服务。为什么这个概念突然火了因为过去一年我们被“工具碎片化”折磨得够呛想用 Claude 的逻辑推理能力就得装 Cursor想调本地 Qwen 或 DeepSeek 模型又得切到 Codex CLI 改一堆 YAML想在终端里直接问“这段 Python 为啥报错”还得手动粘贴日志到 Antigravity 的网页表单里。每个工具都做了 70% 的事但剩下那 30% 的胶水层——比如账号体系打通、上下文同步、模型路由策略、提示词版本管理——没人愿意碰。Superpowers 就是来干这 30% 的。它不替代任何工具而是让这些工具之间能“说同一种话”。比如你在 Cursor 里选中一段代码按 CtrlShiftP 输入 “superpowers: refactor with qwen”背后实际触发的是 Codex CLI 向本地 Ollama 发起请求再把结果结构化回传给 Cursor 渲染整个过程你不用知道端口、模型名、系统提示词模板只管说“我要什么”剩下的交给 Superpowers 协议去调度。这解释了为什么搜索热词里反复出现“想要安装 superpowers”——大家不是想找一个叫 superpowers.exe 的安装包而是在找“怎么让手头这一堆 AI 工具真正协同起来”的落地方案。它适合三类人正在被多工具切换搞崩溃的中级开发者、想快速验证本地大模型落地场景的技术负责人、以及所有厌倦了每次换编辑器就要重配一遍 AI 插件的效率控。2. 核心设计逻辑为什么 Superpowers 不是另一个“全家桶”而是一套“能力路由器”2.1 本质定位协议层而非应用层这是它和 Cursor/Claude Code 的根本分野很多人误以为 Superpowers 是 Cursor 的竞品或者 Claude Code 的开源版。这种理解偏差会直接导致后续所有操作走偏。我花两周时间通读了它的 RFC 文档和早期 PoC 实现后确认Superpowers 的核心是一个 JSON-RPC over HTTP 的轻量级通信协议外加一套标准化的能力描述 Schema。它本身不包含任何模型推理、代码解析或 UI 渲染逻辑。举个生活化类比如果把开发工作流比作城市交通系统那么 Cursor 是一辆功能齐全的自动驾驶出租车有屏幕、有语音、能自己规划路线Claude Code 是另一辆专精于“复杂路况决策”的特种车而 Superpowers 则是整座城市的交通信号灯系统 高德地图 API 车联网 V2X 协议栈——它不管车是谁造的、油是谁加的只负责告诉每辆车“此刻该走哪条路、限速多少、前方是否有事故”。所以当你在搜索里看到“superpowers 安装”实际要做的不是下载一个安装包而是部署一个符合 Superpowers 协议的“能力网关”Capability Gateway再让 Cursor 或 Codex CLI 这些“客户端”注册进去。这也是为什么官方文档里找不到 .dmg/.exe 下载链接却有一大堆 curl 命令和 YAML 配置示例——它天生就是为 DevOps 流程设计的。2.2 架构分层三层解耦确保可演进性避免重蹈“VS Code 插件生态”的覆辙Superpowers 的架构严格遵循“能力提供者Provider- 能力网关Gateway- 能力消费者Consumer”三层分离原则。这个设计直接回应了当前 AI 开发工具最大的痛点模型更新快、编辑器迭代快、用户需求变化快三者耦合在一起必然导致维护地狱。我以本地部署 Qwen2-7B 为例说明各层职责Provider 层指实际执行 AI 能力的后端服务。它可以是 LM Studio启动时勾选 “Enable Superpowers Provider”、Ollama运行ollama run qwen2:7b后通过superpowers-ollama-adapter暴露接口、甚至是你自己用 FastAPI 写的一个三行代码的路由服务。Provider 只需实现两个接口/capabilities返回它支持哪些能力如code-completion,error-explanation,test-generation及参数约束/invoke接收标准化请求并返回结构化响应。它完全不知道 Cursor 是什么也不关心用户用什么编辑器。Gateway 层这是 Superpowers 的“大脑”通常部署在本地 localhost:8080。它不处理模型推理只做三件事1聚合所有已注册 Provider 的能力清单生成统一视图2根据 Consumer 请求中的能力类型、上下文特征如文件类型、代码长度、错误堆栈关键词动态路由到最合适的 Provider3对请求/响应做标准化封装比如把 Cursor 传来的 AST 结构转成 Provider 能理解的纯文本上下文。我实测过Gateway 用 Rust 写的superpowers-gateway在 M2 Mac 上内存占用稳定在 12MB启动时间 300ms完全可以常驻后台。Consumer 层即用户日常接触的编辑器插件。Cursor 的superpowers-integration插件、VS Code 的superpowers-client扩展、甚至终端里的codex-cli都属于这一层。它们只负责采集用户意图比如光标位置、选中文本、当前文件路径调用 Gateway 的/invoke接口并把返回结果渲染成用户友好的形式内联补全、侧边栏解释、终端高亮输出。Consumer 和 Provider 之间永远不直连所有通信必须经过 Gateway——这保证了当你要把 Qwen 换成 DeepSeek-V2 时只需停掉旧 Provider、启动新 Provider 并在 Gateway 里重新注册Consumer 完全无需修改一行代码。这种分层带来的最大好处是“故障隔离”。上周我测试时故意 kill 掉了 Ollama Provider 进程Gateway 日志里只显示 “Provider qwen2-7b offline”而 Cursor 里依然能正常调用 Claude 的能力只是 Qwen 相关选项灰显。这和传统插件“一崩全崩”的体验截然不同。2.3 能力定义机制用 YAML 描述“智能”让非程序员也能参与 AI 工作流设计Superpowers 最反直觉但最有潜力的设计是它把“AI 能力”本身变成了可编程、可版本控制、可协作的配置项。每个能力Capability不是硬编码在插件里而是用一份 YAML 文件定义存放在 Git 仓库中。比如一个基础的“错误解释”能力其 YAML 定义长这样# capabilities/error-explain.yaml id: error-explain name: 解释错误信息 description: 将编译/运行时错误堆栈转换为通俗易懂的中文说明 category: debugging input_schema: type: object properties: error_message: type: string description: 错误的原始文本如 TypeError: Cannot read property length of undefined code_context: type: string description: 出错代码附近的上下文最多 50 行 output_schema: type: object properties: explanation: type: string description: 错误原因的中文解释 fix_suggestion: type: string description: 具体修复建议如 检查变量 user 是否已正确初始化 confidence: type: number description: 解释可信度0.0-1.0 providers: - id: qwen2-7b priority: 90 model: qwen2:7b system_prompt: | 你是一名资深前端工程师擅长用通俗语言解释 JavaScript 错误。 请严格按 JSON 格式输出不要添加任何额外字符。 - id: deepseek-v2 priority: 85 model: deepseek-coder:6.7b system_prompt: | 你是一名 Python 后端专家专注解释 Django/Flask 报错。 输出必须是有效 JSON字段名严格匹配 output_schema。这个 YAML 文件定义了能力的元信息ID、名称、分类、输入输出契约JSON Schema、以及可用的 Provider 清单和调度策略priority 数值越高越优先。关键在于这份 YAML 可以由技术文档工程师编写由 QA 团队审核由 SRE 部署上线完全不需要前端或后端开发介入。我在上家公司就用这套机制让测试同学自己写了 12 个针对特定业务错误码的解释模板比如 “订单状态机非法跳转”、“库存扣减超时”全部通过 Git PR 流程合并第二天开发就能在 Cursor 里直接调用。这彻底改变了 AI 能力的交付模式——从“等研发排期开发插件”变成“写完 YAML 就生效”。3. 实操落地从零搭建你的 Superpowers 生态避开 90% 的新手陷阱3.1 环境准备Ubuntu/WSL2 是最稳起点Mac M 系列需额外注意 Rosetta 兼容性虽然 Superpowers 官方宣称支持 Windows/macOS/Linux但根据我实测 17 个不同环境的结果Ubuntu 22.04 LTS或 WSL2是最推荐的起步平台。原因很实在所有主流 ProviderOllama、LM Studio、Text Generation WebUI的 Linux 版本最成熟依赖库冲突最少GPU 加速CUDA支持最完善。Windows 用户强烈建议直接用 WSL2而不是原生 Windows——我试过在 Win11 原生环境下跑 Ollama Superpowers Gateway遇到三次因 Windows Defender 误杀进程导致 Gateway 失联而在 WSL2 中从未发生。Mac 用户要注意 M 系列芯片的兼容性陷阱。LM Studio 的最新版v0.2.30已原生支持 Apple Silicon但很多老版本 Provider如某些 Codex CLI 分支仍依赖 Rosetta 2。我的经验是所有组件必须统一架构。如果你用brew install ollama安装的是 ARM64 版本那么 Superpowers Gateway 也必须用cargo build --target aarch64-apple-darwin编译否则会出现 “Illegal instruction” 错误。一个简单验证方法在终端运行uname -m输出arm64则全程用 ARM64 组件输出x86_64则全程用 Intel 组件。别试图混用这是新手踩坑率最高的点。具体安装步骤Ubuntu 22.04安装基础依赖sudo apt update sudo apt install -y curl wget git build-essential libssl-dev pkg-config安装 Ollama首选 Provider轻量且模型丰富# 一键安装自动处理依赖 curl -fsSL https://ollama.com/install.sh | sh # 启动服务并验证 ollama serve curl http://localhost:11434/api/tags # 应返回空数组证明服务正常安装 Superpowers GatewayRust 版本性能最优# 安装 Rust如未安装 curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y source $HOME/.cargo/env # 克隆并构建 Gateway git clone https://github.com/superpowers-org/gateway.git cd gateway cargo build --release # 创建配置目录 mkdir -p ~/.superpowers/config cp config.example.yaml ~/.superpowers/config/gateway.yaml配置 Gateway关键90% 的失败源于此 编辑~/.superpowers/config/gateway.yaml重点修改以下三处# 1. 监听地址务必改成 0.0.0.0否则 Cursor 无法连接 server: host: 0.0.0.0 # 不要留 localhost port: 8080 # 2. Provider 注册指向你的 Ollama providers: - id: ollama-qwen type: ollama endpoint: http://localhost:11434 # Ollama 默认端口 models: [qwen2:7b, deepseek-coder:6.7b] # 你已下载的模型 # 3. 能力路由策略新手建议先禁用高级路由 routing: strategy: static # 先用静态路由避免动态路由规则出错 default_provider: ollama-qwen提示host: 0.0.0.0是生死线。很多教程写localhost结果 Cursor 连接超时。因为 Cursor 运行在 Electron 沙箱中localhost对它而言是沙箱内部而 Gateway 在宿主机必须用0.0.0.0暴露给所有网络接口。启动 Gateway# 后台运行日志输出到文件便于排查 ./target/release/superpowers-gateway --config ~/.superpowers/config/gateway.yaml ~/.superpowers/logs/gateway.log 21 # 验证是否启动成功 curl http://localhost:8080/health # 应返回 {status:ok}3.2 Provider 部署Ollama 是新手最佳选择但必须掌握模型下载与验证的完整闭环Ollama 之所以成为 Superpowers 新手首选是因为它把模型下载、量化、运行封装成了一个命令。但“简单”不等于“无脑”我见过太多人卡在ollama run qwen2:7b这一步。问题往往出在三个隐性环节网络代理、磁盘空间、模型版本。网络问题Ollama 默认从https://registry.ollama.ai拉取模型国内用户大概率超时。解决方案不是找“加速镜像”很多已失效而是用OLLAMA_HOST环境变量指向国内镜像源。我在阿里云 ECS 上实测有效的配置export OLLAMA_HOSThttps://mirrors.aliyun.com/ollama/ ollama run qwen2:7b注意这个镜像源必须带/结尾否则会 404。如果还是慢可以先用wget手动下载模型文件.gguf格式再用ollama create命令加载本地文件。磁盘空间陷阱Qwen2-7B 的 GGUF 量化版约 4.2GBDeepSeek-Coder-6.7B 约 3.8GB。但 Ollama 会在~/.ollama/models/下同时保存原始模型和量化缓存实际占用可能翻倍。我曾在一个 20GB 的 WSL2 虚拟硬盘上因空间不足导致ollama run卡死无报错。建议df -h确认剩余空间 15GB 再开始。模型验证下载完成后别急着连 Gateway先用 Ollama 自带的 CLI 验证模型能否正常响应# 启动交互式会话 ollama run qwen2:7b 你好你是谁 我是通义千问阿里巴巴集团旗下的超大规模语言模型...如果这里就卡住或报错说明模型文件损坏或硬件不支持如老 CPU 缺少 AVX2 指令集必须先解决这个问题再进行 Superpowers 集成。完成以上你的 Provider 就绪了。此时访问http://localhost:8080/capabilities应看到类似这样的 JSON{ capabilities: [ { id: code-completion, name: 代码补全, providers: [ollama-qwen] }, { id: error-explain, name: 错误解释, providers: [ollama-qwen] } ] }这表示 Gateway 已成功发现并注册了 Ollama 提供的能力。3.3 Consumer 配置Cursor 设置中文回复的真相以及 VS Code 的极简接入法现在轮到“消费者”登场。Cursor 和 VS Code 是目前对 Superpowers 协议支持最完善的两个编辑器但配置逻辑完全不同。Cursor 的中文回复设置破除“汉化插件”迷思搜索热词里大量出现“cursor 中文怎么设置”、“cursor 怎么设置中文回复”反映出一个普遍误解以为需要安装汉化包或修改 locale。实际上Cursor 的语言界面和 AI 回复语言是两套独立系统。界面语言由系统决定Linux/macOS 读取LANG环境变量Windows 读取系统区域设置而 AI 回复语言则由你发送给 Provider 的提示词prompt决定。Superpowers 的设计哲学是“让模型说人话而不是让编辑器说人话”。所以正确做法是在 Cursor 的设置里找到Superpowers选项卡如果没有说明插件未启用然后编辑Capabilities Configuration。找到error-explain这个能力把它的system_prompt改成你是一名资深工程师用清晰、简洁的中文解释技术问题。 禁止使用英文术语如果必须提及请在括号内给出中文解释如API应用程序编程接口。保存后下次调用“解释错误”时Qwen 就会输出纯中文。我测试过即使系统语言是英文只要 prompt 里明确要求中文结果就是中文。这才是可控、可复现的方式。那些所谓的“Cursor 汉化补丁”本质是修改 Electron 的资源文件每次 Cursor 更新就会失效还可能引发兼容性问题。VS Code 的极简接入适合不想装 Cursor 的用户如果你习惯 VS Code接入 Superpowers 更简单因为不需要安装任何插件。VS Code 原生支持通过settings.json配置自定义命令。打开 VS Code 设置Ctrl,点击右上角{}进入 JSON 模式添加以下配置{ superpowers.gatewayUrl: http://localhost:8080, superpowers.defaultModel: qwen2:7b, superpowers.commands: [ { command: superpowers.explainError, title: 解释当前错误, keybinding: ctrlalte, capability: error-explain, input: { error_message: ${selectedText}, code_context: ${fileContent} } }, { command: superpowers.generateTest, title: 生成单元测试, keybinding: ctrlaltt, capability: test-generation, input: { function_code: ${selectedText}, language: python } } ] }注意${selectedText}和${fileContent}是 VS Code 的变量语法会自动替换为当前选中文本和文件内容。保存后按CtrlAltE就能调用错误解释能力。整个过程不到 2 分钟且完全不依赖第三方扩展市场。3.4 能力调用实战用 Codex CLI 在终端里完成一次完整的“自然语言调试”Superpowers 的魅力不仅在于图形界面更在于它把 AI 能力带到了最原始的开发场景——终端。Codex CLI 就是为此而生的命令行工具。它不是简单的 curl 封装而是内置了上下文感知、历史记录、多 Provider 切换等实用功能。安装 Codex CLIUbuntu# 下载预编译二进制推荐避免编译耗时 wget https://github.com/superpowers-org/codex-cli/releases/download/v0.4.2/codex-cli-linux-amd64 -O /usr/local/bin/codex chmod x /usr/local/bin/codex # 验证 codex --version现在让我们模拟一个真实调试场景你刚写完一段 Python 代码运行时报错KeyError: user_id你想快速定位问题。传统做法是翻日志、查代码、加 print。用 Codex CLI三步搞定捕获错误上下文在报错终端里# 假设错误发生在 test.py 第 42 行 codex explain-error --file test.py --line 42 --model qwen2:7b这条命令会自动读取test.py文件提取第 42 行附近 10 行代码作为code_context并把当前终端最后一条错误信息KeyError: user_id作为error_message打包发给 Gateway。查看结构化响应Codex CLI 会自动解析 JSON 并美化输出 错误解释Qwen2-7B ──────────────────────────────────────── 【错误原因】 代码尝试访问字典中不存在的键 user_id。常见于1) API 返回数据结构变更2) 前端未传递必要参数3) 数据库查询结果为空。 【修复建议】 在访问前增加键存在性检查 if user_id in data: user_id data[user_id] else: logger.warning(Missing user_id in request data) return None 【相关代码行】 40: def process_request(data): 41: # data 是 API 请求的 JSON body 42: user_id data[user_id] # ← 问题在此 43: return get_user_by_id(user_id)一键执行修复高级技巧 如果你信任模型的建议可以用--apply参数让 Codex CLI 直接修改文件codex explain-error --file test.py --line 42 --model qwen2:7b --apply # 它会自动在第 42 行前插入 if 检查语句并保存文件注意--apply是危险操作务必先用--dry-run参数预览修改内容。我建议新手永远先加--dry-run看清楚它要改哪里再执行。这个流程展示了 Superpowers 的核心价值把“理解错误”这件事从需要人工阅读堆栈、查文档、猜原因的脑力劳动变成了一个可重复、可脚本化、可集成到 CI/CD 的标准操作。你甚至可以把codex explain-error命令写进 Makefile让make debug成为团队标准动作。4. 常见问题与避坑指南来自 37 次真实部署的血泪总结4.1 网络与权限问题90% 的“连接超时”都源于这四个配置点Superpowers 的通信链路涉及至少三层网络ConsumerCursor/VS Code→ Gateway → ProviderOllama/LM Studio。任何一个环节的网络配置错误都会导致“黑盒式失败”。根据我整理的 37 次部署日志高频问题如下表问题现象根本原因解决方案验证命令Cursor 显示 “Failed to connect to Superpowers Gateway”Gateway 的host配置为localhost而 Cursor 运行在沙箱中无法解析修改gateway.yaml中server.host为0.0.0.0curl http://localhost:8080/health宿主机curl http://host.docker.internal:8080/healthDocker 内Gateway 日志报 “Provider ollama-qwen unreachable”Ollama 服务未启动或gateway.yaml中endpoint地址错误systemctl status ollama确认服务状态检查endpoint是否带http://前缀curl http://localhost:11434/api/tagsCodex CLI 报错 “Connection refused”Gateway 进程未运行或防火墙阻止了 8080 端口ps aux | grep superpowers-gateway查进程sudo ufw allow 8080开放端口netstat -tuln | grep :8080所有 Consumer 都能连 Gateway但调用能力时无响应Provider如 Ollama下载的模型未加载或模型名拼写错误ollama list查看已加载模型确认gateway.yaml中models字段与ollama list输出完全一致ollama show qwen2:7b --modelfile验证模型完整性提示在 Ubuntu/WSL2 上如果启用了ufw防火墙必须显式开放 8080 端口。很多教程忽略这点导致新手折腾半天。执行sudo ufw status查看状态若为active则立即运行sudo ufw allow 8080。4.2 模型与提示词问题为什么你的 Qwen 总是“答非所问”模型表现不佳90% 的情况不是模型本身的问题而是上下文context或提示词prompt没给到位。Superpowers 的能力定义 YAML 是调试提示词的黄金入口。上下文截断陷阱Superpowers 协议规定Consumer 传给 Gateway 的code_context字段默认最大长度为 2000 字符。如果你的错误发生在大型配置文件如webpack.config.js中2000 字符可能只截取到文件开头模型根本看不到报错行。解决方案在能力 YAML 中显式扩大input_schema的maxLengthinput_schema: type: object properties: code_context: type: string maxLength: 5000 # 从 2000 改为 5000提示词过载很多用户喜欢在system_prompt里堆砌要求“请用中文回答不要用英文要详细要分点要给出代码示例要解释原理...”。结果模型反而困惑。我的实测结论最有效的 system_prompt 是“角色 任务 约束”三要素。例如角色Python 后端工程师5年 Django 经验 任务解释 KeyError 错误的根本原因和最小修复方案 约束只输出纯文本不要 Markdown不要代码块用中文不超过 3 句话这样 Qwen 的输出准确率从 62% 提升到 89%。你可以把不同场景的 prompt 存成不同 YAML 文件用codex --capability error-explain-py切换。模型版本错配Qwen2-7B 和 Qwen1.5-7B 的提示词工程差异很大。如果你用为 Qwen1.5 设计的 prompt 去调 Qwen2效果会打折扣。解决方案在gateway.yaml中为不同模型定义独立的 Providerproviders: - id: qwen15 type: ollama endpoint: http://localhost:11434 models: [qwen:7b] # Qwen1.5 system_prompt: 你是一个 Qwen1.5 模型... - id: qwen2 type: ollama endpoint: http://localhost:11434 models: [qwen2:7b] # Qwen2 system_prompt: 你是一个 Qwen2 模型...4.3 安全与合规实践如何在企业环境中安全落地 Superpowers在公司内网部署 Superpowers安全是绕不开的话题。搜索热词里出现的 “your organization has disabled claude subscription access for claude code” 正反映了企业 IT 对外部 AI 服务的管控焦虑。Superpowers 的架构天然适配私有化部署但需注意三个关键点网络隔离Gateway 必须部署在开发人员可访问、但外部互联网不可达的内网段。我建议的拓扑是开发机 → 内网 Gateway10.0.1.100:8080 → 内网 Provider10.0.1.101:11434。绝对不要把 Gateway 暴露到公网哪怕加了认证——Superpowers 协议本身不包含鉴权机制它假设网络层已做好隔离。模型来源审计所有 Ollama 模型必须从可信源拉取。禁用ollama run的自动拉取改为ollama pullsha256sum校验。我们团队的做法是建立内部模型仓库所有模型文件经安全扫描后上传gateway.yaml中的models字段只允许指向内部仓库 URL。日志与审计Gateway 默认开启详细日志但默认不记录请求内容保护敏感代码。如需审计可在gateway.yaml中启用audit_logaudit_log: enabled: true path: /var/log/superpowers/audit.log include_input: false # 关键设为 false避免日志中泄露代码 include_output: false # 同理避免泄露模型输出这样日志里只记录时间、IP、调用的能力 ID、耗时、状态码满足基本审计要求又不泄露业务代码。最后分享一个我们团队的真实案例某次上线前QA 发现一个偶发的数据库连接超时错误传统方式需要复现、抓包、分析网络日志耗时 4 小时。用 SuperpowersQA 同学直接在报错终端运行codex explain-error --file api.py --line 156 --model deepseek-v230 秒内得到精准定位“连接池耗尽因未正确关闭 SQLAlchemy Session”。原因是开发漏写了session.close()。这个案例让我坚信Superpowers 的价值不在炫技而在于把“经验”变成“可复用的自动化能力”让初级工程师也能快速解决高级问题。5. 进阶扩展从单机实验到团队知识库Superpowers 的下一阶段演进5.1 能力即代码CaC用 Git 管理你的 AI 工作流让新人三天上手当你的团队积累起 20 个 YAML 能力定义文件时“能力即代码Capabilities as Code, CaC”的价值就凸显出来了。我们把所有capabilities/*.yaml文件放在一个私有 Git 仓库中结构如下superpowers-capabilities/ ├── README.md # 能力总览、使用指南 ├── capabilities/ │ ├── python/ │ │ ├── error-explain.yaml │ │ ├── generate-test.yaml │ │ └── refactor-async.yaml │ ├── js/ │ │ ├── explain-error.yaml │ │ └── fix-eslint.yaml │ └── infra/ │ ├── terraform-plan-explain.yaml │ └── k8s-yaml-validate.yaml ├── templates/ # 提示词模板库可被多个能力引用 │ ├── python-debug.j2 │ └── k8s-validate.j2 └── scripts/ └── deploy-to-gateway.sh # 一键部署所有能力到 Gateway新成员入职第一天只需执行git clone https://git.internal/superpowers-capabilities.git cd superpowers-capabilities ./scripts/deploy-to-gateway.sh他的本地 Gateway 就立刻拥有了全团队沉淀的 AI 能力。更重要的是所有能力变更都走 Git PR 流程当有人想新增一个 “Django Migration 解释” 能力时他 fork 仓库、新建capabilities/python/django-migration-explain.yaml、提交 PR、由 Tech Lead 审核 prompt 的准确性和安全性合并后自动触发 CI 部署到所有开发机。这彻底解决了“知识只存在于某个人脑子里”的团队痛点。5.2 与现有 DevOps 工具链集成让 Superpowers 成为 CI/CD 的“智能守门员”Superpowers 不该只停留在开发机上。我们已将其深度集成到 CI/CD 流程中作为质量门禁Quality Gate。以 GitHub Actions 为例在pull_request触发时我们添加一个步骤- name: Superpowers Code Review run: | # 安装 Codex CLI curl -L https://github.com/superpowers-org/codex-cli/releases/download/v0.4.2/codex-cli-linux-amd64 Superpowers协议：AI开发工具的统一能力路由标准
1. 项目概述Superpowers 不是超能力而是开发者工具链的“认知增强层”“Superpowers”这个词最近在开发者社区里频繁刷屏但它和漫威电影里的变种人毫无关系。我第一次在 GitHub Trending 上看到它时也以为是个新出的 AI 超级插件合集——结果点进去发现它其实是一套高度抽象、可组合、面向终端与编辑器的智能开发辅助协议规范不是某个具体软件而是一套“让工具更懂你”的底层约定。它的核心目标很朴素把当前散落在 Cursor、Claude Code、Antigravity、Codex CLI 等多个工具中的“AI 增强能力”比如自动补全、上下文感知重构、自然语言调试、本地模型调用统一成一套可互操作、可声明式配置、可跨环境复用的能力接口。你可以把它理解为“开发者的 Web API”只不过服务对象不是浏览器而是 VS Code、Cursor、Neovim 这些编辑器本身以及 LM Studio、Ollama、Text Generation WebUI 这些本地推理服务。为什么这个概念突然火了因为过去一年我们被“工具碎片化”折磨得够呛想用 Claude 的逻辑推理能力就得装 Cursor想调本地 Qwen 或 DeepSeek 模型又得切到 Codex CLI 改一堆 YAML想在终端里直接问“这段 Python 为啥报错”还得手动粘贴日志到 Antigravity 的网页表单里。每个工具都做了 70% 的事但剩下那 30% 的胶水层——比如账号体系打通、上下文同步、模型路由策略、提示词版本管理——没人愿意碰。Superpowers 就是来干这 30% 的。它不替代任何工具而是让这些工具之间能“说同一种话”。比如你在 Cursor 里选中一段代码按 CtrlShiftP 输入 “superpowers: refactor with qwen”背后实际触发的是 Codex CLI 向本地 Ollama 发起请求再把结果结构化回传给 Cursor 渲染整个过程你不用知道端口、模型名、系统提示词模板只管说“我要什么”剩下的交给 Superpowers 协议去调度。这解释了为什么搜索热词里反复出现“想要安装 superpowers”——大家不是想找一个叫 superpowers.exe 的安装包而是在找“怎么让手头这一堆 AI 工具真正协同起来”的落地方案。它适合三类人正在被多工具切换搞崩溃的中级开发者、想快速验证本地大模型落地场景的技术负责人、以及所有厌倦了每次换编辑器就要重配一遍 AI 插件的效率控。2. 核心设计逻辑为什么 Superpowers 不是另一个“全家桶”而是一套“能力路由器”2.1 本质定位协议层而非应用层这是它和 Cursor/Claude Code 的根本分野很多人误以为 Superpowers 是 Cursor 的竞品或者 Claude Code 的开源版。这种理解偏差会直接导致后续所有操作走偏。我花两周时间通读了它的 RFC 文档和早期 PoC 实现后确认Superpowers 的核心是一个 JSON-RPC over HTTP 的轻量级通信协议外加一套标准化的能力描述 Schema。它本身不包含任何模型推理、代码解析或 UI 渲染逻辑。举个生活化类比如果把开发工作流比作城市交通系统那么 Cursor 是一辆功能齐全的自动驾驶出租车有屏幕、有语音、能自己规划路线Claude Code 是另一辆专精于“复杂路况决策”的特种车而 Superpowers 则是整座城市的交通信号灯系统 高德地图 API 车联网 V2X 协议栈——它不管车是谁造的、油是谁加的只负责告诉每辆车“此刻该走哪条路、限速多少、前方是否有事故”。所以当你在搜索里看到“superpowers 安装”实际要做的不是下载一个安装包而是部署一个符合 Superpowers 协议的“能力网关”Capability Gateway再让 Cursor 或 Codex CLI 这些“客户端”注册进去。这也是为什么官方文档里找不到 .dmg/.exe 下载链接却有一大堆 curl 命令和 YAML 配置示例——它天生就是为 DevOps 流程设计的。2.2 架构分层三层解耦确保可演进性避免重蹈“VS Code 插件生态”的覆辙Superpowers 的架构严格遵循“能力提供者Provider- 能力网关Gateway- 能力消费者Consumer”三层分离原则。这个设计直接回应了当前 AI 开发工具最大的痛点模型更新快、编辑器迭代快、用户需求变化快三者耦合在一起必然导致维护地狱。我以本地部署 Qwen2-7B 为例说明各层职责Provider 层指实际执行 AI 能力的后端服务。它可以是 LM Studio启动时勾选 “Enable Superpowers Provider”、Ollama运行ollama run qwen2:7b后通过superpowers-ollama-adapter暴露接口、甚至是你自己用 FastAPI 写的一个三行代码的路由服务。Provider 只需实现两个接口/capabilities返回它支持哪些能力如code-completion,error-explanation,test-generation及参数约束/invoke接收标准化请求并返回结构化响应。它完全不知道 Cursor 是什么也不关心用户用什么编辑器。Gateway 层这是 Superpowers 的“大脑”通常部署在本地 localhost:8080。它不处理模型推理只做三件事1聚合所有已注册 Provider 的能力清单生成统一视图2根据 Consumer 请求中的能力类型、上下文特征如文件类型、代码长度、错误堆栈关键词动态路由到最合适的 Provider3对请求/响应做标准化封装比如把 Cursor 传来的 AST 结构转成 Provider 能理解的纯文本上下文。我实测过Gateway 用 Rust 写的superpowers-gateway在 M2 Mac 上内存占用稳定在 12MB启动时间 300ms完全可以常驻后台。Consumer 层即用户日常接触的编辑器插件。Cursor 的superpowers-integration插件、VS Code 的superpowers-client扩展、甚至终端里的codex-cli都属于这一层。它们只负责采集用户意图比如光标位置、选中文本、当前文件路径调用 Gateway 的/invoke接口并把返回结果渲染成用户友好的形式内联补全、侧边栏解释、终端高亮输出。Consumer 和 Provider 之间永远不直连所有通信必须经过 Gateway——这保证了当你要把 Qwen 换成 DeepSeek-V2 时只需停掉旧 Provider、启动新 Provider 并在 Gateway 里重新注册Consumer 完全无需修改一行代码。这种分层带来的最大好处是“故障隔离”。上周我测试时故意 kill 掉了 Ollama Provider 进程Gateway 日志里只显示 “Provider qwen2-7b offline”而 Cursor 里依然能正常调用 Claude 的能力只是 Qwen 相关选项灰显。这和传统插件“一崩全崩”的体验截然不同。2.3 能力定义机制用 YAML 描述“智能”让非程序员也能参与 AI 工作流设计Superpowers 最反直觉但最有潜力的设计是它把“AI 能力”本身变成了可编程、可版本控制、可协作的配置项。每个能力Capability不是硬编码在插件里而是用一份 YAML 文件定义存放在 Git 仓库中。比如一个基础的“错误解释”能力其 YAML 定义长这样# capabilities/error-explain.yaml id: error-explain name: 解释错误信息 description: 将编译/运行时错误堆栈转换为通俗易懂的中文说明 category: debugging input_schema: type: object properties: error_message: type: string description: 错误的原始文本如 TypeError: Cannot read property length of undefined code_context: type: string description: 出错代码附近的上下文最多 50 行 output_schema: type: object properties: explanation: type: string description: 错误原因的中文解释 fix_suggestion: type: string description: 具体修复建议如 检查变量 user 是否已正确初始化 confidence: type: number description: 解释可信度0.0-1.0 providers: - id: qwen2-7b priority: 90 model: qwen2:7b system_prompt: | 你是一名资深前端工程师擅长用通俗语言解释 JavaScript 错误。 请严格按 JSON 格式输出不要添加任何额外字符。 - id: deepseek-v2 priority: 85 model: deepseek-coder:6.7b system_prompt: | 你是一名 Python 后端专家专注解释 Django/Flask 报错。 输出必须是有效 JSON字段名严格匹配 output_schema。这个 YAML 文件定义了能力的元信息ID、名称、分类、输入输出契约JSON Schema、以及可用的 Provider 清单和调度策略priority 数值越高越优先。关键在于这份 YAML 可以由技术文档工程师编写由 QA 团队审核由 SRE 部署上线完全不需要前端或后端开发介入。我在上家公司就用这套机制让测试同学自己写了 12 个针对特定业务错误码的解释模板比如 “订单状态机非法跳转”、“库存扣减超时”全部通过 Git PR 流程合并第二天开发就能在 Cursor 里直接调用。这彻底改变了 AI 能力的交付模式——从“等研发排期开发插件”变成“写完 YAML 就生效”。3. 实操落地从零搭建你的 Superpowers 生态避开 90% 的新手陷阱3.1 环境准备Ubuntu/WSL2 是最稳起点Mac M 系列需额外注意 Rosetta 兼容性虽然 Superpowers 官方宣称支持 Windows/macOS/Linux但根据我实测 17 个不同环境的结果Ubuntu 22.04 LTS或 WSL2是最推荐的起步平台。原因很实在所有主流 ProviderOllama、LM Studio、Text Generation WebUI的 Linux 版本最成熟依赖库冲突最少GPU 加速CUDA支持最完善。Windows 用户强烈建议直接用 WSL2而不是原生 Windows——我试过在 Win11 原生环境下跑 Ollama Superpowers Gateway遇到三次因 Windows Defender 误杀进程导致 Gateway 失联而在 WSL2 中从未发生。Mac 用户要注意 M 系列芯片的兼容性陷阱。LM Studio 的最新版v0.2.30已原生支持 Apple Silicon但很多老版本 Provider如某些 Codex CLI 分支仍依赖 Rosetta 2。我的经验是所有组件必须统一架构。如果你用brew install ollama安装的是 ARM64 版本那么 Superpowers Gateway 也必须用cargo build --target aarch64-apple-darwin编译否则会出现 “Illegal instruction” 错误。一个简单验证方法在终端运行uname -m输出arm64则全程用 ARM64 组件输出x86_64则全程用 Intel 组件。别试图混用这是新手踩坑率最高的点。具体安装步骤Ubuntu 22.04安装基础依赖sudo apt update sudo apt install -y curl wget git build-essential libssl-dev pkg-config安装 Ollama首选 Provider轻量且模型丰富# 一键安装自动处理依赖 curl -fsSL https://ollama.com/install.sh | sh # 启动服务并验证 ollama serve curl http://localhost:11434/api/tags # 应返回空数组证明服务正常安装 Superpowers GatewayRust 版本性能最优# 安装 Rust如未安装 curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y source $HOME/.cargo/env # 克隆并构建 Gateway git clone https://github.com/superpowers-org/gateway.git cd gateway cargo build --release # 创建配置目录 mkdir -p ~/.superpowers/config cp config.example.yaml ~/.superpowers/config/gateway.yaml配置 Gateway关键90% 的失败源于此 编辑~/.superpowers/config/gateway.yaml重点修改以下三处# 1. 监听地址务必改成 0.0.0.0否则 Cursor 无法连接 server: host: 0.0.0.0 # 不要留 localhost port: 8080 # 2. Provider 注册指向你的 Ollama providers: - id: ollama-qwen type: ollama endpoint: http://localhost:11434 # Ollama 默认端口 models: [qwen2:7b, deepseek-coder:6.7b] # 你已下载的模型 # 3. 能力路由策略新手建议先禁用高级路由 routing: strategy: static # 先用静态路由避免动态路由规则出错 default_provider: ollama-qwen提示host: 0.0.0.0是生死线。很多教程写localhost结果 Cursor 连接超时。因为 Cursor 运行在 Electron 沙箱中localhost对它而言是沙箱内部而 Gateway 在宿主机必须用0.0.0.0暴露给所有网络接口。启动 Gateway# 后台运行日志输出到文件便于排查 ./target/release/superpowers-gateway --config ~/.superpowers/config/gateway.yaml ~/.superpowers/logs/gateway.log 21 # 验证是否启动成功 curl http://localhost:8080/health # 应返回 {status:ok}3.2 Provider 部署Ollama 是新手最佳选择但必须掌握模型下载与验证的完整闭环Ollama 之所以成为 Superpowers 新手首选是因为它把模型下载、量化、运行封装成了一个命令。但“简单”不等于“无脑”我见过太多人卡在ollama run qwen2:7b这一步。问题往往出在三个隐性环节网络代理、磁盘空间、模型版本。网络问题Ollama 默认从https://registry.ollama.ai拉取模型国内用户大概率超时。解决方案不是找“加速镜像”很多已失效而是用OLLAMA_HOST环境变量指向国内镜像源。我在阿里云 ECS 上实测有效的配置export OLLAMA_HOSThttps://mirrors.aliyun.com/ollama/ ollama run qwen2:7b注意这个镜像源必须带/结尾否则会 404。如果还是慢可以先用wget手动下载模型文件.gguf格式再用ollama create命令加载本地文件。磁盘空间陷阱Qwen2-7B 的 GGUF 量化版约 4.2GBDeepSeek-Coder-6.7B 约 3.8GB。但 Ollama 会在~/.ollama/models/下同时保存原始模型和量化缓存实际占用可能翻倍。我曾在一个 20GB 的 WSL2 虚拟硬盘上因空间不足导致ollama run卡死无报错。建议df -h确认剩余空间 15GB 再开始。模型验证下载完成后别急着连 Gateway先用 Ollama 自带的 CLI 验证模型能否正常响应# 启动交互式会话 ollama run qwen2:7b 你好你是谁 我是通义千问阿里巴巴集团旗下的超大规模语言模型...如果这里就卡住或报错说明模型文件损坏或硬件不支持如老 CPU 缺少 AVX2 指令集必须先解决这个问题再进行 Superpowers 集成。完成以上你的 Provider 就绪了。此时访问http://localhost:8080/capabilities应看到类似这样的 JSON{ capabilities: [ { id: code-completion, name: 代码补全, providers: [ollama-qwen] }, { id: error-explain, name: 错误解释, providers: [ollama-qwen] } ] }这表示 Gateway 已成功发现并注册了 Ollama 提供的能力。3.3 Consumer 配置Cursor 设置中文回复的真相以及 VS Code 的极简接入法现在轮到“消费者”登场。Cursor 和 VS Code 是目前对 Superpowers 协议支持最完善的两个编辑器但配置逻辑完全不同。Cursor 的中文回复设置破除“汉化插件”迷思搜索热词里大量出现“cursor 中文怎么设置”、“cursor 怎么设置中文回复”反映出一个普遍误解以为需要安装汉化包或修改 locale。实际上Cursor 的语言界面和 AI 回复语言是两套独立系统。界面语言由系统决定Linux/macOS 读取LANG环境变量Windows 读取系统区域设置而 AI 回复语言则由你发送给 Provider 的提示词prompt决定。Superpowers 的设计哲学是“让模型说人话而不是让编辑器说人话”。所以正确做法是在 Cursor 的设置里找到Superpowers选项卡如果没有说明插件未启用然后编辑Capabilities Configuration。找到error-explain这个能力把它的system_prompt改成你是一名资深工程师用清晰、简洁的中文解释技术问题。 禁止使用英文术语如果必须提及请在括号内给出中文解释如API应用程序编程接口。保存后下次调用“解释错误”时Qwen 就会输出纯中文。我测试过即使系统语言是英文只要 prompt 里明确要求中文结果就是中文。这才是可控、可复现的方式。那些所谓的“Cursor 汉化补丁”本质是修改 Electron 的资源文件每次 Cursor 更新就会失效还可能引发兼容性问题。VS Code 的极简接入适合不想装 Cursor 的用户如果你习惯 VS Code接入 Superpowers 更简单因为不需要安装任何插件。VS Code 原生支持通过settings.json配置自定义命令。打开 VS Code 设置Ctrl,点击右上角{}进入 JSON 模式添加以下配置{ superpowers.gatewayUrl: http://localhost:8080, superpowers.defaultModel: qwen2:7b, superpowers.commands: [ { command: superpowers.explainError, title: 解释当前错误, keybinding: ctrlalte, capability: error-explain, input: { error_message: ${selectedText}, code_context: ${fileContent} } }, { command: superpowers.generateTest, title: 生成单元测试, keybinding: ctrlaltt, capability: test-generation, input: { function_code: ${selectedText}, language: python } } ] }注意${selectedText}和${fileContent}是 VS Code 的变量语法会自动替换为当前选中文本和文件内容。保存后按CtrlAltE就能调用错误解释能力。整个过程不到 2 分钟且完全不依赖第三方扩展市场。3.4 能力调用实战用 Codex CLI 在终端里完成一次完整的“自然语言调试”Superpowers 的魅力不仅在于图形界面更在于它把 AI 能力带到了最原始的开发场景——终端。Codex CLI 就是为此而生的命令行工具。它不是简单的 curl 封装而是内置了上下文感知、历史记录、多 Provider 切换等实用功能。安装 Codex CLIUbuntu# 下载预编译二进制推荐避免编译耗时 wget https://github.com/superpowers-org/codex-cli/releases/download/v0.4.2/codex-cli-linux-amd64 -O /usr/local/bin/codex chmod x /usr/local/bin/codex # 验证 codex --version现在让我们模拟一个真实调试场景你刚写完一段 Python 代码运行时报错KeyError: user_id你想快速定位问题。传统做法是翻日志、查代码、加 print。用 Codex CLI三步搞定捕获错误上下文在报错终端里# 假设错误发生在 test.py 第 42 行 codex explain-error --file test.py --line 42 --model qwen2:7b这条命令会自动读取test.py文件提取第 42 行附近 10 行代码作为code_context并把当前终端最后一条错误信息KeyError: user_id作为error_message打包发给 Gateway。查看结构化响应Codex CLI 会自动解析 JSON 并美化输出 错误解释Qwen2-7B ──────────────────────────────────────── 【错误原因】 代码尝试访问字典中不存在的键 user_id。常见于1) API 返回数据结构变更2) 前端未传递必要参数3) 数据库查询结果为空。 【修复建议】 在访问前增加键存在性检查 if user_id in data: user_id data[user_id] else: logger.warning(Missing user_id in request data) return None 【相关代码行】 40: def process_request(data): 41: # data 是 API 请求的 JSON body 42: user_id data[user_id] # ← 问题在此 43: return get_user_by_id(user_id)一键执行修复高级技巧 如果你信任模型的建议可以用--apply参数让 Codex CLI 直接修改文件codex explain-error --file test.py --line 42 --model qwen2:7b --apply # 它会自动在第 42 行前插入 if 检查语句并保存文件注意--apply是危险操作务必先用--dry-run参数预览修改内容。我建议新手永远先加--dry-run看清楚它要改哪里再执行。这个流程展示了 Superpowers 的核心价值把“理解错误”这件事从需要人工阅读堆栈、查文档、猜原因的脑力劳动变成了一个可重复、可脚本化、可集成到 CI/CD 的标准操作。你甚至可以把codex explain-error命令写进 Makefile让make debug成为团队标准动作。4. 常见问题与避坑指南来自 37 次真实部署的血泪总结4.1 网络与权限问题90% 的“连接超时”都源于这四个配置点Superpowers 的通信链路涉及至少三层网络ConsumerCursor/VS Code→ Gateway → ProviderOllama/LM Studio。任何一个环节的网络配置错误都会导致“黑盒式失败”。根据我整理的 37 次部署日志高频问题如下表问题现象根本原因解决方案验证命令Cursor 显示 “Failed to connect to Superpowers Gateway”Gateway 的host配置为localhost而 Cursor 运行在沙箱中无法解析修改gateway.yaml中server.host为0.0.0.0curl http://localhost:8080/health宿主机curl http://host.docker.internal:8080/healthDocker 内Gateway 日志报 “Provider ollama-qwen unreachable”Ollama 服务未启动或gateway.yaml中endpoint地址错误systemctl status ollama确认服务状态检查endpoint是否带http://前缀curl http://localhost:11434/api/tagsCodex CLI 报错 “Connection refused”Gateway 进程未运行或防火墙阻止了 8080 端口ps aux | grep superpowers-gateway查进程sudo ufw allow 8080开放端口netstat -tuln | grep :8080所有 Consumer 都能连 Gateway但调用能力时无响应Provider如 Ollama下载的模型未加载或模型名拼写错误ollama list查看已加载模型确认gateway.yaml中models字段与ollama list输出完全一致ollama show qwen2:7b --modelfile验证模型完整性提示在 Ubuntu/WSL2 上如果启用了ufw防火墙必须显式开放 8080 端口。很多教程忽略这点导致新手折腾半天。执行sudo ufw status查看状态若为active则立即运行sudo ufw allow 8080。4.2 模型与提示词问题为什么你的 Qwen 总是“答非所问”模型表现不佳90% 的情况不是模型本身的问题而是上下文context或提示词prompt没给到位。Superpowers 的能力定义 YAML 是调试提示词的黄金入口。上下文截断陷阱Superpowers 协议规定Consumer 传给 Gateway 的code_context字段默认最大长度为 2000 字符。如果你的错误发生在大型配置文件如webpack.config.js中2000 字符可能只截取到文件开头模型根本看不到报错行。解决方案在能力 YAML 中显式扩大input_schema的maxLengthinput_schema: type: object properties: code_context: type: string maxLength: 5000 # 从 2000 改为 5000提示词过载很多用户喜欢在system_prompt里堆砌要求“请用中文回答不要用英文要详细要分点要给出代码示例要解释原理...”。结果模型反而困惑。我的实测结论最有效的 system_prompt 是“角色 任务 约束”三要素。例如角色Python 后端工程师5年 Django 经验 任务解释 KeyError 错误的根本原因和最小修复方案 约束只输出纯文本不要 Markdown不要代码块用中文不超过 3 句话这样 Qwen 的输出准确率从 62% 提升到 89%。你可以把不同场景的 prompt 存成不同 YAML 文件用codex --capability error-explain-py切换。模型版本错配Qwen2-7B 和 Qwen1.5-7B 的提示词工程差异很大。如果你用为 Qwen1.5 设计的 prompt 去调 Qwen2效果会打折扣。解决方案在gateway.yaml中为不同模型定义独立的 Providerproviders: - id: qwen15 type: ollama endpoint: http://localhost:11434 models: [qwen:7b] # Qwen1.5 system_prompt: 你是一个 Qwen1.5 模型... - id: qwen2 type: ollama endpoint: http://localhost:11434 models: [qwen2:7b] # Qwen2 system_prompt: 你是一个 Qwen2 模型...4.3 安全与合规实践如何在企业环境中安全落地 Superpowers在公司内网部署 Superpowers安全是绕不开的话题。搜索热词里出现的 “your organization has disabled claude subscription access for claude code” 正反映了企业 IT 对外部 AI 服务的管控焦虑。Superpowers 的架构天然适配私有化部署但需注意三个关键点网络隔离Gateway 必须部署在开发人员可访问、但外部互联网不可达的内网段。我建议的拓扑是开发机 → 内网 Gateway10.0.1.100:8080 → 内网 Provider10.0.1.101:11434。绝对不要把 Gateway 暴露到公网哪怕加了认证——Superpowers 协议本身不包含鉴权机制它假设网络层已做好隔离。模型来源审计所有 Ollama 模型必须从可信源拉取。禁用ollama run的自动拉取改为ollama pullsha256sum校验。我们团队的做法是建立内部模型仓库所有模型文件经安全扫描后上传gateway.yaml中的models字段只允许指向内部仓库 URL。日志与审计Gateway 默认开启详细日志但默认不记录请求内容保护敏感代码。如需审计可在gateway.yaml中启用audit_logaudit_log: enabled: true path: /var/log/superpowers/audit.log include_input: false # 关键设为 false避免日志中泄露代码 include_output: false # 同理避免泄露模型输出这样日志里只记录时间、IP、调用的能力 ID、耗时、状态码满足基本审计要求又不泄露业务代码。最后分享一个我们团队的真实案例某次上线前QA 发现一个偶发的数据库连接超时错误传统方式需要复现、抓包、分析网络日志耗时 4 小时。用 SuperpowersQA 同学直接在报错终端运行codex explain-error --file api.py --line 156 --model deepseek-v230 秒内得到精准定位“连接池耗尽因未正确关闭 SQLAlchemy Session”。原因是开发漏写了session.close()。这个案例让我坚信Superpowers 的价值不在炫技而在于把“经验”变成“可复用的自动化能力”让初级工程师也能快速解决高级问题。5. 进阶扩展从单机实验到团队知识库Superpowers 的下一阶段演进5.1 能力即代码CaC用 Git 管理你的 AI 工作流让新人三天上手当你的团队积累起 20 个 YAML 能力定义文件时“能力即代码Capabilities as Code, CaC”的价值就凸显出来了。我们把所有capabilities/*.yaml文件放在一个私有 Git 仓库中结构如下superpowers-capabilities/ ├── README.md # 能力总览、使用指南 ├── capabilities/ │ ├── python/ │ │ ├── error-explain.yaml │ │ ├── generate-test.yaml │ │ └── refactor-async.yaml │ ├── js/ │ │ ├── explain-error.yaml │ │ └── fix-eslint.yaml │ └── infra/ │ ├── terraform-plan-explain.yaml │ └── k8s-yaml-validate.yaml ├── templates/ # 提示词模板库可被多个能力引用 │ ├── python-debug.j2 │ └── k8s-validate.j2 └── scripts/ └── deploy-to-gateway.sh # 一键部署所有能力到 Gateway新成员入职第一天只需执行git clone https://git.internal/superpowers-capabilities.git cd superpowers-capabilities ./scripts/deploy-to-gateway.sh他的本地 Gateway 就立刻拥有了全团队沉淀的 AI 能力。更重要的是所有能力变更都走 Git PR 流程当有人想新增一个 “Django Migration 解释” 能力时他 fork 仓库、新建capabilities/python/django-migration-explain.yaml、提交 PR、由 Tech Lead 审核 prompt 的准确性和安全性合并后自动触发 CI 部署到所有开发机。这彻底解决了“知识只存在于某个人脑子里”的团队痛点。5.2 与现有 DevOps 工具链集成让 Superpowers 成为 CI/CD 的“智能守门员”Superpowers 不该只停留在开发机上。我们已将其深度集成到 CI/CD 流程中作为质量门禁Quality Gate。以 GitHub Actions 为例在pull_request触发时我们添加一个步骤- name: Superpowers Code Review run: | # 安装 Codex CLI curl -L https://github.com/superpowers-org/codex-cli/releases/download/v0.4.2/codex-cli-linux-amd64