# Refactorisation du plugin Canvas

Canvas est peu utilisé et expérimental. Traitez-le comme un plugin groupé, 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 du client natif, mais le comportement propre à Canvas doit résider sous extensions/canvas.

# Objectif

Déplacer la responsabilité de Canvas vers extensions/canvas tout en préservant le comportement actuel des nœuds appairés :

• l’outil canvas exposé à 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ôte/source 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 adossé à un plugin

# Non-objectifs

• Ne pas reconcevoir l’interface utilisateur Canvas de l’application native dans cette refactorisation.
• Ne pas supprimer la prise en charge du protocole/client Canvas d’iOS, Android ou macOS, sauf si une décision produit distincte indique que Canvas doit être supprimé.
• Ne pas construire un vaste framework de service de plugins uniquement pour Canvas, sauf si au moins un autre plugin groupé a besoin du même raccord.

# État actuel de la branche

Terminé :

• Ajout d’un paquet de plugin groupé dans extensions/canvas.
• Ajout de extensions/canvas/openclaw.plugin.json.
• Déplacement de l’outil d’agent canvas de src/agents/tools/canvas-tool.ts vers extensions/canvas/src/tool.ts.
• Suppression de l’enregistrement 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 packaging et les helpers Canvas publics 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 CLI Canvas et des helpers JSONL A2UI dans extensions/canvas/src/cli.ts.
• Déplacement de l’URL de l’hôte Canvas et des helpers de capacité à portée limitée dans extensions/canvas/src.
• Déplacement des valeurs par défaut des commandes de nœud Canvas hors des listes du cœur codées en dur et vers nodeInvokePolicies du plugin.
• Ajout de la configuration de l’hôte Canvas appartenant au plugin à plugins.entries.canvas.config.host.
• Déplacement du service HTTP Canvas et A2UI derrière l’enregistrement des routes HTTP du plugin Canvas.
• Ajout d’un dispatch générique de mise à niveau WebSocket de plugin pour les routes HTTP appartenant aux plugins.
• Remplacement de l’URL d’hôte de Gateway propre à Canvas et de l’authentification par capacité de nœud par une surface de plugin hébergée générique et des helpers de capacité de nœud.
• Ajout de résolveurs de médias hébergés appartenant au plugin, afin que les URL de documents Canvas soient résolues via le plugin Canvas au lieu que le cœur importe les éléments internes des documents Canvas.
• Ajout de api.registerNodeCliFeature(...) afin que Canvas puisse déclarer openclaw nodes canvas comme fonctionnalité de nœud appartenant au plugin sans écrire manuellement le chemin de la commande parente.
• Suppression des imports de production src/** de extensions/canvas/runtime-api.js.
• 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 construction/copie A2UI sous extensions/canvas/scripts et remplacement du câblage de construction racine par des hooks génériques d’actifs de plugins groupés.
• Suppression de l’alias de configuration historique d’exécution de niveau supérieur canvasHost.
• Conservation de la migration doctor Canvas afin que openclaw doctor --fix réécrive les anciennes configurations canvasHost en plugins.entries.canvas.config.host.
• Suppression de la compatibilité de protocole Canvas des anciens agents derrière le protocole Gateway v4. Les clients natifs et les gateways utilisent désormais uniquement pluginSurfaceUrls.canvas plus node.pluginSurface.refresh ; les chemins obsolètes canvasHostUrl, canvasCapability et node.canvas.capability.refresh sont intentionnellement non 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 à docs/plugins/reference/canvas.md.

Surfaces Canvas connues qui restent détenues par le cœur :

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

# Forme cible

extensions/canvas doit posséder :

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

Le cœur ne doit posséder que des raccords 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
• le dispatch générique HTTP/auth et de mise à niveau WebSocket du Gateway
• la résolution générique des URL de surface de plugin hébergée
• 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 d’actifs de plugins groupés

Les applications natives peuvent conserver les gestionnaires de commandes Canvas comme clients du protocole. Elles ne sont pas propriétaires 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 groupé expérimental.
3. Exécuter les tests Canvas ciblés, les vérifications d’inventaire des plugins, les vérifications d’API du SDK de plugin, ainsi que les gates de build/type affectés par les frontières d’exécution.

# Liste d’audit

Avant de considérer la refactorisation comme terminée :

• rg "src/canvas-host|../canvas-host" ne renvoie aucun import de source actif.
• rg "canvas-tool|createCanvasTool" src ne trouve aucune implémentation d’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 hors des tests de politique générique de plugin.
• rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts' est vide.
• rg "canvas-documents" src est vide.
• rg "registerNodesCanvasCommands|nodes-canvas" src est vide ; le plugin Canvas enregistre openclaw nodes canvas via les métadonnées CLI imbriquées du plugin.
• rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway ne renvoie aucune propriété d’exécution 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 baselines d’API générées sont mises à jour et relues intentionnellement.
• Les tests Canvas ciblés réussissent.
• Les tests changed-lanes réussissent pour les chemins hôte Canvas/A2UI.
• Le corps de la PR indique explicitement que Canvas est expérimental et adossé à un plugin.

# Commandes de vérification

Utilisez des vérifications locales ciblées pendant l’itération :

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

Exécutez pnpm build avant de pousser si le barrel d’exécution, l’import paresseux, le packaging ou les surfaces de plugin publiées changent.