superpowers故障排除手册：从安装到开发的全方位问题解决指南

superpowers作为Claude Code的核心技能库，是一款提升开发效率的开源工具，为开发者提供强大的AI辅助开发能力。本文将帮助你解决从安装到使用过程中的常见错误，确保你能顺利体验这一工具带来的开发效率提升。

问题速查导航

• 安装类错误
  • Plugin not found错误
  • Windows系统CRLF行结束符问题
  • 旧版本迁移失败
• 使用类错误
  • Plugin hook error错误
  • Bad substitution错误
  • 技能未找到问题
• 开发模式问题
  • 代码审查循环问题
  • 规范理解偏差问题

模块化问题解决单元

如何解决Plugin not found错误

现象描述

当你执行/plugin install superpowers@superpowers-marketplace命令时，系统提示"Plugin not found"错误。

原因分析

1. 插件市场配置不正确
2. 网络连接问题
3. 命令格式错误

分步解决

1. 检查插件市场配置是否正确
2. 验证网络连接状态
3. 确保使用正确的安装命令：

   /plugin install superpowers@superpowers-marketplace
   

4. 运行验证命令确认安装是否成功：

   /plugin list | grep superpowers
   

避坑指南

• 确保使用最新版本的插件市场客户端
• 检查防火墙设置，确保插件市场域名可访问

常见误区

不要省略@superpowers-marketplace后缀，这会导致系统无法正确定位插件源。

如何解决Windows系统CRLF行结束符问题

现象描述

在Windows系统上安装或运行superpowers时，出现由于行结束符引起的脚本执行错误。

原因分析

Windows系统默认使用CRLF作为行结束符，而项目需要LF行结束符。

分步解决

1. 检查项目中的.gitattributes文件，确保已配置强制使用LF行结束符
2. 重新克隆项目仓库：

   git clone https://gitcode.com/GitHub_Trending/su/superpowers
   

3. 验证行结束符设置：

   git config --get core.autocrlf
   

避坑指南

• 在Windows系统上使用Git Bash或WSL终端执行命令
• 避免使用Windows自带的记事本编辑项目文件

常见误区

认为手动转换行结束符即可解决问题，实际上需要通过Git配置确保长期生效。

如何解决旧版本迁移失败问题

现象描述

从旧版本superpowers迁移到新版本时，出现技能无法加载或配置丢失的问题。

原因分析

1. 技能路径变更
2. 配置文件格式不兼容
3. 旧版钩子脚本被移除

分步解决

1. 将技能符号链接到新路径：

   ln -s /path/to/old/skills ~/.config/opencode/skills/superpowers/
   

2. 运行配置迁移工具：

   ./scripts/migrate-config.sh
   

3. 使用新的初始化脚本替代旧的钩子：

   ./initialize-skills.sh
   

4. 验证迁移是否成功：

   ./tests/opencode/test-skills-core.sh
   

避坑指南

• 迁移前备份旧版本配置文件
• 按照RELEASE-NOTES.md中的迁移指南逐步操作

常见误区

直接复制配置文件而不是使用符号链接，导致后续更新困难。

如何解决Plugin hook error错误

现象描述

启动superpowers时，出现"Plugin hook error"错误，技能上下文无法加载。

原因分析

session-start钩子执行失败，导致技能初始化过程中断。

分步解决

1. 更新superpowers到最新版本：

   /plugin update superpowers
   

2. 手动执行session-start脚本：

   hooks/session-start
   

3. 检查钩子执行日志：

   cat hooks/session-start.log
   

4. 验证钩子是否正常工作：

   ./tests/opencode/test-plugin-loading.sh
   

避坑指南

• 确保钩子脚本具有可执行权限
• 检查日志文件中的错误信息

常见误区

忽略钩子执行失败的具体错误信息，盲目重新安装插件。

如何解决Bad substitution错误

现象描述

在Ubuntu/Debian系统上执行脚本时，出现"/bin/sh is dash"导致的"Bad substitution"错误。

原因分析

Ubuntu/Debian系统默认使用dash作为/bin/sh，而部分脚本需要bash环境。

分步解决

1. 检查当前shell：

   ls -l /bin/sh
   

2. 如果链接到dash，切换到bash：

   sudo ln -sf /bin/bash /bin/sh
   

3. 重新执行脚本验证：

   ./run-skill-tests.sh
   

避坑指南

