Superpowers技术工具问题排查指南

新手常见误区

误区一：忽略平台差异

很多新手在安装Superpowers时直接照搬教程命令，没有注意不同平台的安装差异。这会导致安装失败或功能异常。

误区二：乱改配置文件

部分用户为了"优化"工具性能，随意修改[配置目录]下的系统文件，结果导致工具无法启动。

误区三：跳过环境验证

安装完成后不运行验证命令，直接开始使用，遇到问题时难以判断是安装问题还是使用问题。

误区四：忽视版本兼容性

在旧版本系统上安装最新版Superpowers，或在新版本系统上使用过时的安装方法。

误区五：技能安装路径错误

手动指定技能安装路径时，没有遵循工具的目录结构规范，导致技能无法加载。

安装问题场景

场景一：插件安装提示"Plugin not found"

graph TD
    A[执行安装命令] --> B{插件市场配置正确?}
    B -->|是| C[安装成功]
    B -->|否| D[显示"Plugin not found"错误]
    D --> E[检查市场配置]
    E --> F[重新执行安装命令]
    F --> C

🔧 解决方案：

1. 症状识别：执行安装命令后立即显示"Plugin not found"错误
2. 原因分析：插件市场配置不正确或网络连接问题
3. 操作步骤：

/plugin market list  # 查看已配置的插件市场
/plugin market add superpowers-marketplace https://gitcode.com/GitHub_Trending/su/superpowers  # 添加正确的市场
/plugin install superpowers@superpowers-marketplace  # 重新安装

4. 验证方法：运行/plugin list命令，检查superpowers是否出现在已安装插件列表中

⚠️ 预防措施：安装前先运行/plugin market list确认市场配置正确，网络环境稳定

场景二：Windows系统安装后脚本无法执行

graph TD
    A[Windows系统安装完成] --> B[运行初始化脚本]
    B --> C{脚本执行失败?}
    C -->|否| D[使用工具]
    C -->|是| E[检查行结束符]
    E --> F[转换为LF格式]
    F --> B

🔧 解决方案：

1. 症状识别：Windows系统中执行.sh脚本时提示语法错误或无法识别命令
2. 原因分析：Windows默认使用CRLF行结束符，与Unix系统的LF格式不兼容
3. 操作步骤：

# 使用Git Bash执行以下命令
cd [hooks目录]
dos2unix session-start.sh  # 将CRLF转换为LF格式
chmod +x session-start.sh  # 添加执行权限
./session-start.sh  # 重新执行脚本

4. 验证方法：脚本成功执行且无错误提示，工具正常启动

⚠️ 预防措施：Windows用户应始终使用Git Bash或WSL环境运行shell脚本，避免使用cmd.exe

场景三：旧版本迁移后技能丢失

graph TD
    A[从旧版本迁移] --> B[启动Superpowers]
    B --> C{技能列表为空?}
    C -->|否| D[使用工具]
    C -->|是| E[检查技能符号链接]
    E --> F[重新创建符号链接]
    F --> B

🔧 解决方案：

1. 症状识别：迁移后启动工具，发现之前安装的技能全部丢失
2. 原因分析：新版本使用了不同的技能存储路径，旧版本的技能没有正确迁移
3. 操作步骤：

# 创建符号链接（类似快捷方式）将旧技能目录链接到新路径
ln -s ~/.superpowers/skills ~/.config/opencode/skills/superpowers
# 验证链接是否创建成功
ls -l ~/.config/opencode/skills/

4. 验证方法：在工具中运行/skills list命令，确认技能已恢复

⚠️ 预防措施：升级前先备份技能目录，阅读[RELEASE-NOTES.md]了解版本变更内容

场景四：Ubuntu系统提示"Bad substitution"错误

graph TD
    A[执行脚本] --> B{出现"Bad substitution"错误?}
    B -->|否| C[继续操作]
    B -->|是| D[检查shell类型]
    D --> E[切换到bash]
    E --> A

🔧 解决方案：

1. 症状识别：在Ubuntu/Debian系统执行脚本时出现"Bad substitution"错误
2. 原因分析：系统默认shell是dash，不支持某些bash特性
3. 操作步骤：

