ai-chatbot/docs/无限画布-Capability-Runtime与MCP接入说明.md

无限画布 Capability Runtime 与 MCP 接入说明

目标

无限画布的图片工具栏、Agent 和 MCP 共用同一套能力定义与执行器。MCP 只负责协议适配，不复制抠图、增强、3D 等业务逻辑。

调用链

图片工具栏 ─┐
AI SDK Tools ├─> Canvas Capability Registry ─> Runtime/Queue ─> 画布写回
MCP Tools ───┘                 └──────────────> Client Command（交互面板）

• 能力注册：lib/canvas/capabilities/registry.ts
• 参数与命令协议：lib/canvas/capabilities/client-command.ts
• 统一运行时：lib/canvas/capabilities/runtime.ts
• 后台执行器：lib/canvas/capabilities/headless-executor.ts
• 持久化任务：lib/canvas/capabilities/task-store.ts
• 项目内顺序队列：lib/canvas/capabilities/task-queue.ts
• AI SDK 工具：lib/canvas/capabilities/ai-sdk-tools.ts
• MCP 适配器：lib/canvas/capabilities/mcp-server.ts
• 前端命令总线：store/canvas/index.ts

HTTP 入口

• 应用能力接口：GET/POST /api/canvas/:projectId/capabilities
• MCP Streamable HTTP：GET/POST/DELETE /api/mcp/canvas/:projectId

两个入口都使用当前登录会话鉴权，运行时会再次校验画布归属和节点类型。MCP 调用必须传 nodeIds；连续调用时可将上一步返回的 createdNodeIds 传给下一步。

执行模式

• headless：服务端直接执行，完成后写入新节点。
• interactive：通过 SSE 下发客户端命令，打开裁剪、调色、局部编辑等现有面板。
• hybrid：参数完整时后台执行，否则打开交互面板。
• 删除等危险能力必须明确确认，并使用请求号保证幂等。

Tripo 3D 与 World Labs 3D 世界由 Agent/MCP 直接创建任务和结果节点。节点保存任务 ID，页面刷新后继续轮询并恢复最终结果。

部署

部署新版本前必须执行：

pnpm install --frozen-lockfile
pnpm db:migrate
pnpm build

迁移 0090_add_canvas_capability_tasks.sql 新增持久化任务表。未执行迁移时，能力任务无法启动。

增加服务商或能力

1. 在 Registry 新增或扩展能力 Schema、风险、模型策略和工具名称。
2. 在共享后台执行器中接入服务商路由；不要在 React 组件或 MCP 回调中直接实现服务商逻辑。
3. 结果统一返回媒体/3D 节点描述，由运行时写回画布。
4. 需要用户框选或配置时，复用现有 clientAction 和前端面板。
5. 添加能力契约、MCP 工具发现、写回和失败恢复测试。

服务商切换应由系统模型配置和现有服务层完成。Agent/MCP 只传模型别名或能力参数，不持有服务商密钥。