Figma 提案桥 Lancasteerr/figma_bridge_agent

Local Figma Agent MCP

让本地 Coding Agent 安全读取 Figma Design 文档，把设计证据与素材带入前端工程生成代码，并在隔离的 Proposal 副本中创建可审查的设计修改。

English · 中文文档 · 最新版本 · 报告问题 · 示例仓库

本地优先 · 源稿不可直接修改 · 无云端中继 · 无遥测

这是通过 GitHub 分发的非官方开发工具，与 Figma 不存在隶属或背书关系，也不会发布到 Figma Community。Figma 文件和桥接凭据只经过本机 loopback。

能做什么

| 能力 | 说明 |
| 设计稿生成代码 | 向 Agent 提供有界设计语义、素材和新鲜度证据，由 Agent 按目标工程规范实现 |
| 本地读取 | 读取当前文件、选区、节点树、素材事实、样式、变量、字体和 Inspect CSS |
| 实施工作单元 | 事实留在磁盘 JSONL，Workunit 只跟踪代码映射、状态和来源新鲜度 |
| 素材交付 | 提取原始图片或渲染节点，安全写入明确绑定的工作区 |
| 安全编辑 | 先复制目标和必要布局上下文，再仅在隔离 Proposal 内修改 |
| 声明式生成 | 验证完整 DesignPlan 后，原子创建新的 Proposal |
| 多客户端复用 | 多个本地 MCP Adapter 共用一个自动管理的 Bridge Daemon |

Bridge 本身不是特定框架的代码生成器。它为 Coding Agent 提供结构化设计证据、安全素材交付和来源新鲜度校验；Agent 再结合目标仓库的技术栈、组件库和工程约定编写代码。

MCP Server 静态注册 25 个受限工具。除 figma_status 外，工具按 figma_inspect_、figma_frontend_、figma_design_ 领域前缀命名，不存在动态激活步骤。完整列表和调用顺序见 MCP 工具参考。

界面预览

首次配对

插件未配对时会显示 PowerShell 命令；开始配对后，终端与插件分别显示需要人工核对的六位短码。

已连接状态

配对完成后，插件窗口会显示 Bridge 连接状态、当前文档和最近连接时间。

Agent 的修改会出现在 Figma 画布上的隔离 Proposal 中，便于与源设计并排审查。

快速开始

前置条件

- Windows
- Node.js 20 或更高版本
- Figma Desktop
- 支持本地 stdio MCP 或 Agent Plugins 1.0 的 Coding Agent

普通用户不需要 Git、pnpm 或源码仓库。请打开 GitHub 最新版本页面，记下不含 v 前缀的版本号，并用它替换下文中的 <VERSION>。Figma 插件 ZIP、MCP npm 包和 Agent Plugin 必须来自同一版本。

1. 选择一种安装方式

两种方式提供相同的静态工具和工作流能力，只需选择其中一种：

- 安装 Agent Plugin：适用于本项目当前已适配的 Codex、Cursor 和 GitHub Copilot；自动提供 MCP 配置，以及设计稿实现代码与安全 Proposal 工作流 Skill。请按插件安装指南操作。
- 直接配置 MCP Server：适用于 Claude Code、Claude Desktop及其他本地 stdio 主机；需要手工添加 MCP 配置，且不会自动安装 Skill。请按直接 MCP 安装指南操作。

不要同时安装 Agent Plugin 和手工注册同名 MCP Server，否则客户端可能加载重复工具。完整对比见选择安装方式。

2. 导入 Figma 插件

从 GitHub 最新版本页面 下载 figma-agent-bridge-plugin-v<VERSION>.zip，解压到稳定目录。

在 Figma Desktop → Plugins → Development → Import plugin from manifest 中选择：

figma-agent-bridge-plugin/manifest.json

3. 完成首次配对

在 Figma 中启动 Local Figma Agent Bridge，保持插件窗口打开，然后在 PowerShell 运行：

npx -y figma-local-agent-mcp@<VERSION> pair

只有终端与插件显示的六位短码完全一致时，才点击 Codes match。配对成功后，插件会在后续启动时自动认证并重连。

4. 验证连接

重启 MCP 客户端或新建 Agent 会话，确认可发现 25 个静态工具，然后让 Agent 调用 figma_status。正常结果会包含当前 Figma 文件、页面、选区，以及 UNBOUND 或 BOUND 工作区状态。插件与 Server 内部使用 Bridge 协议 11。

Development build、源码构建和直接 MCP 故障排查见直接 MCP 安装指南。

基本使用

从设计稿实现代码

1. 打开目标前端工程，并在 Figma Desktop 中打开 Design 文件和 Local Figma Agent Bridge；让 Agent 先调用 figma_status，再用 figma_frontend_bind_workspace 绑定真实工作区。
2. 说明采用高保真还原，还是优先复用现有设计系统的工程化适配。未指定时，Agent Plugin 的工作流默认采用高保真还原。
3. 大型页面先用 figma_frontend_index_scope 建立结构索引并选择有界根；每个实施范围都先调用 figma_frontend_prepare_workunit，且一次只实施一个 Workunit。
4. Agent 在写视觉代码前更新 implementation.json 的节点到代码映射，事实只按节点 ID 或名称从 JSONL 定向读取；图片或 SVG 通过对应 workUnitId 导出。
5. 完成前调用 figma_frontend_check_workunit_source 检查来源是否仍为 FRESH。截图只作最终外观检查，不建立像素差分基础设施。

示例请求：

- “用高保真方式把当前选中的卡片实现为本项目中的 React 组件，优先复用已有 token，完成后与 Figma 渲染结果核对。”
- “先索引当前页面，按本仓库结构选择有界 Workunit，再逐块生成代码，不要一次加载整页事实。”
- “按现有设计系统实现当前页面，并列出所有相对 Figma 的可见适配。”

