SuperAPI AI 工具集

opencode-plugin-authoring

编程与开发

查看项目

更新于 10-27 13:49

技能介绍

用途:该技能面向为 opencode 编写插件的开发者,提供可复用的生命周期模板、事件模型、配置方式与本地安装路径,减少重新查阅文档的探索成本。

主要能力:

  1. 插件生命周期:默认导出异步函数,参数为 (context, options),其中 context 解构出 $、directory、project、client、worktree;options 来自 opencode.json 中该插件的配置,是第二个位置参数。返回对象可包含 event 处理器,接收 { event }。
  2. 事件面:event.type 为字符串枚举,已验证包含 session.idle(回合完成—代理结束并等待用户输入,是“完成通知”的标准事件)和 session.error(会话出错)。技能明确不要查找 session.complete、session.end、session.finish。
  3. $ 辅助函数:解构出的 $ 是 Bun shell 模板字面量,模板表达式自动转义,适合用户提供的值;禁止使用 child_process.exec 或字符串拼接。
  4. 配置双通道:插件选项(opencode.json 中的 [路径, 选项对象] 元组)优先;环境变量通过 process.env 读取。技能强调插件条目只能是字符串或二元组,对象形式会被拒绝,并建议以实际 schema 为准。示例中环境变量应放在 ~/.zshenv 而非 ~/.zshrc,因为 daemon/launchd 启动的 opencode 不读取后者。密钥不得提交到仓库。
  5. 名称查重:提交前用 curl 检查 npm 名称是否可用(404 可用、200 已占用),并用 gh repo view 检查 GitHub 名称。技能列出已知被占用名称(opencode-notify、opencode-notification、opencode-alert)和可用名称(opencode-push,截至 2026-07-09)。
  6. 包结构:index.ts(默认导出插件)、package.json(type: module,main/module 指向 index.ts,devDependencies 含 @opencode-ai/plugin)、README.md、.gitignore。
  7. 本地安装:机制 A 为符号链接到 ~/.config/opencode/plugins/,自动加载,无需改 opencode.json;机制 B 为 opencode.json 插件数组中引用路径或二元组,可传选项。从机制 A 切换到 B 时需先删除符号链接以避免重复加载。安装后重启 opencode。
  8. 重装/更新:先确认安装方式。机制 A 下 git pull 后重启即可;机制 B 下 git pull 后重启;安装脚本类插件重跑 install.sh。

使用方式:从生命周期模板开始编写插件,按事件表选择 session.idle 等事件;通过插件选项或环境变量配置;用符号链接或 opencode.json 安装;重启 opencode 加载。

适用场景:需要构建带通知/钩子的 opencode 插件、本地开发调试插件、通过插件配置而非环境变量实现 daemon 环境下的稳定加载。

限制与注意事项:事件面仅列出已验证的 session.idle 和 session.error;插件在加载时缓存环境变量,修改配置后需从新 shell 重启 opencode;daemon/launchd 启动链只读取 ~/.zshenv;诊断环境变量问题时建议先检查运行中进程的实际环境,再检查配置文件;技能明确不保证未列出的功能、平台或收费信息。