--- read_when: - Перенесення відповідальності за хост Canvas, інструменти, команди, документацію або протокол - Перевірка, чи Canvas усе ще належить до ядра - Підготовка або перевірка PR експериментального плагіна Canvas summary: План і контрольний список аудиту для перенесення Canvas з ядра до вбудованого експериментального плагіна. title: Рефакторинг плагіна Canvas x-i18n: generated_at: "2026-07-12T13:44:49Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 1470edb74d5f8fe96224d38821ba0b3b13f8ce756124125af64fc3e49df0fcb8 source_path: refactor/canvas.md workflow: 16 --- # Рефакторинг плагіна 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 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` перед надсиланням змін, якщо змінюються експортний модуль середовища виконання, відкладений імпорт, пакування або опубліковані поверхні плагіна.