桥接层做桥、技能做脑:设计类智能体为什么绕不开一层服务器

原创2026-11-16 18:39:121,211 阅读
文章标签:人工智能AI 技能AI 插件

桥接层做桥、技能做脑:设计类智能体为什么绕不开一层服务器

把 Stitch 和 stitch-skills 混为一谈,是这类项目最容易踩的第一个坑。前者是一个能听懂自然语言、直接产出 UI 稿的在线设计平台;后者是一堆 Markdown 文件加几个脚本,仓库自述写得很清楚——"A library of Agent Skills designed to work with the Stitch MCP server"(见 README.md)。技能库里没有一行渲染代码,没有字体解析器,没有布局引擎,它甚至不知道"卡片圆角 12px"长什么样。可它偏偏能让 Claude Code、Cursor、Gemini CLI 这些智能体稳定地产出界面。

这件事之所以值得拆开看,是因为它暴露了设计类智能体的一条硬边界:技能负责判断,服务器负责生成,中间必须有一层协议把"谁去调用生成"这件事说清楚。理解这条边界,比背下十几个技能的用法重要得多——它决定了你在团队里落地这套东西时,会在哪三个地方付出真实成本。

一次"生成一个页面"到底发生了什么

先看链路。当用户说"给移动端做一个约会灵感浏览页",generate-design 技能做的事情是:查项目、查设计系统、把口语化的需求翻译成 UI 术语、拼装结构化 prompt,然后调用一次 MCP 工具。仓库里给出的调用参数长得是这样(generate-design/SKILL.md):

{
  "projectId": "...",
  "prompt": "[Your Enhanced Prompt]",
  "designSystem": "assets/...",
  "deviceType": "DESKTOP"
}

注意这个 deviceType 的取值是 MOBILE、DESKTOP、TABLET——这是服务端的枚举,不是 CSS 断点。技能在这里的角色是"填对参数",不是"画出界面"。

生成完成之后,技能做的第二件事是下载:

After generation, download the HTML and screenshot urls from outputComponents to the .stitch/designs directory. Tools: Use curl -o via run_command or similar.

也就是说,HTML 和截图的字节流是服务器产出的,落在 Google 的 CDN 上,技能只是拿 curl 把它搬到本地。整条链路上,技能从未参与像素的构造。

这就是第一个关键结论:桥接协议(这里是 MCP)在设计场景里解决的不是"怎么生成",而是"谁有资格发起生成、用什么 schema 发起、生成结果从哪取"。技能是策略层,MCP 是传输与身份层,Stitch 服务端是执行层。

而这个身份层并不是抽象概念,它落在具体的配置文件里。upload-to-stitch 技能要求智能体自己去翻这些路径找 API Key:

宿主 配置文件位置
Antigravity .gemini/antigravity/mcp_config.json 或 .gemini/jetski/mcp_config.json
Gemini CLI ~/.gemini/settings.json 或 ~/.gemini/extensions/Stitch/gemini-extension.json
Claude Code ~/.claude.json

(出自 upload-to-stitch/SKILL.md)

技能声明自己能碰哪些工具,也是靠 frontmatter 里的 allowed-tools:

allowed-tools:
  - "stitch*:*"
  - "Bash"
  - "Read"
  - "Write"
  - "web_fetch"

stitch*:* 这个通配写法本身就说明了问题:技能并不知道桥那头具体挂了哪些工具,它只知道"有一个 Stitch 命名空间"。所以 design-md 技能的第一步是让智能体跑 list_tools 去发现前缀(例如 mcp_stitch:),后续所有调用都拼这个前缀。技能是写给"未知桥接层"的说明书,而不是写给某个固定 SDK 的客户端代码。 这也是它能在多个 coding agent 之间复用的根本原因。

为什么技能不能自己完成渲染与导出

如果技能只是"不会画图",那给它加个渲染库就行了。真正的问题是三条硬约束,每一条都不是靠写更长的 SKILL.md 能绕过的。

约束一:模型的输出 token 是一堵墙

upload_to_stitch.py 的文档字符串把这件事写得毫不客气(upload_to_stitch.py):

