stitch-loop

Stitch 构建循环

**限制：**仅当用户明确提到“Stitch”以及多页面或迭代式网站构建时，才使用此技能。

你是一名处于迭代式网站构建循环中的自主前端构建者。每轮迭代：(1) 读取接力棒；(2) 使用 Stitch MCP 生成页面；(3) 集成到网站中；(4) 编写下一根接力棒，让循环继续。

前置条件

• Stitch MCP Server（参见 stitch-setup 技能或 https://stitch.withgoogle.com/docs/mcp/guide/）
• DESIGN.md — 使用现有屏幕通过 stitch-design-system 生成（保持一致性所必需）
• SITE.md — 网站愿景、Stitch 项目 ID、站点地图、路线图（如果缺失则创建）

接力棒系统

next-prompt.md 是迭代之间传递的接力棒，用于告知循环接下来要构建哪个页面。

接力棒格式

---
page: about
---

**DESIGN SYSTEM (REQUIRED):**
[Paste DESIGN.md Section 6 here verbatim]

**Page request:**
About page with company mission, team section (3 people), and timeline.

规则：

• page frontmatter → 输出文件名（about.html）
• 正文必须包含 DESIGN.md 第 6 节中的设计系统区块
• 每轮迭代结束时必须更新 next-prompt.md——缺少该文件时循环会停止

---

执行流程

步骤 1 — 读取接力棒

解析 next-prompt.md：

• 从 YAML frontmatter 中提取 page
• 提取完整的提示词正文（包括设计系统区块）

步骤 2 — 查阅上下文文件

文件	查阅内容
SITE.md	Stitch 项目 ID（第 2 节）、站点地图（第 3 节）、路线图 / 后续页面（第 4 节）、创意自由（第 5 节）
DESIGN.md	第 6 节——将其复制到每个提示词中，而不只是当前提示词

**检查：**不要重新构建 SITE.md 站点地图中已有的页面。不要偏离 DESIGN.md 中的视觉风格。

步骤 3 — 使用 Stitch 生成页面

1. 运行 list_tools → 查找 Stitch MCP 前缀
2. 如果存在 stitch.json，使用其中存储的 projectId——不要创建新项目
3. 如果不存在 stitch.json，调用 create_project → 将数字 ID 保存到 stitch.json
4. 调用 generate_screen_from_text：
   • projectId：数字 ID（不带 projects/ 前缀）
   • prompt：完整的接力棒内容，包括 DESIGN SYSTEM 区块
   • deviceType：与 SITE.md 或 DESIGN.md 中的设置一致
5. 使用数字 projectId 和 screenId 调用 get_screen
6. 下载 HTML：bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "queue/[page].html"
7. 下载屏幕截图：保存到 queue/[page].png

步骤 4 — 集成到网站

1. 将 queue/[page].html 移至 site/public/[page].html
2. 修正资源路径（使其相对于 site/public/）
3. 配置导航：将 href="#" 占位符替换为指向现有页面的真实路径
4. 确保页眉 / 页脚与网站中的其他页面一致

步骤 4.5 — 视觉验证（如果 Chrome DevTools MCP 可用）

如果 list_tools 中有 chrome* 工具：

1. 启动本地服务器：npx serve site/public -p 3000
2. 导航到 http://localhost:3000/[page].html
3. 截取屏幕截图，并与 queue/[page].png 进行比较
4. 停止服务器

步骤 5 — 更新 SITE.md

• 将 [x] [page].html 添加到站点地图
• 从创意自由部分移除已使用的创意
• 如果完成了待办事项，则更新路线图

步骤 6 — 编写下一根接力棒（至关重要）

完成前必须更新 next-prompt.md——跳过此步骤会导致循环停滞。

1. 从以下位置选择下一个页面：站点地图 → 路线图 → 创意自由，或构思一个合适的页面
2. 编写 next-prompt.md，包含：
   • 有效的 YAML frontmatter（page: <next-page-name>）
   • 从 DESIGN.md 第 6 节原样复制的 **DESIGN SYSTEM (REQUIRED):** 区块
   • 清晰的页面描述

---

文件结构

project/
├── next-prompt.md       ← Baton (current task; updated each iteration)
├── stitch.json          ← Stitch project ID (persist between loops!)
├── DESIGN.md            ← From stitch-design-system
├── SITE.md              ← Vision, sitemap, roadmap
├── queue/               ← Staging: [page].html, [page].png
└── site/
    └── public/          ← Production: index.html, about.html, etc.

---

SITE.md 模板

# Site Vision

[One paragraph describing the site's purpose, audience, and overall feeling]

## Stitch Project

- **Project ID (numeric):** [ID from stitch-mcp-create-project]

## Sitemap

- [ ] index.html — Home
- [ ] about.html — About
- [ ] contact.html — Contact

## Roadmap

1. index.html — main landing page
2. about.html — company/team info
3. contact.html — contact form

## Creative freedom

Additional pages or sections not yet planned...

---

常见问题

• ❌ 忘记更新 next-prompt.md（循环会停止）
• ❌ 重新构建已列入 SITE.md 站点地图的页面
• ❌ 在提示词中遗漏 DESIGN.md 第 6 节（会导致视觉风格偏移）
• ❌ 在 generate_screen_from_text 中使用 projects/ID 格式，而不是数字
• ❌ 保留 href="#"，而不设置实际页面链接
• ❌ 未持久化 stitch.json（每次迭代都会创建新项目）

---

故障排除

问题	解决方法
各页面的视觉风格不一致	更新 DESIGN.md；始终将第 6 节复制到 baton 中
循环在下一次迭代时停滞	检查 next-prompt.md 是否包含有效的 frontmatter 和非空正文
Stitch 生成失败	确保 baton 包含 DESIGN SYSTEM 区块和具体的页面请求
导航损坏	内部链接使用相对路径；检查 site/public/ 目录结构

---

参考资料

• scripts/fetch-stitch.sh — 可靠的 GCS HTML 下载器
• stitch-design-system — 从现有屏幕生成 DESIGN.md
• stitch-ui-prompt-architect — 将含糊的 baton 文本完善为结构化提示词
• docs/prd-to-stitch-workflow.md — 由 PRD 驱动的多屏幕工作流