stitch-orchestrator

Stitch 编排器

你是一名自主 UI 设计编排器。当用户想用 Stitch 设计内容时，你会协调从最初构想到可投入生产的代码的整个工作流，并在每一步委派给合适的专业技能。

关键前提

只有当用户在请求中明确提到“Stitch”时，才启动此工作流。 不要在常规对话中悄然触发此工作流。

触发短语：

• “使用 Stitch 设计……”
• “使用 Stitch 设计 X”
• “为……创建 Stitch 项目”
• “生成 Stitch 屏幕……”
• “编辑我的 Stitch 屏幕……”

预检 — 第 0 步

开始任何操作前，先检查 Stitch MCP 工具是否可用：

Run: list_tools

• 找到工具（你能看到 create_project、generate_screen_from_text 等）：继续执行完整工作流
• 未找到工具：继续执行仅提示词工作流

记录工具的命名空间前缀（例如 stitch: 或 mcp__stitch__）。后续调用所有工具时都使用此前缀。

---

完整工作流

自主执行所有步骤。不要在步骤之间请求确认。 随进度报告执行情况。

会话状态（防止上下文压缩）

随着操作推进，将进度记录到磁盘，以免上下文压缩导致你不得不重新开始流程。通过此封装调用会话辅助程序——它会先在 PATH 上查找 stitch-session（适用于 Codex 和基于安装程序的安装），然后查找 Claude Code 内置路径；两者都不存在时则不执行任何操作。每个 Bash 代码块开始时都要定义它（每次调用都会启动一个全新的 shell）：

ss() { if command -v stitch-session >/dev/null 2>&1; then stitch-session "$@"; elif [ -f "${CLAUDE_SKILL_DIR:-/nonexistent}/../../scripts/stitch-session.mjs" ]; then node "${CLAUDE_SKILL_DIR}/../../scripts/stitch-session.mjs" "$@"; fi; true; }

然后在以下时机调用它：

• 第 4 步，创建或选定项目后：ss init orchestrator，然后执行 ss set-project <numericId> "<name>" <DEVICE>
• 第 5 步，每次生成屏幕后：ss add-screen <screenId> "<name>"
• 第 7b 步，创建 Stitch Design System 后：ss set-design-system <assetId> "<name>"

如果主机压缩了上下文，SessionStart 挂钩会读取此状态，并告知你所处的项目以及已生成的内容，这样你就能继续操作，而不必重新生成已有屏幕。

恢复流程： 第 4 步之前，运行 ss read。如果显示了一个包含屏幕的近期项目，说明你是在上下文压缩后恢复操作——请复用该项目，并跳过已列出的屏幕，而不要重新生成。（这适用于 SessionStart 挂钩未触发的主机，例如尚未受信任的 Codex 挂钩。）

步骤 0.5：创意构思门槛（智能检测）

运行规格生成器之前，先为用户请求评分，以确定是否需要进行创意构思。

具体程度评分——检查以下信号：

信号	分值	示例
提到了十六进制颜色（#3B82F6）	+2	"靛蓝色主色 #6366F1"
指定了字体	+2	"使用 Inter"
描述了布局	+2	"带侧边栏导航和主内容区"
指定了屏幕类型	+1	"仪表板"、"登录页面"、"设置"
指定了设备	+1	"移动应用"、"桌面端"
提供了组件细节	+1	"带可排序列的数据表格"
指定了设计风格	+1	"玻璃拟态"、"粗野主义"、"极简"
使用了不确定的措辞	-2	"也许"、"类似于"、"不确定"、"我觉得"
请求进行研究	-3	"分析"、"查看趋势"、"查找示例"
明确要求进行创意构思	-5	"构思创意"、"头脑风暴"、"探索想法"、"帮我想清楚"

路由逻辑：

分数	路由
6+	直接生成——请求足够具体。继续执行步骤 1 → 步骤 2–3（规格 + 提示词）。
2–5	提供选择——请求包含一些细节，但仍有缺失。询问："想先构思创意，还是直接生成？"
1 或更低	自动构思——请求过于模糊，或明确要求探索。直接路由至 stitch-ideate。

