跳转至

适用于 OpenCode 的 Superpowers

使用 Superpowers 配合 OpenCode.ai 的完整指南。

安装

OpenCode V2 需要 2.0.4 或更高版本。

OpenCode V1

使用现有的 V1 插件配置：

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

OpenCode V2（2.0.4 或更高版本）

使用 V2 插件配置：

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

对于本地 V2 安装，请配置包含 index.js 的仓库目录。OpenCode 2.0.4 和 2.0.7 会拒绝已配置的直接 JavaScript 文件路径。已发现的插件符号链接仍然受支持。

重启 OpenCode。V2 使用 opencode 命令；opencode2 可能作为别名可用。该插件通过 OpenCode 的插件管理器安装，并注册所有技能。

可通过提问来验证：“跟我说说你的 superpowers”

如果你之前使用 git clone 和符号链接安装过 superpowers，请移除旧配置：

# 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 原生的 skill 工具列出所有可用的技能：

use skill tool to list skills

加载技能

use skill tool to load brainstorming

个人技能

在 ~/.config/opencode/skills/ 中创建你自己的技能：

mkdir -p ~/.config/opencode/skills/my-skill

创建 ~/.config/opencode/skills/my-skill/SKILL.md：

---
name: my-skill
description: Use when [condition] - [what it does]
---

# My Skill

[Your skill content here]

项目技能

在项目内的 .opencode/skills/ 目录中创建项目专属技能。

V2 技能优先级： 项目技能 > 个人技能 > Superpowers 技能。在测试过的 V1 1.18.31 上，当某个个人或项目技能与内置 Superpowers 技能同名时，内置技能优先；请为个人和项目技能使用不同的名称。此行为不因迁移而改变。

更新

OpenCode 通过基于 git 的包规范安装 Superpowers。某些 OpenCode 和 Bun 版本会在 lockfile 或缓存中固定已解析的 git 依赖，因此重启后可能不会获取最新的 Superpowers 提交。如果更新没有出现，请清除 OpenCode 的包缓存或重新安装插件。

要固定特定版本，请在规范中添加一个标签或提交（V1 的 plugin 键和 V2 的 plugins 键使用相同格式）：

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

在 V2 上，请固定 v6.4.1 或更高版本；v6.3.0 及更早版本只能在 V1 上加载。

工作原理

该插件使用特定宿主版本的 API 做两件事：

  1. 注册技能目录，使 OpenCode 无需符号链接或手动配置即可发现所有 Superpowers 技能。
    • V1： 通过 config 钩子注入到 config.skills.paths
    • V2： 通过 setup() 函数使用 ctx.skill.transform()（V2 原生 API，已在运行时确认生效）
  2. 注入引导上下文，并带有特定版本的工具映射：V1 会话获取下面的 V1 工具名称，V2 会话获取 V2 名称。
    • V1： 通过 experimental.chat.messages.transform 钩子
    • V2： 通过 ctx.session.hook("context") —— V2 的等效方式（已在运行时确认生效）

控制器会话会在瞬态模型上下文中接收 using-superpowers 引导。委托的子会话保留对原生技能的访问，但不会接收控制器引导。没有父会话的手动 fork 会保持控制器行为。当 V2 原生压缩保留了较早的用户消息（默认的 compaction.keep.tokens 预算）时，引导会像未压缩会话一样，放到检查点之前的首个保留用户消息中。当压缩移除了所有用户消息时，插件会在检查点后追加一条瞬态引导消息。无论哪种方式，已保存的历史记录都不会改变。

如果会话查找失败，插件会为该请求保留引导，并在下一个请求时重试。失败的查找不会作为控制器决策被缓存。

工具映射

技能以动作来表达，而不是直接指定某个运行时的工具名称。引导会将它们映射到你的 OpenCode 版本实际暴露的工具。

