尧图网页设计 
如何5分钟定位Superpowers常见报错完整排障与效率提升指南【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 是让 Claude Code、OpenCode 等编码代理遵循标准开发流程的技能框架。本文面向排障场景安装失败、钩子不触发、技能缺失、服务器起不来先用 60 秒定位属于哪一层再按层修复验证。60秒快速自查对照现象锁定所属层先对照下表无关章节可直接跳过你看到的现象归属层跳至装完后代理不提 you have superpowers技能不自动触发安装层第 1 节配置了插件但不加载或更新后版本不生效配置层第 2 节伴生服务器起不来钩子输出字段不对运行时层第 3 节技能列表缺失、自定义技能不生效扩展层第 4 节1. 安装层三步验证插件装对没有一条命令验证插件是否加载OpenCode症状安装完成但代理对技能毫无反应。排查opencode run --print-logs hello 21 | grep -i superpowers预期结果出现插件加载相关日志行。若为空说明插件没加载检查opencode.json的 plugin 行{ plugin: [superpowersgithttps://gitcode.com/GitHub_Trending/su/superpowers.git] }修复写入正确配置行各 harness 的安装命令见 README.md 对应章节Claude Code 用户用/plugin install superpowerssuperpowers-marketplace。重启 harness。需要本地开发版时克隆仓库后按 harness 文档指向本地路径git clone https://gitcode.com/GitHub_Trending/su/superpowers验证问代理 Tell me about your superpowers能复述技能体系即通过。⚠️ 每个 harness 都要单独安装一次Claude Code 装好不代表 OpenCode 也有。Windows 钩子静默跳过的三步修复症状Linux/macOS 正常Windows 上会话开始没有注入引导上下文且日志无报错。排查where bash预期结果输出至少一个 bash 路径如C:\Program Files\Git\bin\bash.exe。找不到时hooks/run-hook.cmd 调度器按设计静默退出不会报错。修复安装 Git for Windows 到标准路径或确保 bash 在 PATH 中。验证bash tests/hooks/test-session-start.sh预期结果测试通过。详见 docs/windows/polyglot-hooks.md 的故障排查章节。⚠️ 静默退出是刻意设计你看不到错误必须主动跑钩子测试确认。2. 配置层解决更新缓存与钩子配置冲突两步解决更新后版本不生效症状重装或升级后代理行为仍是旧版。原因部分 OpenCode / Bun 版本会把解析后的 git 依赖锁定在 lockfile 或缓存里重启不一定拿到最新提交官方 OpenCode 文档已说明此行为。修复清理 OpenCode 的包缓存或重新安装插件。需要稳定版本时改用 tag 固定如superpowers...#v5.0.3示例见 docs/README.opencode.md。验证重启后运行基线测试bash tests/opencode/run-tests.sh预期结果STATUS: PASSED。⚠️ 固定 tag 后不再自动获得更新需要时切回主分支。一行修正钩子 matcher 错配症状钩子脚本没问题但事件从不触发。排查对照 hooks/hooks.json 的 matcherClaude Code 用startup|clear|compactCursor 用sessionStart见 hooks/hooks-cursor.json。修复把 matcher 改为你的 harness 实际发出的事件或加载对应的 hooks 文件。验证手动执行脚本确认输出正常bash hooks/session-start预期结果输出含上下文注入字段的 JSON字段名因平台而异。⚠️ matcher 不匹配不会报错只是不触发只能靠手动执行脚本确认。3. 运行时层修复伴生服务器与钩子输出修复 brainstorm 伴生服务器启动失败症状返回{error: Server failed to start within 5 seconds}或提示 Server started but was killed。排查检查 Node 是否可用node -v预期输出版本号服务器是node server.cjs驱动。was killed 一类错误多由环境回收后台进程导致skills/brainstorming/scripts/start-server.sh 的错误信息里已直接给出前台重跑命令。修复在持久终端中以前台模式重跑bash skills/brainstorming/scripts/start-server.sh --foreground验证会话目录下的服务器日志首行出现server-started。⚠️ 会话目录/tmp/brainstorm-*或项目下.superpowers/brainstorm/内含访问令牌勿外传该目录。逐平台核对钩子输出字段症状钩子执行了但平台没吃到注入的上下文。排查hooks/session-start 按环境变量选择字段CURSOR_PLUGIN_ROOT→additional_contextClaude Code →hookSpecificOutput.additionalContext其余 → 顶层additionalContext。确认当前平台对应的变量是否被 harness 正确设置。修复升级 harness 到支持版本并确认加载了匹配的 hooks 文件hooks.json / hooks-cursor.json。验证重跑bash hooks/session-start核对 JSON 顶层字段与当前平台一致。⚠️ Claude Code 会同时读两个字段且不查重必须保证只输出当前平台消费的那一个。4. 扩展层技能缺失排查与回归验证三步解决 skill not found症状技能列表里没有目标技能或加载报未找到。排查让代理执行 use skill tool to list skills确认列表。检查该技能目录是否有SKILL.md且 YAML frontmattername、description完整——官方文档明确这是加载前提。修复补全 frontmatter若插件整体未加载回第 2 节先修配置。验证按名加载 use skill tool to load brainstorming应成功载入。⚠️ 技能优先级为 项目 个人 Superpowers 内置同名自定义技能会静默覆盖内置版本。改动后跑一遍基线测试症状本地改过插件文件后不确定是否破坏加载链路。修复跑不依赖 OpenCode 的基线测试插件结构、bootstrap 缓存bash tests/opencode/run-tests.sh cd tests/brainstorm-server npm test预期结果全部通过需要 OpenCode 集成测试时给第一条命令加--integration测试体系说明见 docs/testing.md。验证输出无 FAIL 项即回归通过。⚠️evals/行为评测驱动真实 LLM 会话每个场景 3-30 分钟以上仅在验证行为改动时使用。5. 常见错误速查表错误 / 现象常见原因一句话处理办法会话开始后技能不自动触发插件未加载或钩子未注入先查插件加载日志再按 harness 重装Server failed to start within 5 secondsNode 缺失或 5 秒内未就绪查node -v重跑启动脚本Server started but was killed后台进程被环境回收按报错提示用--foreground前台重跑更新后版本不生效lockfile / 缓存固定了 git 依赖清理 OpenCode 缓存或重装插件Linux 钩子正常、Windows 无动作缺少 Git Bash安装 Git for Windows 到标准路径skill not found缺 SKILL.md 或 frontmatter 损坏补全技能 YAML 头后重新加载测试输出STATUS: FAILED插件结构或缓存异常加--verbose看失败项输出定位后重跑6. 效率习惯5 条从今天开始执行✅装完做双验证问 Tell me about your superpowers 用 skill 工具列技能两分钟确认全链路。✅升级前后跑基线测试bash tests/opencode/run-tests.sh秒级完成锁住行为基线。✅稳定期固定 tag用 tag 固定版本代替跟随移动的主分支避免行为漂移。✅改钩子必过测试bash tests/hooks/test-session-start.sh加bash scripts/lint-shell.sh防止跨平台回归。✅更新前读发布说明每次升级前先查 RELEASE-NOTES.md 中与所用 harness 相关的变更。7. 资源索引主文档与各 harness 安装方式README.mdOpenCode 指南与故障排查docs/README.opencode.mdKimi Code 指南docs/README.kimi.md跨平台钩子设计与常见故障docs/windows/polyglot-hooks.md测试体系tests/ 与 evals/ 两套分工docs/testing.md插件基础设施测试tests/Shell 脚本 Lint 工具scripts/lint-shell.sh发布说明RELEASE-NOTES.md社区与问题反馈见 README.md 末尾 Community 小节Discord 与 issue 跟踪入口排障靠分层效率靠验证。先让 60 秒自查表定位到层再按各章定位 → 修复 → 验证闭环走一遍Superpowers 日常的大部分故障都能自助解决。【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何5分钟定位Superpowers常见报错：完整排障与效率提升指南
如何5分钟定位Superpowers常见报错完整排障与效率提升指南【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 是让 Claude Code、OpenCode 等编码代理遵循标准开发流程的技能框架。本文面向排障场景安装失败、钩子不触发、技能缺失、服务器起不来先用 60 秒定位属于哪一层再按层修复验证。60秒快速自查对照现象锁定所属层先对照下表无关章节可直接跳过你看到的现象归属层跳至装完后代理不提 you have superpowers技能不自动触发安装层第 1 节配置了插件但不加载或更新后版本不生效配置层第 2 节伴生服务器起不来钩子输出字段不对运行时层第 3 节技能列表缺失、自定义技能不生效扩展层第 4 节1. 安装层三步验证插件装对没有一条命令验证插件是否加载OpenCode症状安装完成但代理对技能毫无反应。排查opencode run --print-logs hello 21 | grep -i superpowers预期结果出现插件加载相关日志行。若为空说明插件没加载检查opencode.json的 plugin 行{ plugin: [superpowersgithttps://gitcode.com/GitHub_Trending/su/superpowers.git] }修复写入正确配置行各 harness 的安装命令见 README.md 对应章节Claude Code 用户用/plugin install superpowerssuperpowers-marketplace。重启 harness。需要本地开发版时克隆仓库后按 harness 文档指向本地路径git clone https://gitcode.com/GitHub_Trending/su/superpowers验证问代理 Tell me about your superpowers能复述技能体系即通过。⚠️ 每个 harness 都要单独安装一次Claude Code 装好不代表 OpenCode 也有。Windows 钩子静默跳过的三步修复症状Linux/macOS 正常Windows 上会话开始没有注入引导上下文且日志无报错。排查where bash预期结果输出至少一个 bash 路径如C:\Program Files\Git\bin\bash.exe。找不到时hooks/run-hook.cmd 调度器按设计静默退出不会报错。修复安装 Git for Windows 到标准路径或确保 bash 在 PATH 中。验证bash tests/hooks/test-session-start.sh预期结果测试通过。详见 docs/windows/polyglot-hooks.md 的故障排查章节。⚠️ 静默退出是刻意设计你看不到错误必须主动跑钩子测试确认。2. 配置层解决更新缓存与钩子配置冲突两步解决更新后版本不生效症状重装或升级后代理行为仍是旧版。原因部分 OpenCode / Bun 版本会把解析后的 git 依赖锁定在 lockfile 或缓存里重启不一定拿到最新提交官方 OpenCode 文档已说明此行为。修复清理 OpenCode 的包缓存或重新安装插件。需要稳定版本时改用 tag 固定如superpowers...#v5.0.3示例见 docs/README.opencode.md。验证重启后运行基线测试bash tests/opencode/run-tests.sh预期结果STATUS: PASSED。⚠️ 固定 tag 后不再自动获得更新需要时切回主分支。一行修正钩子 matcher 错配症状钩子脚本没问题但事件从不触发。排查对照 hooks/hooks.json 的 matcherClaude Code 用startup|clear|compactCursor 用sessionStart见 hooks/hooks-cursor.json。修复把 matcher 改为你的 harness 实际发出的事件或加载对应的 hooks 文件。验证手动执行脚本确认输出正常bash hooks/session-start预期结果输出含上下文注入字段的 JSON字段名因平台而异。⚠️ matcher 不匹配不会报错只是不触发只能靠手动执行脚本确认。3. 运行时层修复伴生服务器与钩子输出修复 brainstorm 伴生服务器启动失败症状返回{error: Server failed to start within 5 seconds}或提示 Server started but was killed。排查检查 Node 是否可用node -v预期输出版本号服务器是node server.cjs驱动。was killed 一类错误多由环境回收后台进程导致skills/brainstorming/scripts/start-server.sh 的错误信息里已直接给出前台重跑命令。修复在持久终端中以前台模式重跑bash skills/brainstorming/scripts/start-server.sh --foreground验证会话目录下的服务器日志首行出现server-started。⚠️ 会话目录/tmp/brainstorm-*或项目下.superpowers/brainstorm/内含访问令牌勿外传该目录。逐平台核对钩子输出字段症状钩子执行了但平台没吃到注入的上下文。排查hooks/session-start 按环境变量选择字段CURSOR_PLUGIN_ROOT→additional_contextClaude Code →hookSpecificOutput.additionalContext其余 → 顶层additionalContext。确认当前平台对应的变量是否被 harness 正确设置。修复升级 harness 到支持版本并确认加载了匹配的 hooks 文件hooks.json / hooks-cursor.json。验证重跑bash hooks/session-start核对 JSON 顶层字段与当前平台一致。⚠️ Claude Code 会同时读两个字段且不查重必须保证只输出当前平台消费的那一个。4. 扩展层技能缺失排查与回归验证三步解决 skill not found症状技能列表里没有目标技能或加载报未找到。排查让代理执行 use skill tool to list skills确认列表。检查该技能目录是否有SKILL.md且 YAML frontmattername、description完整——官方文档明确这是加载前提。修复补全 frontmatter若插件整体未加载回第 2 节先修配置。验证按名加载 use skill tool to load brainstorming应成功载入。⚠️ 技能优先级为 项目 个人 Superpowers 内置同名自定义技能会静默覆盖内置版本。改动后跑一遍基线测试症状本地改过插件文件后不确定是否破坏加载链路。修复跑不依赖 OpenCode 的基线测试插件结构、bootstrap 缓存bash tests/opencode/run-tests.sh cd tests/brainstorm-server npm test预期结果全部通过需要 OpenCode 集成测试时给第一条命令加--integration测试体系说明见 docs/testing.md。验证输出无 FAIL 项即回归通过。⚠️evals/行为评测驱动真实 LLM 会话每个场景 3-30 分钟以上仅在验证行为改动时使用。5. 常见错误速查表错误 / 现象常见原因一句话处理办法会话开始后技能不自动触发插件未加载或钩子未注入先查插件加载日志再按 harness 重装Server failed to start within 5 secondsNode 缺失或 5 秒内未就绪查node -v重跑启动脚本Server started but was killed后台进程被环境回收按报错提示用--foreground前台重跑更新后版本不生效lockfile / 缓存固定了 git 依赖清理 OpenCode 缓存或重装插件Linux 钩子正常、Windows 无动作缺少 Git Bash安装 Git for Windows 到标准路径skill not found缺 SKILL.md 或 frontmatter 损坏补全技能 YAML 头后重新加载测试输出STATUS: FAILED插件结构或缓存异常加--verbose看失败项输出定位后重跑6. 效率习惯5 条从今天开始执行✅装完做双验证问 Tell me about your superpowers 用 skill 工具列技能两分钟确认全链路。✅升级前后跑基线测试bash tests/opencode/run-tests.sh秒级完成锁住行为基线。✅稳定期固定 tag用 tag 固定版本代替跟随移动的主分支避免行为漂移。✅改钩子必过测试bash tests/hooks/test-session-start.sh加bash scripts/lint-shell.sh防止跨平台回归。✅更新前读发布说明每次升级前先查 RELEASE-NOTES.md 中与所用 harness 相关的变更。7. 资源索引主文档与各 harness 安装方式README.mdOpenCode 指南与故障排查docs/README.opencode.mdKimi Code 指南docs/README.kimi.md跨平台钩子设计与常见故障docs/windows/polyglot-hooks.md测试体系tests/ 与 evals/ 两套分工docs/testing.md插件基础设施测试tests/Shell 脚本 Lint 工具scripts/lint-shell.sh发布说明RELEASE-NOTES.md社区与问题反馈见 README.md 末尾 Community 小节Discord 与 issue 跟踪入口排障靠分层效率靠验证。先让 60 秒自查表定位到层再按各章定位 → 修复 → 验证闭环走一遍Superpowers 日常的大部分故障都能自助解决。【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考