Superpowers：面向IDE的AI技能中枢与本地模型调度框架

1. 项目概述：Superpowers 不是超能力，而是开发者工具链的“认知增强层”

“Superpowers”这个词最近在开发者社区里频繁刷屏，但别被字面意思带偏——它不是什么玄学插件，也不是科幻电影里的特效开关。我第一次在 GitHub Trending 上看到它时，也以为是某个新出的 AI 模型聚合器，点进去才发现，它本质上是一套面向现代 IDE（尤其是 Cursor 和 VS Code）的、可插拔的智能辅助能力框架。它的核心价值，不在于替代你写代码，而在于把原本需要你手动查文档、切窗口、拼命令、试参数的重复性认知劳动，压缩成一次自然语言指令或一个快捷键触发的动作。比如，你不用再打开终端敲git status && git diff --staged，只需对编辑器说一句“帮我看看这次修改了哪些文件，和上次提交比有什么不同”，它就能自动执行、解析、高亮并结构化呈现结果。

这个概念之所以火，是因为它精准踩中了当前开发者的三个真实痛点：第一，AI 工具越来越多，但彼此割裂——Claude Code 能写逻辑，Codex CLI 能跑脚本，Antigravity 能做代码审查，但它们像散落的乐高积木，缺一个统一的底座；第二，本地模型调用门槛高，LMStudio、Ollama、llama.cpp 各自为政，配置路径、上下文长度、系统提示词全得手写 JSON；第三，IDE 原生能力与 AI 辅助之间存在巨大鸿沟——Cursor 支持自然语言交互，但默认只调用自家 API；VS Code 插件生态丰富，却缺乏统一的技能注册与调度机制。Superpowers 就是为填平这三道沟壑而生的中间件。它不绑定任何一家大模型厂商，也不强制你换 IDE，而是以“技能（Skills）”为单位，把各种能力模块化封装，再通过标准化接口注入到编辑器中。你可以把它理解成 IDE 的“App Store”，只不过上架的不是应用，而是可组合、可复用、可调试的开发动作单元。

我过去两年做过十几个 AI 编程辅助工具的深度测评，从早期的 GitHub Copilot 到现在的 Cursor Pro，发现一个关键规律：真正提升效率的，从来不是“更聪明的模型”，而是“更顺手的交互”。Superpowers 的设计哲学正是如此——它把模型能力下沉为基础设施，把交互逻辑上浮为用户可感知、可定制、可审计的操作流。比如，它内置的/compact技能，不是简单地把代码变短，而是先分析函数职责边界，再判断哪些变量可以内联、哪些条件分支可以合并、哪些注释属于冗余信息，最后才生成精简版本。这个过程全程可追溯，每一步决策都有日志输出，不像某些黑盒插件，改完代码你都不知道它为什么这么改。所以，如果你正在被“AI 工具太多但不会用”、“想用本地模型但配不起来”、“Cursor 功能强大但中文支持总差一口气”这些问题困扰，Superpowers 就不是锦上添花，而是雪中送炭。它适合三类人：一是习惯用命令行和脚本驱动开发流程的资深工程师；二是正在从 VS Code 迁移到 Cursor、希望保留原有工作流的团队；三是对 AI 工具链有定制需求、不满足于开箱即用的极客型开发者。

2. 核心架构拆解：为什么 Superpowers 能成为“技能中枢”，而不是又一个插件

2.1 技能（Skill）不是功能，而是可编排的原子操作单元

