بازآرایی Plugin مربوط به Canvas

Canvas کم‌استفاده و آزمایشی است. با آن به‌عنوان یک Plugin همراه برخورد کنید، نه یک قابلیت هسته‌ای. هسته می‌تواند زیرساخت عمومی Gateway، Node، HTTP، احراز هویت، پیکربندی و کلاینت بومی را نگه دارد، اما رفتار مختص Canvas باید زیر extensions/canvas قرار گیرد.

هدف

انتقال مالکیت Canvas به extensions/canvas با حفظ رفتار فعلی Node جفت‌شده:

• ابزار canvas در دسترس عامل، توسط Plugin مربوط به Canvas ثبت شود
• فرمان‌های Node مربوط به Canvas فقط زمانی مجاز باشند که Plugin مربوط به Canvas آن‌ها را ثبت کند
• فایل‌های میزبان/منبع A2UI زیر Plugin مربوط به Canvas قرار گیرند
• مادی‌سازی سند Canvas زیر Plugin مربوط به Canvas قرار گیرد
• پیاده‌سازی فرمان CLI زیر Plugin مربوط به Canvas قرار گیرد، یا از طریق یک barrel زمان اجرای متعلق به Plugin واگذار شود
• مستندات و فهرست موجودی Plugin، Canvas را آزمایشی و مبتنی بر Plugin توصیف کنند

موارد خارج از هدف

• در این بازآرایی، رابط کاربری Canvas در برنامه بومی را بازطراحی نکنید.
• پشتیبانی پروتکل/کلاینت Canvas را از iOS، Android یا macOS حذف نکنید، مگر اینکه تصمیم محصول جداگانه‌ای حذف Canvas را مقرر کند.
• فقط برای Canvas یک چارچوب گسترده خدمات Plugin نسازید، مگر اینکه حداقل یک Plugin همراه دیگر نیز به همان نقطه اتصال نیاز داشته باشد.

وضعیت فعلی شاخه

انجام‌شده:

• بسته Plugin همراه در extensions/canvas اضافه شد.
• extensions/canvas/openclaw.plugin.json اضافه شد.
• ابزار canvas عامل از src/agents/tools/canvas-tool.ts به extensions/canvas/src/tool.ts منتقل شد.
• ثبت هسته‌ای createCanvasTool از src/agents/openclaw-tools.ts حذف شد.
• پیاده‌سازی میزبان Canvas از src/canvas-host به extensions/canvas/src/host منتقل شد.
• extensions/canvas/runtime-api.ts به‌عنوان barrel سازگاری متعلق به Plugin برای آزمون‌ها، بسته‌بندی و ابزارهای کمکی عمومی و خارجی Canvas حفظ شد.
• مادی‌سازی سند Canvas از src/gateway/canvas-documents.ts به extensions/canvas/src/documents.ts منتقل شد.
• پیاده‌سازی CLI مربوط به Canvas و ابزارهای کمکی JSONL مربوط به A2UI به extensions/canvas/src/cli.ts منتقل شدند.
• نشانی URL میزبان Canvas و ابزارهای کمکی قابلیت محدوده‌بندی‌شده به extensions/canvas/src منتقل شدند.
• مقادیر پیش‌فرض فرمان‌های Node مربوط به Canvas از فهرست‌های کدنویسی‌شده در هسته خارج و به nodeInvokePolicies در Plugin منتقل شدند.
• پیکربندی میزبان Canvas متعلق به Plugin در plugins.entries.canvas.config.host اضافه شد.
• ارائه HTTP مربوط به Canvas و A2UI پشت ثبت مسیر HTTP در Plugin مربوط به Canvas قرار گرفت.
• اعزام عمومی ارتقای WebSocket برای مسیرهای HTTP متعلق به Plugin اضافه شد.
• نشانی URL میزبان و مجوزدهی قابلیت Node مختص Canvas در Gateway با ابزارهای کمکی عمومی سطح میزبانی‌شده Plugin و قابلیت Node جایگزین شدند.
• حل‌کننده‌های رسانه میزبانی‌شده متعلق به Plugin اضافه شدند تا نشانی‌های URL سند Canvas به‌جای وارد کردن جزئیات داخلی سند Canvas توسط هسته، از طریق Plugin مربوط به Canvas حل شوند.
• api.registerNodeCliFeature(...) اضافه شد تا Canvas بتواند openclaw nodes canvas را به‌عنوان یک قابلیت Node متعلق به Plugin اعلام کند، بدون آنکه مسیر فرمان والد را به‌صورت دستی مشخص کند.
• واردسازی‌های زمان تولید src/** از extensions/canvas/runtime-api.js حذف شدند.
• منبع بسته A2UI از apps/shared/OpenClawKit/Tools/CanvasA2UI به extensions/canvas/src/host/a2ui-app منتقل شد.
• پیاده‌سازی ساخت/کپی A2UI به زیر extensions/canvas/scripts منتقل و سیم‌کشی ساخت ریشه با قلاب‌های عمومی دارایی Plugin همراه جایگزین شد.
• نام مستعار پیکربندی سطح‌بالای قدیمی canvasHost در زمان اجرا حذف شد.
• مهاجرت doctor مربوط به Canvas حفظ شد تا openclaw doctor --fix پیکربندی‌های قدیمی canvasHost را به plugins.entries.canvas.config.host بازنویسی کند.
• سازگاری پروتکل Canvas با عامل‌های قدیمی در پشت پروتکل Gateway نسخه ۴ حذف شد. کلاینت‌های بومی و Gatewayها اکنون فقط از pluginSurfaceUrls.canvas به‌همراه node.pluginSurface.refresh استفاده می‌کنند؛ مسیر منسوخ‌شده canvasHostUrl، canvasCapability و node.canvas.capability.refresh در این بازآرایی آزمایشی عمداً پشتیبانی نمی‌شود.
• فهرست موجودی تولیدشده Plugin برای افزودن Canvas به‌روزرسانی شد.
• مستندات مرجع Plugin در docs/plugins/reference/canvas.md اضافه شد.

سطوح شناخته‌شده باقی‌مانده Canvas که همچنان متعلق به هسته هستند:

• کنترل‌کننده‌های Canvas در برنامه بومی زیر apps/ همچنان عمداً سطح Plugin مربوط به Canvas را مصرف می‌کنند
• کنترل‌کننده‌های پروتکل/کلاینت Canvas در برنامه بومی زیر apps/
• خروجی مصنوع منتشرشده برای جست‌وجوی سازگار با نسخه‌های قبلی در زمان اجرا همچنان از dist/canvas-host/a2ui استفاده می‌کند، اما مرحله کپی اکنون متعلق به Plugin است

ساختار هدف

extensions/canvas باید مالک موارد زیر باشد:

• مانیفست Plugin و فراداده بسته
• ثبت ابزار عامل
• سیاست فرمان فراخوانی Node
• میزبان Canvas و زمان اجرای A2UI
• منبع بسته A2UI مربوط به Canvas و اسکریپت‌های ساخت/کپی دارایی
• ایجاد سند Canvas و حل دارایی
• پیاده‌سازی CLI مربوط به Canvas
• صفحه مستندات Canvas و مدخل فهرست موجودی Plugin

هسته باید فقط مالک نقاط اتصال عمومی زیر باشد:

• کشف و ثبت Plugin
• رجیستری عمومی ابزار عامل
• رجیستری عمومی سیاست فراخوانی Node
• احراز هویت/HTTP عمومی Gateway و اعزام ارتقای WebSocket
• حل عمومی نشانی URL سطح میزبانی‌شده Plugin
• ثبت عمومی حل‌کننده رسانه میزبانی‌شده
• انتقال عمومی قابلیت Node
• زیرساخت عمومی پیکربندی
• کشف عمومی قلاب دارایی Plugin همراه

برنامه‌های بومی می‌توانند کنترل‌کننده‌های فرمان Canvas را به‌عنوان کلاینت‌های پروتکل نگه دارند. آن‌ها مالک زمان اجرای Plugin نیستند.

مراحل مهاجرت

1. با plugins.entries.canvas.config.host به‌عنوان سطح پیکربندی متعلق به Plugin برخورد کنید.
2. مستندات را به‌روزرسانی کنید تا Canvas به‌عنوان یک Plugin همراه آزمایشی توصیف شود.
3. آزمون‌های متمرکز Canvas، بررسی‌های فهرست موجودی Plugin، بررسی‌های API مربوط به SDK افزونه و دروازه‌های ساخت/نوع متأثر از مرزهای زمان اجرا را اجرا کنید.

چک‌لیست ممیزی

پیش از کامل اعلام کردن بازآرایی:

• rg "src/canvas-host|../canvas-host" هیچ واردسازی فعال منبعی برنگرداند.
• rg "canvas-tool|createCanvasTool" src هیچ پیاده‌سازی ابزار Canvas متعلق به هسته پیدا نکند.
• rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway هیچ مقدار پیش‌فرض فهرست مجاز کدنویسی‌شده‌ای خارج از آزمون‌های سیاست عمومی Plugin پیدا نکند.
• خروجی rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts' خالی باشد.
• خروجی rg "canvas-documents" src خالی باشد.
• خروجی rg "registerNodesCanvasCommands|nodes-canvas" src خالی باشد؛ Plugin مربوط به Canvas فرمان openclaw nodes canvas را از طریق فراداده تودرتوی CLI مربوط به Plugin ثبت کند.
• rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway هیچ مالکیت زمان اجرای Gateway برنگرداند.
• rg "apps/shared/OpenClawKit/Tools/CanvasA2UI|canvas-a2ui-copy|extensions/canvas/src/host/a2ui" scripts .github package.json فقط پوشش‌های سازگاری یا مسیرهای متعلق به Plugin را پیدا کند.
• pnpm plugins:inventory:check با موفقیت اجرا شود.
• pnpm plugin-sdk:api:check با موفقیت اجرا شود، یا خطوط مبنای API تولیدشده عمداً به‌روزرسانی و بازبینی شوند.
• آزمون‌های هدفمند Canvas با موفقیت اجرا شوند.
• آزمون‌های مسیرهای تغییریافته برای مسیرهای میزبان Canvas/A2UI با موفقیت اجرا شوند.
• متن PR صراحتاً بیان کند که Canvas آزمایشی و مبتنی بر Plugin است.

فرمان‌های راستی‌آزمایی

هنگام تکرار و اصلاح، از بررسی‌های محلی هدفمند استفاده کنید:

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

اگر barrel زمان اجرا، واردسازی تنبل، بسته‌بندی یا سطوح منتشرشده Plugin تغییر می‌کنند، پیش از push فرمان pnpm build را اجرا کنید.