自主批量生成整站多页面：用接力棒文件循环逐页生成、集成…

需要以迭代循环方式自主构建完整多页站点（每次生成一页并保持循环不断）时使用。

适用场景

解决思路

1. 若 `.design/` 不存在，先向用户询问：站点名称与用途、目标受众、期望美学风格（极简/大胆/温暖等）、想要的页面清单、品牌色（或从现有站点用 `/design-system` 技能提取）。
2. 创建项目脚手架文件：`.design/SITE.md`（愿景、站点地图、路线图——项目长期记忆）、`.design/DESIGN.md`（视觉设计系统——一致性来源）、`.design/next-prompt.md`（接力棒——当前任务）、`site/public/`（生产页面目录）。
3. 按 SITE.md 模板写入 `.design/SITE.md`，按 DESIGN.md 模板写入 `.design/DESIGN.md`（可用 `design-system` 技能从现有站点提取），并为首页写入第一个接力棒文件。
4. 后续每轮先读 `.design/next-prompt.md`，解析 YAML frontmatter，提取 `page`（输出文件名，不含 .html）、`layout`（可选，`standard`/`wide`/`sidebar`，默认 `standard`）和 prompt 正文。
5. 生成前查阅上下文文件：`.design/SITE.md` 第 4 节 Sitemap（不要重建已有页面）、`.design/DESIGN.md`（配色、字体、组件样式）、`site/public/` 中已有页面（header/footer/nav 模式）；务必读取最近一个页面的 HTML，逐字提取 header、navigation、footer 标记，新页面必须使用完全相同的共享元素。
6. 每轮开始时检测 Stitch 后端是否可用：`ls node_modules/@google/stitch-sdk 2>/dev/null`；检查 `.dev.vars` 或环境变量中是否设置了 `STITCH_API_KEY`；检查 `.design/metadata.json` 是否存在（内含 Stitch 项目 ID）。三者齐备才用 Stitch，否则回退到 Claude 生成。
7. 方式 A（默认 Claude 生成）：生成完整 HTML 文件，使用 Tailwind CSS（CDN 引入），严格匹配 `.design/DESIGN.md` 的设计系统，逐字复用已有页面的 header/nav/footer，自包含（单文件、无构建步骤），移动优先响应式，若设计系统要求则包含暗色模式，使用语义化 HTML（正确的标题层级、landmark、alt 文本），导航链接全部指向真实页面（已存在或计划中）；把文件写入 `site/public/{page}.html`。
8. 方式 B（Stitch 生成，若可用）：把接力棒正文与 DESIGN.md 设计系统块合成 prompt；调用 `project.generate(prompt, deviceType)` 生成屏幕（deviceType 为 `"MOBILE"`/`"DESKTOP"`/`"TABLET"`/`"AGNOSTIC"`，第三个参数可选 `"GEMINI_3_PRO"`/`"GEMINI_3_FLASH"`）；从 `screen.getHtml()` 下载 HTML 到 `.design/designs/{page}.html`；从 `screen.getImage()` 下载截图到 `.design/screenshots/{page}.png`；后处理 Stitch HTML（替换 header/nav/footer 为项目共享元素、统一 Tailwind 配置、接通内部导航链接）；保存处理后的文件到 `site/public/{page}.html`；把新的 screen ID 更新进 `.design/metadata.json`。
9. Stitch 安装与 API 用法：`npm install @google/stitch-sdk`，在环境或 `.dev.vars` 中设置 `STITCH_API_KEY`；用 `stitch.callTool("create_project", { title: "My Site" })` 建项目，`stitch.project("4044680601076201931")` 引用已有项目，`stitch.projects()` 列项目，`project.screens()` 列屏幕，`project.getScreen("id")` 取单个屏幕；细化已有屏幕用 `screen.edit("...")` 而不是重新生成；用 `screen.variants("...", { variantCount: 3, creativeRange: "EXPLORE", aspects: ["COLOR_SCHEME"] })` 生成变体（`creativeRange` 取 `"REFINE"`/`"EXPLORE"`/`"REIMAGINE"`，`aspects` 取 `"LAYOUT"`/`"COLOR_SCHEME"`/`"IMAGES"`/`"TEXT_FONT"`/`"TEXT_CONTENT"`）；`getHtml()` 与 `getImage()` 返回下载 URL，图片 URL 追加 `=w1280` 取全分辨率；鉴权失败/未找到/限流会抛 `StitchError`，码为 `AUTH_FAILED`、`NOT_FOUND`、`RATE_LIMITED`。
10. Stitch 集成技巧：把项目 ID 持久化在 `.design/metadata.json`，不要每轮新建项目；细化用 `screen.edit()` 而非整页重生成；对 Stitch 产出的 HTML 做后处理（替换 header/footer 为共享元素）；prompt 中带上 DESIGN.md 上下文，Stitch 在明确设计系统说明下效果更好。
11. 集成到站点：更新所有已有页面的导航以加入新页面；把 `href="#"` 占位链接替换为真实页面 URL；核对跨页一致性（header、footer、nav 在各页必须完全相同）；检查内部链接无失效。
12. 视觉验证（若有浏览器自动化）：`npx serve site/public -p 3456` 启动本地服务；在桌面 1280px 和移动 375px 宽度截图新页面；保存到 `.design/screenshots/{page}-desktop.png` 和 `{page}-mobile.png`；与设计系统目视比对；修复问题（布局破损、配色错误、导航不一致）；停止服务器。若没有浏览器自动化则跳到第 6 步（更新文档）。
13. 更新站点文档 `.design/SITE.md`：在第 4 节 Sitemap 标记完成 `[x] {page}.html — {描述}`；从第 5 节 Roadmap 或第 6 节 Ideas 中删除已被消费的条目；补充生成过程中发现的新想法。
14. 关键步骤：完成迭代前必须更新 `.design/next-prompt.md`，否则循环中断。选择下一个页面优先级为：先第 5 节高优先级 → 再中优先级 → 再第 6 节 Ideas → 最后自行发明符合站点愿景的页面。接力棒内容包含：YAML frontmatter（`page`，可选 `layout`）、页面目的与内容描述、从 `.design/DESIGN.md` 第 6 节复制的设计系统块、编号的页面结构（sections）。
15. 若站点已完成（路线图全部完成、无更多想法）：写入 `page: _complete` 的接力棒并附构建总结，标志循环结束。循环结束条件：SITE.md 第 4 节全部标记 `[x]`、用户要求停止、或接力棒包含 `page: _complete`。结束时输出总结：已构建页面（带链接）、截图（若有）、后续可做的想法。
16. 跨页一致性规则（防漂移）：Header/Nav 从最近页面逐字复制 HTML，绝不重新生成；Footer 同样逐字复制，只改当前页高亮指示；若用 `<script>` 配置块配置 Tailwind，各页必须完全一致；颜色只用 DESIGN.md 中的精确 hex 值，绝不近似；所有页面使用同一个 Google Fonts `<link>` 标签；间距使用一致的 padding/margin 尺度（记录在 DESIGN.md 中）。
17. 写接力棒 prompt 时，用术语映射把模糊需求转成精确指令："menu at the top"→"sticky navigation bar with logo and menu items"；"big photo"→"full-width hero section with focal-point imagery"；"list of things"→"responsive card grid with hover states and subtle elevation"；"button"→"primary call-to-action button with hover transition"；"form"→"form with labelled input fields, validation states, and submit button"；"picture area"→"hero section with background image or video"；"sidebar"→"collapsible side navigation with icon-label pairings"；"popup"→"modal dialog with overlay and smooth entry animation"；"footer stuff"→"footer with sitemap links, contact info, and legal notices"；"cards"→"content cards with consistent padding, rounded corners, and shadow"；"tabs"→"tabbed interface with active indicator and smooth content transition"；"search"→"search input with icon, placeholder text, and results dropdown"；"pricing"→"pricing comparison cards with highlighted recommended tier"；"testimonials"→"testimonial carousel or grid with avatar, quote, and attribution"。
18. 把氛围词细化："Modern"→"Clean, minimal, generous whitespace, high-contrast typography"；"Professional"→"Sophisticated, trustworthy, subtle shadows, restricted premium palette"；"Fun / Playful"→"Vibrant, rounded corners, bold accent colours, bouncy animations"；"Dark Mode"→"High-contrast accents on deep slate or near-black backgrounds"；"Luxury"→"Elegant, spacious, fine lines, serif headers, high-fidelity photography"；"Tech / Cyber"→"Futuristic, neon accents, glassmorphism, monospaced typography"；"Warm / Friendly"→"Soft colours, rounded shapes, handwritten accents, inviting imagery"；"Bold / Industrial"→"Strong typography, high contrast, geometric shapes, dark backgrounds"；"Organic / Natural"→"Earth tones, soft textures, organic shapes, nature photography"；"Editorial"→"Magazine-like layouts, strong typographic hierarchy, generous leading"。
19. 几何、深度、间距直接映射到 Tailwind 类：圆角 Pill-shaped→`rounded-full`、Softly rounded→`rounded-xl`、Gently rounded→`rounded-lg`、Sharp/precise→`rounded-none` 或 `rounded-sm`、Glassmorphism→`backdrop-blur-md bg-white/10 border border-white/20`、Frosted→`backdrop-blur-sm bg-white/80`；高度 Flat→`shadow-none`、Whisper-soft→`shadow-sm`、Subtle→`shadow-md`、Floating→`shadow-lg` 或 `shadow-xl`、Dramatic→`shadow-2xl`、Inset→`shadow-inner`；区块密度 Tight→`py-8 md:py-12`、Balanced→`py-12 md:py-16`、Generous→`py-16 md:py-24`、Dramatic→`py-24 md:py-32`。
20. 规避常见坑：忘记更新 `.design/next-prompt.md`（循环中断）；重建 SITE.md Sitemap 中已标 `[x]` 的页面；重新生成 header/nav 而不是从已有页面复制；接力棒 prompt 中漏掉设计系统块；导航里残留 `href="#"` 占位；各页 Tailwind 配置不一致；一次迭代生成多个页面（永远一轮一页）。
21. 目录结构与收尾：项目结构为 `.design/`（SITE.md、DESIGN.md、next-prompt.md、metadata.json、screenshots/）、`site/public/`、`.gitignore`；把 `.design/screenshots/` 加入 `.gitignore`。
22. 循环可由人驱动（用户审阅每页后说 "next" 或 "keep going"）、完全自主（Claude 持续运行直到站点完成）或 CI/CD（`.design/next-prompt.md` 变更触发）；本循环与编排方式无关。

适用边界 · 注意事项

• 只做单页或少量页面、不需要多轮迭代接力时——接力棒循环的上下文与文档维护成本大于收益。
• 已有成熟框架与构建流程（如 Next.js 等需要 bundler）的项目——默认产出是 Tailwind CDN 的单文件自包含 HTML。
• 缺少浏览器自动化时无法完成视觉验证与截图比对，只能跳过该步骤（生成质量校验会打折）。