參考 | Stitch 繁體中文文件

安裝

npm install @google/stitch-sdk

匯出項目

所有匯出項目都可從 @google/stitch-sdk 取得：

import {
  stitch,           // Default singleton instance
  Stitch,           // Domain class: project management
  Project,          // Domain class: screen management within a project
  Screen,           // Domain class: screen operations
  StitchToolClient, // Low-level MCP client
  StitchProxy,      // Local proxy server
  StitchError,      // Error class
  StitchErrorCode,  // Error code enum
} from "@google/stitch-sdk";

AI SDK 轉接器（獨立子路徑）：

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

`stitch`（單例）

預設的進入點。一個延遲初始化的 Proxy，結合了 Stitch 領域方法與 StitchToolClient 基礎結構方法。

首次存取時會從環境變數讀取 STITCH_API_KEY 與 STITCH_HOST。

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

領域方法

方法	傳回	說明
`createProject(title)`	`Promise<Project>`	建立新專案。
`projects()`	`Promise<Project[]>`	列出已驗證使用者可存取的所有專案。
`project(id)`	`Project`	從既有的專案 ID 或資源名稱建立 `Project` 控制代碼。不會發出 API 呼叫。

基礎結構方法

方法	傳回	說明
`listTools()`	`Promise<{ tools: ToolDefinition[] }>`	列出所有可用的 MCP 工具。
`callTool<T>(name, params)`	`Promise<T>`	依名稱呼叫原始的 MCP 工具。
`close()`	`Promise<void>`	關閉底層的 MCP 用戶端連線。

`Stitch`

主要的進入點類別，負責管理專案。

import { Stitch, StitchToolClient } from "@google/stitch-sdk";

const client = new StitchToolClient({ apiKey: "..." });
const s = new Stitch(client);

建構函式

參數	型別	說明
`client`	`StitchToolClient`	已初始化的工具用戶端執行個體。

方法

方法	傳回	說明
`createProject(title)`	`Promise<Project>`	建立新專案。對應至 MCP 工具 `create_project`。
`projects()`	`Promise<Project[]>`	列出所有專案。對應至 MCP 工具 `list_projects`。
`project(id)`	`Project`	不發出 API 呼叫即可建立 `Project` 控制代碼。接受專案 ID 或完整資源名稱（`projects/{id}`）。

`Project`

包含螢幕的 Stitch 專案。

屬性

屬性	型別	說明
`projectId`	`string`	專案 ID（不含 `projects/` 前置詞）。
`id`	`string`	`projectId` 的別名。
`data`	`any`	原始的 API 回應資料（若由伺服器回應建構）。若由 ID 字串建構則為 `undefined`。

方法

方法	參數	傳回	說明
`generate(prompt, deviceType?, modelId?)`	`prompt: string`, `deviceType?: DeviceType`, `modelId?: ModelId`	`Promise<Screen>`	從文字提示詞產生新的螢幕。對應至 `generate_screen_from_text`。
`screens()`	-	`Promise<Screen[]>`	列出專案中的所有螢幕。對應至 `list_screens`。
`getScreen(screenId)`	`screenId: string`	`Promise<Screen>`	依 ID 擷取特定螢幕。對應至 `get_screen`。
`upload(filePath, opts?)`	`filePath: string`, `opts?: { title?: string, createScreenInstances?: boolean }`	`Promise<UploadResult>`	上傳檔案（`.png`、`.jpg`、`.jpeg`、`.webp`、`.html`、`.htm`）並建立螢幕。直接傳送到 REST API。絕不會擲回例外——而是傳回可判別的結果。
`createDesignSystem(ds)`	`ds: { displayName: string }`	`Promise<DesignSystem>`	為此專案建立設計系統。
`listDesignSystems()`	-	`Promise<DesignSystem[]>`	列出專案中的所有設計系統。
`designSystem(id)`	`id: string`	`DesignSystem`	從資產 ID 建立 `DesignSystem` 控制代碼。不會發出 API 呼叫。
`uploadDesignMd(designMdBase64)`	`designMdBase64: string`	`Promise<any>`	將 DESIGN.md 檔案（base64 編碼）上傳到專案。傳回螢幕執行個體。對應至 `upload_design_md`。
`createDesignSystemFromDesignMd(selectedScreenInstance, deviceType?)`	`selectedScreenInstance: SelectedScreenInstance`, `deviceType?: DeviceType`	`Promise<DesignSystem>`	從上傳的 DESIGN.md 建立設計系統。對應至 `create_design_system_from_design_md`。

`DesignSystem`

為專案定義視覺權杖的設計系統資產。

屬性

屬性	型別	說明
`id`	`string`	資產 ID。
`data`	`any`	原始的 API 回應資料。若由 ID 字串建構則為 `undefined`。

方法

方法	參數	傳回	說明
`update(ds)`	`ds: { displayName?: string }`	`Promise<DesignSystem>`	更新設計系統的中繼資料。
`apply(selectedScreenInstances)`	`{ id: string, sourceScreen: string }[]`	`Promise<Screen[]>`	將此設計系統套用到指定的螢幕。只傳入 `id` 與 `sourceScreen`——額外欄位會造成錯誤。

