内容
<img src="assets/relai-logo.svg" alt="Relai" height="36" />
| [English](README.md) | 日本語 | 中文 |
**你的AI，在画布上。** Relai 连接 Claude Code、Cursor、Codex — 任何 MCP 客户端 — 到 Figma，这样你可以通过与你已经使用的模型对话来读取、编辑、审核和构建设计系统。它适用于每个 Figma 计划，因为写入操作通过 Figma 插件进行，而不是付费 REST API。
<img src="assets/plugin-ui.png" alt="Relai 插件：活动日志、连接状态和停止按钮" width="380" />
## 会话示例
> **你：** 让 CTA 按钮突出并圆润。
>
> **AI：** `set_properties · 3 个节点 · 0.4s ✓` → `verify_visual · match ✓`
>
> **你：** 现在对整个屏幕进行暗黑模式调整。
>
> **AI：** `set_properties · 24 个节点 · 1.2s ✓` → `analyze_design · 总体 → 92/100`
每个命令在插件中显示其运行过程，带有计时和成功或失败信息。单击某个条目即可跳转到画布上的该层。如果你改变主意，请按 **停止** 按钮 — 其余的操作将被取消。
## 快速开始
你需要 [Figma Desktop](https://www.figma.com/downloads/)、[Node.js](https://nodejs.org/) 18+ 和一个 MCP 客户端。
**1. 安装插件。** 从 [Figma 社区](https://www.figma.com/community/plugin/1662131506342078142) 获取并运行它。插件会自动连接并在重启后记住其房间。
**2. 将服务器** 注册到你的 AI 客户端：
```bash
claude mcp add Relai -- npx -y figma-relai # Claude Code
codex mcp add Relai -- npx -y figma-relai # Codex CLI
```
对于 Cursor，请在 `.cursor/mcp.json` 中添加以下内容：
```json
{ "mcpServers": { "Relai": { "command": "npx", "args": ["-y", "figma-relai"] } } }
```
**3. 请求操作。** 配对是自动的；无需在窗口之间复制任何内容。`join_room` 工具仅在一种特殊情况下使用：两个 Figma 文件同时运行插件。
## 优势
理解设计。 "这个屏幕是如何组合的？" 可以让你一次性获取结构、颜色、布局和令牌使用情况，AI 可以截取屏幕截图来实际查看画布，而不是进行猜测。
批量编辑。 "将所有按钮标签翻译成英文" 或 "将此颜色调整为暗黑模式" 变成一次操作，适用于数十个节点，而不是花费一个下午的时间点击。
审核。 `analyze_design` 检查颜色令牌覆盖率、自动布局质量、组件健康状况和可访问性（WCAG 对比度、触摸目标、文本大小）— 或一次检查所有四个方面，并获得一个加权 0–100 的健康评分，你可以将其放入评审中。
设计系统。具有模式的变量集合、令牌绑定、共享样式、具有正确变体的组件、团队库导入。这些作为声明性操作运行，并带有前提检查，因此相同的请求每次都会以相同的方式运行，并且失败会告诉 AI 下一步该怎么做（“首先调用 `set_layout_mode`”），而不是抛出堆栈跟踪。
其他功能。 `execute_figma` 直接针对 Figma 插件 API 运行 JavaScript — 与 Figma 的官方 MCP 使用的相同逃脱方式 — 带有 `relai.*` 帮助库，使正确的模式成为最短的模式，附带已知错误的提示和标记无声错误的 lint。如果你希望 AI 从不运行代码，请使用插件的“允许代码执行”切换按钮将其关闭。
## 你始终在控制中
插件是设计师的一方：一个显示 AI 执行的所有操作的实时活动日志，一个“AI 已连接”的指示器，指示代理实际已配对（而不仅仅是服务器正在运行），以及一个停止按钮，用于取消待处理的工作。你做出的选择和页面更改会作为事件流回 AI，因此“现在对这个也执行相同的操作”无需重新解释。UI 支持英文、日文和中文。
## 工作原理
```
AI（任何 MCP 客户端）
↕ 标准输入/输出
MCP 服务器 30 个工具 · 分析 · 验证
（嵌入式中继） 127.0.0.1:9055 上的 WebSocket 房间中心
↕ WebSocket
Figma 插件 执行插件 API 调用
```
中继位于 MCP 服务器内，因此无需保持额外的进程运行。当多个 MCP 客户端同时运行时，第一个客户端托管中继，其他客户端连接到它；如果主机退出，幸存者将接管。双方都记得自己的房间，在重启或睡眠后重新加入，并在无需复制任何内容的情况下找到彼此。
端口由 Figma 的插件沙盒固定：清单文件允许使用 `ws://localhost:9055–9057`，而其他端口如果不编辑 `manifest.json` 则无法工作。因此，UI 中没有端口设置。
## 工具
| 分组 | 工具 |
|-------|-------|
| 上下文 | `get_document_overview` · `get_selection_context` · `get_node_details` · `search_nodes` · `get_design_tokens` · `screenshot` · `get_events` |
| 分析 | `analyze_design`（颜色 / 布局 / 组件 / 可访问性 / 总体）· `diff_nodes`（比较或检查点保存/比较） |
| 验证 | `verify_changes` · `validate_design_rules` · `verify_visual` |
| 读取 | `get_node_data`（摘要 / 树 / 完整 / CSS / 变量） |
| 创建和编辑 | `create_node` · `set_properties` · `set_text` · `edit_structure` |
| 组件 | `manage_components` |
| 设计系统 | `manage_variables` · `manage_styles` · `import_from_library` |
| 文档 | `manage_pages` · `navigate` |
| 资产 | `export_asset` · `add_image` |
| 注解 | `annotate` |
| 评论 | `manage_comments`（需要令牌 — 请参见下文） |
| 高级 | `batch_execute` · `execute_figma` · `join_room` |
每个工具都是自我描述的，因此 AI 可以看到完整的参数文档。六个技能文档作为 MCP 提示随附：令牌策略、组件约定、审核工作流程和 `execute_figma` 的插件 API 备忘录。
## Relai 和 Figma 的官方 MCP
Figma 的官方 MCP 服务器旨在将完成的設計转换为代码，其设计上下文和 Code Connect 集成是适用于该交接的正确工具。Relai 朝相反方向发展：它帮助设计师创建和维护设计本身，使用任何客户端和模型，在任何计划上。如果你的团队有席位，请同时运行两者。
## 可选：评论
评论位于 Figma 的 REST API 后面，需要个人访问令牌。在 figma.com → 设置 → 安全（启用评论范围）中生成一个，然后将其添加到你的 MCP 配置中：
```json
{ "mcpServers": { "Relai": { "command": "npx", "args": ["-y", "figma-relai"],
"env": { "FIGMA_TOKEN": "figd_..." } } } }
```
令牌保留在你的配置文件中，仅发送到 `api.figma.com`。其他所有工具无需令牌即可工作。有了它，“应用评论中的反馈”成为 AI 可以实际执行的操作：读取线程、进行编辑、回复。
## 故障排除
**插件显示无服务器。** 没有 MCP 服务器正在监听端口 9055–9057，这通常意味着你的 AI 客户端未运行或 Relai 未在其上注册。面板显示确切的注册命令；插件会一直拨打并在服务器出现时连接。
**中继显示链接但代理显示等待。** 管道正常 — AI 只是在此会话中尚未调用 Figma 工具。向它询问有关文件的问题。
**“多个 Figma 插件已连接。”** 两个文件正在运行插件。告诉 AI 使用插件中显示的房间名称 `join_room`。
**第一次 `npx` 运行缓慢。** 它会一次性下载软件包；后续启动速度很快。
## 安全
中继仅绑定到 `127.0.0.1`，并且对房间名称没有任何身份验证，房间名称带有加密随机后缀。`execute_figma` 在 Figma 的插件沙盒中运行 AI 编写的代码；它默认启用，每次运行都在活动日志中可见，设计师可以禁用它。脚本不是原子的 — 失败的脚本的早期更改仍然存在。完整的威胁模型：[SECURITY.md](SECURITY.md)。
## 贡献者
```bash
git clone https://github.com/syoooo/figma-relai.git
cd figma-relai
bun setup # 安装、构建、编写本地 MCP 配置
bun test
```
需要 [Bun](https://bun.sh/) v1.0+（设置脚本是 bash；在 Windows 上使用 WSL）。通过 **插件 → 开发 → 从清单导入插件…** → `packages/figma-plugin/manifest.json` 加载插件。独立中继（`bun socket`）存在于一种特殊情况，即中继必须在另一台机器上运行。更多信息请参见 [CONTRIBUTING.md](CONTRIBUTING.md)；手动 QA 位于 [docs/smoke-checklist.md](docs/smoke-checklist.md)。
## 许可证
MIT — 请参见 [LICENSE](LICENSE)。
