# Stitch SDK/MCP Root Cause Review — 2026-05-20

## 结论

Stitch 多次失败的主因不是登录态、不是 STITCH_API_KEY、不是 Node 版本，而是我们一直在用非官方/过期的 `@_davideast/stitch-mcp tool ...` 调用路径。

该 CLI 在当前 Stitch MCP schema 上会直接失败：

```bash
npx -y @_davideast/stitch-mcp tool list_tools -d '{}'
# Error: can't resolve reference #/$defs/ScreenInstance from id #
```

官方文档现在推荐两条路径：

1. **SDK 首选**：`@google/stitch-sdk`
2. **Remote MCP 直接接入**：`https://stitch.googleapis.com/mcp` + `X-Goog-Api-Key`

我们旧 skill 里写的：

```bash
npx @_davideast/stitch-mcp tool create_project -d '{"title":"..."}'
npx @_davideast/stitch-mcp tool get_screen_code ...
npx @_davideast/stitch-mcp tool get_screen_image ...
```

已不应继续作为生产流程使用。

## 官方文档逐页核对摘要

已读取：

- `/docs/sdk/tutorial/` — Build your first design
- `/docs/sdk/ai-sdk/` — Use with AI SDK
- `/docs/sdk/agent-workflows/` — Agent-driven workflows
- `/docs/sdk/edit-screen/` — How to edit a screen
- `/docs/sdk/generate-variants/` — How to generate variants
- `/docs/sdk/download-artifacts/` — How to download artifacts
- `/docs/sdk/extract-themes/` — How to extract themes
- `/docs/sdk/design-systems/` — How to manage design systems
- `/docs/sdk/upload-image/` — How to upload files
- `/docs/sdk/reference/` — SDK Reference
- `/docs/sdk/architecture/` — Architecture
- `/docs/mcp/setup/` — Stitch via MCP
- `/docs/mcp/guide/` — Getting Started
- `/docs/mcp/reference/` — MCP Reference

关键事实：

- Node.js 要求：20+；本机 Node `v22.22.0`，满足。
- npm 包：`@google/stitch-sdk`；本机实测安装版本 `0.3.5`。
- API Key：`STITCH_API_KEY`；本机已设置。
- SDK 基本流：
  - `import { stitch } from "@google/stitch-sdk"`
  - `stitch.createProject(title)`
  - `project.generate(prompt, deviceType?, modelId?)`
  - `screen.getHtml()`
  - `screen.getImage()`
- 生成/编辑可能耗时几分钟；官方明确说不要因连接错误盲目重试，应稍后 `get_screen`/`list_screens` 查结果。
- `GEMINI_3_PRO` 已 deprecated；应使用 `GEMINI_3_1_PRO` 或 `GEMINI_3_FLASH`。
- MCP 工具名是：`create_project`, `list_projects`, `list_screens`, `get_screen`, `generate_screen_from_text`, `edit_screens`, `generate_variants`, `create_design_system`, `update_design_system`, `list_design_systems`, `apply_design_system` 等。
- 文档里的下载方式不是 `get_screen_code/get_screen_image` 工具；正确做法是通过 SDK `screen.getHtml()` / `screen.getImage()` 拿下载 URL，再 `fetch`/`curl -L` 保存。

## 本机复现结果

### 旧 CLI 失败

```bash
npm view @_davideast/stitch-mcp version
# 0.7.1

npx -y @_davideast/stitch-mcp tool list_tools -d '{}'
# Error: can't resolve reference #/$defs/ScreenInstance from id #
```

结论：旧 CLI 自身解析 MCP schema 失败，连 `list_tools` 都过不了。这个错误和具体项目 prompt 无关。

### 官方 SDK 成功

```bash
npm install @google/stitch-sdk tsx
```

实测脚本：

```ts
import { stitch } from "@google/stitch-sdk";

const project = await stitch.createProject("Hermes Stitch SDK Smoke Test");
const screen = await project.generate(
  "A tiny desktop login card. Dark background. One email field, one password field, one blue button. Minimal.",
  "DESKTOP",
  "GEMINI_3_FLASH"
);

const htmlUrl = await screen.getHtml();
const imageUrl = await screen.getImage();
```

