feat(docs): refine Infinite Canvas usage instructions and clarify local Agent connection process

2026-07-24 15:24:06 +08:00 · 2026-07-14 16:24:22 +08:00
parent 228ca29c82
commit 7e0288d461
7 changed files with 49 additions and 156 deletions
@@ -3,8 +3,10 @@
  "version": "0.1.0",
  "description": "Use Codex to read and operate Infinite Canvas through the local Canvas Agent MCP server.",
  "author": {
-    "name": "Infinite Canvas"
+    "name": "basketikun",
+    "url": "https://canvas.best/"
  },
+  "homepage": "https://canvas.best/",
  "repository": "https://github.com/basketikun/infinite-canvas",
  "license": "AGPL-3.0",
  "keywords": ["infinite-canvas", "canvas", "mcp", "agent"],
@@ -14,9 +16,10 @@
    "displayName": "Infinite Canvas",
    "shortDescription": "Use Codex to operate the current Infinite Canvas board.",
    "longDescription": "Connects Codex to the local Canvas Agent MCP server so Codex can inspect the current Infinite Canvas board, create nodes, connect flows, and trigger generation through the web canvas confirmation flow.",
-    "developerName": "Infinite Canvas",
+    "developerName": "basketikun",
    "category": "Productivity",
    "capabilities": ["Canvas", "MCP", "Creative Workflow"],
