--- read_when: - Перенос ответственности за хост Canvas, инструменты, команды, документацию или протокол - Аудит того, принадлежит ли Canvas по-прежнему ядру - Подготовка или проверка PR экспериментального плагина Canvas summary: План и контрольный список аудита для переноса Canvas из ядра во встроенный экспериментальный плагин. title: Рефакторинг плагина Canvas x-i18n: generated_at: "2026-07-13T20:15:11Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 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`. - Из `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 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`, если изменяются экспортный модуль среды выполнения, отложенный импорт, упаковка или опубликованные поверхности плагина.