flyu

로컬 디자인 파일 클라이언트: Sketch / Figma 디자인 파일을 통합 DSL v3로 파싱하고, 내장 MCP(HTTP, 앱 시작 시 함께 실행)를 통해 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를 참조하세요.

Related MCP server: figma-opencode-mcp

개발

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로, 앱 시작 시 함께 실행됩니다. 설정 → 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/에 있습니다.

현재 상태

• 듀얼 채널 가져오기: .sketch / .fig 로컬(@open-pencil/core)

• 통합 DSL v3 + SQLite 저장 + 버전 그룹

• 렌더링: fig Skia 직접 렌더링; sketch/ai DSL→HTML→Chromium; degraded 명시적 보고

• MCP 29 Tool + 4 Prompt(탐색/데이터/시각/코드/이미지 내보내기/쓰기 작업/의미 기반 수정)

• 쓰기 기능: 트랜잭션 기반 apply_operations / restyle_*(dryRun)/ create_from_html / fork_document / rollback

• 내보내기: get_html(자체 포함 단일 파일)/ get_code(JSX+Tailwind, vw/rem/tokenize)/ export_fig(.fig 비공식 상호 운용)/ download_assets(SVG/PNG/원본 이미지)

• 디자인 토큰: L1 명명 토큰(fig variables/sketch 스타일, css/dtcg 내보내기) + L3 컴포넌트 토큰 오버라이 워크스루

• Windows / Linux 설치 패키지(구성은 있음, 미배포)