Refaktorierung des Canvas-Plugins

Canvas wird wenig genutzt und ist experimentell. Behandeln Sie es als gebündeltes Plugin, nicht als Kernfunktion. Der Kern darf generische Gateway-, Node-, HTTP-, Authentifizierungs-, Konfigurations- und Native-Client-Infrastruktur beibehalten, Canvas-spezifisches Verhalten sollte jedoch unter extensions/canvas liegen.

Ziel

Verlagern Sie die Zuständigkeit für Canvas nach extensions/canvas und bewahren Sie dabei das aktuelle Verhalten gekoppelter Nodes:

• Das agentenseitige Werkzeug canvas wird vom Canvas-Plugin registriert.
• Canvas-Node-Befehle sind nur zulässig, wenn das Canvas-Plugin sie registriert.
• A2UI-Host-/Quelldateien liegen unter dem Canvas-Plugin.
• Die Materialisierung von Canvas-Dokumenten liegt unter dem Canvas-Plugin.
• Die Implementierung des CLI-Befehls 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

• Gestalten Sie die Canvas-Benutzeroberfläche der nativen App bei dieser Refaktorierung nicht neu.
• Entfernen Sie die Canvas-Protokoll-/Client-Unterstützung nicht aus iOS, Android oder macOS, sofern nicht eine separate Produktentscheidung die Löschung von Canvas vorsieht.
• Erstellen Sie nicht allein für Canvas ein umfassendes Plugin-Service-Framework, sofern nicht mindestens ein weiteres gebündeltes Plugin dieselbe Schnittstelle benötigt.

Aktueller Branch-Stand

Erledigt:

• Gebündeltes Plugin-Paket in extensions/canvas hinzugefügt.
• extensions/canvas/openclaw.plugin.json hinzugefügt.
• Das Agentenwerkzeug canvas von src/agents/tools/canvas-tool.ts nach extensions/canvas/src/tool.ts verschoben.
• Die Kernregistrierung von createCanvasTool aus src/agents/openclaw-tools.ts entfernt.
• Die 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.
• Die Materialisierung von Canvas-Dokumenten von src/gateway/canvas-documents.ts nach extensions/canvas/src/documents.ts verschoben.
• Die Canvas-CLI-Implementierung und A2UI-JSONL-Hilfsfunktionen nach extensions/canvas/src/cli.ts verschoben.
• Die Canvas-Host-URL und Hilfsfunktionen für bereichsbezogene Fähigkeiten nach extensions/canvas/src verschoben.
• Die Standardwerte für Canvas-Node-Befehle aus fest codierten Kernlisten in die Plugin-nodeInvokePolicies verschoben.
• Plugin-eigene Canvas-Host-Konfiguration unter plugins.entries.canvas.config.host hinzugefügt.
• Die HTTP-Bereitstellung von Canvas und A2UI hinter die HTTP-Routenregistrierung des Canvas-Plugins verschoben.
• Generische Plugin-WebSocket-Upgrade-Weiterleitung für Plugin-eigene HTTP-Routen hinzugefügt.
• Die Canvas-spezifische Gateway-Host-URL und Authentifizierung von Node-Fähigkeiten durch generische gehostete Plugin-Oberflächen und Hilfsfunktionen für Node-Fähigkeiten ersetzt.
• Plugin-eigene Resolver für gehostete Medien hinzugefügt, sodass Canvas-Dokument-URLs über das Canvas-Plugin aufgelöst werden, anstatt dass der Kern interne Canvas-Dokumentimplementierungen importiert.
• api.registerNodeCliFeature(...) hinzugefügt, sodass Canvas openclaw nodes canvas als Plugin-eigene Node-Funktion deklarieren kann, ohne den Pfad des übergeordneten Befehls manuell anzugeben.
• Produktive Importe von extensions/canvas/runtime-api.js aus src/** entfernt.
• Die Quelle des A2UI-Bundles von apps/shared/OpenClawKit/Tools/CanvasA2UI nach extensions/canvas/src/host/a2ui-app verschoben.
• Die A2UI-Build-/Kopierimplementierung nach extensions/canvas/scripts verschoben und die Build-Verknüpfung im Stammverzeichnis durch generische Asset-Hooks für gebündelte Plugins ersetzt.
• Den veralteten Top-Level-Konfigurationsalias canvasHost aus der Runtime entfernt.
• Die Canvas-Doctor-Migration beibehalten, sodass openclaw doctor --fix alte canvasHost-Konfigurationen in plugins.entries.canvas.config.host umschreibt.
• Die Canvas-Protokollkompatibilität für alte Agenten hinter Gateway-Protokoll v4 entfernt. Native Clients und Gateways verwenden jetzt ausschließlich pluginSurfaceUrls.canvas zusammen mit node.pluginSurface.refresh; der veraltete Pfad über canvasHostUrl, canvasCapability und node.canvas.capability.refresh wird bei dieser experimentellen Refaktorierung bewusst nicht unterstützt.
• Das generierte Plugin-Inventar um Canvas ergänzt.
• Plugin-Referenzdokumentation unter docs/plugins/reference/canvas.md hinzugefügt.

Bekannte verbleibende Canvas-Oberflächen im Besitz des Kerns:

• Canvas-Handler nativer Apps unter apps/ verwenden weiterhin bewusst die Oberfläche des Canvas-Plugins.
• Canvas-Protokoll-/Client-Handler nativer Apps unter apps/.
• Die Ausgabe veröffentlichter Artefakte verwendet für abwärtskompatible Runtime-Auflösung weiterhin dist/canvas-host/a2ui, der Kopierschritt ist nun jedoch Plugin-eigen.

Zielstruktur

extensions/canvas sollte für Folgendes zuständig sein:

• Plugin-Manifest und Paketmetadaten
• Registrierung des Agentenwerkzeugs
• Richtlinie für Node-Aufrufbefehle
• Canvas-Host und A2UI-Runtime
• Quelle des Canvas-A2UI-Bundles und Asset-Build-/Kopierskripte
• Erstellung von Canvas-Dokumenten und Asset-Auflösung
• Canvas-CLI-Implementierung
• Canvas-Dokumentationsseite und Eintrag im Plugin-Inventar

Der Kern sollte nur für generische Schnittstellen zuständig sein:

• Plugin-Erkennung und -Registrierung
• generische Registrierung von Agentenwerkzeugen
• generische Registrierung von Richtlinien für Node-Aufrufe
• generische Gateway-HTTP-/Authentifizierungs- und WebSocket-Upgrade-Weiterleitung
• generische URL-Auflösung für gehostete Plugin-Oberflächen
• generische Registrierung von Resolvern für gehostete Medien
• generischer Transport von Node-Fähigkeiten
• generische Konfigurationsinfrastruktur
• generische Erkennung von Asset-Hooks gebündelter Plugins

Native Apps dürfen Canvas-Befehlshandler als Clients des Protokolls beibehalten. Sie sind nicht für die Plugin-Runtime zuständig.

Migrationsschritte

1. Behandeln Sie plugins.entries.canvas.config.host als Plugin-eigene Konfigurationsoberfläche.
2. Aktualisieren Sie die Dokumentation, sodass Canvas als experimentelles gebündeltes Plugin beschrieben wird.
3. Führen Sie gezielte Canvas-Tests, Prüfungen des Plugin-Inventars, Prüfungen der Plugin-SDK-API sowie Build-/Typprüfungen aus, die von Runtime-Grenzen betroffen sind.

Audit-Checkliste

Bevor Sie die Refaktorierung als abgeschlossen betrachten:

• rg "src/canvas-host|../canvas-host" gibt keine aktiven Quellcodeimporte zurück.
• rg "canvas-tool|createCanvasTool" src findet keine Canvas-Werkzeugimplementierung im Besitz des Kerns.
• rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway findet außerhalb generischer Tests für Plugin-Richtlinien keine fest codierten Standard-Zulassungslisten.
• rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts' gibt keine Ergebnisse zurück.
• rg "canvas-documents" src gibt keine Ergebnisse zurück.
• rg "registerNodesCanvasCommands|nodes-canvas" src gibt keine Ergebnisse zurück; das Canvas-Plugin registriert openclaw nodes canvas über verschachtelte Plugin-CLI-Metadaten.
• rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway gibt keine Zuständigkeit der Gateway-Runtime 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 wird erfolgreich ausgeführt.
• pnpm plugin-sdk:api:check wird erfolgreich ausgeführt oder generierte API-Baselines werden bewusst aktualisiert und geprüft.
• Gezielte Canvas-Tests werden erfolgreich ausgeführt.
• Tests für geänderte Lanes werden für Canvas-Host-/A2UI-Pfade erfolgreich ausgeführt.
• Der PR-Text gibt ausdrücklich an, dass Canvas experimentell und Plugin-gestützt ist.

Verifizierungsbefehle

Verwenden Sie während der Iteration gezielte lokale Prüfungen:

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

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