StitchFlow：基于AI的本地化UI生成工具，打通产品简报到可交付代码

1. 项目概述：从产品简报到可交付UI的本地化桥梁

如果你和我一样，是个经常在项目早期需要快速探索UI方向的产品工程师或设计工程师，那你一定对“从想法到视觉稿”这个过程的漫长和反复深有体会。产品经理丢过来一段文字描述，你需要在Figma里吭哧吭哧画半天，来回沟通几轮才能定下个大致方向，效率低不说，沟通成本还高。最近，我发现了一个能极大压缩这个“模糊前端”周期的利器——StitchFlow。简单来说，它就是一个能将纯文本的产品简报（Prompt），在几分钟内转化为具体的UI设计方向、Tailwind友好的HTML代码以及可直接预览的屏幕截图，并且这一切都在你的本地机器上完成。

StitchFlow的核心价值在于，它把Google强大的Stitch SDK（一个AI驱动的UI生成模型）打包成了一个可移植的、跨多个AI编码助手（Agent）客户端的工作流。这意味着，无论你习惯在OpenAI的Codex、Anthropic的Claude Code、OpenClaw、GitHub Copilot还是Google的Gemini CLI里工作，你都可以通过一个统一的技能（Skill）来调用这个UI生成能力。你不再需要自己从头去集成Stitch的API，处理复杂的调用逻辑和结果保存；StitchFlow为你准备好了一切，就像一个预配置好的“设计冲刺”工具箱。生成的所有产物——HTML文件、PNG截图、包含元数据的JSON文件——都会规整地保存在你本地的一个runs/目录下，方便你和团队即时审查、迭代，甚至直接嵌入到项目原型中。这对于需要快速验证UI想法、在编写实际前端代码前进行多方案探索的团队来说，无疑是一个生产力倍增器。

2. 核心设计思路与架构拆解

2.1 为什么选择“技能化”与“本地化”双轨策略？

StitchFlow的设计哲学非常明确：降低使用门槛，提升结果的可控性和可移植性。这直接体现在它的两个核心架构选择上。

首先，是“技能化”（Skill）。在当前的AI编码助手生态中，每个平台（如Codex、Claude Code）都有自己扩展功能的方式，但通常都支持一种类似“技能”或“插件”的机制。StitchFlow没有为每个平台单独开发一个插件，而是采用了“一个核心技能，多平台适配”的策略。它定义了一个符合SKILL.md或AGENTS.md规范的核心技能包，然后通过安装脚本，在多个平台的技能目录中创建符号链接（Symlink）或适配入口。这样做的好处是，维护一套核心逻辑就能覆盖所有主流平台，用户无论在哪个环境中，都能通过熟悉的指令（如Codex的$stitchflow、Claude Code的/stitchflow）来触发相同的功能，体验一致。

其次，是彻底的“本地化”（Local-First）。与许多将生成过程和结果托管在云端的服务不同，StitchFlow强调所有关键操作和产物都在本地。它通过一个独立的、名为stitch-starter的工具包来实现。这个工具包本质上是一个Node.js项目，封装了与Stitch API的交互、任务排队、结果处理、文件保存等所有“脏活累活”。当你调用技能时，指令最终会被路由到这个本地工具包执行。本地化的优势显而易见：没有网络延迟带来的交互卡顿，生成速度更快；数据完全私有，你的产品简报和生成的UI设计不会离开你的机器；产物立即可得，生成的HTML和图片文件直接躺在你的文件夹里，用浏览器就能打开，用任何图片查看器都能预览，分享给同事也只需发个文件，无需权限和账号。

2.2 工作流解析：从Prompt到Artifact的完整链条

理解StitchFlow的工作流，能帮你更好地驾驭它。整个过程可以分解为以下几个环节：

