Superpowers 问题排查指南：从定位到解决的系统方法

一、插件安装失败问题

问题现象

执行插件安装命令后系统提示"Plugin not found"错误，或安装进程无响应。

排查步骤

1. 确认当前使用的产品版本（Claude Code/Codex/OpenCode）
2. 检查插件市场配置是否正确指向官方源
3. 验证网络连接状态及防火墙设置

解决方案

根据产品类型选择正确的安装方式：

# Claude Code用户（内置插件系统）
通过应用内市场搜索"superpowers"并安装

# Codex和OpenCode用户（手动安装）
git clone https://gitcode.com/GitHub_Trending/su/superpowers
cd superpowers
./setup.sh

问题预防

• 定期检查插件市场配置有效性
• 安装前验证网络连通性
• 保持产品版本为最新稳定版

相关文档

README.md - 安装指南 RELEASE-NOTES.md - 版本兼容性说明

二、Windows系统兼容性问题

问题现象

Windows系统下脚本执行失败，或出现文件格式相关错误提示。

排查步骤

1. 检查文件行结束符是否为LF格式
2. 确认使用的终端类型（cmd.exe/PowerShell/Git Bash）
3. 验证脚本执行权限设置

解决方案

# 手动转换行结束符（Git Bash环境）
find . -type f -exec dos2unix {} \;

# 执行对应终端的安装脚本
# cmd.exe用户
hooks\run-hook.cmd

# PowerShell用户
.\hooks\run-hook.cmd

# Git Bash用户
./hooks/session-start.sh

问题预防

• 使用Git配置自动转换行结束符
• 根据终端类型选择正确的执行命令
• 参考Windows专用安装文档

相关文档

RELEASE-NOTES.md - Windows平台支持说明 docs/windows/polyglot-hooks.md - 多终端适配指南

三、技能加载失败问题

问题现象

系统提示"技能未找到"或相关功能无法激活。

排查步骤

1. 检查技能安装路径是否正确
2. 运行插件加载测试脚本验证安装完整性
3. 查看日志文件定位具体错误信息

解决方案

# 验证插件安装和结构
tests/opencode/test-plugin-loading.sh

# 手动设置技能路径（如需要）
ln -s /path/to/superpowers/skills ~/.config/opencode/skills/superpowers

# 重启技能服务
hooks/session-start.sh

问题预防

• 安装后运行自动验证脚本
• 保持技能目录结构完整
• 升级前备份自定义配置

相关文档

tests/opencode/test-plugin-loading.sh - 插件验证工具 RELEASE-NOTES.md - 技能路径配置说明

四、子代理开发模式异常

问题现象

子代理代码审查循环异常或规范审查发现重大偏差。

排查步骤

1. 检查实施者与审查者子代理配置
2. 验证需求文档与实现代码的一致性
3. 查看子代理通信日志

解决方案

# 运行子代理驱动开发测试
tests/subagent-driven-dev/run-test.sh

# 重置子代理状态
rm -rf ~/.cache/superpowers/subagents/*
hooks/session-start.sh

当规范审查发现方向偏差时：

1. 终止当前开发任务
2. 重新同步需求理解
3. 基于正确问题定义重启开发流程

问题预防

• 开发前确认需求文档准确性
• 定期运行子代理集成测试
• 保持子代理配置文件最新

相关文档

skills/subagent-driven-development/SKILL.md - 子代理开发指南 skills/subagent-driven-development/spec-reviewer-prompt.md - 规范审查标准

五、环境配置验证与测试

问题现象

功能间歇性故障或测试通过率低。

排查步骤

1. 运行环境验证脚本检查依赖完整性
2. 执行全套功能测试确认系统状态
3. 对比测试结果与预期输出

解决方案

# 设置隔离测试环境
source tests/opencode/setup.sh

# 运行核心技能测试
tests/opencode/test-skills-core.sh

# 执行完整技能测试套件
tests/claude-code/run-skill-tests.sh

问题预防

• 每次更新后执行完整测试套件
• 使用隔离环境进行功能验证
• 记录测试结果用于问题追踪

相关文档

tests/opencode/setup.sh - 测试环境配置 tests/claude-code/run-skill-tests.sh - 技能测试套件

六、获取进一步帮助

当遇到本指南未涵盖的问题时，可通过以下途径获取支持：

1. 查阅详细文档：docs/目录包含完整使用指南
2. 运行内置问题解决技能：通过Superpowers命令面板启动
3. 提交issue：使用项目issue跟踪系统报告问题

定期查阅RELEASE-NOTES.md获取最新功能更新和已知问题修复信息，保持系统处于最佳运行状态。