它不是通用白板：画布中的图片既是素材，也是下一次生成或局部修改的输入。

安装

npx @finchtoys/minitools add finch-codex-canvas

安装后在 Finch Toolcase 启用 Codex 画布，再从左侧栏打开。首次使用前请确认本机已安装 Codex CLI，并已通过 codex login 完成 OAuth 登录。

核心能力

• 基于 Excalidraw 的无限平移、缩放、选择、分组、文字、箭头、图形和手绘标记
• 工具栏仅保留抓手、选择、矩形、椭圆、箭头、手绘、文字、图片和橡皮 9 项核心工具
• 直接调用本机已 OAuth 登录的 Codex CLI 及其内置 image_gen
• 选中 0–5 张画布图片作为参考图，一次生成 1–4 个独立候选版本
• 提交后立即在画布创建包含提示词、版本和实时阶段的目标占位卡；结果原位替换，底部输入区保持可用，可继续并发提交
• 任务与 1–4 个版本槽位由宿主持久管理；切换窗口或重建 App View 后会恢复占位卡，并补收离开期间完成的图片
• 可直接在目标图上写点位修改说明，也可用箭头、矩形、椭圆或手绘标记精确定位
• 自动把原图作为 Image 1、标注定位图作为 Image 2 发给 Codex，避免把红框和编号画进成品
• 生成结果自动放到来源图右侧，并用绑定箭头展示参考或修改关系；移动图片时连线会跟随
• 自有图片库分为“项目图片”和“生成历史”：可定位画布节点，也可把历史结果重新放回画布
• 顶部“导出图片”打开 Excalidraw 正式导出面板，可选背景、比例、PNG、SVG 或复制到剪贴板
• 图片库提供“快速导出”和“打开所在文件夹”，快速导出的成品统一保存到 ~/Downloads/Codex Canvas
• 同时提供左侧全屏 App View 与 Agent Session 右侧 Panel；两处读取同一张持久画布
• 注册统一 Agent 工具，可检查图片、生成新图、精确标注、基于定位图创建新版本并定位节点
• Agent 使用图片内部 0–1 归一化坐标创建真实可编辑的点位、矩形、椭圆、箭头和说明文字
• Agent 指令通过持久命令队列交付；面板未就绪或重建时不会丢失，且默认只新增、不删除或覆盖用户内容
• 自有中英双语帮助页，只展示 Codex 画布相关流程和快捷键，不链接 Excalidraw 外部页面
• 画布与生成历史索引通过 ctx.storage 自动保存，不依赖当前聊天 Session
• 中文 / English 与 Finch light/dark CSS 变量适配

使用方式

在 Agent 对话旁操作画布

启用小程序后，Agent 可调用统一的 Codex Canvas 工具：

• status：查看 Codex 状态、异步任务、待处理指令和可用于后续编辑的图片节点 ID
• inspect：把指定画布图片返回给视觉 Agent，供其判断标注坐标
• generate：提交 1–4 个新图版本，并自动在当前 Agent Session 右侧打开画布
• edit：通过图片节点 ID 和修改要求创建新版本；原图保持不变
• annotate：使用 0–1 图片相对坐标创建可见、可编辑的点位、矩形、椭圆、箭头和说明文字
• annotate_edit：先显示结构化标注，再生成红色编号定位图，并以 Image 1 原图 + Image 2 定位图创建新版本
• focus：打开右侧画布并定位指定图片

Agent 操作遵循追加式策略，不提供删除、覆盖或自动重排。右侧 Panel 适合对话时查看和批注，左侧 App View 继续用于全屏整理；一个视图保存后，其他已打开视图会接收最新场景。

生成新图

1. 在画布中选中需要作为参考的图片（可不选，最多 5 张）。
2. 在底部输入生成要求，选择比例和 1–4 个版本。
3. 点击 生成新图，或按 Cmd/Ctrl + Enter。画布会立即按最终尺寸放置任务卡，卡片固定显示提示词、版本、阶段和耗时。
4. 输入框会立即清空，可继续填写并提交下一条任务；不同批次互不阻塞，也不会重叠排布。
5. 每个版本由独立 Codex 任务生成，不会做成一张拼图；完成后图片原位替换任务卡，并分别连接来源图。

标注后修改

1. 只选中一张要修改的目标图，底部出现“修改目标 · 已锁定”。
2. 最快捷的方式是用文字工具直接点击图上的修改位置并输入说明。
3. 需要标记区域或把说明放到图外时，可画箭头、矩形、椭圆或手绘线，并在标记附近放文字。切换工具后目标图仍会保持锁定。
4. 底部输入框可补充整体要求，也可留空。
5. 点击 按标注修改。任务卡会先出现在原图右侧，输入区立即恢复使用。
6. 新版本完成后会在任务卡原位置替换显示；未标注区域会在请求中明确要求保持不变。