1. 指令触发：你在支持的AI编码助手客户端中输入一个包含特定指令的Prompt。例如，在Claude Code中键入/stitchflow a dashboard for user analytics。
2. 指令路由：客户端识别到stitchflow技能被调用，会将这个请求连同你的Prompt，传递给本地安装的StitchFlow技能模块。
3. 任务执行：技能模块接收到请求后，会调用本地的stitch-starter工具包。工具包负责准备请求参数，通过官方SDK向Google的Stitch API发送生成请求。这里值得注意的是，工具包并非简单转发，它可能包含了一些优化，比如对Prompt进行预处理以确保符合Stitch模型的最佳实践，或者处理一些默认的生成参数（如屏幕尺寸、风格倾向）。
4. 结果处理与保存：Stitch API返回生成结果（通常是包含UI描述和布局的数据）。stitch-starter工具包的核心工作在这里展开：它会将返回的数据渲染成干净的、基于Tailwind CSS的HTML，然后使用一个无头浏览器（如Puppeteer）对这份HTML进行截图，最终将HTML文件、图片文件以及原始的API响应JSON，一并保存到一个按时间戳和操作类型命名的独立文件夹中。
5. 结果返回与展示：技能模块将生成结果的路径或关键信息（如截图保存位置）格式化后，返回给AI编码助手客户端，呈现给你。同时，所有原始文件已经在你指定的本地目录里了。

这个链条的关键在于，StitchFlow抽象了所有复杂性。你不需要关心API密钥如何管理、HTTP请求如何构造、HTML如何渲染、截图怎么截。你只需要提供一个想法（Prompt），就能得到一套立即可用的、本地的设计资产。

注意：虽然StitchFlow极大简化了流程，但它依然依赖于Google Stitch API的服务。这意味着你需要一个有效的STITCH_API_KEY，并且该服务的可用性和生成质量受Google方面控制。StitchFlow提供的是工作流和封装，而不是底层的生成模型。

3. 详细安装与环境配置指南

要让StitchFlow跑起来，你需要完成几个步骤。别看步骤多，其实每一步都很直接，跟着做五分钟内就能搞定。

3.1 前置条件检查

在开始安装之前，请确保你的系统满足以下最低要求：

• Node.js 22或更高版本：这是stitch-starter工具包运行的基础。你可以通过终端运行node -v来检查版本。如果版本过低，建议使用nvm（Node Version Manager）来安装和管理Node.js版本。
• 有效的STITCH_API_KEY：这是调用Google Stitch API的凭证。你需要前往Google AI Studio或相关的API控制台（具体取决于Stitch API的申请渠道，项目README中可能提供指引）申请一个API密钥。请妥善保管此密钥，就像保管你的OpenAI API Key一样。
• 至少一个支持的AI编码助手客户端：你必须已经安装并配置好了以下至少一个工具：
  • OpenAI Codex CLI
  • Anthropic Claude Code
  • OpenClaw (with ClawHub)
  • GitHub Copilot CLI
  • Google Gemini CLI 这些客户端的安装方法各不相同，请参照各自的官方文档进行安装和基础配置。

3.2 一键安装与初始化

StitchFlow提供了非常便捷的一键安装脚本，这是最推荐的安装方式。

打开你的终端（Terminal、iTerm、Windows Terminal等），依次执行以下命令：

# 1. 克隆项目仓库到本地 git clone https://github.com/yshishenya/stitchflow.git cd stitchflow # 2. 运行安装脚本，并指定 `--target all` 来安装所有支持的客户端适配 bash install.sh --target all

这个install.sh脚本做了很多事情：

• 它会将核心技能文件复制到统一的Agent技能目录（通常是~/.agents/skills/stitchflow）。
• 它会克隆或初始化stitch-starter工具包到~/.agents/stitch-starter。
• 它会根据你系统上检测到的客户端，在相应的目录（如~/.codex/skills/,~/.claude/skills/）创建指向核心技能的符号链接。这就是实现“一次安装，多处使用”的魔法所在。
• 它还会为兼容性保留一个旧的技能别名stitch-design-local，确保之前依赖此别名的脚本或习惯仍能工作。

3.3 关键配置：注入API密钥

安装完成后，最关键的步骤是配置你的Stitch API密钥。所有生成请求都将使用这个密钥。