详细的范围选择、素材策略和视觉验收规则见前端实现工作流与Workunit 工作流。

在 Figma 中创建或修改 Proposal

1. 在 Figma Desktop 打开目标 Design 文件和 Local Figma Agent Bridge。
2. 在 Agent 中先检查 figma_status，再直接使用 figma_inspect_ 与 figma_design_ 工具，选择要处理的节点并描述读取、修改或生成目标。
3. 修改现有设计时，Agent 会先创建隔离 Proposal；从零生成复杂界面时，会先验证完整 DesignPlan。
4. 在画布中审查生成的 Proposal；公开写工具不会覆盖源稿。

示例请求：

- “读取当前选择，说明它的层级、Auto Layout、字体和视觉样式，不要修改 Figma。”
- “把当前卡片复制为 Proposal，调整间距和标题，然后渲染修改结果供我审查。”
- “使用 DesignPlan 创建新的登录卡片 Proposal，先验证完整计划，再应用并渲染预览。”

工作方式

当前 Design 文件的当前页面 ↕ Figma Plugin API Figma 插件 UI 与主进程 ↕ 每设备认证的 ws://127.0.0.1:3900/ Local Bridge Daemon ↕ 已认证的 ws://127.0.0.1:3900/mcp MCP Adapter ↕ 独立 stdio 会话 Coding Agent ├─ 读取设计事实、Workunit 和素材 → 在本地前端工程生成代码 └─ 发起受控设计写入 → 在 Figma 中创建或修改隔离 Proposal

首次配对由用户核对六位短码。之后每个插件设备使用独立凭据和新鲜 proof 认证。Bridge 只监听 127.0.0.1，不提供远程或云端传输。

从设计稿实现代码时，每个有界范围都先准备一个稳定 Workunit；大型区域或页面可先建立结构索引再选择范围。完整事实保留在不可变的磁盘 JSONL 中，公开 MCP 结果只返回用途明确的路径、完整性状态和必需的控制 token；逐文件摘要、字节计数与正文不跨越该边界。implementation.json 仅记录来源、实施状态、代码映射、假设与未解决差异，工具创建后不再覆盖。

修改现有设计时，Bridge 会把目标与必要布局上下文复制到 Page 级 Proposal；连续写入使用完整树指纹保护并发编辑。从零生成复杂界面时，Agent 可以先验证 DesignPlan，再使用五分钟内单次有效的验证 ID 原子创建 Proposal。

实现细节见 架构与安全模型。

安全边界

- 公开写工具只能新建 Proposal，或修改带 Bridge 标记的 Proposal 根内部节点。
- 输入素材只接受 Base64；Server 不抓取 URL，也不读取调用方指定的本地文件。
- Team Library 不会被查询；需要复用的外部 Instance 必须先放到当前页面。
- Workunit 来源正文只写入会话目录；公开结果仅保留相对路径、完整性信息和 workunit 新鲜度所需的来源指纹，不把完整设计事实或内部摘要注入对话。
- 结构索引、Workunit 与素材导出共享一次性工作区绑定。每个 MCP Adapter 初始为 UNBOUND；实施阶段由 Agent 提交自身任务执行环境的准确 cwd 与最新 session ID，绑定成功后才允许持久写入。
- Bridge 不决定组件职责、代码映射或框架写法；这些实现决策由 Agent 根据用户要求和目标仓库作出。
- 同一时间只支持一个活动 Figma 插件窗口；纯远程智能体无法访问本机 Bridge。

完整边界和操作建议见 安全说明。

文档

| 文档 | 适用对象 | 内容 |
| 文档首页 | 所有人 | 按任务选择文档 |
| 选择安装方式 | 使用者 | 对比插件与直接 MCP 两条路线 |
| 安装 Agent Plugin | 插件客户端用户 | Codex、Cursor、Copilot 稳定版安装 |
| 直接配置 MCP | stdio 主机用户 | Claude、通用主机、Development 与源码构建 |
| MCP 工具参考 | 使用者、Agent 开发者 | 工作流工具集合、写入边界和调用流程 |
| 架构与安全模型 | 开发者 | 进程、协议、Proposal 和 DesignPlan 生命周期 |
| 开发指南 | 贡献者 | Monorepo、常用命令、测试和构建 |
| 端到端验收 | 贡献者 | 发行产物和 Figma 场景验收 |

本地开发

贡献者需要 Node.js 20+ 和 pnpm 11.19.0：

pnpm install --frozen-lockfile
pnpm check
pnpm build:release

pnpm check 会执行 Agent Plugin 校验、类型检查、Lint、格式检查、测试和构建。pnpm build:release 会在 artifacts/ 下生成 Figma 插件 ZIP、npm tarball、可移植 Agent Plugin ZIP 和 SHA256SUMS。

开发环境和仓库结构见 开发指南。

当前范围

当前稳定版支持 Windows、本地 stdio、多个 MCP Adapter、一个活动 Figma 插件，以及当前 Design 文件的当前页面。它支持读取、渲染、Workunit、素材导出、受控 Proposal 编辑和已验证的 DesignPlan。Coding Agent 可以依据这些能力在本地前端工程中生成代码。

当前不提供 Windows 安装器、自动更新、远程传输、云同步、任意 JavaScript、源稿直接写入、通用删除、Instance 分离或 Team Library 查询。Bridge 也不内置特定框架的一键代码生成器；代码生成由所连接的 Coding Agent 完成。

License

本项目基于 MIT License 发布。使用生成的 Proposal 或导出内容前，请在自己的环境中完成审查。