feat(agent): implement local Canvas Agent with MCP integration and HTTP server

2026-08-06 01:14:36 +08:00 · 2026-06-14 18:27:44 +08:00
parent 8aa3fad684
commit e422285c59
27 changed files with 2388 additions and 7 deletions
@@ -0,0 +1,107 @@
+# Infinite Canvas Agent
+
+本地 Canvas Agent 用来连接线上画布网页和用户电脑上的 Codex / Claude Code。
+
+## 启动
+
+```bash
+npx -y canvas-agent
+```
+
+本仓库开发时也可以直接运行：
+
+```bash
+cd canvas-agent
+npm install
+npm run build
+node dist/index.js
+```
+
+启动后会输出本机地址和 token：
+
+```txt
+Local URL: http://127.0.0.1:17371
+Connect token: xxxxxx
+```
+
+在画布右上角点击 `Agent`，填入地址和 token 后连接。
+
+Canvas Agent 默认只监听 `127.0.0.1`。网页第一次带正确 token 连接后，Canvas Agent 会记录该网页 Origin；之后其他 Origin 不能复用这个本地 Agent，除非用户清理 `~/.infinite-canvas/canvas-agent.json` 里的 `origins`。
+
+## Codex MCP
+
+如果希望 Codex 终端能直接操作画布，需要先把 Canvas Agent 注册成 Codex MCP。
+
+Canvas Agent 启动后，给 Codex 添加 MCP：
+
+```bash
+codex mcp add infinite-canvas -- npx -y canvas-agent mcp
+```
+
+本仓库开发时可以改成，实际使用建议替换为本机绝对路径：
+
+```bash
+codex mcp add infinite-canvas -- node /path/to/infinite-canvas/canvas-agent/dist/index.js mcp
+```
+
+Canvas Agent 源码使用 TypeScript 编写，MCP 协议层使用官方 `@modelcontextprotocol/sdk`，工具入参使用 `zod` 描述。
+
+如果希望终端里的 Codex 不被 MCP 审批卡住，可以在 `~/.codex/config.toml` 里给这个 MCP 设置自动放行：
+
+```toml
+[mcp_servers.infinite-canvas]
+command = "npx"
+args = ["-y", "canvas-agent", "mcp"]
+default_tools_approval_mode = "approve"
+```
+
+可用工具：
+
+- `canvas_get_state`
+- `canvas_get_selection`
+- `canvas_export_snapshot`
+- `canvas_apply_ops`
+- `canvas_create_text_node`
+- `canvas_create_image_prompt_flow`
+
+`canvas_apply_ops` 示例：
+
+```json
+{
+  "ops": [
+    {
+      "type": "add_node",
+      "nodeType": "text",
+      "title": "标题",
+      "position": { "x": 0, "y": 0 },
+      "metadata": { "content": "文本内容" }
+    }
+  ]
+}
+```
+
+## 侧边栏 Codex
+
+本地面板会把提示词发送给 Canvas Agent。Canvas Agent 使用官方 `@openai/codex` CLI 的 `codex app-server --stdio` 启动并复用同一个 Codex thread，启动时会注入 `infinite-canvas` MCP 配置并自动放行 MCP 审批，真正执行画布修改前仍由网页侧边栏二次确认。
+
+侧边栏会展示 Codex 返回的 `thread.started`、`turn.started`、`item.*`、`turn.completed` 等结构化事件；收到 app-server 的 `item/agentMessage/delta` 时，Canvas Agent 会转成 `item.updated`，网页会用同一条消息做真实流式更新，并把工具细节收进运行日志。
+
+侧边栏上传或粘贴的图片会先发到本机 Canvas Agent，再由 Canvas Agent 临时写入本机文件并作为 app-server `localImage` 输入传给 Codex；前端会提示附件体积，单次请求体限制为 30MB。
+
+## Claude Code
+
+Claude Code Adapter 代码暂时保留，但当前网页侧边栏只开放 Codex。后续开放 Claude 入口时，Canvas Agent 会调用本机 `claude -p --output-format stream-json` 并把流式 JSON 事件转发到侧边栏。
+
+如果希望 Claude Code 也能操作画布，需要给 Claude Code 添加同一个 MCP。建议用 user scope，避免 Canvas Agent 从不同目录启动时找不到配置：
+
+```bash
+claude mcp add --scope user --transport stdio infinite-canvas -- npx -y canvas-agent mcp
+```
+
+本仓库开发时可以改成：
+
+```bash
+claude mcp add --scope user --transport stdio infinite-canvas -- node /path/to/infinite-canvas/canvas-agent/dist/index.js mcp
+```
+
+Canvas Agent 调用 Claude Code 时会默认带上 `--allowedTools mcp__infinite-canvas__*`，画布写操作仍由网页侧边栏确认。