直接放在图上的文字会按所在位置转换成点位标注。箭头按无方向连线解析：结合两端与图片、说明文字的距离判断连接关系，不要求用户区分箭头头尾；两端都在图内时按整段连线覆盖的位置处理。图形覆盖区域同样会换算成相对坐标。随后工具渲染一张临时红色编号定位图，它只用于 Codex 理解空间位置，不会保存为画布节点。

图片库

• 点击画布右上角的 图片库。
• 项目图片会自动列出当前画布中的全部图片，无需右键“添加到素材库”；点击卡片可直接定位并选中对应节点。
• 生成历史列出最多 200 张 Codex 输出；点击“添加到画布”会创建一个新的画布图片节点。
• 选中画布图片后，右上角 导出图片会打开 Excalidraw 正式导出面板；项目图片与生成历史卡片中的 快速导出则直接写入 ~/Downloads/Codex Canvas。
• 图片固定存放在 Finch 为小程序分配的私有 storagePath，无需选择目录，移动项目文件也不会造成历史失效。索引只保存提示词、时间和私有文件路径等轻量元数据。

运行要求

• Finch 1.6.0 或兼容版本
• 本机已安装 Codex CLI
• 已执行 codex login 完成 OAuth 登录
• Codex CLI 能使用内置 image_gen 工具

本工具不会读取或使用 OPENAI_API_KEY；启动 Codex 子进程前会主动从环境中移除该变量。

架构

• src/index.ts：App View / App Panel Bridge、Agent 工具、图片检查、持久命令队列、场景与生成历史持久化、任务轮询和面板生命周期
• src/agent-commands.ts：Agent 命令与归一化标注校验
• src/agent-annotation-geometry.ts：图片相对坐标到 Excalidraw 场景坐标的转换
• src/codex-engine.ts：Codex 检测、OAuth 状态、后台任务、PNG 校验与超时治理
• src/document.ts：v2 Excalidraw 场景验证和容量限制
• src/task-layout.ts：异步任务卡尺寸、批次网格、避让布局和提示词折行
• src/task-registry.ts：宿主持久任务、版本状态与重连槽位校验
• src/web/App.tsx：画布 UI、并发任务节点、参考图选择、生成/编辑回环、自动保存
• src/web/annotations.ts：标注识别、相对坐标提示词、定位图渲染
• src/web/styles.css：Finch 主题适配与底部生成工作台

宿主与 App View 通过以下消息通信：

• 场景：canvas:ready / canvas:load / canvas:save / canvas:saved / canvas:error
• Codex：codex:status / codex:start / codex:sync / codex:resume / codex:progress / codex:result / codex:error；批量请求携带 count 与版本槽位，响应携带 variantIndex / variantCount
• 图片库：library:list / library:items / library:item / library:asset / library:error
• 导出：image:export / library:export / image:reveal / library:reveal / export:open-directory / export:done / export:error / export:revealed

Codex 任务以 detached 子进程运行，任务注册表保存在私有 storagePath。关闭或重建 App View 不会取消任务；再次打开时，页面通过任务快照恢复原坐标并补收待交付结果。

开发

npm install
npm run check

本地安装：

npx @finchtoys/minitools add .

然后在 Finch Toolcase 启用 Codex 画布，从左侧栏打开 App View。

限制

• 单画布最多 2,000 个元素、80 个二进制图片文件、64 MB 场景文档
• 单张传给 Codex 的输入图最多 30 MB；每次任务最多 5 张输入图
• 单个后台任务超时为 10 分钟；一次最多并行生成 4 个版本
• 标注识别目前基于几何邻近规则，不理解旋转图片或复杂嵌套语义
• 当前只有一个本地画布；左侧 App View 与右侧 Panel 共享它，但没有多人协作和多画布库
• 双视图同步采用保存后的场景广播；不建议在两个视图中同时持续拖拽编辑同一批节点
• Finch 整个进程退出后，已启动的 detached Codex 任务仍可继续；下次启动会从任务注册表恢复轮询，异常中断在启动前的槽位会标记失败

安全与隐私

• 图片和任务文件存放在 Finch 为本扩展分配的私有 storagePath
• Shell 仅用于启动明确找到的本机 Codex 可执行文件，参数通过 spawn(..., shell: false) 传递
• 仅接受 PNG/JPEG/WebP data URL 作为 Codex 输入，并校验数量和大小
• 结果必须通过 PNG 文件头校验后才回传前端
• 生产依赖审计：npm audit --omit=dev 为 0 vulnerabilities

开源参考

• Excalidraw 0.17.6（MIT）：画布底座
• AI-Canvas（MIT）：标注解析与版本回环设计参考
• canvas-codex（MIT）：Excalidraw + Codex 产品形态参考
• InvokeAI（Apache-2.0）：节点画布工作流参考

本项目没有采用 tldraw，避免其当前生产使用许可约束；也没有复用无明确许可证项目的代码。完整归属见 THIRD_PARTY_NOTICES.md。

License

MIT