mirror of
https://github.com/basketikun/infinite-canvas.git
synced 2026-07-24 15:24:06 +08:00
feat(docs): refine Infinite Canvas usage instructions and clarify local Agent connection process
This commit is contained in:
HouYunFei
+5
-5
@@ -2,19 +2,19 @@
|
||||
|
||||
## Unreleased
|
||||
|
||||
+ [新增] 画布空白区域支持双击打开节点选择菜单，并在点击位置创建节点。
|
||||
+ [优化] 本地 Agent 连接说明明确区分插件 / 手动 MCP 才会增加 Codex token 消耗。
|
||||
+ [优化] 优化本地 Agent 连接说明，区分 Codex 插件启动和直接运行 Agent 两种方式。
|
||||
+ [新增] Agent 对话消息改用 streamdown 流式渲染，提升Markdown 内容展示效果。
|
||||
+ [新增] Agent 新增画布、工作台、提示词库和素材等站点级工具。
|
||||
+ [新增] Agent 面板改为全站常驻右侧栏，开关时同步推动顶栏和页面内容，并保留独立入口按钮。
|
||||
+ [新增] Agent 新增 `site_navigate` 工具，支持页面跳转。
|
||||
+ [新增] Agent 对话运行中支持一键停止，中断当前 Codex turn。
|
||||
+ [调整] Codex 会话改为站点级连续线程，跨页面和跨画布保持同一上下文。
|
||||
+ [调整] 移除仅前端调用 OpenAI responses 接口，统一走 MCP + 本地 Codex 链路。
|
||||
+ [新增] 画布节点支持统一维护名称字段，默认显示在节点上方，并可直接双击名称编辑。
|
||||
+ [新增] 画布新增组节点，支持节点拖入/拆出分组、拖拽高亮吸附和移动组时带动子节点。
|
||||
+ [新增] 画布空白区域支持双击打开节点选择菜单，并在点击位置创建节点。
|
||||
+ [调整] Codex 会话改为站点级连续线程，跨页面和跨画布保持同一上下文。
|
||||
+ [调整] 移除仅前端调用 OpenAI responses 接口，统一走 MCP + 本地 Codex 链路。
|
||||
+ [调整] 画布节点顶部工具条改为点击选中节点后显示，避免鼠标经过节点时频繁弹出。
|
||||
+ [优化] 本地 Agent 连接说明明确区分插件 / 手动 MCP 才会增加 Codex token 消耗。
|
||||
+ [优化] 优化本地 Agent 连接说明，区分 Codex 插件启动和直接运行 Agent 两种方式。
|
||||
|
||||
## v0.6.0 - 2026-07-09
|
||||
|
||||
|
||||
@@ -72,7 +72,7 @@ codex plugin add infinite-canvas@infinite-canvas-local
|
||||
npx -y @basketikun/canvas-agent mcp
|
||||
```
|
||||
|
||||
使用时可以直接在 Codex 里说“打开 Infinite Canvas”，插件会优先启动本地画布和本地 Agent，读取 Local URL 和 Connect token，然后直接打开画布网页地址新建并连接画布。如果自动连接失败，再检查本地画布服务和 Canvas Agent 是否都已启动。
|
||||
使用时可以直接在 Codex 里说“打开 Infinite Canvas”，插件会启动本地 Agent，读取 Local URL 和 Connect token，然后在右侧打开 `https://canvas.best/` 并自动新建、连接画布；只有明确要求使用本地项目时才会启动本地前端。
|
||||
|
||||
Canvas Agent 启动后，给 Codex 添加 MCP：
|
||||
|
||||
|
||||
@@ -88,7 +88,7 @@ codex plugin add infinite-canvas@infinite-canvas-local
|
||||
打开 Infinite Canvas 新建画布 并连接好Codex
|
||||
```
|
||||
|
||||
插件会优先确认当前仓库的本地画布服务是否已经运行。如果端口被占用，它会检查监听进程是否属于当前项目，避免误连到其他项目。确认或启动画布后，插件会启动本地 Canvas Agent，并打开带连接参数的新建画布 URL。
|
||||
插件会启动本地 Canvas Agent，读取连接地址和 token，然后在右侧打开 `https://canvas.best/` 并自动新建、连接画布。只有明确要求使用本地项目时，插件才会启动本地前端。
|
||||
|
||||
画布打开后可以继续让 Codex 操作画布：
|
||||
|
||||
@@ -125,10 +125,10 @@ bun install
|
||||
bun run dev
|
||||
```
|
||||
|
||||
然后启动本地 Agent。端口不是 `3000` 时，把 `CANVAS_URL` 换成真实本地画布地址：
|
||||
然后启动本地 Agent：
|
||||
|
||||
```bash
|
||||
CANVAS_URL=http://localhost:3000 npx -y @basketikun/canvas-agent
|
||||
npx -y @basketikun/canvas-agent
|
||||
```
|
||||
|
||||
从 Agent 输出或 `http://127.0.0.1:17371/config` 读取本地地址和 token 后，打开：
|
||||
|
||||
@@ -19,7 +19,7 @@ description: 当前版本已实现但仍需人工验证的变更项
|
||||
- 画布组节点：工具栏新增“组”节点，普通节点拖入组区域会高亮目标组，松手后自动吸附进组；拖出组区域会解除归属，拖动组节点会一起移动组内子节点。
|
||||
- GitHub Pages：新增版本 tag 触发的前端静态站点自动发布 workflow，需在仓库 Pages 设置中选择 GitHub Actions 并验证路由刷新回退。
|
||||
- 画布图片切图：行数 / 列数会生成可直接拖拽的等分切图线，并支持新增横向 / 纵向线、删除单条线、重置切图线和切片数量预览。
|
||||
- Codex App 插件文档：新增插件安装教程，区分 AI 自动安装、手动安装和本仓库开发调试安装；同步优化插件 README 与技能说明。
|
||||
- Codex App 插件：精简插件 README 安装步骤，更新插件网站和作者信息，并将 `open-canvas` 调整为默认打开在线画布、仅按需启动本地前端；需重新安装后确认详情页和两种打开流程正确。
|
||||
- 本地 Codex 连接画布文档：新增 Canvas Agent、MCP、SSE 与浏览器画布交互原理说明，需确认文档导航和描述是否清晰。
|
||||
- 顶部导航：缩小桌面顶部导航栏高度，导航项下划线和内容垂直对齐需确认。
|
||||
- 配置与用户偏好：新增独立顶部导航页面，并在页面和弹窗中复用同一套配置面板；新增 Codex Tab，展示插件安装和本地 Agent 启动步骤，可配置本地 Agent 地址、Connect token 和工具执行确认开关。
|
||||
|
||||
@@ -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`
|
||||
|
||||
某条启动命令直接报错时，报告该错误并处理明确原因；不要提前执行额外诊断流程。
|
||||
|
||||
Reference in New Issue
Block a user