成功输出：

- Project ID: `689614418780933065`
- Screen ID: `75dd60c427304fbdb6d96a5072ae8e0a`
- HTML 下载成功：`11302` bytes
- Image 下载成功：PNG `512x410`, `23872` bytes
- HTML 包含 `tailwind-config`

## 根因链路

1. `site-design` skill 绑定了过期/非官方 CLI：`@_davideast/stitch-mcp`。
2. 旧 CLI 在当前官方 MCP schema 上解析 `$defs/ScreenInstance` 引用失败。
3. 设计 Agent 遇到失败后走 `local-html-fallback`，但验收 Gate 没有把 fallback 当成 P0 风险。
4. 后续前端把 fallback HTML 当作 Stitch 真源执行，导致“看起来像没经过 Stitch”。
5. `get_screen_code/get_screen_image` 这类命令不在官方 MCP reference 当前工具列表里，属于旧封装语义，不能再依赖。

## 新标准流程

### 1. SDK 生成

```bash
mkdir -p /tmp/stitch-run && cd /tmp/stitch-run
npm install @google/stitch-sdk tsx
export STITCH_API_KEY=...
```

```ts
import { stitch } from "@google/stitch-sdk";
import fs from "fs/promises";
import path from "path";

const project = await stitch.createProject("Product Design");
const screen = await project.generate(prompt, "DESKTOP", "GEMINI_3_FLASH");

const htmlUrl = await screen.getHtml();
const imageUrl = await screen.getImage();

await fs.writeFile("screen-index.json", JSON.stringify({
  projectId: project.id,
  screenId: screen.id,
  htmlUrl,
  imageUrl
}, null, 2));

await fs.writeFile("desktop.html", await (await fetch(htmlUrl)).text());
await fs.writeFile("desktop.png", Buffer.from(await (await fetch(imageUrl)).arrayBuffer()));
```

### 2. 多页/移动端

每个关键页面/状态独立 screen：

- landing desktop
- landing mobile
- map normal
- map search/filter
- map marker popup
- mobile bottom sheet
- SEO index/template page

移动端用：

```ts
await project.generate(mobilePrompt, "MOBILE", "GEMINI_3_FLASH")
```

### 3. 变体/精修

```ts
const edited = await screen.edit("Make the map panel more game-like, add HUD styling", "DESKTOP", "GEMINI_3_FLASH");
const variants = await screen.variants("Explore darker underwater palettes", {
  numVariants: 3,
  creativeRange: "EXPLORE",
  aspects: ["COLOR_SCHEME", "LAYOUT", "IMAGES"]
});
```

### 4. 下载与验收

必须同时落盘：

- `stitch/screen-index.json`
- `html/*.html`
- `screens/*.png|jpeg`
- `stitch/run.log`
- `stitch/tool-schemas.json`（首次/异常时保存 `listTools()`）

验收：

- HTML 文件非空且包含 `<html`。
- 图片文件非空，`file` 能识别为 PNG/JPEG。
- HTML 包含 `tailwind-config` 或明确的 CSS/字体设计系统。
- `screen-index.json` 有真实 `projectId/screenId/htmlUrl/imageUrl`。
- 不得把旧 CLI 报错后的 fallback 标为 Stitch 成功。

## 阻断规则

- 禁止生产流程继续使用 `@_davideast/stitch-mcp tool ...`。
- 禁止使用 `get_screen_code/get_screen_image` 作为官方工具名。
- 任何 `can't resolve reference #/$defs/ScreenInstance` 都直接判定为旧 CLI/schema 兼容故障，切到 `@google/stitch-sdk`。
- Stitch 失败后可交 `local-html-fallback`，但只能进入 `CONDITIONAL_DESIGN_REVIEW`，不能 DESIGN_GO。
- 若是游戏/地图/攻略站，fallback 还必须通过竞品视觉/交互基线复核，否则 BLOCK。