+    "websiteURL": "https://canvas.best/",
    "defaultPrompt": [
      "打开 Infinite Canvas",
      "读取当前画布并总结节点结构",
@@ -1,123 +1,31 @@
 # Infinite Canvas Codex Plugin

-这个插件把 Infinite Canvas 的本地 Canvas Agent MCP 打包给 Codex app 使用，让 Codex 能打开本地画布、读取当前节点、创建内容并触发生成流程。
+让 Codex 可以打开并操作 Infinite Canvas。

 ## 安装

-### AI 自动安装
-
-把下面这段发给 Codex：
-
-```text
-请从 https://github.com/basketikun/infinite-canvas.git 安装 Infinite Canvas Codex 插件。
-请 clone 仓库到 ~/plugins/infinite-canvas，确认 plugins/infinite-canvas/.codex-plugin/plugin.json 存在，
-把 plugins/infinite-canvas 加入 personal marketplace，先运行 codex plugin marketplace add ~，
-再运行 codex plugin add infinite-canvas@personal。
-安装后请校验插件，并告诉我是否需要开启一个新对话来加载新技能和 MCP 工具。
-```
-
-### 手动安装
-
-推荐把仓库 clone 到 Codex personal marketplace 默认会引用的位置：
+macOS / Linux：

 ```bash
-mkdir -p ~/plugins
-git clone https://github.com/basketikun/infinite-canvas.git ~/plugins/infinite-canvas
-```
-
-确保 `~/.agents/plugins/marketplace.json` 中有 Infinite Canvas 条目，注意 `path` 指向仓库里的插件子目录：
-
-```json
-{
-  "name": "personal",
-  "interface": {
-    "displayName": "Personal"
-  },
-  "plugins": [
-    {
-      "name": "infinite-canvas",
-      "source": {
-        "source": "local",
-        "path": "./plugins/infinite-canvas/plugins/infinite-canvas"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Productivity"
-    }
-  ]
-}
-```
-
-然后注册 personal marketplace 并安装插件：
-
-```bash
-codex plugin marketplace add ~
-codex plugin add infinite-canvas@personal
-```
-
-安装后建议开启一个新的 Codex 对话，让新的 skill 和 MCP 工具完整加载。
-
-安装 Codex 插件后会加载 `infinite-canvas` MCP。这个 MCP 内置工具较多，会增加 Codex 上下文和 token 消耗；不使用插件时建议移除插件：
-
-```bash
-codex plugin remove infinite-canvas
-```
-
-如果你另外手动执行过 `codex mcp add`，再移除手动添加的 MCP：
-
-```bash
-codex mcp remove infinite-canvas
-```
-
-### 本仓库开发调试
-
-如果你就在 Infinite Canvas 仓库中调试插件，可以直接添加仓库自带 marketplace。建议使用仓库绝对路径，避免 Codex 从其他工作目录解析失败：
-
-```bash
-cd /path/to/infinite-canvas
+git clone https://github.com/basketikun/infinite-canvas.git
+cd infinite-canvas
 codex plugin marketplace add "$(pwd)"
 codex plugin add infinite-canvas@infinite-canvas-local
 ```

-## 使用
+Windows PowerShell：

-1. 新建 Codex 线程后说“打开 Infinite Canvas”。
-2. 插件会确认当前仓库的本地画布服务是否已运行；端口被占用时会检查进程归属，不会把其他项目的 `3000` 当作 Infinite Canvas。
-3. 确认或启动后，插件会直接打开新建画布 URL，并自动尝试连接本地 Agent。
-4. 画布打开后，让 Codex 读取或操作当前画布。
+```powershell
+git clone https://github.com/basketikun/infinite-canvas.git
+cd infinite-canvas
+codex plugin marketplace add "$PWD"
+codex plugin add infinite-canvas@infinite-canvas-local
+```

-常用提示：
+Windows CMD 将 `$PWD` 替换为 `%cd%`。
+
+安装后新建一个 Codex 任务，然后输入：

 ```text
-打开 Infinite Canvas
-读取当前画布并总结节点结构
-根据选中节点创建一组生图提示词
+帮我打开并连接到 Infinite Canvas
 ```
-
-## 工作机制
-
-插件默认通过以下命令启动 MCP；这个命令只提供 MCP 工具，不会把 MCP 写入全局配置，也不会在退出时自动卸载。需要打开画布时，`open-canvas` 技能会另外启动本地 Agent：
-
-```bash
-npx -y @basketikun/canvas-agent mcp
-```
-
-## 手动排查
-
-优先本地启动画布：
-
-```bash
-cd web
-bun install
-bun run dev
-```
-
-然后启动本地 Agent。端口不是 `3000` 时，把 `CANVAS_URL` 换成真实本地画布地址：
-
-```bash
-CANVAS_URL=http://localhost:3000 npx -y @basketikun/canvas-agent
-```
-
-手动排查时先从 Agent 输出或 `http://127.0.0.1:17371/config` 读取本地地址和 token，然后直接打开 `<画布网页地址>/canvas?mode=new&agentUrl=<Local URL>&agentToken=<Connect token>`。不要通过页面点击来新建画布；`mode=new` 会让网页自动创建具体画布并连接本地 Agent。
@@ -1,44 +1,31 @@
 ---
 name: open-canvas
-description: 下载、安装并打开 Infinite Canvas，自动连接本地 Canvas Agent。用户要求打开、启动、进入或使用 Infinite Canvas 画布时使用。
+description: 打开 Infinite Canvas 在线或本地画布，并自动连接本地 Canvas Agent。用户要求打开、启动、进入或使用 Infinite Canvas 画布时使用。
 ---

 # Open Infinite Canvas

-用户要求打开 Infinite Canvas 时直接执行，不要先搜索目录、扫描端口、检查进程归属、读取配置文件或让用户手动复制 URL 和 token。
+默认打开在线版。只有用户明确要求使用本地项目时，才启动本地前端。

-## 选择项目目录
+## 在线版

-只分两种情况：
-
-### 当前就在 Infinite Canvas 项目中
-
-当前目录存在 `web/package.json` 和 `plugins/infinite-canvas/.codex-plugin/plugin.json` 时，直接把当前目录作为项目目录。
-
-### 当前不在 Infinite Canvas 项目中
-
-固定使用 `~/plugins/infinite-canvas`：
+1. 启动本地 Canvas Agent 并保持运行：

 ```bash
-mkdir -p ~/plugins
-git clone https://github.com/basketikun/infinite-canvas.git ~/plugins/infinite-canvas
-cd ~/plugins/infinite-canvas
+npx -y @basketikun/canvas-agent
 ```

-如果该目录已经存在就直接进入，不要再查找其他副本。
+2. 从启动输出取得 `Local URL` 和 `Connect token`。

-## 一步启动
+3. 在 Codex 右侧浏览器打开：

-进入项目目录后依次执行：
-
-1. 安装当前项目内的 Codex 插件：
-
-```bash
-codex plugin marketplace add "$(pwd)"
-codex plugin add infinite-canvas@infinite-canvas-local
+```text
+https://canvas.best/canvas?mode=new&agentUrl=<Local URL>&agentToken=<Connect token>
 ```

-2. 安装前端依赖并启动开发服务：
+## 本地版
+
+1. 在 Infinite Canvas 项目中启动前端，并使用 Vite 输出的 `Local` 地址：

 ```bash
 cd web
@@ -46,31 +33,26 @@ bun install
 bun run dev
 ```

-保持开发服务运行，直接采用 Vite 输出的 `Local` 地址作为画布地址，不要另外探测端口。
-
-3. 在项目根目录启动网页连接所需的本地 Agent，并把 Vite 输出的地址传给它：
+2. 启动本地 Canvas Agent：

 ```bash
-CANVAS_URL=<Vite Local 地址> npx -y @basketikun/canvas-agent
+npx -y @basketikun/canvas-agent
 ```

-安装插件后，插件会自动启动 `npx -y @basketikun/canvas-agent mcp`；上面的命令只负责启动网页要连接的 HTTP Agent，两者都需要，不要再手动添加 MCP。
-
-4. 从 Agent 启动输出中直接取得 `Local URL` 和 `Connect token`，立即在浏览器打开：
+3. 从启动输出取得 `Local URL` 和 `Connect token`，在 Codex 右侧浏览器打开：

 ```text
 <Vite Local 地址>/canvas?mode=new&agentUrl=<Local URL>&agentToken=<Connect token>
 ```

-网页会自动新建画布并连接 Agent，不要再点击“新建画布”，也不要在打开后追加连接检查。
+## MCP 与连接地址

-如果插件是本轮对话中刚安装的，完成安装和服务启动后告知用户新开一个 Codex 对话即可加载 MCP；不要因此重复安装或重启前端。
+插件在新的 Codex 任务中加载时会自动启动 `npx -y @basketikun/canvas-agent mcp`。这个 MCP 进程负责提供画布工具，不提供网页连接服务；
+上面启动的普通 Canvas Agent 负责提供 `Local URL` 和 `Connect token`。两个进程读取同一份本地配置，因此不需要用户手动填写地址或 token。

 ## 打开模式

-默认使用 `mode=new`。只有用户明确要求时才替换为：
+用户没有明确指定打开方式时，始终使用 `mode=new` 新建画布。只有用户明确要求时才替换为：

 - 最近画布：`mode=recent`
 - 自己选择：`mode=choose`
-
-某条启动命令直接报错时，报告该错误并处理明确原因；不要提前执行额外诊断流程。