> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

# Рефакторинг плагіна 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 є експериментальним і працює на основі плагіна.

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

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

```sh theme={"theme":{"light":"min-light","dark":"min-dark"}}
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` перед надсиланням змін, якщо змінюються експортний модуль середовища виконання, відкладений імпорт, пакування або опубліковані поверхні плагіна.