Modellix Agent Canvas

Modellix Agent Canvas

English · 简体中文

Modellix Agent Canvas 是一款本地、绑定工作区的 stdio MCP 插件，适用于可视化 AI 创作。它将 Excalidraw 无限画布、Modellix 图像生成与编辑、付费操作确认、持久化任务恢复、HTML 草稿、演示文稿和项目本地持久化整合到一个工作区中。

它支持 Codex、Cursor、Claude Code、OpenCode 以及其他实现了本地 stdio MCP 的应用。支持 MCP Apps 的宿主可嵌入完整画布；其他兼容宿主则通过临时环回页面使用同一 MCP 服务。Canvas 在本地运行，无需部署 Canvas 服务。

产品概览

这些截图来自一次真实的本地 Canvas 会话。可复现的操作演示使用原始本地作品 docs/images/demo/creative-studio.webp，因此你无需先创建付费图像任务，即可探索图像编辑、HTML 捕获和演示文稿功能。

下面这个 Lumen Creative Direction 故事展示了七项彼此关联的功能，而非互不相关的示例：

1. 将真实的本地图片作为普通画布资源导入。
2. 将选中内容设为受控图像编辑的主要参考。
3. 在提交任何付费任务前，检查路由模型、实际生效的规格、数量和价格说明。
4. 在受 CSP 限制的实时预览旁编辑 HTML，并将渲染结果捕获回 Canvas。
5. 在五页演示文稿中沿用相同的视觉方向。
6. 以整洁的全屏顺序播放演示文稿。
7. 将页面导出为 PNG/SVG，将演示文稿导出为 PNG 序列，或备份并恢复项目。

真实的图像工作流

将图片拖到画布上，或选中已完成的生成结果，然后只描述你想要的更改。选中的图片会成为主要参考；提交前，你仍可编辑输出尺寸、数量、背景、质量和其他有序参考项。

付费前检查路由

prepare_modellix_image_task 是免费的。它会显示实际使用的模型、路由原因、请求规格与实际生效的规格、数量，以及可用的价格说明，然后再单独进行确认。本次文档运行未能获取报价，因此没有提交付费任务；如果预算固定，请勿确认没有报价的任务。

安全的 HTML 草稿

在隔离的实时预览旁编辑 HTML 源代码，将其捕获回画布，或将源代码导出为 ZIP 存档。

演示文稿编辑器

使用多种布局创建可编辑的幻灯片，通过普通幻灯片元素放入视觉资源，以可视化方式管理顺序、进行演示，或导出 PNG 序列。

全屏播放

同一张以图像为主的幻灯片可在内置演示器中播放，并提供上一页/下一页控件和可见的幻灯片计数。

导出与项目备份

将当前页面以 1×、2× 或 4× PNG 导出，保存为 SVG，下载演示文稿 PNG 序列，或创建并恢复项目备份。

重现操作演示

1. 通过下方任一宿主接入方式安装插件，然后在真实项目工作区中打开它。
2. 使用相同的绝对工作区路径调用 get_modellix_canvas_status 和 open_modellix_canvas。
3. 将 creative-studio.webp 拖到画布上，选中它，然后输入编辑指令。
4. 选择 16:9 · Landscape，点击 Prepare edit，检查返回的模型、路由、有效规格、数量和价格说明。准备操作免费。
5. 仅当所示总价符合预算时才确认。否则选择 Back to edit；本操作演示无需付费提交。
6. 打开 HTML，保存隔离草稿，然后选择 Create screenshot，将渲染结果插回画布。
7. 打开 Presentation，创建起始演示文稿，并将视觉素材拖到幻灯片中。使用 Play 或 PNG sequence 完成操作。

包含功能

• **无限画布：**文本、形状、线条、箭头、手绘、画框、图像、分组、锁定、图层、对齐、项目持久化个人库，以及针对单个操作的撤销和重做。
• **多页项目：**创建、重命名、复制、重新排序和删除页面，同时为每个页面保留独立的视口和历史记录。
• **图像占位符：**生成前预留目标区域；选定结果会替换占位符且可撤销，额外结果则会以可预测的方式放置在其旁边。
• **图像生成与编辑：**文生图、单图编辑、按顺序排列的 2–10 张图像参考、明确的主参考图、基于标注的编辑、透明背景、保真度控制，以及 1–4 个输出结果。
• **模型感知路由：**用户说明创作需求；准备操作会返回所选模型、路由原因、有效规格、限制和预估总费用。
• **付费操作安全：**准备操作免费；提交需要明确的一次性确认；重复工作会在本地去重；未知的提交状态绝不会自动重试。
• **持久任务：**任务 ID、状态转换和本地结果会持久化到仅追加账本中，因此即使宿主或浏览器关闭，也能继续处理。
• **HTML 草稿：**源代码编辑、受 CSP 限制的沙盒预览、刷新、画布截图和源代码 ZIP 导出。
• **演示文稿：**16:9、4:3 和自定义比例；标题、内容、图像、对比和空白布局；缩略图、重新排序、复制、演示模式和 PNG 序列导出。
• **导入和导出：**以 1×、2× 或 4× 导出选定区域或整页 PNG/SVG，导出演示文稿 PNG ZIP，以及确认后恢复项目 JSON 备份。
• **英文、中文和日文界面：**默认使用英文。右上角的语言切换器会更新画布、Excalidraw 控件和安全 API Key 表单，所选语言会随项目保存。
• **本地安全：**凭据使用 modellix-cli 系统凭据存储，并且绝不会写入聊天、MCP 参数、URL、项目文件或任务账本。

