用途
stitch-to-react 用于把 Stitch 设计稿转换为生产可用的 React 组件。它面向需要将设计稿落地为规范前端代码的场景，通过一套强制性的架构规则约束生成结果，避免出现单文件组件堆砌、逻辑与视图混杂、样式硬编码等问题。
主要能力
- 命名空间发现：运行 list_tools 找到 Stitch MCP 前缀（通常为 stitch: 或 mcp_stitch:），后续调用均使用该前缀。
- 屏幕获取：调用 [prefix]:get_screen，可获取 screenshot.downloadUrl、htmlCode.downloadUrl、width、height、deviceType 以及 designTheme（颜色、字体、圆角）。
- 设计缓存决策：若 .stitch/designs/{page}.html 与 .stitch/designs/{page}.png 已存在，先询问用户是使用缓存还是从 Stitch 刷新，仅在用户确认后才重新下载；不存在则直接下载。
- 高可靠下载：内部 AI fetch 在 GCS 域名上会失败，需使用 bash 脚本：
- HTML：bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" ".stitch/designs/{page}.html"
- 截图：在 URL 后追加 =w{width}，即 bash scripts/fetch-stitch.sh "[screenshot.downloadUrl]=w{width}" ".stitch/designs/{page}.png"
架构规则（不可协商）
- 模块化文件：绝不输出单文件组件堆砌。
- 逻辑隔离：事件处理器放入 src/hooks/。
- 数据解耦：静态内容放入 src/data/mockData.ts。
- 类型安全：每个组件都要有名为 [Component]Props 的 Readonly 接口。
- 样式映射：从 HTML <head> 提取 tailwind.config，同步到 resources/style-guide.json。
文件结构
src/ ├── components/ # 每个组件一个文件 + index.ts barrel ├── hooks/ # useNavigation.ts、useFormState.ts 等 ├── data/ │ └── mockData.ts # 所有静态文本、图片、配置 ├── styles/ │ └── theme.ts # 提取的 Tailwind tokens └── App.tsx
使用方式
- 运行 list_tools 确定 Stitch MCP 前缀。
- 调用 [prefix]:get_screen 获取设计资源与主题信息。
- 按缓存决策流程判断是否重新下载。
- 使用 bash 脚本下载 HTML 与截图（截图 URL 需追加 =w{width}）。
- 按架构规则生成组件、hooks、mockData 与主题文件。
- 生成每个组件后执行验证序列：
- npm run validate <file_path> 进行 AST 合规检查
- 对照 resources/architecture-checklist.md 检查
- npm run dev 要求零控制台错误 只有通过清单且开发服务器无错误，组件才算完成。
适用场景
- 将 Stitch 设计稿批量转换为结构清晰的 React 组件。
- 需要强制模块化、类型安全与样式集中管理的团队协作项目。
- 需要复用设计缓存、避免重复下载的工作流。
限制与禁止事项
- 未检查 .stitch/designs/ 前绝不下载；重新下载前必须询问用户刷新意图。
- 绝不把十六进制颜色硬编码为 Tailwind 任意值（如 bg-[#2563eb]），应提取到主题并使用语义类。
- 绝不跳过 AST 校验，架构清单在标记完成前是必选项。
- 绝不把逻辑放进组件体，事件处理器与状态逻辑放入 src/hooks/。
- 绝不省略 TypeScript 接口，每个组件都需要 Readonly Props 类型。
- 绝不把数据打包进组件文件，所有静态文本、图片、列表放入 src/data/mockData.ts。
- 绝不在生成的 React 组件中包含 Google 许可证头。
- 绝不使用内部 AI fetch 工具处理 Google Cloud Storage URL，它们在 GCS 域名上会失败，应使用 bash 脚本。
故障排查
- 抓取失败（403）：检查脚本引号；确认截图 URL 已追加 =w{width}。
- AST 显示硬编码样式：将十六进制提取到 style-guide.json，再替换为 Tailwind 类。
- TypeScript prop 错误：按 resources/component-template.tsx 模板添加 Readonly 接口。
- 主题类无法识别：确认 tailwind.config 已提取并同步到 style-guide.json。
- 缓存截图过期：检查文件时间戳，请用户确认刷新。