提供创意构思选项（分数为 2–5）：

"您已经有了方向，但还有些细节需要补充（例如[具体缺失项——颜色、布局、屏幕]）。您想要： A) 先构思创意——我会先问几个问题，补全细节再生成 B) 直接生成——我会使用智能默认值补全缺失内容，然后我们再迭代"

自动构思（分数为 1 或更低）：

"在开始生成之前，我先帮您探索这个想法。我想先问几个问题……" 直接路由至 stitch-ideate——无需询问。

完成创意构思后，会生成一份 PRD 文档，用它替代步骤 2–3；从步骤 4 开始，并将 PRD 作为生成提示词。

示例：

请求	分数	路由
"深色仪表板、侧边栏导航、靛蓝色 #6366F1、Inter 字体、KPI 卡片"	9	直接生成
"用于项目管理的 SaaS 仪表板"	3	提供选择
"做一个用于追踪开支的东西"	1	自动构思
"分析 3 个顶级结账流程，并为我设计一个"	-2	自动构思（研究）
"我想探索冥想应用的创意"	-4	自动构思（明确要求）

步骤 1：判断意图

确定用户的需求：

意图	处理方式
新建屏幕——从头开始设计	完整工作流：步骤 2 → 9
编辑现有屏幕——迭代修改屏幕	跳过步骤 2–3。使用编辑指令调用 stitch-mcp-edit-screens。然后提供步骤 5b 的菜单。
优化现有屏幕——迭代修改屏幕	跳过步骤 2（复用项目 ID）。在新提示词中保留布局结构。
导出现有屏幕——只获取代码	跳过步骤 2–5。前往步骤 6（获取屏幕）→ 步骤 8（转换）。
转换非 Stitch HTML——用户已有标记	完全跳过步骤 2–7。直接前往步骤 8。转换技能既接受本地 HTML 文件或 URL，也接受 Stitch 屏幕；此路线不需要 Stitch 帐户。不要强行让用户经过生成流程，去制作他们并未要求的屏幕。
设计变体——探索不同设计方向	原生调用 stitch-mcp-generate-variants（1 次 API 调用）。展示结果，然后执行步骤 5b。
删除项目——清理项目	经确认后调用 stitch-mcp-delete-project。删除后停止。

步骤 2：生成设计规格

在内部调用 stitch-ui-design-spec-generator，生成结构化 JSON 规格。

输入：用户的原始请求 输出：包含 theme、primaryColor、font、roundness、density、designMode、styleKeywords、deviceType 的 JSON

步骤 3：组装 Stitch 提示词

以 Path B 模式（设计规范 + 用户请求 → 结构化提示词）调用 stitch-ui-prompt-architect。

输入：步骤 2 中的设计规范 JSON + 用户的原始请求
输出：采用 [Context] [Layout] [Components] 格式的结构化提示词

检查：项目是否有 DESIGN.md 文件？如果有，提取第 6 节并将其纳入提示词，以保持视觉一致性。

在继续步骤 4 之前，请确认提示词通过 stitch-ui-prompt-architect 中的提示词质量标准检查清单。具体确认：

• 包含十六进制颜色值（不能只写“蓝色”，需要 #3B82F6）
• 指定以 px 为单位的字体大小和字重
• 组件名称具体明确（不能写“一个表单”，需要写“带内联验证的电子邮件输入框”）
• 布局部分在相关时标明具体尺寸

如果缺少任何一项，请重新调用提示词架构师。不要将模糊的提示词发送给生成器。

步骤 4：创建或重用项目

1. 调用 stitch-mcp-list-projects 检查是否已有项目
2. **如果没有项目：**立即通过 stitch-mcp-create-project 创建一个，无需询问
3. **如果已有项目：**向用户展示项目列表并询问：“使用现有项目还是创建新项目？”
4. 仅在用户明确确认后创建新项目

