HolyStitch

什么是 holystitch？

HolyStitch 是一个 MCP（Model Context Protocol）工具，它通过 Stitch API 读取你的 Stitch 项目，并将其编译成可运行的 Next.js 代码库。它不是让模型“猜测”转换，而是生成完整的 JSX/Next.js 输出文件。

其核心目的是以确定性方式将 Stitch 屏幕转为磁盘上的 React/Next.js 项目，包括组件结构、样式配置，以及保留的源 HTML 以供参考——让你能审阅结果并完成剩余清单项。

Stitch API 摄取（按项目 ID）： 使用你提供的 Stitch 项目 ID，通过 Stitch API 获取项目中的每个屏幕。
结构化 React 编译（非提示）： 基于 Stitch 嵌入的 HTML 标记（例如 ）解析组件，并写入有效的 React JSX。
确定性 Next.js 项目输出： 生成包含 app/、components/ 和支持文件的 Next.js 项目目录，即装即用。
共享组件提取与去重： 检测跨多个屏幕共享的组件，并在 components/ 中仅写入一次，而非每页重复。
Tailwind 主题提取： 提取精确的 Tailwind 主题配置，包括颜色、字体和暗黑模式设置，并写入 tailwind.config.js。
JSX/HTML 边缘情况处理： 执行常见的 JSX 安全转换和规范化，包括 class→className、for→htmlFor、内联样式字符串转为样式对象（包括 url()、calc()、var() 和 font-variation-settings）、正确的图标字体渲染（例如 Material Symbols/Icons）、<pre><code> 内转义代码块，以及重复属性处理。

本地构建工具
- 克隆并构建：
  - git clone https://github.com/BaselAshraf81/holystitch
  - cd holystitch
  - npm install
  - npm run build
- 记下构建文件夹的完整路径（例如 /Users/alice/holystitch）。
获取 Stitch API 密钥
- 从 Stitch 项目设置中复制你的 API 密钥。
配置你的 MCP 主机（Claude Desktop / Cursor / Windsurf / 其他 MCP 主机）
- 将 MCP 主机指向构建的包（使用构建的 dist/index.js 路径）并设置 STITCH_API_KEY。
- Claude Desktop 示例：
  - 在 claude_desktop_config.json 中添加条目，包含 command: "node"、args: ["<full path>/dist/index.js"]，以及 env: { "STITCH_API_KEY": "your-api-key-here" }。
提供你的 Stitch 项目 ID
- 使用 Stitch URL 中的项目 ID（仓库文档显示为 https://stitch.withgoogle.com/project/<projectId> 的一部分）。
运行转换
- 让你的 AI 助手（连接到 MCP 服务器）将 Stitch 项目 ID 转换为目标文件夹中的 Next.js 应用。
- 工具将项目文件写入磁盘；AI 可随后帮助完成后续清单项（例如路由、字体或剩余 JSX 边缘情况），这些需要人工审阅。

将现有 Stitch 登陆页转为 Next.js 应用： 将 Stitch 屏幕编译成 React 组件和 app/ 路由，使设计成为可运行代码。
处理大型多屏幕 Stitch 项目中的共享 UI： 使用组件去重提取重复部分（例如导航栏、页脚、英雄区）为共享组件。
精确保留样式配置： 将相同的 Tailwind 主题（颜色、字体和暗黑模式配置）提取到 tailwind.config.js，而非手动重现样式。
减少 HTML-to-JSX 转换中的 LLM 猜测： 依赖编译器的特定 JSX 安全规则（属性重命名、内联样式解析、转义代码块）避免常见转换失败。
生成可审阅代码库用于迭代开发： 从生成的 Next.js 项目开始（保留 stitch-source/ 以供参考），然后用你自己的开发流程调整功能和路由。

holystitch 转换 Stitch 项目时会消耗 AI 令牌吗？ 仓库描述称其为“编译而非提示”，转换本身“零令牌”。
运行转换需要提供什么？ 你提供 Stitch 项目 ID，并在 MCP 主机配置中设置 STITCH_API_KEY。
它生成什么框架？ 文档默认输出为 Next.js 项目。工具还提到可使用 vite 作为框架选项，但输出示例主要聚焦 Next.js。
生成文件夹中包含什么？ 示例输出包括 components/、app/、stitch-source/（保留原始 HTML 以供参考）、tailwind.config.js，以及 package.json 和 tsconfig.json 等项目配置文件。
能只转换特定屏幕吗？ 文档选项包括 screenIds 设置，可传入特定屏幕 ID 以转换子集；默认是“所有屏幕”。

手动 Stitch 到 React 转换： 手动重建组件和 Tailwind 样式。对于小型项目可行，但通常耗时更长，且在 JSX 属性边缘情况更容易出错。
使用 AI 助手进行基于提示的 HTML 到 React/Next.js 转换： 将导出的 HTML/标记发送给 LLM 进行转换。与编译器方法不同，它可能需要更多迭代来修正 className/属性问题和重复结构。
设计到代码的通用模板生成器： 使用从设计资源生成 React/Next.js 代码骨架的工具。这些工具可能无法像 Stitch 专用编译器那样保留 Stitch 特定组件结构、Tailwind 主题细节或嵌入标记。
组件优先的 UI 重新实现： 将每个屏幕视为独立的 React 实现任务，并自行构建共享组件。这提供最大控制，但将转换工作完全转移到开发而非生成。