企业官网建设流程全解析

Superpowers 在 OpenCode 中更新后不生效或插件加载失败怎么排查？

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

Superpowers 在 OpenCode 中是通过opencode.json的plugin数组以 git 包规格安装的插件。常见的两类故障是：更新 Superpowers 仓库后新内容不生效，或者插件根本没加载（问它"你的 superpowers"没有反应、skill工具里列不出 superpowers 技能）。docs/README.opencode.md 的 Troubleshooting 一节把这两种现象拆成了四条排查路径：插件未加载、更新不生效、技能找不到、bootstrap 不出现。本文按文档给出的检查顺序，从确认配置到查日志、清缓存、换安装方式，给出一条连续的排查路径。适用前提是你在 OpenCode 中安装了 Superpowers 插件。

先判断故障属于哪一种

排查前先对照 docs/README.opencode.md 的四个故障类别确定起点：

确认安装配置与基线验证

排查的第一步是回到安装配置本身。Superpowers 在 OpenCode 中的安装方式是：在opencode.json（全局或项目级）的plugin数组中加入：

{ "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"] }

修改后必须重启 OpenCode——插件通过 OpenCode 的插件管理器安装并注册全部技能，配置变更不会热生效。

基线验证方式是直接向会话提问：Tell me about your superpowers。如果这一步正常，说明插件加载与技能注册都没问题，故障大概率是"更新不生效"一类，直接跳到下一节。

插件没加载：先看 OpenCode 日志

docs/README.opencode.md 给出的插件未加载排查顺序是：

1. 查看 OpenCode 日志，过滤 superpowers 相关行：

opencode run --print-logs "hello" 2>&1 | grep -i superpowers

2. 核对opencode.json中的plugin行是否正确（包名、git+https地址是否完整）。
3. 确认你在运行较新版本的 OpenCode。

这条命令会以非交互方式跑一次 OpenCode 并打印日志，再用grep过滤，本身不修改环境。日志里出现 superpowers 相关报错，就能直接定位是安装、依赖还是配置问题；完全无输出，则优先怀疑配置行或 OpenCode 版本。

更新后不生效：锁文件或缓存钉住了旧提交

这是文档专门说明的一类问题：OpenCode 通过 git-backed 包规格安装 Superpowers，部分 OpenCode 和 Bun 版本会把已解析的 git 依赖钉在锁文件或缓存里，所以仅重启可能拿不到最新的 Superpowers 提交。

文档给出的处理方式是：如果更新没有出现，清除 OpenCode 的包缓存，或重新安装插件（文档原文为 "clear OpenCode's package cache or reinstall the plugin"，未给出统一的清缓存命令，以你本地 OpenCode 的缓存位置为准）。

另外，如果你想固定到某个版本而不是跟着 main 走，可以在包规格后加分支或 tag：

{ "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"] }

也就是说，"更新不生效"既可能是缓存钉住了旧提交（清缓存/重装解决），也可能是你本来就钉了 tag（改成 main 或更新 tag 才生效），两种情况要先区分清楚再动手。

技能找不到：先确认插件加载，再查 SKILL.md

文档对 "Skills not found" 的排查步骤：

1. 用 OpenCode 原生skill工具列出可用技能，看实际发现了什么：

use skill tool to list skills

2. 确认插件本身在加载（即上一节的日志检查）。
3. 每个技能都需要一个带合法 YAML frontmatter 的SKILL.md文件，frontmatter 损坏的技能不会被发现。

加载单个技能同样走skill工具，例如：

use skill tool to load brainstorming

文档还明确了技能优先级：项目技能 > 个人技能 > Superpowers 技能。项目技能放在项目的.opencode/skills/，个人技能放在~/.config/opencode/skills/。如果你发现同名技能加载出来的是 Superpowers 自带版本而不是你的项目版本，这是 OpenCode 当前对重名技能的行为（tests/opencode/test-priority.sh 把它记录为已知的待上游改进行为），不是你的安装坏了。

Bootstrap 不出现：检查 hook 支持与重启

Superpowers 插件通过experimental.chat.messages.transformhook 给每个会话注入 bootstrap 上下文。文档对 bootstrap 缺失的排查只有两条：

1. 确认你的 OpenCode 版本支持experimental.chat.messages.transformhook；
2. 修改配置后重启 OpenCode。

如果你更新 Superpowers 后 bootstrap 行为变了，而skill工具列技能一切正常，优先核对 OpenCode 侧版本，而不是反复重装 Superpowers。

Windows 上装不上插件：改用系统 npm 装本地包

文档记录了一部分 Windows OpenCode 构建在处理 git-backed 包规格时的上游安装器问题，包括git+httpsURL 的缓存路径问题，以及 Bun 在普通终端里能找到git.exe却在 OpenCode 里找不到。

如果 OpenCode 始终无法安装插件，文档给的替代路径是：用系统 npm 把包装到 OpenCode 配置目录，再把opencode.json指向本地包路径。

npm install superpowers@git+https://github.com/obra/superpowers.git --prefix "$HOME\.config\opencode"

这条命令的副作用是把 superpowers 安装到~/.config\opencode目录下（含node_modules），不改动系统全局环境。之后在opencode.json中改用文档给出的本地包路径写法：

{ "plugin": ["~/.config/opencode/node_modules/superpowers"] }

从旧版 symlink 安装迁移

如果你以前是用git clone+ symlink 的方式装的 Superpowers，旧文件会与新插件管理器冲突。docs/README.opencode.md 给出的清理命令如下——注意这些命令会永久删除你本地的旧安装文件，确认~/.config/opencode下没有需要保留的其他内容后再执行：

# Remove old symlinks rm -f ~/.config/opencode/plugins/superpowers.js rm -rf ~/.config/opencode/skills/superpowers # Optionally remove the cloned repo rm -rf ~/.config/opencode/superpowers # Remove skills.paths from opencode.json if you added one for superpowers

最后一条是注释项：如果opencode.json里曾为 superpowers 加过skills.paths，一并删除。清理完再按标准安装步骤配置plugin数组。

可选：用仓库自带测试套件做结构化验证

仓库自带一套 OpenCode 插件测试，入口是 tests/opencode/run-tests.sh。它在mktemp临时目录里搭建隔离环境（结束后自动清理），不触碰你真实的 OpenCode 配置。常用方式：

bash tests/opencode/run-tests.sh --test test-plugin-loading.sh

--test参数让它只跑指定测试，而不是整套；test-plugin-loading.sh验证插件文件结构、skills 目录、bootstrap 路径引用等；test-tools.sh和test-priority.sh属于集成测试，需要先装好 OpenCode，且要加--integration才会运行。脚本会对仓库内的测试文件执行chmod +x以保证可执行，其余读写都发生在临时目录。

边界与后续

• OpenCode 有独立的插件安装，如果你同时用 Claude Code、Codex 等其他 harness，Superpowers 需要在每个 harness 里分别安装，不能互相复用。
• 排查完配置、日志、缓存三条主线后仍有问题，文档建议到项目仓库的 issues 区报告（主文档 docs/README.opencode.md 的 Getting Help 一节）。
• 技能内部动作到 OpenCode 工具的映射表（如 "Create a todo" →todowrite、子代理模板 →task工具）也记录在 docs/README.opencode.md 的 Tool Mapping 一节，遇到技能行为与预期工具不符时可按此表核对。

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