# 检查当前shell
echo $0
# 如果输出不是bash，运行以下命令切换
bash
# 再次执行脚本
./hooks/session-start.sh

4. 验证方法：脚本能够正常执行，无错误提示

⚠️ 预防措施：在脚本开头添加#!/bin/bash明确指定使用bash解释器

场景五：安装后无法找到核心技能

graph TD
    A[安装完成] --> B[使用技能命令]
    B --> C{提示"技能未找到"?}
    C -->|否| D[正常使用]
    C -->|是| E[运行技能测试脚本]
    E --> F{测试通过?}
    F -->|是| G[检查命令拼写]
    F -->|否| H[重新安装技能]
    H --> B

🔧 解决方案：

1. 症状识别：执行技能命令时提示"技能未找到"或"command not found"
2. 原因分析：技能安装不完整或路径配置错误
3. 操作步骤：

# 运行技能测试脚本
tests/opencode/test-plugin-loading.sh
# 如果测试失败，重新安装核心技能
/plugin install superpowers-core@superpowers-marketplace

4. 验证方法：测试脚本输出"All tests passed"，技能命令可以正常执行

⚠️ 预防措施：安装完成后立即运行[tests/opencode/test-plugin-loading.sh]验证安装完整性

使用问题场景

场景一：钩子执行失败导致技能加载异常

graph TD
    A[启动Superpowers] --> B{技能无法使用?}
    B -->|否| C[正常使用]
    B -->|是| D[检查钩子执行日志]
    D --> E{钩子执行失败?}
    E -->|是| F[手动执行钩子脚本]
    F --> C
    E -->|否| G[其他问题排查]

🔧 解决方案：

1. 症状识别：工具启动后所有技能都无法使用，或提示"技能上下文未加载"
2. 原因分析：session-start钩子执行失败，导致技能上下文无法正确加载
3. 操作步骤：

# 查看钩子执行日志
cat [日志文件] | grep "hook"
# 手动执行钩子脚本
hooks/session-start.sh
# 检查是否有错误输出

4. 验证方法：钩子脚本无错误输出，技能命令可以正常执行

⚠️ 预防措施：定期更新Superpowers到最新版本，钩子问题通常会在新版本中修复

场景二：子代理开发模式下代码审查循环问题

graph TD
    A[启动子代理开发] --> B[实施者编写代码]
    B --> C[审查者发现问题]
    C --> D[实施者修复问题]
    D --> E{问题是否解决?}
    E -->|是| F[完成开发]
    E -->|否| C

🔧 解决方案：

1. 症状识别：代码审查反复发现相同问题，陷入无限循环
2. 原因分析：实施者没有正确理解审查意见或修复不彻底
3. 操作步骤：

# 查看完整审查记录
cat [子代理日志目录]/code-review.log
# 明确问题修复要求
grep "CRITICAL" [子代理日志目录]/code-review.log
# 针对性修复后重新提交
/subagent submit --fixes "问题描述"

4. 验证方法：审查者确认问题已解决，不再提出相同意见

⚠️ 预防措施：实施者在修复前与审查者充分沟通，确保理解问题本质

场景三：规范审查发现需求理解偏差

graph TD
    A[开始开发任务] --> B[实施者编写代码]
    B --> C[规范审查]
    C --> D{发现需求理解偏差?}
    D -->|否| E[继续开发]
    D -->|是| F[停止当前任务]
    F --> G[重新理解需求]
    G --> H[调整开发方向]
    H --> B

🔧 解决方案：

1. 症状识别：规范审查者指出"解决了错误的问题"或"偏离需求目标"
2. 原因分析：开发前未充分理解需求，或需求文档存在歧义
3. 操作步骤：

# 查看规范审查意见
cat [子代理日志目录]/spec-review.log
# 重新获取并阅读需求文档
cat [文档目录]/requirements.md
# 与需求方确认理解
/chat start requirements-clarification

4. 验证方法：规范审查者确认需求理解正确，开发方向符合预期

⚠️ 预防措施：开发前执行需求确认流程，确保与需求方达成共识

场景四：技能执行超时或无响应