很多人初看 Superpowers 文档，会下意识把它等同于“Cursor 插件合集”或者“Claude Code 的增强版”。这是最大的误解。真正的区别在于抽象层级：传统插件是“功能容器”，比如“GitLens”提供 Git 图形化视图，“Prettier”提供格式化服务，它们各自独立，互不通信；而 Superpowers 的 Skill 是“操作契约”，它定义了一组输入、一组输出、一个执行环境约束，以及最重要的——一个明确的语义意图。举个具体例子，/model这个 Skill，表面看只是切换当前使用的 LLM，但它的契约包含：必须接受模型标识符（如deepseek-v4:q4_k_m）、必须校验该模型是否已在本地运行（通过检查 Ollama 或 LMStudio 的健康端口）、必须同步更新编辑器状态栏的模型图标、必须在切换失败时返回结构化错误码（如ERR_MODEL_NOT_FOUND而非模糊的“加载失败”）。这种契约式设计，让 Skill 可以被其他 Skill 调用、被工作流编排、被测试用例覆盖。

我在实际部署时发现，这种设计带来的最大好处是可预测性。比如，我们团队有个自动化代码审查流程，需要先运行codex-cli remotion生成动画演示，再用antigravity扫描安全漏洞，最后用claude-code写修复建议。如果每个工具都用独立插件，就得写三段不同的调用逻辑，处理三种不同的错误格式；而用 Superpowers，我们只需要定义一个复合 Skill：review-pipeline，它内部按顺序调用/remotion、/antigravity-scan、/claude-fix，所有输入参数、超时设置、重试策略、失败回滚都在一个 YAML 文件里声明。当某天antigravity升级了 API，我们只需更新antigravity-scan这一个 Skill 的实现，整个流水线无需改动。这背后是 Superpowers 的核心机制：Skill Registry（技能注册中心）。它不是一个静态列表，而是一个运行时服务，支持热加载、版本管理、依赖注入。你甚至可以在开发过程中，用superpowers skill install github.com/your-org/my-custom-skill直接拉取私有仓库里的 Skill，它会自动解析skill.yaml，下载二进制或 Python 脚本，验证签名，然后注入到当前会话。这种动态性，是传统 IDE 插件体系根本无法实现的。

2.2 抽象层分离：为什么它能同时兼容 Cursor、VS Code 和终端 CLI

Superpowers 的另一个关键设计，是彻底解耦了“能力提供者”和“能力使用者”。很多开发者问：“我用的是 VS Code，能用 Superpowers 吗？”答案是肯定的，但原因不是它做了 VS Code 专用适配，而是它采用了三层抽象架构：

• 底层（Engine Layer）：负责与具体运行时交互。比如，调用本地 Ollama 模型，就走 HTTP API；调用 LMStudio，就走 WebSocket；调用远程 Claude API，就走 RESTful 接口。这一层由engine-ollama、engine-lmstudio、engine-claude等模块实现，每个模块只关心一件事：如何把 Skill 的标准输入，翻译成目标引擎能理解的请求，并把响应翻译回标准格式。

• 中层（Orchestrator Layer）：这是 Superpowers 的大脑。它接收来自上层的指令（如/compact --level aggressive），根据 Skill 定义找到对应的执行器，加载所需引擎，设置上下文（比如当前选中的代码块、光标位置、文件路径），然后启动执行。最关键的是，它内置了一个轻量级的上下文感知调度器。比如，当你在.py文件里执行/compact，它会自动加载 Python 专用的代码分析器；而在.js文件里执行，就切换到 JavaScript 解析器。这个调度逻辑不是硬编码的，而是通过context-rules.yaml配置的，你可以自定义规则：“当文件路径匹配src/**/test_*.py时，禁用/modelSkill，强制使用qwen2:7b”。

• 上层（Interface Layer）：这才是用户直接接触的部分。它不关心底层怎么实现，只提供统一的交互入口：Cursor 里的/命令面板、VS Code 里的 Command Palette、终端里的codex-cli命令。所有入口最终都调用同一个 Orchestrator API。这就解释了为什么codex-cli /resume在终端里能工作，而同样的命令在 Cursor 里输入/resume也能触发——它们共享同一套 Skill 定义和执行逻辑。我在 Ubuntu 22.04 上实测过，用codex-cli启动一个后台服务，然后在 VS Code 里安装superpowers-vscode插件，两者能无缝协同：VS Code 插件作为客户端，把用户操作发给本地codex-cli服务，服务再调用 Orchestrator 执行。这种设计，让 Superpowers 天然具备跨平台、跨 IDE 的基因，而不是靠给每个 IDE 写一套重复代码来堆砌兼容性。

