OpenCode + Superpowers 安装教程

OpenCode 的超能力

最近 Claude Code 的 Skills 功能火得一塌糊涂。很多兄弟问我：这玩意儿到底是个啥？

说白了，它就是给 AI 也就是 Claude 发了一本操作手册 。以前你让 AI 干活，得费劲写一大堆提示词，它还经常发挥不稳定。现在有了 Skills，等于直接把“怎么干活”的流程固化下来了，AI 照着做，又快又稳。

这两天我把 GitHub 翻了个底朝天，从几十个仓库里挑出了 1个最好用的 。不管你是写代码的、搞科研的，还是做自媒体的，这里面绝对有你能用的东西。

废话不多说，直接上干货。

什么来头 ：专为软件开发设计的“一条龙”服务。

• 有啥用 ：这个库最牛的地方在于技能连招 。它不是散乱的工具，而是一套工作流：
  • 先用 brainstorming 搞头脑风暴
  • 再用 writing-plans 写技术方案
  • 接着 executing-plans 执行代码
  • 最后 verification 验证结果
• 评价 ：如果你是用 OpenCode 写代码，这个库能让你少掉好几根头发。

安装

前提条件

• 已安装 OpenCode.ai
• 已安装 Node.js
• 已安装 Git

安装步骤

1. 安装 Superpowers

   mkdir -p ~/.config/opencode/superpowers
   git clone https://github.com/obra/superpowers.git
   npm install -g @opencode-ai/plugin
   

2. 注册插件
   OpenCode 从 ~/.config/opencode/plugin/ 发现插件。创建软链接：

   mkdir -p ~/.config/opencode/plugin
   ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js ~/.config/opencode/plugin/superpowers.js
   
   # powershell命令：
   New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\opencode\plugin\superpowers.js" -Target "$env:USERPROFILE\.config\opencode\superpowers\.opencode\plugin\superpowers.js" -Force
   

   或者，进行项目本地安装：

   # 在你的 OpenCode 项目中
   mkdir -p .opencode/plugin
   ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js .opencode/plugin/superpowers.js
   
   # powershell命令：
   New-Item -ItemType SymbolicLink -Path ".opencode\plugin\superpowers.js" -Target "$env:USERPROFILE\.config\opencode\superpowers\.opencode\plugin\superpowers.js" -Force
   

3. 重启 OpenCode
   重启 OpenCode 以加载插件。Superpowers 将自动激活。

使用

查找技能
使用 find_skills 工具列出所有可用技能：

use find_skills tool

加载技能
使用 use_skill 工具加载特定技能：

use use_skill tool with skill_name: "superpowers: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 项目中创建项目特定技能：

# 在你的 OpenCode 项目中
mkdir -p .opencode/skills/my-project-skill

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

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

# My Project Skill

[Your skill content here]

技能优先级
技能按以下优先级顺序解析：

1. 项目技能 (.opencode/skills/) - 最高优先级
2. 个人技能 (~/.config/opencode/skills/)
3. Superpowers 技能 (~/.config/opencode/superpowers/skills/)

你可以强制解析到特定级别：

• project:skill-name - 强制使用项目技能
• skill-name - 搜索顺序：项目 → 个人 → superpowers
• superpowers:skill-name - 强制使用 superpowers 技能

功能

自动上下文注入
插件通过 chat.message 钩子在每个会话中自动注入 superpowers 上下文。无需手动配置。

消息插入模式
当你使用 use_skill 加载技能时，它会以 noReply: true 的方式作为用户消息插入。这确保了技能在长对话中持续存在，即使 OpenCode 压缩了上下文。

压缩恢复能力
插件监听 session.compacted 事件，并在上下文压缩后自动重新注入核心 superpowers 引导程序以保持功能。

工具映射
为 Claude Code 编写的技能会自动适配 OpenCode。插件提供映射说明：

• TodoWrite → update_plan
• 带子代理的任务 → OpenCode 的 @mention 系统
• 技能工具 → use_skill 自定义工具
• 文件操作 → 原生 OpenCode 工具

架构

插件结构

• 位置：~/.config/opencode/superpowers/.opencode/plugin/superpowers.js
• 组件：
  • 两个自定义工具：use_skill、find_skills
  • chat.message 钩子用于初始上下文注入
  • session.compacted 事件处理器用于重新注入
  • 使用共享的 lib/skills-core.js 模块（也被 Codex 使用）

共享核心模块

• 位置：~/.config/opencode/superpowers/lib/skills-core.js
• 功能：
  • extractFrontmatter() - 解析技能元数据
  • stripFrontmatter() - 从内容中移除元数据
  • findSkillsInDir() - 递归发现技能
  • resolveSkillPath() - 带覆盖的技能解析
  • checkForUpdates() - Git 更新检测

该模块在 OpenCode 和 Codex 实现之间共享，以实现代码重用。

更新

cd ~/.config/opencode/superpowers
git pull

重启 OpenCode 以加载更新。

故障排除

插件未加载

• 检查插件文件是否存在：ls ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js
• 检查软链接：ls -l ~/.config/opencode/plugin/superpowers.js
• 检查 OpenCode 日志：opencode run "test" --print-logs --log-level DEBUG
• 查找：service=plugin path=file:///.../superpowers.js loading plugin

技能未找到

• 验证技能目录：ls ~/.config/opencode/superpowers/skills
• 使用 find_skills 工具查看发现了什么
• 检查技能结构：每个技能都需要一个 SKILL.md 文件

工具不工作

• 验证插件已加载：检查 OpenCode 日志中的插件加载消息
• 检查 Node.js 版本：插件需要 Node.js 以支持 ES 模块
• 手动测试插件：node --input-type=module -e "import('file://~/.config/opencode/plugin/superpowers.js').then(m => console.log(Object.keys(m)))"

上下文未注入

• 检查 chat.message 钩子是否工作
• 验证 using-superpowers 技能是否存在
• 检查 OpenCode 版本（需要支持插件的最新版本）

获取帮助

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

测试
实现包含位于 tests/opencode/ 的自动化测试套件：

# 运行所有测试
./tests/opencode/run-tests.sh --integration --verbose

# 运行特定测试
./tests/opencode/run-tests.sh --test test-tools.sh

测试验证：

• 插件加载
• Skills-core 库功能
• 工具执行（use_skill、find_skills）
• 技能优先级解析
• 使用临时 HOME 的适当隔离