Superpowers 安装与使用快速排查：按报错修问题

Superpowers 安装与使用快速排查按报错修问题【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 是给编码智能体用的技能框架装好后你的 agent 会自动按头脑风暴、写计划、子代理实现、代码审查的流程干活不用你手动触发。这篇文章收集安装和使用中最容易撞上的报错——插件找不到、Windows 启动卡死、Bad substitution、SDD 审查循环反复——每节都按现象 → 原因 → 修复 → 验证写你对着报错文本对号入座就能修好。刚装完的新手、或流程卡在半路的人直接看。速查表 ✅你看到的报错原因解法Plugin not found插件市场没先注册先跑/plugin marketplace add再装Windows 终端卡死、键盘无响应钩子同步执行卡住界面升级到最新版Bad substitution/bin/sh是 dash不认 bash 语法升级到 POSIX 安全钩子版本OpenCode 里技能找不到技能目录没做符号链接链接到~/.config/opencode/skills/superpowers/子代理写.git/被拒绝受保护路径限制升级到 6.0.3账本已移走安装后插件或技能找不到Claude Code 里安装报Plugin not found先注册市场再执行安装就行。现象跑安装命令时报Plugin not found。原因安装名是superpowerssuperpowers-marketplace你没先注册这个市场名字自然不存在。修复在 Claude Code 会话里执行下面两条命令按顺序/plugin marketplace add obra/superpowers-marketplace /plugin install superpowerssuperpowers-marketplace验证/plugin list里 superpowers 显示为已安装新开一个会话能看到技能自动加载。更多平台的装法见 README.md 的 Installation 一节。旧版本残留导致升级了还是老行为删掉旧目录重装即可。现象升级后 agent 的行为还是旧版技能的样子。原因早期版本会自动把技能克隆到~/.config/superpowers/skills/升级时旧的.git被备份成.git.bak、旧技能备份成skills.bak你手动恢复过这些目录就会重新加载旧版。修复删除~/.config/superpowers/包括两个.bak目录重新安装插件让它重新自动克隆技能验证ls ~/.config/superpowers/skills/显示的是最新技能内容。备份细节可查 RELEASE-NOTES.md。Windows 启动卡死、钩子不加载怎么修终端卡死键盘无响应升级到最新版即可解决。现象Windows 上打开 Claude Code终端冻结、输入完全无响应。原因早期版本的 SessionStart 钩子同步执行把终端界面阻塞了。修复升级 Superpowers 到最新版钩子改为异步执行并经 Git Bash 调度。验证重启会话终端立即响应技能照常加载。启动后技能全无PowerShell 解析错误同样是升级到最新版。现象启动后 agent 完全没有 Superpowers 技能个别环境还能看到 PowerShell 解析器报错。原因钩子的命令串以带引号的路径开头PowerShell 会把它当表达式解析cmd.exe 的引号剥离规则又会截断命令引导流程于是静默没加载。修复升级到最新版钩子已声明shell: bash由 Git Bash 直接执行若没装 Git Bash先装 Git for Windows验证新开会话问 agent你有哪些技能它能列出 superpowers 技能清单。跨平台钩子原理见 docs/windows/polyglot-hooks.md。脚本报bad interpreter或奇怪的\r这是行尾符问题重新检出仓库就行。现象执行钩子脚本报bad interpreter之类的 CRLF 错误。原因Windows 检出时把 shell 脚本的 LF 换行变成了 CRLFbash 认不出解释器路径。修复升级到最新版仓库已用.gitattributes强制 shell 脚本用 LF重新克隆仓库或执行git checkout -- .恢复行尾验证file hooks/session-start的输出里不含 CRLF 字样。Linux/macOS 上Bad substitution等脚本报错怎么修Bad substitution报错升级到最新版即可这是老钩子用了 bash 专属语法。现象Ubuntu/Debian 上会话启动时报Bad substitution。原因旧钩子用了${BASH_SOURCE[0]}这种 bash 专属写法你这台机器的/bin/sh是 dash看不懂。修复升级到最新版钩子已改用 POSIX 安全的$0解析路径实现见 hooks/session-start。验证新开一个会话不再报错且技能正常加载。OpenCode 里技能找不到把技能目录做成符号链接类似快捷方式就能被找到。现象OpenCode 提示找不到 superpowers 技能或插件未加载。原因OpenCode 要求技能通过符号链接挂在~/.config/opencode/skills/superpowers/手动复制文件是发现不了的。修复克隆仓库到固定位置git clone https://gitcode.com/GitHub_Trending/su/superpowers建符号链接ln -s /path/to/superpowers/skills ~/.config/opencode/skills/superpowers把插件文件注册到~/.config/opencode/plugins/下验证ls -l ~/.config/opencode/skills/superpowers显示为链接且里面有 SKILL.md想完整校验安装结构跑 tests/opencode/test-plugin-loading.sh。子代理开发SDD流程卡住怎么修子代理写.git/sdd/被拒绝升级到 6.0.3 及以上即可。现象跑 subagent-driven-development 时实施者子代理往.git/sdd/写报告被拦截。原因Claude Code 把.git/当受保护路径、拒绝写入6.0.3 起账本和报告已挪到工作区的.superpowers/sdd/。修复升级到 6.0.3 或更新版本该目录被 git 忽略不污染提交。验证运行中工作区出现.superpowers/sdd/git status保持干净。git clean -fdx之后账本丢了从 git 历史恢复进度即可账本本来就不在版本库里。现象执行git clean -fdx后 SDD 进度账本消失恢复会话时 agent 想重做已完成的任务。原因账本是工作区里的临时文件git clean -fdx会把它删掉。修复用git log找出已完成任务的提交让控制器按 git 历史重建账本后继续验证恢复后 agent 跳过已完成任务直接从下一个任务继续。审查者反复提出新问题这是设计内的审查-修复循环超五轮会熔断。现象审查-修复回合里审查者不断发现新问题实施者反复改。原因每轮修复都会让原实施者接着改、做范围化复审超过 5 轮触发熔断由控制器仲裁——反复几轮是正常现象。修复熔断触发时让控制器给出仲裁结论同一问题反复多轮就停手重读任务定义再改验证复审通过后.superpowers/sdd/计划名/工作区自动清理。完整生命周期见 skills/subagent-driven-development/SKILL.md。还卡住⚠️ 先把 Superpowers 升到最新版本文多数报错在新版本里已修复仍不行就翻 docs/ 里对应平台的文档问题还在就提 issue附上完整报错文本和你的版本号。【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考