OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

快速开始

Canvas 插件重构

Canvas 插件重构

Canvas 使用率较低，且处于实验阶段。应将其视为内置插件，而非核心功能。核心可以保留通用的 Gateway 网关、节点、HTTP、身份验证、配置和原生客户端基础设施，但 Canvas 特有行为应位于 extensions/canvas 下。

目标

将 Canvas 的所有权迁移至 extensions/canvas，同时保留当前的已配对节点行为：

  • 面向智能体的 canvas 工具由 Canvas 插件注册
  • 仅当 Canvas 插件注册 Canvas 节点命令时，才允许使用这些命令
  • A2UI 主机/源文件位于 Canvas 插件下
  • Canvas 文档实体化逻辑位于 Canvas 插件下
  • CLI 命令实现位于 Canvas 插件下，或通过插件自有的运行时导出入口进行委托
  • 文档和插件清单将 Canvas 描述为实验性且由插件提供支持

非目标

  • 此次重构不重新设计原生应用的 Canvas UI。
  • 除非另有产品决策要求删除 Canvas，否则不要移除 iOS、Android 或 macOS 中的 Canvas 协议/客户端支持。
  • 除非至少还有一个其他内置插件需要相同的接口，否则不要仅为 Canvas 构建通用的插件服务框架。

当前分支状态

