開始使用 · figlens 文件

還沒有設計檔？ 用小型公開範例檢查環境：驗證所選執行檔、找到一個 frame，再核對 bundle 內容。不需要模型。

把 design.fig 放進你的專案，再從下面擇一設定。每種方式都會讓 agent 取得 figlens 工具，以及同一套內建的規劃、實作與圖片處理指引。

方式	適用對象	指引來源
Plugin	Claude Code, Codex, Antigravity, Cursor, Kimi Code	plugin 內附的 skill 與 server 的 `workflow` tool
MCP	Claude Code、Cursor、Codex、Gemini CLI 等 MCP client	server 的 `workflow` tool
Pi	Pi 1.3.0+	套件內附的 skill
OpenCode V2	OpenCode V2 2.2.0	套件內附的 skill
OMP	OMP 18.13.2	套件內附的 skill
CLI	只會執行 shell 指令的 agent、腳本與 CI，或你自己	`figlens workflow <topic>`，或選用的 skill

一般與進階。 一般使用不需要任何設定：figlens search design.fig "query" 只讀取 .fig，不會建立任何東西。選用的本機索引只在你要求時建立（figlens index prepare design.fig --scope 0:0），之後跨重啟和宿主重複使用。請見一般搜尋與選用的本機索引。選用且屬實驗性功能：--mode semantic 或 hybrid 使用你自行設定的本機模型依語意排序，請見選用的語意搜尋。

Plugin

一次安裝就把 figlens skill 和 MCP server 加進 agent（需要 Node.js 18+）。Server 固定在 plugin 對應的版本（npx -y @runkids/figlens@<version> mcp）；要換新版本就更新 plugin。

宿主	安裝
Claude Code	`claude plugin marketplace add runkids/figlens`, `claude plugin install figlens@figlens`
Codex	`codex plugin marketplace add runkids/figlens`, `codex plugin add figlens@figlens`
Antigravity	`agy plugin install https://github.com/runkids/figlens/tree/main`
Cursor	`git clone --depth 1 https://github.com/runkids/figlens ~/.cursor/plugins/local/figlens`，再重新載入視窗
Kimi Code	在 session 中執行 `/plugins install https://github.com/runkids/figlens/tree/main`，再執行 `/reload`

skillshare 可一次把同一個 plugin 安裝到多個宿主：skillshare plugin add https://github.com/runkids/figlens.git --target claude --target codex --target cursor -g；之後用 skillshare plugin update figlens -g 更新。

重新啟動宿主或開新的 session，確認 figlens tools 已列出。Plugin 安裝會複製 repository：約 7 MB，Codex 另外保留 Git 歷史（約 60 MB）。Antigravity 只載入 skill 的前 24 KB；完整指引由 server 的 workflow tool 提供。目前還不支援 Muse。宿主對照表與驗證範圍

MCP

Claude Code（Node.js 18+、macOS/Linux）：

claude mcp add --transport stdio --scope local figlens -- npx -y @runkids/figlens mcp

Codex CLI（Node.js 18+、macOS/Linux）：

codex mcp add figlens -- npx -y @runkids/figlens mcp

任何 MCP client：

{
  "mcpServers": {
    "figlens": {
      "command": "npx",
      "args": ["-y", "@runkids/figlens", "mcp"]
    }
  }
}

沒有 Node.js 時，先安裝獨立執行檔（見 CLI），再改用 "command": "figlens", "args": ["mcp"]。開啟新的 session，確認看得到 figlens 工具（Claude Code 用 /mcp）。不必另外安裝 skill。在 mcp 後面加上 --root <dir>，可以限制 figlens 能讀寫的資料夾。

MCP 啟動參數

將以下選項放在 client 的 args 中、mcp 之後。MCP 啟動選項只有這兩個，皆為選填且可重複。

選項	用途
`--root DIR`	允許讀取 `DIR` 與子資料夾內的設計檔，以及寫出匯出檔案。未指定時，figlens 不加上路徑限制，仍受作業系統權限約束；不是預設限制在目前專案，也不會掃描整台電腦。
`--storage-root DIR`	允許在 `DIR` 與子資料夾內明確指定自訂索引儲存位置。它不會選擇或改變預設儲存位置。

請使用已存在目錄的絕對路徑。每個選項和路徑都是獨立的陣列項目；多個資料夾要重複寫選項。--root 是路徑邊界，不是管理員權限；只限制 figlens MCP，不限制 agent 的其他工具。

