flyu

本地设计文件客户端:把 Sketch / Figma 设计文件解析为统一 DSL v3,通过内嵌 MCP(HTTP,随 app 启动)暴露给 Cursor / Claude,让 AI 直接看设计稿、写代码、改稿、导出切图。

演示

https://github.com/user-attachments/assets/51cc93c6-8413-4c3b-8bfd-7fd135e26a3c

许可:MIT。第三方声明见 NOTICE.md。安全披露见 SECURITY.md。贡献见 CONTRIBUTING.md。

Sketch / Figma 的文件格式与商标归其权利人所有。本项目在用户本机解析你导入的 .sketch / .fig,不附带厂商授权,也不声称与 Figma, Inc. 或 Sketch B.V. 有关联。请遵守其服务条款,只导入你有权使用的设计文件。.fig 解码实现见 crates/fig-kiwi-rs。

用户向文档见 docs/user-guide.md(安装 / 功能 / 话术 / 排查);MCP 工具细节见 docs/write-tools-guide.md。

开发

pnpm install        # 安装依赖(postinstall 会把 better-sqlite3 编到 Electron ABI)
pnpm dev            # 启动 Electron + HMR
pnpm typecheck      # 类型检查(main + renderer + mcp + tests)
pnpm lint           # ESLint
pnpm test           # 单元 + 契约测试(tsx --test)
pnpm test:visual    # 渲染像素回归(改 import/render 后必跑)
pnpm build          # 构建到 out/(含 main/preload/renderer/mcp)
pnpm dist           # 打本机未签名 mac 双架构(arm64 + x64).dmg → release/

打包(macOS 本机未签名)

pnpm dist           # build + electron-builder → release/flyu-*-mac-arm64.dmg + flyu-*-mac-x64.dmg
pnpm dist:dir       # 只打 arm64 .app 到 release/mac-arm64/(便于调试)

双架构:electron-builder 按目标架构分别打包;better-sqlite3 为每个架构各自重编(arm64 主机上交叉编 x64 已验证可用)。

产物为未签名包(identity: null),安装后应用名为「非鱼」。本机打开若被 Gatekeeper 拦截:右键 → 打开。勿与正在跑的 pnpm dev 同时启动(单例锁会让第二个进程立刻退出)。

MCP Server

两种接入,同一份 tools/prompts(29 个 Tool + 4 个 Prompt):

• HTTP(推荐):客户端内嵌 Streamable HTTP,随 app 启动。设置 → MCP 使用配置 → 复制(URL + Bearer token)。端口默认 32677 并持久化,被占用才顺延;token 持久化于 userData/mcp-token(0600),可重新生成。
• stdio(备选,需本机 Node):node out/mcp/server.js。要求 DB 已存在(客户端至少跑过一次)。

构建 stdio 入口

pnpm mcp:build      # esbuild 打包到 out/mcp/server.js
pnpm mcp:dev        # tsx 直跑(调试用)

验证(JSON-RPC 手工测)

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | pnpm mcp:dev

应返回 serverInfo: { name: "flyu-design", version: "1.0.0" }。

macOS 本地开发陷阱(双 ABI + 代码签名)

1. ABI 切换:better-sqlite3 同一时刻只能为一个 runtime 编译。
   • Electron 用:pnpm rebuild(走 electron-rebuild)
   • 直跑 Node(MCP 调试 / tsx 测试):cd node_modules/.pnpm/better-sqlite3@*/node_modules/better-sqlite3 && ./node_modules/.bin/prebuild-install -r node
   • 症状:跑错了 runtime 会报 NODE_MODULE_VERSION 130 vs 127 之类。
2. 代码签名:从 npm 拉的 prebuilt .node 在 macOS 26+ 上会被 AMFI 以 Invalid Page 杀掉(SIGKILL,exit 137,stderr 空)。修法:

   codesign --remove-signature node_modules/.pnpm/better-sqlite3@*/node_modules/better-sqlite3/build/Release/better_sqlite3.node
   codesign --force --sign -       node_modules/.pnpm/better-sqlite3@*/node_modules/better-sqlite3/build/Release/better_sqlite3.node
   

   每次 prebuild-install 后都要重做。后续打包时用 electron-builder 的 afterSign 钩子自动化。

目录

src/
├── main/           Electron 主进程(DB / IPC / 渲染 / 导入导出)
│   ├── import/     双通道导入:sketch-*(.sketch)/ fig-*(.fig 本地,@open-pencil/core)
│   │               + html-to-dsl(HTML 生成)、collect-tokens(共享令牌统计)
│   ├── render/     渲染调度(fig 走 Skia 直渲;sketch 走 DSL→HTML→Chromium)
│   ├── export/     dsl-to-jsx / dsl-to-fig / vector-to-svg / code-snippets / cut-cache
│   ├── tokens/     设计令牌(L1 命名令牌 / L3 组件令牌 / tokenize)
│   ├── db/         SQLite(writers / write-ops / write-docs / restyle / migrations)
│   └── ipc/        渲染进程桥(files / folders / explorer / mcp-config / library)
├── preload/        contextBridge 桥
├── renderer/       React + AntD UI
├── mcp/            MCP Server:server.ts(stdio)+ tools.ts(聚合器)+ tools-*.ts(8 个域模块)
├── shared/         三端共享(DSL v3 类型 / IPC 通道 / 错误码 / 路径)
└── native/         fig-kiwi WASM(由 crates/ 编译)

crates/             Rust 原生(.fig Kiwi 解码)
resources/          打包图标 icon.png / icon.icns
docs/               用户教程 / 写能力设计与工具文档
scripts/            正式脚本(icons / wasm / 视觉回归)
tests/              单元与契约测试

本地运行时数据在用户目录(~/Library/Application Support/flyu)与可选的 .tokensave/(已 gitignore),构建产物在 out/。

当前状态

• [x] 双通道导入:.sketch / .fig 本地(@open-pencil/core)
• [x] 统一 DSL v3 + SQLite 落库 + 版本组
• [x] 渲染:fig Skia 直渲;sketch/ai DSL→HTML→Chromium;degraded 显式上报
• [x] MCP 29 Tool + 4 Prompt(导航/数据/视觉/代码/切图/写操作/语义修改)
• [x] 写能力:事务化 apply_operations / restyle_*(dryRun)/ create_from_html / fork_document / rollback
• [x] 导出:get_html(自包含单文件)/ get_code(JSX+Tailwind,vw/rem/tokenize)/ export_fig(.fig 非官方互通)/ download_assets(SVG/PNG/原图)
• [x] 设计令牌:L1 命名令牌(fig variables/sketch 样式,css/dtcg 导出)+ L3 组件令牌覆盖走查
• [ ] Windows / Linux 安装包(配置已有,未发布)