Skip to main content

​
Refatoração do Plugin Canvas

O Canvas é pouco usado e experimental. Trate-o como um Plugin integrado, não como um recurso central. O núcleo pode manter a infraestrutura genérica de Gateway, Node, HTTP, autenticação, configuração e cliente nativo, mas o comportamento específico do Canvas deve ficar em extensions/canvas.

​
Objetivo

Mover a propriedade do Canvas para extensions/canvas, preservando o comportamento atual de nós pareados:
  • a ferramenta canvas voltada para o agente é registrada pelo Plugin Canvas
  • comandos de nó do Canvas são permitidos somente quando o Plugin Canvas os registra
  • arquivos de host/fonte A2UI ficam no Plugin Canvas
  • a materialização de documentos Canvas fica no Plugin Canvas
  • a implementação de comandos da CLI fica no Plugin Canvas ou delega por meio de um barril de runtime pertencente ao Plugin
  • a documentação e o inventário de Plugins descrevem o Canvas como experimental e respaldado por Plugin

​
Não objetivos

  • Não redesenhar a UI Canvas do app nativo nesta refatoração.
  • Não remover o suporte de protocolo/cliente Canvas do iOS, Android ou macOS, a menos que uma decisão separada de produto diga que o Canvas deve ser excluído.
  • Não criar uma estrutura ampla de serviço de Plugin apenas para o Canvas, a menos que pelo menos outro Plugin integrado precise do mesmo seam.

​
Estado atual da branch

