本地 Agent 接入规划

本文档规划个人用户在访问线上画布网页时，如何连接自己电脑上的 Codex / Claude Code，并让 Agent 通过对话和工具调用操作当前画布。

目标

• 用户打开线上画布后，可以启动本机服务连接当前画布。
• 用户可以在 Codex 终端里通过 MCP 操作画布。
• 用户也可以在网页侧边栏里和本地 Codex / Claude Code 对话。
• 侧边栏需要展示普通消息、流式输出、工具调用、工具结果和错误提示。
• 线上服务不保存用户本地 Codex / Claude Code 登录态、API Key 或本地文件权限。

核心结论

浏览器页面不能直接启动本地进程，也不应该直接控制本机 Codex / Claude Code。推荐增加一个用户本机运行的 canvas-agent 服务：

线上画布网页 <-> 本机 canvas-agent <-> Codex / Claude Code
                         |
                         +-> MCP Server
                         +-> 画布连接

canvas-agent 是本地可信边界，负责启动或连接 Codex / Claude Code、暴露 MCP 工具、维护画布连接、转发侧边栏对话事件。

推荐目录

后续实现时建议在项目根目录新增独立 npm 包：

canvas-agent/
  package.json
  tsconfig.json
  src/
    index.ts
    config.ts
    http-server.ts
    canvas-session.ts
    mcp-server.ts
    agents.ts
    schemas.ts
    tools.ts
    types.ts

原因：

• 这是用户本机运行的 Node 服务，不属于线上服务端，也不属于纯前端页面。
• 后续可以发布成 npm 包，用户通过 npx 或全局安装启动。
• Codex SDK、Codex MCP、Claude SDK 都更适合在本地 Node 进程中接入。
• HTTP 路由使用 Express，MCP 协议层使用官方 @modelcontextprotocol/sdk，工具入参使用 zod，避免手写协议和松散 JSON。

本机启动方式

MVP 阶段优先提供 npx：

npx -y @basketikun/canvas-agent

在本仓库内开发调试时可直接运行：

cd canvas-agent
npm install
npm run build
node dist/index.js

启动后输出：

Infinite Canvas Agent
Local URL: http://127.0.0.1:17371
Connect token: xxxxxx

网页侧边栏填写或自动发现 http://127.0.0.1:17371 和 token 后连接本机服务。

前端需要增加的能力

前端不直接暴露 HTTP 接口给本机服务，优先由网页主动连接本机 Canvas Agent。当前 MVP 使用 SSE 接收本机事件，HTTP POST 上报画布状态和工具结果：

网页 -> http://127.0.0.1:17371/events?token=xxx
网页 -> http://127.0.0.1:17371/canvas/state?token=xxx
网页 -> http://127.0.0.1:17371/canvas/result?token=xxx

前端需要提供一个画布 Agent 控制层，内部调用现有 store / hook，不直接让外部操作 React 组件：

canvasAgent.getState()
canvasAgent.getSelection()
canvasAgent.applyOps(ops)
canvasAgent.focusNodes(ids)
canvasAgent.exportSnapshot()

建议先支持最小操作集：

• add_node：新增图片、文本、音频、视频、生成配置节点。
• update_node：更新节点位置、尺寸、内容和配置。
• delete_node：删除节点。
• connect_nodes：连接两个节点。
• set_viewport：移动或缩放当前视口。
• select_nodes：选中节点。

工具入参应使用画布业务 JSON，不使用模拟鼠标点击或屏幕坐标自动化。

MCP 读取画布状态时默认返回摘要，不直接把完整图片、视频、音频或超长 base64 内容塞给 Agent。

MCP 工具设计

canvas-agent 内置 MCP Server，让 Codex CLI 可以连接：

Codex CLI <-> canvas-agent MCP <-> 当前网页画布

建议首批 MCP 工具：

• canvas_get_state：读取当前画布节点、连线、选区和视口摘要。
• canvas_apply_ops：批量执行画布操作。
• canvas_get_selection：读取当前选中的节点。
• canvas_export_snapshot：导出当前画布快照，用于让 Agent 理解布局。
• canvas_create_text_node：快捷创建文本节点。
• canvas_create_image_prompt_flow：快捷创建提示词文本节点和图片生成配置节点。

用户本机 Codex 配置示例：

codex mcp add infinite-canvas -- npx -y @basketikun/canvas-agent mcp

本仓库调试时可使用，实际配置建议替换为本机绝对路径：

codex mcp add infinite-canvas -- node /path/to/infinite-canvas/canvas-agent/dist/index.js mcp

网页侧边栏助手另走 Canvas Agent 的对话通道。Canvas Agent 使用官方 @openai/codex CLI 的 codex app-server --stdio 启动并续用同一个 thread，启动时会注入 infinite-canvas MCP 配置并把 default_tools_approval_mode 设为 approve，避免 Codex 自己的 MCP 审批卡住侧边栏；真正修改画布前由网页侧边栏做二次确认。

