Refactorisation du plugin Canvas

Canvas est peu utilisé et expérimental. Traitez-le comme un plugin intégré, et non comme une fonctionnalité du cœur. Le cœur peut conserver la plomberie générique du Gateway, des nœuds, de HTTP, de l’authentification, de la configuration et des clients natifs, mais le comportement propre à Canvas doit résider sous extensions/canvas.

Objectif

Transférer la responsabilité de Canvas à extensions/canvas tout en préservant le comportement actuel des nœuds appairés :

• l’outil canvas destiné à l’agent est enregistré par le plugin Canvas
• les commandes de nœud Canvas ne sont autorisées que lorsque le plugin Canvas les enregistre
• les fichiers hôtes/sources A2UI résident sous le plugin Canvas
• la matérialisation des documents Canvas réside sous le plugin Canvas
• l’implémentation de la commande CLI réside sous le plugin Canvas, ou délègue via un barrel d’exécution appartenant au plugin
• la documentation et l’inventaire des plugins décrivent Canvas comme expérimental et fondé sur un plugin

Hors objectifs

• Ne pas reconcevoir l’interface utilisateur Canvas de l’application native dans le cadre de cette refactorisation.
• Ne pas supprimer la prise en charge du protocole/client Canvas sur iOS, Android ou macOS, sauf si une décision produit distincte prévoit la suppression de Canvas.
• Ne pas créer un vaste framework de services pour plugins uniquement pour Canvas, sauf si au moins un autre plugin intégré nécessite la même interface.

État actuel de la branche

Terminé :

