Tái cấu trúc Plugin Canvas

Canvas ít được sử dụng và đang ở trạng thái thử nghiệm. Hãy coi Canvas là một Plugin đi kèm, không phải tính năng cốt lõi. Phần lõi có thể giữ lại hạ tầng chung cho Gateway, Node, HTTP, xác thực, cấu hình và máy khách gốc, nhưng hành vi dành riêng cho Canvas nên nằm trong extensions/canvas.

Mục tiêu

Chuyển quyền sở hữu Canvas sang extensions/canvas trong khi vẫn duy trì hành vi Node được ghép nối hiện tại:

• công cụ canvas dành cho tác tử được đăng ký bởi Plugin Canvas
• các lệnh Node của Canvas chỉ được cho phép khi Plugin Canvas đăng ký chúng
• các tệp máy chủ/nguồn A2UI nằm trong Plugin Canvas
• việc hiện thực hóa tài liệu Canvas nằm trong Plugin Canvas
• phần triển khai lệnh CLI nằm trong Plugin Canvas hoặc ủy quyền thông qua barrel runtime do Plugin sở hữu
• tài liệu và danh mục Plugin mô tả Canvas là tính năng thử nghiệm dựa trên Plugin

Ngoài phạm vi

• Không thiết kế lại giao diện người dùng Canvas của ứng dụng gốc trong lần tái cấu trúc này.
• Không loại bỏ khả năng hỗ trợ giao thức/máy khách Canvas khỏi iOS, Android hoặc macOS, trừ khi có quyết định sản phẩm riêng rằng Canvas nên bị xóa.
• Không xây dựng một khung dịch vụ Plugin tổng quát chỉ dành cho Canvas, trừ khi có ít nhất một Plugin đi kèm khác cần cùng điểm nối đó.

Trạng thái nhánh hiện tại

Đã hoàn tất:

• Đã thêm gói Plugin đi kèm trong extensions/canvas.
• Đã thêm extensions/canvas/openclaw.plugin.json.
• Đã chuyển công cụ canvas của tác tử từ src/agents/tools/canvas-tool.ts sang extensions/canvas/src/tool.ts.
• Đã loại bỏ việc đăng ký createCanvasTool trong phần lõi khỏi src/agents/openclaw-tools.ts.
• Đã chuyển phần triển khai máy chủ Canvas từ src/canvas-host sang extensions/canvas/src/host.
• Đã giữ extensions/canvas/runtime-api.ts làm barrel tương thích do Plugin sở hữu cho các bài kiểm thử, việc đóng gói và các trình trợ giúp Canvas công khai bên ngoài.
• Đã chuyển việc hiện thực hóa tài liệu Canvas từ src/gateway/canvas-documents.ts sang extensions/canvas/src/documents.ts.
• Đã chuyển phần triển khai CLI Canvas và các trình trợ giúp JSONL A2UI vào extensions/canvas/src/cli.ts.
• Đã chuyển URL máy chủ Canvas và các trình trợ giúp khả năng có phạm vi vào extensions/canvas/src.
• Đã chuyển các giá trị mặc định của lệnh Node Canvas khỏi danh sách mã hóa cứng trong phần lõi sang nodeInvokePolicies của Plugin.
• Đã thêm cấu hình máy chủ Canvas do Plugin sở hữu tại plugins.entries.canvas.config.host.
• Đã chuyển việc phục vụ Canvas và A2UI qua HTTP ra sau cơ chế đăng ký tuyến HTTP của Plugin Canvas.
• Đã thêm cơ chế điều phối nâng cấp WebSocket chung cho các tuyến HTTP do Plugin sở hữu.
• Đã thay thế URL máy chủ Gateway và xác thực khả năng Node dành riêng cho Canvas bằng các trình trợ giúp chung cho bề mặt Plugin được lưu trữ và khả năng Node.
• Đã thêm các trình phân giải phương tiện được lưu trữ do Plugin sở hữu để URL tài liệu Canvas được phân giải thông qua Plugin Canvas thay vì phần lõi nhập trực tiếp các phần nội bộ của tài liệu Canvas.
• Đã thêm api.registerNodeCliFeature(...) để Canvas có thể khai báo openclaw nodes canvas là một tính năng Node do Plugin sở hữu mà không cần viết thủ công đường dẫn lệnh cha.
• Đã loại bỏ các lệnh nhập extensions/canvas/runtime-api.js khỏi src/** trong mã sản xuất.
• Đã chuyển nguồn gói A2UI từ apps/shared/OpenClawKit/Tools/CanvasA2UI sang extensions/canvas/src/host/a2ui-app.
• Đã chuyển phần triển khai xây dựng/sao chép A2UI vào extensions/canvas/scripts và thay thế việc nối dây xây dựng ở thư mục gốc bằng các hook tài nguyên Plugin đi kèm dùng chung.
• Đã loại bỏ bí danh cấu hình cấp cao nhất kế thừa canvasHost khỏi runtime.
• Đã giữ lại quá trình di chuyển Canvas trong doctor để openclaw doctor --fix ghi lại các cấu hình canvasHost cũ thành plugins.entries.canvas.config.host.
• Đã loại bỏ khả năng tương thích giao thức Canvas với tác tử cũ phía sau giao thức Gateway v4. Các máy khách gốc và Gateway hiện chỉ sử dụng pluginSurfaceUrls.canvas cùng với node.pluginSurface.refresh; đường dẫn canvasHostUrl, canvasCapability và node.canvas.capability.refresh đã lỗi thời được chủ ý không hỗ trợ trong lần tái cấu trúc thử nghiệm này.
• Đã cập nhật danh mục Plugin được tạo để bao gồm Canvas.
• Đã thêm tài liệu tham chiếu Plugin tại docs/plugins/reference/canvas.md.

Các bề mặt Canvas còn lại đã biết vẫn do phần lõi sở hữu:

• Các trình xử lý Canvas của ứng dụng gốc trong apps/ vẫn chủ ý sử dụng bề mặt Plugin Canvas
• các trình xử lý giao thức/máy khách Canvas của ứng dụng gốc trong apps/
• đầu ra hiện vật đã phát hành vẫn sử dụng dist/canvas-host/a2ui để tra cứu runtime tương thích ngược, nhưng bước sao chép hiện do Plugin sở hữu

Cấu trúc mục tiêu

extensions/canvas nên sở hữu:

• tệp kê khai Plugin và siêu dữ liệu gói
• đăng ký công cụ tác tử
• chính sách lệnh gọi Node
• máy chủ Canvas và runtime A2UI
• nguồn gói A2UI Canvas và các tập lệnh xây dựng/sao chép tài nguyên
• việc tạo tài liệu Canvas và phân giải tài nguyên
• phần triển khai CLI Canvas
• trang tài liệu Canvas và mục trong danh mục Plugin

Phần lõi chỉ nên sở hữu các điểm nối chung:

• khám phá và đăng ký Plugin
• sổ đăng ký công cụ tác tử chung
• sổ đăng ký chính sách gọi Node chung
• HTTP/xác thực Gateway chung và cơ chế điều phối nâng cấp WebSocket
• phân giải URL bề mặt Plugin được lưu trữ chung
• đăng ký trình phân giải phương tiện được lưu trữ chung
• cơ chế truyền tải khả năng Node chung
• hệ thống kết nối cấu hình chung
• khám phá hook tài nguyên Plugin đi kèm chung

Các ứng dụng gốc có thể giữ các trình xử lý lệnh Canvas với vai trò máy khách của giao thức. Chúng không phải là bên sở hữu runtime của Plugin.

Các bước di chuyển

1. Coi plugins.entries.canvas.config.host là bề mặt cấu hình do Plugin sở hữu.
2. Cập nhật tài liệu để mô tả Canvas là một Plugin đi kèm mang tính thử nghiệm.
3. Chạy các bài kiểm thử tập trung cho Canvas, kiểm tra danh mục Plugin, kiểm tra API SDK Plugin và các cổng xây dựng/kiểu dữ liệu bị ảnh hưởng bởi ranh giới runtime.

Danh sách kiểm tra đánh giá

Trước khi tuyên bố hoàn tất việc tái cấu trúc:

• rg "src/canvas-host|../canvas-host" không trả về lệnh nhập mã nguồn đang hoạt động nào.
• rg "canvas-tool|createCanvasTool" src không tìm thấy phần triển khai công cụ Canvas nào do phần lõi sở hữu.
• rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway không tìm thấy giá trị mặc định trong danh sách cho phép được mã hóa cứng nào ngoài các bài kiểm thử chính sách Plugin chung.
• rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts' không trả về kết quả.
• rg "canvas-documents" src không trả về kết quả.
• rg "registerNodesCanvasCommands|nodes-canvas" src không trả về kết quả; Plugin Canvas đăng ký openclaw nodes canvas thông qua siêu dữ liệu CLI Plugin lồng nhau.
• rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway không trả về quyền sở hữu runtime Gateway nào.
• rg "apps/shared/OpenClawKit/Tools/CanvasA2UI|canvas-a2ui-copy|extensions/canvas/src/host/a2ui" scripts .github package.json chỉ tìm thấy các trình bao tương thích hoặc đường dẫn do Plugin sở hữu.
• pnpm plugins:inventory:check vượt qua.
• pnpm plugin-sdk:api:check vượt qua, hoặc các đường cơ sở API được tạo đã được chủ ý cập nhật và xem xét.
• Các bài kiểm thử Canvas có mục tiêu vượt qua.
• Các bài kiểm thử làn thay đổi vượt qua đối với các đường dẫn máy chủ Canvas/A2UI.
• Nội dung PR nêu rõ Canvas là tính năng thử nghiệm và dựa trên Plugin.

Các lệnh xác minh

Sử dụng các bước kiểm tra cục bộ có mục tiêu trong khi lặp:

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

Chạy pnpm build trước khi đẩy nếu barrel runtime, cơ chế nhập lười, việc đóng gói hoặc các bề mặt Plugin đã phát hành thay đổi.