Refactorización del Plugin Canvas
Canvas tiene poco uso y es experimental. Trátalo como un Plugin incluido, no como una función central. El núcleo puede conservar la infraestructura genérica de Gateway, Node, HTTP, autenticación, configuración y cliente nativo, pero el comportamiento específico de Canvas debe residir bajoextensions/canvas.
Objetivo
Mover la propiedad de Canvas aextensions/canvas preservando el comportamiento actual de Node emparejado:
- la herramienta
canvasorientada al agente la registra el Plugin Canvas - los comandos de Node de Canvas solo se permiten cuando el Plugin Canvas los registra
- los archivos de host/fuente de A2UI residen bajo el Plugin Canvas
- la materialización de documentos de Canvas reside bajo el Plugin Canvas
- la implementación del comando CLI reside bajo el Plugin Canvas, o delega a través de un barrel de runtime propiedad del Plugin
- la documentación y el inventario de Plugins describen Canvas como experimental y respaldado por un Plugin
No objetivos
- No rediseñar la interfaz de usuario de Canvas de la aplicación nativa en esta refactorización.
- No eliminar la compatibilidad de protocolo/cliente de Canvas de iOS, Android o macOS salvo que una decisión de producto separada indique que Canvas debe eliminarse.
- No crear un framework amplio de servicios de Plugin solo para Canvas a menos que al menos otro Plugin incluido necesite la misma costura.
Estado actual de la rama
Hecho:- Se agregó el paquete de Plugin incluido en
extensions/canvas. - Se agregó
extensions/canvas/openclaw.plugin.json. - Se movió la herramienta
canvasdel agente desrc/agents/tools/canvas-tool.tsaextensions/canvas/src/tool.ts. - Se eliminó el registro central de
createCanvasTooldesrc/agents/openclaw-tools.ts. - Se movió la implementación del host de Canvas de
src/canvas-hostaextensions/canvas/src/host. - Se mantuvo
extensions/canvas/runtime-api.tscomo el barrel de compatibilidad propiedad del Plugin para pruebas, empaquetado y helpers públicos externos de Canvas. - Se movió la materialización de documentos de Canvas de
src/gateway/canvas-documents.tsaextensions/canvas/src/documents.ts. - Se movieron la implementación de CLI de Canvas y los helpers JSONL de A2UI a
extensions/canvas/src/cli.ts. - Se movieron la URL del host de Canvas y los helpers de capacidad con ámbito a
extensions/canvas/src. - Se movieron los valores predeterminados de comandos de Node de Canvas fuera de listas del núcleo codificadas de forma rígida y a
nodeInvokePoliciesdel Plugin. - Se agregó configuración del host de Canvas propiedad del Plugin en
plugins.entries.canvas.config.host. - Se movió el servicio HTTP de Canvas y A2UI detrás del registro de rutas HTTP del Plugin Canvas.
- Se agregó despacho genérico de actualización WebSocket de Plugin para rutas HTTP propiedad del Plugin.
- Se reemplazaron la URL de host del Gateway específica de Canvas y la autenticación de capacidades de Node por una superficie genérica de Plugin alojado y helpers de capacidad de Node.
- Se agregaron resolvedores de medios alojados propiedad del Plugin para que las URL de documentos de Canvas se resuelvan a través del Plugin Canvas en lugar de que el núcleo importe elementos internos de documentos de Canvas.
- Se agregó
api.registerNodeCliFeature(...)para que Canvas pueda declararopenclaw nodes canvascomo una función de Node propiedad del Plugin sin escribir manualmente la ruta del comando padre. - Se eliminaron las importaciones de producción
src/**deextensions/canvas/runtime-api.js. - Se movió la fuente del bundle de A2UI de
apps/shared/OpenClawKit/Tools/CanvasA2UIaextensions/canvas/src/host/a2ui-app. - Se movió la implementación de compilación/copia de A2UI bajo
extensions/canvas/scriptsy se reemplazó el cableado de compilación raíz por hooks genéricos de assets de Plugins incluidos. - Se eliminó el alias heredado de runtime de configuración de nivel superior
canvasHost. - Se mantuvo la migración de doctor de Canvas para que
openclaw doctor --fixreescriba configuraciones antiguas decanvasHostenplugins.entries.canvas.config.host. - Se eliminó la compatibilidad del protocolo de Canvas de agentes antiguos detrás del protocolo de Gateway v4. Los clientes nativos y Gateways ahora usan solo
pluginSurfaceUrls.canvasmásnode.pluginSurface.refresh; la ruta obsoletacanvasHostUrl,canvasCapabilityynode.canvas.capability.refreshno está admitida intencionadamente en esta refactorización experimental. - Se actualizó el inventario de Plugins generado para incluir Canvas.
- Se agregaron documentos de referencia del Plugin en
docs/plugins/reference/canvas.md.
- Los handlers de Canvas de la aplicación nativa bajo
apps/aún consumen intencionadamente la superficie del Plugin Canvas - handlers de protocolo/cliente de Canvas de la aplicación nativa bajo
apps/ - la salida de artefactos publicados todavía usa
dist/canvas-host/a2uipara la búsqueda de runtime compatible con versiones anteriores, pero el paso de copia ahora es propiedad del Plugin
Forma objetivo
extensions/canvas debe poseer:
- manifiesto del Plugin y metadatos del paquete
- registro de herramientas del agente
- política de comandos de invocación de Node
- host de Canvas y runtime de A2UI
- fuente del bundle de Canvas A2UI y scripts de compilación/copia de assets
- creación de documentos de Canvas y resolución de assets
- implementación de CLI de Canvas
- página de documentación de Canvas y entrada del inventario de Plugins
- descubrimiento y registro de Plugins
- registro genérico de herramientas de agente
- registro genérico de políticas de invocación de Node
- HTTP/autenticación genéricos de Gateway y despacho de actualización WebSocket
- resolución genérica de URL de superficie de Plugin alojado
- registro genérico de resolvedores de medios alojados
- transporte genérico de capacidades de Node
- infraestructura genérica de configuración
- descubrimiento genérico de hooks de assets de Plugins incluidos
Pasos de migración
- Tratar
plugins.entries.canvas.config.hostcomo la superficie de configuración propiedad del Plugin. - Actualizar la documentación para que Canvas se describa como un Plugin incluido experimental.
- Ejecutar pruebas enfocadas de Canvas, comprobaciones de inventario de Plugins, comprobaciones de API del SDK de Plugins y puertas de compilación/tipos afectadas por límites de runtime.
Lista de verificación de auditoría
Antes de dar por completa la refactorización:rg "src/canvas-host|../canvas-host"no devuelve importaciones de fuente activas.rg "canvas-tool|createCanvasTool" srcno encuentra ninguna implementación de herramienta de Canvas propiedad del núcleo.rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gatewayno encuentra valores predeterminados de allowlist codificados de forma rígida fuera de pruebas genéricas de políticas de Plugin.rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts'está vacío.rg "canvas-documents" srcestá vacío.rg "registerNodesCanvasCommands|nodes-canvas" srcestá vacío; el Plugin Canvas registraopenclaw nodes canvasmediante metadatos anidados de CLI de Plugin.rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gatewayno devuelve propiedad de runtime del Gateway.rg "apps/shared/OpenClawKit/Tools/CanvasA2UI|canvas-a2ui-copy|extensions/canvas/src/host/a2ui" scripts .github package.jsonsolo encuentra wrappers de compatibilidad o rutas propiedad del Plugin.pnpm plugins:inventory:checkpasa.pnpm plugin-sdk:api:checkpasa, o las líneas base de API generadas se actualizan y revisan intencionadamente.- Las pruebas dirigidas de Canvas pasan.
- Las pruebas de changed-lanes pasan para rutas de host/A2UI de Canvas.
- El cuerpo del PR dice explícitamente que Canvas es experimental y está respaldado por un Plugin.
Comandos de verificación
Usa comprobaciones locales dirigidas durante la iteración:pnpm build antes de hacer push si cambian el barrel de runtime, la importación diferida, el empaquetado o las superficies publicadas del Plugin.