兩個設計／輸出範圍與兩個 storage 允許範圍的範例：

{
  "mcpServers": {
    "figlens": {
      "command": "npx",
      "args": [
        "-y", "@runkids/figlens", "mcp",
        "--root", "/absolute/designs",
        "--root", "/absolute/project",
        "--storage-root", "/absolute/storage-a",
        "--storage-root", "/absolute/storage-b"
      ]
    }
  }
}

沒有 figlens mcp --storage 這個選項。實際位置由 index tool 的 storage 參數指定（允許的 storage 範圍內的絕對路徑），或使用 CLI figlens index prepare design.fig --storage /absolute/storage-a。prepare 後會記住該 workspace 的位置，跨重啟、跨 host 重用，不必再傳 storage 或 --storage-root。未自訂位置時，使用每位使用者的預設目錄，不必設定 storage 旗標。

要避免在進 Git 的設定裡寫死這些路徑，或在多個 Git worktree 之間共用設計稿，請看進 Git 的設定中的 root。

多個 storage root 只會擴大允許範圍：每次 storage 仍只選一個位置，不會自動分流、同步或備份索引。既有 workspace 資料庫不能只靠改指定另一個 root 搬家；位置衝突時 figlens 會拒絕。

Pi

一個套件包含 CLI、MCP、viewer、/figlens 指令與 skill：

pi install npm:@runkids/figlens

Pi 擴充套件說明

OpenCode V2

在 OpenCode V2 安裝套件：

opencode plugin add @runkids/figlens

重新啟動 OpenCode，再執行 /figlens help。 OpenCode V2

OMP

在 OMP 安裝同一套件：

omp plugin install @runkids/figlens

重新啟動 OMP，再執行 /figlens help。 OMP

CLI

透過 npm 執行，或安裝獨立執行檔：

npx @runkids/figlens --help                                                                # Node.js 18+，免安裝
curl -fsSL https://raw.githubusercontent.com/runkids/figlens/main/scripts/install.sh | sh  # macOS、Linux
brew install runkids/tap/figlens                                                           # Homebrew
irm https://raw.githubusercontent.com/runkids/figlens/main/scripts/install.ps1 | iex      # Windows PowerShell

npx 會執行它解析到的套件版本所對應的執行檔。用安裝腳本裝的以 figlens update 更新；Homebrew 裝的以 brew upgrade figlens 更新。執行檔支援 macOS（Apple silicon、Intel）、Linux（arm64、x86_64）與 Windows（x86_64）。

使用 CLI 的 agent 可以執行 figlens workflow build 讀取指引（另有 audit、images、search、plan、planning-details 與需明確啟用的 yolo），內容永遠與執行檔版本一致；也可以改用 agent skill。

CLI 參考

Agent skill（選用）

skill 教 agent 的流程和內建指引相同：找到 frame、分段讀取 bundle、規劃範圍內的工作，再拿執行中的 UI 和設計比對。skill 只有說明，不含執行檔，要搭配 CLI 或 MCP 使用。用 MCP 或 Pi 則不需要另外安裝。

推薦：skillshare。 安裝一次 skill，就能同步到你用的每個 agent：

skillshare install github.com/runkids/figlens/skills/figlens
skillshare sync

同一個工具也能幫這些 agent 設定 figlens 的 MCP 連線：

skillshare mcp add figlens --global --target claude --target codex --target cursor --no-tui -- npx -y @runkids/figlens mcp
skillshare sync mcp --global

其他安裝 skill 的方式：

npx skills add runkids/figlens --skill figlens   # Skills CLI

也可以從這個 repo 或 release archive 把 skills/figlens/ 複製到 agent 的 skills 目錄（Claude Code：~/.claude/skills/）。另外安裝的 skill 和執行檔分開更新；figlens workflow 則一定和執行檔同版。

接著請它做一個畫面：

Build the task board from ./design.fig in this project.
Find the matching frame, use this project's components and image workflow,
then compare the running UI with the design and fix confirmed differences.
Report missing assets and any checks you could not run.

Agent 會找到 frame，將設計資料、素材與參考圖打包成 bundle，再用你的技術堆疊實作畫面。共用工作流程會引導字型與素材檢查；缺料會回報，切版仍使用已記錄的替代方案繼續。請它展示變更檔案與瀏覽器比對結果。