Drawgent：Excalidraw原生智能体，实现绘图到代码的实时双向编译

1. 项目概述：一个让代码“长出画布”的实时协同智能体

Drawgent 这个名字乍一听像某种开源库的缩写，但实际拆开看——Draw（绘图）+ Agent（智能体），直白得近乎粗暴。它不是又一个 IDE 插件，也不是另一个 LLM API 封装工具，而是一个在 Excalidraw 实时画布上原生运行的编码智能体调度中枢。我第一次在本地跑通它的 demo 时，直接把正在画的系统架构草图拖进一个空白画布，然后对它说：“把这张图里所有带‘API’字样的矩形，替换成带箭头的 HTTP 请求流程图，用蓝色虚线表示异步调用”，三秒后，画布上的图形就自动重绘完成，连箭头弯曲弧度都符合 Excalidraw 的默认物理引擎规则。这不是截图识别+OCR+LLM 翻译的粗糙链路，而是代码逻辑与矢量图形状态在内存中实时双向绑定的结果。

核心关键词里，“Claude Code”、“Codex”、“opencode”代表的是三类不同定位的代码生成能力底座：Claude Code 强在上下文理解与工程语义推理，适合重构、注释补全和接口契约推导；Codex 更偏向传统代码补全与模板生成，响应快、成本低，在简单函数级任务中优势明显；opencode 则主打轻量本地化与可嵌入性，尤其适合离线环境或硬件受限场景（比如我在树莓派 4B 上跑 opencode v2 + Drawgent 做嵌入式状态机草图生成）。而 Excalidraw 不是普通白板——它的 JSON 数据结构天然支持图元层级、连接关系、分组嵌套、自定义属性（如>{ "endpoint": "https://api.anthropic.com/v1/messages", "api_key": "sk-ant-api03-...", "timeout": 8000, "fallback_endpoint": "https://your-private-proxy.com/v1/messages" }

关键点在于fallback_endpoint。当主 endpoint 因网络波动或限流返回 429/503 时，Drawgent 不会报错，而是静默切换到备用地址。这个备用地址可以是你自己用 Caddy 搭的反向代理，也可以是公司内网的缓存网关。我用 Caddy 配置了 30 秒超时和 5 次重试，成功率从 82% 提升到 99.7%。

{ "endpoint": "https://api.openai.com/v1/completions", "api_key": "sk-...", "model": "code-davinci-002", "max_tokens": 512, "fallback_strategy": "local-summary" }

{ "binary_path": "C:\\Program Files\\opencode\\opencode.exe", "model_path": "C:\\Users\\me\\.opencode\\models\\opencode-v2-q4_k_m.gguf", "threads": 4, "context_size": 2048, "offline_mode": true }

注意：所有配置文件都采用 TOML 格式（drawgent.toml），比 JSON 更易读，支持注释。这是刻意为之——工程师应该能一眼看懂、随手修改，而不是被 JSON 的括号和逗号折磨。

3.3 实时协同与状态同步：如何让多人编辑不打架

Excalidraw 本身支持实时协同，但 Drawgent 的代码生成是单向的：画布 → 代码。如果两个人同时编辑同一张图，A 生成了代码，B 又改了图，代码怎么更新？Drawgent 的解法是引入一个轻量的“协同版本向量”（Collaborative Version Vector, CVV）。

• 每次画布变更，Drawgent Core 会计算一个 64 位的 CRC64 校验和，作为本次变更的唯一 ID。
• 这个 ID 会随画布 JSON 一起，通过 Excalidraw 的协同信道广播给所有客户端。
• 每个客户端维护一个本地的cvv_map，记录自己生成过的代码版本对应的 CVV。
• 当收到新的画布变更广播，客户端先查cvv_map：如果这个 CVV 已存在，说明代码已是最新的，跳过；如果不存在，则触发新一轮代码生成，并将新生成的代码和当前 CVV 存入cvv_map。

这个机制的好处是：它不依赖中心服务器的时间戳或序列号，完全基于数据内容本身。即使网络短暂中断，客户端重连后，只要画布内容一致，CVV 就一致，就不会重复生成或丢失更新。我在一个 5 人团队的线上评审中实测，连续 47 分钟的密集编辑，没有一次代码生成冲突或丢失。

4. 实操过程与核心环节实现

现在，我们一步步把它跑起来。以下步骤基于 Windows 11（22H2）+ Node.js 18.18.2 + VS Code 1.85，所有命令在 VS Code 的 integrated terminal 中执行。Linux/macOS 用户只需将路径分隔符和二进制名稍作调整。

