feat(plugin): add Codex App plugin support and local agent integration

2026-07-24 15:24:06 +08:00 · 2026-06-23 17:35:43 +08:00
parent 8cbe00e348
commit bd0ad0aebf
18 changed files with 518 additions and 28 deletions
@@ -0,0 +1,140 @@
+---
+title: Codex App 插件
+description: 在 Codex App 中安装并使用 Infinite Canvas 插件
+---
+
+# Codex App 插件
+
+Infinite Canvas 提供了一个 Codex App 插件，用来把 Codex 和本地 Canvas Agent 连接起来。安装后，你可以直接在 Codex 中说“打开 Infinite Canvas”，让 Codex 打开画布、读取节点、创建节点并触发生成流程。
+
+插件源码位于仓库的 `plugins/infinite-canvas/` 目录。
+
+## 安装方式
+
+### 让 Codex 自动安装
+
+把下面这段发给 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 工具。
+```
+
+这种方式适合不想手动改 marketplace 配置的用户。Codex 会完成 clone、写入 marketplace、安装插件和基础校验。
+
+### 手动安装
+
+推荐把仓库 clone 到 Codex personal marketplace 默认会引用的位置：
+
+```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 工具完整加载。
+
+### 本仓库开发调试安装
+
+如果你正在 Infinite Canvas 仓库中开发插件，可以直接使用仓库自带的 marketplace：
+
+```bash
+cd /path/to/infinite-canvas
+codex plugin marketplace add "$(pwd)"
+codex plugin add infinite-canvas@infinite-canvas-local
+```
+
+仓库内的 `.agents/plugins/marketplace.json` 已经指向 `./plugins/infinite-canvas`，适合开发者本地调试。
+
+## 使用插件
+
+新建 Codex 对话后，可以直接说：
+
+```text
+打开 Infinite Canvas 新建画布 并连接好Codex
+```
+
+插件会优先确认当前仓库的本地画布服务是否已经运行。如果端口被占用，它会检查监听进程是否属于当前项目，避免误连到其他项目。确认或启动画布后，插件会启动本地 Canvas Agent，并打开带连接参数的新建画布 URL。
+
+画布打开后可以继续让 Codex 操作画布：
+
+```text
+读取当前画布并总结节点结构
+根据选中节点创建一组生图提示词
+把这些节点整理成一个生成流程
+```
+
+## 更新插件
+
+普通业务代码变更通常不需要更新插件。只有改了下面这些内容时，才建议重新安装或刷新插件：
+
+- `plugins/infinite-canvas/.codex-plugin/plugin.json`
+- `plugins/infinite-canvas/.mcp.json`
+- `plugins/infinite-canvas/skills/` 下的技能说明
+- 插件暴露的 MCP、app 或入口脚本
+
+重新安装后建议开启新对话，避免旧对话继续使用缓存中的技能和 MCP 工具。
+
+## 手动排查
+
+插件默认通过下面的 MCP 命令启动 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 后，打开：
+
+```text
+<画布网页地址>/canvas?mode=new&agentUrl=<Local URL>&agentToken=<Connect token>
+```
+
+`mode=new` 会让网页自动创建具体画布并连接本地 Agent，不需要手动点击“新建画布”。
@@ -4,6 +4,7 @@
  "defaultOpen": true,
  "pages": [
    "quick-start",
+    "codex-app-plugin",
    "features",
    "render",
    "docker",
@@ -5,6 +5,7 @@ description: 当前版本已实现但仍需人工验证的变更项

 # 待测试

+- Codex App 插件文档：新增插件安装教程，区分 AI 自动安装、手动安装和本仓库开发调试安装；同步优化插件 README 与技能说明。
 - 配置与用户偏好：每个模型渠道新增 OpenAI / Gemini 调用格式选择，默认 OpenAI，切换默认格式时同步更新默认 Base URL；渠道 Tab 增加紧凑醒目的提醒，说明模型是否可选需要到“模型”Tab 选择。
 - Gemini 调用格式：支持拉取 Gemini 模型列表，并用于文本问答、在线 Agent 工具调用、基础生图和图生图请求。
 - 音频和视频生成：选择 Gemini 调用格式时先给出不支持提示，仍需使用 OpenAI 兼容渠道。