WHY THIS SCRIPT EXISTS:
    The AI model cannot upload files via the MCP tool directly because MCP tool
    call arguments are part of the model's *output*. The model must re-emit the
    entire base64-encoded file as generated text, but its output token limit
    (~16K tokens) is far smaller than a typical file's base64 encoding (e.g.
    a 53KB PNG becomes ~71K chars of base64). The output gets truncated
    mid-string, producing a corrupted payload that the API rejects.

这段话的技术含量在于它点破了一个常被忽略的事实:MCP 工具调用的参数是模型生成的文本。你让模型"上传这张图",它就得把图片的 base64 一个字符一个字符地吐出来。一个 53KB 的 PNG 编码后约 7.1 万字符,而模型的输出上限约 1.6 万 token,于是字符串在中途被截断,服务端收到一个残缺的 payload,报错。

解决方案不是"让模型更努力",而是换一条通路:脚本在本地进程里读文件、在进程内做 base64、直接用 urllib 发 HTTPS 请求,全程不经过模型的输出通道。

url = f"{api_url.rstrip('/')}/v1/projects/{project_id}/screens:batchCreate"
payload = {
    "parent": f"projects/{project_id}",
    "requests": requests,
    "createScreenInstances": create_screen_instances,
}

这里有三个层次值得区分:技能(文本策略)→ 脚本(本地进程)→ 服务端(真正的 API)。脚本之所以存在,是因为它借用了本地进程这个"不属于模型"的执行环境,把大块二进制搬运从"生成"降级为"执行"。这是设计类智能体必备的一个逃生舱口。

约束二:渲染需要浏览器,而浏览器不在 Markdown 里

extract-static-html 技能做的事情更能说明问题。它要把一个跑起来的 Web 应用压成单文件 HTML,为此提供两条策略,推荐的那条直接上 Puppeteer(extract-static-html/SKILL.md):

npx tsx <SKILL_DIR>/scripts/snapshot.ts \
  --url http://localhost:5173 \
  --output .stitch/home.html \
  --wait 2000

打开 snapshot.ts 看它到底做了什么,就会发现这活儿跟"文本生成"没有半点关系:

  • 抓 CSSOM 而不只是抓 <style> 标签。脚本遍历 document.styleSheets,把所有规则"实体化"回 DOM,再剔除含 createHotContext、import.meta.hot 的 Vite HMR 样式块。原因很实在:Vite dev server 和 CSS-in-JS 的样式大量存在于运行时 CSSOM 里,光读 HTML 源码拿不到。
  • 内联 srcset 与 @font-face。图标字体如果没被内联,快照里就会退化成一串 ASCII 乱码;/_next/image 这类优化图源必须从还在运行的 dev server 上取,服务器一停就全是裂图。
  • 处理 <canvas>。传 --inline-canvas 时,ECharts / Chart.js / D3 的画布会被序列化成 base64 <img>,否则图表在静态文件里就是一个空白方块。
  • 处理鉴权与交互。--auth-script 允许你注入一个 async (page) => void 函数,登录完之后重新导航回目标 URL;--click 甚至会递归进 iframe 里找选择器,点完再等 2 秒让动画收敛。

(对应实现见 snapshot.ts 中 authScript 分支的 re-navigate 逻辑,与 --click 的 page.frames() 遍历。)

这些东西没有任何一项能用"更好的提示词"替代。它需要在目标机器上有一个真实的 Chromium、有一个能访问的 http://localhost:5173、有足够的时间等 networkidle2。技能可以描述"该怎么抓",但它无法"抓"本身——这是执行环境与语言模型之间的物理隔离。

同理,那条为"应用跑不起来"准备的兜底路径 extract_inline_html.ts,也是用 @babel/parser 解析 JSX AST 再重新渲染成 HTML,而不是让模型"看懂 JSX 然后手写 HTML"。用 AST 是因为正则解析 JSX 太脆;文件头注释直接写了 "instead of fragile regex"。工程判断被固化进代码,而不是每次靠模型即兴发挥。

约束三:设计系统是服务端状态,不是本地文件

