Back to Details

stitch-sdk-pipeline

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Stitch SDK Pipeline

Stitch SDK生成流水线

This skill orchestrates the full SDK generation pipeline — from capturing MCP tool schemas to publishing a tested, validated package. Use this when:
  • The Stitch MCP server adds or changes tools
  • You need to regenerate the SDK from scratch
  • You want to verify the pipeline is healthy
[!IMPORTANT] Stage 2 is the only step requiring agent intelligence. All other stages are deterministic scripts. For Stage 2, use the 
stitch-sdk-domain-design
skill.
该Skill编排完整的SDK生成流水线——从捕获MCP工具schema到发布经过测试和验证的包。在以下场景使用：
  • Stitch MCP服务器新增或修改工具
  • 需要从头重新生成SDK
  • 想要验证流水线是否正常运行
[!IMPORTANT] 第2阶段是唯一需要Agent智能的步骤。 所有其他阶段都是确定性脚本。第2阶段请使用
stitch-sdk-domain-design
Skill。

Prerequisites

前置条件

  • STITCH_API_KEY
    environment variable set
  • bun
    installed
  • Working directory: project root (
    stitch-sdk/
    )
  • 已设置
    STITCH_API_KEY
    环境变量
  • 已安装
    bun
  • 工作目录：项目根目录（
    stitch-sdk/
    ）

Pipeline Stages

流水线阶段

Stage 1: Capture Tool Schemas 🤖

阶段1：捕获工具Schema 🤖

bash
// turbo
npm run capture
Connects to the Stitch MCP server, calls 
tools/list
, and writes the raw schemas to 
packages/sdk/generated/tools-manifest.json
. Updates the manifest section of 
stitch-sdk.lock
.
Output: 
packages/sdk/generated/tools-manifest.json
(includes 
inputSchema
+ 
outputSchema
for every tool)
When to skip: If 
tools-manifest.json
is already up to date and no server-side changes occurred.
bash
// turbo
npm run capture
连接到Stitch MCP服务器，调用
tools/list
接口，并将原始schema写入
packages/sdk/generated/tools-manifest.json
。更新
stitch-sdk.lock
中的manifest部分。
输出：
packages/sdk/generated/tools-manifest.json
（包含每个工具的
inputSchema
和
outputSchema
）
可跳过场景：如果
tools-manifest.json
已经是最新版本，且服务器端没有发生变更。

Stage 2: Domain Design 🧠 (Agent)

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

Use the 
stitch-sdk-domain-design
skill for this stage.
Read 
tools-manifest.json
and edit 
packages/sdk/generated/domain-map.json
to map tools → classes → methods.
Key decisions at this stage:
  • Which class owns each tool?
  • What are the arg routing rules (self, param, computed, selfArray)?
  • What is the response projection path?
  • Should the method cache data from the construction response?
Input: 
tools-manifest.json
+ 
scripts/ir-schema.ts
(the canonical IR contract) Output: 
packages/sdk/generated/domain-map.json
When to skip: If 
domain-map.json
already has the correct bindings and you only changed 
ir-schema.ts
or 
generate-sdk.ts
.
本阶段请使用
stitch-sdk-domain-design
Skill。
读取
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
。

Stage 3: Generate TypeScript 🤖

阶段3：生成TypeScript代码 🤖

