text-to-design 后台服务

让 AI 助手直接帮你操作即时设计(jsDesign)画布:读取选中内容、按描述画图、改样式、导出图片。装好后不用手动启动任何东西,打开 AI 工具就能用。

这里说的「后台服务」,就是负责在 AI 和设计软件插件之间传话的那个小帮手。

能做什么

• 读取画布当前选中的内容
• 按你的描述画图:卡片、按钮、文字、形状等
• 修改已有内容:改位置、颜色、文字、圆角
• 把多个元素合成一个图形、给图形加轮廓
• 把图形变成可反复复用的组件
• 导出图片(PNG / JPG / SVG / PDF)
• 用本地图片填充图形

安装(三步)

第一步:告诉 AI 工具

后台服务不用手动安装,注册命令统一为 npx -y text-to-design-mcp@latest,任意 AI 工具都会自动化拉取运行。把下面需求丢给 AI,它会自动注册并验证:

请帮我完成 text-to-design 安装,并按步骤汇报进度:

1. 注册 MCP 服务:用你工具原生的方式注册一个 stdio MCP server,
   命令 npx -y text-to-design-mcp@latest(无需手动安装,npx 会自动拉取运行)。

2. 验证后台服务能启动:
   timeout 5 npx -y text-to-design-mcp@latest
   预期输出含 "[text-to-design-mcp] shim 模式" 或 "daemon 就绪"(首次会自动拉起常驻服务)。

3. 安装设计软件插件,下载并解压到用户目录:
   cd ~ && npm pack text-to-design-ui
   mkdir -p text-to-design-plugin
   tar -xzf text-to-design-ui-*.tgz -C text-to-design-plugin --strip-components=1

4. 上述三步完成后,告知用户剩下两步需手动:
   - 在即时设计里「插件 → 导入」,选择 ~/text-to-design-plugin/dist/manifest.json,
     运行插件,面板显示「已连接」即就绪
   - 重启 AI 会话,调用 jsd_ping 验证连通

5. 汇报完成情况。

若希望全局安装(装一次、不依赖联网拉取),可 npm i -g text-to-design-mcp,注册命令可简化为 text-to-design-mcp。

第二步:安装设计软件插件

先拿到插件包(任选):

| 管理器 | 命令 | | --- | --- | | npm | npm pack text-to-design-ui | | pnpm | pnpm pack text-to-design-ui | | yarn | yarn dlx npm pack text-to-design-ui |

解压得到的安装包里有个 dist 文件夹。在即时设计里点「插件 → 导入」,选择里面的 manifest.json,然后回到画布运行插件。面板显示「已连接」就是准备好了。

第三步:重启 AI 工具

改完重启 AI 工具会话(首次使用会自动拉取后台服务并常驻运行)。

怎么用

打开会话后直接说人话,比如:

• 「读取当前画布选中的内容」
• 「在画布中心画一个 300x200 的卡片,标题叫发布页,背景浅灰」
• 「把选中的按钮导出成 PNG 存到 /tmp/btn.png」

想确认插件通不通,先让它调 jsd_ping。

常见问题

• AI 说连不上插件:看即时设计里的插件面板是不是「已连接」,没有就重新运行插件,再重启 AI 会话
• AI 说某工具/某字段「平台不支持」:当前插件平台没有这项能力。面板可折叠的「能力」区块、jsd_ping 回包、jsd://platform/state 三处看到的是同一份能力表(即时设计侧只有本地样式;变量 / 组件属性 / 文本截断是 Figma 侧才有的差异能力)
• 改了配置没反应:重启 AI 工具会话
• 想深入排查:看文末「给开发者看」的日志部分
• 旧版升级见下方「升级」

升级

新版起会自动替换:启动时若检测到旧版常驻服务,会自动关停并拉起新版,无需手动操作。

仅从旧版(没有自动替换能力)升级时,首次需手动清理一次残留的常驻服务:

pkill -f text-to-design-mcp

之后任意一次 AI 调用会自动拉起新版服务。

给开发者看

以下内容供开发、排查问题的人参考。

完整工具清单

一个操作对应一个工具,没有 op 分发;两个聚合入口(jsd_manage_nodes / jsd_manage_components)仅用于批量或一次改多组字段。所有写工具都支持 ids(缺省作用于当前选中);属性类工具(及 jsd_set_*)的 recursive 只作用于后代,不含目标节点自身(给一组图标容器刷色时容器不会被套上方框),要连容器自身一起改才传 includeSelf=true。

