Superpowers故障排查实战指南：从问题定位到预防措施

一、环境适配类问题

H2: 终端显示"Plugin not found"错误

典型症状

执行插件安装命令后，系统返回"Plugin not found"错误提示，无法完成Superpowers插件的安装流程。

根本原因

1. 插件市场配置未正确指向Superpowers官方仓库
2. 网络连接问题导致无法访问插件市场
3. 命令语法错误或版本号指定不正确

解决步骤

1. 🔍 检查当前插件市场配置

   # 查看当前插件源配置
   /plugin list-sources
   

2. 验证Superpowers插件源是否已添加

   # 添加官方插件源（如尚未添加）
   /plugin add-source superpowers-marketplace https://gitcode.com/GitHub_Trending/su/superpowers
   

3. 执行正确的安装命令

   # 完整的插件安装命令
   /plugin install superpowers@superpowers-marketplace
   

相关资源

问题排查工具：tests/opencode/test-plugin-loading.sh
官方安装文档：README.md

H2: Windows系统出现CRLF行结束符警告

典型症状

在Windows系统中执行脚本时，出现"warning: LF will be replaced by CRLF"或脚本执行格式错误。

根本原因

Windows系统默认使用CRLF作为行结束符，而Superpowers项目采用LF行结束符标准，导致跨平台兼容性问题。

解决步骤

1. 🔍 检查Git配置中的行结束符设置

   # 查看当前Git行结束符配置
   git config --global core.autocrlf
   

2. 配置Git自动转换行结束符

   # 为Windows系统设置正确的行结束符转换规则
   git config --global core.autocrlf true
   

3. 重新克隆仓库以应用正确的行结束符

   # 克隆项目仓库
   git clone https://gitcode.com/GitHub_Trending/su/superpowers
   

相关资源

版本说明文档：RELEASE-NOTES.md
Windows安装指南：docs/windows/polyglot-hooks.md

二、执行流程类问题

H2: "Plugin hook error"启动失败

典型症状

Superpowers启动时显示"Plugin hook error"错误，技能上下文无法加载，核心功能不可用。

根本原因

session-start钩子脚本执行失败，导致技能初始化流程中断，通常与环境变量配置或脚本权限有关。

解决步骤

1. 🔍 检查钩子脚本执行权限

   # 验证脚本权限
   ls -l hooks/session-start.sh
   

2. 手动执行钩子脚本并观察错误输出

   # 直接运行钩子脚本进行调试
   bash -x hooks/session-start.sh
   

3. 更新Superpowers到修复此问题的版本

   # 更新到最新版本
   /plugin update superpowers
   

相关资源

钩子脚本源码：hooks/session-start.sh
问题修复记录：RELEASE-NOTES.md

H2: Ubuntu系统出现"Bad substitution"错误

典型症状

在Ubuntu或Debian系统上执行脚本时，出现"/bin/sh: 1: Bad substitution"错误提示。

根本原因

Ubuntu/Debian系统默认将/bin/sh符号链接到dash shell，而脚本中使用了bash特定的语法特性。

解决步骤

1. 🔍 检查当前默认shell

   # 查看sh的实际指向
   ls -l /bin/sh
   

2. 显式使用bash执行脚本

   # 使用bash执行而非默认sh
   bash hooks/session-start.sh
   

3. 永久解决方法：将脚本shebang修改为明确指定bash

   # 修改脚本首行
   sed -i 's/^#!/#!/bin/bash/' hooks/session-start.sh
   

相关资源

问题修复记录：RELEASE-NOTES.md
测试脚本：tests/opencode/test-skills-core.sh

三、子代理开发模式问题

H2: 代码审查循环无法正常结束

典型症状

在子代理驱动开发过程中，代码审查反复发现相同问题，实施者修复后审查者仍报告相同问题。

根本原因

1. 实施者未正确理解审查意见
2. 修复方案未完全解决根本问题
3. 缺乏明确的审查通过标准

解决步骤

