# Refaktoryzacja Plugin Canvas

Canvas jest mało używany i eksperymentalny. Traktuj go jako dołączony Plugin, a nie funkcję rdzenia. Rdzeń może zachować ogólną obsługę Gateway, Node, HTTP, uwierzytelniania, konfiguracji i natywnego klienta, ale zachowanie specyficzne dla Canvas powinno znajdować się w extensions/canvas.

# Cel

Przenieść własność Canvas do extensions/canvas, zachowując obecne zachowanie sparowanego węzła:

• narzędzie canvas przeznaczone dla agenta jest rejestrowane przez Plugin Canvas
• polecenia węzła Canvas są dozwolone tylko wtedy, gdy Plugin Canvas je rejestruje
• pliki hosta/źródłowe A2UI znajdują się w Plugin Canvas
• materializacja dokumentów Canvas znajduje się w Plugin Canvas
• implementacja polecenia CLI znajduje się w Plugin Canvas albo deleguje przez należący do Plugin barrel środowiska uruchomieniowego
• dokumentacja i inwentarz Plugin opisują Canvas jako eksperymentalny i oparty na Plugin

# Poza zakresem

• Nie przeprojektowuj natywnego interfejsu Canvas w tej refaktoryzacji.
• Nie usuwaj obsługi protokołu/klienta Canvas z iOS, Androida ani macOS, chyba że osobna decyzja produktowa mówi, że Canvas należy usunąć.
• Nie buduj szerokiej platformy usług Plugin tylko dla Canvas, chyba że co najmniej jeden inny dołączony Plugin potrzebuje tego samego punktu integracji.

# Obecny stan gałęzi

Zrobione:

• Dodano pakiet dołączonego Plugin w extensions/canvas.
• Dodano extensions/canvas/openclaw.plugin.json.
• Przeniesiono narzędzie agenta canvas z src/agents/tools/canvas-tool.ts do extensions/canvas/src/tool.ts.
• Usunięto rejestrację rdzeniową createCanvasTool z src/agents/openclaw-tools.ts.
• Przeniesiono implementację hosta Canvas z src/canvas-host do extensions/canvas/src/host.
• Zachowano extensions/canvas/runtime-api.ts jako należący do Plugin barrel zgodności dla testów, pakowania i zewnętrznych publicznych helperów Canvas.
• Przeniesiono materializację dokumentów Canvas z src/gateway/canvas-documents.ts do extensions/canvas/src/documents.ts.
• Przeniesiono implementację CLI Canvas i helpery JSONL A2UI do extensions/canvas/src/cli.ts.
• Przeniesiono URL hosta Canvas i helpery ograniczonych capability do extensions/canvas/src.
• Przeniesiono domyślne polecenia węzła Canvas z zakodowanych na stałe list rdzenia do Plugin nodeInvokePolicies.
• Dodano należącą do Plugin konfigurację hosta Canvas w plugins.entries.canvas.config.host.
• Przeniesiono serwowanie HTTP Canvas i A2UI za rejestrację tras HTTP Plugin Canvas.
• Dodano ogólne przekazywanie upgrade WebSocket Plugin dla należących do Plugin tras HTTP.
• Zastąpiono specyficzne dla Canvas uwierzytelnianie URL hosta Gateway i capability węzła ogólną powierzchnią hostowanego Plugin oraz helperami capability węzła.
• Dodano należące do Plugin resolvery hostowanych mediów, aby adresy URL dokumentów Canvas były rozwiązywane przez Plugin Canvas zamiast importowania przez rdzeń wewnętrznych części dokumentów Canvas.
• Dodano api.registerNodeCliFeature(...), aby Canvas mógł deklarować openclaw nodes canvas jako należącą do Plugin funkcję węzła bez ręcznego wypisywania ścieżki polecenia nadrzędnego.
• Usunięto produkcyjne importy src/** z extensions/canvas/runtime-api.js.
• Przeniesiono źródło pakietu A2UI z apps/shared/OpenClawKit/Tools/CanvasA2UI do extensions/canvas/src/host/a2ui-app.
• Przeniesiono implementację budowania/kopiowania A2UI pod extensions/canvas/scripts i zastąpiono główne powiązanie budowania ogólnymi hookami zasobów dołączonych Plugin.
• Usunięto alias starszej konfiguracji najwyższego poziomu canvasHost z runtime.
• Zachowano migrację doctor dla Canvas, aby openclaw doctor --fix przepisywało stare konfiguracje canvasHost do plugins.entries.canvas.config.host.
• Usunięto zgodność starego protokołu Canvas agenta za Gateway protocol v4. Natywni klienci i Gateway używają teraz wyłącznie pluginSurfaceUrls.canvas oraz node.pluginSurface.refresh; przestarzałe ścieżki canvasHostUrl, canvasCapability i node.canvas.capability.refresh są celowo nieobsługiwane w tej eksperymentalnej refaktoryzacji.
• Zaktualizowano wygenerowany inwentarz Plugin, aby uwzględniał Canvas.
• Dodano dokumentację referencyjną Plugin w docs/plugins/reference/canvas.md.

Znane pozostałe powierzchnie Canvas należące do rdzenia:

• Handlery Canvas natywnej aplikacji pod apps/ nadal celowo używają powierzchni Plugin Canvas
• handlery protokołu/klienta Canvas natywnej aplikacji pod apps/
• wyjście publikowanego artefaktu nadal używa dist/canvas-host/a2ui dla zgodnego wstecznie wyszukiwania runtime, ale krok kopiowania należy teraz do Plugin

# Docelowy kształt

extensions/canvas powinno posiadać:

• manifest Plugin i metadane pakietu
• rejestrację narzędzia agenta
• politykę poleceń wywołań węzła
• host Canvas i runtime A2UI
• źródło pakietu Canvas A2UI oraz skrypty budowania/kopiowania zasobów
• tworzenie dokumentów Canvas i rozwiązywanie zasobów
• implementację CLI Canvas
• stronę dokumentacji Canvas i wpis w inwentarzu Plugin

Rdzeń powinien posiadać tylko ogólne punkty integracji:

• wykrywanie i rejestrację Plugin
• ogólny rejestr narzędzi agenta
• ogólny rejestr polityk wywołań węzła
• ogólne HTTP/uwierzytelnianie Gateway i przekazywanie upgrade WebSocket
• ogólne rozwiązywanie URL powierzchni hostowanego Plugin
• ogólną rejestrację resolvera hostowanych mediów
• ogólny transport capability węzła
• ogólne okablowanie konfiguracji
• ogólne wykrywanie hooków zasobów dołączonych Plugin

Natywne aplikacje mogą zachować handlery poleceń Canvas jako klienci protokołu. Nie są właścicielem runtime Plugin.

# Kroki migracji

1. Traktuj plugins.entries.canvas.config.host jako należącą do Plugin powierzchnię konfiguracji.
2. Zaktualizuj dokumentację, aby Canvas był opisany jako eksperymentalny dołączony Plugin.
3. Uruchom ukierunkowane testy Canvas, sprawdzenia inwentarza Plugin, sprawdzenia API Plugin SDK oraz bramki build/type, na które wpływają granice runtime.

# Lista kontrolna audytu

Przed uznaniem refaktoryzacji za ukończoną:

• rg "src/canvas-host|../canvas-host" nie zwraca żadnych aktywnych importów źródłowych.
• rg "canvas-tool|createCanvasTool" src nie znajduje należącej do rdzenia implementacji narzędzia Canvas.
• rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway nie znajduje zakodowanych na stałe domyślnych list dozwolonych poza ogólnymi testami polityk Plugin.
• rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts' jest puste.
• rg "canvas-documents" src jest puste.
• rg "registerNodesCanvasCommands|nodes-canvas" src jest puste; Plugin Canvas rejestruje openclaw nodes canvas przez zagnieżdżone metadane CLI Plugin.
• rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway nie zwraca własności runtime Gateway.
• rg "apps/shared/OpenClawKit/Tools/CanvasA2UI|canvas-a2ui-copy|extensions/canvas/src/host/a2ui" scripts .github package.json znajduje tylko wrappery zgodności albo ścieżki należące do Plugin.
• pnpm plugins:inventory:check przechodzi.
• pnpm plugin-sdk:api:check przechodzi albo wygenerowane baseline’y API są celowo zaktualizowane i sprawdzone.
• Ukierunkowane testy Canvas przechodzą.
• Testy changed-lanes przechodzą dla ścieżek hosta Canvas/A2UI.
• Treść PR wyraźnie mówi, że Canvas jest eksperymentalny i oparty na Plugin.

# Polecenia weryfikacyjne

Używaj ukierunkowanych lokalnych sprawdzeń podczas iteracji:

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

Uruchom pnpm build przed push, jeśli zmienia się barrel runtime, leniwy import, pakowanie albo publikowane powierzchnie Plugin.