Superpowers 智能体技能框架排错指南：6 个高频问题的 10 分钟修复法
【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers
Superpowers 是一套给编码智能体（Claude Code、OpenCode、Codex、Kimi 等）用的技能框架，装好后智能体会自动走头脑风暴、TDD、代码审查这套开发流程。新手最常栽跟头的，不是它的能力，而是装完之后的各种小毛病：一启动报 "Bad substitution"、插件加载了却像没装一样、更新半天不生效。这篇文章挑 6 个真实高频问题，每个都给你最短的修复路径。
先想清楚问题卡在哪一层
排查时先做个三选一的分诊：是宿主环境（shell、Node、平台）的问题，还是插件安装（marketplace 注册、插件行配置）的问题，还是运行时行为（会话没刷新、缓存没清）的问题。九成问题都卡在后两层——装好了但会话还是旧的，这是新手最容易忽略的一点。
"Bad substitution" 报错的三步处理
- 症状：在 Ubuntu/Debian 上启动，终端直接弹出
Bad substitution，流程没跑起来。 - 原因：Ubuntu/Debian 的
/bin/sh默认是 dash，不支持 bash 专属语法（如${BASH_SOURCE[0]:-...}）。老版本的hooks/session-start钩子里恰好用了这种写法，dash 一执行就报这个错。 - 修复：这是官方已修的老 bug（v3.6.2 和 v5.0.3 都修了钩子脚本），升级到新版即可：
# 在 Claude Code 里执行，拉取最新 Superpowers /plugin update superpowers如果你现在被卡住等不及，先手动用 bash 跑钩子绕过：bash hooks/session-start，先恢复工作再说。
- 确认：新开会话后启动不再弹
Bad substitution，智能体正常进入技能流程，就算修好了。
顺带一提：所有脚本的 shebang 也统一成了#!/usr/bin/env bash，NixOS、FreeBSD 这类 bash 位置不寻常的系统不再报错，升级一次全解决了。
macOS 启动钩子卡死的解法
- 症状：macOS 上用 Homebrew bash，会话启动时钩子无限挂起，转圈等不出结果。
- 原因：bash 5.3+ 有个回归 bug：heredoc 里展开超大变量会死等。钩子原来用 heredoc 输出注入内容，变量一大就触发这个坑（官方 issue #571、#572）。
- 修复：同样靠升级，新版把 heredoc 换成了
printf输出：
# 确认你的 bash 版本（5.3 及以上才受影响） bash --version- 确认：升级后重新
clear会话，启动钩子秒级返回、不再卡死。
OpenCode 装完插件不加载的排查路径
- 症状：
opencode.json加了插件行，重启后问"你有哪些 superpowers"，智能体一脸茫然。 - 原因：要么插件行写错，要么 OpenCode 版本太老不支持。官方给的标准排查顺序是：先看日志，再核对配置行。
- 修复：按 OpenCode 文档 的 Troubleshooting 一节来：
# 过滤插件加载日志，确认有没有 superpowers 相关报错 opencode run --print-logs "hello" 2>&1 | grep -i superpowers日志干净但就是不生效？核对opencode.json里"plugin"数组那一行，并升级到较新的 OpenCode 版本。
- 确认：让 OpenCode 用 skill 工具列出技能清单，
brainstorming、writing-plans等技能能列出来，就通了。
技能"未找到"或装了不生效的常见根因
- 症状：提示找不到某技能，或者 Kimi 里装完插件、新对话还是老样子。
- 原因：两条主线。一是技能本身每个都靠
SKILL.md里的 YAML frontmatter 被发现，文件缺失或 frontmatter 坏了技能就不存在；二是很多宿主（如 Kimi）只对新会话应用插件变更，旧会话里装了等于没装。 - 修复：Kimi 用户装完直接开新会话：
# Kimi Code 中开启全新会话，插件变更才会生效 /new其他宿主先确认插件已加载（见上一章），再检查对应技能目录下SKILL.md是否完整。
- 确认：用 Kimi 文档给的验收句
Let's make a react todo list，装对了的话智能体应先触发brainstorming而不是直接写代码。
更新半天不生效：清 OpenCode 缓存
- 症状：明明升级了 Superpowers，行为却停留在旧版本。
- 原因：OpenCode 通过 git 地址装插件，部分 OpenCode/Bun 版本会把解析到的 git 依赖钉在 lockfile 或缓存里，重启也拉不到最新提交。
- 修复：清掉 OpenCode 的包缓存，或卸载重装插件。想锁版本的话，插件行直接钉 tag，例如：
{ "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"] }- 确认：清缓存重启后问智能体它的 Superpowers 版本，或观察新特性出现，即更新成功。
Windows 上 brainstorm 可视化伴侣悄悄挂了
- 症状：brainstorming 流程里可视化伴侣页面出不来，没有任何报错。
- 原因：老版脚本在 Windows 上用
nohup/disown挂后台，Git Bash 环境会把这种进程直接收走，服务器没起来也不会提示。 - 修复：v5.0.3 起脚本会自动识别 Windows/Git Bash 并改走前台模式，升级即可。确认脚本版本：
# 看 start-server.sh 是否带 Windows 自动检测（OSTYPE/MSYSTEM 判断） grep -n "msys" skills/brainstorming/scripts/start-server.sh- 确认：能 grep 到
msys相关判断，重启流程后伴侣页面正常弹出。
全部问题速查表
| 症状 | 最可能原因 | 一句话修复 |
|---|---|---|
启动弹Bad substitution | dash 不支持 bash 语法，钩子是老版本 | 升级 Superpowers（v3.6.2/v5.0.3 已修） |
| macOS 启动钩子卡死 | bash 5.3+ heredoc 回归 bug | 升级，新版改用printf输出 |
| OpenCode 装完插件不加载 | 插件行写错 / OpenCode 太老 | opencode run --print-logs查日志，核对opencode.json |
| 技能未找到 / Kimi 装了没反应 | SKILL.md损坏，或插件变更未进新会话 | 修好 SKILL.md；Kimi 里执行/new开新会话 |
| 更新后行为仍是旧版 | git 依赖被 lockfile/缓存钉住 | 清 OpenCode 包缓存或重装插件 |
| Windows 上可视化伴侣无响应 | nohup后台进程被 Git Bash 回收 | 升级到 v5.0.3+（自动切前台模式） |
日常习惯：少踩坑的 4 件事
- 宿主（Claude Code / OpenCode / Kimi 等）和 Superpowers 都保持较新版本，本文一半的坑升级就消失。
- 升级前扫一眼 RELEASE-NOTES.md，平台相关的修复都写在里面。
- 改完任何插件配置，一律开新会话再验证，别在旧会话里反复试。
- 跑不通时先跑项目自带的测试脚本定位层级，比如 tests/ 下的
run-*.sh，以及 docs/testing.md 里的说明。
卡住了就去项目 Discord 社区提问，或在 issue 区开一个带完整日志的工单——附上日志的问题，响应快得多。
【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
