Superpowers全平台零障碍部署指南：Claude Code、Codex与OpenCode三大平台安装教程

问题：开发效率提升的技术瓶颈

在现代软件开发流程中，开发者常面临工具链整合复杂、平台差异导致的配置难题，以及AI辅助开发工具能力碎片化等问题。Superpowers作为基于技能组合系统（→基于模块化能力的工作流引擎）的开发环境，通过可组合的"技能"模块解决这些痛点，为不同AI编码平台提供统一的增强能力。本教程将通过"问题-方案-验证-进阶"四阶段框架，帮助开发者在三大主流平台实现零障碍部署。

方案：跨平台安装实施指南

Claude Code平台部署

环境诊断（基础，5分钟）

在开始安装前，请确认Claude Code已更新至最新版本，并具备插件市场访问权限。执行以下命令检查系统兼容性：

# 检查Claude Code版本
/claude version
# 验证插件市场连接性
/plugin marketplace list

核心部署（基础，8分钟）

Claude Code提供插件市场一键安装功能，具体步骤如下：

操作步骤	命令	参数说明
注册插件市场	/plugin marketplace add obra/superpowers-marketplace	obra/superpowers-marketplace：官方插件源标识
安装核心包	/plugin install superpowers@superpowers-marketplace	superpowers：核心技能包名 @superpowers-marketplace：指定插件源
查看已安装插件	/plugin list	验证Superpowers是否出现在已安装列表中

功能验证（基础，2分钟）

执行帮助命令检查核心功能是否可用：

/help

成功安装后应显示Superpowers命名空间下的命令列表，包括brainstorm、write-plan和execute-plan。

Codex平台部署

环境诊断（进阶，10分钟）

Codex平台需要手动配置环境变量和依赖管理。执行以下命令检查系统要求：

# 检查Node.js版本（需v16+）
node -v
# 验证Git安装
git --version

核心部署（进阶，15分钟）

通过官方仓库手动部署Superpowers：

# 克隆项目仓库
git clone https://gitcode.com/GitHub_Trending/su/superpowers
cd superpowers
# 执行Codex专用安装脚本
./.codex/install.sh
# 配置环境变量
export SUPERPOWERS_HOME=~/.config/codex/superpowers

功能验证（基础，3分钟）

导入核心技能包并验证加载状态：

# 加载技能系统
codex load skills-core.js
# 验证技能加载
codex skills list

应显示包括brainstorming、test-driven-development在内的技能列表。

OpenCode平台部署

环境诊断（基础，7分钟）

OpenCode需要特定版本的插件系统支持。执行以下命令检查兼容性：

# 检查OpenCode版本
opencode --version
# 验证插件目录权限
ls -ld ~/.config/opencode/plugins

核心部署（基础，12分钟）

通过OpenCode命令行工具完成部署：

# 执行安装引导命令
opencode install https://gitcode.com/GitHub_Trending/su/superpowers
# 配置技能路径
opencode config set skills.path ~/.config/opencode/skills
# 更新技能缓存
opencode skills refresh

功能验证（基础，5分钟）

运行集成测试套件验证功能完整性：

# 执行平台测试
cd tests/opencode
./run-tests.sh

测试通过应显示"All tests passed"消息。

验证：功能完整性检测体系

基础验证（所有平台通用）

• 命令可用性检查：执行/superpowers:help（Claude）或superpowers --help（其他平台）验证基础命令集
• 技能列表验证：确认brainstorming、writing-plans等核心技能出现在可用技能列表中
• 版本信息验证：检查RELEASE-NOTES.md确认安装版本与预期一致

集成验证（进阶）

• 工作流测试：执行/superpowers:brainstorm "创建一个待办应用"验证端到端流程
• 技能联动测试：使用write-plan生成计划后，立即执行execute-plan验证数据流转
• 环境集成测试：检查Superpowers是否正确识别当前项目类型并加载对应技能

性能验证（高级）

• 响应时间测试：测量brainstorm命令从调用到首次响应的时间（应<3秒）
• 资源占用监控：执行top或任务管理器，确认技能运行时内存占用<200MB
• 并发能力测试：同时激活3个不同技能，验证系统稳定性

进阶：场景化应用与深度优化

跨平台兼容性矩阵

