> ## 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`. * Из `src/agents/openclaw-tools.ts` удалена регистрация `createCanvasTool` в ядре. * Реализация хоста 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 и вспомогательные функции A2UI JSONL перенесены в `extensions/canvas/src/cli.ts`. * URL хоста Canvas и вспомогательные функции ограниченных по области возможностей перенесены в `extensions/canvas/src`. * Настройки команд узла Canvas по умолчанию вынесены из жёстко заданных списков ядра в `nodeInvokePolicies` плагина. * Добавлена принадлежащая плагину конфигурация хоста Canvas в `plugins.entries.canvas.config.host`. * Обслуживание HTTP для Canvas и A2UI перенесено за регистрацию 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 в doctor, чтобы `openclaw doctor --fix` преобразовывал старые конфигурации `canvasHost` в `plugins.entries.canvas.config.host`. * Удалена совместимость протокола Canvas со старыми агентами, скрытая за версией 4 протокола 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`, если изменяются экспортный модуль среды выполнения, отложенный импорт, упаковка или опубликованные поверхности плагина.