bash
// turbo
npm run generate
Validates the IR (Zod schema) and every projection (against 
outputSchema
), then emits TypeScript files via ts-morph into 
packages/sdk/generated/src/
.
Output: 
packages/sdk/generated/src/*.ts
+ updated 
stitch-sdk.lock
If this fails with a projection error, go back to Stage 2 and fix 
domain-map.json
.
bash
// turbo
npm run generate
验证IR（Zod schema）和每个投影（与
outputSchema
对比），然后通过ts-morph将TypeScript文件输出到
packages/sdk/generated/src/
。
输出：
packages/sdk/generated/src/*.ts
+ 更新后的
stitch-sdk.lock
如果因投影错误失败，请回到阶段2修复
domain-map.json
。

Stage 4: Build 🤖

阶段4：构建 🤖

bash
// turbo
npm run build
TypeScript compilation: 
packages/sdk/
→ 
packages/sdk/dist/
.
bash
// turbo
npm run build
TypeScript编译：
packages/sdk/
→ 
packages/sdk/dist/
。

Stage 5: Unit Tests 🤖

阶段5：单元测试 🤖

bash
// turbo
npm run test
Runs core unit tests (vitest) — mocked 
callTool
, verifying generated method signatures, caching, and error handling.
bash
// turbo
npm run test
运行核心单元测试（vitest）——模拟
callTool
，验证生成的方法签名、缓存和错误处理。

Stage 6: Script Tests 🤖

阶段6：脚本测试 🤖

bash
// turbo
npm run test:scripts
Runs contract tests (IR schema acceptance/rejection) and logic tests (expression builders) using 
bun:test
.
bash
// turbo
npm run test:scripts
使用
bun:test
运行契约测试（IR schema的接受/拒绝）和逻辑测试（表达式构建器）。

Stage 7: E2E Tests 🤖

阶段7：端到端测试 🤖

bash
npm run test:e2e
Live API tests against the built package. Requires 
STITCH_API_KEY
(and 
GEMINI_API_KEY
for AI SDK tests). Two test suites:
  • live.test.ts
     — Direct SDK calls: create projects, generate screens, verify responses.
  • ai-sdk-e2e.test.ts
     — AI SDK integration via 
    stitchTools()
    : Gemini autonomously calls Stitch tools, generates designs, extracts HTML + Tailwind config, produces modular React components, validates via SWC, and scaffolds a Vite preview app at 
    .stitch/preview/
    .
bash
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预览应用。

Stage 8: Lock Validation 🤖

阶段8：锁文件验证 🤖

bash
// turbo
npm run validate:generated
Verifies that 
stitch-sdk.lock
hashes match the actual generated files. Catches drift (someone edited generated files manually or forgot to regenerate).
[!IMPORTANT] Always run after Stage 3 (Generate). If you run Capture (Stage 1) then Validate without re-generating, the hashes will mismatch because the manifest hash changed.
bash
// turbo
npm run validate:generated
验证
stitch-sdk.lock
中的哈希值与实际生成的文件是否匹配。捕获漂移问题（例如有人手动编辑了生成的文件或忘记重新生成）。
[!IMPORTANT] 请始终在阶段3（生成）之后运行此步骤。如果运行了捕获（阶段1）但未重新生成就直接验证，由于manifest哈希已更改，哈希值会不匹配。

Stage 9: Skill Audit 🧠 (Agent)

阶段9：Skill审计 🧠（Agent）

After the pipeline passes, audit agent skills for freshness. Read the current source of truth and update any skills that reference stale methods, args, or examples.
Inputs:
  • packages/sdk/src/index.ts
    (public surface)
  • Generated class files in 
    packages/sdk/generated/src/
  • packages/sdk/src/spec/errors.ts
    (error codes)
  • packages/sdk/src/spec/client.ts
    (config schema)
Skills to audit (in priority order):
  1. stitch-sdk-usage
    — highest churn, references specific methods and constructor signatures
  2. stitch-sdk-readme
    — must document 
    stitchTools()
    , 
    toolDefinitions
    , and AI SDK integration examples
  3. stitch-sdk-development
    — check cache examples match current domain-map patterns
  4. stitch-sdk-domain-design
    — check code examples in the cache section
Skills to skip: 
stitch-sdk-pipeline
(self-referential), 
red-green-yellow
(generic methodology).
What to check:
  • Every method name in a code example exists on its class
  • Every import in an example matches an export in 
    index.ts
  • Constructor signatures match the actual constructors
  • Config fields match 
    StitchConfigSchema
  • Error codes match 
    StitchErrorCode
When to skip: If only infrastructure code changed (
packages/sdk/src/client.ts
, 
packages/sdk/src/proxy/
) and no public API surface changed.
流水线通过后，审计Agent Skill的新鲜度。读取当前的事实来源，并更新所有引用过时方法、参数或示例的Skill。
输入：
  • packages/sdk/src/index.ts
    （公共接口）
  • packages/sdk/generated/src/
    中的生成类文件
  • packages/sdk/src/spec/errors.ts
    （错误码）
  • packages/sdk/src/spec/client.ts
    （配置schema）
需要审计的Skill（按优先级排序）：
  1. stitch-sdk-usage
    — 变更频率最高，引用了特定方法和构造函数签名
  2. stitch-sdk-readme
    — 必须记录
    stitchTools()
    、
    toolDefinitions
    和AI SDK集成示例
  3. stitch-sdk-development
    — 检查缓存示例是否匹配当前domain-map模式
  4. stitch-sdk-domain-design
    — 检查缓存部分的代码示例
可跳过的Skill：
stitch-sdk-pipeline
（自引用）、
red-green-yellow
（通用方法论）。
检查内容：
  • 代码示例中的每个方法名都存在于对应的类中
  • 示例中的每个导入都与
    index.ts
    中的导出匹配
  • 构造函数签名与实际构造函数一致
  • 配置字段与
    StitchConfigSchema
    匹配
  • 错误码与
    StitchErrorCode
    匹配
可跳过场景：如果仅修改了基础设施代码（
packages/sdk/src/client.ts
、
packages/sdk/src/proxy/
），且公共API接口未发生变化。

Quick Reference

快速参考

Full pipeline (script stages only)

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

bash
npm run pipeline
Runs Stage 1 → 3 → 4 → 5 in sequence. Does not include Stage 2 (agent), Stage 7 (e2e), or Stage 9 (skill audit).
bash
npm run pipeline
按顺序运行阶段1→3→4→5。不包含阶段2（Agent）、阶段7（端到端测试）或阶段9（Skill审计）。

Starting from a specific stage

从指定阶段开始

ScenarioStart from
New tool added to MCP serverStage 1
Need to change how a tool maps to a methodStage 2
Changed 
ir-schema.ts
or 
generate-sdk.ts
Stage 3
Changed code in 
packages/sdk/src/
(client, errors)		Stage 4
Just want to verify everything worksStage 5
Changed AI SDK tools adapter or tool definitionsStage 5
Public API surface changedStage 9
场景从哪个阶段开始
MCP服务器新增工具阶段1
需要修改工具到方法的映射方式阶段2
修改了
ir-schema.ts
或
generate-sdk.ts
阶段3
修改了
packages/sdk/src/
中的代码（客户端、错误处理）		阶段4
仅需验证所有功能是否正常阶段5
修改了AI SDK工具适配器或工具定义阶段5
公共API接口发生变化阶段9

Key files

关键文件

FileLocationRole
tools-manifest.json
packages/sdk/generated/
Raw MCP tool schemas (Stage 1 output)
domain-map.json
packages/sdk/generated/
IR: tool → class → method mappings (Stage 2 output)
tool-definitions.ts
packages/sdk/generated/src/
Generated JSON Schema tool definitions for AI SDK
tools-adapter.ts
packages/sdk/src/
stitchTools()
— AI SDK v6 adapter (imported via 
@google/stitch-sdk/ai
)
ir-schema.ts
scripts/
Zod schema defining valid IR structure
tool-schema.ts
scripts/
TypeScript types for JSON Schema
generate-sdk.ts
scripts/
ts-morph codegen (Stage 3)
stitch-sdk.lock
packages/sdk/generated/
Integrity hashes for drift detection
stitch-html.ts
packages/sdk/test/helpers/
Stitch HTML parser (Tailwind config + font extraction)
component-validator.ts
packages/sdk/test/helpers/
SWC AST validator for generated React components
文件位置作用
tools-manifest.json
packages/sdk/generated/
MCP工具原始schema（阶段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 schema
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验证器