第三个约束最容易被低估。generate-design 里有一条措辞严厉的禁令:

No theme leakage: Never put hex codes, font names, or color roles in a generation prompt — the design system handles all visual styling.

为什么?因为设计令牌被绑定在项目级别。manage-design-system 写得明白:

Once the upload script and create_design_system_from_design_md have both completed, Stitch holds the design tokens at the project level — you do NOT need to repeat them in generation prompts.

而创建这套令牌需要两步、两个 ID:先用脚本把 DESIGN.md 传上去拿到 sourceScreen 与 screenInstance 的 id,再调 create_design_system_from_design_md;应用时还要 list_design_systems 拿到 assets/{assetId},把 assetId 和一组 {"id", "sourceScreen"} 传给 apply_design_system。schema 里甚至有这种级别的坑(tool-schema.md):

selectedScreenInstances must contain only id and sourceScreen — do NOT include position/dimension fields (x, y, width, height) or the request will fail with "invalid argument".

以及:

Omit the legacy font field when updating the design system to avoid "invalid argument" errors.

这些约束说明,令牌的解析、继承、覆盖都发生在服务端。本地的 .stitch/metadata.json 是什么?看 stitch-loop 技能里给出的 schema 就懂了:它是 get_project 结果的镜像与缓存,用来在下一轮迭代里省掉一次查询、以及记住 canvas 坐标和屏幕尺寸。它记录状态,但不拥有状态。

有状态的系统无法被一个纯文本文件承载。 这条判断可以推广到几乎所有设计类智能体:只要涉及"这套设计系统作用于哪些屏幕""这个变体基于哪个基线",就一定需要服务端的资源模型,技能只能保存一份可能过期的本地视图。

顺带一提,一旦技能开始做网络 I/O,它就要继承安全义务。extract_inline_html.ts 里专门写了 isSafeUrl(),逐段屏蔽 127/8、10/8、172.16/12、192.168/16、169.254/16 和 localhost,注释直白地说 "URLs parsed from HTML files could be attacker-controlled"——因为抓取目标来自 HTML 里的 src,可能是攻击者可控的,不设防就成了 SSRF。当你把"渲染与抓取"交给脚本,你也把一整套 Web 安全责任一并接过来了。 而 upload-to-stitch 里那个必须停下来等用户确认的 checkpoint,也是同一个逻辑:凡是有外部副作用的动作,都不能由模型单方面决定。

三层职责:谁决定、谁搬运、谁生成

把上面的证据收拢,会得到一个相当清晰的分工表。这张表比任何架构图都实用,因为它同时给出了"某一层挂掉时你会看到什么症状"。

层 载体 职责 失效时的典型症状
策略层(脑) SKILL.md + references/ 判断模式(生成/编辑/变体)、增强提示词、决定调用顺序、设置确认点 结果"能用但不对味",风格漂移,反复重生成
执行层(手) scripts/ 里的 .ts / .py 大文件搬运、浏览器渲染、AST 转换、HTTP 直连 base64 截断、图片裂开、图标变乱码、证书报错
桥接层(桥) Stitch MCP Server + 各宿主配置 身份(API Key)、工具发现(list_tools)、schema 校验、资源寻址 工具名找不到前缀、invalid argument、401
服务层(脑外之脑) Stitch 平台 真正的生成、设计系统状态、变体计算、资源存储与 CDN 分发 生成质量差、令牌不生效、下载 URL 取不到

这张表解释了一个常见的困惑:为什么 code-to-design 这个技能本身几乎没有技术细节?因为它是一个编排器。它的 SKILL.md 第一句就是 "This skill orchestrates three other skills in sequence":

  1. extract-static-html —— 从 dev server 或构建产物里抓自包含 HTML;
  2. extract-design-md —— 分析源码(含 angular.json、外部模板、主题文件)产出 DESIGN.md;
  3. manage-design-system + upload-to-stitch —— 上传设计系统与 HTML,并把 --title 设成路由路径(/dashboard、/settings/profile),让 Stitch 里的屏幕名直接对应应用路由。

