# @dream-craft/canvas-agent 中文文档

规范地址：https://npmcn.com/package/%40dream-craft/canvas-agent/

版本：0\.7\.10
npm 元数据更新时间：2026-11-11T07:11:53.538Z
中文译文更新时间：2026-11-12T23:31:29.701Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dream-craft/canvas-agent
原文对照：https://npmcn.com/package/%40dream-craft/canvas-agent/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：710 kB，67 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：8 个
- 首次发布：2026-10-17T13:20:40.229Z
- 最新版本发布：2026-11-11T07:11:53.286Z
- 近 30 天下载量：3038（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

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

## 安装

```sh
npm install @dream-craft/canvas-agent
```

也可以使用：`pnpm add @dream-craft/canvas-agent`、`yarn add @dream-craft/canvas-agent`、`bun add @dream-craft/canvas-agent`

## README

# Infinite Canvas Agent

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

## 启动

```bash
npx -y @dream-craft/canvas-agent@latest
```

带上 `@latest` 是因为 npx 会缓存已下载的版本，不加就可能一直运行旧版本。

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

```bash
npx -y @dream-craft/canvas-agent@latest --debug
```

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

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

```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 后连接。

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

Canvas Agent 默认只监听 `127.0.0.1`。网页第一次带正确 token 连接后，Canvas Agent 会记录该网页 Origin 并只允许它复用；其他 Origin 不能复用这个本地 Agent，除非用户清理 `~/.infinite-canvas/canvas-agent.json` 里的 `origins`。诊断用的 `/health` 无论来源都只认 token。

MCP 模式（`canvas-agent mcp`）本身只是把工具调用转发到上面这个地址，不会启动服务。服务未运行、或该端口上的服务没有使用同一份 token 时，工具调用返回手动启动指引，MCP 不会自行拉起常驻进程。

## 发布

`canvas-agent` 使用自己的 `package.json` 版本号，不跟仓库根目录 `VERSION` 绑定。发布前先按仓库本地开发文档核对并提升包版本；npm 不允许覆盖已发布版本。发布由维护者手动执行：在 `canvas-agent` 目录确认已登录 npm（账号 `chaoyang2009918`）后运行：

```bash
npm publish
```

## Codex MCP

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

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

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

```bash
codex plugin remove infinite-canvas
```

手动添加 MCP 时移除 MCP：

```bash
codex mcp remove infinite-canvas
```

### Codex app 插件

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

插件和下面手动 `codex mcp add`、直接写 `~/.codex/config.toml` 注册的是**同名** server，只需要留一种。同时存在时 `config.toml` 会覆盖插件自带的 MCP 配置，插件 `.mcp.json` 里的超时和自动放行会静默失效。

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

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

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

```bash
npx -y @dream-craft/canvas-agent@latest mcp
```

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

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

```bash
codex mcp add infinite-canvas -- npx -y @dream-craft/canvas-agent@latest 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 CLI、没有安装上面的插件时，可以在 `~/.codex/config.toml` 里手动注册并自动放行（插件的 `.mcp.json` 已经带 `default_tools_approval_mode`，装了插件就不需要这段）：

```toml
[mcp_servers.infinite-canvas]
command = "npx"
args = ["-y", "@dream-craft/canvas-agent@latest", "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` 等结构化事件；Canvas Agent 会合并短时间内的回复、思考摘要和命令输出增量，网页使用同一条消息持续更新，并把任务进度、计划、搜索、文件修改与工具操作整理为中文过程时间线。

侧边栏上传或粘贴的图片会先在前端一律重编码为 WebP（长边 1536px、质量 0.85）再发到本机 Canvas Agent，由 Canvas Agent 临时写入本机文件并作为 app-server `localImage` 输入传给 Codex，本轮结束后临时文件即删除。附件体积上界因此由像素数决定、与源文件编码无关；Canvas Agent 侧另有兜底闸门：单张 2MB、单次请求总量 8MB，超限返回 413 中文报错。`express` 的请求体上限仍是 30MB，只作为最后一道防线。动图（GIF 等）重编码后只保留首帧。

## 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 @dream-craft/canvas-agent@latest 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__*`，画布写操作仍由网页侧边栏确认。

## 常见问题

### @dream-craft/canvas-agent 是什么？

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

### 如何安装 @dream-craft/canvas-agent？

在项目目录运行 npm install @dream-craft/canvas-agent，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 canvas-agent，可以用 npx canvas-agent 直接运行。

### @dream-craft/canvas-agent 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dream-craft/canvas-agent 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dream-craft/canvas-agent 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dream-craft/canvas-agent 可以商用吗？

@dream-craft/canvas-agent 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dream-craft/canvas-agent 的下载量有多少？

根据 npm 官方下载统计，@dream-craft/canvas-agent 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,038 次，日均约 101 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dream-craft/canvas-agent 还在维护吗？

最新版本 0\.7\.10 发布于 2026/11/11（2 天前）；至今共发布 19 个版本，其中过去 12 个月发布了 19 个；首次发布于 2026/10/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。