你需要创建一个环境配置文件。根据安装脚本的输出或项目约定，工具包根目录下应该有一个.env文件。如果不存在，请手动创建。

# 进入 stitch-starter 工具包目录 cd "${STITCH_STARTER_ROOT:-$HOME/.agents/stitch-starter}" # 使用你喜欢的文本编辑器编辑或创建 .env 文件，例如使用 nano nano .env

在打开的.env文件中，添加如下一行：

STITCH_API_KEY=你的_Stitch_API_密钥_在这里

请将你的_Stitch_API_密钥_在这里替换为你实际申请的API密钥。保存并退出编辑器。

重要提示：.env文件通常包含敏感信息，请确保它被添加到你的.gitignore文件中，避免意外提交到版本控制系统。

3.4 客户端重启与验证

配置好API密钥后，务必完全退出并重新启动你使用的AI编码助手客户端。这是因为许多客户端在启动时会加载技能配置，重启才能确保它识别到新安装的stitchflow技能。

验证安装是否成功，可以尝试在你客户端的聊天界面中输入一个简单的测试指令。例如，在Claude Code中，输入：

/stitchflow help

或者在Codex中，输入：

What can $stitchflow do?

如果安装成功，客户端应该能识别到该技能，并返回一些基本的帮助信息或确认技能可用。如果遇到“command not found”或类似错误，请检查安装脚本的输出日志，确认技能链接是否创建成功，并确保已重启客户端。

4. 核心功能实操与高级用法

安装配置妥当后，我们就可以开始施展拳脚了。StitchFlow的核心功能围绕“生成”、“编辑”和“变体”展开，下面我们结合具体命令和场景来深入看看。

4.1 基础生成：从零到一的UI创造

这是最常用的功能。你有一段文字描述，想看看AI能把它变成什么样的界面。

在AI助手客户端中直接使用：这是最自然的方式。只需在聊天框中输入指令即可。

• Codex风格:Use $stitchflow to generate a clean admin panel for a content management system, with a top navigation bar, a data table, and action buttons.
• Claude Code风格:/stitchflow a mobile-friendly recipe app homepage featuring a search bar, category filters, and a grid of recipe cards.
• OpenClaw风格:Use the stitchflow skill to create a login page for a fintech app, with a focus on security and a modern, trustworthy aesthetic.

输入后，助手会调用技能。稍等片刻（通常几十秒，取决于API响应速度），你会收到回复，告知你生成已完成，并附上截图预览的路径，例如Generated screen saved to: /Users/yourname/.agents/stitch-starter/runs/20250415_102030-generate-dashboard/screen.png。你可以直接点击路径（如果客户端支持）或手动前往该文件夹查看所有生成物。

通过CLI直接调用工具包：有时你可能想脱离AI助手环境，或者在脚本中批量调用，这时可以直接使用工具包提供的npm脚本。

# 确保在 stitch-starter 目录下 cd "${STITCH_STARTER_ROOT:-$HOME/.agents/stitch-starter}" # 使用 npm run generate 并传入 --prompt 参数 npm run generate -- --prompt “A dark mode weather dashboard for desktop, showing current conditions, hourly forecast, and severe weather alerts.”

执行后，终端会输出运行日志，并在runs/目录下生成包含时间戳的新文件夹。你可以立刻用浏览器打开其中的screen.html文件查看交互式效果，或者查看screen.png截图。

4.2 迭代编辑：在已有设计上精雕细琢

你很少能一次就得到完美的设计。第一版生成后，你通常会有“颜色再沉稳些”、“间距调大点”、“换个字体”之类的想法。这时就用到了编辑功能。

编辑功能需要基于上一次的生成结果。StitchFlow在runs/目录下保存了一个latest-screen.json文件，它指向最近一次单屏幕生成的结果。编辑操作会读取这个文件中的设计上下文。

在AI助手客户端中使用编辑：

/stitchflow Make the previous dashboard more minimalist. Remove the sidebar, use a monochromatic color scheme, and increase the whitespace.

或者，更明确地引用某个特性：

