SDK 與開發者擴展

摘要

本章是所有章節的巔峰——從消費者變成創造者。你將學習如何使用 @opencode-ai/sdk 建立自己的工具與應用，理解 opencode 的 HTTP API 架構，開發自訂外掛，並將 opencode 整合到 Zed、JetBrains、Neovim 等編輯器中。無論你想為 opencode 生態貢獻外掛，還是將 opencode 嵌入自家產品，本章都會給你完整的指引。

學習目標

• 學會安裝與使用 @opencode-ai/sdk
• 理解 SDK 的核心 API 分類與使用時機
• 掌握結構化輸出（JSON Schema）的用法
• 能架設 HTTP API 伺服器並設定認證
• 開發一個自訂外掛並載入到 opencode 中
• 設定 ACP 編輯器整合
• 了解 opencode 生態系統與社群資源

@opencode-ai/sdk 安裝與客戶端建立

@opencode-ai/sdk 是 opencode 的官方 Node.js SDK，提供程式化操作 opencode 所有功能的 API。

安裝

npm install @opencode-ai/sdk

建立客戶端

import { OpenCode } from '@opencode-ai/sdk'

const client = new OpenCode({
  apiKey: process.env.ANTHROPIC_API_KEY,
  // 可選：指定自訂伺服器位址
  baseUrl: 'http://localhost:8080'
})

// 快速測試連線
const info = await client.app.info()
console.log(info.version)

SDK 支援 TypeScript 型別定義，提供完整的 IDE 自動完成支援。

核心 API 分類

SDK 的 API 按照功能領域分類，每個分類對應不同的操作場景：

實際使用範例

import { OpenCode } from '@opencode-ai/sdk'

const oc = new OpenCode({ apiKey: process.env.ANTHROPIC_API_KEY })

// 列出所有工作階段
const sessions = await oc.session.list()
console.log(`共有 ${sessions.length} 個工作階段`)

// 在目前專案中搜尋
const results = await oc.find.grep('TODO', { include: '*.ts' })
console.log(`找到 ${results.length} 個 TODO`)

// 讀取並編輯檔案
const content = await oc.file.read('src/app.ts')
await oc.file.write('src/app.ts', content + '\n// updated by SDK')

// 監聽事件
oc.event.on('session:created', (session) => {
  console.log('新工作階段開始:', session.id)
})

結構化輸出（JSON Schema）

opencode 支援 結構化輸出，讓你可以要求 AI 回應符合特定 JSON Schema 的資料，而非自然語言。這對於程式化處理回應特別有用。

在 SDK 中使用

import { OpenCode } from '@opencode-ai/sdk'

const oc = new OpenCode({ apiKey: process.env.ANTHROPIC_API_KEY })

const result = await oc.app.complete({
  prompt: '分析此專案的 package.json，列出所有過時的依賴',
  responseSchema: {
    type: 'object',
    properties: {
      dependencies: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            name: { type: 'string' },
            current: { type: 'string' },
            latest: { type: 'string' },
            severity: { type: 'string', enum: ['low', 'medium', 'high'] }
          },
          required: ['name', 'current', 'latest', 'severity']
        }
      }
    },
    required: ['dependencies']
  }
})

console.log(JSON.stringify(result, null, 2))

支援的 Schema 功能

• 基本型別：string、number、boolean、array、object
• 列舉：透過 enum 限制允許的值
• 巢狀結構：任意深度的物件嵌套
• 條件約束：minimum、maximum、minLength、pattern 等
• 遞迴結構：透過 $ref 定義遞迴型別

伺服器架構

opencode 本身可以作為 HTTP 伺服器執行，提供 RESTful API 供外部工具呼叫。

啟動 HTTP 伺服器

opencode serve --port 8080 --api-key sk-internal-key

API 端點

啟動後可透過 HTTP 呼叫所有 SDK 功能。例如：

# 取得應用資訊
curl http://localhost:8080/api/app/info \
  -H "Authorization: Bearer sk-internal-key"

# 送出提示
curl -X POST http://localhost:8080/api/app/complete \
  -H "Authorization: Bearer sk-internal-key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "解釋這個專案的架構",
    "responseSchema": { "type": "object" }
  }'

OpenAPI 3.1 文件

啟動伺服器後，可透過以下路徑取得完整的 OpenAPI 3.1 規格文件：

# OpenAPI JSON
curl http://localhost:8080/api/openapi.json

# Swagger UI
# 瀏覽器開啟 http://localhost:8080/api/docs

這份文件可以用於自動產生客戶端程式碼、匯入 Postman 或整合到 API Gateway。

