Refaktoryzacja pluginu Canvas

Canvas jest rzadko używany i eksperymentalny. Traktuj go jako dołączony plugin, a nie funkcję rdzenia. Rdzeń może zachować ogólną infrastrukturę Gateway, Node, HTTP, uwierzytelniania, konfiguracji i klientów natywnych, ale zachowanie specyficzne dla Canvas powinno znajdować się w extensions/canvas.

Cel

Przenieść odpowiedzialność za Canvas do extensions/canvas, zachowując bieżące działanie sparowanego Node:

• narzędzie canvas dostępne dla agenta jest rejestrowane przez plugin Canvas
• polecenia Node dla Canvas są dozwolone tylko wtedy, gdy zarejestruje je plugin Canvas
• pliki hosta i źródłowe A2UI znajdują się w pluginie Canvas
• materializacja dokumentów Canvas znajduje się w pluginie Canvas
• implementacja polecenia CLI znajduje się w pluginie Canvas lub deleguje przez należący do pluginu moduł zbiorczy środowiska wykonawczego
• dokumentacja i wykaz pluginów opisują Canvas jako rozwiązanie eksperymentalne i oparte na pluginie

Poza zakresem

• Nie przeprojektowuj w ramach tej refaktoryzacji interfejsu Canvas w aplikacji natywnej.
• Nie usuwaj obsługi protokołu ani klienta Canvas z systemów iOS, Android lub macOS, chyba że odrębna decyzja produktowa nakaże usunięcie Canvas.
• Nie twórz rozbudowanej struktury usług pluginów wyłącznie dla Canvas, chyba że co najmniej jeden inny dołączony plugin potrzebuje tego samego punktu integracji.

Bieżący stan gałęzi

Ukończono:

• Dodano pakiet dołączonego pluginu 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ę createCanvasTool w rdzeniu 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 pluginu moduł zbiorczy zgodności na potrzeby testów, pakowania i zewnętrznych publicznych funkcji pomocniczych Canvas.
• Przeniesiono materializację dokumentów Canvas z src/gateway/canvas-documents.ts do extensions/canvas/src/documents.ts.
• Przeniesiono implementację CLI Canvas i funkcje pomocnicze JSONL A2UI do extensions/canvas/src/cli.ts.
• Przeniesiono adres URL hosta Canvas i funkcje pomocnicze ograniczonych zakresowo możliwości do extensions/canvas/src.
• Przeniesiono domyślne polecenia Node dla Canvas z zakodowanych na stałe list rdzenia do nodeInvokePolicies pluginu.
• Dodano należącą do pluginu konfigurację hosta Canvas w plugins.entries.canvas.config.host.
• Przeniesiono udostępnianie Canvas i A2UI przez HTTP za rejestrację tras HTTP pluginu Canvas.
• Dodano ogólną obsługę podnoszenia połączeń WebSocket dla tras HTTP należących do pluginów.
• Zastąpiono specyficzne dla Canvas uwierzytelnianie adresu URL hosta Gateway i możliwości Node ogólnymi funkcjami pomocniczymi hostowanej powierzchni pluginu i możliwości Node.
• Dodano należące do pluginu mechanizmy rozpoznawania hostowanych multimediów, dzięki czemu adresy URL dokumentów Canvas są rozpoznawane przez plugin Canvas zamiast przez importowanie przez rdzeń wewnętrznych elementów dokumentów Canvas.
• Dodano api.registerNodeCliFeature(...), aby Canvas mógł deklarować openclaw nodes canvas jako należącą do pluginu funkcję Node bez ręcznego określania ścieżki polecenia nadrzędnego.
• Usunięto produkcyjne importy extensions/canvas/runtime-api.js z src/**.
• Przeniesiono źródło pakietu A2UI z apps/shared/OpenClawKit/Tools/CanvasA2UI do extensions/canvas/src/host/a2ui-app.
• Przeniesiono implementację budowania i kopiowania A2UI do extensions/canvas/scripts oraz zastąpiono główną konfigurację procesu budowania ogólnymi punktami zaczepienia zasobów dołączonych pluginów.
• Usunięto starszy alias konfiguracji canvasHost najwyższego poziomu ze środowiska wykonawczego.
• Zachowano migrację Canvas w narzędziu diagnostycznym, aby openclaw doctor --fix przepisywało stare konfiguracje canvasHost do plugins.entries.canvas.config.host.
• Usunięto zgodność protokołu Canvas ze starszymi agentami za bramą protokołu Gateway v4. Klienci natywni i Gateway używają teraz wyłącznie pluginSurfaceUrls.canvas oraz node.pluginSurface.refresh; przestarzała ścieżka canvasHostUrl, canvasCapability i node.canvas.capability.refresh celowo nie jest obsługiwana w tej eksperymentalnej refaktoryzacji.
• Zaktualizowano wygenerowany wykaz pluginów, aby uwzględnić Canvas.
• Dodano dokumentację referencyjną pluginu w docs/plugins/reference/canvas.md.

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

• Procedury obsługi Canvas w aplikacjach natywnych w apps/ nadal celowo korzystają z powierzchni pluginu Canvas
• procedury obsługi protokołu i klienta Canvas w aplikacjach natywnych w apps/
• dane wyjściowe opublikowanego artefaktu nadal używają dist/canvas-host/a2ui w celu zachowania zgodności wstecznej podczas wyszukiwania w środowisku wykonawczym, ale etap kopiowania należy teraz do pluginu

Docelowa struktura

extensions/canvas powinno odpowiadać za:

• manifest pluginu i metadane pakietu
• rejestrację narzędzia agenta
• zasady wywoływania poleceń Node
• host Canvas i środowisko wykonawcze A2UI
• źródło pakietu Canvas A2UI oraz skrypty budowania i kopiowania zasobów
• tworzenie dokumentów Canvas i rozpoznawanie zasobów
• implementację CLI Canvas
• stronę dokumentacji Canvas i wpis w wykazie pluginów

Rdzeń powinien odpowiadać wyłącznie za ogólne punkty integracji:

• wykrywanie i rejestrację pluginów
• ogólny rejestr narzędzi agenta
• ogólny rejestr zasad wywoływania Node
• ogólną obsługę HTTP i uwierzytelniania Gateway oraz podnoszenia połączeń WebSocket
• ogólne rozpoznawanie adresów URL hostowanych powierzchni pluginów
• ogólną rejestrację mechanizmów rozpoznawania hostowanych multimediów
• ogólny transport możliwości Node
• ogólną obsługę konfiguracji
• ogólne wykrywanie punktów zaczepienia zasobów dołączonych pluginów

Aplikacje natywne mogą zachować procedury obsługi poleceń Canvas jako klienci protokołu. Nie są właścicielem środowiska wykonawczego pluginu.

Kroki migracji

1. Traktuj plugins.entries.canvas.config.host jako należącą do pluginu powierzchnię konfiguracji.
2. Zaktualizuj dokumentację tak, aby Canvas był opisywany jako eksperymentalny dołączony plugin.
3. Uruchom ukierunkowane testy Canvas, kontrole wykazu pluginów, kontrole API SDK pluginów oraz bramki budowania i typów, na które wpływają granice środowiska wykonawczego.

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 testami ogólnych zasad pluginów.
• Wynik rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts' jest pusty.
• Wynik rg "canvas-documents" src jest pusty.
• Wynik rg "registerNodesCanvasCommands|nodes-canvas" src jest pusty; plugin Canvas rejestruje openclaw nodes canvas za pośrednictwem zagnieżdżonych metadanych CLI pluginu.
• rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway nie zwraca żadnych elementów środowiska wykonawczego należących do Gateway.
• rg "apps/shared/OpenClawKit/Tools/CanvasA2UI|canvas-a2ui-copy|extensions/canvas/src/host/a2ui" scripts .github package.json znajduje wyłącznie opakowania zgodności lub ścieżki należące do pluginu.
• pnpm plugins:inventory:check przechodzi pomyślnie.
• pnpm plugin-sdk:api:check przechodzi pomyślnie albo wygenerowane wartości bazowe API zostały celowo zaktualizowane i sprawdzone.
• Ukierunkowane testy Canvas przechodzą pomyślnie.
• Testy zmienionych ścieżek przechodzą pomyślnie dla ścieżek hosta Canvas i A2UI.
• Treść PR jednoznacznie stwierdza, że Canvas jest eksperymentalny i oparty na pluginie.

Polecenia weryfikacyjne

Podczas iteracji używaj ukierunkowanych kontroli lokalnych:

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

Uruchom pnpm build przed wypchnięciem zmian, jeśli zmienia się moduł zbiorczy środowiska wykonawczego, import leniwy, pakowanie lub opublikowane powierzchnie pluginu.