V1（opencode 1.x）：

  • “创建待办” / “在待办列表中标记完成” → todowrite
  • Subagent (general-purpose): 模板 → OpenCode 的 task 工具，使用 subagent_type: "general"（或代码库探索时使用 "explore"）
  • “调用技能” → OpenCode 原生的 skill 工具
  • “读取文件” → read
  • “创建文件” / “编辑文件” / “删除文件” → apply_patch
  • “运行 shell 命令” → bash
  • “搜索文件内容” / “按名称查找文件” → grep、glob
  • “获取 URL” → webfetch

V2（opencode 2.0.4 或更高版本；opencode2 可能作为别名可用）：

  • “创建待办” → V2 没有任何待办工具；映射会指示模型改为在 markdown 文件（或运行框架的规划工具）中跟踪计划
  • Subagent (general-purpose): 模板 → OpenCode 的 subagent 工具，使用 agent: "general"（或 "explore"）；传递 sessionID 可继续之前的 subagent
  • “调用技能” → OpenCode 原生的 skill 工具
  • “读取文件” → read
  • “创建、编辑或删除文件” → 在可用时使用带 patchText 的 patch；否则使用 write 创建或覆盖文件，使用 edit 进行针对性修改，使用 shell 进行删除
  • “运行 shell 命令” → shell（command、workdir、timeout、background）
  • “搜索文件内容” / “按名称查找文件” → grep、glob
  • “获取 URL” → webfetch
  • “搜索网络” → websearch

简而言之，V2 将 task 重命名为 subagent（代理名称从 subagent_type 移到了 agent，并通过使用 sessionID 重新调用来继续），将 apply_patch 重命名为 patch，将 bash 重命名为 shell，并完全移除了待办工具。可用的修改工具取决于所选模型：对于选定的 GPT 模型 ID，可使用 patch，而其他模型则使用 write 和 edit。

（V1 列表已根据已安装的 OpenCode 1.18.x CLI 的工具清单进行验证；V2 列表已根据 OpenCode 2.0.4 和 2.0.7 宿主契约进行验证。）

故障排除

插件未加载

V1： 检查 OpenCode 日志：

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

V2： 插件在后台服务器中加载，其日志只有在 --standalone 下才会通过 --print-logs 显示：

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

或者检查 ~/.local/share/opencode/log/opencode.log，并筛选 role=server。

同时确认 opencode.json 中的插件路径正确，并且你正在运行较新版本的 OpenCode。

Windows 安装问题

某些 Windows 版 OpenCode 构建在上游安装程序处理基于 git 的插件规范时存在问题，包括 git+https URL 的缓存路径，以及 Bun 即使在普通终端中可用也找不到 git.exe。如果 OpenCode 无法安装插件，请尝试使用系统 npm 安装，并让 OpenCode 指向本地包：

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

然后在 opencode.json 中使用已安装包的绝对路径，以匹配你的 OpenCode 版本。OpenCode 不会展开 ~；~/... 条目会被视为包名，而不是本地目录。

V1：

{
  "plugin": ["C:\\Users\\<you>\\.config\\opencode\\node_modules\\superpowers"]
}

V2（2.0.4 或更高版本）：

{
  "plugins": ["C:\\Users\\<you>\\.config\\opencode\\node_modules\\superpowers"]
}

未找到技能

  1. 使用 OpenCode 的 skill 工具列出可用技能
  2. 检查插件是否正在加载（见上文）
  3. 每个技能都需要一个包含有效 YAML 前置元数据的 SKILL.md 文件

Bootstrap 未出现

  • V1： 检查 OpenCode 版本是否支持 experimental.chat.messages.transform 钩子。配置更改后重启 OpenCode。
  • V2： 插件使用 ctx.session.hook("context") 进行 Bootstrap 注入。通过 opencode api get /api/plugin 验证插件已加载。配置更改后使用 opencode service restart 重启。opencode2 命令可能作为别名可用。

获取帮助

  • 报告问题：https://github.com/obra/superpowers/issues
  • 主要文档：https://github.com/obra/superpowers
  • OpenCode V2 文档：https://opencode.ai/v2/docs/
  • OpenCode V1 文档：https://opencode.ai/docs/

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 su/superpowers