用途：本技能面向 @google/stitch-sdk 的开发者，说明其核心系统、模式与设计理念，重点在于如何思考该系统，而非逐个方法罗列（代码库本身才是方法的权威来源）。
生成流水线：领域层完全生成，无手写领域类。共三阶段：阶段一（bun scripts/capture-tools.ts）连接实时 Stitch MCP 服务器，调用 tools/list，写出 tools-manifest.json，是工具存在性的权威来源；阶段二（由代理或人完成）读取清单并产出 domain-map.json 这一中间表示，判断哪个工具映射到哪个类、参数来自 self/param/computed、如何提取返回值及缓存内容；阶段三（bun scripts/generate-sdk.ts）确定性代码生成，读取清单与领域映射，在 packages/sdk/generated/src/ 生成 TypeScript 类，无 LLM 参与，纯模板展开。完整性由 stitch-sdk.lock 记录输入输出的 SHA-256 哈希，bun scripts/validate-generated.ts 校验一致性，可在 CI 中运行以防发布过期代码。
支持新工具：运行阶段一捕获更新后的清单；在 domain-map.json 中为新工具添加绑定；运行阶段三重新生成 SDK 类；运行 validate-generated.ts 确认一致性；按需更新测试。
领域映射 IR：domain-map.json 表达两类内容。类定义领域对象及其构造方式（如 Screen 的 constructorParams、parentField、reference）。绑定定义 MCP 工具到类方法的映射，含 tool、class、method、args 与 returns。参数路由：self 从 this 注入，param 由调用方传入，computed 在调用时由模板构建，selfArray 将 [this.field] 包为数组。响应投影为结构化 ProjectionStep[] 数组，按 outputSchema 校验，单元素用 index，数组用 each，空 [] 表示直接返回。缓存：方法可指定带结构化投影的 cache，在调用 API 前检查 this.data。
双模态：SDK 服务两类消费者。代理模态 StitchToolClient 面向 AI 代理与编排脚本，是原始工具管道，代理接收工具模式、构造 JSON、发送并取回 JSON。stitch 单例通过 Proxy 同时暴露领域方法与工具方法，无需实例化，首次访问时依据环境变量惰性创建 StitchToolClient。读取 STITCH_API_KEY（或 STITCH_ACCESS_TOKEN + GOOGLE_CLOUD_PROJECT），用 STITCH_BASE_URL 覆盖服务器地址（STITCH_HOST 为已废弃别名，2.0 移除）。也可直接实例化 StitchToolClient 以显式控制。配置解析顺序：构造函数参数到环境变量到默认值；鉴权需 apiKey 或 accessToken + projectId，构造时经 Zod 校验。callTool 与 listTools 首次调用自动连接，并发调用通过基于 promise 的锁安全共享连接。AI SDK 适配器 stitchTools() 面向基于 Vercel AI SDK 的代理，将 MCP 工具模式转换为 AI SDK 兼容定义，从 /ai 子路径导出以保持 ai 依赖可选，内部使用同一共享单例。SDK 模态为生成的领域类，面向编写精确程序化脚本的人类，是 callTool 之上的类型化外观，返回领域对象，失败时抛出 StitchError。
错误处理：所有生成方法使用 throw StitchError，不采用 Result<T> 模式，StitchError.fromUnknown() 将所有错误归一化为带 code、message 与可恢复性提示的 StitchError。
基础设施（手写）：StitchToolClient（MCP 传输、鉴权、工具调用）、StitchError（带代码、消息、恢复提示的类型化错误类）、StitchProxy（对其他代理重新暴露 Stitch 的 MCP 代理服务器）、singleton.ts（带环境变量配置的惰性代理）。
副作用膜：SDK 由正式边界分为两个半球。生成半球涵盖每次 MCP 工具调用、响应投影、参数路由与类构造，凡发送 JSON 并取回 JSON 者必须生成；手写半球涵盖触及真实世界的操作：文件系统 I/O、二进制流、非 MCP 的 REST 端点，凡触及磁盘或使用私有 API 者必须手写。该膜在 domain-map.json 中通过任何带 extensionPath 的类上的 sideEffects 声明。有效 reason 值：filesystem_io、binary_data、private_rest、complex_orchestration。生成器在阶段三校验：无 sideEffect.method 与生成的绑定方法名冲突；每个 specPath 指向存在的文件。
新增副作用方法遵循 Spec→Handler→Extension 模式：创建 Spec（src/spec/my-operation.ts），定义输入模式（Zod）、错误码、Result 类型与接口，Handler 必须实现该接口且永不抛出；创建 Handler（src/my-operation-handler.ts），实现 Spec 接口，所有失败返回 Result<T>，绝不抛出，副作用逻辑所在；加入扩展（src/project-ext.ts），薄适配器（每个方法体少于 15 行），解析输入、调用 Handler，并将 Result 映射为失败时抛出 StitchError；在 domain-map.json 中声明 sideEffect 条目；运行 bun scripts/generate-sdk.ts 重新生成。
规则：扩展方法不得覆盖生成方法（防静默遮蔽）；扩展方法必须委托给 Handler（防内联业务逻辑）；Handler 必须实现 Spec 接口（类型化服务契约）；Handler 必须返回 Result，绝不抛出（一致错误面）；扩展不得从 singleton.ts 导入（防循环依赖）。
红绿灯实现：红灯阶段先写会失败的测试，在实现存在前定义契约，如 npx vitest run test/unit/sdk.test.ts 与 bun scripts/e2e-test.ts 应失败；绿灯阶段在 domain-map.json 添加绑定，运行 bun scripts/generate-sdk.ts，更新测试验证行为，npx vitest run 与 bun scripts/e2e-test.ts 通过；黄灯阶段在测试保护下重构以求清晰、补充边界测试、运行 npx tsc 验证类型安全、运行 bun scripts/validate-generated.ts 验证流水线完整性。
在代码库中定位：公开界面从 packages/sdk/src/index.ts 开始；生成类在 packages/sdk/generated/src/（Stitch、Project、Screen、DesignSystem）；流水线产物为 domain-map.json 与 tools-manifest.json；基础设施包括 client.ts、spec/errors.ts、singleton.ts；测试结构为 test/unit/ 与 test/integration/；可用命令读取 package.json 的 scripts 字段。不要依赖文件或目录树的缓存描述，直接阅读源码。导入约定：使用 .js 扩展名以兼容 ESM。