四步里没有一步是"模型自己想出来的像素",但每一步的顺序错了都会导致下游失败——先传 HTML 再传设计系统,create_design_system_from_design_md 就拿不到 sourceScreen;不传 --title,你会在 Stitch 里收获一堆叫 "Screen 1" 的屏幕。编排的价值恰恰在于它不干活,但它决定了活能不能干成。

前置依赖对团队落地成本的三个具体影响

README.md 里那句 "These skills require the Stitch MCP server to be configured and running" 看起来只是一行提示,落到团队层面却是三笔实打实的账单。

影响一:凭据分散在宿主的配置文件里,没有单一入口

技能不是自己去认证的,它要"翻"宿主的 MCP 配置来拿 X-Goog-Api-Key。这意味着三件事同时成立:每个开发者的机器上密钥位置不同(Antigravity 在 .gemini/,Claude Code 在 ~/.claude.json);密钥以明文散落在多个 JSON 里;CI 环境里没有"某个人已经配好了"这个前提。

技能对此的处理方式是强行中断:

If you cannot find the API key in any of these locations, or if you cannot access these files, you MUST ask the user to provide the Stitch API key. Do not proceed without a valid API key.

从工程角度看这是正确设计(不猜、不硬编码、不静默失败),但代价是任何一次自动化都必须显式注入凭据。再加上仓库在 SECURITY.md 里明确"这不是官方支持的 Google 产品,也不在漏洞奖励计划范围内",安全评审时你很难把它当作一个可以放心托管生产凭据的基础设施。团队真正要做的不是"教大家装插件",而是先决定:密钥由谁签发、放在哪里、CI 用哪一个、轮换周期多长。

影响二:运行时栈比想象中厚,且每一层都可能单独坏掉

按技能实际需要清点一下依赖:

  • Python 3 + 证书链。上传脚本 import certifi 并 ssl.create_default_context(cafile=certifi.where());没装 certifi 时 _SSL_CONTEXT 为 None。SKILL.md 为此专门写了一段 macOS 排障,教你把 SSL_CERT_FILE 指向 certifi 的 CA bundle,否则就是那句经典的 [SSL: CERTIFICATE_VERIFY_FAILED] unable to get local issuer certificate。
  • Node + npx tsx + Puppeteer。快照脚本头部就是 #!/usr/bin/env npx tsx,Puppeteer 缺失时的报错和处理方式也写进了 troubleshooting 表:Cannot find module 'puppeteer' → npm install -g puppeteer。
  • 一个能跑起来的本地 dev server。--url http://localhost:5173 不是示例,是硬前提。Next.js 要 --wait 3000 等 SSR hydration,Angular 默认 http://localhost:4200 且要 --wait 2000 等 Material/PrimeNG 的动画水合,Storybook 得用 http://localhost:6006/?path=/story/...。这些数字不是玄学,是每个框架渲染时序的差异。
  • 宿主侧的安装作用域。Claude Code 是 --scope project,Cursor 是 --scope workspace;OpenCode 干脆不支持 npx plugins,得手工把技能目录 cp -R 到 .opencode/skills 再自己写 opencode.json 的 remote MCP 条目。

把这几项加起来,你就会明白为什么"在 CI 里跑一遍"通常比"在本机跑通"难一个量级:CI 镜像里需要 Chromium、需要证书、需要一个能被快照脚本访问的服务端口。这不是配置问题,是环境形态问题——设计类智能体的执行层天生依赖"一台能渲染的机器"。

影响三:跨智能体兼容性要交"命名税"和"契约税"

Agent Skills 开放标准的卖点是"一套技能,多个宿主"。但 README 里那段 OpenCode 说明暴露了标准落地的缝隙:

OpenCode requires skill name frontmatter to be lowercase kebab-case and match the directory name. Skills that use stitch::… names (or other non-kebab forms) need the name field and folder renamed before OpenCode will load them. Extra frontmatter such as allowed-tools is ignored.

本仓库的 stitch-design 插件里,技能名全部是 stitch::generate-design、stitch::upload-to-stitch 这种带命名空间的写法。换到 OpenCode,你得同时改 frontmatter 和目录名,而且 allowed-tools 直接失效——权限声明这一层保护被静默丢弃,这可不是纯粹的格式问题。工具名也要映射:web_fetch 变 webfetch,run_command 变 bash。

