企业官网建设流程全解析

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

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers

Superpowers 是 Claude Code 的技能库插件：装好之后，你的编码代理会自动带上头脑风暴、TDD、代码审查这一整套开发方法论。第一次上手的人最常卡在两处——安装命令直接报错，或者会话起来后技能列表一片空白。这篇 Superpowers 问题排查指南按「你实际看到的报错」来组织，5 个高频故障逐一给出定位步骤，照着做基本都能恢复。

✅ 开工前的 30 秒自查清单

在动手改任何东西之前，先确认这 4 件事，能排除一半以上的低级故障：

1. 你在哪个代理平台上用？Claude Code、OpenCode、Codex、Cursor 各自的安装路径不同，别把 A 平台的命令贴到 B 平台。
2. 插件市场注册了吗？插件市场可以理解为插件的「仓库地址」，superpowers-marketplace这个市场没注册，安装命令必然找不到目标。
3. 你的终端是什么？Windows 下 cmd.exe、PowerShell、Git Bash 对引号和路径的解析规则各不相同，很多 Windows 安装报错源于此。
4. 你用的是最新版吗？拉一下仓库最新的提交；Bad substitution、Plugin hook error这些坑都已在后续版本修掉。

🎯 按你看到的报错对号入座

终端弹出Plugin not found

现象：安装命令一执行，立刻返回Plugin not found。

原因：你只跑了安装命令，但没先注册superpowers-marketplace这个插件市场——安装命令里的@superpowers-marketplace后缀指的就是市场名，市场不存在时自然查无此插件。

解决步骤：

1. 注册市场：运行/plugin marketplace add obra/superpowers-marketplace
2. 再运行安装命令/plugin install superpowers@superpowers-marketplace
3. 如果你不想用自建市场，可以改走官方市场：/plugin install superpowers@claude-plugins-official

验证：重启会话后列出已装插件，应能看到 Superpowers：

/plugin list

Ubuntu/Debian 上炸出Bad substitution

现象：会话启动时，/bin/sh直接吐出Bad substitution，技能上下文没加载。

原因：Ubuntu/Debian 的/bin/sh实际是 dash，不认识${BASH_SOURCE[0]}这类 bash 专属语法；旧版 Superpowers 的钩子脚本（会话启动时自动运行的小程序，负责给代理注入技能上下文）用了这种写法。新版已把脚本改成 POSIX 兼容语法，dash 下不再报错。

解决步骤：

1. 更新 Superpowers 到最新版本
2. 无法立即更新时，手动用 bash 执行钩子绕过 dash：bash hooks/session-start
3. 自己维护脚本时，把 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/。

解决步骤：

1. 更新 Superpowers 到最新版本
2. 在项目根目录手动执行bash hooks/session-start，观察输出里有没有路径错误
3. 检查技能目录是否完整，缺失则删除该目录重新触发克隆

验证：列出技能目录，应看到一批技能子目录：

ls ~/.config/superpowers/skills/

Windows 上装完钩子不生效

现象：Windows 下装完一切正常，但会话启动时钩子没跑，或 PowerShell 里冒出解析错误。

原因：两个常见触发点——CRLF 换行符让 shell 脚本解析失败（项目已用.gitattributes强制 LF 行结束符解决），以及钩子命令的引号写法被 cmd.exe / PowerShell 各自误解。新版把钩子声明为shell: "bash"，让 Claude Code 直接走 Git Bash 执行，绕开两种原生 shell 的差异。

解决步骤：

1. 确认已安装 Git for Windows（提供 Git Bash），未装先装
2. 更新到最新版本，让钩子走 Git Bash 路径
3. 若你的项目路径含(、空格等字符，把项目挪到干净路径再试

验证：手动跑一次钩子，应静默完成、无任何报错：

bash hooks/session-start

子代理审查后，实施者反复改同一处

现象：审查者提问题，实施者子代理修复后再审又被拒，同一块代码来回改。

原因：这是 subagent-driven-development 技能里的修复循环在跑：前 3 轮复用原实施者，第 4~5 轮自动换新模型重新实施，5 轮是上限。若 5 轮后仍未收敛，通常是规范审查者判定了「实施者解决的是错误的问题」——继续改代码没有意义，问题出在需求定义本身。

解决步骤：

1. 停止当前任务，调出审查者的规范结论与计划原文逐条比对
2. 确认实施方向与规范一致后，再重新分发任务
3. 若审查结论与计划文本冲突，停下来问人哪边为准，不要让代理自行裁决

验证：查看该计划的进度台账，每个任务都应有明确的完成或修复轮次记录：

cat .superpowers/sdd/*/progress.md

📦 从旧版本迁移过来要注意什么

有个人技能的话，迁移前按 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：验证子代理驱动开发的工作区脚本

想在不污染真实配置的前提下验证，可以加载隔离环境——它会用临时目录冒充 HOME：

source 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