Superpowers 安装排查完整指南5 类高频报错按症状快速修复【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 是一个为编码智能体提供可组合技能与开发方法论的框架。本 Superpowers 安装排查手册覆盖安装报错、钩子失败、技能不触发等高频问题帮你按症状快速对号入座。动手前先自查版本、平台、配置路径排查前先用 3 分钟确认三件事能过滤掉一半环境问题。确认你的平台harnessClaude Code、Codex、OpenCode、Cursor、Gemini CLI 等的安装方式各不相同。安装差异以 README.md 的 Installation 章节为准多个平台同时使用时需要为每个平台单独安装一份。确认版本查看package.json中的版本号并与 RELEASE-NOTES.md 对照。文中大部分修复Windows 钩子、Bad substitution、插件安装失败等都只在较新版本生效升级往往就是解法本身。确认技能实际落盘位置Claude Code 插件技能随插件目录分发无需额外配置OpenCode技能需符号链接到~/.config/opencode/skills/superpowers/Codex通过~/.agents/skills/superpowers/符号链接做原生技能发现确认平台专属文档OpenCode 的完整安装与排障说明在 docs/README.opencode.md含 cmd.exe、PowerShell、Git Bash 三种终端的操作差异⚠️ 注意~/.config/superpowers/skills/是早期架构v4 之前的独立技能仓库的路径当前版本技能直接随插件/仓库分发不要按旧文档手动建目录。按症状快速对号入座症状 / 报错信息可能原因解决入口会话启动后 agent 不触发技能、行为没装Superpowerssession-start钩子未执行或失败钩子执行失败Plugin not found未先注册市场或市场源名称写错早期版本evals子模块也曾导致部分用户安装中断插件找不到PowerShell 解析器报错、cmd 命令被截断、Windows 钩子静默失效引号路径被 shell 误解析CRLF 行尾符缺 Git BashWindows 钩子报错Bad substitutionUbuntu/Debian 的/bin/sh是 dash旧钩子脚本含 bash 专有写法Bad substitution升级后提示找不到技能、重装报file already exists技能符号链接缺失或旧版路径未迁移技能未找到分场景解决会话启动后技能不触发session-start 钩子执行失败现象报错Plugin hook error或不报错但首条消息后 agent 直接开写代码、不走 brainstorming 流程——技能上下文没有注入会话。原因Superpowers 依赖会话启动钩子注入using-superpowers引导内容。历史版本中钩子曾配置为异步执行async: true可能赶不上模型第一轮就失败退出另有钩子命令的引号写法在部分系统上执行失败见 RELEASE-NOTES.md 中 v5.0.5 的同步化修复。步骤将 Superpowers 升级到最新版本手动执行钩子定位错误bash hooks/session-start确认 hooks/hooks.json 中命令直接指向session-start且脚本行尾为 LF验证开启新会话让 agent 做一个小任务正常应先进入 brainstorming 提问而非直接写代码。Windows 下钩子报错、终端卡死或技能静默失效现象PowerShell 报解析器错误路径含(等字符时 cmd 命令被截断钩子无任何输出但技能不生效。原因钩子命令串以带引号的路径开头PowerShell 会把引号串当表达式解析cmd 的引号剥离规则会在特殊字符处截断命令见 RELEASE-NOTES.md v6.2.0 Windows 章节。更早的版本还存在 CRLF 行尾符导致脚本损坏的问题现已通过.gitattributes强制 LF 行尾修复。步骤将 Claude Code 升级到 ≥ 2.1.81并安装 Git for Windows——钩子现声明shell: bash由 Git Bash 执行缺失时会弹出可操作的安装提示更新 Superpowers 到最新发行版各终端cmd / PowerShell / Git Bash的具体安装差异参考 docs/windows/polyglot-hooks.md 与 docs/README.opencode.md验证新开会话无解析报错、无终端冻结技能正常触发。Ubuntu/Debian 上出现 Bad substitution现象钩子执行时输出Bad substitution原因这些系统默认/bin/sh是 dash而旧版 hooks/session-start 使用了${BASH_SOURCE[0]:-$0}这类 bash 专有写法历史问题 #553、#141。步骤将 Superpowers 升级到 v5.0.3 之后的版本——脚本已改为 POSIX 安全的$0写法并全面使用#!/usr/bin/env bash可移植 shebang。验证bash hooks/session-start无报错且输出技能列表即修复完成。安装时提示 Plugin not found现象/plugin install提示Plugin not found。原因最常见是未先注册 Superpowers 市场就直接按市场源安装此外 v6.0.2 之前附带的evals子模块曾导致部分用户插件安装中断#1778、#1774已在新版中移除。步骤先注册市场再安装/plugin marketplace add obra/superpowers-marketplace /plugin install superpowerssuperpowers-marketplace或使用官方市场一行安装/plugin install superpowersclaude-plugins-officialCodex 用户走插件市场搜索安装输入/plugins搜索superpowers选择Install Plugin验证命令无报错新会话启动时能看到 Superpowers 引导内容加载。升级或重装后提示技能未找到现象OpenCode 等平台上升级后技能列表为空重装时符号链接步骤报file already exists。原因OpenCode 的技能依赖符号链接注册到~/.config/opencode/skills/superpowers/旧版文档曾遗漏该步骤直接覆盖式重装会因链接已存在而失败。步骤按 docs/README.opencode.md 删除旧链接后重建符号链接旧安装会被自动备份skills.bak升级后检查个人技能是否已从备份迁移当前版本 OpenCode 插件通过config钩子自动注册技能目录只需在opencode.json中一行配置确认该行存在验证运行插件结构检查脚本见下文确认修好了。确认修好了用项目自带测试脚本验证以下脚本都在tests/目录对应各平台自检source tests/opencode/setup.sh—— 创建隔离的临时测试环境避免污染真实配置tests/opencode/test-plugin-loading.sh—— 验证插件安装是否完整、技能目录结构是否正确tests/opencode/run-tests.sh—— 运行 OpenCode 全套插件测试tests/hooks/test-session-start.sh—— 验证session-start钩子输出tests/claude-code/run-skill-tests.sh—— 运行 Claude Code 技能行为测试tests/shell-lint/test-lint-shell.sh—— 对全部 shell 脚本做语法 lint提前暴露Bad substitution类问题✅ 对应平台的脚本全部通过即可认为环境恢复正常。仍然解决不了求助渠道与上报清单按顺序尝试查文档docs/ 目录包含完整使用与移植指南平台专属问题优先查对应 README如 docs/README.opencode.md、docs/README.kimi.md查发布记录多数报错在 RELEASE-NOTES.md 中带 issue 编号记录过按报错关键词搜索往往直接找到修复版本提交 issue在项目的 issue 跟踪系统报告项目方也提供 Discord 社区支持内置能力排查 Superpowers 自身脚本问题时可以直接让 agent 调用systematic-debugging技能做四阶段根因分析例如 skills/systematic-debugging/find-polluter.sh 这类脚本有配套的确定性测试 tests/systematic-debugging/test-find-polluter.sh 可对照上报问题时请附上以下信息可显著加快定位完整报错内容与出现时机安装 / 会话启动 / 技能触发Superpowers 版本号与所用 harness 及其版本Claude Code / Codex / OpenCode…操作系统与终端类型Linux/macOS/Windowscmd、PowerShell 或 Git Bash手动执行bash hooks/session-start的完整输出【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Superpowers 安装排查完整指南：5 类高频报错，按症状快速修复
Superpowers 安装排查完整指南5 类高频报错按症状快速修复【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 是一个为编码智能体提供可组合技能与开发方法论的框架。本 Superpowers 安装排查手册覆盖安装报错、钩子失败、技能不触发等高频问题帮你按症状快速对号入座。动手前先自查版本、平台、配置路径排查前先用 3 分钟确认三件事能过滤掉一半环境问题。确认你的平台harnessClaude Code、Codex、OpenCode、Cursor、Gemini CLI 等的安装方式各不相同。安装差异以 README.md 的 Installation 章节为准多个平台同时使用时需要为每个平台单独安装一份。确认版本查看package.json中的版本号并与 RELEASE-NOTES.md 对照。文中大部分修复Windows 钩子、Bad substitution、插件安装失败等都只在较新版本生效升级往往就是解法本身。确认技能实际落盘位置Claude Code 插件技能随插件目录分发无需额外配置OpenCode技能需符号链接到~/.config/opencode/skills/superpowers/Codex通过~/.agents/skills/superpowers/符号链接做原生技能发现确认平台专属文档OpenCode 的完整安装与排障说明在 docs/README.opencode.md含 cmd.exe、PowerShell、Git Bash 三种终端的操作差异⚠️ 注意~/.config/superpowers/skills/是早期架构v4 之前的独立技能仓库的路径当前版本技能直接随插件/仓库分发不要按旧文档手动建目录。按症状快速对号入座症状 / 报错信息可能原因解决入口会话启动后 agent 不触发技能、行为没装Superpowerssession-start钩子未执行或失败钩子执行失败Plugin not found未先注册市场或市场源名称写错早期版本evals子模块也曾导致部分用户安装中断插件找不到PowerShell 解析器报错、cmd 命令被截断、Windows 钩子静默失效引号路径被 shell 误解析CRLF 行尾符缺 Git BashWindows 钩子报错Bad substitutionUbuntu/Debian 的/bin/sh是 dash旧钩子脚本含 bash 专有写法Bad substitution升级后提示找不到技能、重装报file already exists技能符号链接缺失或旧版路径未迁移技能未找到分场景解决会话启动后技能不触发session-start 钩子执行失败现象报错Plugin hook error或不报错但首条消息后 agent 直接开写代码、不走 brainstorming 流程——技能上下文没有注入会话。原因Superpowers 依赖会话启动钩子注入using-superpowers引导内容。历史版本中钩子曾配置为异步执行async: true可能赶不上模型第一轮就失败退出另有钩子命令的引号写法在部分系统上执行失败见 RELEASE-NOTES.md 中 v5.0.5 的同步化修复。步骤将 Superpowers 升级到最新版本手动执行钩子定位错误bash hooks/session-start确认 hooks/hooks.json 中命令直接指向session-start且脚本行尾为 LF验证开启新会话让 agent 做一个小任务正常应先进入 brainstorming 提问而非直接写代码。Windows 下钩子报错、终端卡死或技能静默失效现象PowerShell 报解析器错误路径含(等字符时 cmd 命令被截断钩子无任何输出但技能不生效。原因钩子命令串以带引号的路径开头PowerShell 会把引号串当表达式解析cmd 的引号剥离规则会在特殊字符处截断命令见 RELEASE-NOTES.md v6.2.0 Windows 章节。更早的版本还存在 CRLF 行尾符导致脚本损坏的问题现已通过.gitattributes强制 LF 行尾修复。步骤将 Claude Code 升级到 ≥ 2.1.81并安装 Git for Windows——钩子现声明shell: bash由 Git Bash 执行缺失时会弹出可操作的安装提示更新 Superpowers 到最新发行版各终端cmd / PowerShell / Git Bash的具体安装差异参考 docs/windows/polyglot-hooks.md 与 docs/README.opencode.md验证新开会话无解析报错、无终端冻结技能正常触发。Ubuntu/Debian 上出现 Bad substitution现象钩子执行时输出Bad substitution原因这些系统默认/bin/sh是 dash而旧版 hooks/session-start 使用了${BASH_SOURCE[0]:-$0}这类 bash 专有写法历史问题 #553、#141。步骤将 Superpowers 升级到 v5.0.3 之后的版本——脚本已改为 POSIX 安全的$0写法并全面使用#!/usr/bin/env bash可移植 shebang。验证bash hooks/session-start无报错且输出技能列表即修复完成。安装时提示 Plugin not found现象/plugin install提示Plugin not found。原因最常见是未先注册 Superpowers 市场就直接按市场源安装此外 v6.0.2 之前附带的evals子模块曾导致部分用户插件安装中断#1778、#1774已在新版中移除。步骤先注册市场再安装/plugin marketplace add obra/superpowers-marketplace /plugin install superpowerssuperpowers-marketplace或使用官方市场一行安装/plugin install superpowersclaude-plugins-officialCodex 用户走插件市场搜索安装输入/plugins搜索superpowers选择Install Plugin验证命令无报错新会话启动时能看到 Superpowers 引导内容加载。升级或重装后提示技能未找到现象OpenCode 等平台上升级后技能列表为空重装时符号链接步骤报file already exists。原因OpenCode 的技能依赖符号链接注册到~/.config/opencode/skills/superpowers/旧版文档曾遗漏该步骤直接覆盖式重装会因链接已存在而失败。步骤按 docs/README.opencode.md 删除旧链接后重建符号链接旧安装会被自动备份skills.bak升级后检查个人技能是否已从备份迁移当前版本 OpenCode 插件通过config钩子自动注册技能目录只需在opencode.json中一行配置确认该行存在验证运行插件结构检查脚本见下文确认修好了。确认修好了用项目自带测试脚本验证以下脚本都在tests/目录对应各平台自检source tests/opencode/setup.sh—— 创建隔离的临时测试环境避免污染真实配置tests/opencode/test-plugin-loading.sh—— 验证插件安装是否完整、技能目录结构是否正确tests/opencode/run-tests.sh—— 运行 OpenCode 全套插件测试tests/hooks/test-session-start.sh—— 验证session-start钩子输出tests/claude-code/run-skill-tests.sh—— 运行 Claude Code 技能行为测试tests/shell-lint/test-lint-shell.sh—— 对全部 shell 脚本做语法 lint提前暴露Bad substitution类问题✅ 对应平台的脚本全部通过即可认为环境恢复正常。仍然解决不了求助渠道与上报清单按顺序尝试查文档docs/ 目录包含完整使用与移植指南平台专属问题优先查对应 README如 docs/README.opencode.md、docs/README.kimi.md查发布记录多数报错在 RELEASE-NOTES.md 中带 issue 编号记录过按报错关键词搜索往往直接找到修复版本提交 issue在项目的 issue 跟踪系统报告项目方也提供 Discord 社区支持内置能力排查 Superpowers 自身脚本问题时可以直接让 agent 调用systematic-debugging技能做四阶段根因分析例如 skills/systematic-debugging/find-polluter.sh 这类脚本有配套的确定性测试 tests/systematic-debugging/test-find-polluter.sh 可对照上报问题时请附上以下信息可显著加快定位完整报错内容与出现时机安装 / 会话启动 / 技能触发Superpowers 版本号与所用 harness 及其版本Claude Code / Codex / OpenCode…操作系统与终端类型Linux/macOS/Windowscmd、PowerShell 或 Git Bash手动执行bash hooks/session-start的完整输出【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考