obra / superpowers

obra/superpowers

open_in_new前往仓库

一个有效的智能体技能框架与软件开发方法论。

项目概览

项目概述

Superpowers 是一个面向编码代理（coding agents）的智能体技能框架与软件开发方法论。它由一组可组合的技能（skills）和初始指令构成，使编码代理在开发过程中自动遵循一套结构化的流程，包括需求澄清、设计确认、计划制定、子代理驱动开发（subagent-driven development）、测试驱动开发（TDD）以及代码审查。该项目旨在提升编码代理在真实软件开发任务中的自主性、一致性和代码质量。

核心功能

  • 技能库（Skills Library）：包含多个技能，如 brainstorming（头脑风暴）、writing-plans（编写计划）、executing-plans（执行计划）、subagent-driven-development（子代理驱动开发）、test-driven-development（测试驱动开发）、systematic-debugging（系统化调试）、requesting-code-review（请求代码审查）等。
  • 自动触发机制：编码代理在开始任何任务前会自动检查相关技能，并强制遵循工作流，而非仅作为建议。
  • 子代理驱动开发：为每个工程任务分派全新的子代理，并执行两阶段审查（规格符合性与代码质量），支持长时间自主工作。
  • 测试驱动开发（TDD）：强制 RED-GREEN-REFACTOR 循环，先写失败测试，再写最小代码使其通过，最后重构。
  • 多平台支持：支持 Claude Code、Antigravity、Codex App、Codex CLI、Cursor、Factory Droid、Gemini CLI、GitHub Copilot CLI、Kimi Code、OpenCode、Pi 等多种编码代理平台。
  • 可视化头脑风暴伴侣（Visual Companion）：提供基于浏览器的可视化界面，用于展示 UI 原型、线框图，并收集用户交互反馈。
  • 进度账本（Progress Ledger）：在会话压缩后，通过账本文件记录任务完成状态，确保恢复时不会重复执行已完成任务。

适用与不适用场景

适用场景：

  • 需要编码代理自主执行多任务实现计划的软件开发项目。
  • 强调测试驱动开发、代码质量和结构化流程的团队。
  • 需要长时间自主工作（如数小时）而无需人工频繁干预的任务。
  • 跨多个编码代理平台（如 Claude Code、Codex、Cursor 等）保持一致的开发方法论。

不适用场景：

  • 简单的、一次性的代码修改，无需完整流程。
  • 需要紧密耦合、无法分解为独立任务的开发工作。
  • 编码代理平台不支持会话启动时自动注入指令（无法满足硬性要求）。
  • 对流程开销敏感、希望快速迭代而不愿遵循严格审查循环的场景。

技术架构与依赖

  • 语言：Shell（主要脚本）、JavaScript/TypeScript（插件与扩展）、Python（评估工具）。
  • 依赖：仓库资料未提供具体运行时依赖列表，但项目强调零运行时依赖（zero-dependency）。
  • 架构：核心技能内容与平台无关，通过各平台的插件/扩展机制注入引导指令（bootstrap），并将技能中的动作词汇映射到平台原生工具。
  • 评估：使用 drill 评估框架（位于 evals/ 目录）进行技能行为测试，通过真实 LLM 会话验证技能合规性。

安装与快速开始

安装方式因平台而异，以下为部分平台的安装命令：

  • Claude Code：/plugin install superpowers@claude-plugins-official 或通过 Superpowers marketplace 安装。
  • Antigravity：agy plugin install https://github.com/obra/superpowers
  • Codex CLI：在插件搜索界面中搜索 superpowers 并安装。
  • Cursor：在 Agent chat 中执行 /add-plugin superpowers。
  • Gemini CLI：gemini extensions install https://github.com/obra/superpowers
  • GitHub Copilot CLI：copilot plugin marketplace add obra/superpowers-marketplace 然后安装。
  • Kimi Code：在插件管理器中搜索 Superpowers 并安装。
  • OpenCode：在 opencode.json 中添加 "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]。
  • Pi：pi install git:github.com/obra/superpowers

安装后，启动编码代理会话，Superpowers 会自动激活。

典型使用方法

  1. 启动会话：在支持的编码代理中开始新会话。
  2. 自动触发：代理检测到开发任务后，自动加载 brainstorming 技能，通过提问澄清需求。
  3. 设计确认：代理将设计文档分块展示，用户确认后进入计划阶段。
  4. 计划制定：writing-plans 技能将工作分解为小任务（每个 2-5 分钟），包含精确文件路径、完整代码和验证步骤。
  5. 执行计划：用户批准后，代理使用 subagent-driven-development 或 executing-plans 技能，分派子代理逐任务执行，并进行两阶段审查。
  6. 测试驱动：实现过程中强制 TDD 循环。
  7. 完成分支：所有任务完成后，使用 finishing-a-development-branch 技能决定合并、创建 PR 或保留分支。

配置与部署要点

  • 环境变量：SUPERPOWERS_DISABLE_TELEMETRY 可禁用遥测；BRAINSTORM_PORT、BRAINSTORM_DIR 等用于配置可视化伴侣服务器。
  • 遥测：默认加载 Prime Radiant 标志，包含版本信息，不包含项目细节；可通过环境变量禁用。
  • 多平台安装：每个平台需单独安装，不能跨平台复用。
  • 更新：更新方式因平台而异，通常通过插件管理器或重新安装。
  • 安全：可视化伴侣服务器默认绑定 127.0.0.1，支持会话密钥认证，防止跨源攻击。

限制、风险与许可证

  • 限制：
    • 需要平台支持会话启动时自动注入指令，否则无法正常工作。
    • 技能内容为精心调校的行为塑造代码，不接受随意修改。
    • 评估场景运行成本高（每次约 $3-15），且需要真实 API 密钥。
  • 风险：
    • 长时间自主运行可能产生意外行为，需人工监督。
    • 可视化伴侣存在安全风险，已通过密钥和 Origin 检查缓解。
    • 进度账本可能因 git clean -fdx 被删除，需从 git 日志恢复。
  • 许可证：MIT License。

官方链接

信息来源和分析时间

  • 信息来源：GitHub 仓库 obra/superpowers 的 README、文档目录（docs/）、计划文档（docs/superpowers/plans/）以及最新发布信息。
  • 分析时间：2026-07-24（基于最新发布版本日期）。