内容
# 中继
从Claude Code驱动Figma。 中继是一个本地桥接器，它为Claude Code提供直接访问您打开的Figma文件的权限：搜索组件、审计令牌覆盖率、重新设置样式变体、在不同配方中切换复制，所有这些都无需离开终端。
[](https://www.loom.com/share/d4127a4e2df743e7a3a81cfcd37cf477)
## 为什么使用中继
Claude Code擅长于推理您的代码库，但它无法触及您的设计系统。 Figma插件可以做到这一点，但它们没有终端、仓库、CI或其他工具。 中继是连接它们之间的桥梁。
安装完成后，Claude Code可以：
- **构建组件。** 搭建新的变体，填充槽位，连接实例交换属性。
- **审计组件。** 扫描页面中的未绑定填充、缺失焦点状态、手动滚动原子、辅助功能回归。
- **修订组件。** 批量重命名变体，将颜色重新绑定到令牌，重新设置整个组件集的样式，只需一个提示。
所有操作都发生在您已经在编写代码的聊天中，因此无需在工具之间复制粘贴。
> **无终端模式。** 中继还附带了一个聊天面板，位于插件内部。 携带您自己的Anthropic API密钥，与Haiku代理对话，具有相同的工具界面。
## 截图
**空状态。** 一个带有启动提示的新聊天。
**带有工具调用的聊天。** 询问组件并获得真实的答案。
**Claude Code活动日志。** Claude Code驱动文件时的实时工具日志。
## 工作原理
```
Claude Code ──▶ MCP 服务器 ──▶ 中继 HTTP 队列 ──▶ Figma 插件 ──▶ figma.*
（stdio） （127.0.0.1:9226） （长轮询）
```
三个部分，全部本地：
- **`server/`**：节点HTTP中继，监听`127.0.0.1:9226`。内存任务队列，长轮询。进程外无状态。
- **`plugin/`**：Figma插件。沙盒执行`figma.*`调用；UI处理聊天/活动面板和工作线程轮询。
- **`mcp/`**：MCP服务器，通过stdio向Claude Code公开中继的工具。
## 快速开始
### 1. 运行中继服务器
两种选项。请选择一个。
**选项A：安装一次，永久运行（macOS推荐）。** 丢弃一个LaunchAgent，以便服务器在登录时启动，并在崩溃时重启。安装后无需终端。
```sh
bash scripts/install.sh
```
稍后删除：`bash scripts/uninstall.sh`。日志位于`~/Library/Logs/relay.log`。
**选项B：手动运行。** 对服务器本身的开发很有用。
```sh
cd server
npm start
```
无论哪种方式，服务器都监听`127.0.0.1:9226`。Claude Code路径不需要API密钥。
### 2. 安装Figma插件
1. 打开Figma桌面版。
2. 插件 → 开发 → 从清单导入插件…
3. 选择`plugin/manifest.json`。
4. 插件 → 开发 → 启动中继。
工作线程模式默认开启。插件立即开始轮询中继，并显示“工作线程空闲”，直到任务到达。
### 3. 连接Claude Code
```sh
cd mcp
npm install
```
将MCP服务器注册到Claude Code：
```sh
claude mcp add relay node /absolute/path/to/relay/mcp/server.js
```
重启Claude Code，运行`/mcp`，确认`relay`已连接。
### 4. 使用它
打开目标Figma文件并运行插件，询问Claude Code关于文件：
> 查找此文件中所有Button组件并报告其变体。
>
> 审计Chip组件集的未绑定填充并重新绑定到Foundry令牌。
>
> 将所有Checkbox配方标签从“记住我”重命名为“订阅更新”。
Claude Code选择正确的`mcp__relay__figma_*`工具，插件对打开的文档执行操作，结果流回对话。
## 向Claude Code公开的工具
| 工具 | 功能 |
|---|---|
| `figma_search_components` | 按名称搜索COMPONENT / COMPONENT_SET节点 |
| `figma_find_node` | 按ID查找节点 |
| `figma_export_node` | 导出PNG / JPG / SVG / PDF（以base64返回） |
| `figma_set_text` | 替换TEXT节点字符（自动加载正确的字体） |
| `figma_set_fills` | 替换节点上的填充数组 |
| `figma_set_strokes` | 替换节点上的描边数组 |
| `figma_set_instance_properties` | 在INSTANCE上设置变体 / 布尔 / 文本 / 实例交换属性 |
| `figma_execute` | 在插件沙盒中逃逸以执行任意异步代码片段 |
通过在`plugin/code.js`中扩展`tools`映射并在`mcp/server.js`中注册它们来添加更多工具。
## 无终端模式（BYOK聊天）
如果您不想设置Claude Code，插件有一个内置的聊天面板。首次启动时，它会要求一个Anthropic API密钥，该密钥存储在`figma.clientStorage`中。该密钥是每个设备独有的，并且只会发送到`api.anthropic.com`。
这是公共分发路径。任何人都可以安装插件，粘贴密钥，并与Haiku代理聊天，该代理具有与Claude Code相同的`figma.*`工具。
## 两种任务形状
中继接受两种`POST /tasks`。
**直接工具调用**，由MCP服务器使用。插件循环中无LLM：
```json
{ "tool": "figma.search_components", "input": { "query": "Button" } }
```
**自然语言指令**，用于插件内聊天。插件运行具有工具白名单的Haiku代理循环：
```json
{ "instruction": "Find every Button component and list its variants." }
```
两者都经过相同的队列和工作线程。添加`?wait=true&timeout=60000`到POST以阻塞直到任务达到终端状态。这就是MCP服务器如何进行同步工具调用的。
## 健康检查
```sh
curl http://127.0.0.1:9226/health
curl -X POST 'http://127.0.0.1:9226/tasks?wait=true&timeout=10000' \
-H 'content-type: application/json' \
-d '{"tool": "figma.search_components", "input": {"query": ""}}'
```
如果插件正在运行，第二个调用将返回打开文件中的每个组件。
## 设计笔记
参见[`DESIGN.md`](./DESIGN.md)，了解架构背景：为什么本地队列优于WebSocket桥接，为什么在插件代理中使用Haiku，MVP故意跳过的内容。
## 许可证
[MIT](./LICENSE)
MCP 市场