Рефакторинг 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 и вспомогательные средства A2UI JSONL перемещены в extensions/canvas/src/cli.ts.
• URL хоста Canvas и вспомогательные средства ограниченных capabilities перемещены в extensions/canvas/src.
• Значения по умолчанию для команд Canvas Node вынесены из жестко заданных списков ядра в nodeInvokePolicies Plugin.
• Добавлена конфигурация хоста Canvas, принадлежащая Plugin, в plugins.entries.canvas.config.host.
• HTTP-обслуживание Canvas и A2UI перенесено за регистрацию HTTP-маршрутов Canvas Plugin.
• Добавлена универсальная диспетчеризация WebSocket upgrade для HTTP-маршрутов, принадлежащих Plugin.
• Специфичные для Canvas URL хоста Gateway и авторизация capabilities Node заменены универсальной поверхностью размещенного Plugin и вспомогательными средствами capabilities Node.
• Добавлены резолверы размещенных медиа, принадлежащие Plugin, чтобы URL документов Canvas разрешались через Canvas Plugin, а не через импорт ядром внутренних модулей документов Canvas.
• Добавлен api.registerNodeCliFeature(...), чтобы Canvas мог объявлять openclaw nodes canvas как функцию Node, принадлежащую Plugin, без ручного указания пути родительской команды.
• Удалены production-импорты extensions/canvas/runtime-api.js из src/**.
• Исходники A2UI bundle перемещены из apps/shared/OpenClawKit/Tools/CanvasA2UI в extensions/canvas/src/host/a2ui-app.
• Реализация сборки/копирования A2UI перемещена в extensions/canvas/scripts, а корневая проводка сборки заменена универсальными asset hooks встроенного Plugin.
• Удален runtime-legacy псевдоним конфигурации верхнего уровня canvasHost.
• Сохранена миграция doctor для Canvas, чтобы 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 lookup, но шаг копирования теперь принадлежит Plugin

Целевая форма

extensions/canvas должен владеть:

• манифестом Plugin и метаданными пакета
• регистрацией агентского инструмента
• политикой команд node invoke
• хостом Canvas и runtime A2UI
• исходниками Canvas A2UI bundle и скриптами сборки/копирования assets
• созданием документов Canvas и разрешением assets
• реализацией Canvas CLI
• страницей документации Canvas и записью в инвентаре Plugin

Ядро должно владеть только универсальными швами:

• обнаружением и регистрацией Plugin
• универсальным реестром агентских инструментов
• универсальным реестром политик node invoke
• универсальными HTTP/аутентификацией Gateway и диспетчеризацией WebSocket upgrade
• универсальным разрешением URL поверхности размещенного Plugin
• универсальной регистрацией резолверов размещенных медиа
• универсальным транспортом capabilities Node
• универсальной проводкой конфигурации
• универсальным обнаружением asset hooks встроенного Plugin

Нативные приложения могут сохранять обработчики команд Canvas как клиенты протокола. Они не являются владельцем runtime Plugin.

Шаги миграции

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

Аудит-чеклист

Перед тем как считать рефакторинг завершенным:

• rg "src/canvas-host|../canvas-host" не возвращает живых импортов исходного кода.
• rg "canvas-tool|createCanvasTool" src не находит реализации инструмента Canvas, принадлежащей ядру.
• rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway не находит жестко заданных allowlist defaults вне тестов универсальной политики 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 tests проходят для путей 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.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 перед push, если изменяются runtime barrel, lazy import, упаковка или опубликованные поверхности Plugin.