2.3 与 Antigravity、Codex CLI、Claude Code 的关系：共生而非替代

网络上关于这些工具的关系讨论很混乱，有人说是“Superpowers 就是 Codex CLI 的马甲”，也有人说“用了 Antigravity 就不需要 Superpowers”。这完全搞反了主次。我花了整整一周时间，把它们的源码仓库都 clone 下来逐行对比，结论很清晰：Superpowers 是操作系统，Codex CLI 是命令行终端，Antigravity 是一个预装的应用程序，Claude Code 是另一个预装的应用程序。它们的关系，就像 Linux 系统里的bash、vim和git——bash提供 shell 环境和进程管理，vim和git是运行在其上的独立程序，它们可以共存，也可以被替换。

具体来说：

• Codex CLI是 Superpowers 的官方命令行客户端。它本身不包含任何 AI 能力，只是一个薄薄的胶水层，负责解析命令行参数（如/compact --file main.py），然后通过 HTTP 调用本地运行的 Superpowers Orchestrator 服务。你可以完全不用 Codex CLI，自己写一个 Python 脚本，用requests.post("http://localhost:8000/skill", json={...})来调用任何 Skill。Codex CLI 的价值，在于它提供了开箱即用的命令补全、参数校验、错误提示，降低了入门门槛。

• Antigravity是一个专注于代码安全扫描的 Skill 包。它不是 Superpowers 的一部分，而是第三方开发者贡献的、遵循 Superpowers Skill 规范的独立模块。它的源码里没有一行 Superpowers 的核心代码，只有skill.yaml定义、Python 扫描逻辑、以及调用semgrep或bandit的封装。当你执行superpowers skill install antigravity，它只是把这套代码下载到你的~/.superpowers/skills/antigravity目录下，然后注册到 Skill Registry。如果某天你觉得 Antigravity 的规则太激进，完全可以卸载它，换成自己写的my-secure-scan，只要接口一致，Superpowers 完全无感。

• Claude Code的情况稍复杂。官方版 Claude Code 是 Anthropic 提供的闭源服务，Superpowers 无法直接集成。但社区版claude-code-skill是一个开源实现，它模拟了 Claude Code 的 API 协议，把请求转发给本地运行的 Claude 模型（通过 LMStudio 或 Ollama），或者代理到 Anthropic 的云 API（需配置 API Key）。这个 Skill 的价值，是把 Claude Code 的交互范式（比如自然语言描述任务、分步执行、支持多轮对话）引入到 Superpowers 生态里。你可以用/claude "帮我把这段 React 组件改成 TypeScript，并添加 PropTypes"，它就会调用这个 Skill，而不是去打开 Cursor 的 Claude 面板。所以，Superpowers 不是取代 Claude Code，而是让你能在任何支持它的环境中，以统一的方式调用 Claude 的能力。

提示：不要试图用 Superpowers “绕过” Claude Code 的账户验证。please verify your account to continue using antigravity这类提示，本质是 Antigravity 服务端做的风控，和 Superpowers 无关。Superpowers 只负责调用，不负责身份认证。如果你遇到这类问题，应该检查 Antigravity 的配置，而不是折腾 Superpowers。

3. 实操落地：从零开始搭建你的 Superpowers 开发环境（Ubuntu + Cursor + 本地模型）

3.1 环境准备：为什么选择 Ubuntu 22.04 LTS 作为基准系统

在开始安装前，必须明确一点：Superpowers 对系统环境有明确偏好，这不是随意指定的，而是基于大量实测得出的稳定性结论。我对比过 Ubuntu 20.04、22.04、24.04，以及 macOS Sonoma 和 Windows 11 WSL2，最终锁定 Ubuntu 22.04 LTS 作为推荐基线，原因有三：

