SuperAPI AI 工具集

writing-opencode-plugins

编程与开发

查看项目

更新于 11-02 01:51

技能介绍

本技能用于指导 OpenCode 插件的开发,适用于创建或修改 OpenCode 插件时的项目搭建、测试与发布。

用途与项目结构:建议采用 shim 模式把开发代码与插件加载分开。项目根目录包含 src/main.ts(主实现)、.opencode/(插件依赖与 plugin 加载入口)、test/(单元与端到端测试)、package.json 和 tsconfig.json。.opencode/plugins/ 下的 shim 文件由 OpenCode 加载,并从 src 重新导出插件,例如 export { PluginName as PluginNamePlugin } from "../../src/main"。这种结构便于使用 TypeScript 进行类型安全开发、编写测试,并避免在 .opencode/ 中重复源码。

插件结构与钩子:插件导出一个函数,接收上下文参数并返回钩子对象。上下文参数包括 directory(当前工作目录)、worktree(Git worktree 路径)、project(项目信息)、client(OpenCode SDK 客户端)和 $(Bun shell API)。资料列出的常用钩子有 shell.env(在 shell 执行前注入环境变量)、tool.execute.before(拦截工具调用)、tool.execute.after(后处理工具结果)和 file.edited(响应文件变更)。

测试方式:单元测试使用 bun test,隔离测试核心逻辑,示例中包含临时目录的创建与清理。端到端测试通过 opencode run 命令验证插件与 OpenCode CLI 的集成,若找不到 CLI 则跳过。测试数据可放在 test/fixtures/ 中,包括基础、复杂和端到端场景。

依赖与发布:根 package.json 包含开发依赖、脚本和发布信息,依赖 @opencode-ai/plugin 1.2.10;.opencode/package.json 只包含运行时依赖,OpenCode 启动时会自动在 .opencode/ 执行 bun install。发布可使用 np(bunx np --any-branch)或手动 npm version 加 npm publish --access public,并提供 .npmignore 排除测试、本地插件目录和开发文件。

配置与实践:TypeScript 采用严格模式与 Bun 默认设置;AGENTS.md 建议用 Bun 替代 Node.js、npm、pnpm 或 vite。开发流程为编辑 src/main.ts、运行 bun test,重启 OpenCode 后 shim 自动重新加载。插件安装分为项目级(.opencode/plugins/ 自动加载)、全局(复制到 ~/.config/opencode/plugins/)和从 npm 安装(在 opencode.json 的 plugin 字段添加包名,OpenCode 自动安装到缓存目录)。最佳实践包括把可测试逻辑从钩子中抽离、使用 try/catch 处理错误、钩子均为异步、在设置前检查输出以避免不必要的修改,以及用 quiet 模式抑制日志。CI/CD 示例使用 GitHub Actions 与 oven-sh/setup-bun@v2 运行 bun install 和 bun test。

限制:资料未提供具体价格、平台支持范围或插件运行时性能数据,这些暂未提供;使用前需具备 Bun、TypeScript 与 OpenCode 环境。