graph TD
    A[执行技能命令] --> B{长时间无响应?}
    B -->|否| C[获取结果]
    B -->|是| D[检查系统资源]
    D --> E{资源不足?}
    E -->|是| F[释放资源]
    E -->|否| G[检查技能日志]
    F --> A
    G --> H[重启技能服务]
    H --> A

🔧 解决方案：

1. 症状识别：执行技能命令后长时间无响应，或最终提示"超时"
2. 原因分析：系统资源不足，或技能内部出现死锁/无限循环
3. 操作步骤：

# 检查系统资源使用情况
top  # 查看CPU和内存占用
# 如果资源紧张，终止占用过高的进程
kill -9 [进程ID]
# 检查技能日志
cat [日志目录]/skill-execution.log
# 重启技能服务
/skill service restart

4. 验证方法：技能命令能够在合理时间内返回结果

⚠️ 预防措施：避免同时运行多个资源密集型技能，定期清理缓存释放资源

场景五：测试脚本执行失败

graph TD
    A[运行测试脚本] --> B{测试失败?}
    B -->|否| C[测试通过]
    B -->|是| D[查看测试报告]
    D --> E{环境问题?}
    E -->|是| F[运行环境设置脚本]
    E -->|否| G[修复代码问题]
    F --> A
    G --> A

🔧 解决方案：

1. 症状识别：运行测试脚本后显示"Test failed"或错误堆栈信息
2. 原因分析：测试环境配置不正确，或代码存在功能缺陷
3. 操作步骤：

# 运行环境设置脚本
source tests/opencode/setup.sh
# 查看详细测试报告
cat [测试报告目录]/latest.log
# 运行特定失败的测试用例
tests/opencode/run-tests.sh --specific [测试用例名称]

4. 验证方法：所有测试用例执行通过，显示"All tests passed"

⚠️ 预防措施：提交代码前先运行测试，确保本地测试通过

平台差异对比表

问题场景	Windows系统	Linux系统	macOS系统
脚本执行	需要Git Bash或WSL环境	直接执行.sh脚本	直接执行.sh脚本
路径表示	使用反斜杠\	使用正斜杠/	使用正斜杠/
权限管理	无需文件权限设置	需要chmod设置执行权限	需要chmod设置执行权限
符号链接	需要管理员权限	直接使用ln命令	直接使用ln命令
行结束符	默认CRLF，需转换为LF	默认LF，无需转换	默认LF，无需转换

高级排查技巧

日志分析方法

1. 关键日志位置

• 系统日志：[日志目录]/system.log
• 技能执行日志：[日志目录]/skill-execution.log
• 子代理通信日志：[日志目录]/subagent-communication.log
• 错误日志：[日志目录]/errors.log

2. 常用日志分析命令

# 实时查看错误日志
tail -f [日志目录]/errors.log
# 搜索特定错误
grep "ERROR" [日志目录]/system.log
# 查看最近100行日志
tail -n 100 [日志目录]/skill-execution.log
# 按时间范围筛选日志
grep "2026-02-08" [日志目录]/system.log

环境检测命令

1. 系统环境检查

# 检查系统信息
uname -a
# 检查shell版本
bash --version
# 检查网络连接
ping gitcode.com -c 4

2. 工具环境检查

# 检查Superpowers版本
/superpowers --version
# 检查已安装插件
/plugin list
# 检查技能状态
/skill status
# 验证依赖完整性
/dependency check

3. 性能监控

# 查看系统资源占用
htop
# 检查磁盘空间
df -h
# 查看内存使用
free -m
# 网络连接状态
netstat -tuln

获取帮助

如果遇到本指南未涵盖的问题，可以通过以下方式获取帮助：

1. 查阅官方文档：docs/目录包含完整的使用指南
2. 运行内置帮助命令：/help查看所有可用帮助主题
3. 使用问题解决技能：/skill run problem-solving启动交互式问题排查
4. 提交issue：通过工具内置反馈系统提交详细问题报告

通过以上方法，大多数Superpowers的安装和使用问题都能得到快速解决。如果问题持续存在，请确保你使用的是最新版本，并提供详细的错误信息以便进一步排查。