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

# Refaktorierung des Canvas-Plugins

# Refactoring des Canvas-Plugins

Canvas wird wenig genutzt und ist experimentell. Behandeln Sie es als mitgeliefertes Plugin, nicht als Core-Funktion. Der Core darf generische Gateway-, Node-, HTTP-, Authentifizierungs-, Config- und Native-Client-Infrastruktur behalten, Canvas-spezifisches Verhalten sollte jedoch unter `extensions/canvas` liegen.

## Ziel

Die Zuständigkeit für Canvas nach `extensions/canvas` verschieben und dabei das aktuelle Verhalten gekoppelter Nodes beibehalten:

* das agentenseitige `canvas`-Tool wird vom Canvas-Plugin registriert
* Canvas-Node-Befehle sind nur erlaubt, wenn das Canvas-Plugin sie registriert
* A2UI-Host-/Quelldateien liegen unter dem Canvas-Plugin
* Canvas-Dokumentmaterialisierung liegt unter dem Canvas-Plugin
* die CLI-Befehlsimplementierung liegt unter dem Canvas-Plugin oder delegiert über ein Plugin-eigenes Runtime-Barrel
* Dokumentation und Plugin-Inventar beschreiben Canvas als experimentell und Plugin-gestützt

## Nichtziele

* Die native App-Canvas-UI in diesem Refactoring nicht neu entwerfen.
* Canvas-Protokoll-/Client-Unterstützung nicht aus iOS, Android oder macOS entfernen, es sei denn, eine separate Produktentscheidung besagt, dass Canvas gelöscht werden soll.
* Kein breites Plugin-Service-Framework nur für Canvas bauen, es sei denn, mindestens ein anderes mitgeliefertes Plugin benötigt dieselbe Schnittstelle.

## Aktueller Branch-Zustand

Erledigt:

* Mitgeliefertes Plugin-Paket in `extensions/canvas` hinzugefügt.
* `extensions/canvas/openclaw.plugin.json` hinzugefügt.
* Das Agent-`canvas`-Tool von `src/agents/tools/canvas-tool.ts` nach `extensions/canvas/src/tool.ts` verschoben.
* Core-Registrierung von `createCanvasTool` aus `src/agents/openclaw-tools.ts` entfernt.
* Canvas-Host-Implementierung von `src/canvas-host` nach `extensions/canvas/src/host` verschoben.
* `extensions/canvas/runtime-api.ts` als Plugin-eigenes Kompatibilitäts-Barrel für Tests, Paketierung und externe öffentliche Canvas-Hilfsfunktionen beibehalten.
* Canvas-Dokumentmaterialisierung von `src/gateway/canvas-documents.ts` nach `extensions/canvas/src/documents.ts` verschoben.
* Canvas-CLI-Implementierung und A2UI-JSONL-Hilfsfunktionen nach `extensions/canvas/src/cli.ts` verschoben.
* Canvas-Host-URL und Hilfsfunktionen für bereichsgebundene Capabilities nach `extensions/canvas/src` verschoben.
* Canvas-Node-Befehlsdefaults aus hartcodierten Core-Listen in Plugin-`nodeInvokePolicies` verschoben.
* Plugin-eigene Canvas-Host-Config unter `plugins.entries.canvas.config.host` hinzugefügt.
* Canvas- und A2UI-HTTP-Bereitstellung hinter die HTTP-Routenregistrierung des Canvas-Plugins verschoben.
* Generisches Plugin-WebSocket-Upgrade-Dispatching für Plugin-eigene HTTP-Routen hinzugefügt.
* Canvas-spezifische Gateway-Host-URL und Node-Capability-Authentifizierung durch generische gehostete Plugin-Oberfläche und Node-Capability-Hilfsfunktionen ersetzt.
* Plugin-eigene Resolver für gehostete Medien hinzugefügt, damit Canvas-Dokument-URLs über das Canvas-Plugin aufgelöst werden, statt dass der Core Canvas-Dokumentinterna importiert.
* `api.registerNodeCliFeature(...)` hinzugefügt, damit Canvas `openclaw nodes canvas` als Plugin-eigenes Node-Feature deklarieren kann, ohne den übergeordneten Befehlspfad manuell auszuschreiben.
* Produktionsimporte von `extensions/canvas/runtime-api.js` aus `src/**` entfernt.
* Die A2UI-Bundle-Quelle von `apps/shared/OpenClawKit/Tools/CanvasA2UI` nach `extensions/canvas/src/host/a2ui-app` verschoben.
* A2UI-Build-/Copy-Implementierung unter `extensions/canvas/scripts` verschoben und Root-Build-Verdrahtung durch generische Asset-Hooks für mitgelieferte Plugins ersetzt.
* Den Runtime-Legacy-Top-Level-Config-Alias `canvasHost` entfernt.
* Canvas-Doctor-Migration beibehalten, damit `openclaw doctor --fix` alte `canvasHost`-Configs in `plugins.entries.canvas.config.host` umschreibt.
* Alte Agent-Canvas-Protokollkompatibilität hinter Gateway-Protokoll v4 entfernt. Native Clients und Gateways verwenden jetzt nur noch `pluginSurfaceUrls.canvas` plus `node.pluginSurface.refresh`; der veraltete Pfad `canvasHostUrl`, `canvasCapability` und `node.canvas.capability.refresh` wird in diesem experimentellen Refactoring absichtlich nicht unterstützt.
* Generiertes Plugin-Inventar aktualisiert, um Canvas einzuschließen.
* Plugin-Referenzdokumentation unter `docs/plugins/reference/canvas.md` hinzugefügt.

