架构

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 工具名称、描述和输入 schema 的快照。
2. domain-map.json——手工编写的映射，把工具分配到领域类和方法。

生成脚本读取这两个文件，并在 generated/src/ 中产出 TypeScript 类。每个方法都是 callTool 外的一层薄封装，负责参数映射和响应解析。

生成过程是内容哈希锁定的——只有当 manifest 或领域映射真正发生变化时，重新生成才会产出改动。这样可以避免无谓的变动。

第 3 层：stitch 单例（便捷封装）

一个 Proxy 对象，它从环境变量惰性初始化 StitchToolClient，并根据方法名把调用委托给 Stitch 领域类或 StitchToolClient。

当你写 stitch.projects() 时，代理会路由到 Stitch.projects()；当你写 stitch.callTool(...) 时，它会路由到 StitchToolClient.callTool()。

标识映射模式

stitch.project(id) 和 new Project(client, id) 会创建一个句柄，而不发起 API 调用。它们解析 ID（去掉任何 projects/ 前缀），返回一个可以立即调用 .generate()、.screens() 或 .getScreen() 的 Project 对象。

当你从之前的操作中已经知道项目 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") 重建工具 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);
  }
}