13.4 OpenCode SDK

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

---

Plugin 通过 PluginInput.client 获得一个 OpenCode SDK 客户端实例。本节简要介绍 SDK 的设计和使用方式。

13.4.1 @opencode-ai/sdk——TypeScript 客户端 SDK

@opencode-ai/sdk 是 OpenCode 的官方 TypeScript SDK，位于 packages/sdk/ 目录。它提供了与 OpenCode Server API 完全对应的类型安全客户端。

SDK 是基于 OpenAPI 规范自动生成的——当 Server 的 API 发生变化时，SDK 可以通过 opencode generate 命令重新生成，确保 API 和 SDK 始终保持同步。

13.4.2 createOpencodeClient() 的使用方式

import { createOpencodeClient } from "@opencode-ai/sdk/v2"

const sdk = createOpencodeClient({
  baseUrl: "http://localhost:4096",
  directory: "/path/to/project",
  fetch: customFetch,  // 可选：自定义 fetch 实现
  signal: abortSignal,  // 可选：取消信号
})

SDK 客户端提供了以下 API 命名空间：

// Session 管理
sdk.session.create({})
sdk.session.list()
sdk.session.get({ sessionID: "..." })
sdk.session.chat({ sessionID, content })
sdk.session.abort({ sessionID })
sdk.session.fork({ sessionID })

// 消息管理
sdk.message.list({ sessionID })
sdk.message.get({ sessionID, messageID })

// 配置管理
sdk.config.get()

// 事件订阅
sdk.event.subscribe({})

// Provider/Model
sdk.provider.list()
sdk.model.list()

// MCP
sdk.mcp.list()

// Permission
sdk.permission.list()
sdk.permission.reply({ requestID, action })

// 其他
sdk.project.get()
sdk.file.read({ path })
sdk.pty.create({})

13.4.3 基于 OpenAPI 规范的自动生成

SDK 的生成流程：

1. Server 定义路由：使用 Hono 框架定义 API 路由，路由参数使用 Zod Schema。

2. 生成 OpenAPI 规范：opencode generate 命令遍历所有路由，利用 Zod Schema 和 BusEvent.payloads() 生成 OpenAPI JSON 文档。

3. 生成 SDK 代码：基于 OpenAPI 文档自动生成 TypeScript 客户端代码。

这种"Schema → OpenAPI → SDK"的流水线确保了三个产物的一致性：

Zod Schema (Server 端)
    ↓ 自动提取
OpenAPI 规范 (API 文档)
    ↓ 自动生成
TypeScript SDK (客户端)

13.4.4 在 Plugin 中使用 SDK

Plugin 不需要自己创建 SDK 客户端——PluginInput.client 已经提供了一个配置好的实例。这个实例使用了内部的 fetch 实现（直接调用 Server.App().fetch()），不经过 HTTP 网络层，延迟更低。

const myPlugin: Plugin = async (ctx) => {
  // 使用 SDK 读取会话列表
  const sessions = await ctx.client.session.list()

  // 使用 SDK 获取项目信息
  const project = await ctx.client.project.get()

  return {
    "chat.message": async (input, output) => {
      // 在消息中注入项目统计信息
      const stats = await ctx.client.stats()
      output.parts.push({
        type: "text",
        text: `[Project Stats] ${stats.sessions} sessions, ${stats.messages} messages`,
      })
    },
  }
}

13.4.5 小结

OpenCode SDK 的设计遵循了"单一来源"原则：

1. Zod Schema 是唯一的类型定义来源——Server 路由、OpenAPI 文档、SDK 类型都从 Zod Schema 派生。

2. OpenAPI 是 API 契约的标准表达——人类可读的文档和机器可读的客户端生成器都以它为输入。

3. SDK 是自动生成的——避免了手动维护客户端代码的一致性问题。

这种自动化流水线使得 OpenCode 的 API 可以快速迭代——修改 Server 端的 Zod Schema 后，一条命令即可更新 OpenAPI 文档和 SDK。