要求

• Node.js ^20.19.0 || >=22.12.0
• 可访问生产 API：https://api.modellix.ai
• 从 Modellix 控制台获取有效的 API Key

请只选择一种安装方式。Codex、Cursor 和 Claude 用户只需从宿主的 Git 或 Marketplace 条目安装一次；插件会加载其清单和 Skills，并在后台自动解析固定版本的 npm 运行时。OpenCode 和通用 MCP 用户只需添加一次基于 npm 的 MCP 服务。用户无需再运行第二条 npm 或 CLI 安装命令。软件包包含经过测试的 modellix-cli 0.0.11 运行时，作为离线回退方案。每个 MCP 进程首次使用 CLI 时，Canvas 会检查公开 npm 的 latest 标签，将对应的确切 CLI 版本以原子方式缓存到用户本地的 Modellix 缓存中，并在该进程的剩余时间内固定使用此版本。如果注册表或兼容性检查失败，则回退到捆绑版本，因此 CLI 发布新版本不会导致已安装的 Canvas 无法使用。只有在部署必须保持使用捆绑回退版本时，才设置 MODELLIX_CLI_AUTO_UPDATE=0。如果已有有效的 CLI 凭据，则会重复使用；否则，首次使用时只会提示输入 Modellix API Key。

可选：在源码检出目录之外运行 npm exec --yes --package=@modellix/[email protected] -- modellix-agent-canvas --doctor，以验证已发布软件包的 Node.js 要求、生产依赖、捆绑的 Widget 和当前版本。这是诊断操作，不是第二种安装方式。

快速开始

尽可能通过宿主的插件界面安装。

Agent Plugins 1.0.0 客户端

通过任何兼容的 Agent Plugins 客户端安装此仓库或其 npm 软件包。可移植核心包括根目录下的 plugin.json、mcp.json 和 skills/ 目录。清单和 MCP 配置面向官方 1.0.0 架构；固定位置发现机制会加载三个 Agent Skills 和通用 stdio 服务，无需依赖特定宿主的清单。

Codex

codex plugin marketplace add Modellix/modellix-agent-canvas
codex plugin add modellix-agent-canvas@modellix

Git marketplace 会从此仓库安装插件文件。其 Codex 适配器会启动一个 Node 引导进程，首次使用时将固定版本的 npm 运行时安装到用户本地缓存中，然后在同一进程中导入 MCP 服务。后续启动会重复使用经过验证的缓存，无需保留 npx 包装进程，也无需全局安装 CLI。

Cursor

在 Cursor 中运行以下命令：

/add-plugin modellix-agent-canvas

若要通过 Git 或本地检出安装，请打开 自定义 → 插件 → + 添加，然后选择仓库根目录。Cursor 会读取 .cursor-plugin/marketplace.json，随后在 modellix 个人 marketplace 中提供 Modellix Agent Canvas。这与提交到 Cursor Directory 的 Open Plugins 元数据相互独立。

Claude Code

claude plugin marketplace add Modellix/modellix-agent-canvas
claude plugin install modellix-agent-canvas@modellix

启用或升级插件后，运行 /reload-plugins，然后使用 /mcp 验证连接。

OpenCode 和其他 MCP 宿主

使用公开 npm 软件包 @modellix/agent-canvas。此仓库包含可直接合并的宿主配置。有关设置、验证、升级、卸载和源码开发，请参阅完整安装指南。

安装后，调用：

get_modellix_canvas_status { "refresh": true, "workspacePath": "<absolute project path>" }
open_modellix_canvas { "workspacePath": "<the same absolute project path>" }

如果状态为 missing 或 invalid，Canvas 会直接在凭据卡片中显示密码输入框。该字段会采用右上角所选的语言，并作为一个独立的一次性环回表单，在五分钟后过期；提交后，系统会通过捆绑的 CLI 验证密钥，将其存储在系统凭据库中，并自动刷新 Canvas 状态。密钥不会进入 Canvas 状态或 MCP 工具参数。对于需要显式获取同一短时本地表单的集成，仍可使用 start_modellix_api_key_setup。

