使用 SDK

你是 OpenCode SDK 導航顧問。

【角色】
OpenCode SDK 導航顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- 想用 SDK 做什麼：___
- 現成功能為什麼不夠：___
- 團隊開發能力：___
- 維護投入：___
- 經驗水平：___

【工作流程】
1. 判斷是否需要 SDK
2. 說明 SDK 能力
3. 評估成本
4. 給入門路徑
5. 給第一步

【輸出規範】
▌一、是否需要
▌二、SDK 能力
▌三、成本
▌四、入門 + 第一步

【硬約束】
- 現成夠用就不用 SDK
- 評估維護成本
- 憑據安全處理
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

OpenCode JS/TS SDK 是 opencode server 的型別安全客戶端。它適合把 OpenCode 接進你自己的工具、後臺服務、自動化平臺或產品介面。

新手先記住：SDK 不是用來替代 TUI 的第一入口。你已經能在 TUI / CLI 裡穩定完成任務後，才應該考慮 SDK。

SDK 整合路徑

SDK 是 server 的型別安全客戶端，不是模型 API 的簡單 wrapper。

flowchart LR
  TUI["TUI / CLI 已跑通"] --> Server{"server 誰來管理?"}
  Server -->|SDK 啟動| Local["本地工具 / 一次性實驗"]
  Server -->|外部已有| Client["client-only 連線已有 server"]
  Local --> Prompt["只讀 prompt"]
  Client --> Prompt
  Prompt --> Structured["結構化輸出"]
  Structured --> Product["業務系統 / dashboard / 佇列 / PR 檢查"]

  style TUI fill:#dbeafe,stroke:#3b82f6
  style Prompt fill:#dcfce7,stroke:#22c55e,stroke-width:2px
  style Product fill:#fef3c7,stroke:#f59e0b

先理解：SDK 解決什麼問題

TUI 解決“人和 OpenCode 互動”。

CLI 解決“從命令列觸發任務”。

Server 解決“OpenCode 對外提供可呼叫 API”。

SDK 解決“你的 JS/TS 程式型別安全地呼叫 server”。

如果你只是想手動改程式碼，用 TUI。如果你只是想在指令碼里跑一次任務，先看 CLI。如果你要讓內部系統建立 session、傳送 prompt、讀取結果、做結構化輸出、整合到業務流程裡，才用 SDK。

兩種使用方式怎麼選

第一種是 SDK 幫你啟動 server，並返回 client。這適合本地工具、桌面輔助指令碼和一次性整合實驗。

第二種是 client-only，連線已經執行的 opencode server。這適合已有後臺服務、共享 server、容器化部署或你想自己控制 server 生命週期的場景。

新手先用第一種驗證 API 呼叫，再用第二種做真實整合。不要一開始就把 server 生命週期、認證、埠、記錄、錯誤處理全混在一起。

設定怎麼理解

SDK 可以傳入 config 覆蓋或補充本機 opencode.json。這適合測試不同模型、切換 provider、限制工具或為某個整合定製行為。

但不要把憑據塞進 SDK 程式碼。provider key 仍然應該由 /connect、環境變數或安全憑據系統管理。

如果 SDK 程式碼要進儲存庫，設定裡只放可公開的模型名、provider 名和行為策略，不放 token。

結構化輸出什麼時候用

官方 SDK 支援透過 JSON Schema 請求結構化輸出。它適合讓下游程式消費結果，例如風險報告、專案後設資料、釋出摘要、分類標籤、檢查清單。

結構化輸出不是為了讓回答更好看，而是為了讓程式能穩定解析。

新手寫 schema 時要簡單：欄位少、描述清楚、required 明確。複雜巢狀 schema 會增加模型失敗和重試成本。

錯誤處理要先設計

SDK 整合一定會遇到錯誤：server 啟動失敗、埠被佔、模型請求失敗、session id 無效、結構化輸出校驗失敗、網路超時。

新手不要只寫 happy path。至少要處理：

• server 是否啟動成功。
• client 是否連到正確 base URL。
• prompt 是否返回錯誤物件。
• 結構化輸出是否失敗並需要重試。
• 操作結束後 server 是否需要關閉。

新手常見坑

• TUI 還沒跑通就寫 SDK：問題會被包裝層掩蓋。
• 把 SDK 當模型 API：它控制的是 OpenCode server，不只是呼叫 LLM。
• 不管理 server 生命週期：本地殘留程序、埠衝突、測試互相影響。
• 把 API key 寫進程式碼：SDK 示例裡出現 config，不代表憑據可以進儲存庫。
• schema 太複雜：結構化輸出頻繁失敗，最後又回到自然語言解析。
• 忽略 TypeScript 型別：SDK 的價值之一就是讓 API shape 在開發時暴露出來。

一個穩妥的整合路線

第一步，在 TUI 裡確認 provider、model、permissions 和專案設定都能工作。

第二步，用 SDK 做一個只讀健康檢查：連線 server，確認版本和目前專案。

第三步，建立一個最小 session，傳送一個只讀 prompt，讀取結果。

第四步，加入結構化輸出，讓結果變成固定欄位。

第五步，再接入業務系統，例如 PR 檢查、內部 dashboard、任務佇列或釋出流程。

第二步的最小骨架大概長這樣（虛擬碼 / 概念示意，具體匯入名以官方 SDK 目前版本為準）：

import { createOpencodeClient, createOpencodeServer } from "@opencode-ai/sdk";

// 方式 A：让 SDK 自己启动一个临时 server（适合本地工具）
const server = await createOpencodeServer({ hostname: "127.0.0.1", port: 0 });
const client = createOpencodeClient({ baseUrl: server.url });

// 健康检查：先确认能连通
const { data: health } = await client.app.get();
console.log("opencode 已连接：", health);

// 用完关掉 server，避免后台进程残留
await server.close();

如果你已經在外部用 opencode serve 起了一個 server，跳過 createOpencodeServer，只把 baseUrl 指向那個 server 的地址即可（外部啟動時記得設 OPENCODE_SERVER_PASSWORD + 在 client 裡帶上 basic auth header）。

怎麼驗收

整合完成後，至少確認：

• 能說明 server 是 SDK 啟動的，還是外部已執行的。
• 能區分 server 未啟動、client base URL 錯誤、模型失敗、許可權失敗和結構化輸出失敗。
• SDK 程式碼裡沒有 key、token 和私有設定。
• 輸入輸出由 TypeScript 型別約束，不是到處寫 any。
• 本地 server 在任務結束後能關閉，避免測試和開發環境殘留。

接下來去哪

官方資料

• SDK：https://opencode.ai/docs/sdk
• Server：https://opencode.ai/docs/server
• Ecosystem：https://opencode.ai/docs/ecosystem