Superpowers 技能框架故障排查与修复指南4 个常见故障场景逐条恢复【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 是给 Claude Code、Codex、OpenCode 等编码智能体的 agentic 技能框架装好后智能体会自动运行头脑风暴、TDD、子代理评审等技能。安装报错、技能不触发、头脑风暴页面打不开本文给出 4 个最高发故障的定位方法与修复命令。插件装不上修复 Plugin not found 报错现象还原你在 Claude Code 里直接敲安装命令回一句 Plugin not found或者在 Codex 里能找到市场名字但列表里没有任何可安装的条目。快速定位看两个点。一是插件名带superpowers-marketplace这个市场没先注册就不存在二是版本太旧v6.1.0 之前的仓库没有 Codex 市场清单marketplace.json升级前 Codex 侧永远装不上。动手修复先注册市场再装插件/plugin marketplace add obra/superpowers-marketplace /plugin install superpowerssuperpowers-marketplace用 OpenCode 或 Pi 的话安装入口不同细节看 docs/README.opencode.md。避坑提醒多个 harness 要分别安装Claude Code 装好了不代表 Codex 也有市场名和插件名长得很像add失败时先确认网络能访问仓库再怀疑命令Codex 显示已安装但功能不生效多半是旧版残留升级仓库后重新安装钩子不触发会话里智能体完全不激活技能现象还原会话一切正常但智能体不再主动查技能像忘了 Superpowers。Windows 上最常见的表现是没有任何报错就是静默不生效。快速定位Superpowers 靠hooks/session-start这个 SessionStart 钩子注入using-superpowers引导内容。先在仓库里跑自带自测确认钩子逻辑本身没问题bash tests/hooks/test-session-start.sh动手修复自测通过但会话仍不触发问题出在 shell 环境。Windows 必须装 Git for Windows含 Git Bashv6.2.0 起钩子声明shell: bash由 Git Bash 调度缺 Git Bash 时会给出可操作的安装提示而不是晦涩的解析错误。Linux/macOS 则核对 hooks/hooks.json 里的路径是否和实际文件一致。避坑提醒别给钩子脚本改名或加.sh后缀Windows 下 Claude Code 会对含.sh的命令自动前缀bash直接弄坏分发器原理见 docs/windows/polyglot-hooks.md没有 bash 时钩子会静默退出插件看似一切正常——无报错但不生效是最容易误判的情况改过钩子命令字符串的保留shell: bash声明别删头脑风暴视觉伴侣打不开处理 Server failed to start within 5 seconds 现象还原brainstorming 技能要打开视觉伴侣网页时脚本报错最常见的是{error: Server failed to start within 5 seconds}也有人是进程刚起来就没了。快速定位先确认 node 存在再找日志。服务器把启动信息写到状态目录的server-info运行期错误进server.log用过--project-dir的话这两个文件在项目根目录.superpowers/brainstorm/会话id/state/下。动手修复装好 node 后带--project-dir重跑启动脚本既拿到端口和日志位置也让 mockup 可持久化skills/brainstorming/scripts/start-server.sh --project-dir /path/to/projectCodex 和 Windows 环境会收割后台进程脚本已自动切前台模式各平台完整参数用法见 skills/brainstorming/visual-companion.md。避坑提醒返回的 URL 带?key会话密钥把裸端口地址丢给用户会被服务器拒绝不带--project-dir时文件落 /tmp重启即丢记得把.superpowers/加进.gitignore上游测试绿、你这里红先分清卡在哪一层现象还原本地跑仓库测试有失败项但 CI 是绿的或者真实会话里智能体表现正常测试却报红两边行为对不上。快速定位Superpowers 的测试分两层混着跑是误判主因。tests/验非 LLM 代码bash node python秒级出结果evals/驱动真实 LLM 会话要配ANTHROPIC_API_KEY单项 3 到 30 分钟。把 evals 超时当插件 bug是最常见的错误归因。动手修复没有本地仓库就先 clone 一份再跑不依赖外部依赖的快速套件并用--test隔离单测git clone https://gitcode.com/GitHub_Trending/su/superpowers tests/opencode/run-tests.sh --test test-plugin-loading.sh两套测试体系的完整说明在 docs/testing.md。避坑提醒不带--integration时只跑无外部依赖的用例别把它当成全量测试结论evals 失败常是 API key、模型配额或超时先查环境再动代码升级仓库后重跑失败项很多环境不一致只是 checkout 太旧修不好怎么办求助前先在 RELEASE-NOTES.md 里对版本号。多数已知问题早被某个版本修掉了升级是最便宜的修复。问题可复现的话把三样东西凑齐再提问harness 名称与版本、完整报错文案、相关自测脚本的输出。然后去项目 issue 区提交或进社区 Discord 频道问。自查资源docs/testing.md —— 两套测试体系的完整说明docs/windows/polyglot-hooks.md —— 钩子跨平台调度机制Windows 钩子问题的原理入口skills/writing-skills/SKILL.md —— 技能规范怀疑技能行为不对时对照检查hooks/hooks.json —— 钩子注册配置钩子失灵的第一排查点RELEASE-NOTES.md —— 逐版本变更记录与已知问题修复【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
