# 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.

![真实浏览器中的画布与图片评论，图片为合成设计样例](docs/images/canvas-review.png)

## 功能

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

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

## 本地运行

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

```sh
npm ci
npm run check
npm start
```

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

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

## 安装到 Codex

```sh
npm run package:plugin
```

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

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

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

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

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

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

## 与 Codex 协作

可以这样请求：

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

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

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

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

## 目录

```text
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
```

[架构与并发策略](docs/architecture.md) · [数据与隐私](docs/privacy.md) · [第三方组件](docs/third-party.md) · [MIT License](LICENSE)