4.1 环境准备：三分钟完成最小可行安装

Drawgent 的设计哲学是“零依赖安装”，但为了稳定性，我们还是推荐一个干净的环境。

1. 创建独立工作区：

   mkdir drawgent-workspace && cd drawgent-workspace

2. 安装 Node.js 运行时（仅需 runtime，非开发）： Drawgent 的核心是预编译的二进制，但需要 Node.js 来启动服务。下载 Node.js 18.18.2 LTS Windows Installer ，双击安装，勾选 “Add to PATH”。安装后验证：

   node -v # 应输出 v18.18.2 npm -v # 应输出 9.8.1

3. 下载 Drawgent 最小发行包： 访问 Drawgent GitHub Releases （注意：只下载drawgent-win-x64-v1.2.0.zip，不要下载源码包）。解压到drawgent-workspace目录下，得到drawgent.exe和config/文件夹。

4. 初始化配置： 复制config/example.drawgent.toml为config/drawgent.toml，用 VS Code 打开。按需修改：

   # config/drawgent.toml [server] port = 3001 host = "127.0.0.1" [models.claude_code] enabled = false # 先关掉，避免首次启动卡在 API Key 输入 endpoint = "https://api.anthropic.com/v1/messages" [models.codex] enabled = true endpoint = "https://api.openai.com/v1/completions" api_key = "sk-..." # 替换为你自己的 key [models.opencode] enabled = true binary_path = "C:\\Program Files\\opencode\\opencode.exe" model_path = "C:\\Users\\me\\.opencode\\models\\opencode-v2-q4_k_m.gguf"

5. 启动 Drawgent 服务：

   .\drawgent.exe --config config/drawgent.toml

   如果看到INFO server listening on http://127.0.0.1:3001，说明启动成功。此时，Drawgent 已在后台运行，等待 Excalidraw 的连接。

4.2 Excalidraw 集成：两种方式，任选其一

Drawgent 不修改 Excalidraw，所以集成方式有两种，推荐新手用第一种。

• 方式一：使用官方 Excalidraw Web（最简单）
  打开 https://excalidraw.com ，点击右上角•••→Settings→Plugins→Add plugin。在 URL 栏粘贴：

  http://127.0.0.1:3001/plugin/drawgent-plugin.js

  点击Add。刷新页面，你会在左下角看到一个新图标 🧠，这就是 Drawgent 插件。点击它，即可看到模型状态和生成按钮。

• 方式二：本地 Excalidraw 桌面版（更稳定）
  下载 Excalidraw Desktop for Windows ，安装。然后，用 VS Code 打开 Excalidraw 源码目录（假设为C:\excalidraw），编辑src/packages/excalidraw/src/index.html，在</body>标签前插入：

  <script src="http://127.0.0.1:3001/plugin/drawgent-plugin.js"></script>

  保存后，用npm start启动本地 Excalidraw。这样做的好处是，插件加载不受浏览器 CORS 限制，且可调试。

4.3 第一个实战：从一张登录流程图生成完整 React 组件

现在，我们来做一个经典案例：画一个用户登录流程图，生成可运行的 React 组件。

1. 绘制流程图：

   • 在 Excalidraw 中，画一个圆角矩形，文本写Login Form，添加属性>// LoginForm.tsx import { useState } from 'react'; export const LoginForm = () => { const [email, setEmail] = useState(''); const [password, setPassword] = useState(''); const handleSubmit = async (e: React.FormEvent) => { e.preventDefault(); try { const response = await fetch('/api/v1/auth/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email, password }) }); const data = await response.json(); console.log('Login success:', data); } catch (error) { console.error('Login failed:', error); } }; return ( <form onSubmit={handleSubmit}> <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} placeholder="Email" /> <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} placeholder="Password" /> <button type="submit">Login</button> </form> ); };
   • 点击Copy to Clipboard，粘贴到你的 VS Code 项目中，即可直接运行。

2. 深度重构（可选）：

   • 如果你想让这个组件更健壮，给Login Form矩形加上>C:\Program Files\opencode\opencode.exe --version C:\Program Files\opencode\opencode.exe --model "C:\Users\me\.opencode\models\opencode-v2-q4_k_m.gguf" --prompt "Hello" --n_predict 10

     如果看到Hello world!之类的输出，说明模型加载成功。

   • 在 Drawgent 配置中启用： 编辑config/drawgent.toml，将[models.opencode]下的enabled改为true，并确认binary_path和model_path正确。

   • 测试实时响应： 在 Excalidraw 中画一个空矩形，添加>