Superpowers技术故障排除指南：从问题诊断到预防策略

问题检索指引

使用以下关键词快速定位相关解决方案：

• 安装失败、Plugin not found → 环境配置故障排除
• CRLF、终端兼容性 → 跨平台兼容性调整
• 旧版本迁移、符号链接 → 版本迁移问题
• Plugin hook error、session-start → 钩子执行失败
• Bad substitution、dash → Shell环境兼容性
• 技能未找到、test-plugin-loading → 技能加载异常
• 代码审查循环、实施者修复 → 子代理开发模式

环境配置故障排除

故障特征描述

• 安装命令执行后无响应或提示"Plugin not found"
• 插件市场连接超时或认证失败
• 安装进度停滞在特定百分比

诊断步骤

1. 验证网络连接状态
2. 检查插件市场配置有效性
3. 确认当前用户权限级别
4. 验证目标安装路径可写性

解决方案实施

基础解决步骤

# 标准安装命令 (Claude Code用户)
/plugin install superpowers@superpowers-marketplace

# 手动安装命令 (Codex/OpenCode用户)
git clone https://gitcode.com/GitHub_Trending/su/superpowers ~/.config/superpowers
cd ~/.config/superpowers
chmod +x setup.sh
./setup.sh --install

高级优化选项

# 自定义安装路径
./setup.sh --prefix /opt/superpowers

# 安装特定版本
git checkout v1.2.3 && ./setup.sh --install

# 启用调试模式安装
DEBUG=1 ./setup.sh --install

[!TIP] 安装过程中遇到网络问题时，可使用代理服务器： http_proxy=http://proxy:port ./setup.sh --install

根本原因分析

插件安装失败通常源于三个核心问题：网络连接问题、权限不足或市场配置错误。当市场配置正确但仍无法安装时，手动克隆仓库通常能绕过市场访问限制。

预防策略建议

• 定期更新插件市场配置信息
• 创建安装日志监控：./setup.sh --install > install.log 2>&1
• 设置定时检查机制验证插件完整性
• 维护离线安装包作为备用方案

相关资源

• 安装脚本源码：setup.sh
• 插件加载测试工具：test-plugin-loading.sh

跨平台兼容性调整

故障特征描述

• Windows系统执行脚本时出现"行结束符"错误
• 命令在一种终端正常执行，在另一种终端失败
• 脚本执行过程中出现语法错误但脚本未修改

诊断步骤

1. 确认操作系统版本和终端类型
2. 检查文件行结束符格式
3. 验证脚本解释器兼容性
4. 测试基础命令执行情况

解决方案实施

基础解决步骤

# 检查并转换行结束符 (Windows Git Bash)
dos2unix hooks/session-start

# 验证脚本解释器
head -n 1 hooks/session-start  # 应显示 #!/bin/bash

# 确保执行权限
chmod +x hooks/session-start

高级优化选项

# 在Windows上使用WSL执行
wsl ~/.config/superpowers/hooks/session-start

# 为不同终端创建别名
alias superpowers='bash ~/.config/superpowers/hooks/session-start'

# 强制使用bash执行所有脚本
find . -name "*.sh" -exec sed -i 's|#!/bin/sh|#!/bin/bash|g' {} \;

[!WARNING] 在Ubuntu/Debian系统上，/bin/sh默认指向dash而非bash，可能导致"Bad substitution"错误。解决方法：sudo dpkg-reconfigure dash选择"No"。

根本原因分析

Windows和Unix系统的行结束符差异(CRLF vs LF)是跨平台问题的主要根源。此外，不同终端对环境变量和命令解析的差异也会导致执行行为不一致。

预防策略建议

• 使用.gitattributes文件强制统一行结束符
• 在脚本开头明确指定解释器：#!/bin/bash而非#!/bin/sh
• 为不同平台创建专用启动脚本
• 将平台兼容性检查添加到启动流程

相关资源

• Windows安装指南：docs/windows/polyglot-hooks.md
• 发布说明：RELEASE-NOTES.md

版本迁移问题

故障特征描述

• 升级后技能无法加载
• 配置文件冲突导致启动失败
• 旧版本数据无法访问

诊断步骤

1. 确认当前安装版本和目标版本
2. 检查符号链接状态
3. 验证配置文件兼容性
4. 检查备份文件完整性

解决方案实施

基础解决步骤

# 创建旧版本备份
mv ~/.config/superpowers ~/.config/superpowers_backup_$(date +%Y%m%d)

# 克隆新版本
git clone https://gitcode.com/GitHub_Trending/su/superpowers ~/.config/superpowers

# 设置正确的符号链接
ln -s ~/.config/superpowers/skills ~/.config/opencode/skills/superpowers

高级优化选项

# 增量迁移配置
rsync -av --exclude='*.log' --exclude='*.tmp' ~/.config/superpowers_backup_20231015/config/ ~/.config/superpowers/config/

# 迁移验证
./tests/opencode/test-skills-core.sh --validate-migration

[!TIP] 版本迁移前，使用./tests/opencode/run-tests.sh执行完整测试套件，确保迁移环境兼容性。

根本原因分析

版本迁移问题通常源于配置文件格式变化、技能路径调整或依赖关系更新。setup-personal-superpowers钩子被initialize-skills.sh取代就是一个典型的接口变更案例。

预防策略建议

• 建立版本迁移检查清单
• 实施自动化迁移测试
• 使用版本控制系统跟踪配置变更
• 维护详细的版本间变更日志

