drawgent：你在实时 Excalidraw 画布上的编码代理#
drawgent 将你自己的 Claude Code、Codex 或 opencode（你自己的安装、登录、配置和
仓库）连接到一个 Excalidraw 白板。在聊天面板中请求生成图表，或者在你想修改的绘图部分旁边
写下 AGENT: …。代理会查看画布（截图 +
场景），实时编辑它，检查结果，并将该注释标记为 DONE
。
工作原理#
快速开始#
前提条件：已安装并登录 claude
、codex
或 opencode
中的任意一个。Claude 和
Codex 桥接还需要 Node.js ≥ 18（npm）。
drawgent setup claude # 每个 agent 执行一次：claude | codex | opencode
cd ~/my-repo
drawgent up # 在该仓库中新建 agent 会话，并在浏览器中打开画布
drawgent up --attach # 或者：从正在运行的会话中选一个，并将画布连接到它
演示#
drawgent setup <agent>
检查所有内容一次，当缺少某些东西时，会以确切的修复方法失败，并写入
~/.config/drawgent/config.toml
：
-代理 CLI。你的claude
/codex
/opencode
在 PATH 上。 -登录。claude auth status
、codex login status
或opencode auth list
。 -ACP 桥接。- opencode 本身支持 ACP（
opencode acp
）。 - Claude Code 和 Codex 使用官方 ACP 适配器。它们被一次性安装到
~/.cache/drawgent/adapters
（约 60 MB），不包含它们捆绑的代理二进制文件，并指向你的CLI（CLAUDE_CODE_EXECUTABLE
、CODEX_PATH
）。 - 然后设置会验证 ACP 握手。
- opencode 本身支持 ACP（
-附加会话的画布工具。只有 Codex 需要更改：
codex mcp add drawgent -- drawgent mcp
。Claude 和 opencode 在附加时获得这些工具。 -用于渲染器的无头 Chrome。如果你有 Chrome/Chromium，设置会使用它。否则它会建议：- 下载
Chrome Headless Shell（Chrome for Testing，约 120 MB，无需 sudo）到~/.cache/drawgent/chrome
，并准确告诉你缺少哪些系统库（如果有的话）； - 使用你的包管理器安装 Chromium（
apt
、snap
、dnf
、pacman
、zypper
、apk
、brew
或nix
，无需 sudo）。
非交互式：
--chrome download | system | /path/to/chrome
。 - 下载
drawgent up
在该代理的设置成功之前拒绝启动，或者如果设置记录的内容消失了。
drawgent up
在当前目录（工作区）中运行：
- 在
127.0.0.1:7300
上启动编辑器 + API（如果被占用则使用下一个空闲端口）； - 通过 ACP 启动你的代理的新会话，在工作区中工作；
- 打开你的浏览器。在无头机器上，它会打印
ssh -L
命令。
实时场景及其同步状态保存在 .drawgent/scene.json
中，该文件会自动被 git 忽略。
将图表保留在仓库中：--diagram
drawgent up --diagram docs/architecture.excalidraw # remembered for this workspace
写入的内容：一个标准的 .excalidraw 文件（可在 excalidraw.com 上打开），与画布保持同步。它只保存当前绘图（不含已删除元素、不含激光轨迹），经过美化打印且不包含每次编辑的同步字段，因此差异清晰，且仅在绘图变化时重写。像提交其他源文件一样提交它。来自 git 的更改：如果文件在 drawgent 之外发生变化（git pull、检出、手动编辑），以文件为准。画布实时更新，包括删除，启动时磁盘上已有的文件也会被应用。无法解析的文件（例如合并冲突标记）会在聊天面板中报告，并在修复前被忽略。选择文件：工作区根目录下的 drawgent.excalidraw 会被自动使用，因此全新克隆无需任何标志。房间：--diagram 不能与 --room 组合使用，此时绘图由 excalidraw.com 持有。
drawgent up --attach [id]
将画布连接到您已运行的会话。不带 id 时，它会列出找到的会话（当前目录优先）并让您选择一个：
| agent | discovery | how the canvas reaches it |
|---|---|---|
| Claude Code | claude agents --json（交互式和后台会话） |
|
| fork：一个携带完整对话的新会话，由 drawgent 通过 ACP 驱动。您的终端会话不受影响 | ||
| opencode | 本地监听的 opencode 服务器：使用 opencode --port 4096（或 opencode serve）启动 TUI |
|
| live：消息进入您正在运行的会话（您在 TUI 中看到它们）；drawgent 在运行时将其 MCP 工具添加到该服务器；您在 TUI 中输入的回复、工具调用和提示会镜像到聊天面板 | ||
| Codex | ~/.codex/sessions 中的会话 |
|
live：codex queue --thread <id>；回复从会话的 rollout 文件镜像。该会话需要 drawgent MCP（由 setup 注册，在 Codex 启动时加载） |
使用画布#
聊天面板（右侧）：发送请求，观看回复和工具调用流式传入，批准权限提示，按 Stop 取消一轮。在画布上：在形状旁边或内部写一个以 AGENT: 开头的文本，或从便签画一个箭头指向形状。停止输入约 2.5 秒后触发，附带其位置、指向的对象以及附近的内容。agent 将其解析为一个绿色的 DONE: … 便签。将其编辑回 AGENT: 可再次发送。激光区域：选择 Excalidraw 的激光（K）并在图表的一部分上画圈或涂鸦。轨迹作为红色轮廓保留在画布上，聊天面板打开并准备好接收您的指令，带有一个列出区域下内容的标签（🔴 Laser zone · API, Redis ×）。您的下一条消息将与区域（边界和覆盖的元素）一起发送给 agent，agent 完成后轨迹消失。彼此间隔 4 秒内的笔画形成一个区域；× 丢弃它。- 提示会排队并一次运行一个。已处理过的排队便签会被跳过。
excalidraw.com 房间#
drawgent up --room 'https://excalidraw.com/#room=<id>,<key>'
- drawgent 作为协作者加入房间（
🤖 Agent
，其光标会跟随它的编辑）。人类可以继续使用 excalidraw.com：他们的AGENT:
笔记会传达到你的 agent，而它的编辑也会实时显示在那里。 - 流量使用房间密钥进行端到端加密。空房间从 excalidraw 的 Firestore 存储加载并保存到其中。
- 本地编辑器镜像该房间，并且仍然保留聊天面板。
其他命令#
drawgent mcp
：带有画布工具的 stdio MCP 服务器。Agent 启动它；它会自行找到正在运行的drawgent up
。drawgent serve
：带有显式 agent 的低层服务器（按设置使用--agent claude,codex,opencode
，或对任意 ACP agent 使用name=command
）；用于脚本和容器。-up
/serve
的选项：--port
、--room
、--token
（API bearer + URL 中的?token=
）、--permissions canvas|ask|all
（默认canvas
：绘图工具自动批准，其他任何操作都在聊天面板中询问）、--data
、--settle-ms
。
可选：Docker#
docker compose up --build
运行一个画布服务器（drawgent + Chromium，无 agent），例如用于
在服务器上托管共享画布或房间桥接。Agent 从不捆绑：它们始终
使用你自己的设置运行。
从源码构建#
npm ci && npm run build # editor + renderer pages -> dist/ (embedded into the binary)
cargo install --path . # or: cargo build --release
发布构建（nix develop -c make …
提供工具链，或 rustup + cargo-zigbuild）：
| 命令 | 输出 |
|---|---|
make musl / make dist |
|
静态 Linux x86_64 二进制文件 / tarball（ARM 使用 MUSL_TARGET=aarch64-unknown-linux-musl） |
|
make darwin / make dist-darwin |
|
| macOS 通用二进制文件（Intel + Apple Silicon，macOS ≥ 13）/ tarball |
macOS 构建是如何完成的：它是在 Linux 上使用 zig 交叉构建的，不依赖 Apple SDK（drawgent 仅链接libSystem
、libiconv
和libcharset
）。签名：arm64 切片由链接器进行 ad-hoc 签名。它未经公证，因此下载后请运行一次xattr -d com.apple.quarantine drawgent
。状态：尚未在真实 Mac 上测试。小型机器：使用JOBS=1
。有一个依赖项（chromiumoxide_cdp
）编译时需要大量内存。
Agent 工具（MCP）#
get_scene
、get_screenshot
（视觉；使用 element_ids
缩放）、add_elements
（Excalidraw
骨架；箭头按 id 绑定并沿边缘到边缘路由）、add_mermaid
（自动布局）、update_elements
（标签跟随形状，绑定的箭头重新路由）、delete_elements
、clear_canvas
、list_instructions
、resolve_instruction
、set_status
。
API#
GET /api/health
· GET /api/scene
· GET /api/screenshot?ids=&padding=&max=
·
POST|PATCH|DELETE /api/elements
· POST /api/mermaid
· POST /api/clear
·
GET /api/instructions
· POST /api/instructions/{id}/resolve
· POST /api/status
·
POST /api/chat {agent?, text}
· WS /ws
（浏览器同步 + 聊天事件）
测试#
cargo test # 分数索引、房间加密/分帧
node scripts/smoke.mjs [url] # 聊天轮次 + 针对运行中的 drawgent 的 AGENT: 备注
node scripts/e2e-browser.mjs [url] # 真实浏览器：聊天面板 + 在画布上输入的备注
node scripts/room-e2e.mjs # 全新的 excalidraw.com 房间 ↔ drawgent，双向
node scripts/laser-e2e.mjs # 激光区域 → 聊天 → 代理仅编辑该区域（需要设置 claude）
node scripts/diagram-e2e.mjs # --diagram 文件：干净输出，git pull / 手动编辑回流
布局#
src/
（Rust）：
main.rs
：CLI。setup.rs
、config.rs
、chrome.rs
：安装设置、配置、渲染器。attach.rs
：会话发现与选择。agents.rs
+acp.rs
：ACP 驱动（新建 / 分叉会话）。live.rs
：实时 opencode / Codex 驱动。hub.rs
：路由、笔记、聊天日志。scene.rs
：存储与编辑操作。renderer.rs
：基于 CDP 的 Chrome。mcp.rs
：MCP 服务器。room.rs
：excalidraw.com 客户端。fractional.rs
、geometry.rs
、el.rs
：辅助工具。
web/
：编辑器（main.jsx
、chat.jsx
、laser.js
）与渲染器页面（render.jsx
）。
限制#
- 渲染器需要 Chrome（原生渲染器已在计划中）。
- Claude 的“attach”是一种分叉，因为 Claude Code 没有公开的方式向正在运行的终端会话注入内容。
- Codex 实时 attach 已实现，但尚未针对已登录的 Codex 进行测试。
- 每个工作区一个场景（以及一个图表文件）。图像/文件不会同步。