13.1 Plugin 接口定义

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-17

---

前面几个部分我们完成了 OpenCode 核心架构的解析。从本章开始，我们进入生态篇——探索 OpenCode 如何通过 Plugin、Skill、MCP 等机制实现可扩展性。

Plugin 系统是 OpenCode 最核心的扩展机制——第三方开发者可以通过 Plugin 注入自定义工具、修改 LLM 调用参数、拦截消息、监听事件，甚至改变 Agent 的行为模式。oh-my-opencode（第 15 章将详细剖析）就是构建在 Plugin 系统之上的。

13.1.1 @opencode-ai/plugin 包的类型定义

Plugin 的类型定义位于 packages/plugin/ 包中，这是一个独立的 npm 包（@opencode-ai/plugin），只包含 TypeScript 类型定义——没有运行时代码。这种设计使得 Plugin 开发者只需安装这个轻量级的类型包即可获得完整的类型提示。

Plugin 类型

Plugin 的核心类型定义非常简洁：

// packages/plugin/src/index.ts
export type Plugin = (input: PluginInput) => Promise<Hooks>

一个 Plugin 就是一个异步函数——接收 PluginInput 上下文，返回 Hooks 对象。这种函数式设计比基于类的设计更灵活：Plugin 可以是一个简单的箭头函数，也可以是一个复杂的工厂函数。

PluginInput：Plugin 的上下文

export type PluginInput = {
  client: ReturnType<typeof createOpencodeClient>  // OpenCode SDK 客户端
  project: Project                                   // 当前项目信息
  directory: string                                  // 工作目录
  worktree: string                                   // Git 工作树根目录
  serverUrl: URL                                     // Server 地址
  $: BunShell                                        // Bun Shell（用于执行命令）
}

字段	类型	用途
client	SDK 客户端	通过 API 与 OpenCode Server 交互
project	Project	当前项目的元信息（ID、VCS 类型等）
directory	string	当前工作目录的绝对路径
worktree	string	Git 仓库根目录的绝对路径
serverUrl	URL	内嵌 HTTP Server 的地址
$	BunShell	Bun 的 Shell API，可执行系统命令

PluginInput 提供了 Plugin 运行所需的所有环境信息。client 字段特别重要——它让 Plugin 可以通过标准 API 与 OpenCode 交互，而不需要直接引用内部模块。

Hooks 接口

Hooks 是 Plugin 的核心——它定义了 Plugin 可以挂载的所有生命周期钩子：

export interface Hooks {
  // 事件监听
  event?: (input: { event: Event }) => Promise<void>

  // 配置注入
  config?: (input: Config) => Promise<void>

  // 自定义工具注册
  tool?: { [key: string]: ToolDefinition }

  // 认证扩展
  auth?: AuthHook

  // 消息钩子
  "chat.message"?: (input, output) => Promise<void>

  // LLM 参数钩子
  "chat.params"?: (input, output) => Promise<void>

  // 请求头钩子
  "chat.headers"?: (input, output) => Promise<void>

  // 权限钩子
  "permission.ask"?: (input, output) => Promise<void>

  // 命令执行前钩子
  "command.execute.before"?: (input, output) => Promise<void>

  // 工具执行前/后钩子
  "tool.execute.before"?: (input, output) => Promise<void>
  "tool.execute.after"?: (input, output) => Promise<void>

  // Shell 环境变量钩子
  "shell.env"?: (input, output) => Promise<void>

  // 实验性：消息列表变换
  "experimental.chat.messages.transform"?: (input, output) => Promise<void>

  // 实验性：系统提示词变换
  "experimental.chat.system.transform"?: (input, output) => Promise<void>

  // 实验性：压缩过程钩子
  "experimental.session.compacting"?: (input, output) => Promise<void>

  // 实验性：文本完成钩子
  "experimental.text.complete"?: (input, output) => Promise<void>
}

所有钩子函数都遵循统一的 (input, output) => Promise<void> 签名模式：

• input：只读的上下文信息（谁触发了这个钩子、在什么场景下）。

• output：可修改的输出对象（Plugin 通过修改这个对象来影响行为）。

这种 input/output 分离模式 是 OpenCode Plugin 设计的精髓——Plugin 不直接返回结果，而是原地修改 output 对象。这使得多个 Plugin 可以链式处理同一个事件：每个 Plugin 在前一个 Plugin 修改后的 output 基础上继续修改。

13.1.2 ToolDefinition：Plugin 工具定义

Plugin 可以通过 tool 钩子注册自定义工具：

// packages/plugin/src/tool.ts
export type ToolDefinition = {
  description?: string
  parameters: Record<string, {
    type: string
    description?: string
    required?: boolean
    enum?: string[]
  }>
  execute: (args: any, context: ToolContext) => Promise<ToolResult>
}

export type ToolContext = {
  sessionID: string
  messageID: string
  abort: AbortSignal
}

export type ToolResult = {
  output: string
  title?: string
  metadata?: any
}

Plugin 工具的定义比内部工具更简单——不需要 Zod Schema，使用普通对象描述参数。OpenCode 内部会通过 fromPlugin() 适配器将其转换为标准的 Tool.Info 格式。

13.1.3 AuthHook：认证扩展

AuthHook 是一种特殊的钩子，允许 Plugin 为特定的 LLM Provider 提供认证方式：

export type AuthHook = {
  provider: string           // 关联的 Provider（如 "openai"、"anthropic"）
  loader?: (auth, provider) => Promise<Record<string, any>>
  methods: (OAuthMethod | ApiKeyMethod)[]
}

OpenCode 内置了三个认证 Plugin：

• CodexAuthPlugin：为 OpenAI Codex 提供 OAuth 认证。

• CopilotAuthPlugin：为 GitHub Copilot 提供 OAuth 认证。

• GitlabAuthPlugin：为 GitLab AI 提供 OAuth 认证。

认证方法支持两种模式：

• OAuth：通过浏览器跳转进行授权，返回 url 和 callback。

• API Key：直接输入 API 密钥。

13.1.4 一个最简 Plugin 示例

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

const myPlugin: Plugin = async (ctx) => {
  console.log(`Plugin loaded for project: ${ctx.project.id}`)

  return {
    // 注册自定义工具
    tool: {
      "my-search": {
        description: "Search the web",
        parameters: {
          query: { type: "string", description: "Search query", required: true },
        },
        execute: async (args) => ({
          output: `Results for: ${args.query}`,
        }),
      },
    },

    // 修改 LLM 参数
    "chat.params": async (input, output) => {
      output.temperature = 0.7  // 覆盖温度设置
    },

    // 监听事件
    event: async ({ event }) => {
      if (event.type === "session.created") {
        console.log("New session:", event.properties.info.id)
      }
    },
  }
}

export default myPlugin

这个示例展示了 Plugin 的三种常见能力：注册工具、修改参数、监听事件。Plugin 函数接收项目上下文并返回一个 Hooks 对象——所有钩子都是可选的，只实现需要的即可。