开始使用 · 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 客户端	服务器的 `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	在会话中运行 `/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 更新。

重启宿主或开启新会话，确认已列出 figlens tools。Plugin 安装会复制仓库：约 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 客户端：

{
  "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 启动参数

将以下选项放在客户端的 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

也可以从这个仓库或 release 归档中把 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，并用你的技术栈构建画面。共享工作流会指导字体与素材检查；缺失项会被报告，布局实现仍使用已记录的替代方案继续。请让它展示修改的文件与浏览器对比结果。