Superpowers 问题排查终极指南：5 类高频故障从安装报错到子代理循环一次定位

Superpowers 问题排查终极指南5 类高频故障从安装报错到子代理循环一次定位【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 是 Claude Code 的技能库插件装好之后你的编码代理会自动带上头脑风暴、TDD、代码审查这一整套开发方法论。第一次上手的人最常卡在两处——安装命令直接报错或者会话起来后技能列表一片空白。这篇 Superpowers 问题排查指南按「你实际看到的报错」来组织5 个高频故障逐一给出定位步骤照着做基本都能恢复。✅ 开工前的 30 秒自查清单在动手改任何东西之前先确认这 4 件事能排除一半以上的低级故障你在哪个代理平台上用Claude Code、OpenCode、Codex、Cursor 各自的安装路径不同别把 A 平台的命令贴到 B 平台。插件市场注册了吗插件市场可以理解为插件的「仓库地址」superpowers-marketplace这个市场没注册安装命令必然找不到目标。你的终端是什么Windows 下 cmd.exe、PowerShell、Git Bash 对引号和路径的解析规则各不相同很多 Windows 安装报错源于此。你用的是最新版吗拉一下仓库最新的提交Bad substitution、Plugin hook error这些坑都已在后续版本修掉。 按你看到的报错对号入座终端弹出Plugin not found现象安装命令一执行立刻返回Plugin not found。原因你只跑了安装命令但没先注册superpowers-marketplace这个插件市场——安装命令里的superpowers-marketplace后缀指的就是市场名市场不存在时自然查无此插件。解决步骤注册市场运行/plugin marketplace add obra/superpowers-marketplace再运行安装命令/plugin install superpowerssuperpowers-marketplace如果你不想用自建市场可以改走官方市场/plugin install superpowersclaude-plugins-official验证重启会话后列出已装插件应能看到 Superpowers/plugin listUbuntu/Debian 上炸出Bad substitution现象会话启动时/bin/sh直接吐出Bad substitution技能上下文没加载。原因Ubuntu/Debian 的/bin/sh实际是 dash不认识${BASH_SOURCE[0]}这类 bash 专属语法旧版 Superpowers 的钩子脚本会话启动时自动运行的小程序负责给代理注入技能上下文用了这种写法。新版已把脚本改成 POSIX 兼容语法dash 下不再报错。解决步骤更新 Superpowers 到最新版本无法立即更新时手动用 bash 执行钩子绕过 dashbash hooks/session-start自己维护脚本时把 bash 专属语法换成 POSIX 写法验证用 sh 直接跑一遍钩子无报错即恢复sh hooks/session-start报Plugin hook error技能加载失败现象会话启动弹出Plugin hook error之后 agent 完全不调用 brainstorming 等任何技能。原因session-start 钩子失败会导致整套技能上下文丢失表现就是「技能加载失败」。旧版本在插件执行环境里BASH_SOURCE未定义时脚本静默挂掉v2.0.1 已修复另外要确认技能仓库是否完整克隆到了~/.config/superpowers/skills/。解决步骤更新 Superpowers 到最新版本在项目根目录手动执行bash hooks/session-start观察输出里有没有路径错误检查技能目录是否完整缺失则删除该目录重新触发克隆验证列出技能目录应看到一批技能子目录ls ~/.config/superpowers/skills/Windows 上装完钩子不生效现象Windows 下装完一切正常但会话启动时钩子没跑或 PowerShell 里冒出解析错误。原因两个常见触发点——CRLF 换行符让 shell 脚本解析失败项目已用.gitattributes强制 LF 行结束符解决以及钩子命令的引号写法被 cmd.exe / PowerShell 各自误解。新版把钩子声明为shell: bash让 Claude Code 直接走 Git Bash 执行绕开两种原生 shell 的差异。解决步骤确认已安装 Git for Windows提供 Git Bash未装先装更新到最新版本让钩子走 Git Bash 路径若你的项目路径含(、空格等字符把项目挪到干净路径再试验证手动跑一次钩子应静默完成、无任何报错bash hooks/session-start子代理审查后实施者反复改同一处现象审查者提问题实施者子代理修复后再审又被拒同一块代码来回改。原因这是 subagent-driven-development 技能里的修复循环在跑前 3 轮复用原实施者第 4~5 轮自动换新模型重新实施5 轮是上限。若 5 轮后仍未收敛通常是规范审查者判定了「实施者解决的是错误的问题」——继续改代码没有意义问题出在需求定义本身。解决步骤停止当前任务调出审查者的规范结论与计划原文逐条比对确认实施方向与规范一致后再重新分发任务若审查结论与计划文本冲突停下来问人哪边为准不要让代理自行裁决验证查看该计划的进度台账每个任务都应有明确的完成或修复轮次记录cat .superpowers/sdd/*/progress.md 从旧版本迁移过来要注意什么旧安装的行为现在的行为手动把技能目录拷到各平台配置路径技能自动克隆到~/.config/superpowers/skills/由初始化脚本统一管理OpenCode 的技能符号链接符号链接一个指向真实文件的快捷方式避免拷贝两份代码指向旧路径统一符号链接到~/.config/opencode/skills/superpowers/靠setup-personal-superpowers钩子做个人技能初始化该钩子已废弃由initialize-skills.sh脚本取代迁移前要自己备份旧技能下次会话启动时自动备份旧安装再自动克隆全新技能仓库有个人技能的话迁移前按 RELEASE-NOTES.md 的升级说明先备份迁移后复制回本地技能仓库提交即可。 验证清单 还没解决怎么办跑一遍下面的脚本确认安装和功能都在线tests/claude-code/run-skill-tests.sh批量跑 Claude Code 下的技能测试tests/opencode/test-plugin-loading.sh校验 OpenCode 插件是否装对、目录结构是否完整tests/claude-code/test-sdd-workspace.sh验证子代理驱动开发的工作区脚本想在不污染真实配置的前提下验证可以加载隔离环境——它会用临时目录冒充 HOMEsource tests/opencode/setup.sh上面都试过还有问题先翻 docs/ 目录里的平台文档如 README.opencode.md再去项目的 issue 区搜一下是否有人踩过或者直接对代理说「用 systematic-debugging 排查这个问题」让它按四阶段流程做根因分析。【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考