## 项目概述

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 仓库：https://github.com/obra/superpowers
- 发布公告：https://blog.fsck.com/2025/10/09/superpowers/
- Discord 社区：https://discord.gg/35wsABTejz
- 问题追踪：https://github.com/obra/superpowers/issues
- 最新版本：v6.2.0（2026-07-24 发布）

## 信息来源和分析时间

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