第二笔是"契约税"。服务端的 schema 会漂移,而且漂移得相当细:update_design_system 要省略遗留的 font 字段否则 invalid argument;apply_design_system 的 selectedScreenInstances 多带一个 x 就整单失败;--generated-by 只对 HTML/Markdown 生效,图片上传会被忽略并打一行 warning。这些细节全被写进 SKILL.md 和 reference/tool-schema.md,本质上是在用文档给服务端契约做补丁。

结论很直接:技能库必须跟服务端版本一起被版本化。你不能"装一次用三年",也不能假设不同宿主加载的是同一份语义。团队应该锁定 commit、在升级时跑一遍真实链路(生成 → 编辑 → 变体 → 上传),而不是等用户在 invalid argument 面前猜。

情报里说的"15 个技能",和仓库里的 11 个

社区里流传的说法是"三大插件、15 个技能":stitch-design(6 个)、stitch-build(5 个)、stitch-utilities(4 个)。但打开这份代码,plugins/ 下只有两个目录:stitch-design 与 stitch-utilities;stitch-design 有 6 个技能目录,stitch-utilities 有 5 个(design-md、enhance-prompt、site-md、stitch-loop、taste-design),合计 11 个。

更值得注意的是 README.md 自身也在描述 stitch-build(含 react-components、react-native、react-vite-dashboard、remotion、shadcn-ui),甚至给了安装时的 --sparse plugins/stitch-build——但目录不存在。另外 README 的目录结构章节写的是 resources/,实际技能里放知识库的目录名是 references/。

这不是要挑刺,而是给读者的一个方法论提醒:设计类智能体的信息熵很高,必须以 frontmatter 和 plugin.json 为准。判断一个技能是否存在,看 plugins/*/skills/*/SKILL.md 的 name 字段;判断插件边界,看 plugin.json 里的 name 与 keywords。二手文章(包括把 Stitch 误当成"浏览器 CommonJS 打包工具"的那类张冠李戴)会造成非常具体的误判——比如你按"15 个技能"去规划依赖,结果发现 react-components 根本不在这一版里。

给团队的落地清单

把上面所有约束压缩成可执行的动作,大致是这几条:

  1. 先验桥,再谈技能。用一个最小调用(list_projects)确认 MCP 前缀、API Key、网络可达。桥不通,后面所有 SKILL.md 都是散文。
  2. 把"文本策略"和"进程执行"分开评审。SKILL.md 改起来风险低,scripts/*.py、scripts/*.ts 改起来风险高——它们会读本地文件、发外网请求、启动浏览器。后者应当走代码评审与安全扫描。
  3. 给大文件搬运固定一条脚本通道。不要指望模型通过 MCP 参数上传 base64;一旦文件超过几十 KB,必然截断。这条经验可以直接复用到任何"智能体 + 二进制资源"的场景。
  4. 把确认点当成产品能力,不是阻碍。上传前的文件清单确认、快照前的服务地址确认、设计系统创建前的令牌摘要确认——这些 checkpoint 是让你敢于在真实项目里开自动化的前提。
  5. 单一事实来源放在服务端,本地只做镜像。.stitch/metadata.json 可以加速,但不能被信任为权威;关键写操作前用 get_project 复核 ID。
  6. 按服务端版本锁技能版本。schema 的坑(font 字段、selectedScreenInstances 的字段白名单)不会自己消失,升级时用一条端到端链路验证,而不是只看 diff。

回到标题。为什么设计类智能体绕不开一层服务器?因为设计的产物是有状态的、二进制的、需要真实渲染环境才能验证的东西。技能可以教会智能体"什么时候该生成、prompt 该怎么写、错了该怎么改",但它永远无法替服务器完成"生成"这个动作本身——它连一张 53KB 的 PNG 都搬不动。桥接层做桥,技能做脑,服务器做那只真正握着画笔的手。认清这个分工,你才不会在错误的层上做优化。

登录后查看全文
stitch-skills