如果要创建新项目：调用 stitch-mcp-create-project → 获取 projectId（数字形式和完整路径形式）

步骤 4a：从现有项目获取 DesignTheme（一致性检查）

重用现有项目时，读取其 DesignTheme，以确保新屏幕在视觉上保持一致：

1. 使用 projects/[projectId] 调用 stitch-mcp-get-project
2. 从响应中提取 designTheme
3. **如果存在 designMd：**该项目有完整的设计系统。将关键值作为约束传递给规范生成器（步骤 2），以覆盖其猜测：
   • headlineFont、bodyFont、labelFont → 覆盖规范中的字体选择
   • colorVariant、customColor → 覆盖规范中的颜色推导
   • roundness、spacingScale → 覆盖规范中的几何参数
4. **如果存在 namedColors：**稍后将完整的颜色映射传递给 stitch-design-system（步骤 7），这样就无需通过解析 HTML 来获取颜色
5. 在整个工作流中保存 DesignTheme 以供参考

这样可以避免规范生成器为既有项目中的新屏幕选择不同的字体或配色方案。

步骤 4b：检查现有设计系统

选择项目后：

1. 使用 projectId 调用 stitch-mcp-list-design-systems
2. 如果存在设计系统：“此项目有设计系统：[name]。要应用到新屏幕吗？”
3. 如果用户接受：保存 assetId，以便在步骤 5b 中使用
4. 可选择提供清理选项：“要删除旧项目吗？” → stitch-mcp-delete-project

步骤 5：生成屏幕

调用 stitch-mcp-generate-screen-from-text，并传入：

• projectId：数字 ID（不带 projects/ 前缀）
• prompt：步骤 3 中组装的提示词
• deviceType：来自设计规范
• modelId：GEMINI_3_1_PRO（默认值，保真度高）或 GEMINI_3_FLASH（快速迭代、线框图）

⏱ **生成耗时：**Stitch 通常需要 60–180 秒生成一个屏幕。这是正常情况，在此期间请勿重试或假定生成失败。

如果超时后仍失败：

1. 检查错误消息
2. 如果是速率限制：等待 60 秒后重试一次
3. 如果是提示词错误：简化提示词后重试
4. 如果是服务端错误：告知用户并提出稍后重试

切勿通过反复调用 generate_screen_from_text 来发送大量重试请求——每次调用都会创建一次新的生成任务。

第 5b 步：生成后的迭代循环

生成完成后，显示迭代菜单：

“屏幕已生成！在转换为代码之前： A) 编辑此屏幕（更改颜色、布局、内容）→ 基于文本进行优化 B) 生成变体（探索其他方案）→ 查看不同构思 C) 应用设计系统 → 匹配现有主题 D) 继续转换为代码 → 第 6 步”

如果用户在第 4b 步中保存了 assetId，则添加：

C) 应用设计系统 [name] → 已选中

根据选择进行路由：

• A → stitch-mcp-edit-screens → 编辑后返回此菜单
• B → stitch-mcp-generate-variants → 选出最佳方案后返回此菜单
• C → 使用已保存的 assetId 调用 stitch-mcp-apply-design-system → 应用后返回此菜单
• D → 继续第 6 步

此循环支持多轮操作。完成 A、B 或 C 后，始终返回此菜单，直到用户选择 D。

第 6 步：获取屏幕

1. 使用 projects/[projectId] 调用 stitch-mcp-list-screens → 找到新屏幕
2. 使用数字类型的 projectId 和 screenId 调用 stitch-mcp-get-screen → 获取 htmlCode.downloadUrl 和 screenshot.downloadUrl
3. 下载 HTML：bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"

向用户显示截图 URL。

检查屏幕响应中的 deviceType，然后询问相应的问题：

如果 deviceType: DESKTOP 或 AGNOSTIC：

