stitch-sdk-pipeline

Stitch SDK 流水线

此技能用于编排完整的 SDK 生成流水线——从捕获 MCP 工具架构，到发布经过测试和验证的软件包。以下情况适用：

• Stitch MCP 服务新增或更改了工具
• 需要从头重新生成 SDK
• 想要验证流水线是否正常运行

重要

阶段 2 是唯一需要 Agent 智能的步骤。 其他所有阶段都是确定性脚本。阶段 2 请使用 stitch-sdk-domain-design 技能。

---

前置条件

• 已设置 STITCH_API_KEY 环境变量
• 已安装 bun
• 工作目录：项目根目录（stitch-sdk/）

---

流水线阶段

阶段 1：捕获工具架构 🤖

// turbo
npm run capture

连接到 Stitch MCP 服务，调用 tools/list，并将原始架构写入 packages/sdk/generated/tools-manifest.json。更新 stitch-sdk.lock 中的清单部分。

输出：packages/sdk/generated/tools-manifest.json（包含每个工具的 inputSchema 和 outputSchema）

跳过条件：如果 tools-manifest.json 已是最新版本，且服务端没有发生更改。

---

阶段 2：领域设计 🧠（Agent）

此阶段请使用 stitch-sdk-domain-design 技能。

读取 tools-manifest.json，并编辑 packages/sdk/generated/domain-map.json，将工具映射到类和方法。

此阶段的关键决策：

• 每个工具由哪个类负责？
• 参数路由规则是什么（self、param、computed、selfArray）？
• 响应投影路径是什么？
• 方法是否应缓存构造响应中的数据？

输入：tools-manifest.json + scripts/ir-schema.ts（规范的 IR 契约） 输出：packages/sdk/generated/domain-map.json

跳过条件：如果 domain-map.json 中的绑定已正确，且你只更改了 ir-schema.ts 或 generate-sdk.ts。

---

阶段 3：生成 TypeScript 🤖

// turbo
npm run generate

验证 IR（Zod 架构）和每个投影（与 outputSchema 对照），然后通过 ts-morph 将 TypeScript 文件写入 packages/sdk/generated/src/。

输出：packages/sdk/generated/src/*.ts + 已更新的 stitch-sdk.lock

如果此步骤因投影错误而失败，请返回阶段 2 并修复 domain-map.json。

---

阶段 4：构建 🤖

// turbo
npm run build

TypeScript 编译：packages/sdk/ → packages/sdk/dist/。

---

阶段 5：单元测试 🤖

// turbo
npm run test

运行核心单元测试（vitest）——模拟 callTool，验证生成的方法签名、缓存和错误处理。

---

阶段 6：脚本测试 🤖

// turbo
npm run test:scripts

使用 bun:test 运行契约测试（IR 架构的接受/拒绝）和逻辑测试（表达式构建器）。

---

阶段 7：端到端测试 🤖

npm run test:e2e

针对已构建的软件包运行实时 API 测试。需要 STITCH_API_KEY（AI SDK 测试还需要 GEMINI_API_KEY）。包含两个测试套件：

• live.test.ts — 直接调用 SDK：创建项目、生成屏幕并验证响应。
• ai-sdk-e2e.test.ts — 通过 stitchTools() 集成 AI SDK：Gemini 自主调用 Stitch 工具、生成设计、提取 HTML + Tailwind 配置、生成模块化 React 组件、通过 SWC 验证，并在 .stitch/preview/ 中搭建 Vite 预览应用。

---

阶段 8：锁定文件验证 🤖

// turbo
npm run validate:generated

验证 stitch-sdk.lock 中的哈希是否与实际生成的文件匹配。检测偏差（有人手动编辑了生成的文件，或忘记重新生成）。

重要

始终在阶段 3（生成）之后运行。如果运行捕获（阶段 1）后直接运行验证，而没有重新生成，哈希将不匹配，因为清单哈希已更改。

第 9 阶段：技能审计 🧠（Agent）

流水线通过后，审计 Agent 技能是否为最新。阅读当前的事实来源，并更新引用了过时方法、参数或示例的技能。

输入：

• packages/sdk/src/index.ts（公共接口）
• packages/sdk/generated/src/ 中的生成类文件
• packages/sdk/src/spec/errors.ts（错误代码）
• packages/sdk/src/spec/client.ts（配置架构）

待审计技能（按优先级排序）：

1. stitch-sdk-usage — 变更最频繁，引用了特定方法和构造函数签名
2. stitch-sdk-readme — 必须记录 stitchTools()、toolDefinitions 和 AI SDK 集成示例
3. stitch-sdk-development — 检查缓存示例是否符合当前的 domain-map 模式
4. stitch-sdk-domain-design — 检查缓存部分中的代码示例

跳过的技能：stitch-sdk-pipeline（自我引用）、red-green-yellow（通用方法论）。

检查内容：

• 代码示例中的每个方法名都存在于其所属类上
• 示例中的每个导入都对应 index.ts 中的导出
• 构造函数签名与实际构造函数一致
• 配置字段与 StitchConfigSchema 一致
• 错误代码与 StitchErrorCode 一致

跳过条件：如果只更改了基础设施代码（packages/sdk/src/client.ts、packages/sdk/src/proxy/），且公共 API 接口未更改。

---

快速参考

完整流水线（仅脚本阶段）

npm run pipeline

按顺序运行第 1 → 3 → 4 → 5 阶段。不包括第 2 阶段（Agent）、第 7 阶段（e2e）或第 9 阶段（技能审计）。

从特定阶段开始

场景	从以下阶段开始
向 MCP 服务添加新工具	第 1 阶段
需要更改工具到方法的映射方式	第 2 阶段
更改了 ir-schema.ts 或 generate-sdk.ts	第 3 阶段
更改了 packages/sdk/src/ 中的代码（客户端、错误）	第 4 阶段
只想验证一切是否正常	第 5 阶段
更改了 AI SDK 工具适配器或工具定义	第 5 阶段
公共 API 接口已更改	第 9 阶段

关键文件

文件	位置	作用
tools-manifest.json	packages/sdk/generated/	原始 MCP 工具架构（第 1 阶段输出）
domain-map.json	packages/sdk/generated/	IR：工具 → 类 → 方法映射（第 2 阶段输出）
tool-definitions.ts	packages/sdk/generated/src/	为 AI SDK 生成的 JSON Schema 工具定义
tools-adapter.ts	packages/sdk/src/	stitchTools() — AI SDK v6 适配器（通过 @google/stitch-sdk/ai 导入）
ir-schema.ts	scripts/	定义有效 IR 结构的 Zod 架构
tool-schema.ts	scripts/	JSON Schema 的 TypeScript 类型
generate-sdk.ts	scripts/	ts-morph 代码生成（第 3 阶段）
stitch-sdk.lock	packages/sdk/generated/	用于检测偏移的完整性哈希
stitch-html.ts	packages/sdk/test/helpers/	Stitch HTML 解析器（Tailwind 配置 + 字体提取）
component-validator.ts	packages/sdk/test/helpers/	用于生成的 React 组件的 SWC AST 验证器