• 在脚本开头使用#!/bin/bash明确指定shell
• 避免使用bash特有的语法结构

常见误区

认为修改脚本内容比更改默认shell更简单，实际上切换到bash可以一劳永逸解决问题。

如何解决技能未找到问题

现象描述

系统提示找不到特定技能，尽管已经安装了superpowers插件。

原因分析

1. 技能安装不完整
2. 技能路径配置错误
3. 插件加载顺序问题

分步解决

1. 运行技能测试脚本验证安装：

   tests/claude-code/run-skill-tests.sh
   

2. 检查技能路径配置：

   echo $SUPERPOWERS_SKILLS_PATH
   

3. 确保技能已克隆到正确目录：

   ls ~/.config/superpowers/skills/
   

4. 重新加载插件：

   /plugin reload superpowers
   

避坑指南

• 使用test-plugin-loading.sh脚本验证插件结构
• 确保环境变量正确设置

常见误区

手动创建技能目录而不是使用官方安装脚本，导致目录结构不完整。

代码审查循环问题的3种解决方法

现象描述

在使用子代理驱动开发时，代码审查反复发现问题，形成无限循环。

原因分析

1. 实施者未正确理解审查意见
2. 审查标准不明确
3. 缺乏有效的沟通机制

分步解决

方法一：增强审查反馈清晰度

1. 审查者提供具体的修改建议而非笼统评价
2. 实施者确认理解所有审查意见
3. 进行小步修改并重新提交

方法二：引入第三方仲裁

1. 当循环超过3次时，邀请第三位开发者参与
2. 共同制定明确的修改方案
3. 按优先级分批解决问题

方法三：调整开发流程

1. 在正式审查前增加同伴评审环节
2. 实施者先进行自我审查
3. 使用自动化工具进行初步检查

避坑指南

• 建立明确的审查标准和验收条件
• 限制单次审查的修改范围

常见误区

认为审查循环是正常现象，实际上这表明开发流程或沟通存在问题。

如何解决规范理解偏差问题

现象描述

规范审查者发现实施者解决了错误的问题，与需求不符。

原因分析

1. 需求文档不清晰
2. 实施前缺乏充分的需求讨论
3. 规范理解存在主观差异

分步解决

1. 立即停止当前任务
2. 安排需求澄清会议
3. 更新需求文档，增加具体示例
4. 创建原型验证理解是否一致
5. 根据澄清后的需求重新规划开发任务

避坑指南

• 在开发前进行需求确认和签字
• 使用可视化工具辅助需求理解
• 定期进行需求回顾

常见误区

急于开始编码而忽略需求澄清，导致后期大量返工。

进阶优化建议

环境隔离最佳实践

为避免不同项目间的冲突，建议为每个项目创建独立的superpowers环境：

# 创建隔离环境
source tests/opencode/setup.sh

# 验证环境隔离状态
echo $SUPERPOWERS_ENVIRONMENT

自动化测试集成

将superpowers测试集成到CI/CD流程中：

# 添加到CI配置文件
tests/claude-code/run-skill-tests.sh && tests/opencode/test-skills-core.sh

技术资源库

官方文档

• 安装指南：README.md
• 发布说明：RELEASE-NOTES.md
• 测试文档：docs/testing.md

测试脚本

• 技能测试：tests/claude-code/run-skill-tests.sh
• 核心测试：tests/opencode/test-skills-core.sh
• 插件测试：tests/opencode/test-plugin-loading.sh

技能文档

• 子代理开发：skills/subagent-driven-development/SKILL.md
• 系统调试：skills/systematic-debugging/SKILL.md
• 测试驱动开发：skills/test-driven-development/SKILL.md

用户分类指引

新手用户

• 从README.md开始了解项目
• 使用/plugin install superpowers@superpowers-marketplace快速安装
• 运行tests/claude-code/run-skill-tests.sh验证安装

开发者

• 查阅docs/plans/了解开发计划
• 使用子代理开发模式提高效率
• 参与技能测试和改进

管理员

• 关注RELEASE-NOTES.md中的更新内容
• 配置适当的环境变量和权限
• 定期运行完整测试套件

附录：问题反馈模板

当遇到本手册未涵盖的问题时，请使用以下模板提交反馈：

问题描述：
重现步骤：
错误日志：
环境信息：
已尝试的解决方案：
预期行为：

请将填写好的模板提交到项目的issue跟踪系统。