Refaktor plugin Canvas

Canvas jarang digunakan dan bersifat eksperimental. Perlakukan Canvas sebagai plugin bawaan, bukan fitur inti. Inti dapat mempertahankan infrastruktur generik untuk Gateway, Node, HTTP, autentikasi, konfigurasi, dan klien native, tetapi perilaku khusus Canvas harus berada di bawah extensions/canvas.

Tujuan

Pindahkan kepemilikan Canvas ke extensions/canvas sambil mempertahankan perilaku Node berpasangan saat ini:

• alat canvas yang ditujukan untuk agen didaftarkan oleh plugin Canvas
• perintah Node Canvas hanya diizinkan ketika plugin Canvas mendaftarkannya
• file host/sumber A2UI berada di bawah plugin Canvas
• materialisasi dokumen Canvas berada di bawah plugin Canvas
• implementasi perintah CLI berada di bawah plugin Canvas, atau mendelegasikan melalui barrel runtime milik plugin
• dokumentasi dan inventaris plugin menjelaskan Canvas sebagai eksperimental dan didukung plugin

Bukan tujuan

• Jangan mendesain ulang UI Canvas aplikasi native dalam refaktor ini.
• Jangan menghapus dukungan protokol/klien Canvas dari iOS, Android, atau macOS kecuali keputusan produk terpisah menetapkan bahwa Canvas harus dihapus.
• Jangan membangun kerangka kerja layanan plugin yang luas hanya untuk Canvas kecuali setidaknya satu plugin bawaan lain memerlukan seam yang sama.

Status cabang saat ini

Selesai:

• Menambahkan paket plugin bawaan di extensions/canvas.
• Menambahkan extensions/canvas/openclaw.plugin.json.
• Memindahkan alat agen canvas dari src/agents/tools/canvas-tool.ts ke extensions/canvas/src/tool.ts.
• Menghapus pendaftaran inti untuk createCanvasTool dari src/agents/openclaw-tools.ts.
• Memindahkan implementasi host Canvas dari src/canvas-host ke extensions/canvas/src/host.
• Mempertahankan extensions/canvas/runtime-api.ts sebagai barrel kompatibilitas milik plugin untuk pengujian, pemaketan, dan helper publik eksternal Canvas.
• Memindahkan materialisasi dokumen Canvas dari src/gateway/canvas-documents.ts ke extensions/canvas/src/documents.ts.
• Memindahkan implementasi CLI Canvas dan helper JSONL A2UI ke extensions/canvas/src/cli.ts.
• Memindahkan URL host Canvas dan helper kapabilitas bercakupan ke extensions/canvas/src.
• Memindahkan nilai default perintah Node Canvas dari daftar inti yang di-hardcode ke nodeInvokePolicies milik plugin.
• Menambahkan konfigurasi host Canvas milik plugin di plugins.entries.canvas.config.host.
• Memindahkan penyajian HTTP Canvas dan A2UI ke balik pendaftaran rute HTTP plugin Canvas.
• Menambahkan dispatch peningkatan WebSocket plugin generik untuk rute HTTP milik plugin.
• Mengganti URL host Gateway khusus Canvas dan autentikasi kapabilitas Node dengan permukaan plugin yang di-host serta helper kapabilitas Node generik.
• Menambahkan resolver media yang di-host milik plugin agar URL dokumen Canvas diselesaikan melalui plugin Canvas alih-alih inti mengimpor internal dokumen Canvas.
• Menambahkan api.registerNodeCliFeature(...) agar Canvas dapat mendeklarasikan openclaw nodes canvas sebagai fitur Node milik plugin tanpa menuliskan jalur perintah induk secara manual.
• Menghapus impor produksi src/** atas extensions/canvas/runtime-api.js.
• Memindahkan sumber bundel A2UI dari apps/shared/OpenClawKit/Tools/CanvasA2UI ke extensions/canvas/src/host/a2ui-app.
• Memindahkan implementasi build/salin A2UI ke bawah extensions/canvas/scripts dan mengganti pengkabelan build root dengan hook aset plugin bawaan generik.
• Menghapus alias konfigurasi tingkat atas lama canvasHost dari runtime.
• Mempertahankan migrasi doctor Canvas agar openclaw doctor --fix menulis ulang konfigurasi canvasHost lama menjadi plugins.entries.canvas.config.host.
• Menghapus kompatibilitas protokol Canvas untuk agen lama di balik protokol Gateway v4. Klien native dan Gateway kini hanya menggunakan pluginSurfaceUrls.canvas serta node.pluginSurface.refresh; jalur canvasHostUrl, canvasCapability, dan node.canvas.capability.refresh yang tidak digunakan lagi sengaja tidak didukung dalam refaktor eksperimental ini.
• Memperbarui inventaris plugin yang dihasilkan agar mencakup Canvas.
• Menambahkan dokumentasi referensi plugin di docs/plugins/reference/canvas.md.

Permukaan Canvas yang diketahui masih dimiliki inti:

• Handler Canvas aplikasi native di bawah apps/ masih secara sengaja menggunakan permukaan plugin Canvas
• handler protokol/klien Canvas aplikasi native di bawah apps/
• output artefak yang dipublikasikan masih menggunakan dist/canvas-host/a2ui untuk pencarian runtime yang kompatibel dengan versi sebelumnya, tetapi langkah penyalinan kini dimiliki plugin

Bentuk target

extensions/canvas harus memiliki:

• manifes plugin dan metadata paket
• pendaftaran alat agen
• kebijakan perintah pemanggilan Node
• host Canvas dan runtime A2UI
• sumber bundel A2UI Canvas serta skrip build/salin aset
• pembuatan dokumen Canvas dan resolusi aset
• implementasi CLI Canvas
• halaman dokumentasi Canvas dan entri inventaris plugin

Inti seharusnya hanya memiliki seam generik:

• penemuan dan pendaftaran plugin
• registri alat agen generik
• registri kebijakan pemanggilan Node generik
• HTTP/autentikasi Gateway generik dan dispatch peningkatan WebSocket
• resolusi URL permukaan plugin yang di-host secara generik
• pendaftaran resolver media yang di-host secara generik
• transport kapabilitas Node generik
• infrastruktur konfigurasi generik
• penemuan hook aset plugin bawaan generik

Aplikasi native dapat mempertahankan handler perintah Canvas sebagai klien protokol. Aplikasi tersebut bukan pemilik runtime plugin.

Langkah migrasi

1. Perlakukan plugins.entries.canvas.config.host sebagai permukaan konfigurasi milik plugin.
2. Perbarui dokumentasi agar Canvas dijelaskan sebagai plugin bawaan eksperimental.
3. Jalankan pengujian Canvas terfokus, pemeriksaan inventaris plugin, pemeriksaan API SDK plugin, serta gate build/tipe yang terpengaruh oleh batas runtime.

Daftar periksa audit

Sebelum menyatakan refaktor selesai:

• rg "src/canvas-host|../canvas-host" tidak menghasilkan impor sumber aktif.
• rg "canvas-tool|createCanvasTool" src tidak menemukan implementasi alat Canvas milik inti.
• rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway tidak menemukan nilai default daftar izin yang di-hardcode di luar pengujian kebijakan plugin generik.
• rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts' kosong.
• rg "canvas-documents" src kosong.
• rg "registerNodesCanvasCommands|nodes-canvas" src kosong; plugin Canvas mendaftarkan openclaw nodes canvas melalui metadata CLI plugin bertingkat.
• rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway tidak menghasilkan kepemilikan runtime Gateway.
• rg "apps/shared/OpenClawKit/Tools/CanvasA2UI|canvas-a2ui-copy|extensions/canvas/src/host/a2ui" scripts .github package.json hanya menemukan wrapper kompatibilitas atau jalur milik plugin.
• pnpm plugins:inventory:check berhasil.
• pnpm plugin-sdk:api:check berhasil, atau catatan kontrak API yang dihasilkan diperbarui dan direview secara sengaja.
• Pengujian Canvas yang ditargetkan berhasil.
• Pengujian changed-lanes berhasil untuk jalur host Canvas/A2UI.
• Isi PR secara eksplisit menyatakan bahwa Canvas bersifat eksperimental dan didukung plugin.

Perintah verifikasi

Gunakan pemeriksaan lokal yang ditargetkan selama iterasi:

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

Jalankan pnpm build sebelum push jika barrel runtime, impor malas, pemaketan, atau permukaan plugin yang dipublikasikan berubah.