已完成：

  • 在 extensions/canvas 中添加了内置插件包。
  • 添加了 extensions/canvas/openclaw.plugin.json。
  • 将智能体的 canvas 工具从 src/agents/tools/canvas-tool.ts 移至 extensions/canvas/src/tool.ts。
  • 从 src/agents/openclaw-tools.ts 中移除了核心对 createCanvasTool 的注册。
  • 将 Canvas 主机实现从 src/canvas-host 移至 extensions/canvas/src/host。
  • 保留 extensions/canvas/runtime-api.ts，作为由插件所有的兼容性导出入口，供测试、打包和外部公开 Canvas 辅助工具使用。
  • 将 Canvas 文档实体化逻辑从 src/gateway/canvas-documents.ts 移至 extensions/canvas/src/documents.ts。
  • 将 Canvas CLI 实现和 A2UI JSONL 辅助工具移至 extensions/canvas/src/cli.ts。
  • 将 Canvas 主机 URL 和限定作用域的能力辅助工具移至 extensions/canvas/src。
  • 将 Canvas 节点命令默认值从核心硬编码列表移至插件的 nodeInvokePolicies。
  • 在 plugins.entries.canvas.config.host 添加了插件自有的 Canvas 主机配置。
  • 将 Canvas 和 A2UI HTTP 服务置于 Canvas 插件的 HTTP 路由注册之后。
  • 为插件自有的 HTTP 路由添加了通用插件 WebSocket 升级分派。
  • 使用通用的托管插件界面和节点能力辅助工具，替换了 Canvas 特有的 Gateway 网关主机 URL 和节点能力身份验证。
  • 添加了插件自有的托管媒体解析器，使 Canvas 文档 URL 通过 Canvas 插件解析，而无需核心导入 Canvas 文档内部实现。
  • 添加了 api.registerNodeCliFeature(...)，使 Canvas 可以将 openclaw nodes canvas 声明为插件自有的节点功能，而无需手动写出父命令路径。
  • 移除了生产代码中从 src/** 对 extensions/canvas/runtime-api.js 的导入。
  • 将 A2UI 包源代码从 apps/shared/OpenClawKit/Tools/CanvasA2UI 移至 extensions/canvas/src/host/a2ui-app。
  • 将 A2UI 构建/复制实现移至 extensions/canvas/scripts 下，并用通用的内置插件资源钩子替换了根级构建接线。
  • 移除了运行时旧版顶层 canvasHost 配置别名。
  • 保留了 Canvas 的 Doctor 迁移，使 openclaw doctor --fix 可将旧的 canvasHost 配置重写为 plugins.entries.canvas.config.host。
  • 移除了 Gateway 网关协议 v4 下的旧版智能体 Canvas 协议兼容性。原生客户端和 Gateway 网关现在仅使用 pluginSurfaceUrls.canvas 及 node.pluginSurface.refresh；在此次实验性重构中，已弃用的 canvasHostUrl、canvasCapability 和 node.canvas.capability.refresh 路径被明确设为不受支持。
  • 更新了生成的插件清单，以纳入 Canvas。
  • 在 docs/plugins/reference/canvas.md 添加了插件参考文档。

已知仍由核心所有的 Canvas 界面：

  • apps/ 下的原生应用 Canvas 处理程序仍按设计使用 Canvas 插件界面
  • apps/ 下的原生应用 Canvas 协议/客户端处理程序
  • 为保持运行时查找的向后兼容性，已发布产物的输出仍使用 dist/canvas-host/a2ui，但复制步骤现已由插件所有

目标形态

extensions/canvas 应负责：

  • 插件清单和包元数据
  • 智能体工具注册
  • 节点调用命令策略
  • Canvas 主机和 A2UI 运行时
  • Canvas A2UI 包源代码和资源构建/复制脚本
  • Canvas 文档创建和资源解析
  • Canvas CLI 实现
  • Canvas 文档页面和插件清单条目

核心应仅负责通用接口：

  • 插件发现和注册
  • 通用智能体工具注册表
  • 通用节点调用策略注册表
  • 通用 Gateway 网关 HTTP/身份验证和 WebSocket 升级分派
  • 通用托管插件界面 URL 解析
  • 通用托管媒体解析器注册
  • 通用节点能力传输
  • 通用配置基础设施
  • 通用内置插件资源钩子发现

原生应用可以保留 Canvas 命令处理程序，作为协议客户端。它们不是插件运行时的所有者。

迁移步骤

  1. 将 plugins.entries.canvas.config.host 视为插件自有的配置界面。
  2. 更新文档，将 Canvas 描述为实验性内置插件。
  3. 运行有针对性的 Canvas 测试、插件清单检查、插件 SDK API 检查，以及受运行时边界影响的构建/类型检查关卡。

审计检查清单

在宣布重构完成之前：

  • rg "src/canvas-host|../canvas-host" 不返回任何仍在使用的源代码导入。
  • rg "canvas-tool|createCanvasTool" src 找不到任何由核心所有的 Canvas 工具实现。
  • rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway 在通用插件策略测试之外找不到任何硬编码的允许列表默认值。
  • rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts' 的结果为空。
  • rg "canvas-documents" src 的结果为空。
  • rg "registerNodesCanvasCommands|nodes-canvas" src 的结果为空；Canvas 插件通过嵌套的插件 CLI 元数据注册 openclaw nodes canvas。
  • rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway 不返回任何归 Gateway 网关运行时所有的实现。
  • rg "apps/shared/OpenClawKit/Tools/CanvasA2UI|canvas-a2ui-copy|extensions/canvas/src/host/a2ui" scripts .github package.json 仅找到兼容性包装器或插件自有路径。
  • pnpm plugins:inventory:check 通过。
  • pnpm plugin-sdk:api:check 通过，或有意更新并审查了生成的 API 基线。
  • 针对 Canvas 的测试通过。
  • Canvas 主机/A2UI 路径的变更通道测试通过。
  • PR 正文明确说明 Canvas 是实验性的，并由插件提供支持。

验证命令

迭代期间使用有针对性的本地检查：

sh
pnpm test extensions/canvas/src/host/server.test.ts extensions/canvas/src/host/server.state-dir.test.ts extensions/canvas/src/host/file-resolver.test.tspnpm test src/gateway/server.plugin-node-capability-auth.test.ts src/gateway/server-import-boundary.test.tspnpm test extensions/canvas/src/config-migration.test.ts src/commands/doctor-legacy-config.migrations.test.tspnpm test test/scripts/changed-lanes.test.ts test/scripts/build-all.test.ts extensions/canvas/scripts/bundle-a2ui.test.ts test/scripts/bundled-plugin-assets.test.ts extensions/canvas/scripts/copy-a2ui.test.ts src/infra/run-node.test.tspnpm tsgo:extensionspnpm plugins:inventory:checkpnpm plugin-sdk:api:check

如果运行时导出入口、延迟导入、打包或已发布的插件界面发生变化，请在推送前运行 pnpm build。

Was this useful?
On this page

On this page