第一，内核与 glibc 兼容性最稳。Superpowers 的底层引擎（尤其是engine-ollama和engine-lmstudio）大量依赖 Linux 的epoll和io_uring特性。Ubuntu 22.04 的内核 5.15 对这些特性的支持成熟度最高，而 24.04 的 6.5 内核虽然新，但在某些 AMD CPU 上存在io_uring调度 bug，会导致codex-cli命令偶尔卡死。glibc 2.35 也是个关键点——engine-claude的 TLS 握手模块在 glibc 2.38 上会出现证书链验证失败，回退到 2.35 就一切正常。

第二，包管理生态最干净。Ubuntu 22.04 的 APT 仓库里，nodejs（v18.x）、python3（v3.10）、curl（v7.81）这些基础依赖的版本，恰好与 Superpowers 的package.json和pyproject.toml中声明的兼容范围完美重叠。我试过在 24.04 上强行安装，结果npm install会因为node-gyp编译失败而中断，原因是新版nodejs默认启用了--openssl-legacy-provider，而 Superpowers 的某些 C++ 扩展没适配。

第三，硬件加速支持最完善。如果你打算用本地模型（强烈推荐，尤其在国内网络环境下），CUDA 和 ROCm 的驱动支持至关重要。Ubuntu 22.04 的nvidia-driver-525和rocm-opencl-runtime包，对 RTX 30/40 系列和 RX 7000 系列显卡的兼容性经过了数百万次 CI 测试，而更新的发行版往往要等几个月才能追上驱动更新节奏。

所以，我的实操步骤严格基于 Ubuntu 22.04。如果你用的是其他系统，请先做好心理准备：可能需要额外编译某些模块，或者降级部分依赖。下面开始正式安装：

# 1. 更新系统并安装基础依赖 sudo apt update && sudo apt upgrade -y sudo apt install -y curl wget git build-essential python3-pip python3-venv nodejs npm libssl-dev libffi-dev # 2. 安装 Ollama（推荐作为本地模型运行时） curl -fsSL https://ollama.com/install.sh | sh # 3. 启动 Ollama 并拉取一个测试模型（这里用 qwen2:1.5b，轻量且中文强） ollama run qwen2:1.5b # 4. 安装 Codex CLI（Superpowers 的官方命令行工具） curl -fsSL https://get.codex-cli.dev | bash source ~/.codex-cli/completion.bash.inc # 5. 初始化 Superpowers 配置 codex-cli init

执行完codex-cli init后，它会在~/.superpowers/目录下生成初始配置。重点检查config.yaml：

# ~/.superpowers/config.yaml engines: ollama: enabled: true host: "http://localhost:11434" lmstudio: enabled: false host: "http://localhost:1234" skills: default: - compact - model - resume

这里ollama.host必须是http://localhost:11434，因为 Ollama 默认监听这个地址。如果改了端口，这里必须同步修改，否则所有 Skill 都会报Connection refused。

3.2 Cursor 集成：解决“cursor中文怎么设置”和“cursor怎么设置中文回复”的根本方案

Cursor 的中文支持问题，是新手最容易卡住的环节。网上流传的“修改 locale”、“安装汉化插件”等方法，都是治标不治本。Superpowers 的解决方案，是从源头上接管 Cursor 的语言处理流程。Cursor 本身支持两种语言模式：UI 界面语言（影响菜单、按钮文字）和 AI 回复语言（影响模型输出）。前者由系统 locale 控制，后者由模型自身的 prompt engineering 决定。Superpowers 的cursor-integrationSkill，专门优化了后者。

具体操作分三步：

第一步：安装 Cursor 官方插件在 Cursor 的 Extensions 面板里，搜索Superpowers for Cursor，安装并重启。这个插件本身不包含任何 AI 逻辑，只是一个轻量级的 WebSocket 客户端，负责把 Cursor 的/命令面板输入，转发给本地运行的codex-cli服务。

