企业官网建设流程全解析

Superpowers 故障排查实战：从装不上到子代理卡死的完整避坑指南

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

Superpowers 是给 Claude Code、Codex 这类编程代理套上完整软件开发方法论的 agentic skills 框架：brainstorm、写计划、TDD、代码审查，全程自动触发。你可能也遇到过这两个瞬间：插件装好了，代理却像没看见一样直接开写代码；或者子代理跑了一小时，集体静默，你不知道它卡在哪。读完这篇，装不上、技能不触发、brainstorm 画面打不开、子代理卡死这四类状况都能自己处理，不用再翻八个网页。

装不上：先查这三处再动手

你大概率会看到……安装命令报 "Plugin not found"，marketplace 注册卡住，或者仓库内容明明在、代理却完全不认识 Superpowers。

先查这里别急着重装，先确认两件事：一是你用的 harness 装没装对——Superpowers 是按编程代理分别安装的，同时用 Claude Code 和 Codex 就要各装一遍，装一个不等于装两个；二是仓库本身完整。跑一下：

git clone https://gitcode.com/GitHub_Trending/su/superpowers ls skills/

skills/下应该有一长串技能目录，缺了就是 clone 不完整。

怎么修最轻的动作：确认 marketplace 注册后再装，比如 Claude Code 里先注册官方市场再/plugin install superpowers@claude-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 substitution；Windows 上run-hook.cmd找不到 bash 会静默退出（插件能跑，但钩子上下文没了），用where bash确认 Git for Windows 是否已装。钩子按平台环境变量选输出字段：

验证方式：输出的字段名和你当前平台对得上，重启会话后代理能复述技能系统的存在。

别再踩一次别把钩子文件名改成.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.md）：tests/目录全是非 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