1. 🔍 检查审查反馈与修复记录

   # 查看审查历史记录
   cat skills/subagent-driven-development/code-quality-reviewer-prompt.md
   

2. 实施者与审查者建立明确的修复标准

   # 创建审查检查清单
   touch review-checklist.md
   

3. 执行完整的审查循环验证

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

相关资源

子代理开发指南：skills/subagent-driven-development/SKILL.md
审查者提示：skills/subagent-driven-development/spec-reviewer-prompt.md

H2: 规范审查发现"解决了错误的问题"

典型症状

规范审查者报告实施者开发的功能与原始需求不符，解决了错误的问题。

根本原因

1. 需求理解存在偏差
2. 开发前未充分确认需求细节
3. 缺乏规范的需求文档和验收标准

解决步骤

1. 🔍 停止当前开发任务，重新审查需求文档

   # 查看项目需求文档
   cat docs/plans/2025-11-22-opencode-support-design.md
   

2. 与需求方确认核心功能点

   # 创建需求确认文档
   touch requirements-confirmation.md
   

3. 按照正确的问题定义重新规划开发

   # 生成新的开发计划
   skills/writing-plans/SKILL.md
   

相关资源

设计文档：docs/plans/2025-11-22-opencode-support-design.md
实施指南：docs/plans/2025-11-22-opencode-support-implementation.md

四、预防措施与最佳实践

H2: 环境一致性保障

典型症状

在不同环境中表现不一致，本地工作正常但部署环境出现错误。

根本原因

开发环境与生产环境配置差异，依赖版本不一致，系统环境变量设置不同。

解决步骤

1. 🔍 使用项目提供的环境设置脚本

   # 初始化标准测试环境
   source tests/opencode/setup.sh
   

2. 运行完整的环境兼容性测试

   # 执行环境测试套件
   tests/opencode/run-tests.sh
   

3. 创建环境配置清单

   # 生成环境配置报告
   env > environment-checklist.txt
   

相关资源

环境设置脚本：tests/opencode/setup.sh
测试套件：tests/

H2: 版本迁移风险控制

典型症状

升级Superpowers版本后出现功能异常或数据丢失。

根本原因

1. 旧版本数据格式与新版本不兼容
2. 配置文件格式发生变化
3. 技能路径或依赖关系调整

解决步骤

1. 🔍 备份当前安装

   # 创建配置备份
   cp -r ~/.config/superpowers ~/.config/superpowers-backup
   

2. 查阅版本迁移指南

   # 查看版本说明中的迁移部分
   grep -A 20 "迁移指南" RELEASE-NOTES.md
   

3. 执行版本兼容性测试

   # 运行跨版本测试
   tests/claude-code/run-skill-tests.sh
   

相关资源

版本说明：RELEASE-NOTES.md
技能迁移工具：lib/skills-core.js

附录：跨版本兼容对照表

功能/组件	v1.x	v2.x	v3.x	迁移注意事项
技能路径	~/.superpowers/skills	~/.config/opencode/skills	~/.config/superpowers/skills	需要手动迁移技能文件
钩子系统	custom-hooks/	hooks/	hooks/	钩子脚本格式兼容，但需检查路径
配置文件	config.json	config.yaml	config.yaml	JSON格式需手动转换为YAML
插件系统	内置	模块化	市场集成	需重新安装所有插件
子代理功能	实验性	稳定	增强版	旧版子代理脚本需要更新

五、问题排查流程总结

当遇到Superpowers相关问题时，建议按照以下流程进行排查：

1. 确认环境：检查系统兼容性、依赖项和权限设置
2. 复现问题：记录详细的错误信息和复现步骤
3. 查阅文档：检查RELEASE-NOTES和相关技能文档
4. 运行测试：使用项目提供的测试脚本验证功能
5. 逐步排查：从简单原因开始排查，如网络、路径、权限等
6. 寻求支持：若问题持续，使用内置问题解决技能或提交issue

相关资源：问题解决技能：skills/systematic-debugging/SKILL.md