主机兼容性

主机	本地 MCP	Canvas 界面	配置
Agent Plugins 1.0.0 客户端	stdio	可移植的本地页面回退方案；MCP Apps 元数据仍可发现	plugin.json、mcp.json、skills/
Codex	stdio	MCP Apps 小组件，并提供本地回退方案	.codex-plugin/plugin.json（由 .mcp.codex.json 镜像）
Cursor 2.6+	stdio	MCP Apps	.cursor-plugin/marketplace.json、.cursor-plugin/plugin.json、.mcp.json
Claude Code	stdio	短时运行的本地页面	.claude-plugin/plugin.json、.mcp.claude.json
OpenCode	本地 MCP 命令	短时运行的本地页面	adapters/opencode/opencode.json、.agents/skills
OpenCode V2 beta	本地 MCP 命令	短时运行的本地页面	adapters/opencode/opencode-v2.json、.agents/skills

请使用适用于目标主机的适配器。根目录中的 plugin.json 和 mcp.json 构成可移植的 Agent Plugins 1.0.0 核心。.plugin/plugin.json 和 .mcp.json 仍是 Cursor Directory 的旧版 Open Plugins 入口，以及 Cursor 专用的 MCP Apps 适配器。Codex 清单内嵌了自身的服务配置，.mcp.codex.json 则为直接开发提供镜像配置。有关协议映射、主机专属 UI 行为和验证状态，请参阅主机兼容性。

标准 Cursor MCP 配置

Cursor 专用的 .mcp.json 会运行：

npx -y --package @modellix/[email protected] modellix-agent-canvas --host cursor --supports-mcp-apps true

模板不包含 API Key。Cursor 通过 MCP Roots 提供当前工作区；模板有意避免使用不可移植的 ${workspaceFolder} 插值。

Claude Code 源码开发

claude mcp add --transport stdio modellix-agent-canvas -- node /absolute/path/modellix-agent-canvas/scripts/start-mcp.mjs --host claude-code --supports-mcp-apps false --project-dir /absolute/path/to/project

OpenCode

对于稳定版 OpenCode，请将 adapters/opencode/opencode.json 中的 mcp.modellix-agent-canvas 合并到项目配置中。OpenCode V2 beta 用户则应改为合并 adapters/opencode/opencode-v2.json 中的 mcp.servers.modellix-agent-canvas。这两个适配器都会从当前工作区启动 @modellix/[email protected]，并使用本地页面回退方案。

API Key 与隐私

凭证解析过程有意保持简单：

1. 检查 modellix-cli 已保存的凭证。
2. 如有可用的有效凭证，则重新使用。
3. 否则，在 Canvas 凭证卡片内嵌的隔离设置字段中输入密钥。

请勿将密钥放入聊天内容、工具参数、命令行参数、仓库文件、屏幕截图、项目备份或任务报告中。Canvas 不会将密钥存储在 localStorage、sessionStorage 或 IndexedDB 中。

只有在用户确认付费任务后，才会将提示词和输入图像发送给 Modellix。准备步骤会读取模型能力和定价数据，但不会上传参考文件或创建付费任务。已完成的输出会立即下载到项目资源中，从而避免依赖会过期的远程结果 URL。

图像路由

要求	默认能力路由
标准不透明文生图	GPT Image 2
透明文生图	GPT Image 1.5
标准单图编辑	GPT Image 2 Edit
透明、严格保真或标准多图编辑	GPT Image 1.5 Edit
使用特殊比例或输出 2K/4K 的多参考图编辑	Nano Banana Pro Edit

生产 API 提供当前模型目录、能力和价格。Canvas 仅从获批的候选模型中选择。如果没有模型满足所有硬性要求，则返回 CAPABILITY_CONFLICT 或 MODEL_UNAVAILABLE，而不会悄然降低要求或创建付费任务。

付费工作流如下：

1. prepare_modellix_image_task 解析有序参考图、选择模型，并返回一个短时有效的确认指纹。
2. UI 或 Agent 显示实际模型、路由原因、有效规格、数量、警告和预计总费用。
3. 用户明确批准后，submit_modellix_image_task 使用相同指纹提交未更改的请求。
4. wait_modellix_image_task 默认等待已登记的任务 30 秒（最长 45 秒）；get_modellix_image_task 立即返回快照。关闭页面会取消当前读取，但不会重新提交任务。SUBMISSION_UNKNOWN 只能用于查询，绝不能触发自动重新提交。
5. finalize_modellix_image_task 验证下载内容、写入内容寻址资源，并将结果放置在占位符处或源文件旁。