相关资源

• 迁移指南：RELEASE-NOTES.md
• 核心技能测试：test-skills-core.sh

钩子执行失败

故障特征描述

• 启动时出现"Plugin hook error"
• 技能上下文无法加载
• session-start脚本执行失败

诊断步骤

1. 检查钩子脚本执行权限
2. 验证脚本依赖是否安装
3. 执行钩子脚本排查错误输出
4. 检查日志文件获取详细信息

解决方案实施

基础解决步骤

# 手动执行钩子脚本
hooks/session-start

# 检查执行权限
chmod +x hooks/session-start

# 查看错误日志
tail -n 50 ~/.config/superpowers/logs/hook-errors.log

高级优化选项

# 调试模式执行钩子
DEBUG=1 hooks/session-start

# 检查钩子依赖
bash -n hooks/session-start  # 语法检查
ldd hooks/session-start      # 动态依赖检查

# 重置钩子配置
cp hooks/session-start.example hooks/session-start

[!WARNING] 钩子执行失败会导致技能上下文无法正确加载，进而影响所有依赖技能的功能。

根本原因分析

钩子执行失败通常是由于权限不足、依赖缺失或脚本语法错误导致。session-start钩子负责初始化技能环境，其执行失败会导致连锁反应。

预防策略建议

• 实施钩子执行前验证机制
• 添加钩子依赖自动安装逻辑
• 建立钩子执行状态监控
• 维护钩子脚本的版本控制

相关资源

• 钩子脚本：hooks/session-start
• 测试工具：test-tools.sh

技能加载异常

故障特征描述

• 系统提示"技能未找到"
• 部分功能模块无法使用
• 技能列表显示不完整

诊断步骤

1. 检查技能目录结构完整性
2. 验证技能配置文件格式
3. 执行插件加载测试
4. 检查技能路径环境变量

解决方案实施

基础解决步骤

# 运行技能加载测试
tests/opencode/test-plugin-loading.sh

# 验证技能路径配置
echo $SUPERPOWERS_SKILLS_PATH

# 重新加载技能
/plugin reload superpowers

高级优化选项

# 详细技能加载诊断
SUPERPOWERS_DEBUG=1 tests/opencode/test-plugin-loading.sh

# 检查技能符号链接
ls -la ~/.config/opencode/skills/superpowers

# 手动注册技能
node lib/skills-core.js --register-all

[!TIP] 最新版本会自动将技能克隆到~/.config/superpowers/skills/，如果自定义路径，需确保设置正确的SUPERPOWERS_SKILLS_PATH环境变量。

根本原因分析

技能加载异常通常是由于路径配置错误、技能元数据损坏或依赖缺失导致。test-plugin-loading.sh工具可以全面验证插件安装和结构完整性。

预防策略建议

• 定期执行技能完整性检查
• 实施技能版本控制
• 建立技能依赖管理系统
• 创建技能加载失败自动恢复机制

相关资源

• 技能测试脚本：run-skill-tests.sh
• 核心技能库：lib/skills-core.js

子代理开发模式问题

故障特征描述

• 代码审查循环无法结束
• 实施者与审查者意见冲突
• 规范理解存在偏差

诊断步骤

1. 分析审查反馈内容
2. 检查规范文档完整性
3. 评估实施与需求匹配度
4. 验证沟通机制有效性

解决方案实施

基础解决步骤

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

# 生成规范文档
skills/subagent-driven-development/spec-reviewer-prompt.md --export规范

# 重新启动审查流程
agent code-reviewer --reset

高级优化选项

# 设置审查严格度级别
export REVIEW_STRICTNESS=medium

# 启用审查日志记录
agent code-reviewer --log-detail=verbose

# 运行自动化规范验证
node tests/subagent-driven-dev/verify-spec.js

[!TIP] 当规范审查者发现实施者解决了错误的问题时，应立即停止当前任务，重新理解需求，确保开发方向正确。

根本原因分析

子代理开发模式的问题通常源于需求理解偏差或沟通机制不健全。实施者子代理与审查者子代理之间需要清晰的反馈循环和明确的规范定义。

预防策略建议

• 建立需求澄清机制
• 实施阶段性规范验证
• 开发可视化沟通工具
• 创建审查结果量化评估体系

相关资源

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

测试与验证策略

故障特征描述

• 功能工作不稳定
• 测试通过但实际使用失败
• 环境差异导致行为不一致

诊断步骤

1. 确认测试环境配置
2. 检查测试覆盖率
3. 验证测试用例有效性
4. 比较开发与生产环境差异

解决方案实施

基础解决步骤

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

# 运行核心测试套件
tests/opencode/run-tests.sh

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

高级优化选项

# 运行特定测试
tests/opencode/run-tests.sh --filter=plugin-loading

# 生成测试覆盖率报告
tests/claude-code/run-skill-tests.sh --coverage

# 执行压力测试
tests/systematic-debugging/test-pressure-3.md --run

[!WARNING] 不要在生产环境直接运行测试脚本，应始终使用setup.sh创建隔离的测试环境。

根本原因分析

测试与验证问题通常源于环境差异、测试用例不完整或验证策略不足。setup.sh脚本创建的隔离环境可以有效消除环境变量和配置差异带来的问题。

预防策略建议

• 实施持续集成测试
• 建立环境一致性检查
• 开发自动化验证工具
• 创建测试结果监控系统

相关资源

• 测试环境设置：setup.sh
• 压力测试用例：test-pressure-3.md