shared-whiteboard

--- tags: - 白板 - tldraw - mcp - 工具 # 共享白板 命名、持久的 draw.io 风格的白板在浏览器中，**您和克劳德可以同时编辑**。白板存活在一个小型同步服务器上；浏览器通过 [tldraw](https://tldraw.dev) 渲染它们；MCP 服务器允许克劳德按名称打开并修改白板。您的编辑和克劳德的编辑会出现在同一个画布上。 ## 其适用的工作流程 1. 打开网页 UI，从下拉菜单中选择一个白板（或 `＋ new`）。下拉菜单的名称是您告诉克劳德的名称。 2. 告诉克劳德： *"打开 **身份验证重构** 白板并添加一个会话存储节点"*。 3. 克劳德调用 `open_board("身份验证重构")` 然后进行编辑 - 您实时观察到这一过程。 4. 任一方都可以创建白板；新白板会出现在另一方的列表中。 ## 架构 ### 每个白板都有一个权威文档 - 每个白板都是一个 `TLSocketRoom` (`@tldraw/sync-core`)，由 URL 安全 ID 索引。 - 两种客户端修改同一个房间：浏览器（WebSocket，`@tldraw/sync`）和克劳德（HTTP，通过 MCP 服务器）。 - 每个突变都通过 `room.updateStore(...)` 运行，它广播到所有连接的浏览器 - 因此克劳德的编辑实时显示，并且 `get_board` 反射您刚刚进行的编辑。 - **持久性**：任何更改（浏览器或克劳德）都会将白板的快照 debounce-write 到 `data/snapshots/<id>.json`；在下次访问时重新加载。白板名称存储在 `data/boards.json` 中。重启服务器后保留每个白板。 ``` 浏览器（tldraw useSync） ──WS──┐ ├── server.js（每个白板的 TLSocketRoom） ── data/*.json 克劳德（mcp-server.js） ──HTTP──┘ ``` ### 组件 - `server.js` — 同步后端。浏览器 WS 在 `/connect/:boardId`；语义化 HTTP API；还从 `web/dist` 提供内置网页 UI（一个端口处理所有功能）。 - `boards.js` — 命名 + 持久化房间注册表（创建/重命名/删除/加载/保存）。 - `shapes.js` — 构建器 → 有效的 tldraw v5.2.5 记录（从实时编辑器捕获）。 - `uml-schema.js` — 自定义 `uml` 形状的属性（后端部分；参见下面的注意事项）。 - `templates.js` — 可重用的块存储 + 模板/克隆（ID 重新映射，重新基准到某个点）。 - `mcp-server.js` — 标准输入输出 MCP。持有每个会话的“当前白板”；每个工具 = 一个 HTTP 调用。 - `web/` — Vite + React + tldraw 客户端。白板选择器，`＋UML`，保存/模板戳。 - `web/src/uml.tsx` — `UmlShapeUtil`（自定义形状的浏览器部分 + 双击编辑）。 ### 自定义 UML 形状 - 唯一的陷阱 自定义 tldraw 形状必须在 **三个** 位置注册，所有位置都同意相同的属性（无迁移，因此同步模式匹配）： 1. `web/src/uml.tsx` — `UmlShapeUtil.props`（浏览器渲染 + 验证）。 2. `uml-schema.js` → `boards.js` `createTLSchema({ shapes: { uml: {props} } })`（服务器验证）。 3. `shapes.js` `buildUml`（MCP 服务器写入的记录）。 更改一个位置的属性，请在所有三个位置更改，否则同步将中断。 ### 重用模型 没有 Figma 风格的链接主节点（tldraw 没有）。模板是捕获的记录包；模板克隆它们并在目标点具有新的 ID。副本是独立的。编辑 `data/templates.json` 以检查/修剪。 ## 运行 ### 开发（热重载） ```bash ./run.sh # 后端 :5858 + Vite 开发 UI :5173 → 打开 http://127.0.0.1:5173 ``` ### 始终运行（一个进程提供 UI + API 在 :5858） ```bash cd web && npm run build # 构建 UI 一次（在更改 web/ 后重新运行） # 然后安装用户服务： cp whiteboard.service ~/.config/systemd/user/whiteboard.service systemctl --user daemon-reload systemctl --user enable --now whiteboard.service # UI + API 现已在 http://127.0.0.1:5858 上运行 ``` ## 克劳德 / MCP 在 **用户范围** 注册（在每个项目中都有效），指向后端： ```bash claude mcp add --scope user whiteboard --env WB_URL=http://127.0.0.1:5858 \ -- node "/home/camer/ClaudeChats/Shared Whiteboard/mcp-server.js" ``` MCP 服务器仅代理 HTTP，因此 **后端必须运行**（这就是为什么建议始终运行）。重启克劳德代码以在添加服务器后加载它。 ### 工具 白板管理： - `list_boards` — 每个白板（名称，ID，形状计数，已更新）。 - `open_board {name}` — 按名称/ID 打开，使其处于活动状态，返回其内容。 - `create_board {name}` — 创建 + 打开 + 使其处于活动状态。 - `rename_board {name, id?}` / `delete_board {name}`。 编辑活动白板（首先调用 `open_board` 或 `create_board`）： - `get_board` — 所有形状（ID，类型，x/y，w/h，颜色，文本；UML 形状还提供名称/字段/方法）+ 箭头链接。 - `create_node {text,x,y,w?,h?,shape?,color?,fill?}` → ID。 - `create_text {text,x,y,color?,size?}` → ID。 - `create_note {text,x,y,color?}` → ID。 - `create_uml {name,x,y,fields?,methods?,color?}` → ID。UML 类块（标题 + 字段 + 方法隔间）。 - `update_uml {id,name?,fields?,methods?,color?,x?,y?,w?}` — 替换名称/字段/方法。 - `add_field {id,field}` / `add_method {id,method}` — 追加一行（自动增长）。 - `connect {fromId,toId,text?,color?,dashed?}` → 随形状移动的箭头。 - `update_node {id,text?,x?,y?,w?,h?,color?,fill?}`。 - `delete_shapes {ids}` — 还会删除绑定的箭头。 - `clear_board` — 清除形状/箭头（保留白板）。 可重用模板（保存一个块一次，在任何地方戳复制品）： - `list_templates` — 已保存的模板（名称 + 形状计数）。 - `save_template {name, ids}` — 从活动白板中捕获给定的形状（+ 它们之间的箭头）作为模板。 - `stamp_template {name, x, y}` — 在活动白板上放置一个全新的独立副本。 - `delete_template {name}`。 ### 枚举 - **颜色**：黑色，灰色，浅紫色，紫色，蓝色，浅蓝色，黄色，橙色，绿色，浅绿色，浅红色，红色 - **形状** （几何）：矩形，椭圆，菱形，三角形，六边形，云，星形，卵形，五边形，八边形，菱形，梯形，X 盒，复选框，心形 - **填充**：无，半实心，实心，图案 - 无效枚举 → 错误（否则会使浏览器的验证器崩溃）。 ## HTTP API（MCP 服务器调用） - `GET /boards` · `POST /boards {name}` · `POST /boards/rename {id,name}` · `POST /boards/delete {id}` · `GET /boards/find?q=` - `GET /board?board=<id>` — 语义摘要 · `GET /snapshot?board=<id>` — 原始 - `POST /node|/text|/note|/connect|/update|/delete|/clear?board=<id>` - `POST /mutate?board=<id>` — 低级 `{puts, deletes}` 出口 ## 注意事项 / 限制 - 坐标是 tldraw 页面像素；`create_*` 将形状放置在 `x,y`（左上角）。 - 冲突模型是每次写入最后 - 胜利者每个记录 - 足够好用于人类 + 克劳德轮流操作，不适合 CRDT 级别的两个人在同一个文本字段中同时输入。 - 后端绑定 `127.0.0.1`。对于 LAN，设置 `WB_HOST=0.0.0.0` 并打开主机的 IP 地址。