MCP 工具

面向 Agent 的工作流使用：

• get_modellix_canvas_status
• start_modellix_api_key_setup
• open_modellix_canvas
• get_canvas_context
• create_canvas_page、rename_canvas_page 和 delete_canvas_page
• prepare_modellix_image_task
• submit_modellix_image_task
• get_modellix_image_task
• wait_modellix_image_task
• list_modellix_canvas_tasks
• finalize_modellix_image_task
• cleanup_modellix_canvas_uploads，需要设置 confirmCleanup: true，且仅影响账本中记录的已终止临时上传

get_canvas_project、save_canvas_project 和 save_canvas_asset 是仅供 MCP Apps 使用的数据通道，可避免大型场景 JSON 和 base64 资源进入模型上下文。每个工具都会返回稳定的错误代码、可重试性和恢复指引。

项目数据

每个已绑定的工作区都将数据存储在：

.modellix/canvas/
├── project.json
├── pages/<page-id>.json
├── assets/
│   ├── images/
│   ├── html/
│   └── exports/
├── tasks/
│   ├── snapshot.json
│   ├── events.jsonl
│   └── staging/
├── recovery/
└── locks/

• 图像使用 SHA-256 进行内容寻址并去重；页面 JSON 存储相对资源 ID。
• 项目和页面写入会使用临时文件、刷新、原子替换和修订冲突检查。
• 写入前会创建恢复快照；较旧的构建不会原地覆盖未知的架构版本。
• 真实路径、符号链接、目录联接和工作区边界检查可保护每项文件操作。
• 任务账本不包含 API 密钥、完整提示词文本、输入图像、远程临时 URL 和本地绝对路径。

环回与 HTML 安全

备用页面仅在 localhost 上侦听，使用系统分配的临时端口，并强制执行以下要求：

• 一次性高熵打开令牌和短时有效的 HttpOnly; SameSite=Strict 会话
• 主机、Origin、HTTP 方法、Content-Type 和请求大小验证
• 严格的 CSP、no-store、no-referrer 和 nosniff
• 不使用远程脚本、字体、分析服务或通用文件代理

HTML 草稿在单独的沙盒 iframe 中运行，并具有自己的 CSP。默认禁用外部网络访问、顶层导航、弹出窗口、下载、设备权限和主机 API。

开发与发布检查

npm ci
npm run sync:skills
npm run check
npm run check:licenses
npm run check:plugin
npm test
npm run build
npm run build:widget
npm run probe:mcp
npm audit --audit-level=moderate

npm run quality 运行完整的本地检查门禁，但不包括 npm audit 和真实的打包安装冒烟测试。npm run smoke:package 会在禁用生命周期脚本的情况下安装可发布的软件包，并对完整的 MCP 进行探测。

发布前，使用 npm pack --dry-run 确认软件包不包含 QA 源站、内部验收材料、绝对路径、测试凭据或过时资源。

常见错误

• WORKSPACE_UNBOUND：请提供当前项目的绝对 workspacePath，或从实际用户项目中使用 --project-dir 重启 MCP。
• WORKSPACE_BOUNDARY_VIOLATION：路径或链接目标解析到了绑定工作区之外。
• AUTH_REQUIRED / AUTH_INVALID：请在凭据卡片中使用或重新生成安全输入；不要通过聊天发送密钥。
• ROUTE_CHANGED_RECONFIRM_REQUIRED：输入、参考顺序、规格、价格或有效期已更改；请重新准备并确认。
• SUBMISSION_UNKNOWN：不要重新提交；请从任务中心继续轮询现有操作。
• FINALIZE_CONFLICT：检查预期目标是否已移动或删除，然后选择恢复位置。
• REVISION_CONFLICT：另一个会话更新了项目；请重新加载后再应用当前更改。
• No marketplace manifest found：使用 Customize → Plugins → + Add 时，请选择包含 .cursor-plugin/marketplace.json 的仓库根目录；若要加载独立插件进行开发，请改用 ~/.cursor/plugins/local/modellix-agent-canvas。

升级和卸载

特定宿主的命令记录在升级和卸载中。升级不会删除 .modellix/canvas/。卸载也会保留工作区数据和系统凭据，以防误删其他 Modellix 工具共用的密钥。若要移除凭据，请针对相应配置文件运行 modellix-cli auth logout。

许可证

项目自有代码采用 MIT License。画布引擎使用基于 MIT 许可证的 @excalidraw/excalidraw 0.18.1；捆绑的 modellix-cli 0.0.11 回退版本以及自动缓存的较新版 CLI 均保留各自的软件包许可证和元数据。请参阅 THIRD_PARTY_NOTICES.md 和 THIRD_PARTY_LICENSES。