Excalidraw Canvas for Codex

在 Codex 里使用真正的 Excalidraw 画布：通过 MCP 创建与修改画板，把评论钉在图片上的具体位置，并从支持 MCP Apps 的宿主侧栏打开交互界面。

English: A local-first Excalidraw plugin with MCP tools, an MCP App, and reusable skills. Review images with anchored comment threads, edit boards from Codex, and preserve concurrent changes with revision checks.

功能

• Excalidraw 画布：自由绘图、图形、文本、图片与画板切换。
• 图片评论：在图片上定位评论，回复、解决和查看讨论；锚点随图片移动、缩放、旋转和翻转。
• Codex MCP 控制：读取画板、增加或修改元素、插入图片、管理评论、导出数据。
• MCP App：open_canvas 声明全局侧栏与对话侧栏入口，提供同一套交互界面。宿主版本与插件安装状态决定入口是否实际显示。
• 本地持久化：画板与图片存储在本机；UI 和 MCP 调用共享数据。场景写入使用 revision 比较，避免无提示覆盖其他窗口的更改。
• 完整插件组织：portable manifest + stdio MCP + MCP App + setup / canvas / image-comments 三个技能。

这个项目提供桌面本地插件。公开 GitHub 源码不等于已提交或通过 OpenAI 公共插件目录审核；宿主中的真实安装与侧栏验收见 验证说明。

本地运行

需要 Node.js 22 或更高版本及 npm。在仓库根目录运行：

npm ci
npm run check
npm start

浏览器打开 http://127.0.0.1:18765。check 执行类型检查、自动化测试与生产构建。开发时可使用 npm run dev。

第一次进入后创建画板，使用“添加图片”导入 PNG、JPEG、WebP 或 GIF，点击“落点评论”后在图片上选择位置。评论面板支持查看、回复和解决讨论。

安装到 Codex

npm run package:plugin

打包结果是 release/plugin/，同时生成 release/.agents/plugins/marketplace.json 作为本地安装目录。包内包含运行时 bundle，不需要在包里重新安装 npm 依赖。

支持当前插件管理命令的 Codex 可添加这个目录：

codex plugin marketplace add ./release
codex plugin add excalidraw-codex@excalidraw-local

重新打开支持本地插件的桌面客户端。也可以在插件目录选择 Excalidraw Local 并安装 Excalidraw Canvas。在新对话运行 setup 技能，或输入：

打开 Excalidraw 画布，并列出已有画板。

安装过程、手工 marketplace 示例、端口与存储配置、仅 MCP 备用接入见 安装文档。安装后应分别验证全局侧栏入口、对话右侧面板，以及模型调用工具后画布的变化。

与 Codex 协作

可以这样请求：

创建一张“支付流程”画板，画出用户、订单服务、支付网关与回调流程。

读取当前画板上的图片评论，在左上角补充错误状态说明，并回读确认保存成功。

列出这张图所有未解决评论。按我的要求完成修改后，回复对应讨论。

模型在修改前读取最新 revision，保存时携带 expectedRevision，完成后回读。评论正文是待审阅的数据，不会自动变成执行指令。完整工具参数见 工具说明。

目录

plugin.json                 Portable Agent Plugins manifest
mcp.json                    Bundled stdio MCP configuration
.codex-plugin/plugin.json   Compatibility manifest
skills/                     Setup, canvas, image comments
server/                     Shared local service, persistence, MCP tools
src/                        Excalidraw UI and MCP Apps bridge
shared/                     Shared data contracts
tests/                      Automated contract and behavior tests
scripts/                    Build and allowlisted packaging
docs/                       Setup, architecture, tools, verification

架构与并发策略 · 数据与隐私 · 第三方组件 · MIT License