@xiaohe-store/canvas-agent

v0.10.15

Published

20 days ago

本地 Canvas Agent 用来连接小禾画布网页和用户电脑上的 Codex / Claude Code。本地开发时优先连接 `http://localhost:3000`，不需要先使用线上站点。

0High
0Medium
0Low

xiaoheai

Xiaohe Canvas Agent

本地 Canvas Agent 用来连接小禾画布网页和用户电脑上的 Codex / Claude Code。本地开发时优先连接 http://localhost:3000，不需要先使用线上站点。

快速安装（推荐）

在 Codex 终端运行：

codex mcp add xiaohe-canvas -- npx -y @xiaohe-store/canvas-agent mcp

安装后在 Codex 对话中输入：

打开小禾画布

启动

npx -y @xiaohe-store/canvas-agent

需要排查连接、线程、Codex app-server 或工具调用问题时，可开启 Debug 模式：

npx -y @xiaohe-store/canvas-agent --debug

Debug 日志会以 [DEBUG][HH:mm:ss] 等传统格式输出到终端，并按启动日期保存到 ~/.xiaohe-canvas/logs/canvas-agent-YYYY-MM-DD.log。终端日志带级别颜色，文件日志为纯文本；日志包含 HTTP、SSE、线程、turn、Codex app-server 和工具调用事件，token 与图片 Data URL 会自动隐藏。

本仓库开发时也可以直接运行：

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

启动后会输出本机地址和 token：

Local URL: http://127.0.0.1:17371
Connect token: xxxxxx

在画布右上角点击 Agent，填入地址和 token 后连接。

Codex app 插件会读取启动输出里的 Local URL 和 Connect token，并直接打开画布网页地址；Canvas Agent 不负责生成画布打开 URL。

Canvas Agent 默认只监听 127.0.0.1。网页第一次带正确 token 连接后，Canvas Agent 会记录该网页 Origin；之后其他 Origin 不能复用这个本地 Agent，除非用户清除 ~/.xiaohe-canvas/canvas-agent.json 里的 origins。

发布

canvas-agent 使用自己的 package.json 版本号，不跟仓库根目录 VERSION 绑定。推送到 main 后，GitHub Actions 会检查 npm 上是否已经存在当前包版本；不存在时才发布 @xiaohe-store/canvas-agent。

发布前需要在 GitHub 仓库 Secrets 中配置 NPM_TOKEN。

Codex MCP

如果希望 Codex 终端能直接操作画布，需要先把 Canvas Agent 注册为 Codex MCP。

直接运行 npx -y @xiaohe-store/canvas-agent 只启动本地 Agent 服务，不会安装 MCP，也不会增加 Codex 工具上下文。只有安装 Codex app 插件，或手动执行 codex mcp add 后，xiaohe-canvas 工具才会进入 Codex 上下文；由于工具较多，不使用时建议移除。

通过插件安装时移除插件：

codex plugin remove xiaohe-canvas

手动添加 MCP 时移除 MCP：

codex mcp remove xiaohe-canvas

Codex app 插件

仓库内提供了 Codex app 插件：plugins/xiaohe-canvas。在 Codex app 中添加本仓库的 marketplace 后，可以安装「小禾画布」插件；插件会注册同一个 xiaohe-canvas MCP，并带上画布操作说明。

添加本地 marketplace 时建议使用仓库绝对路径，避免 Codex 从其他工作目录解析失败：

cd /path/to/xiaohe-canvas
codex plugin marketplace add "$(pwd)"
codex plugin add xiaohe-canvas@xiaohe-canvas-local

插件默认通过 npm 启动 MCP；这个命令只提供 MCP 工具，不会把 MCP 写入全局配置，也不会在退出时自动卸载：

npx -y @xiaohe-store/canvas-agent mcp

使用时可以直接在 Codex 里说"打开小禾画布"，插件会启动本地 Agent，读取 Local URL 和 Connect token，然后在右侧打开 https://www.xiaohe.store/canvas 并自动新建、连接画布；只有明确要求使用本地项目时才会启动本地前端。

