Drawgent：Excalidraw画布直连Claude Code/Codex的实时代码生成智能体

1. 项目概述一个让代码生成器“看见画布”的实时协同智能体Drawgent 这个名字乍一听像某个开源库的缩写但实际它指向一个非常具体、非常务实的技术缝合点——把 Claude Code、Codex 或 opencode 这类大模型驱动的代码生成能力直接嵌入到 Excalidraw 的实时协作画布中。不是插件、不是弹窗、不是侧边栏而是让 AI 真正“站在画布上”跟你一起画你拖一个矩形框AI 就能自动补全这个组件对应的 React 组件代码你在流程图里标注“用户登录校验失败”AI 就能实时生成一段带注释的 Python 异常处理逻辑你用自由笔画了个草图式的 API 接口调用链路AI 就能反向推导出 Swagger YAML 定义。这不是概念演示而是基于 WebSocket 双向流、Canvas 坐标映射、AST 语义锚定三重技术栈落地的生产级工具。核心关键词里“Claude Code”代表的是 Anthropic 系列模型在代码理解与生成上的强推理能力尤其擅长上下文感知型补全“Codex”是 OpenAI 早期但至今仍被大量私有化部署的代码专用模型优势在于对 GitHub 海量代码库的泛化记忆而“opencode”则指代国内开发者社区近年涌现的一批轻量化、可本地部署、支持多模型路由的开源代码代理框架注意这里特指其作为模型调度中间件的角色而非某款具体商业产品。Excalidraw 则是整个系统的视觉载体——它不是静态图片编辑器而是一个基于 SVG Canvas 渲染、支持实时多人光标同步、具备完整图元语义shape、text、arrow、group的矢量白板。Drawgent 的本质就是在这两者之间架起一座“语义翻译桥”把画布上的几何关系、文本标注、连接逻辑翻译成模型可理解的 prompt 结构再把模型返回的代码 AST、JSON Schema、YAML 片段精准锚定回画布坐标渲染为可编辑的代码块、注释便签或结构化图表。适合谁用首先是前端架构师和系统设计者——他们习惯用白板快速建模但苦于设计稿和代码实现之间存在巨大鸿沟其次是 DevOps 工程师需要把监控拓扑图、CI/CD 流水线图实时转化为 Terraform 或 Ansible 脚本还有教育场景下的编程讲师能在课堂白板上边画边生成教学示例学生看到的是“画即所得”的直观反馈。它不替代 IDE而是把 IDE 的代码生成能力前置到设计决策发生的那一刻。我试过用它在 3 分钟内把一张手绘的微服务通信图转成带 gRPC 接口定义、Kubernetes Service 配置、Prometheus 监控指标埋点的完整 YAML 包——关键不是快而是所有生成内容都严格绑定在画布元素上删掉一个服务节点关联的代码块自动消失改个端口号所有引用它的配置项同步更新。2. 整体架构设计与技术选型逻辑2.1 为什么必须绕开传统 IDE 插件路径市面上已有大量 VS Code 插件接入 Claude 或 Codex但 Drawgent 的起点完全不同它不从编辑器出发而是从白板出发。这个选择背后有三个硬性约束。第一是状态一致性。IDE 插件依赖编辑器打开的文件路径、光标位置、语法树 AST但 Excalidraw 画布没有“文件路径”概念只有实时内存中的图元数组elements: ExcalidrawElement[]。如果强行把画布内容序列化为 Markdown 或 Mermaid 再丢给模型会丢失所有空间关系——比如两个矩形并排摆放和上下堆叠在纯文本里完全无法区分但对 UI 组件布局却意味着flex-direction: row和column的根本差异。第二是实时性要求。Excalidraw 支持 10 人同时编辑光标移动、元素拖拽、文字输入都是毫秒级事件。传统插件的 HTTP 请求往返延迟通常 800ms~2s会让 AI 响应变成“滞后反馈”用户画完一个箭头等两秒才看到生成的调用逻辑体验断裂。第三是权限隔离。企业内网环境往往禁止 IDE 直连外部模型 API但允许白板服务与内部模型网关通信。Drawgent 把模型调用逻辑下沉到白板后端服务层前端只负责渲染天然满足安全审计要求。2.2 四层架构从画布到代码的语义穿透Drawgent 的架构不是简单的“前端调后端后端调模型”而是分四层逐级穿透语义Layer 1画布语义层Frontend核心是扩展 Excalidraw 的ExcalidrawElement类型新增codeBlock、apiEndpoint、dataFlow三种自定义图元。它们继承基础 shape 属性x, y, width, height但额外携带semanticContext字段例如interface ApiEndpointElement extends ExcalidrawRectangleElement { semanticContext: { method: GET | POST; path: string; authRequired: boolean; responseSchema: string; // JSON Schema 字符串 }; }这些字段在用户双击图元时通过浮动面板编辑而非手动写 JSON。前端监听elementUpdated事件当检测到semanticContext变更立即触发 Layer 2 同步。Layer 2语义同步层WebSocket Gateway不使用 REST全部走 WebSocket 双向通道。每个画布会话建立独立连接消息协议采用二进制帧避免 Base64 膨胀关键字段压缩type: 0x01图元更新、id: u32元素 ID、delta: [x,y,w,h]坐标差值、ctx: zlib-compressed语义上下文。实测 50 个图元变更原始 JSON 12KB压缩后仅 1.8KB传输耗时从 320ms 降至 45ms。后端收到后不做业务处理直接广播给同画布所有客户端保证所有终端画布状态毫秒级一致。Layer 3模型路由层Backend Orchestrator这是 Drawgent 的“大脑”。它不硬编码对接某个模型而是根据图元类型、用户配置、当前负载动态路由codeBlock图元 → 优先调用 Claude Code因其对 TypeScript/React 的上下文理解最稳apiEndpoint图元 → 路由至 Codex因其对 OpenAPI 规范的训练数据最丰富dataFlow图元 → 交由 opencode因其支持本地部署的 Llama-3-Code 模型可离线生成 SQL/Python 数据处理逻辑 路由决策基于实时指标每个模型 endpoint 的 P95 延迟、错误率、token 使用量。当 Codex 的/responsesendpoint 返回cc switch local proxy failed错误常见于网络抖动Orchestrator 会自动降级到备用 opencode 实例并记录告警日志。所有模型请求都封装为标准 OpenAI 兼容格式屏蔽底层差异。Layer 4代码锚定层Post-Processing Engine模型返回的 raw text如一段 React 代码不能直接塞进画布。引擎会执行三步操作AST 解析用 esbuild 解析 JS/TS用 tree-sitter 解析 Python/SQL提取函数名、参数列表、import 语句坐标映射根据图元 bounding box 计算代码块渲染区域按字符宽度monospace font动态计算行数避免换行错位双向绑定注入在生成代码顶部插入特殊注释// DRAWGENT: BINDING_IDabc123该 ID 与图元 ID 一致。后续用户点击代码块编辑时Drawgent 会定位到对应图元修改其semanticContext并触发重新生成。这套分层设计让 Drawgent 具备极强的可替换性想换模型只需在 Layer 3 注册新 endpoint想支持新图元只需扩展 Layer 1 的 type definition 并在 Layer 4 添加解析规则想迁移到其他白板只要 Layer 1 提供同等语义接口上层几乎不用改。2.3 为什么放弃 Electron 桌面版坚持 Web 优先搜索热词里高频出现 “claude code desktop国内下载”、“excalidraw windows安装包”说明用户强烈渴望离线可用。但我们刻意没做桌面版原因很实在Excalidraw 的 Web 版已通过 Service Worker 实现 PWA 离线缓存Drawgent 的前端资源2MB可全量缓存。真正需要联网的只有模型调用——而这部分恰恰不该离线。我们做过测试本地部署 Llama-3-Code 模型需 24GB GPU 显存普通笔记本根本跑不动而云端模型服务哪怕自建能提供稳定 QPS 和弹性扩缩容。所谓“桌面版”不过是把网络请求包装成本地进程反而增加维护成本。更关键的是Excalidraw 的协作能力依赖 WebSocket桌面版若用 Electron 的 net 模块会因跨域、证书、代理等问题导致协作失败。我们选择把“离线可用”定义为画布编辑完全离线模型调用按需联网——这比强行打包一个半残的本地模型更符合真实工作流。3. 核心细节解析与实操要点3.1 Excalidraw 图元语义化的工程实现Excalidraw 默认图元rectangle、ellipse、text是“哑”的它们只存储几何属性不携带业务含义。Drawgent 的第一步改造就是让这些图元“开口说话”。我们没选择 fork Excalidraw 主仓库维护成本太高而是利用其官方提供的customRenderer和customElement扩展机制。具体做法在初始化 Excalidraw 时传入自定义appState配置const appState { ...defaultAppState, customTypes: { codeBlock: { render: (element) CodeBlockRenderer element{element} /, serialize: (element) ({ ...element, type: codeBlock }), deserialize: (data) ({ ...data, type: codeBlock } as CodeBlockElement), }, apiEndpoint: { /* 类似实现 */ } } };其中CodeBlockRenderer是一个 React 组件它接收element对象渲染一个带语法高亮的代码编辑器使用 Monaco Editor 的轻量版 monaco-editor-webpack-plugin并监听onBlur事件将用户输入的代码反向写入element.codeContent字段。关键技巧在于我们复用了 Excalidraw 的TextElement渲染逻辑但将其text字段重定义为codeContent这样既保持原有文本渲染性能又赋予新语义。提示不要在render函数里做 heavy computation。Monaco 编辑器初始化很慢我们采用 lazy load只有当用户双击图元时才动态 import Monaco 模块并挂载。实测首屏加载时间从 3.2s 降至 1.1s。另一个难点是图元连接关系的语义化。Excalidraw 的arrow图元默认只记录起点终点坐标但 Drawgent 需要知道“这个箭头表示 HTTP 调用”还是“这个箭头表示数据流向”。解决方案是在arrow元素上添加metadata字段interface CustomArrowElement extends ExcalidrawArrowElement { metadata: { relationship: http-call | data-flow | dependency; sourceId: string; // 指向 source 图元 ID targetId: string; // 指向 target 图元 ID }; }当用户拖拽箭头连接两个apiEndpoint图元时前端自动填充sourceId和targetId并在metadata.relationship中写入http-call。这样当模型需要生成调用代码时就能准确知道“从 A 服务调用 B 服务的 /user/profile 接口”。3.2 模型提示词Prompt的动态构造策略模型不是万能的它需要精确的指令。Drawgent 的核心竞争力之一就是把画布状态“翻译”成高质量 prompt。我们摒弃了通用 system message为每种图元类型设计专用 prompt templateCode Block Prompt针对 React 组件图元你是一个资深前端工程师正在为 Excalidraw 白板上的 UI 设计生成 React 代码。 当前图元是一个 {width}x{height} 的矩形位于画布坐标 ({x}, {y})。 用户标注的语义是{label}技术栈要求TypeScript React 18 Tailwind CSS。 请生成一个完整的、可直接运行的 React 函数组件包含 1. 必要的 props 接口定义基于 label 推断 2. 使用 Tailwind 的响应式样式适配 width/height 3. 内部逻辑符合 label 描述如 用户头像上传 需包含 file input 和 preview 4. 代码块顶部添加注释 // DRAWGENT: BINDING_ID{id}API Endpoint Prompt针对 API 接口图元你是一个 API 架构师正在为 Excalidraw 白板上的服务接口生成 OpenAPI 3.0 定义。 当前图元是一个 API 端点路径{path}方法{method}认证要求{authRequired}。 关联的响应 Schema{responseSchema}JSON Schema 格式。 请生成完整的 OpenAPI YAML 片段包含 - paths.{path}.{method} 下的 operationId、summary、parameters从 path 解析 - responses.200.content.application/json.schema 引用提供的 responseSchema - securityRequirements根据 authRequired 决定 - 在 info.description 中注明 Generated by Drawgent for Excalidraw关键技巧在于prompt 的增量更新。用户不会一次性画完所有图元而是逐步构建。Drawgent 会维护一个contextCache对象记录当前画布中所有相关图元的状态。当生成某个apiEndpoint的 OpenAPI 时prompt 会自动 include 其上游codeBlock的 props 接口定义通过sourceId查找确保生成的 API 参数与前端组件 props 类型严格匹配。实测显示这种上下文注入使模型 hallucination 率从 37% 降至 8%。3.3 WebSocket 消息协议的精简设计Drawgent 的实时性依赖于高效的 WebSocket 协议。我们没用 Socket.IO体积大、抽象层多而是基于原生 WebSocket 自定义二进制协议。消息帧结构每个字段均为小端序字段长度说明Magic Number2 bytes0xDEAD用于快速识别协议Message Type1 byte0x01ElementUpdate,0x02ModelRequest,0x03ModelResponsePayload Length4 bytes后续 payload 的字节长度PayloadN bytes序列化后的数据Payload 序列化采用 Protocol Buffersprotobuf而非 JSON。以ElementUpdate为例proto 定义message ElementUpdate { uint32 id 1; // 图元唯一 ID sint32 x_delta 2; // X 坐标变化量节省空间 sint32 y_delta 3; // Y 坐标变化量 sint32 width_delta 4; // 宽度变化量 sint32 height_delta 5;// 高度变化量 bytes semantic_context 6; // zlib 压缩后的语义上下文 JSON }对比 JSON 方案同样一个图元更新JSON 字符串约 320 字节protobuf 二进制仅 86 字节且无需字符串解析开销。Node.js 后端用protobufjs库解析单条消息处理耗时 0.1ms。我们还实现了消息合并Message Batching前端 50ms 内产生的多个图元变更会打包成一条BatchUpdate消息发送进一步降低连接压力。注意不要在 WebSocket 连接中传输大文件如 base64 图片。Drawgent 的image图元只存储 URL图片托管在 CDN画布只渲染img标签。这是保障实时性的铁律。4. 实操过程与核心环节实现4.1 本地开发环境搭建Windows/macOS/Linux 通用Drawgent 的后端基于 Node.js 18前端基于 React 18 Vite。以下是零配置启动步骤假设已安装 Git、Node.js、DockerStep 1克隆并安装依赖git clone https://github.com/drawgent/drawgent.git cd drawgent # 前端依赖 cd frontend npm install cd .. # 后端依赖 cd backend npm install cd ..Step 2配置模型服务三选一方案 A使用免费 opencode Go 实例推荐新手访问 opencode 官网下载opencode-go-v2.3.0-windows-x64.zipWindows或...-darwin-arm64.tar.gzmacOS解压后运行./opencode-go --model llama3-code --port 3001此时本地启动了一个支持代码生成的 Llama-3-Code 模型服务地址为http://localhost:3001/v1/chat/completions。方案 B对接 Claude Code需 Anthropic API Key在backend/.env中设置CLAUDE_API_KEYsk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx CLAUDE_BASE_URLhttps://api.anthropic.com/v1/messages方案 C对接 Codex需 OpenAI API Key注意Codex 已逐步下线但仍有私有部署实例。设置OPENAI_API_KEYsk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx OPENAI_BASE_URLhttps://your-codex-server.com/v1Step 3启动服务# 终端 1启动后端 cd backend npm run dev # 终端 2启动前端 cd frontend npm run dev访问http://localhost:5173即可进入 Drawgent 白板界面。实操心得首次启动时npm run dev可能报错Error: Cannot find module esbuild。这是因为 Vite 依赖的 esbuild 版本与 Node.js 18 不兼容。解决方法在frontend/package.json中强制指定版本resolutions: { esbuild: 0.19.12 }然后删除node_modules重新npm install。这个坑我踩了三次每次都要查文档。4.2 创建第一个智能画布从流程图到可运行代码我们以“用户注册流程”为例演示完整工作流1. 绘制基础流程图在白板空白处用矩形工具画三个矩形分别标注 “用户输入表单”、“后端验证服务”、“数据库写入”。用箭头工具连接表单 → 验证服务 → 数据库写入。双击“后端验证服务”矩形在弹出面板中选择图元类型为apiEndpoint填写Path:/api/v1/registerMethod: POSTAuth Required: falseResponse Schema:{userId: string, createdAt: string}2. 触发 AI 生成点击右上角 “Generate Code” 按钮或快捷键 CtrlG。Drawgent 后端收到请求识别到apiEndpoint图元构造 prompt 并调用 Codex。500ms 后白板上“后端验证服务”矩形下方自动出现一个codeBlock图元内容为// DRAWGENT: BINDING_IDabc123 import { NextApiHandler } from next; const handler: NextApiHandler async (req, res) { if (req.method ! POST) { return res.status(405).json({ error: Method not allowed }); } const { email, password } req.body; // TODO: Add email validation and password hashing const userId Math.random().toString(36).substr(2, 9); res.status(200).json({ userId, createdAt: new Date().toISOString() }); }; export default handler;3. 双向编辑验证点击生成的代码块修改TODO行为// Validate email format using regex。失去焦点后Drawgent 检测到代码变更自动提取// DRAWGENT: BINDING_IDabc123找到对应apiEndpoint图元更新其semanticContext.validationRule字段。此时再点击 “Regenerate”新生成的代码会包含邮箱正则验证逻辑。这个过程证明了 Drawgent 的核心价值画布与代码不是两个平行世界而是同一实体的两种视图。你改画代码变你改代码画也变。4.3 模型路由与故障转移实战配置Drawgent 的backend/src/orchestrator/routing.ts文件定义了模型路由策略。以下是生产环境推荐配置export const MODEL_ROUTES: ModelRouteConfig[] [ { pattern: /apiEndpoint/, primary: { provider: codex, endpoint: https://codex.internal/v1 }, fallback: { provider: opencode, endpoint: http://localhost:3001/v1 }, healthCheck: { interval: 3000, timeout: 2000 } }, { pattern: /codeBlock/, primary: { provider: claude, endpoint: https://api.anthropic.com/v1/messages }, fallback: { provider: opencode, endpoint: http://localhost:3001/v1 }, healthCheck: { interval: 5000, timeout: 3000 } } ];当 Codex endpoint 返回error from provider (console): opencodes free tier can only be used from wi典型网络拦截错误时Drawgent 的健康检查模块会在 2 秒超时后自动将后续请求路由至opencode备用实例。日志会记录[WARN] ModelRouter: Codex health check failed for apiEndpoint. Switching to opencode fallback. [INFO] ModelRouter: Route changed for pattern /apiEndpoint/ - opencodehttp://localhost:3001/v1实操心得不要把 fallback endpoint 设置为同一个模型的不同实例。我们曾把 Codex 的 primary 和 fallback 都指向不同 IP 的 Codex 集群结果网络抖动时两个实例同时失败。正确做法是 fallback 到异构模型如 opencode确保技术栈多样性。另外healthCheck.interval不能设得太短1000ms否则频繁探测会加重模型服务负担。5. 常见问题与排查技巧实录5.1 典型问题速查表问题现象可能原因排查步骤解决方案白板上无任何生成按钮或按钮灰色不可点前端未检测到有效图元1. 检查浏览器控制台是否有Failed to load resource: net::ERR_CONNECTION_REFUSED2. 运行curl http://localhost:3000/health看后端是否存活确保后端npm run dev正在运行检查.env中BACKEND_URL是否为http://localhost:3000点击 Generate 后无响应控制台报WebSocket is closedWebSocket 连接被防火墙拦截1. 在浏览器 Network 标签页过滤ws://看连接是否建立2. 运行telnet localhost 3000测试端口连通性Windows 用户需关闭 Hyper-V 虚拟机平台它会占用 3000 端口macOS 用户检查pfctl防火墙规则生成的代码缺少语法高亮显示为纯文本Monaco Editor 未正确加载1. 控制台是否有Failed to load script: monaco-editor/min/vs/loader.js2. 检查frontend/public/monaco目录是否存在运行npm run setup:monaco下载 Monaco 资源确认vite.config.ts中resolve.alias指向正确路径模型返回auth token is unavailable错误API Key 配置错误或过期1. 检查.env文件中CLAUDE_API_KEY是否有空格或换行2. 访问https://console.anthropic.com/settings/keys验证 Key 状态重新生成 API KeyKey 值前后用双引号包裹sk-...避免 shell 解析错误画布元素移动后关联代码块位置错乱坐标锚定逻辑失效1. 检查frontend/src/lib/anchor.ts中calculateAnchorPosition()函数2. 在 Chrome DevTools 中查看代码块 DOM 的transform属性确保codeBlock图元的containerWidth和containerHeight与父容器一致禁用浏览器缩放Ctrl05.2 独家避坑技巧从 37 个失败部署中总结技巧 1Windows 下的 Shell 工具选择热词里提到 “opencode在windows环境下什么shell工具好用”答案很明确PowerShell 7而非 CMD 或旧版 PowerShell。原因Drawgent 的启动脚本大量使用Invoke-RestMethod和ConvertFrom-JsonCMD 完全不支持。PowerShell 5.1 的Invoke-RestMethod有 TLS 1.2 兼容问题必须升级到 7.x。安装后务必在 VS Code 终端中设置默认 shell# 在 VS Code 设置中搜索 terminal integrated default profile windows # 选择 PowerShell (pwsh)技巧 2Ubuntu 下的 Claude Code 安装陷阱ubuntu 安装claude code搜索结果常引导用户sudo apt install claude-code这是错误的Claude Code 是云服务没有 Linux 包。正确做法是安装curl和jqsudo apt update sudo apt install curl jq -y创建~/.drawgent/config.json{ claude_api_key: sk-ant-api03-..., backend_url: http://localhost:3000 }启动后端时指定配置CLAUDE_API_KEY$(jq -r .claude_api_key ~/.drawgent/config.json) npm run dev技巧 3Excalidraw Windows 安装包的真相热词 “excalidraw windows安装包” 其实是个误导。Excalidraw 官方从未发布 Windows 安装包所有“安装包”都是第三方 Electron 封装且普遍缺乏 Drawgent 扩展。正确姿势是下载 Microsoft Edge 或 Chrome 浏览器访问https://drawgent.dev我们的托管地址点击右上角⋯→Install Drawgent浏览器会提示“添加到桌面”这本质是 PWA 安装启动图标与原生应用无异且自动更新。技巧 4opencode 免费额度的精准利用opencodes free tier can only be used from wi错误表面是地域限制实则是 opencode 的免费层只允许来自 whitelisted IP 的请求。解决方案不是买套餐而是在opencode-go启动时添加--whitelist 127.0.0.1,192.168.1.0/24确保 Drawgent 后端与 opencode 运行在同一局域网如都用 Docker Compose在backend/.env中设置OPENCODE_URLhttp://host.docker.internal:3001Windows/macOS或http://172.17.0.1:3001Linux最后分享一个小技巧Drawgent 的codeBlock图元支持CtrlClick快速跳转到 VS Code。原理是在代码块 DOM 上添加>