Рефакторинг плагіна Canvas

Canvas використовується рідко та є експериментальним. Розглядайте його як вбудований плагін, а не як основну функцію. У ядрі можна залишити універсальну інфраструктуру Gateway, Node, HTTP, автентифікації, конфігурації та нативного клієнта, але специфічна для Canvas поведінка має міститися в extensions/canvas.

Мета

Перенести відповідальність за Canvas до extensions/canvas, зберігши поточну поведінку спареного вузла:

• орієнтований на агента інструмент canvas реєструється плагіном Canvas
• команди вузла Canvas дозволені лише тоді, коли їх реєструє плагін Canvas
• файли хоста й вихідного коду A2UI містяться в плагіні Canvas
• матеріалізація документів Canvas виконується в плагіні Canvas
• реалізація команди CLI міститься в плагіні Canvas або делегується через належний плагіну експортний модуль середовища виконання
• документація та реєстр плагінів описують Canvas як експериментальну функцію на основі плагіна

Поза межами завдання

• Не змінюйте дизайн інтерфейсу Canvas у нативному застосунку в межах цього рефакторингу.
• Не видаляйте підтримку протоколу або клієнта Canvas з iOS, Android чи macOS, якщо окреме продуктове рішення не передбачає видалення Canvas.
• Не створюйте широку сервісну інфраструктуру для плагінів лише заради Canvas, якщо принаймні одному іншому вбудованому плагіну не потрібен такий самий механізм інтеграції.

Поточний стан гілки

Виконано:

• Додано пакет вбудованого плагіна в extensions/canvas.
• Додано extensions/canvas/openclaw.plugin.json.
• Інструмент агента canvas перенесено з src/agents/tools/canvas-tool.ts до extensions/canvas/src/tool.ts.
• Видалено реєстрацію createCanvasTool у ядрі з src/agents/openclaw-tools.ts.
• Реалізацію хоста Canvas перенесено з src/canvas-host до extensions/canvas/src/host.
• extensions/canvas/runtime-api.ts збережено як належний плагіну експортний модуль сумісності для тестів, пакування та зовнішніх загальнодоступних допоміжних засобів Canvas.
• Матеріалізацію документів Canvas перенесено з src/gateway/canvas-documents.ts до extensions/canvas/src/documents.ts.
• Реалізацію CLI Canvas і допоміжні засоби JSONL для A2UI перенесено до extensions/canvas/src/cli.ts.
• URL-адресу хоста Canvas і допоміжні засоби можливостей з обмеженою областю дії перенесено до extensions/canvas/src.
• Стандартні команди вузла Canvas видалено із жорстко заданих списків ядра та перенесено до nodeInvokePolicies плагіна.
• Додано належну плагіну конфігурацію хоста Canvas у plugins.entries.canvas.config.host.
• Обслуговування Canvas і A2UI через HTTP перенесено за реєстрацію HTTP-маршрутів плагіна Canvas.
• Додано універсальну диспетчеризацію оновлення з’єднання WebSocket для належних плагінам HTTP-маршрутів.
• Специфічні для Canvas URL-адресу хоста Gateway й авторизацію можливостей вузла замінено універсальною розміщеною поверхнею плагіна та допоміжними засобами можливостей вузла.
• Додано належні плагіну засоби вирішення розміщених медіаресурсів, щоб URL-адреси документів Canvas визначалися через плагін Canvas, а ядро не імпортувало внутрішні компоненти документів Canvas.
• Додано api.registerNodeCliFeature(...), щоб Canvas міг оголошувати openclaw nodes canvas як належну плагіну функцію вузла без ручного зазначення шляху батьківської команди.
• Видалено імпорти extensions/canvas/runtime-api.js з робочого коду src/**.
• Вихідний код пакета A2UI перенесено з apps/shared/OpenClawKit/Tools/CanvasA2UI до extensions/canvas/src/host/a2ui-app.
• Реалізацію збирання та копіювання A2UI перенесено до extensions/canvas/scripts, а кореневі налаштування збирання замінено універсальними обробниками ресурсів вбудованих плагінів.
• Видалено застарілий псевдонім конфігурації верхнього рівня canvasHost із середовища виконання.
• Збережено міграцію Canvas у засобі діагностики, щоб openclaw doctor --fix перетворював старі конфігурації canvasHost на plugins.entries.canvas.config.host.
• Видалено сумісність протоколу Canvas зі старими агентами, яка існувала до версії 4 протоколу Gateway. Нативні клієнти та Gateway тепер використовують лише pluginSurfaceUrls.canvas разом із node.pluginSurface.refresh; застарілий шлях canvasHostUrl, canvasCapability і node.canvas.capability.refresh навмисно не підтримується в цьому експериментальному рефакторингу.
• Оновлено згенерований реєстр плагінів, додавши Canvas.
• Додано довідкову документацію плагіна в docs/plugins/reference/canvas.md.

Відомі поверхні Canvas, за які досі відповідає ядро:

• Обробники Canvas у нативних застосунках у apps/ усе ще навмисно використовують поверхню плагіна Canvas
• обробники протоколу та клієнта Canvas у нативних застосунках у apps/
• вихідні дані опублікованого артефакту досі використовують dist/canvas-host/a2ui для зворотно сумісного пошуку під час виконання, але етап копіювання тепер належить плагіну

Цільова структура

extensions/canvas має відповідати за:

• маніфест плагіна та метадані пакета
• реєстрацію інструмента агента
• політику виклику команд вузла
• хост Canvas і середовище виконання A2UI
• вихідний код пакета Canvas A2UI та сценарії збирання й копіювання ресурсів
• створення документів Canvas і визначення ресурсів
• реалізацію CLI Canvas
• сторінку документації Canvas і запис у реєстрі плагінів

Ядро має відповідати лише за універсальні механізми інтеграції:

• виявлення та реєстрацію плагінів
• універсальний реєстр інструментів агента
• універсальний реєстр політик виклику вузлів
• універсальну диспетчеризацію HTTP/автентифікації Gateway та оновлення з’єднання WebSocket
• універсальне визначення URL-адрес розміщених поверхонь плагінів
• універсальну реєстрацію засобів визначення розміщених медіаресурсів
• універсальний транспорт можливостей вузла
• універсальну інфраструктуру конфігурації
• універсальне виявлення обробників ресурсів вбудованих плагінів

Нативні застосунки можуть зберігати обробники команд Canvas як клієнти протоколу. Вони не є власниками середовища виконання плагіна.

Етапи міграції

1. Розглядайте plugins.entries.canvas.config.host як належну плагіну поверхню конфігурації.
2. Оновіть документацію, щоб Canvas описувався як експериментальний вбудований плагін.
3. Запустіть цільові тести Canvas, перевірки реєстру плагінів, перевірки API SDK плагінів і перевірки збирання та типів, на які вплинули межі середовища виконання.

Контрольний список аудиту

Перш ніж вважати рефакторинг завершеним:

• rg "src/canvas-host|../canvas-host" не повертає активних імпортів вихідного коду.
• rg "canvas-tool|createCanvasTool" src не знаходить у ядрі реалізації інструмента Canvas.
• rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway не знаходить жорстко заданих стандартних списків дозволів поза тестами універсальної політики плагінів.
• Результат rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts' порожній.
• Результат rg "canvas-documents" src порожній.
• Результат rg "registerNodesCanvasCommands|nodes-canvas" src порожній; плагін Canvas реєструє openclaw nodes canvas через вкладені метадані CLI плагіна.
• rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway не повертає компонентів середовища виконання Gateway, які відповідають за цю функціональність.
• rg "apps/shared/OpenClawKit/Tools/CanvasA2UI|canvas-a2ui-copy|extensions/canvas/src/host/a2ui" scripts .github package.json знаходить лише обгортки сумісності або належні плагіну шляхи.
• pnpm plugins:inventory:check виконується успішно.
• pnpm plugin-sdk:api:check виконується успішно, або згенеровані базові версії API навмисно оновлено та перевірено.
• Цільові тести Canvas виконуються успішно.
• Тести змінених напрямів для шляхів хоста Canvas/A2UI виконуються успішно.
• У тексті PR прямо зазначено, що Canvas є експериментальним і працює на основі плагіна.

Команди перевірки

Під час ітерацій використовуйте цільові локальні перевірки:

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

Запустіть pnpm build перед надсиланням змін, якщо змінюються експортний модуль середовища виконання, відкладений імпорт, пакування або опубліковані поверхні плагіна.