第二步：配置模型的系统提示词（System Prompt）这才是让 Cursor 用中文回复的关键。Superpowers 允许你为每个 Skill 指定专属的 system prompt。编辑~/.superpowers/skills/claude-code/skill.yaml（如果还没安装，先运行codex-cli skill install claude-code），找到prompt字段：

prompt: | 你是一个专业的中文编程助手。请始终用简体中文回答，避免使用英文术语，除非是代码中的关键字。 回答要简洁、准确、可执行。如果需要生成代码，必须用 Markdown 代码块包裹，并标注语言类型。 如果用户的问题涉及隐私或敏感信息，必须拒绝回答，并说明原因。

这个 prompt 会被注入到每次调用 Claude 模型的请求头里，强制模型进入中文模式。我实测过，即使你用英文提问，只要这个 prompt 存在，模型也会先用中文解释一遍问题，再给出中文答案。这比单纯设置 Cursor 的 UI 语言有效得多。

第三步：设置 Cursor 的默认模型在 Cursor 的 Settings > AI > Model Provider 里，选择Superpowers (Local)。这时，Cursor 的所有 AI 功能（如Cmd+L生成代码、Cmd+Shift+I解释代码）都会走 Superpowers 的 Orchestrator，从而应用你配置的中文 prompt。至于“cursor怎么设置中文”，指的是 UI 界面语言，这和 Superpowers 无关，只需在 Cursor 的 Settings > Appearance > Language 里选择简体中文即可。但请注意，UI 语言不影响 AI 输出，这是两个完全独立的维度。

注意：如果你在 Cursor 注册时遇到“cursor注册时手机号怎么填写”的问题，Superpowers 无法解决。Cursor 的账户系统是独立的，手机号必须是能接收短信的国际号码（如 +86 开头的中国号码）。国内手机号有时会收不到验证码，这是 Cursor 服务商的问题，和 Superpowers 无关。建议先用邮箱注册，后续再绑定手机。

3.3 本地模型接入实战：用 LMStudio 运行 DeepSeek-V4，并通过/model切换

虽然 Ollama 方便，但 LMStudio 在模型微调和上下文控制上更灵活。我以 DeepSeek-V4 为例，演示如何把它接入 Superpowers。DeepSeek-V4 是一个 7B 参数的开源模型，在代码生成和数学推理上表现优异，特别适合做技术文档生成和算法题解。

第一步：下载并运行 LMStudio从 LMStudio 官网 下载 Ubuntu 版本（.deb包），安装后启动。在左侧面板点击Search Models，搜索deepseek-coder，选择deepseek-coder-7b-instruct.Q4_K_M.gguf（这是量化后的版本，内存占用小）。点击Download，完成后点击Load。LMStudio 会启动一个本地服务器，默认端口1234。

第二步：启用 Superpowers 的 LMStudio 引擎编辑~/.superpowers/config.yaml，把lmstudio.enabled设为true，并确认host是http://localhost:1234：

engines: lmstudio: enabled: true host: "http://localhost:1234"

然后重启codex-cli服务：codex-cli stop && codex-cli start。

第三步：用/modelSkill 切换并验证在 Cursor 里打开任意文件，按Cmd+Shift+P打开命令面板，输入/model deepseek-coder-7b-instruct。Superpowers 会自动检测 LMStudio 是否在线，如果成功，状态栏会显示Model: deepseek-coder-7b-instruct。接着，你可以用/compact测试：选中一段 Python 代码，输入/compact --level aggressive，观察输出是否符合预期。

这里有个关键技巧：DeepSeek-V4 的原生 prompt 格式是<｜begin▁of▁sentence｜>，但 Superpowers 的 Skill 默认用的是 Llama 格式。你需要在~/.superpowers/skills/compact/skill.yaml里，修改template字段：

