> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Refatoração do Plugin Canvas

# 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:

```sh theme={"theme":{"light":"min-light","dark":"min-dark"}}
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.