功能特性	Claude Code	Codex	OpenCode	备注
插件自动更新	✅ 支持	❌ 需手动	✅ 支持	Claude支持后台自动更新
技能自定义	⚠️ 有限支持	✅ 完全支持	✅ 完全支持	Codex支持自定义技能开发
多语言支持	✅ 10种+	✅ 15种+	✅ 12种+	Codex支持最广泛的语言
离线工作模式	❌ 不支持	✅ 支持	⚠️ 部分支持	Codex可完全离线运行
团队协作功能	✅ 完整支持	❌ 不支持	✅ 基础支持	Claude提供团队共享技能库

场景化应用指南

场景1：快速原型开发（适合初创项目）

1. 启用技能组合：brainstorming + writing-plans + test-driven-development
2. 执行流程：

   /superpowers:brainstorm "创建一个React待办应用"
   /superpowers:write-plan --framework react --tests true
   /superpowers:execute-plan --batch-size 5
   

3. 配置建议：设置AUTO_COMMIT=true自动提交代码变更

场景2：企业级应用开发（适合中大型项目）

1. 启用技能组合：systematic-debugging + requesting-code-review + verification-before-completion
2. 执行流程：

   # 启用严格模式
   /superpowers:config set strictMode true
   # 配置代码审查规则
   /superpowers:review-config set minApprovals 2
   # 执行质量门禁检查
   /superpowers:verify --require-coverage 80%
   

3. 配置建议：集成using-git-worktrees技能管理多分支并行开发

场景3：开源项目贡献（适合社区开发者）

1. 启用技能组合：finishing-a-development-branch + receiving-code-review + using-git-worktrees
2. 执行流程：

   # 创建专用工作树
   /superpowers:git-worktree create feature/new-skill
   # 提交贡献前检查
   /superpowers:prepare-pr --lint --test --signoff
   # 生成贡献文档
   /superpowers:write-contribution --type feature
   

3. 配置建议：设置CONTRIBUTOR_MODE=true自动生成贡献指南

故障排除决策树

安装类错误

• 插件市场连接失败

  • 检查网络连接：ping marketplace.obra.dev
  • 验证防火墙设置：确保443端口开放
  • 手动添加市场：/plugin marketplace add obra/superpowers-marketplace --force

• 依赖安装失败

  • 清除npm缓存：npm cache clean --force
  • 更换镜像源：npm config set registry https://registry.npm.taobao.org
  • 手动安装依赖：cd lib && npm install

功能类错误

• 技能加载失败

  • 检查技能文件权限：chmod +r skills/**/*.md
  • 验证技能格式：/superpowers:validate-skills
  • 重置技能缓存：/superpowers:cache clear

• 命令执行超时

  • 增加超时设置：/superpowers:config set timeout 60
  • 减少批处理大小：--batch-size 2
  • 检查系统资源：free -m确认内存充足

环境预检工具

使用项目内置的环境检测脚本进行系统兼容性检查：

# 运行环境检测工具
./tests/opencode/test-tools.sh --preflight

该工具会自动检查：

• 系统依赖版本兼容性
• 文件系统权限配置
• 网络连接状态
• 必要环境变量设置

技能组合推荐清单

初级开发者

• 基础组合：brainstorming + writing-plans + using-superpowers
• 学习路径：先掌握计划生成与执行流程，再逐步扩展技能范围
• 配置建议：启用GUIDED_MODE=true获取操作提示

中级开发者

• 进阶组合：test-driven-development + systematic-debugging + executing-plans
• 学习路径：深入理解测试驱动开发流程，掌握调试技巧
• 配置建议：集成git-worktrees管理复杂项目结构

高级开发者

• 专家组合：subagent-driven-development + dispatching-parallel-agents + verification-before-completion
• 学习路径：掌握多代理协作开发，优化复杂项目管理
• 配置建议：自定义技能开发，扩展skills-core.js功能

深入学习资源

• 核心技能文档：skills/目录下各技能的SKILL.md文件
• 平台专属指南：
  • Claude Code：docs/README.codex.md
  • OpenCode：docs/README.opencode.md
• 测试策略：docs/testing.md提供完整测试方法论
• 技能开发指南：skills/writing-skills/SKILL.md介绍自定义技能开发流程

通过本指南，您已掌握Superpowers在三大平台的部署方法及高级应用技巧。Superpowers的模块化设计使您能够根据项目需求灵活组合技能，显著提升开发效率。随着使用深入，建议定期查看RELEASE-NOTES.md获取功能更新信息，保持技能系统与时俱进。