Concluído:
  • Adicionado pacote de Plugin integrado em extensions/canvas.
  • Adicionado extensions/canvas/openclaw.plugin.json.
  • Movida a ferramenta canvas do agente de src/agents/tools/canvas-tool.ts para extensions/canvas/src/tool.ts.
  • Removido o registro central de createCanvasTool de src/agents/openclaw-tools.ts.
  • Movida a implementação do host Canvas de src/canvas-host para extensions/canvas/src/host.
  • Mantido extensions/canvas/runtime-api.ts como o barril de compatibilidade pertencente ao Plugin para testes, empacotamento e helpers públicos externos do Canvas.
  • Movida a materialização de documentos Canvas de src/gateway/canvas-documents.ts para extensions/canvas/src/documents.ts.
  • Movida a implementação da CLI Canvas e helpers JSONL A2UI para extensions/canvas/src/cli.ts.
  • Movidos o URL do host Canvas e helpers de capacidade com escopo para extensions/canvas/src.
  • Movidos os padrões de comandos de nó do Canvas para fora de listas rígidas no núcleo e para nodeInvokePolicies do Plugin.
  • Adicionada configuração de host Canvas pertencente ao Plugin em plugins.entries.canvas.config.host.
  • Movido o serviço HTTP do Canvas e A2UI para trás do registro de rotas HTTP do Plugin Canvas.
  • Adicionado despacho genérico de upgrade WebSocket de Plugin para rotas HTTP pertencentes a Plugins.
  • Substituídos o URL de host Gateway específico do Canvas e a autenticação de capacidade de nó por superfície genérica de Plugin hospedado e helpers de capacidade de nó.
  • Adicionados resolvedores de mídia hospedada pertencentes ao Plugin, para que URLs de documentos Canvas sejam resolvidos pelo Plugin Canvas em vez de o núcleo importar detalhes internos de documentos Canvas.
  • Adicionado api.registerNodeCliFeature(...), para que o Canvas possa declarar openclaw nodes canvas como um recurso de nó pertencente ao Plugin sem soletrar manualmente o caminho do comando pai.
  • Removidas importações de produção src/** de extensions/canvas/runtime-api.js.
  • Movida a fonte do bundle A2UI de apps/shared/OpenClawKit/Tools/CanvasA2UI para extensions/canvas/src/host/a2ui-app.
  • Movida a implementação de build/cópia A2UI para extensions/canvas/scripts e substituída a fiação de build raiz por hooks genéricos de assets de Plugins integrados.
  • Removido o alias legado de runtime de configuração de nível superior canvasHost.
  • Mantida a migração do doctor do Canvas para que openclaw doctor --fix reescreva configurações antigas de canvasHost para plugins.entries.canvas.config.host.
  • Removida a compatibilidade de protocolo Canvas de agentes antigos atrás do protocolo Gateway v4. Clientes nativos e Gateways agora usam somente pluginSurfaceUrls.canvas mais node.pluginSurface.refresh; o caminho obsoleto canvasHostUrl, canvasCapability e node.canvas.capability.refresh é intencionalmente sem suporte nesta refatoração experimental.
  • Atualizado o inventário gerado de Plugins para incluir Canvas.
  • Adicionada documentação de referência do Plugin em docs/plugins/reference/canvas.md.
Superfícies Canvas conhecidas que ainda pertencem ao núcleo:
  • handlers Canvas do app nativo em apps/ ainda consomem intencionalmente a superfície do Plugin Canvas
  • handlers de protocolo/cliente Canvas do app nativo em apps/
  • a saída do artefato publicado ainda usa dist/canvas-host/a2ui para busca de runtime compatível com versões anteriores, mas a etapa de cópia agora pertence ao Plugin

​
Forma alvo

extensions/canvas deve possuir:
  • manifesto do Plugin e metadados do pacote
  • registro de ferramenta do agente
  • política de comando de invocação de nó
  • host Canvas e runtime A2UI
  • fonte do bundle Canvas A2UI e scripts de build/cópia de assets
  • criação de documentos Canvas e resolução de assets
  • implementação da CLI Canvas
  • página de documentação do Canvas e entrada no inventário de Plugins
O núcleo deve possuir apenas seams genéricos:
  • descoberta e registro de Plugins
  • registro genérico de ferramentas de agente
  • registro genérico de políticas de invocação de nó
  • HTTP/autenticação genéricos do Gateway e despacho de upgrade WebSocket
  • resolução genérica de URL de superfície de Plugin hospedado
  • registro genérico de resolvedor de mídia hospedada
  • transporte genérico de capacidade de nó
  • infraestrutura genérica de configuração
  • descoberta genérica de hooks de assets de Plugins integrados
Apps nativos podem manter handlers de comando Canvas como clientes do protocolo. Eles não são os proprietários do runtime do Plugin.

​
Etapas de migração

  1. Tratar plugins.entries.canvas.config.host como a superfície de configuração pertencente ao Plugin.
  2. Atualizar a documentação para que o Canvas seja descrito como um Plugin integrado experimental.
  3. Executar testes focados do Canvas, verificações de inventário de Plugins, verificações da API do SDK de Plugin e gates de build/tipos afetados pelos limites de runtime.

​
Checklist de auditoria

Antes de considerar a refatoração concluída:
  • rg "src/canvas-host|../canvas-host" não retorna importações de fonte ativas.
  • rg "canvas-tool|createCanvasTool" src não encontra implementação de ferramenta Canvas pertencente ao núcleo.
  • rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway não encontra padrões de allowlist rígidos fora de testes genéricos de política de Plugin.
  • rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts' está vazio.
  • rg "canvas-documents" src está vazio.
  • rg "registerNodesCanvasCommands|nodes-canvas" src está vazio; o Plugin Canvas registra openclaw nodes canvas por meio de metadados aninhados de CLI de Plugin.
  • rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway não retorna propriedade de runtime do Gateway.
  • rg "apps/shared/OpenClawKit/Tools/CanvasA2UI|canvas-a2ui-copy|extensions/canvas/src/host/a2ui" scripts .github package.json encontra somente wrappers de compatibilidade ou caminhos pertencentes ao Plugin.
  • pnpm plugins:inventory:check passa.
  • pnpm plugin-sdk:api:check passa, ou os baselines de API gerados são atualizados e revisados intencionalmente.
  • Testes Canvas direcionados passam.
  • Testes de lanes alteradas passam para caminhos Canvas host/A2UI.
  • O corpo do PR diz explicitamente que o Canvas é experimental e respaldado por Plugin.

​
Comandos de verificação

Use verificações locais direcionadas durante a iteração: 
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.ts
pnpm test src/gateway/server.plugin-node-capability-auth.test.ts src/gateway/server-import-boundary.test.ts
pnpm test extensions/canvas/src/config-migration.test.ts src/commands/doctor-legacy-config.migrations.test.ts
pnpm 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.ts
pnpm tsgo:extensions
pnpm plugins:inventory:check
pnpm plugin-sdk:api:check
Execute pnpm build antes do push se o barril de runtime, importação lazy, empacotamento ou superfícies publicadas do Plugin mudarem.