Superpowers故障速查：高效解决开发障碍的7个实战解决方案

01.跨平台安装差异：系统适配指南

现象：安装命令执行失败
🔍 排查步骤：

1. 确认使用的AI开发工具类型（Claude Code/Codex/OpenCode）
2. 检查插件市场配置是否正确

🛠️ 解决方案：

• Claude Code用户：通过内置插件市场直接安装
• Codex/OpenCode用户：执行手动安装命令

/plugin install superpowers@superpowers-marketplace

📌 相关文档：README.md

02.Windows系统兼容问题：环境配置指南

现象：脚本执行格式错误
🔍 排查步骤：

1. 检查文件行结束符是否为LF格式
2. 确认使用的终端类型（cmd.exe/PowerShell/Git Bash）

🛠️ 解决方案：
系统已通过.gitattributes文件强制使用LF行结束符，不同终端的安装指南可参考发布说明文档

📌 相关文档：RELEASE-NOTES.md

03.旧版本迁移问题：数据平滑过渡方案

现象：技能无法加载或配置丢失
🔍 排查步骤：

1. 检查技能是否正确符号链接（Symbolic Link，一种文件系统链接）到目标目录
2. 确认旧版本备份是否自动创建

🛠️ 解决方案：

1. 创建技能符号链接

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

2. 新版本已自动备份旧安装并使用initialize-skills.sh替代setup-personal-superpowers钩子

📌 相关文档：RELEASE-NOTES.md

04.钩子执行失败：技能上下文加载问题

现象："Plugin hook error"错误提示
🔍 排查步骤：

1. 检查session-start钩子文件是否存在
2. 验证钩子文件权限是否正确

🛠️ 解决方案：

1. 更新Superpowers到最新版本
2. 手动执行钩子脚本

hooks/session-start.sh

📌 相关文档：RELEASE-NOTES.md

05."Bad substitution"错误：Shell兼容性问题

现象：Ubuntu/Debian系统执行脚本时报错
🔍 排查步骤：

1. 确认系统默认shell是否为dash
2. 检查脚本中是否使用了bash特定语法

🛠️ 解决方案：
已在更新版本中修复，确保使用最新版本或显式指定bash执行脚本

bash hooks/session-start.sh

📌 相关文档：RELEASE-NOTES.md

06.技能未找到：插件加载验证方案

现象：系统提示"技能不存在"
🔍 排查步骤：

1. 运行插件加载测试脚本验证安装
2. 检查技能路径是否正确

🛠️ 解决方案：

1. 执行插件加载测试

tests/opencode/test-plugin-loading.sh

2. 确认技能已克隆到正确目录：~/.config/superpowers/skills/

📌 相关文档：test-plugin-loading.sh

07.子代理开发模式问题：代码质量控制方案

现象：代码审查发现质量问题
🔍 排查步骤：

1. 检查实施者子代理是否正确响应审查意见
2. 确认审查循环机制是否正常工作

🛠️ 解决方案：
实施者子代理会自动修复质量问题，并进入审查循环，直至问题解决。如遇规范理解偏差：

1. 停止当前任务
2. 重新理解需求
3. 按照正确问题定义开发

📌 相关文档：SKILL.md、spec-reviewer-prompt.md

问题预防：关键注意事项

1. 保持版本更新
   定期更新Superpowers到最新版本，以获取错误修复和功能改进。

2. 环境验证
   在部署前运行测试环境验证脚本：

source tests/opencode/setup.sh

3. 测试套件执行
   定期运行完整测试套件确保系统功能正常：

tests/claude-code/run-skill-tests.sh
tests/opencode/test-skills-core.sh

4. 文档查阅
   遇到问题先查阅项目文档：docs/目录包含完整使用指南。

5. 使用内置支持
   利用Superpowers内置的问题解决技能获取实时帮助。