Superpowers 故障排查实战从装不上到子代理卡死的完整避坑指南【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 是给 Claude Code、Codex 这类编程代理套上完整软件开发方法论的 agentic skills 框架brainstorm、写计划、TDD、代码审查全程自动触发。你可能也遇到过这两个瞬间插件装好了代理却像没看见一样直接开写代码或者子代理跑了一小时集体静默你不知道它卡在哪。读完这篇装不上、技能不触发、brainstorm 画面打不开、子代理卡死这四类状况都能自己处理不用再翻八个网页。装不上先查这三处再动手你大概率会看到……安装命令报 Plugin not foundmarketplace 注册卡住或者仓库内容明明在、代理却完全不认识 Superpowers。先查这里别急着重装先确认两件事一是你用的 harness 装没装对——Superpowers 是按编程代理分别安装的同时用 Claude Code 和 Codex 就要各装一遍装一个不等于装两个二是仓库本身完整。跑一下git clone https://gitcode.com/GitHub_Trending/su/superpowers ls skills/skills/下应该有一长串技能目录缺了就是 clone 不完整。怎么修最轻的动作确认 marketplace 注册后再装比如 Claude Code 里先注册官方市场再/plugin install superpowersclaude-plugins-official。如果上面没解决再走源码本地安装——clone 后用各 harness 的本地路径加载见 README 的 Installation 一节。验证方式新开一个会话让代理自我介绍它应该说清楚自己有超能力、会自动检查技能而不是闷头写代码。别再踩一次升级前先翻一眼仓库根目录的 RELEASE-NOTES.md多 harness 用户把每个代理单独装这条写进你的安装清单里。装了但不触发session-start 钩子是命门你大概率会看到……插件显示已安装代理却从不主动 brainstorm 或 TDD直接开干Windows 用户尤其容易踩——钩子静默失败没有任何报错。先查这里手动跑一遍钩子看真实输出bash hooks/run-hook.cmd session-start | head -c 200盯输出里有没有additionalContext字样的 JSON、内容里有没有 You have superpowers。如果看到 Error reading using-superpowers skill说明skills/using-superpowers/SKILL.md文件缺失钩子注入的是错误信息而不是技能。怎么修先补文件重新 clone 或 git pull 把skills/目录补全再跑一次上面的命令。如果上面没解决再查 shell 和平台——脚本是 bash 专属的用 dash 之类环境跑会报 Bad substitutionWindows 上run-hook.cmd找不到 bash 会静默退出插件能跑但钩子上下文没了用where bash确认 Git for Windows 是否已装。钩子按平台环境变量选输出字段平台识别的环境变量输出 JSON 字段CursorCURSOR_PLUGIN_ROOTadditional_contextClaude CodeCLAUDE_PLUGIN_ROOThookSpecificOutput.additionalContextCopilot CLI 及其他COPILOT_CLIadditionalContext验证方式输出的字段名和你当前平台对得上重启会话后代理能复述技能系统的存在。别再踩一次别把钩子文件名改成.sh后缀——Windows 的自动检测逻辑会被它干扰hooks/run-hook.cmd注释里写明了。动过 hooks 目录就跑一次bash tests/hooks/test-session-start.sh。brainstorm 画面打不开视觉伴侣服务器排查你大概率会看到……brainstorming 阶段视觉伴侣的画面刷不出来端口被占用或者远程容器里返回的 URL 根本访问不到。先查这里前台直接跑服务器看真实报错而不是猜bash skills/brainstorming/scripts/start-server.sh --foreground能打印出带 URL 的 JSON说明服务器没问题锅在浏览器或网络。怎么修远程环境要换绑定地址加--host 0.0.0.0 --url-host 可达地址注意0.0.0.0 会把端口暴露出去别在公网环境这么干。如果上面没解决多半是旧实例占着端口先停再启bash skills/brainstorming/scripts/stop-server.sh验证方式浏览器打开新 JSON 里的 URL能看到 brainstorm 画面即恢复。别再踩一次想让会话文件留存就带--project-dir参数否则文件在 /tmp 里服务器停了就没了另外服务器空闲 4 小时会自动关停那是设计行为别当成故障。子代理集体静默SDD 卡死的分诊三步你大概率会看到……子代理跑着跑着不吭声了或者在一个任务上反复打转。最贵的一种事故会话压缩compaction后控制器忘了进度把整套已完成的任务重新派发一遍——这是 SDD 文档里点名的头号失血点。⚠️先查这里别凭对话记录猜去看账本ledger文件SDD 的进度记录在 ledger 里而不是对话上下文里对照计划和 ledger 看哪个任务真的完成了、卡在哪一轮。同时读skills/subagent-driven-development/的 SKILL.md 里修复循环规则审查-修复最多 5 轮第 4 轮起换新实现者、换更强的模型满 5 轮还没过就该报 BLOCKED 停下。怎么修最轻的动作让它走完流程——如果它正好报 BLOCKED那是熔断器在工作不是故障你只需要对剩余 findings 逐条裁决再继续。如果上面没解决回头查计划本身writing-plans 技能要求每个任务 2-5 分钟可完成、路径和代码都写全任务大到说不清一句验证方式就该拆细再派发新子代理而不是让旧子代理硬扛。别再踩一次每次接手会话先看 ledger 再看 todo这一步能挡住最贵的重复派发。测试不过先跑非 LLM 测试套件你大概率会看到……升级后某个平台行为变了你不知道是自己的环境问题还是上游改动测试脚本一跑就报错但不知道错在哪个层面。先查这里Superpowers 的测试分两层见 docs/testing.mdtests/目录全是非 LLM 的 bash/node/python 集成测试快先跑它evals/目录是真 LLM 行为评测每个 3-30 分钟别拿它当第一道分诊。bash tests/opencode/run-tests.sh bash tests/hooks/test-session-start.sh怎么修单项失败就单跑bash tests/opencode/run-tests.sh --test 名称run-tests.sh 支持--test参数。如果上面没解决是 shell 脚本改动引入的问题用bash scripts/lint-shell.sh跑 ShellCheck 定位。动过 brainstorm 服务器的 JS 代码就在tests/brainstorm-server/目录补跑npm test。别再踩一次改任何 shell 脚本前把bash scripts/lint-shell.sh跑一遍比事后猜错在哪快得多。日常体检bash tests/hooks/test-session-start.sh bash tests/opencode/run-tests.sh bash scripts/lint-shell.sh改钩子后加跑一次钩子测试多 harness 用户记得逐代理验证。卡住了先去 docs/testing.md 和 skills/writing-skills/SKILL.md再带着head -c 200的钩子输出去 issue 区提问。现在就去跑一遍bash tests/hooks/test-session-start.sh让全绿成为你的基线。【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考