Superpowers技术故障排除指南

一、安装故障排除（完成度：1/4，预计阅读时间：5分钟）

1.1 "Plugin not found"错误

问题现象：执行插件安装命令后，系统返回"Plugin not found"错误提示。

排查流程： 🔍 检查插件市场配置是否正确 🔍 确认网络连接状态 🔍 验证插件名称和版本号是否正确

分场景解决方案：

🛠️ Claude Code用户：

/plugin install superpowers@superpowers-marketplace  # 使用官方市场源安装

🛠️ Codex和OpenCode用户：

git clone https://gitcode.com/GitHub_Trending/su/superpowers  # 克隆官方仓库
cd superpowers
./install.sh  # 运行安装脚本

用户常见误区：使用第三方市场源安装导致插件找不到，应始终优先使用官方市场源。

长效优化建议： 📌 定期执行/plugin update命令保持插件列表最新 📌 将插件市场配置备份到~/.config/superpowers/marketplace.json

验证步骤：执行/plugin list命令，确认superpowers已在已安装插件列表中。

二、钩子执行故障排除（完成度：2/4，预计阅读时间：6分钟）

2.1 "Plugin hook error"错误

问题现象：启动Superpowers时出现"Plugin hook error"，技能上下文无法加载。

排查流程： 🔍 检查session-start钩子文件权限 🔍 查看钩子执行日志 🔍 验证技能目录结构是否完整

分场景解决方案：

🛠️ 所有用户通用修复：

chmod +x hooks/session-start  # 确保钩子文件可执行
./hooks/session-start  # 手动执行钩子验证

🛠️ Linux/macOS用户：

sed -i 's/\r$//' hooks/session-start  # 修复可能的换行符问题

用户常见误区：忽略钩子执行失败的警告信息，导致后续功能异常。

长效优化建议： 📌 添加钩子执行状态检查到启动脚本 📌 设置钩子执行日志自动归档到logs/hooks/目录

验证步骤：重启Superpowers后，检查日志文件logs/session-start.log确认无错误信息。

三、子代理开发模式故障排除（完成度：3/4，预计阅读时间：7分钟）

3.1 代码审查循环异常

问题现象：子代理开发过程中，代码审查反复出现相同问题，无法进入下一阶段。

排查流程： 🔍 检查实施者与审查者的通信日志 🔍 验证规范文档是否清晰明确 🔍 确认质量检查标准是否一致

分场景解决方案：

🛠️ 规范理解偏差：

# 重新生成规范文档
./scripts/generate-spec.sh --update  # 更新规范文档到最新版本

🛠️ 实施者配置问题：

# 重置实施者子代理配置
cp config/implementer.default.json config/implementer.json

用户常见误区：过度依赖自动化审查，忽视人工复核重要环节。

长效优化建议： 📌 建立审查问题分类库，持续优化自动化规则 📌 定期同步更新实施者与审查者的标准库

验证步骤：运行./tests/subagent-driven-dev/run-test.sh验证修复效果。

四、社区支持资源导航（完成度：4/4，预计阅读时间：3分钟）

4.1 官方文档资源

• 安装指南：docs/installation.md
• 技能开发手册：docs/skills/development.md
• API参考：docs/api/index.md

4.2 测试与验证工具

• 技能测试套件：tests/claude-code/run-skill-tests.sh
• 环境验证脚本：tests/opencode/setup.sh
• 插件加载测试：tests/opencode/test-plugin-loading.sh

4.3 社区支持渠道

• 问题跟踪系统：提交issue到项目仓库
• 技能支持：使用Superpowers内置的问题解决技能
• 社区论坛：通过项目讨论区交流经验

术语速查：

• 钩子(Hook)：在特定事件触发时执行的脚本，用于扩展功能
• 子代理(Subagent)：负责特定任务的AI代理，如代码审查者、实施者等
• 技能(Skill)：Superpowers的功能模块，提供特定开发辅助能力