| 工具 | 用途 | | --- | --- | | jsd_ping | 检查插件是否在线,返回三张能力表(核心能力 / 平台差异能力 / 平台特有 op 名单);回包被 daemon 缓存,后续可读 jsd://platform/state | | jsd_get_selection | 读取画布当前选中的节点 | | jsd_find | 按名称/类型/id 查找节点 | | jsd_create_nodes | 按描述创建节点(frame/rect/text 等,支持阴影/描边/渐变/文本样式) | | jsd_create_svg | 直接导入 SVG 字符串(保留 path/矢量数据,不经降级) | | jsd_create_icon | 按名称/别名模糊匹配插入 Lucide 内置图标,查无时返回候选名 | | jsd_html_to_design | 把 HTML 转成设计节点 | | jsd_set_fill_color | 填充(fills 整体替换)、混合模式、填充样式 | | jsd_set_stroke | 描边列表/宽度(可四边分开)/对齐/端点/连接/虚线/描边样式 | | jsd_set_cornerRadius | 圆角半径(四角可分开)与圆角平滑度 | | jsd_set_text | 文本内容与排版(characters/fontSize/fontName/对齐/行高/字距/截断) | | jsd_move_node | 位置 x/y 与旋转 | | jsd_resize_node | 尺寸 width/height,可同时传 x/y 一步改尺寸并定位 | | jsd_set_layout | FRAME auto-layout(layoutMode/间距/内边距/对齐/伸缩/约束) | | jsd_set_effects | 阴影/模糊、溢出裁剪、布局网格、椭圆环形参数 | | jsd_set_visibility | 不透明度、显示开关、锁定 | | jsd_rename_node | 重命名 | | jsd_update_node | 聚合:一次改多组字段,或改 pointCount/innerRadius 等长尾字段 | | jsd_select_nodes | 设置画布当前选中 | | jsd_delete_node | 删除节点(matchName 可再过滤;ids 缺省删当前选中) | | jsd_clone_node | 复制节点(克隆 COMPONENT 得到 INSTANCE) | | jsd_group_nodes | 编组(至少 2 个),可同时设置 auto-layout | | jsd_ungroup_nodes | 解组 | | jsd_flatten_nodes | 至少 2 个节点合并为单一矢量 | | jsd_outline_stroke | 描边转轮廓矢量(几何被烘焙) | | jsd_reparent_nodes | 移入父节点成为其子节点(parentId 建议显式传;跨父级移动保持绝对位置,内部自动换算,移入 auto-layout 容器时位置由布局接管) | | jsd_repair_nodes | 清理引擎残留的损坏/失效节点 | | jsd_manage_nodes | 聚合入口,op 含 select/remove/clone/group/ungroup/flatten/outline_stroke/reparent/repair;各 op 返回键不同(select→selected / remove→removed / ungroup→ungrouped / repair→cleaned 为 id 字符串数组;clone/outline_stroke→created 节点数组,group/flatten→created 节点单对象;reparent→moved,同时附同义的 updated)。结构变更类 op 与固定 op 小工具一样会做同层几何漂移复核 | | jsd_create_component | 建「空壳」组件:先 resize 再 reparent 归入子节点,最后删除原容器 | | jsd_create_instance | 按 COMPONENT 生成实例 | | jsd_detach_instance | 取消实例链接,得到可自由编辑的普通节点 | | jsd_import_component | 按 key 从团队库导入组件 | | jsd_swap_component | 换绑组件(丢弃目标既有覆盖) | | jsd_set_instance_properties | 设置变体属性(属性名需与 variantGroupProperties 完全匹配) | | jsd_combine_as_variants | 合并为变体集(仅 COMPONENT,实例不能直接合成)。⚠ 本引擎必然失败(平台缺陷),全败时返回可执行出口:改用「族名 / 状态」命名的多个独立主件 | | jsd_copy_overrides | 复制源实例覆盖为快照,返回 snapshotId(缓存) | | jsd_apply_overrides | 按 snapshotId 批量套用,可 swapToSource | | jsd_sync_overrides | 无状态一次性「复制+套用」,适合 jsd_batch | | jsd_manage_components | 聚合入口,op 含 create_component/create_instance/detach_instance/import_component/swap_component/set_instance_properties/combine_as_variants/copy_overrides/apply_overrides/sync_overrides | | jsd_batch | 批量编排器:一次请求顺序执行多个 jsd_* 步骤,双花括号占位符串起中间值;步骤回显做摘要裁剪(节点只留 id/name/type/x/y,丢 vectorPaths 等大字段,超预算降级为 id 清单),占位符解析用完整数据;含图标的批次另配一次 jsd_export 目视验收;含删除/移父的步骤自动复核同层几何漂移(结果 warnings,checkDrift:false 可关;单工具调用同样会复核) | | jsd_export | 导出节点为 PNG/JPG/SVG/PDF(导出失败的 id 在文本里点名) | | jsd_list_fonts | 列出可用字体:families 与各族的可用字型 fonts:[{family,styles}](写 fontName 前照这份取组合,family+style 需精确匹配,猜错会静默退回默认字重) | | jsd_fill_image | 用本地图片填充节点 | | jsd_platform_op | 平台特有能力的通用通道(Figma 变量/本地样式/组件属性定义与设值)。先读 jsd_ping 的 platformOps 名单再传 op 名;插件平台不适用(如即时设计)时由 daemon 直接拦截并给出替代路径,不发插件往返 |

配方 prompt(prompts/list)

带参数的操作引导词,让 AI 少猜流程细节;策略类以 assistant 身份下发,配方式以 user 身份下发。

| prompt | 用途 | | --- | --- | | design-strategy | 设计策略总纲:命名/层级/间距字号阶梯/出错回滚,附登录页示例结构树 | | text-replace-strategy | 大改文案:jsd_clone_node 留底 → 语义分块 → jsd_set_text 批量替换 → 逐块导小图复核 | | variant-sync | 把一个实例的样式/文案批量套用到多个同类实例(优先 jsd_sync_overrides / copy+apply,手工 jsd_set_* 兜底) | | html-to-design | HTML 转设计稿,含保真度取舍说明 | | icon-grid | 批量插入 Lucide 图标并排成自动布局网格 | | script-ops | 脚本化调用纪律:压缩工具往返与上下文占用 |

只读资源(resources/list)

按需读取画布与平台状态,模型可直接作为上下文。资源目录恒定列出,不随连接门控隐藏: 插件离线时调用会快速失败并返回「插件未连接」的明确提示,而不是把整张目录藏起来 (隐藏式门控依赖客户端处理 listChanged,多数客户端不处理,会话若在插件离线时建立就会永久看不到资源)。

| resource | 内容 | | --- | --- | | jsd://canvas/selection | 当前选中的序列化树(等价 jsd_get_selection depth=2) | | jsd://fonts | 当前环境可用字体:families 与各族的可用字型 fonts:[{family,styles}] | | jsd://styles | 当前文档可复用本地样式(PAINT/TEXT/EFFECT/GRID,按名应用样式前先读这里) | | jsd://page | 当前页顶层节点轻量摘要(名称/类型/位置/尺寸/子节点数,从头设计整页前先读) | | jsd://node/{id} | 按 id 读节点序列化结构 | | jsd://platform/state | 插件平台状态与能力表(platform / capabilities / coreCapabilities / platformOps)。读 daemon 本地缓存,不发插件请求;插件上线时 daemon 自动探测一次,断开即清空,未探测时为空 |

工作原理(简版)

• 一个常驻的轻量服务负责和插件通信,连接即时设计里的插件
• 每个 AI 会话会自动连上这个服务;会话关掉不影响插件
• 服务常驻;更新版本时自动替换,无需手动清理(旧版首次升级除外,见「升级」)
• 多个会话可以同时用,共享同一个插件连接

环境变量

| 变量 | 默认 | 说明 | | --- | --- | --- | | TEXT_TO_DESIGN_MCP_PORT | 47812 | 与插件通信的端口(被占用会启动失败) | | TEXT_TO_DESIGN_MCP_HTTP_PORT | 47820 | 内部服务端口(一般不用动) | | TEXT_TO_DESIGN_MCP_LOG | /tmp/text-to-design-mcp.log | 日志文件路径 | | TEXT_TO_DESIGN_MCP_LOG_LEVEL | info | 落盘级别:debug/info/warn/error;只约束日志文件,面板推送全量下发 |

日志排查

• 看日志:tail -f /tmp/text-to-design-mcp.log(请求/响应耗时、HTTP 状态码、插件连接、二进制组装都会记)
• 要更细的连接日志,启动时设 TEXT_TO_DESIGN_MCP_LOG_LEVEL=debug(默认 info);该开关只减落盘量,面板推送不受限制
• 插件面板自带连接状态和日志:服务端日志实时推送,档位默认隐藏 debug,切「全部」可见帧级明细;插件离线期间的日志会先缓冲,上线后按顺序回放
• 面板还有可折叠的「能力」区块:核心能力(两平台一致)、当前平台可用的差异能力、平台特有 op 名单 —— 数据与 MCP 侧 capabilities / platformOps 同源

构建与开发

pnpm install
pnpm dev        # watch 构建 ui/code
pnpm mcp        # 开发态启动后台服务(tsx 直跑)