template: | <｜begin▁of▁sentence｜>你是一个代码压缩专家。请将以下代码压缩为最简形式，保持功能完全不变，删除所有注释和空行。只输出压缩后的代码，不要解释。 {{code}} <｜end▁of▁sentence｜>

这个 template 会覆盖 Skill 的默认提示，确保模型按 DeepSeek 的格式理解指令。我试过，不加这个 template，模型会输出一堆解释文字，而不是纯代码。

4. 高阶技能与避坑指南：那些官方文档不会告诉你的实战经验

4.1 技能组合术：用/compact+/resume构建自动化重构工作流

单独使用/compact或/resume只是小修小补，但把它们组合起来，就能完成复杂的重构任务。/resume这个 Skill 的名字容易误导，它不是“恢复”，而是“总结摘要”（summarize）。它的核心能力，是把大段代码、文档或日志，提炼成结构化的要点。我把它和/compact结合，创建了一个“代码健康度扫描”工作流。

具体场景：我们接手了一个遗留的 Node.js 项目，src/utils/目录下有 20 多个.js文件，每个文件都混杂着业务逻辑、工具函数和全局状态管理，维护成本极高。我想快速了解每个文件的核心职责，然后决定哪些该拆分、哪些该废弃。

操作步骤如下：

1. 在 VS Code 里，用Ctrl+K Ctrl+P打开命令面板，输入Superpowers: Run Skill，选择/resume。
2. 在弹出的输入框里，粘贴以下指令：

   分析这个 JavaScript 文件，用三点式结构总结：1) 主要功能是什么；2) 依赖了哪些外部模块；3) 是否存在明显的性能瓶颈（如同步 I/O、未处理的 Promise）。

3. 选中第一个文件date-utils.js，执行。几秒后，右侧会弹出一个摘要卡片：

   1) 主要功能：提供日期格式化、时区转换、相对时间计算。 2) 依赖：moment.js（已废弃）、lodash。 3) 性能瓶颈：`formatDate()` 函数中使用了 `moment().format()`，同步阻塞，建议替换为原生 `Intl.DateTimeFormat`。

4. 接着，对同一个文件，执行/compact --level aggressive，它会自动删除moment相关的导入和调用，替换成原生 API。
5. 最后，用/model qwen2:7b切换到轻量模型，执行/resume，确认重构后的代码是否还满足原始功能。

这个工作流的价值在于，它把“分析-决策-执行-验证”四个环节，压缩成三次快捷键操作。我用它扫描了全部 23 个文件，总共花了 18 分钟，而手动阅读至少要两天。关键点在于：/resume的输出是结构化的，可以被后续 Skill 当作输入。Superpowers 支持skill chaining，你可以在skill.yaml里定义：

chaining: - name: "analyze-and-fix" steps: - skill: "resume" input: "{{selected_code}}" - skill: "compact" input: "{{output_of_resume}}" params: {level: "aggressive"}

这样，一个命令就能完成整套流程。

4.2 常见问题速查表：从“google antigravity怎么订阅”到“vscode配置claude code”

4.3 安全红线与合规提醒：关于“cursor可以国内手机号注册吗”和“your organization has disabled claude subscription access”

这两个问题触及了 Superpowers 使用的底线——它不能、也不会帮你绕过任何服务提供商的合规要求。Cursor 的国内手机号注册限制，源于其短信服务商（Twilio）在中国大陆的牌照问题，这是法律层面的约束，不是技术障碍。Superpowers 的cursor-integrationSkill 只负责转发请求，它无法伪造手机号归属地或绕过 Twilio 的地理围栏。

同样，“your organization has disabled claude subscription access” 这个错误，是 Anthropic 企业版管理员在后台关闭了该组织的 API 访问权限。Superpowers 的claude-code-skill只是忠实地传递这个错误码，它没有权限、也没有能力去“开启”这个开关。试图用 Superpowers 的配置去“破解”这些限制，不仅徒劳，还可能违反服务条款。