認證保護

HTTP API 支援多種認證方式：

• Bearer Token：透過 Authorization: Bearer <token> 標頭
• API Key：透過 X-API-Key 標頭
• mTLS：雙向 TLS 認證，適合內部服務通訊

# 啟動時指定認證方式
opencode serve \
  --port 8080 \
  --api-key sk-internal-key \
  --tls-cert server.crt \
  --tls-key server.key \
  --mtls-ca ca.crt

外掛系統深入

opencode 的外掛系統讓你可以擴展幾乎任何功能。每個外掛本質上就是一個目錄，包含 opencode-plugin.json 設定檔與實作程式碼。

事件類型

外掛可以訂閱以下事件類別：

開發範例：日誌記錄外掛

以下是一個完整的外掛範例，記錄所有工作階段的開始與結束：

{
  "name": "session-logger",
  "version": "1.0.0",
  "description": "記錄所有工作階段",
  "events": ["session:start", "session:end"],
  "main": "index.js"
}

// index.js
const fs = require('fs')
const logFile = '/tmp/opencode-sessions.log'

module.exports = {
  async 'session:start'({ sessionId, project }) {
    const entry = `[${new Date().toISOString()}] START ${sessionId} in ${project}\n`
    fs.appendFileSync(logFile, entry)
  },

  async 'session:end'({ sessionId, duration, tokens }) {
    const entry = `[${new Date().toISOString()}] END ${sessionId} (${duration}ms, ${tokens} tokens)\n`
    fs.appendFileSync(logFile, entry)
  }
}

安裝外掛

# 本地外掛
opencode plugin add ./path/to/session-logger

# 從 npm 安裝
opencode plugin add @company/opencode-session-logger

ACP 支援

ACP（Agent Communication Protocol） 是 opencode 定義的通訊協定，讓外部編輯器可以與 opencode 互動。ACP 支援以下編輯器：

Zed

Zed 是對 opencode 支援最完善的編輯器之一，原生整合 ACP：

# 在 Zed 設定中啟用
// ~/.config/zed/settings.json
{
  "agent": {
    "opencode": {
      "enabled": true,
      "apiKey": "sk-ant-xxxxx"
    }
  }
}

JetBrains（IntelliJ IDEA、WebStorm 等）

透過 OpenCode ACP Plugin 安裝：

# 從 JetBrains Marketplace 安裝外掛
# 或手動安裝
opencode acp install jetbrains

安裝後可在 JetBrains 的工具視窗中找到 opencode 面板，支援程式碼選取、內嵌編輯、問題提問等功能。

Neovim

Neovim 用戶可以透過社群外掛整合：

-- 使用 lazy.nvim 安裝
{
  "opencode-ai/opencode.nvim",
  config = function()
    require('opencode').setup({
      api_key = vim.env.ANTHROPIC_API_KEY,
      keymaps = {
        ask = 'aa',
        edit = 'ae',
        explain = 'ax',
      }
    })
  end
}

自訂 ACP 客戶端

你也可以透過 SDK 建立自訂 ACP 客戶端：

import { ACPClient } from '@opencode-ai/sdk/acp'

const client = new ACPClient({
  endpoint: 'http://localhost:8080/acp',
  apiKey: 'sk-key'
})

// 傳送選取的程式碼給 opencode
const result = await client.ask({
  selection: 'function add(a,b){return a+b}',
  prompt: '為此函數添加 TypeScript 型別'
})

生態系統

opencode 擁有活躍且快速成長的生態系統，以下是一些值得關注的資源：

知名外掛

• opencode-docgen：自動產生 API 文件並發布到 Confluence
• opencode-jira：從 Jira 擷取任務描述，自動建立分支與 PR
• opencode-slack：將工作階段摘要發送到 Slack 頻道
• opencode-sentry：分析 Sentry 錯誤並建議修復方案
• opencode-db：資料庫 Schema 視覺化與查詢最佳化建議

相關專案

• opencode-web：基於 opencode SDK 的 Web 聊天介面
• opencode-server：團隊協作伺服器（企業版基礎）
• opencode-mcp：MCP 伺服器整合套件
• opencode-bench：代理效能基準測試工具

社群資源

• GitHub：github.com/anthropics/opencode — 原始碼、Issues、Discussions
• 官方文件：opencode.ai/docs/zh-tw/ — 完整繁體中文文件
• Discord：opencode 官方 Discord 伺服器 — 即時技術討論
• npm：@opencode-ai/sdk、@opencode-ai/opencode

實戰練習