• Ajout du paquet de plugin intégré dans extensions/canvas.
• Ajout de extensions/canvas/openclaw.plugin.json.
• Déplacement de l’outil agent canvas de src/agents/tools/canvas-tool.ts vers extensions/canvas/src/tool.ts.
• Suppression de l’enregistrement dans le cœur de createCanvasTool depuis src/agents/openclaw-tools.ts.
• Déplacement de l’implémentation de l’hôte Canvas de src/canvas-host vers extensions/canvas/src/host.
• Conservation de extensions/canvas/runtime-api.ts comme barrel de compatibilité appartenant au plugin pour les tests, le conditionnement et les fonctions d’assistance Canvas publiques externes.
• Déplacement de la matérialisation des documents Canvas de src/gateway/canvas-documents.ts vers extensions/canvas/src/documents.ts.
• Déplacement de l’implémentation de la CLI Canvas et des fonctions d’assistance JSONL A2UI vers extensions/canvas/src/cli.ts.
• Déplacement de l’URL de l’hôte Canvas et des fonctions d’assistance de capacité à portée limitée vers extensions/canvas/src.
• Déplacement des valeurs par défaut des commandes de nœud Canvas hors des listes codées en dur du cœur vers les nodeInvokePolicies du plugin.
• Ajout d’une configuration de l’hôte Canvas appartenant au plugin dans plugins.entries.canvas.config.host.
• Déplacement de la mise à disposition HTTP de Canvas et d’A2UI derrière l’enregistrement des routes HTTP du plugin Canvas.
• Ajout d’un routage générique des mises à niveau WebSocket de plugin pour les routes HTTP appartenant aux plugins.
• Remplacement de l’URL d’hôte et de l’authentification des capacités de nœud propres à Canvas dans le Gateway par des fonctions d’assistance génériques pour les surfaces de plugin hébergées et les capacités de nœud.
• Ajout de résolveurs de médias hébergés appartenant au plugin afin que les URL des documents Canvas soient résolues par le plugin Canvas au lieu que le cœur importe les composants internes des documents Canvas.
• Ajout de api.registerNodeCliFeature(...) afin que Canvas puisse déclarer openclaw nodes canvas comme une fonctionnalité de nœud appartenant au plugin sans devoir spécifier manuellement le chemin de la commande parente.
• Suppression des importations de production de extensions/canvas/runtime-api.js depuis src/**.
• Déplacement de la source du bundle A2UI de apps/shared/OpenClawKit/Tools/CanvasA2UI vers extensions/canvas/src/host/a2ui-app.
• Déplacement de l’implémentation de la compilation/copie A2UI sous extensions/canvas/scripts et remplacement du câblage de compilation à la racine par des hooks génériques de ressources de plugins intégrés.
• Suppression de l’alias de configuration d’exécution hérité de premier niveau canvasHost.
• Conservation de la migration Canvas de doctor afin que openclaw doctor --fix réécrive les anciennes configurations canvasHost en plugins.entries.canvas.config.host.
• Suppression de la compatibilité du protocole Canvas avec les anciens agents derrière la version 4 du protocole Gateway. Les clients natifs et les Gateways utilisent désormais uniquement pluginSurfaceUrls.canvas ainsi que node.pluginSurface.refresh ; le chemin obsolète canvasHostUrl, canvasCapability et node.canvas.capability.refresh n’est intentionnellement pas pris en charge dans cette refactorisation expérimentale.
• Mise à jour de l’inventaire généré des plugins pour inclure Canvas.
• Ajout de la documentation de référence du plugin dans docs/plugins/reference/canvas.md.

Surfaces Canvas restantes connues appartenant au cœur :

• les gestionnaires Canvas de l’application native sous apps/ continuent intentionnellement de consommer la surface du plugin Canvas
• les gestionnaires de protocole/client Canvas de l’application native sous apps/
• la sortie de l’artefact publié utilise encore dist/canvas-host/a2ui pour une recherche d’exécution rétrocompatible, mais l’étape de copie appartient désormais au plugin

Structure cible

extensions/canvas doit posséder :

• le manifeste du plugin et les métadonnées du paquet
• l’enregistrement de l’outil agent
• la politique des commandes d’invocation de nœud
• l’hôte Canvas et l’exécution A2UI
• la source du bundle A2UI de Canvas et les scripts de compilation/copie des ressources
• la création de documents Canvas et la résolution des ressources
• l’implémentation de la CLI Canvas
• la page de documentation Canvas et l’entrée dans l’inventaire des plugins

Le cœur ne doit posséder que des interfaces génériques :

• la découverte et l’enregistrement des plugins
• le registre générique des outils d’agent
• le registre générique des politiques d’invocation de nœud
• l’authentification HTTP générique du Gateway et le routage des mises à niveau WebSocket
• la résolution générique des URL de surfaces de plugin hébergées
• l’enregistrement générique des résolveurs de médias hébergés
• le transport générique des capacités de nœud
• la plomberie générique de configuration
• la découverte générique des hooks de ressources de plugins intégrés

Les applications natives peuvent conserver les gestionnaires de commandes Canvas en tant que clients du protocole. Elles ne sont pas responsables de l’exécution du plugin.

Étapes de migration

1. Traiter plugins.entries.canvas.config.host comme la surface de configuration appartenant au plugin.
2. Mettre à jour la documentation afin que Canvas soit décrit comme un plugin intégré expérimental.
3. Exécuter les tests Canvas ciblés, les vérifications de l’inventaire des plugins, les vérifications de l’API du SDK de plugin et les contrôles de compilation/types affectés par les limites d’exécution.

Liste de contrôle d’audit

Avant de déclarer la refactorisation terminée :

• rg "src/canvas-host|../canvas-host" ne renvoie aucune importation active dans le code source.
• rg "canvas-tool|createCanvasTool" src ne trouve aucune implémentation de l’outil Canvas appartenant au cœur.
• rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway ne trouve aucune valeur par défaut de liste d’autorisation codée en dur en dehors des tests génériques de politique de plugin.
• rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts' ne renvoie rien.
• rg "canvas-documents" src ne renvoie rien.
• rg "registerNodesCanvasCommands|nodes-canvas" src ne renvoie rien ; le plugin Canvas enregistre openclaw nodes canvas au moyen de métadonnées CLI de plugin imbriquées.
• rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway ne renvoie aucune responsabilité d’exécution du Gateway.
• rg "apps/shared/OpenClawKit/Tools/CanvasA2UI|canvas-a2ui-copy|extensions/canvas/src/host/a2ui" scripts .github package.json ne trouve que des wrappers de compatibilité ou des chemins appartenant au plugin.
• pnpm plugins:inventory:check réussit.
• pnpm plugin-sdk:api:check réussit, ou les références de base de l’API générées sont intentionnellement mises à jour et examinées.
• Les tests Canvas ciblés réussissent.
• Les tests des ensembles modifiés réussissent pour les chemins de l’hôte Canvas/A2UI.
• Le corps de la PR indique explicitement que Canvas est expérimental et fondé sur un plugin.

Commandes de vérification

Utilisez des vérifications locales ciblées pendant les itérations :

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

Exécutez pnpm build avant le push si le barrel d’exécution, l’importation différée, le conditionnement ou les surfaces publiées du plugin changent.