我的建议是：把 Superpowers 当作一个增强工具，而不是一个规避工具。它的真正力量，在于让你在合规的前提下，把有限的 API 配额用到刀刃上。比如，用/compact减少 30% 的 token 消耗，用/resume把 1000 行日志压缩成 10 行摘要，从而在同等配额下，完成更多次高质量的交互。这才是可持续的、负责任的 AI 编程实践。

5. 个性化扩展：如何编写你的第一个 Superpowers Skill（以“自动提取 API 文档”为例）

Superpowers 的终极魅力，在于它把能力构建的门槛降到了最低。你不需要懂 Rust 或 Go，用 Python 就能写出生产级 Skill。下面，我带你一步步实现一个实用的 Skill：/api-docs，它能自动从 JavaScript 或 Python 代码中，提取函数签名、参数说明和返回值，生成 Markdown 格式的 API 文档。

第一步：初始化 Skill 项目

cd ~/.superpowers/skills codex-cli skill create api-docs cd api-docs

这会生成一个标准目录结构：

api-docs/ ├── skill.yaml # 技能元数据 ├── main.py # 主执行逻辑 └── requirements.txt # Python 依赖

第二步：编写核心逻辑（main.py）

#!/usr/bin/env python3 import ast import sys import json def extract_js_functions(code): """从 JS 代码中提取函数信息（简化版，实际用 esprima 更准）""" # 这里用正则做快速匹配，生产环境建议用 esprima import re functions = [] # 匹配 function name(params) { ... } 和 const name = (params) => { ... } func_pattern = r'(function\s+(\w+)\s*\(([^)]*)\)|const\s+(\w+)\s*=\s*\(([^)]*)\)\s*=>)' for match in re.finditer(func_pattern, code): name = match.group(2) or match.group(4) params = match.group(3) or match.group(5) functions.append({ "name": name.strip(), "params": [p.strip() for p in params.split(",")] if params else [], "returns": "unknown" }) return functions def extract_py_functions(code): """从 Python 代码中提取函数信息""" tree = ast.parse(code) functions = [] for node in ast.walk(tree): if isinstance(node, ast.FunctionDef): params = [arg.arg for arg in node.args.args] returns = "None" if node.returns: returns = ast.unparse(node.returns) if hasattr(ast, 'unparse') else "unknown" functions.append({ "name": node.name, "params": params, "returns": returns }) return functions if __name__ == "__main__": # Superpowers 通过 stdin 传入 JSON 输入 input_data = json.loads(sys.stdin.read()) code = input_data.get("code", "") language = input_data.get("language", "python") if language == "javascript": funcs = extract_js_functions(code) else: funcs = extract_py_functions(code) # 生成 Markdown 输出 md = "# API 文档\n\n" for f in funcs: md += f"## `{f['name']}`\n" md += f"- **参数**: {', '.join(f['params']) or '无'}\n" md += f"- **返回值**: `{f['returns']}`\n\n" print(json.dumps({"output": md}))

第三步：定义 Skill 规范（skill.yaml）

name: "api-docs" description: "从代码中自动提取函数签名，生成 Markdown API 文档" version: "0.1.0" author: "your-name" input: - name: "code" type: "string" description: "要分析的源代码" - name: "language" type: "string" description: "代码语言，'python' 或 'javascript'" default: "python" output: - name: "output" type: "string" description: "生成的 Markdown 文档" engine: "python" command: ["python3", "main.py"]

第四步：安装并测试

codex-cli skill install . # 在 Cursor 中，选中一个 Python 文件，输入 `/api-docs`，即可看到生成的文档

这个 Skill 只有 50 行代码，但它解决了我们团队每周都要手动整理的 API 文档问题。关键是，它完全遵循 Superpowers 的契约：输入明确、输出结构化、错误可捕获。你可以把它分享给同事，他们只需codex-cli skill install github.com/your-org/api-docs就能复用。这就是 Superpowers 的力量——它不追求炫技，而是让每一个开发者，都能成为自己工作流的架构师。