Canvas Agent 启动后，给 Codex 添加 MCP：

codex mcp add xiaohe-canvas -- npx -y @xiaohe-store/canvas-agent mcp

本仓库开发时可以改成，实际使用建议替换为本机绝对路径：

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

Canvas Agent 源码使用 TypeScript 编写，MCP 协议层使用官方 @modelcontextprotocol/sdk，工具入参使用 zod 描述。

如果希望终端里的 Codex 不被 MCP 审批卡住，可以在 ~/.codex/config.toml 里给这个 MCP 设置自动放行：

[mcp_servers.xiaohe-canvas]
command = "npx"
args = ["-y", "@xiaohe-store/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 示例：

{
  "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，启动时会注入 xiaohe-canvas MCP 配置并自动放行 MCP 审批，真正执行画布修改前仍由网页侧边栏二次确认。

侧边栏会展示 Codex 返回的 thread.started、turn.started、item.*、turn.completed 等结构化事件；Canvas Agent 会合并短时间内的回复、思考摘要和命令输出增量，网页使用同一条消息持续更新，并把任务进度、计划、搜索、文件修改与工具操作整理为中文过程时间线。

侧边栏上传或粘贴的图片会先发到本地 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 从不同目录启动时找不到配置：

claude mcp add --scope user --transport stdio xiaohe-canvas -- npx -y @xiaohe-store/canvas-agent mcp

本仓库开发时可以改成：

claude mcp add --scope user --transport stdio xiaohe-canvas -- node /path/to/xiaohe-canvas/canvas-agent/dist/index.js mcp

Canvas Agent 调用 Claude Code 时会默认带上 --allowedTools mcp__xiaohe-canvas__*，画布写操作仍由网页侧边栏确认。

OpenAI 兼容模式

Canvas Agent 支持对接 OpenAI 兼容的 API 服务，例如 AIClient2API。AIClient2API 可以将 Kiro、Codex、Gemini CLI 等客户端 AI 转换为 OpenAI 兼容的 API 接口，让你可以使用这些模型来操作画布。

配置

通过 HTTP API 配置 OpenAI 兼容后端：

# 查看当前后端配置
curl http://127.0.0.1:17371/agent/backend?token=YOUR_TOKEN

# 切换到 OpenAI 兼容模式并配置
curl -X POST http://127.0.0.1:17371/agent/backend?token=YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "backend": "openai-compatible",
    "openaiCompatible": {
      "baseUrl": "http://localhost:8080",
      "apiKey": "your-api-key",
      "model": "kiro"
    }
  }'

# 切换回 Codex 模式
curl -X POST http://127.0.0.1:17371/agent/backend?token=YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"backend": "codex"}'

配置会保存到 ~/.xiaohe-canvas/canvas-agent.json，下次启动时自动读取。

使用

配置完成后，通过 /agent/openai/turn 发送消息：

curl -X POST http://127.0.0.1:17371/agent/openai/turn?token=YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your-client-id",
    "prompt": "在画布上创建一个文本节点，内容是 Hello World",
    "threadId": "",
    "systemPrompt": ""
  }'

对接 AIClient2API

部署 AIClient2API 服务
配置 Canvas Agent：
- baseUrl: AIClient2API 服务地址，例如 http://localhost:8080
- apiKey: AIClient2API 的 API Key
- model: 要使用的模型名称，例如 kiro、codex、gemini-cli 等

API 端点

| 端点 | 方法 | 说明 | |------|------|------| | /agent/backend | GET | 获取当前后端配置 | | /agent/backend | POST | 更新后端配置 | | /agent/openai/threads | GET | 列出所有对话 | | /agent/openai/threads/:threadId/clear | POST | 清除指定对话历史 | | /agent/openai/turn | POST | 发送消息 | | /agent/openai/interrupt | POST | 中断当前任务 |

注意事项

OpenAI 兼容模式与 Codex 模式相互独立，可以随时切换
对话历史保存在内存中，重启 Agent 后会丢失
支持 function calling / tool calling，会自动调用画布工具
默认最多执行 20 轮工具调用，防止无限循环

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme