create-opencode-plugin

创建 OpenCode 插件

在插件开发过程中定期重新阅读此文件，以刷新上下文并确保遵循正确的流程。

流程概览

步骤	操作	阅读
1	验证 SDK 参考文档	运行提取脚本
2	验证可行性	本文件
3	设计插件	references/hooks.md、references/hook-patterns.md、references/CODING-TS.MD
4	实现	references/tool-helper.md（如使用自定义工具）
5	添加 UI 反馈	references/toast-notifications.md、references/ui-feedback.md（如有需要）
6	测试	references/testing.md
7	发布	references/publishing.md、references/update-notifications.md（如使用 npm）

---

步骤 1：验证 SDK 参考文档（必需）

创建任何插件之前，必须重新生成 API 参考文档，以确保其准确无误：

bun run .opencode/skill/create-opencode-plugin/scripts/extract-plugin-api.ts

这将生成：

• references/hooks.md - 所有可用钩子及其签名
• references/events.md - 所有事件类型及属性
• references/tool-helper.md - 工具创建模式

---

步骤 2：验证可行性（必需）

必须确定用户的构想是否能通过现有钩子实现。

可作为插件实现：

• 拦截／阻止工具调用
• 响应事件（文件编辑、会话完成等）
• 为大模型添加自定义工具
• 修改大模型参数（温度等）
• 为提供商自定义身份验证流程
• 自定义会话压缩
• 显示状态消息（Toast、内嵌消息）

无法实现（请告知用户）：

• 修改 TUI 渲染或布局
• 添加新的内置工具（需要修改 OC 源码）
• 更改核心 Agent 行为／提示词
• 在助手响应流中途进行拦截
• 添加新的快捷键或命令
• 修改内部文件读写
• 添加新的权限类型

如果无法实现，必须明确告知用户。建议：

• 修改 OC 核心：为 packages/opencode 贡献代码
• MCP 工具：使用 MCP 服务配置
• 简单自动化：使用 shell 脚本

---

步骤 3：设计插件

阅读：references/hooks.md，了解可用钩子；references/hook-patterns.md，了解实现模式。

阅读：references/CODING-TS.MD，了解代码架构原则。必须遵循以下设计指南：

• 模块化结构：将复杂插件拆分为多个职责明确的文件（类型、实用工具、钩子、工具）
• 单一职责：每个函数只做好一件事
• DRY：立即将通用模式提取到共享实用工具中
• 保持文件精简：每个文件不超过 150 行；按需拆分为更小的模块
• 避免单体文件：不得将所有插件代码放在单个 index.ts 文件中

插件位置

范围	路径	使用场景
项目	.opencode/plugin/<name>/index.ts	团队共享、特定于仓库
全局	~/.config/opencode/plugin/<name>/index.ts	个人使用，适用于所有项目

基本结构

import type { Plugin } from "@opencode-ai/plugin"

export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  // Setup code runs once on load

  return {
    // Hook implementations - see references/hook-patterns.md
  }
}

上下文参数

参数	类型	描述
project	Project	当前项目信息（id、工作树、名称）
client	SDK Client	OpenCode API 客户端
$	BunShell	用于运行命令的 Bun shell
directory	string	当前工作目录
worktree	string	Git 工作树路径

---

第 4 步：实现

阅读：references/hook-patterns.md，了解钩子实现示例。

阅读：如果要添加自定义工具（Zod 架构），请阅读 references/tool-helper.md。

阅读：如果要使用事件钩子（事件类型/属性），请阅读 references/events.md。

阅读：references/examples.md，查看完整的插件示例。

务必阅读：references/CODING-TS.MD，并遵循模块化设计原则。

插件结构（非单体）

对于复杂插件，必须使用模块化目录结构：

.opencode/plugin/my-plugin/
├── index.ts          # Entry point, exports Plugin
├── types.ts          # TypeScript types/interfaces
├── utils.ts          # Shared utilities
├── hooks/            # Hook implementations
│   ├── event.ts
│   └── tool-execute.ts
└── tools/            # Custom tool definitions
    └── my-tool.ts

模块化 index.ts 示例：

import type { Plugin } from "@opencode-ai/plugin"
import { eventHooks } from "./hooks/event"
import { toolHooks } from "./hooks/tool-execute"
import { customTools } from "./tools"

export const MyPlugin: Plugin = async ({ project, client }) => {
  return {
    ...eventHooks({ client }),
    ...toolHooks({ client }),
    tool: customTools,
  }
}

每个文件控制在 150 行以内。随着复杂度增加，将内容拆分到多个文件中。

常见错误

错误	修复方法
使用 client.registerTool()	使用 tool: { name: tool({...}) }
事件属性名称错误	查看 references/events.md
同步事件处理程序	必须使用 async
未抛出异常以阻止操作	在 tool.execute.before 中使用 throw new Error()
忘记 TypeScript 类型	import type { Plugin } from "@opencode-ai/plugin"

---

第 5 步：添加 UI 反馈（可选）

仅当插件需要向用户显示通知时：

阅读：references/toast-notifications.md，了解短暂提醒（简短弹窗）

阅读：references/ui-feedback.md，了解持久的内联状态消息

根据以下需求选择：

需求	使用
简短提醒、警告	Toast
详细统计、多行内容	内联消息
配置验证错误	Toast
会话完成通知	Toast 或内联消息

---

第 6 步：测试

阅读：references/testing.md，了解完整的测试流程。

快速测试步骤

1. 使用 opencode.json 创建测试文件夹：

   {
     "plugin": ["file:///path/to/your/plugin/index.ts"],
   }
   

2. 验证插件是否加载：

   cd /path/to/test-folder
   opencode run hi
   

3. 交互式测试：

   opencode
   

4. 应根据使用的钩子类型推荐具体测试。

---

第 7 步：发布（可选）

阅读：references/publishing.md，了解 npm 发布。

阅读：references/update-notifications.md，了解版本更新提示（适用于固定版本的用户）。

<reference_summary>

Reference Files Summary

File	Purpose	When to Read
hooks.md	Hook signatures (auto-generated)	Step 3-4
events.md	Event types (auto-generated)	Step 4 (if using events)
tool-helper.md	Zod tool schemas (auto-generated)	Step 4 (if custom tools)
hook-patterns.md	Hook implementation examples	Step 3-4
CODING-TS.MD	Code architecture principles	Step 3 (Design)
examples.md	Complete plugin examples	Step 4
toast-notifications.md	Toast popup API	Step 5 (if toasts needed)
ui-feedback.md	Inline message API	Step 5 (if inline needed)
testing.md	Testing procedure	Step 6
publishing.md	npm publishing	Step 7
update-notifications.md	Version toast pattern	Step 7 (for npm plugins)

</reference_summary>