stitch-loop

Stitch 构建循环

你是一名参与迭代式网站构建循环的自主前端构建者。你的目标是使用 Stitch 生成页面，将其集成到网站中，并为下一次迭代准备说明。

概述

构建循环模式通过“接力棒”系统实现持续、自主的网站开发。每次迭代：

1. 从接力棒文件（.stitch/next-prompt.md）读取当前任务
2. 使用 Stitch MCP 工具生成页面
3. 将页面集成到网站结构中
4. 将下一项任务写入接力棒文件，供下一次迭代使用

先决条件

必需：

• 能够访问 Stitch MCP Server
• 一个 Stitch 项目（现有项目或新建项目）
• 一个 .stitch/DESIGN.md 文件（如有需要，使用 design-md skill 生成）
• 一个 .stitch/SITE.md 文件，用于记录网站愿景和路线图

可选：

• Chrome DevTools MCP Server — 可用于对生成的页面进行视觉验证

接力棒系统

.stitch/next-prompt.md 文件充当迭代之间传递任务的接力棒：

---
page: about
---
A page describing how jules.top tracking works.

**DESIGN SYSTEM (REQUIRED):**
[Copy from .stitch/DESIGN.md Section 6]

**Page Structure:**
1. Header with navigation
2. Explanation of tracking methodology
3. Footer with links

关键规则：

• YAML frontmatter 中的 page 字段决定输出文件名
• 提示词内容必须包含 .stitch/DESIGN.md 中的设计系统区块
• 你必须在完成工作前更新此文件，才能继续循环

执行流程

第 1 步：读取接力棒

解析 .stitch/next-prompt.md，提取：

• page frontmatter 字段中的页面名称
• Markdown 正文中的提示词内容

第 2 步：查阅上下文文件

生成页面之前，先阅读以下文件：

文件	用途
.stitch/SITE.md	网站愿景、Stitch Project ID、现有页面（网站地图）、路线图
.stitch/DESIGN.md	Stitch 提示词所需的视觉风格

重要检查：

• 第 4 节（网站地图）——不要重新创建已存在的页面
• 第 5 节（路线图）——如果有待办任务，从这里选择任务
• 第 6 节（创意自由）——如果路线图为空，从这里获取新页面的创意

第 3 步：使用 Stitch 生成页面

使用 Stitch MCP 工具生成页面：

1. 发现命名空间：运行 list_tools，查找 Stitch MCP 前缀
2. 获取或创建项目：
   • 如果 .stitch/metadata.json 存在，使用其中的 projectId
   • 否则，调用 [prefix]:create_project，然后调用 [prefix]:get_project 获取完整项目信息，并将其保存到 .stitch/metadata.json（参见下方架构）
   • 每生成一个屏幕后，再次调用 [prefix]:get_project，并使用每个屏幕的完整元数据（id、sourceScreen、尺寸、画布位置）更新 .stitch/metadata.json 中的 screens 映射
3. 生成屏幕：调用 [prefix]:generate_screen_from_text，并提供：
   • projectId：项目 ID
   • prompt：接力棒中的完整提示词（包括设计系统区块）
   • deviceType：DESKTOP（或指定的设备类型）
4. 获取资源：下载前，检查 .stitch/designs/{page}.html 和 .stitch/designs/{page}.png 是否已存在：
   • 如果文件存在：询问用户是要从 Stitch 项目刷新设计，还是重用现有本地文件。只有在用户确认后才重新下载。
   • 如果文件不存在：继续下载：
     • htmlCode.downloadUrl — 下载并保存为 .stitch/designs/{page}.html
     • screenshot.downloadUrl — 下载前在 URL 后追加 =w{width}，其中 {width} 是屏幕元数据中的 width 值（Google CDN 默认提供低分辨率缩略图）。保存为 .stitch/designs/{page}.png

第 4 步：集成到网站

1. 将生成的 HTML 从 .stitch/designs/{page}.html 移至 site/public/{page}.html
2. 修正所有资源路径，使其相对于 public 文件夹
3. 更新导航：
   • 找出现有的占位链接（例如 href="#"），并将其指向新页面
   • 如适用，将新页面添加到全局导航中
4. 确保所有页面的页眉和页脚保持一致

步骤 4.5：视觉验证（可选）

如果 Chrome DevTools MCP Server 可用，请验证生成的页面：

1. 检查是否可用：运行 list_tools，查看是否存在 chrome* 工具
2. 启动开发服务器：使用 Bash 启动本地服务器（例如 npx serve site/public）
3. 导航到页面：调用 [chrome_prefix]:navigate，打开 http://localhost:3000/{page}.html
4. 截取屏幕截图：调用 [chrome_prefix]:screenshot，捕获渲染后的页面
5. 视觉对比：将页面与 Stitch 截图（.stitch/designs/{page}.png）对比，检查还原度
6. 停止服务器：终止开发服务器进程

注意： 此步骤为可选步骤。如果未安装 Chrome DevTools MCP，请跳至步骤 5。

步骤 5：更新站点文档

修改 .stitch/SITE.md：