Use $stitchflow to edit the last design: change the primary color to a deep blue (#2563eb) and convert the stat cards to a horizontal layout.

通过CLI进行编辑：

npm run edit -- --prompt “Convert the layout to a single-column, mobile-responsive view and use a warmer color palette.”

编辑功能极大地提升了工作流的连贯性，让你可以像与设计师对话一样，通过自然语言持续优化UI，而无需手动调整代码。

4.3 探索变体：一次性获取多个设计方向

在项目初期，探索不同的视觉方向至关重要。手动创建多个Mockup费时费力。StitchFlow的“变体”功能可以一键生成多个不同风格的设计供你选择。

在客户端中请求变体：

/stitchflow Explore three distinct visual directions for a podcast app landing page: one bright and energetic, one dark and sophisticated, and one using abstract geometric shapes.

通过CLI生成变体：

npm run variants -- --prompt “A pricing page for a SaaS product” --variant-count 4

执行变体生成后，你会在runs/目录下得到一个variants.json文件，里面包含了所有变体的元数据，以及对应的多个子文件夹（如variant-1/,variant-2/），每个文件夹里都有一套完整的HTML和截图。你可以快速浏览这些截图，挑选最符合产品调性的方向，极大地加速了决策过程。

4.4 产物管理与组织

所有生成物都井然有序地存放在~/.agents/stitch-starter/runs/目录下。每次操作（生成、编辑、变体）都会创建一个新的文件夹，命名格式为<时间戳>-<操作类型>-<简短描述>，例如20250415_142055-generate-analytics-dash。

每个文件夹内通常包含：

• screen.html: 完整的、可独立在浏览器中运行的HTML文件，通常已内联Tailwind CSS样式。
• screen.png(或.jpeg/.webp): 该HTML的截图，方便快速预览和分享。
• result.json(或variants.json): 来自Stitch API的原始响应数据，包含详细的布局、组件和样式信息。这对于调试或需要进一步程序化处理的情况非常有用。
• html-url.txt/image-url.txt: 有时可能包含生成文件的临时在线URL（如果API支持），但本地路径始终是主要的访问方式。

这种组织方式让你可以轻松回顾历史、比较不同迭代，或者将某个版本的HTML直接复制到你的项目中进行二次开发。

5. 实战技巧与避坑指南

经过一段时间的使用，我积累了一些能让StitchFlow发挥更大效能的技巧，也踩过一些坑，在这里分享给你。

5.1 编写高效Prompt的秘诀

Stitch模型对Prompt的理解能力很强，但清晰的指令能得到更精准的结果。我总结了一个“角色-场景-需求-约束”的Prompt结构：

1. 定义角色与场景：告诉AI你在为谁、在什么情境下设计。例如：“为面向中小企业的项目管理工具设计一个…”
2. 明确核心需求：列出必须包含的核心功能模块或元素。例如：“…包含项目甘特图、团队任务看板和实时聊天窗口的…”
3. 描述视觉风格与感觉：使用形容词和设计术语。例如：“…采用现代化、专业感的深色主题…”
4. 添加具体约束：指定技术栈或特殊要求。例如：“…使用Tailwind CSS，并为移动端做响应式适配。”

一个优秀的综合Prompt示例：

“为一家高端健身品牌的会员App设计一个主页（角色与场景）。需要突出今日推荐课程、会员数据概览（步数、卡路里）和预约快速入口（核心需求）。视觉上要充满活力、激励人心，使用大胆的渐变色和强对比字体（视觉风格）。布局优先考虑移动端，组件使用Tailwind的类名（具体约束）。”

5.2 管理API成本与速率限制

Stitch API并非无限免费，你需要关注其定价策略和速率限制。虽然StitchFlow是本地工具，但每次生成、编辑、变体都会消耗API调用。

• 批量操作前先小试：在运行一个生成5个变体的任务前，先用一个简单的Prompt生成一个版本来测试效果和风格是否符合预期，避免浪费额度在不合适的方向上。
• 利用编辑功能：相比生成一个全新的设计，基于现有设计进行编辑（edit）通常消耗更少的资源，且能保持设计的一致性。对于微调，优先使用编辑。
• 关注result.json：如果生成的UI大体结构满意但细节不佳，不要急于重新生成。你可以手动微调screen.html，或者基于result.json中的数据结构进行更精细的Prompt编辑，这比完全从头开始更经济。

5.3 处理生成结果不理想的场景

AI生成具有随机性，有时结果可能不尽如人意。别灰心，可以尝试以下策略：

• 增加特异性：如果生成结果过于通用或混乱，尝试在Prompt中加入更具体的组件名称（如“use a card component with a header and footer”）、布局描述（如“a two-column layout with a 3:1 ratio”）或甚至颜色代码（“primary color: #7C3AED”）。
• 分步生成：不要试图在一个Prompt中描述一个极其复杂的完整页面。可以先生成一个核心区域（如“生成一个数据表格组件”），得到满意的组件后，再在下一个Prompt中要求将其放入一个更大的布局（如“将之前生成的表格放入一个带有侧边栏和标题的仪表盘中”）。
• 迭代与混合：将StitchFlow视为一个强大的“初级设计师”。用它快速产出多个方向和基础框架，然后由人类设计师或前端工程师基于生成的HTML进行深度定制和优化。它的强项是快速发散和搭建基础，而不是完成最终像素级完美的设计。

5.4 集成到现有工作流

StitchFlow生成的HTML是基于Tailwind CSS的，这为集成到现代前端项目提供了便利。

• 直接提取组件：你可以将screen.html中某个满意的部分（比如一个设计精美的数据卡片<div class=”card”>…</div>）直接复制粘贴到你的Vue/React组件中。
• 作为设计参考：生成的截图可以快速放入产品需求文档（PRD）、Confluence页面或Slack频道，作为视觉参考与团队进行异步沟通，比文字描述直观得多。
• 自动化脚本：你可以编写一个简单的Shell脚本或Node.js脚本，定期运行npm run generate来为你的产品线生成一系列标准页面的初始模板，建立一个可快速启动的UI模板库。

6. 跨平台兼容性详解与故障排查

StitchFlow的一大优势是跨平台，但不同客户端的集成方式略有差异，了解这些细节有助于排错。

6.1 各客户端集成机制对比

6.2 常见安装与运行问题排查

问题1：客户端提示“未知技能”或“命令未找到”。

• 检查步骤：
  1. 确认你运行了bash install.sh --target all且没有报错。
  2. 检查对应的技能目录是否存在符号链接。例如，对于Claude Code，运行ls -la ~/.claude/skills/查看是否有stitchflow链接指向~/.agents/skills/stitchflow。
  3. 最重要的步骤：完全退出客户端（包括后台进程），然后重新启动。很多客户端只在启动时加载技能列表。
  4. 如果使用环境变量（如CLAUDE_HOME），请确保其指向正确的目录，并且在启动客户端前已导出。

问题2：生成失败，提示API密钥错误或网络问题。

• 检查步骤：
  1. 确认~/.agents/stitch-starter/.env文件中的STITCH_API_KEY值正确无误，没有多余的空格或换行。
  2. 尝试在终端中手动运行一个生成命令来获取更详细的错误信息：

     cd ~/.agents/stitch-starter node index.js generate --prompt “test”

  3. 检查你的网络连接，确保可以访问Google的API服务。某些地区或网络环境可能需要特殊配置。

问题3：生成的HTML在浏览器中样式错乱。

• 原因与解决：StitchFlow生成的HTML通常内联了Tailwind CSS的一个子集或特定编译版本。如果样式错乱，可能是因为缺少某些Tailwind类或浏览器兼容性问题。
  • 临时查看：使用生成文件夹内的screen.png截图，这是最保真的输出。
  • 集成到项目：如果打算复用HTML结构，建议将其中的类名与你项目中的Tailwind CSS配置进行比对和调整。更好的方式是只借鉴其DOM结构，样式用自己的Tailwind工具类重写。

问题4：npm run命令在stitch-starter目录下无法执行。

• 检查步骤：
  1. 确保你位于正确的目录：~/.agents/stitch-starter。
  2. 运行npm install来安装项目依赖（通常安装脚本已执行此操作，但可重复执行）。
  3. 检查package.json中是否正确定义了generate,edit,variants等脚本。

6.3 进阶配置：自定义输出与行为

stitch-starter工具包本身是一个Node.js项目，这意味着你有一定的自定义空间。

• 修改默认截图尺寸：你可以查看并修改工具包源码（通常是index.js或lib/generator.js）中调用无头浏览器截图的部分，调整page.setViewport的参数来改变生成截图的宽度和高度，以适应桌面端或移动端的原型展示。
• 更改输出格式：默认输出PNG图片。你可以在截图代码部分，将screenshot方法的type参数改为‘jpeg’以获得更小的文件体积，或改为‘webp’以获得更好的压缩率。
• 添加后处理脚本：你可以在工具包生成文件后，自动运行一个自定义脚本，例如将生成的HTML通过Prettier格式化，或将截图上传到团队的图床。这需要你修改工具包的输出处理逻辑。

7. 项目生态、贡献与未来展望

StitchFlow不仅仅是一个工具，它代表了一种工作流理念的实践。它的项目结构清晰，文档齐全，为社区贡献和自定义扩展留出了空间。

7.1 理解项目结构

克隆下来的stitchflow仓库主要包含两部分：

• 技能定义部分 (skills/stitchflow/): 这里存放了核心的SKILL.md文件，它定义了技能的名称、描述、参数和调用方式。还有各平台特定的清单文件（如GitHub Copilot的plugin.json），用于在不同客户端注册技能。
• 本地工具包部分 (stitch-starter/): 这是一个独立的Node.js项目，是实际干活的“引擎”。它包含了与Stitch API通信、处理任务、渲染HTML、截图和文件管理的所有逻辑。安装脚本会把这个工具包克隆/放置到你的~/.agents/目录下独立运行。

这种分离使得技能接口保持轻量和兼容性，而复杂的业务逻辑则在独立的、可更新的工具包中维护。

7.2 如何为项目做贡献

如果你发现Bug，或者有改进的想法，项目的CONTRIBUTING.md文件提供了指引。常见的贡献方式包括：

• 提交Issue：报告Bug，或提出新功能建议。在提交前，请先搜索是否已有类似问题。
• 修复Bug或开发功能：Fork仓库，在本地进行修改，确保通过测试后，提交Pull Request。
• 改进文档：如果你发现某些步骤不清楚，或者有更好的使用示例，可以提交文档更新。
• 分享使用案例：在项目的Discussion区或社区分享你用StitchFlow构建了什么的经验，这对其他用户非常有价值。

7.3 在团队中推广与实践建议

要将StitchFlow有效地融入团队工作流，可以考虑以下几点：

• 设立“设计冲刺”环节：在启动新功能或页面开发前，用1-2小时的时间，让产品经理、设计师和前端工程师一起，用StitchFlow快速生成3-5个不同的UI方向。通过即时可视化的讨论，快速收敛到1-2个最有潜力的方案。
• 建立Prompt库：团队可以共同维护一个prompt-recipes.md文件，积累针对常用组件（如表格、表单、卡片、导航栏）和页面类型（如登录页、仪表盘、详情页）的高效Prompt模板。新成员可以快速上手，保证输出质量的一致性。
• 与设计系统结合：虽然StitchFlow生成的是通用Tailwind CSS，但你可以通过编辑生成的screen.html，将其中核心的样式变量（如颜色、圆角、字体）替换成你团队设计系统中的Token，使其生成的结果更贴近品牌规范。

StitchFlow正处于快速发展阶段，随着底层Stitch模型的进化，其生成质量和可控性有望进一步提升。对于前端开发者和产品构建者而言，掌握这类“Prompt-to-UI”的工具，正逐渐从“锦上添花”变为“必备技能”。它不会取代专业设计师，但能成为连接产品构想与视觉原型之间最高效的桥梁，让你在激烈的市场竞争中，更快地将想法转化为可见、可感、可讨论的实物。