架構

Stitch SDK 不是手寫的 REST 用戶端，而是建構在 Model Context Protocol（MCP）之上的產生式領域層，目標是提供流暢的 TypeScript API，同時為 Stitch 提供的每個工具保留單一事實來源。

為什麼是 MCP，而不是 REST？

Stitch 已經運行一個供 AI 代理程式直接連線的 MCP 伺服器。SDK 不再維護另一套獨立的 REST API 介面，而是透過 HTTP 連線至同一個 MCP 伺服器。這代表：

• 單一 API 介面。 SDK 可用的工具與你的 AI 代理程式使用的工具完全相同，不會出現落差。
• 即時更新。 MCP 伺服器推出新工具時，SDK 產生器會自動納入。
• 代理程式相容。 無論你是在 SDK 指令碼或 AI 代理程式中，相同的 callTool 語意都能運作。

三個層次

SDK 具有明確的三層架構：

┌─────────────────────────────────┐
│     stitch (singleton proxy)     │  ← What you import
├─────────────────────────────────┤
│  Stitch / Project / Screen       │  ← Generated domain classes
├─────────────────────────────────┤
│       StitchToolClient           │  ← MCP-over-HTTP transport
└─────────────────────────────────┘

第 1 層：StitchToolClient（傳輸）

這是基礎層。透過 HTTP 連線到 Stitch MCP 伺服器、處理身分驗證（API 金鑰或 OAuth），並為任何 MCP 工具公開原始的 callTool(name, params)。如果你需要完全的控制權，可以直接使用這一層。

第 2 層：產生的領域類別（領域）

Stitch、Project 與 Screen 是從兩個來源檔案自動產生的：

1. tools-manifest.json——每個 MCP 工具名稱、說明與輸入結構描述的快照。
2. domain-map.json——手動撰寫的對應表，將工具指派給領域類別與方法。

產生指令碼會讀取這兩個檔案，並在 generated/src/ 中產生 TypeScript 類別。每個方法都是 callTool 的精簡包裝，負責處理參數對應與回應解析。

產生程序受到內容雜湊鎖定——只有在資訊清單或領域對應表確實變更時，重新產生才會帶來變更，藉此避免無謂的異動。

第 3 層：stitch 單例（便利層）

一個 Proxy 物件，會依環境變數延遲初始化 StitchToolClient，並依方法名稱將方法呼叫委派給 Stitch 領域類別或 StitchToolClient。

當你撰寫 stitch.projects() 時，代理物件會路由到 Stitch.projects()；當你撰寫 stitch.callTool(...) 時，則路由到 StitchToolClient.callTool()。

身分對應模式

stitch.project(id) 與 new Project(client, id) 不必發出 API 呼叫，就能建立控制代碼。它們會解析 ID（去除任何 projects/ 前置詞），並傳回 Project 物件，你可以立即對它呼叫 .generate()、.screens() 或 .getScreen()。

當你從先前的操作得知專案 ID 時，這個模式就很實用——你不需要重新擷取。

AI SDK 轉接器

stitchTools()（來自 @google/stitch-sdk/ai）將 SDK 橋接到 Vercel AI SDK 生態系。它會讀取相同的 tools-manifest.json，並產生與 generateText() 和 streamText() 相容的 Record<string, Tool>。

這個轉接器對 ai 套件沒有任何執行階段相依性。它使用 Symbol.for("vercel.ai.schema") 重建工具結構描述格式——在不匯入 AI SDK 任何程式碼的情況下，對應其內部通訊協定。這讓只使用領域 API 的取用者能保持 SDK 輕量。

錯誤處理

所有領域方法都會在內部攔截錯誤，並以具結構化錯誤代碼的 StitchError 執行個體重新擲回。這讓你有單一錯誤型別可以攔截：

import { StitchError } from "@google/stitch-sdk";

try {
  await screen.edit("...");
} catch (e) {
  if (e instanceof StitchError) {
    console.error(e.code, e.message);
  }
}