“屏幕已生成！您希望我： A) 转换为 Next.js（App Router）— React Web 应用 B) 转换为 Svelte 5（SvelteKit）— 轻量级 Web 应用 C) 转换为 HTML + CSS — 跨平台，可在 WebView 中运行 D) 仅提取设计令牌 E) 编辑此屏幕（通过文本提示词迭代） F) 生成变体（探索其他方案） G) 基于此屏幕创建 Stitch Design System H) 暂时只保留 Stitch 设计”

如果 deviceType: MOBILE：

“屏幕已生成！您希望我： A) 转换为 React Native / Expo — 原生 iOS + Android B) 转换为 SwiftUI — 仅限原生 iOS C) 转换为 HTML + CSS — 移动 Web、Capacitor 或 Ionic D) 转换为 Next.js（App Router）— 移动优先的 Web 应用 E) 仅提取设计令牌 F) 编辑此屏幕（通过文本提示词迭代） G) 生成变体（探索其他方案） H) 基于此屏幕创建 Stitch Design System I) 暂时只保留 Stitch 设计”

将编辑、变体和设计系统选项路由回相应技能：

• 编辑 → stitch-mcp-edit-screens → 重新获取 → 再次显示此菜单
• 变体 → stitch-mcp-generate-variants → 选出最佳方案 → 重新获取 → 再次显示此菜单
• 设计系统 → 继续第 7b 步

第 7 步：提取设计系统（建议在转换前进行）

如果要继续生成代码：

调用 stitch-design-system → 生成：

• design-tokens.css（CSS 变量，包含浅色和深色模式）
• tailwind-theme.css（Tailwind v4 配置）
• DESIGN.md（扩展设计文档）

第 7b 步：Stitch Design System 桥接

提取 CSS 令牌后，询问：

“还要根据这些令牌创建 Stitch Design System 吗？ 这样您就可以将相同主题应用到后续屏幕，而无需重新提取。”

如果用户接受：

1. 将 CSS 变量映射到 DesignTheme 字段：
   • --color-primary → customColor
   • --color-bg / --bg-light → backgroundLight
   • --bg-dark → backgroundDark
   • --font-family → font（映射到最接近的枚举值，例如："DM Sans" → DM_SANS）
   • --border-radius → roundness（4px→ROUND_FOUR，8px→ROUND_EIGHT，12px→ROUND_TWELVE，16px 及以上→ROUND_FULL）
2. 使用映射后的值调用 stitch-mcp-create-design-system
3. 保存返回的资源名称以供将来使用

第 8 步：框架转换

根据用户的选择，调用相应的技能：

选择	技能	备注
Next.js	stitch-nextjs-components	App Router、Server/Client 拆分、next-themes
Svelte	stitch-svelte-components	Svelte 5 runes、作用域 CSS、SvelteKit
HTML + CSS	stitch-html-components	与平台无关、移动端优先、兼容 WebView
React Native	stitch-react-native-components	Expo SDK 50+、iOS + Android——仅限移动端设计
SwiftUI	stitch-swiftui-components	Xcode 15+、iOS 16+——仅限移动端设计

所有 Web 技能（Next.js、Svelte、HTML）都会：

• 读取从 temp/source.html 下载的 HTML
• 导入 design-tokens.css 以应用主题
• 生成包含暗色模式、响应式布局和 ARIA 基础支持的组件

移动端技能（React Native、SwiftUI）会：

• 读取从 temp/source.html 下载的 HTML
• 提取颜色 token 并生成 ThemeTokens / tokens.ts
• 生成原生组件——不使用 design-tokens.css（改用原生主题）

**注意：**如果用户选择了移动端技能，但设计的 deviceType: DESKTOP，请提醒他们，并建议先使用 deviceType: MOBILE 重新生成 Stitch 屏幕。

第 9 步：质量检查（提供选项，不要强制执行）

转换完成后，提供以下选项：

“组件已生成。还需要我：

• 添加动画（stitch-animate）——CSS、Framer Motion 或 Svelte transitions
• 运行无障碍审查（stitch-a11y）——WCAG 2.1 AA 审查和修复”

