إعادة هيكلة Plugin ‏Canvas

يُستخدم Canvas قليلًا وهو تجريبي. تعامل معه بوصفه Plugin مضمنًا، لا ميزة أساسية. يمكن للنواة الاحتفاظ بالبنية التحتية العامة لـ Gateway وNode وHTTP والمصادقة والإعداد والعميل الأصلي، لكن ينبغي أن يوجد السلوك الخاص بـ Canvas ضمن extensions/canvas.

الهدف

نقل ملكية Canvas إلى extensions/canvas مع الحفاظ على السلوك الحالي للعقدة المقترنة:

• تُسجَّل أداة canvas الموجّهة إلى الوكيل بواسطة Plugin ‏Canvas
• لا يُسمح بأوامر عقدة Canvas إلا عندما يسجّلها Plugin ‏Canvas
• توجد ملفات مضيف/مصدر A2UI ضمن Plugin ‏Canvas
• تتم عملية تجسيد مستندات Canvas ضمن Plugin ‏Canvas
• يوجد تنفيذ أمر CLI ضمن Plugin ‏Canvas، أو يفوّض عبر ملف تصدير وقت تشغيل يملكه Plugin
• تصف الوثائق وقائمة Plugins ‏Canvas بأنه تجريبي ومدعوم بواسطة Plugin

ما لا يشمله العمل

• لا تُعِد تصميم واجهة مستخدم Canvas في التطبيق الأصلي ضمن إعادة الهيكلة هذه.
• لا تزل دعم بروتوكول/عميل Canvas من iOS أو Android أو macOS ما لم ينص قرار منتج منفصل على ضرورة حذف Canvas.
• لا تنشئ إطار عمل واسعًا لخدمات Plugins من أجل Canvas وحده، ما لم يحتج 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 بوصفه ملف تصدير التوافق المملوك لـ 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.
• نقل الإعدادات الافتراضية لأوامر عقدة Canvas من القوائم الأساسية المضمّنة إلى nodeInvokePolicies الخاصة بـ Plugin.
• إضافة إعداد مضيف Canvas مملوك لـ Plugin في plugins.entries.canvas.config.host.
• نقل تقديم Canvas وA2UI عبر HTTP ليصبح خلف تسجيل مسارات HTTP في Plugin ‏Canvas.
• إضافة توجيه عام لترقية WebSocket الخاصة بـ Plugin لمسارات HTTP المملوكة لـ Plugin.
• استبدال عنوان URL لمضيف Gateway والمصادقة على إمكانات العقدة الخاصين بـ Canvas بسطح Plugin مستضاف عام ومساعدات عامة لإمكانات العقدة.
• إضافة محللات وسائط مستضافة يملكها Plugin كي تُحل عناوين URL لمستندات Canvas عبر Plugin ‏Canvas بدلًا من استيراد النواة للتفاصيل الداخلية لمستندات Canvas.
• إضافة api.registerNodeCliFeature(...) كي يتمكن Canvas من إعلان openclaw nodes canvas بوصفه ميزة عقدة مملوكة لـ Plugin دون كتابة مسار الأمر الأب يدويًا.
• إزالة استيرادات الإنتاج ضمن src/** لـ extensions/canvas/runtime-api.js.
• نقل مصدر حزمة A2UI من apps/shared/OpenClawKit/Tools/CanvasA2UI إلى extensions/canvas/src/host/a2ui-app.
• نقل تنفيذ بناء/نسخ A2UI إلى extensions/canvas/scripts واستبدال ربط البناء الجذري بخطافات أصول عامة لـ Plugins المضمنة.
• إزالة الاسم البديل القديم لإعداد المستوى الأعلى canvasHost من وقت التشغيل.
• الإبقاء على ترحيل Canvas في أداة الفحص كي يعيد openclaw doctor --fix كتابة إعدادات canvasHost القديمة إلى plugins.entries.canvas.config.host.
• إزالة توافق بروتوكول Canvas للوكلاء القدامى خلف الإصدار 4 من بروتوكول Gateway. تستخدم الآن العملاء الأصلية وGateway فقط pluginSurfaceUrls.canvas بالإضافة إلى node.pluginSurface.refresh؛ أما مسار canvasHostUrl وcanvasCapability وnode.canvas.capability.refresh المهمل، فهو غير مدعوم عمدًا في إعادة الهيكلة التجريبية هذه.
• تحديث قائمة Plugins المولّدة لتتضمن Canvas.
• إضافة وثائق مرجعية لـ Plugin في docs/plugins/reference/canvas.md.

أسطح Canvas المتبقية المعروفة والمملوكة للنواة:

• لا تزال معالجات Canvas في التطبيقات الأصلية ضمن apps/ تستهلك عمدًا سطح Plugin ‏Canvas
• معالجات بروتوكول/عميل Canvas في التطبيقات الأصلية ضمن apps/
• لا يزال ناتج العنصر المنشور يستخدم dist/canvas-host/a2ui للبحث المتوافق مع الإصدارات السابقة في وقت التشغيل، لكن خطوة النسخ أصبحت الآن مملوكة لـ Plugin

الشكل المستهدف

ينبغي أن يملك extensions/canvas ما يلي:

• بيان Plugin والبيانات الوصفية للحزمة
• تسجيل أداة الوكيل
• سياسة أمر استدعاء العقدة
• مضيف Canvas ووقت تشغيل A2UI
• مصدر حزمة Canvas ‏A2UI وبرامج بناء/نسخ الأصول النصية
• إنشاء مستندات Canvas وحل الأصول
• تنفيذ CLI الخاص بـ Canvas
• صفحة وثائق Canvas وإدخال قائمة Plugins

ينبغي أن تملك النواة الواجهات العامة فقط:

• اكتشاف Plugins وتسجيلها
• سجل أدوات الوكيل العام
• سجل سياسات استدعاء العقدة العام
• توجيه HTTP/المصادقة في Gateway وترقية WebSocket بصورة عامة
• حل عناوين URL لأسطح Plugins المستضافة بصورة عامة
• تسجيل محللات الوسائط المستضافة بصورة عامة
• نقل إمكانات العقدة بصورة عامة
• البنية التحتية العامة للإعداد
• اكتشاف خطافات أصول Plugins المضمنة بصورة عامة

يجوز للتطبيقات الأصلية الاحتفاظ بمعالجات أوامر Canvas بوصفها عملاء للبروتوكول. وهي ليست مالكة وقت تشغيل Plugin.

خطوات الترحيل

1. تعامل مع plugins.entries.canvas.config.host بوصفه سطح الإعداد المملوك لـ Plugin.
2. حدّث الوثائق بحيث تصف Canvas بأنه Plugin مضمن تجريبي.
3. شغّل اختبارات Canvas المركّزة، وفحوصات قائمة Plugins، وفحوصات API الخاصة بـ SDK ‏Plugin، وبوابات البناء/الأنواع المتأثرة بحدود وقت التشغيل.

قائمة تدقيق المراجعة

قبل اعتبار إعادة الهيكلة مكتملة:

• لا يعيد 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.
• ينص متن طلب السحب صراحةً على أن 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

شغّل pnpm build قبل الدفع إذا تغيّر ملف تصدير وقت التشغيل أو الاستيراد الكسول أو الحزم أو أسطح Plugin المنشورة.