# Рефакторинг Canvas Plugin

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

# Мета

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

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

# Нецілі

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

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

Зроблено:

• Додано пакет вбудованого Plugin у 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 як сумісний barrel, яким володіє Plugin, для тестів, пакування та зовнішніх публічних помічників Canvas.
• Переміщено матеріалізацію документів Canvas з src/gateway/canvas-documents.ts до extensions/canvas/src/documents.ts.
• Переміщено реалізацію Canvas CLI та JSONL-помічники A2UI до extensions/canvas/src/cli.ts.
• Переміщено URL хоста Canvas і scoped capability-помічники до extensions/canvas/src.
• Переміщено типові значення команд Canvas Node з жорстко закодованих списків ядра до Plugin nodeInvokePolicies.
• Додано конфігурацію хоста Canvas, якою володіє Plugin, у plugins.entries.canvas.config.host.
• Переміщено HTTP-обслуговування Canvas і A2UI за реєстрацію HTTP-маршрутів Canvas Plugin.
• Додано загальну диспетчеризацію оновлень WebSocket Plugin для HTTP-маршрутів, якими володіє Plugin.
• Замінено специфічні для Canvas URL хоста Gateway та автентифікацію capability Node на загальну поверхню розміщеного Plugin і помічники capability Node.
• Додано hosted media resolver, яким володіє Plugin, щоб URL документів Canvas розв’язувалися через Canvas Plugin, а не через імпорт ядром внутрішніх частин документів Canvas.
• Додано api.registerNodeCliFeature(...), щоб Canvas міг оголошувати openclaw nodes canvas як функцію Node, якою володіє Plugin, без ручного прописування шляху батьківської команди.
• Видалено production-імпорти extensions/canvas/runtime-api.js з src/**.
• Переміщено джерело пакета A2UI з apps/shared/OpenClawKit/Tools/CanvasA2UI до extensions/canvas/src/host/a2ui-app.
• Переміщено реалізацію збирання/копіювання A2UI під extensions/canvas/scripts і замінено кореневу прив’язку збірки загальними хуками ресурсів вбудованих Plugin.
• Видалено runtime-застарілий верхньорівневий псевдонім конфігурації canvasHost.
• Залишено міграцію Canvas doctor, щоб openclaw doctor --fix переписував старі конфігурації canvasHost у plugins.entries.canvas.config.host.
• Видалено сумісність протоколу Canvas для старих агентів за Gateway protocol v4. Нативні клієнти та Gateway тепер використовують лише pluginSurfaceUrls.canvas плюс node.pluginSurface.refresh; застарілий шлях canvasHostUrl, canvasCapability і node.canvas.capability.refresh навмисно не підтримується в цьому експериментальному рефакторингу.
• Оновлено згенерований інвентар Plugin, щоб включити Canvas.
• Додано довідкову документацію Plugin у docs/plugins/reference/canvas.md.

Відомі поверхні Canvas, якими й далі володіє ядро:

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

# Цільова форма

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

• маніфестом Plugin і метаданими пакета
• реєстрацією агентського інструмента
• політикою команд виклику Node
• хостом Canvas і runtime A2UI
• джерелом пакета Canvas A2UI і скриптами збирання/копіювання ресурсів
• створенням документів Canvas і розв’язанням ресурсів
• реалізацією Canvas CLI
• сторінкою документації Canvas і записом інвентарю Plugin

Ядро має володіти лише загальними швами:

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

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

# Кроки міграції

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

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

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

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

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

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

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

Запустіть pnpm build перед push, якщо змінюється runtime barrel, lazy import, пакування або опубліковані поверхні Plugin.