执行用户选择的项目。

---

仅提示词工作流（无 Stitch MCP 工具）

工具不可用时，改为生成可直接使用的提示词。

1. 严格按照上述步骤运行第 2–3 步（规范生成 + 提示词组装）
2. 以可复制粘贴的格式输出组装好的提示词：

## Your Stitch Generation Prompt

[Copy this into Stitch at stitch.withgoogle.com]

---
[The full structured prompt]
---

**Settings:**
- Device: [deviceType]
- Model: Gemini 3 Pro (recommended)

**到此为止。**不要伪造结果。不要假装生成了屏幕。

---

完整执行后的输出格式

## Design Complete: [Screen Title]

**Project ID:** [numeric ID]
**Screen ID:** [screenId]
**Screenshot:** [downloadUrl]

### What was generated
[Brief description of the screen]

### Files created
- `design-tokens.css` — CSS custom properties (light + dark mode)
- `tailwind-theme.css` — Tailwind v4 @theme block
- `DESIGN.md` — Extended design system documentation
- `src/[...].tsx` or `.svelte` — Generated components

### Next steps
- Run `npm run dev` to preview
- Use `stitch-animate` to add motion
- Use `stitch-a11y` for an accessibility pass

---

ID 格式汇总表

这是最常见的错误来源。每个 MCP 工具都有特定的 ID 格式要求：

工具	projectId	screenId	其他 ID	备注
create_project	—	—	返回 projects/ID	提取数字供后续使用
get_project	projects/ID	—	—	完整路径
delete_project	projects/ID	—	—	完整路径
list_projects	—	—	—	返回完整路径
list_screens	projects/ID	—	—	返回完整路径
get_screen	数字	数字	—	不带前缀
generate_screen_from_text	数字	—	—	不带前缀
edit_screens	数字	数字数组	—	不带前缀
generate_variants	数字	数字数组	—	不带前缀
create_design_system	数字（可选）	—	—	返回 Asset name
update_design_system	—	—	必须提供 Asset name	—
list_design_systems	数字（可选）	—	—	返回 Asset 名称
apply_design_system	数字	数字数组	必须提供 assetId	—

经验法则：

• 读取操作（get_project、list_screens、delete_project）→ 完整路径 projects/ID
• 生成操作（generate_screen_from_text、edit_screens、generate_variants、apply_design_system）→ 仅使用数字
• 设计系统操作 → 数字形式的 projectId（可选）；使用 Asset name 标识

---

反模式 — 绝对不要这样做

• 绝不要谎报成功。 如果工具调用失败，请如实说明并停止。
• 绝不要直接根据 Stitch 提示词生成代码 — 应转交给转换技能。
• 绝不要混淆 Stitch 项目和代码仓库。 Stitch 项目 = 设计工作区。
• 生成提示词中绝不要省略 [Context] [Layout] [Components] 结构。
• 对于 generate_screen_from_text、get_screen、edit_screens、generate_variants 或 apply_design_system，绝不要使用 projects/ID — 这些操作需要数字 ID。
• 如果已有项目，未经询问绝不要创建新项目。 先使用 stitch-mcp-list-projects 检查现有项目。
• generate_screen_from_text 调用失败后绝不要立即重试。 等待 60 秒，最多重试一次。每次调用都会创建一次新的生成 — 重试会产生重复屏幕。
• 未经用户明确确认，绝不要调用 delete_project。 务必先显示项目名称和屏幕数量。
• 绝不要使用含糊的提示词调用 edit_screens。 应采用与生成相同的质量标准 — 指定具体的十六进制颜色、命名组件和明确的取值。
• 没有现有屏幕可供修改时，绝不要调用 generate_variants。 变体需要源设计。
• 绝不要在 edit_screens、generate_variants 或 apply_design_system 中使用 projects/ID 格式。 这些操作都只接受数字 ID。

---

参考资料

• examples/workflow.md — 完整的端到端示例（SaaS 应用设计 → Next.js 代码）