Рефакторинг плагина 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 является экспериментальной функцией на основе плагина.

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

Во время итераций используйте целевые локальные проверки:

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, если изменяются экспортный модуль среды выполнения, отложенный импорт, упаковка или опубликованные поверхности плагина.