• 在第 4 节（站点地图）中添加新页面，并标记为 [x]
• 从第 6 节（创意自由）中移除已采用的想法
• 如果完成了待办事项，请更新第 5 节（路线图）

步骤 6：准备下一棒（关键）

完成前必须更新 .stitch/next-prompt.md。 这样才能让循环持续下去。

1. 确定下一个页面：
   • 检查 .stitch/SITE.md 第 5 节（路线图）中的待办事项
   • 如果没有待办事项，请从第 6 节（创意自由）中挑选
   • 或者构思一个符合站点愿景的新点子
2. 编写交接内容，并添加正确的 YAML frontmatter：

---
page: achievements
---
A competitive achievements page showing developer badges and milestones.

**DESIGN SYSTEM (REQUIRED):**
[Copy the entire design system block from .stitch/DESIGN.md]

**Page Structure:**
1. Header with title and navigation
2. Badge grid showing unlocked/locked states
3. Progress bars for milestone tracking

文件结构参考

project/
├── .stitch/
│   ├── metadata.json   # Stitch project & screen IDs (persist this!)
│   ├── DESIGN.md       # Visual design system (from design-md skill)
│   ├── SITE.md         # Site vision, sitemap, roadmap
│   ├── next-prompt.md  # The baton — current task
│   └── designs/        # Staging area for Stitch output
│       ├── {page}.html
│       └── {page}.png
└── site/public/        # Production pages
    ├── index.html
    └── {page}.html

.stitch/metadata.json 架构

此文件会保存所有 Stitch 标识符，供后续迭代在编辑或创建变体时引用。创建项目或生成屏幕后，调用 [prefix]:get_project 来填充此文件。

{
  "name": "projects/6139132077804554844",
  "projectId": "6139132077804554844",
  "title": "My App",
  "visibility": "PRIVATE",
  "createTime": "2026-03-04T23:11:25.514932Z",
  "updateTime": "2026-03-04T23:34:40.400007Z",
  "projectType": "PROJECT_DESIGN",
  "origin": "STITCH",
  "deviceType": "MOBILE",
  "designTheme": {
    "colorMode": "DARK",
    "font": "INTER",
    "roundness": "ROUND_EIGHT",
    "customColor": "#40baf7",
    "saturation": 3
  },
  "screens": {
    "index": {
      "id": "d7237c7d78f44befa4f60afb17c818c1",
      "sourceScreen": "projects/6139132077804554844/screens/d7237c7d78f44befa4f60afb17c818c1",
      "x": 0,
      "y": 0,
      "width": 390,
      "height": 1249
    },
    "about": {
      "id": "bf6a3fe5c75348e58cf21fc7a9ddeafb",
      "sourceScreen": "projects/6139132077804554844/screens/bf6a3fe5c75348e58cf21fc7a9ddeafb",
      "x": 549,
      "y": 0,
      "width": 390,
      "height": 1159
    }
  },
  "metadata": {
    "userRole": "OWNER"
  }
}

字段	描述
name	完整资源名称（projects/{id}）
projectId	Stitch 项目 ID（来自 create_project 或 get_project）
title	易于理解的项目标题
designTheme	设计系统令牌：色彩模式、字体、圆角、自定义颜色、饱和度
deviceType	目标设备：MOBILE、DESKTOP、TABLET
screens	页面名称 → 屏幕对象的映射。每个屏幕均包含 id、sourceScreen（用于 MCP 调用的资源路径）、画布位置（x、y）和尺寸（width、height）
metadata.userRole	用户在项目中的角色（OWNER、EDITOR、VIEWER）

编排选项

此循环可由不同的编排层驱动：

方法	工作方式
CI/CD	GitHub Actions 在 .stitch/next-prompt.md 发生更改时触发
人工介入	开发者在继续之前审查每次迭代
Agent 链	一个 Agent 向另一个 Agent 派发任务（例如 Jules API）
手动	开发者在同一仓库中反复运行 Agent

此技能与编排方式无关——应关注模式，而非触发机制。

设计系统集成

此技能与 design-md 技能配合使用效果最佳：

1. 首次设置：使用 design-md 技能，根据现有 Stitch 屏幕生成 .stitch/DESIGN.md
2. 每次迭代：将第 6 节（“Stitch 生成的设计系统说明”）复制到交接提示词中
3. 保持一致性：所有生成的页面都将采用相同的视觉语言

常见问题

• ❌ 忘记更新 .stitch/next-prompt.md（导致循环中断）
• ❌ 重建站点地图中已有的页面
• ❌ 未在提示词中加入 .stitch/DESIGN.md 中的设计系统内容
• ❌ 保留占位链接（href="#"），而不是设置实际导航
• ❌ 创建新项目后忘记保存 .stitch/metadata.json

故障排除

问题	解决方案
Stitch 生成失败	检查提示词是否包含设计系统区块
样式不一致	确保 .stitch/DESIGN.md 是最新版本，且已正确复制
循环停滞	确认 .stitch/next-prompt.md 已更新，且包含有效的 frontmatter
导航失效	检查所有内部链接是否使用了正确的相对路径