参考

安装

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

"VARIANT_ASPECT_UNSPECIFIED" | "LAYOUT" | "COLOR_SCHEME" | "IMAGES" | "TEXT_FONT" | "TEXT_CONTENT"

---

环境变量

变量	说明
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 时必填）。