第 12 章：SDK、外掛開發與生態系統

12.1 OpenCode SDK

OpenCode SDK 是一組開發工具與函式庫，讓開發者能夠建立自訂工具、外掛以及與 OpenCode 深度整合的應用程式。SDK 封裝了與 OpenCode 核心互動所需的所有底層細節，提供簡潔的 API 介面。

SDK 核心功能

快速入門

使用 npm 初始化 SDK 專案：

# 建立新專案
mkdir my-opencode-plugin
cd my-opencode-plugin
npm init -y

# 安裝 OpenCode SDK
npm install @opencode/sdk

# 建立基本工具
touch tools/my-tool.js

12.2 Server Mode：API 伺服器

OpenCode 可以透過 opencode serve 指令以伺服器模式執行，提供 HTTP API 供外部應用程式呼叫。這使得 OpenCode 可以整合到 CI/CD 管線、Web 應用程式或其他自動化流程中。

啟動伺服器

# 啟動 OpenCode 伺服器（預設埠 3000）
opencode serve

# 指定埠號
opencode serve --port 8080

# 啟用 CORS（跨域請求）
opencode serve --cors

# 指定允許的來源
opencode serve --cors --origin https://myapp.example.com

API 使用範例

// 透過 HTTP API 呼叫 OpenCode
const response = await fetch('http://localhost:3000/api/execute', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    task: 'Explain the architecture of this project',
    context: {
      files: ['src/index.ts', 'src/config.ts'],
      directory: process.cwd()
    }
  })
});

const result = await response.json();
console.log(result.output);

整合 CI/CD

Server Mode 讓 OpenCode 可以無縫整合到 CI/CD 流程中：

# GitHub Actions 範例
jobs:
  code-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 啟動 OpenCode Review
        run: |
          opencode serve --port 3000 &
          sleep 2
          curl -X POST http://localhost:3000/api/execute \
            -H "Content-Type: application/json" \
            -d '{
              "task": "Review this PR diff for bugs",
              "context": { "git_diff": true }
            }'

12.3 外掛開發

外掛（Plugin）是 OpenCode 生態系統的基礎單元。一個外掛可以包含多個工具、設定面板、生命週期掛鉤與資產檔案。

外掛目錄結構

my-opencode-plugin/
├── package.json          # 套件資訊與相依性
├── index.js              # 外掛入口點
├── tools/                # 自訂工具
│   ├── tool-a.js
│   └── tool-b.js
├── hooks/                # 生命週期掛鉤
│   ├── before-task.js
│   └── on-error.js
├── assets/               # 靜態資源
│   └── icon.svg
├── config/               # 設定範本
│   └── defaults.json
└── README.md             # 外掛文件

建立第一個外掛

// index.js — 外掛入口點
const { Plugin } = require('@opencode/sdk');

class MyPlugin extends Plugin {
  constructor() {
    super({
      name: 'my-plugin',
      version: '1.0.0',
      description: '我的第一個 OpenCode 外掛'
    });
  }

  // 外掛初始化
  async onActivate(context) {
    console.log('外掛已啟動！');
    
    // 註冊工具
    this.registerTool('hello-world', {
      description: '向使用者打招呼',
      schema: {
        type: 'object',
        properties: {
          name: { type: 'string', description: '你的名字' }
        },
        required: ['name']
      },
      handler: async (params) => {
        return { message: `哈囉，${params.name}！歡迎使用 OpenCode！` };
      }
    });

    // 註冊生命週期掛鉤
    this.registerHook('beforeTask', async (task) => {
      console.log(`即將執行任務：${task.name}`);
    });
  }

  // 外掛停用
  async onDeactivate() {
    console.log('外掛已停用');
  }
}

module.exports = MyPlugin;

安裝外掛

外掛可以透過 opencode.json 註冊：

{
  "plugins": [
    {
      "name": "my-plugin",
      "path": "./plugins/my-plugin",
      "enabled": true
    },
    {
      "name": "community-formatter",
      "version": "2.1.0",
      "enabled": false
    }
  ]
}

12.4 OpenCode 生態系統

OpenCode 不僅僅是一個工具——它是一個正在成長的開發者生態系統。以下介紹生態系統的主要組成部分：

第三方整合

12.5 分享會話

OpenCode 提供了 opencode share 命令，讓開發者可以分享當前的會話狀態給團隊成員或社群：

# 分享當前會話
opencode share

# 分享並包含檔案變更
opencode share --include-diff

# 分享到特定平台
opencode share --platform discord

# 輸出為可攜式檔案
opencode share --output session.json

分享的會話包含：完整的對話歷史、所有工具呼叫記錄、檔案變更摘要與執行結果。這對於團隊協作、問題除錯與知識分享非常有價值。

12.6 如何貢獻 OpenCode

OpenCode 是一個開源專案，歡迎各種形式的貢獻：

12.7 社群資源總覽

以下是參與 OpenCode 生態系統的重要連結與資源：

📝 本章測驗

❓ 常見問題