Bekannte verbleibende Core-eigene Canvas-Oberflächen:

* Native App-Canvas-Handler unter `apps/` konsumieren weiterhin absichtlich die Canvas-Plugin-Oberfläche
* Native App-Canvas-Protokoll-/Client-Handler unter `apps/`
* Die veröffentlichte Artefaktausgabe verwendet weiterhin `dist/canvas-host/a2ui` für rückwärtskompatible Runtime-Lookups, aber der Copy-Schritt ist jetzt Plugin-eigen

## Zielstruktur

`extensions/canvas` sollte Folgendes besitzen:

* Plugin-Manifest und Paketmetadaten
* Agent-Tool-Registrierung
* Node-Invoke-Befehlspolicy
* Canvas-Host und A2UI-Runtime
* Canvas-A2UI-Bundle-Quelle und Asset-Build-/Copy-Skripte
* Canvas-Dokumenterstellung und Asset-Auflösung
* Canvas-CLI-Implementierung
* Canvas-Dokumentationsseite und Plugin-Inventareintrag

Der Core sollte nur generische Schnittstellen besitzen:

* Plugin-Erkennung und -Registrierung
* generische Agent-Tool-Registry
* generische Node-Invoke-Policy-Registry
* generisches Gateway-HTTP/Auth und WebSocket-Upgrade-Dispatching
* generische URL-Auflösung für gehostete Plugin-Oberflächen
* generische Registrierung von Resolvern für gehostete Medien
* generischer Node-Capability-Transport
* generische Config-Infrastruktur
* generische Asset-Hook-Erkennung für mitgelieferte Plugins

Native Apps dürfen Canvas-Befehlshandler als Clients des Protokolls behalten. Sie sind nicht der Runtime-Eigentümer des Plugins.

## Migrationsschritte

1. `plugins.entries.canvas.config.host` als Plugin-eigene Config-Oberfläche behandeln.
2. Dokumentation aktualisieren, sodass Canvas als experimentelles mitgeliefertes Plugin beschrieben wird.
3. Fokussierte Canvas-Tests, Plugin-Inventarprüfungen, Plugin-SDK-API-Prüfungen sowie Build-/Typ-Gates ausführen, die von Runtime-Grenzen betroffen sind.

## Audit-Checkliste

Bevor das Refactoring als abgeschlossen gilt:

* `rg "src/canvas-host|../canvas-host"` gibt keine Live-Quellimporte zurück.
* `rg "canvas-tool|createCanvasTool" src` findet keine Core-eigene Canvas-Tool-Implementierung.
* `rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway` findet keine hartcodierten Allowlist-Defaults außerhalb generischer Plugin-Policy-Tests.
* `rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts'` ist leer.
* `rg "canvas-documents" src` ist leer.
* `rg "registerNodesCanvasCommands|nodes-canvas" src` ist leer; das Canvas-Plugin registriert `openclaw nodes canvas` über verschachtelte Plugin-CLI-Metadaten.
* `rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway` gibt keine Gateway-Runtime-Zuständigkeit zurück.
* `rg "apps/shared/OpenClawKit/Tools/CanvasA2UI|canvas-a2ui-copy|extensions/canvas/src/host/a2ui" scripts .github package.json` findet nur Kompatibilitäts-Wrapper oder Plugin-eigene Pfade.
* `pnpm plugins:inventory:check` besteht.
* `pnpm plugin-sdk:api:check` besteht, oder generierte API-Baselines werden absichtlich aktualisiert und überprüft.
* Zielgerichtete Canvas-Tests bestehen.
* Changed-Lanes-Tests für Canvas-Host-/A2UI-Pfade bestehen.
* Der PR-Body sagt ausdrücklich, dass Canvas experimentell und Plugin-gestützt ist.

## Verifizierungsbefehle

Verwenden Sie beim Iterieren zielgerichtete lokale Prüfungen:

```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
```

Führen Sie `pnpm build` vor dem Push aus, wenn sich Runtime-Barrel, Lazy Import, Paketierung oder veröffentlichte Plugin-Oberflächen ändern.