内容
# Reqwise Figma 中间件
**一个让 AI 代理可以读取和绘制 Figma 画布的中间件——安全。**
Reqwise Figma 中间件将本地中间件服务器与配套的 Figma 插件配对。指向 Claude Code、Cursor 或任何支持中间件的代理，然后代理可以通过执行针对 `figma.*` 代理 API 的 JavaScript 来检查 Figma 文件并绘制到其中——插件层捕获通常将“AI 绘制屏幕”变成“AI 绘制溢出、半剪辑混乱”的错误。
它的存在是因为当前一代的 Figma 中间件使代理负责它们不具备的自律：记住永远不要叠加半透明框架，每次调用重新声明令牌映射，手动计算 x/y 偏移，目视检查截图以检查剪辑。Reqwise 将这种自律转移到服务器和插件，并为代理提供了一种结构化的方法来验证其自身的工作。
## 为什么选择这个
| | 典型的 Figma 中间件 | Reqwise Figma 中间件 |
|---|---|---|
| 验证 | 仅截图——代理检查像素 | `layout_audit` 返回声明的边界与渲染的边界、`overflowsParent`、`clippedBy`、`textTruncated`，每个节点；截图保留用于最终人工审查 |
| 叠加层/遮罩 | 代理使屏幕变暗，带有不透明度框架（使整个子树变暗） | `figma.overlay()` 创建一个正确分层的矩形——结构上无法犯错 |
| 会话状态 | 令牌映射和 ID 注册表在每次调用时重新声明 | `state` 是每个会话的持久对象；设置令牌一次，在调用之间重用 |
| 连接 | 静默布尔值，或带有无解释的死 WebSocket | `figma_status` 返回诊断信息和有序的 `hints` 列表，用于具体下一步骤 |
| 多个 IDE 窗口 | 第二个服务器实例争夺端口或静默失败 | 领导者/跟随者选举；跟随者通过身份验证的 `/rpc` 转发给持有插件连接的领导者 |
| 批量操作 | 硬上限（例如 50 个操作），全部或无失败 | 分段流式处理，部分提交，精确的每个索引错误报告，无硬上限 |
| 结构框架 | Figma 的默认白色填充将布局包装器变成意外的白色板 | FRAME/COMPONENT 如果没有显式填充，则默认为透明；可见表面选择加入 |
| 沙盒 JavaScript | 受限制/旧语法（无 `?.`、`??`、扩展） | 节点 `vm`——完整的现代 ES（可选链接、空值合并、扩展、async/await） |
| 错误 | 裸异常 | 每个失败都带有 `{code, message, hint}`——提示是下一步骤 |
| 原位编辑 | 从头绘制的关注点；每个操作都与单线程插件冲突 | 基于选择的 工作流（`readSelection` → 修改 → `layout_audit`），实例重写“格式绘制器”，递归重新着色，混合字体安全的文本编辑；写入序列化每个连接，因此突变永远不会竞争 |
有关这些默认值的完整设计原理和根本原因修复，请参见 [`ARCHITECTURE.md`](./ARCHITECTURE.md)。
## 快速入门
**1. 安装**
```bash
git clone https://github.com/<you>/reqwise-figma-mcp.git
cd reqwise-figma-mcp
npm install
npm run build
```
这会将服务器构建到 `dist/`，并将插件包构建到 `plugin/code.js`。
**2. 注册中间件服务器**
```bash
claude mcp add reqwise-figma -- node /absolute/path/to/reqwise-figma-mcp/dist/server/index.js
```
（有关 Cursor 和 Claude Desktop JSON 配置，以及基于 `npx` 的设置，请参见 [`docs/INSTALL.md`](./docs/INSTALL.md）。）
**3. 将插件导入 Figma Desktop**
Figma Desktop → 菜单 → **插件 → 开发 → 从清单导入插件…** → 从此仓库中选择 `plugin/manifest.json`。从 **插件 → 开发 → Reqwise Figma 中间件** 运行它，并保持其窗口打开。
**4. 检查连接**
要求您的代理调用 `figma_status`。健康的连接如下所示：
```json
{
"pluginConnected": true,
"mode": "leader",
"port": 38470,
"plugin": { "version": "0.1.0", "apiVersionMatch": true, "fileName": "My File", "pageName": "Page 1" },
"hints": ["All systems nominal. Draw with figma_write; verify with figma_read layout_audit."]
}
```
如果 `pluginConnected` 为 `false`，或提示中提到版本不匹配或心跳丢失，请参见 [`docs/INSTALL.md`](./docs/INSTALL.md) 中的故障排除表。
`pluginConnected` 是三态的：`true`/`false` 是 **测量的**，`null` 表示 **未知**——从属进程无法查询领导者（请参见 `statusSource` 和 `statusError`）。将 `null` 视为“无信息”，而不是断开连接：操作可能仍在转发，因此不要仅凭 `null` 就重新安装或重启插件。
## 工具
| 工具 | 用途 |
|---|---|
| `figma_status` | 丰富的连接诊断信息——插件连接、领导者/从属模式、心跳、队列、会话和有序的 `hints` 列表。永远不是裸布尔值。 |
| `figma_read` | 通过 `op` 枚举读取画布（`get_document_info`、`get_selection`、`read_selection`、`get_design_context`、`get_design_system_kit`、`generate_design_md`、`search_nodes`、`screenshot`、`layout_audit`，...），响应令牌节省。 |
| `figma_write` | 对 `figma.*` 代理执行现代 ES JavaScript 以创建/修改画布。`state` 在每个会话中持久存在。 |
| `figma_rules` | 一次调用设计系统规则表（样式 + 变量 + 组件）为 Markdown——在绘制前读取以重用而不是硬编码。对于持久规范，请使用 `figma_read` 操作 `generate_design_md` 并将返回的 Markdown 保存为 `design.md`。 |
| `figma_docs` | 按需文档：`rules` \| `layout` \| `api` \| `tokens` \| `icons` \| `recipes`。 |
每个操作和每个 `figma.*` 方法的完整参数参考：[`docs/TOOLS.md`](./docs/TOOLS.md)。
## 示例：`figma_write`
```js
// 设置令牌一次——它们在此会话的 `state.tokens` 中持久存在。
await figma.setupTokens({
colors: { primary: "#2563EB", surface: "#0B0B0F" },
numbers: { "radius-md": 8 },
});
// 绘制一个带有换行文本的卡片，重用父级的宽度。
const card = await figma.create({
type: "FRAME", name: "Card", parentId: state.rootId,
width: 320, layoutMode: "VERTICAL",
});
await figma.applyVariable(card.id, "fills", "surface");
await figma.create({
type: "TEXT", parentId: card.id, wrap: true,
characters: "A long paragraph that must wrap inside the card.",
});
// 在截图给人类之前进行验证。
const audit = await figma.layoutAudit(card.id);
if (audit.summary.issues.length) console.warn(audit.summary.issues);
```
## 示例：生成 `design.md`
要求您的代理调用：
```json
{ "op": "generate_design_md", "params": { "depth": 3, "includeAnatomy": true, "includeScreens": true } }
```
响应包含源基础的 `design.md`：提取覆盖范围、颜色、
## 架构
```
中间件客户端（Claude Code / Cursor）
│ stdio（MCP）
▼
Reqwise 中间件服务器（Node ≥ 18，TypeScript）
│ 拥有 localhost:38470 上的 HTTP+WS 服务器（备用 +1..+9）
│ GET /health → 诊断信息 JSON
│ POST /rpc → 从属 → 领导者转发（身份验证令牌）
│ WS /ws → Figma 插件 UI 连接
▼
Figma Desktop 插件
├── ui.html （WebSocket 客户端，心跳，重连 w/ 回退）
└── code.js （插件 API 执行器，安全默认处理程序）
```
每个操作——直接领导或转发跟随者——都通过一个 `validateOperation()` 阻塞点，然后才到达插件。完整的拓扑结构、领导/跟随者协议和 15 个安全默认修复在 [`ARCHITECTURE.md`](./ARCHITECTURE.md) 中有详细说明。
## 文档
- [`docs/INSTALL.md`](./docs/INSTALL.md) — 详细设置，MCP 客户端配置，故障排除
- [`docs/TOOLS.md`](./docs/TOOLS.md) — 完整的工具 + `figma.*` API 参考，错误代码
- [`docs/MIGRATION.md`](./docs/MIGRATION.md) — 从 `figma-ui-mcp` 迁移
- [`docs/RECIPES.md`](./docs/RECIPES.md) — 实用食谱
- [`ARCHITECTURE.md`](./ARCHITECTURE.md) — 设计目标和内部原理
## 许可证
MIT © 2026 Hoang Phan. See [`LICENSE`](./LICENSE).