`Screen`

產生的 UI 螢幕，提供 HTML 程式碼與截圖影像的存取。

屬性

屬性	型別	說明
`projectId`	`string`	上層專案 ID。
`screenId`	`string`	螢幕 ID。
`id`	`string`	`screenId` 的別名。
`data`	`any`	原始的 API 回應資料。

方法

方法	參數	傳回	說明
`edit(prompt, deviceType?, modelId?)`	`prompt: string`, `deviceType?: DeviceType`, `modelId?: ModelId`	`Promise<Screen>`	以文字提示詞編輯此螢幕。傳回新的 `Screen`；原始物件不會改變。對應至 `edit_screens`。
`variants(prompt, variantOptions, deviceType?, modelId?)`	`prompt: string`, `variantOptions: VariantOptions`, `deviceType?: DeviceType`, `modelId?: ModelId`	`Promise<Screen[]>`	產生設計變體。對應至 `generate_variants`。
`getHtml()`	-	`Promise<string>`	傳回此螢幕的 HTML 下載 URL。若有快取 URL 則使用快取。
`getImage()`	-	`Promise<string>`	傳回截圖下載 URL。若有快取 URL 則使用快取。

`StitchToolClient`

透過 HTTP 連線到 Stitch 伺服器的低階 MCP 用戶端。

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

建構函式

參數	型別	說明
`config`	`StitchConfigInput`	連線設定。

`StitchConfigInput`

欄位	型別	必填	說明
`apiKey`	`string`	`apiKey` 或 `accessToken` 其中之一	用於身分驗證的 API 金鑰。
`accessToken`	`string`	`apiKey` 或 `accessToken` 其中之一	OAuth 存取權杖。
`projectId`	`string`	搭配 `accessToken` 時必填	Google Cloud 專案 ID（用於 OAuth）。
`baseUrl`	`string`	否	覆寫伺服器 URL。預設為 `https://stitch.googleapis.com/mcp`。

方法

方法	傳回	說明
`connect()`	`Promise<void>`	明確連線到 MCP 伺服器。首次呼叫工具時會自動執行。
`callTool<T>(name, params)`	`Promise<T>`	以指定參數呼叫具名的 MCP 工具。
`listTools()`	`Promise<{ tools: ToolDefinition[] }>`	列出伺服器上所有可用的工具。
`close()`	`Promise<void>`	關閉連線。

`stitchTools(options?)`

AI SDK 轉接器。以 Vercel AI SDK 格式傳回 Stitch 工具。

從 /ai 子路徑匯入：

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

參數

欄位	型別	說明
`options.apiKey`	`string`	覆寫 `STITCH_API_KEY` 環境變數。
`options.include`	`string[]`	只包含特定的工具名稱。

傳回值

Record<string, Tool>——直接放入 generateText({ tools: stitchTools() }) 即可。

`StitchError`

所有 SDK 方法擲回的錯誤類別。

屬性	型別	說明
`message`	`string`	人類可讀的錯誤訊息。
`code`	`StitchErrorCode`	結構化錯誤代碼。

靜態方法

方法	說明
`StitchError.fromUnknown(error)`	將任何擲回的值包裝成 `StitchError`。

列舉

`DeviceType`

"DEVICE_TYPE_UNSPECIFIED" | "MOBILE" | "DESKTOP" | "TABLET" | "AGNOSTIC"

`ModelId`

"MODEL_ID_UNSPECIFIED" | "GEMINI_3_PRO" | "GEMINI_3_FLASH"

`CreativeRange`

"CREATIVE_RANGE_UNSPECIFIED" | "REFINE" | "EXPLORE" | "REIMAGINE"

`VariantAspect`

環境變數

變數	說明
`STITCH_API_KEY`	用於身分驗證的 API 金鑰。供 `stitch` 單例與 `stitchTools()` 使用。
`STITCH_HOST`	覆寫 MCP 伺服器 URL。預設為 `https://stitch.googleapis.com/mcp`。
`STITCH_ACCESS_TOKEN`	OAuth 存取權杖（API 金鑰的替代方案）。
`GOOGLE_CLOUD_PROJECT`	Google Cloud 專案 ID（使用 OAuth 時必填）。

安裝

匯出項目

stitch（單例）

領域方法

基礎結構方法

Stitch

建構函式

方法

Project

屬性

方法

DesignSystem

屬性

方法

Screen

屬性

方法

StitchToolClient

建構函式

StitchConfigInput

方法

stitchTools(options?)

參數

傳回值

StitchError

靜態方法

列舉

DeviceType

ModelId

CreativeRange

VariantAspect

環境變數

`stitch`（單例）

`Stitch`

`Project`

`DesignSystem`

`Screen`

`StitchToolClient`

`StitchConfigInput`

`stitchTools(options?)`

`StitchError`

`DeviceType`

`ModelId`

`CreativeRange`

`VariantAspect`