侧边栏图片附件通过 HTTP 发送到本机 Canvas Agent，Canvas Agent 临时写入本机文件后作为 app-server localImage 输入传给 Codex；MVP 会在输入区提示附件体积，单次请求体限制为 30MB。

侧边栏助手设计

侧边栏助手连接 canvas-agent 后，由 Canvas Agent 选择 Agent Adapter：

Sidebar -> canvas-agent -> Codex app-server stdio
Sidebar -> canvas-agent -> Claude Code CLI / Claude Agent SDK

侧边栏优先展示 Codex app-server 原生结构化事件。前端只消费必要事件：

type AgentEvent =
  | { type: "thread.started"; thread_id: string }
  | { type: "turn.started" }
  | { type: "item.started" | "item.updated" | "item.completed"; item: ThreadItem }
  | { type: "turn.completed"; usage: Usage }
  | { type: "turn.failed"; error: { message: string } };

Claude 后续接入时再单独做 Claude Adapter；当前前端默认只展示 Codex。

Codex 接入优先级

优先使用官方 @openai/codex CLI 的 codex app-server --stdio。

• Codex app-server 会输出 item/agentMessage/delta；Canvas Agent 转成 item.updated 后，前端用同一条消息做真实流式渲染。
• 图片附件使用 app-server localImage 输入，不手写多模态协议。

参考：

• https://github.com/openai/codex/tree/main/codex-rs/app-server
• https://developers.openai.com/codex/codex-manual.md

Claude Code 接入优先级

Claude Code 侧当前 MVP 先调用本机 Claude Code CLI 的流式 JSON 输出，由 canvas-agent 统一转换事件和工具调用；后续可升级为 Claude Agent SDK。

如果希望 Claude Code 也能操作当前画布，需要给 Claude Code 配置同一个 MCP：

claude mcp add --scope user --transport stdio infinite-canvas -- npx -y @basketikun/canvas-agent mcp

Canvas Agent 调用 Claude Code 时默认允许 mcp__infinite-canvas__*，避免 print 模式被工具审批卡住；真正修改画布仍由网页侧边栏确认。

参考：

• https://docs.anthropic.com/en/docs/claude-code/sdk
• https://code.claude.com/docs/en/agent-sdk/typescript

安全边界

• Canvas Agent 默认只监听 127.0.0.1。
• Canvas Agent 启动时生成 token，网页连接必须携带 token。
• Canvas Agent 只接受允许的 Origin，默认允许用户当前打开的画布域名。
• 画布操作默认先在侧边栏展示工具调用，canvas_apply_ops 默认需要用户确认后执行，并保留最近一次工具操作撤销入口。
• 不把 Codex / Claude 登录态、API Key、用户本地文件路径上传到线上服务。
• 线上网页只保存 Canvas Agent 地址和必要偏好，不保存本地密钥。

实现阶段

第一阶段：Codex 终端操作画布

1. 新增 canvas-agent/ npm 包。
2. Canvas Agent 提供 SSE/HTTP 连接，网页连接并注册当前画布。
3. 前端新增 canvasAgent 控制层。
4. Canvas Agent 内置 MCP Server。
5. Codex 通过 MCP 调用 canvas_get_state 和 canvas_apply_ops。

第二阶段：网页侧边栏连接 Codex

1. 前端新增本地 Agent 侧边栏。
2. Canvas Agent 通过官方 @openai/codex CLI 的 codex app-server --stdio 接入 Codex，复用同一个 thread，注入 infinite-canvas MCP，并展示结构化事件流。
3. 运行日志只保留关键 Codex 事件，避免把流式中间更新刷满日志。
4. 侧边栏展示消息流、工具调用、工具结果、错误和图片附件大小提示。

第三阶段：接入 Claude Code

1. Canvas Agent 新增 Claude Code CLI Adapter。
2. 统一 Claude Code 的消息和工具调用事件。
3. 前端侧边栏增加 Agent 类型选择。

第四阶段：体验完善

1. 增加本机连接状态、重连和 token 更新。
2. 优化工具调用确认、撤销和批量工具队列体验。
3. 增加常用画布动作模板。
4. 增加 npm 发布和用户安装文档。

MVP 验收标准

• 用户运行 npx -y @basketikun/canvas-agent 后，线上画布能显示已连接。
• 用户在 Codex CLI 中可以创建文本节点、移动节点、连接节点。
• 网页侧边栏能发送一条消息给本地 Codex，并展示流式回复。
• 网页侧边栏默认只展示本地 Codex，并展示结构化回复。
• 侧边栏能展示一次 canvas_apply_ops 工具调用和结果。
• 断开 Canvas Agent 后，网页能显示清晰的本机连接失败提示。