内容
# Easel
> 一个代码智能体绘制的画布。
开源的AI编码智能体可视化画布。设计直接渲染为2D画布上的真实HTML — 无需形状到代码的转换步骤。MCP服务器将画布（以及您的项目令牌和组件）交给Cursor或任何支持MCP的智能体，以便智能体可以可视化地组合UI，读取用户选择的内容，并使用您现有的设计系统生成惯用的React代码。
自主托管，本地运行，无需遥测数据。适用于SaaS设计工具不可用的环境。
## 工作原理
```
+----------------+ WebSocket +-----------------+ stdio +-------+
| Easel 画布 | <------------- | Easel MCP | <---------- | IDE |
| (网页应用) | 状态 + | 服务器 | 工具 | 智能体|
| | 选择 | | | |
+----------------+ <-------------> +-----------------+ +-------+
|
v
+-----------------+
| ds-scanner |
| 读取项目的 |
| Tailwind 配置、 |
| 组件/ UI、 |
| 令牌 |
+-----------------+
```
1. 画布（`pnpm canvas`）在 `http://localhost:5173` 运行。
2. 您的IDE智能体启动MCP服务器，该服务器绑定本地WebSocket到 `127.0.0.1:7777` 并保持规范状态。
3. 您要求智能体构建某些内容。它使用您的真实令牌在画布上绘制HTML。您可以实时查看。
4. 选择同步双向。单击画布 → 智能体的 `get_selection` 返回它。智能体调用 `set_selection` → 您的屏幕上跳转的靶心环。
5. 当您满意时，要求智能体将其交付。它读取树（`get_jsx`、`get_computed_styles`、`get_screenshot`）并使用您的 `<Button>`、您的令牌、您的约定将惯用的JSX写入您的存储库中。
## 要求
- **Node.js 20+** (`node --version`)
- **pnpm 8+** (`pnpm --version`) — `npm install -g pnpm`
- 用于画布的基于Chromium的浏览器（Chrome、Edge、Arc、 Brave等）
## 安装
```bash
git clone git@github.com:mraza007/easel.git
cd easel
pnpm setup # 安装依赖项，构建 ds-scanner + mcp-server
pnpm canvas # 仅在 http://localhost:5173 启动网页画布
```
`pnpm canvas` 故意**不**启动MCP服务器 — 您的IDE智能体会通过stdio（下一节）启动自己的副本。这样可以保持WS端口7777空闲，供负责的智能体使用。
一旦画布启动，请打开 `http://localhost:5173`。右上角的状态指示器会显示 **OFFLINE**，直到您连接智能体。
## 连接智能体
Easel与任何支持MCP的智能体一起工作。最快捷的方式是使用捆绑的安装程序。
### Cursor（推荐）
```bash
pnpm install:cursor # 使用 easel 存储库作为设计系统源
pnpm install:cursor -- --project-root ~/code/my-app # 或指向您的真实 React 项目
```
脚本：
- 写入 `~/.cursor/mcp.json`（如果丢失则创建，保留已经在那里的服务器）。
- 将 `EASEL_PROJECT_ROOT` 设置为您传递的路径 — 这是 `ds-scanner` 在启动时读取以检测 Tailwind 配置、组件和 CSS 变量的目录。将其指向您要智能体翻译设计到的 React 项目。
- 幂等 — 随时重新运行以更改项目根目录。
运行后：
1. 启动画布（`pnpm canvas`）。
2. 重启 Cursor（或在 **设置 → 工具 & MCP** 下切换 `easel`）。
3. 在 Cursor 聊天中： *"使用 easel MCP — 画布上有什么？"*
### 手动配置
如果您更喜欢手动编辑，存储库根目录中的 `cursor.example.json` 具有确切的 JSON 形状。将其复制到 `~/.cursor/mcp.json` 并替换绝对路径。
对于项目范围的安装，请在该项目中将相同的 JSON 文件放在 `.cursor/mcp.json` 下。项目配置优先于全局配置，如果两者都定义了 `easel`。
### 其他支持 MCP 的智能体
MCP 服务器是一个纯粹的stdio二进制文件，位于 `mcp-server/dist/index.js`（首先运行 `pnpm setup`）。任何可以启动MCP stdio进程的工具都可以使用 — 将其指向该路径并设置 `EASEL_PROJECT_ROOT` 以启用设计系统内省。
## 示例提示
连接智能体后，尝试：
```
使用 easel MCP 告诉我画布上有什么。
```
调用 `get_basic_info`。智能体总结种子画板。
```
使用 easel 添加一个包含三个并排卡片的“Pricing”画板。
```
观看画板实时出现并填充，智能体调用 `create_artboard` + `write_html`。
```
我已经在画布上选择了一个按钮。使用 easel 读取选择内容并使其变大且呈靛蓝色。
```
调用 `get_selection`，然后 `update_styles`。无需节点 ID 粘贴。
```
通过 get_jsx + get_computed_styles 读取 Pricing 画板，然后使用语义 Tailwind 类将其写入 src/Pricing.tsx 作为 React 组件。
```
完整的智能体 → 真实代码循环。截图工具为智能体提供视觉基础，当计算样式不够时。
## 智能体可以执行的操作（17 种 MCP 工具）
**读取：** `get_basic_info`、`get_design_system`、`get_node_info`、`get_jsx`、`get_computed_styles`、`get_screenshot`、`get_selection`
**写入：** `create_artboard`、`write_html`、`update_styles`、`set_text`、`set_layer_name`、`set_document_name`、`delete_node`、`duplicate_artboard`、`reset_canvas`、`set_selection`
## 您可以直接执行的操作（无需智能体）
| 操作 | 方法 |
|---|---|
| 平移/缩放 | 拖动空白画布 / `cmd+scroll` |
| 选择 | 点击画布或图层树 |
| 取消选择 | 点击空白画布，或 `Esc` |
| 编辑文本 | 双击任意文本 → 输入 → `Enter`（或失去焦点）；`Esc` 取消 |
| 删除 | 选择后按 `Delete` 或 `Backspace` |
| 新建画板 | 点击侧边栏中“画板”旁边的 `+` |
| 复制画板 | 选择画板，按 `⌘D` |
| 重命名文档 | 点击顶部工具栏中的文件名 |
| 重命名画板 | 双击图层树中的名称 |
| 服务器菜单 | 点击连接指示器 — 从磁盘重新加载，重新连接，重置 |
## 持久性
状态自动保存到 `~/.easel/state.json`（使用 `EASEL_STATE_FILE` 覆盖）。500毫秒防抖，原子写入通过 `.tmp` + 重命名。启动时加载。删除文件以恢复到种子状态。
如果画布和磁盘曾经漂移（例如，旧的智能体进程在内存中留下了状态），请在服务器菜单中使用 **从磁盘重新加载** — 一键恢复。
## 故障排除
**状态指示器一直显示 OFFLINE。**
MCP服务器未绑定到 `127.0.0.1:7777`。检查您的IDE是否已启动它 — 在 Cursor 中，查看 **设置 → 工具 & MCP** 并确认已启用 `easel`。如果其他内容占用了端口：
```bash
lsof -nP -iTCP:7777 -sTCP:LISTEN -t | xargs kill
```
**画布显示的内容与 `~/.easel/state.json` 不同。**
一个过时的mcp-server正在并行运行并提供过时的内存状态。打开服务器菜单（点击连接指示器）并使用 **从磁盘重新加载**。
**智能体说它找不到节点 ID。**
您可能在画布具有过时的ID时重启了服务器。使用 `⌘+shift+R` 强制刷新浏览器，以便它采用服务器的当前状态。
## 软件包
- **`app/`** — Vite + React 画布。真实的 HTML/CSS，可平移 + 缩放，图层树，选择，自动保存指示器，服务器管理菜单。
- **`mcp-server/`** — Node MCP 服务器（stdio）。保持规范树状态，通过 WebSocket 与画布桥接。今天有 17 种工具。
- **`ds-scanner/`** — 项目内省。自动检测 Tailwind 配置、组件库、设计令牌、CSS 自定义属性从项目根目录。
## 状态
预发布。形状 1（智能体驱动的画布）是具有选择、内联编辑、多画板组织和服务器管理 UI 的端到端功能。样式检查器和 Tailwind 类循环遍历是下一步。
## 许可证
MIT.
