diff --git a/docs/ar/channels/matrix.md b/docs/ar/channels/matrix.md index 050c0446b..2c43aa121 100644 --- a/docs/ar/channels/matrix.md +++ b/docs/ar/channels/matrix.md @@ -1,29 +1,29 @@ --- read_when: - إعداد Matrix في OpenClaw - - تكوين التشفير التام بين الطرفين E2EE والتحقق في Matrix -summary: حالة دعم Matrix وإعداده وأمثلة التكوين + - تهيئة التشفير من الطرف إلى الطرف (E2EE) والتحقق في Matrix +summary: حالة دعم Matrix، والإعداد، وأمثلة التهيئة title: Matrix x-i18n: - generated_at: "2026-04-09T01:30:25Z" + generated_at: "2026-04-15T07:17:44Z" model: gpt-5.4 provider: openai - source_hash: 28fc13c7620c1152200315ae69c94205da6de3180c53c814dd8ce03b5cb1758f + source_hash: 631f6fdcfebc23136c1a66b04851a25c047535d13cceba5650b8b421bc3afcf8 source_path: channels/matrix.md workflow: 15 --- # Matrix -Matrix هو إضافة قناة مدمجة لـ OpenClaw. -ويستخدم `matrix-js-sdk` الرسمي ويدعم الرسائل المباشرة، والغرف، والخيوط، والوسائط، والتفاعلات، واستطلاعات الرأي، والموقع، وE2EE. +Matrix هو Plugin قناة مضمّن لـ OpenClaw. +وهو يستخدم `matrix-js-sdk` الرسمي ويدعم الرسائل الخاصة، والغرف، وسلاسل الرسائل، والوسائط، والتفاعلات، والاستطلاعات، والموقع، والتشفير من الطرف إلى الطرف. -## الإضافة المدمجة +## Plugin مضمّن -يأتي Matrix كإضافة مدمجة في إصدارات OpenClaw الحالية، لذلك لا تحتاج -البنيات المعبأة العادية إلى تثبيت منفصل. +يأتي Matrix كـ Plugin مضمّن في إصدارات OpenClaw الحالية، لذلك لا تحتاج +عمليات البناء المجمّعة العادية إلى تثبيت منفصل. -إذا كنت تستخدم إصدارًا أقدم أو تثبيتًا مخصصًا يستبعد Matrix، فقم بتثبيته +إذا كنت تستخدم إصدارًا أقدم أو تثبيتًا مخصصًا يستبعد Matrix، فثبّته يدويًا: التثبيت من npm: @@ -38,20 +38,20 @@ openclaw plugins install @openclaw/matrix openclaw plugins install ./path/to/local/matrix-plugin ``` -راجع [Plugins](/ar/tools/plugin) لمعرفة سلوك الإضافات وقواعد التثبيت. +راجع [Plugins](/ar/tools/plugin) لمعرفة سلوك Plugins وقواعد التثبيت. ## الإعداد -1. تأكد من توفر إضافة Matrix. - - إصدارات OpenClaw الحالية المعبأة تتضمنها بالفعل. - - يمكن للتثبيتات الأقدم/المخصصة إضافتها يدويًا بالأوامر أعلاه. +1. تأكد من أن Plugin Matrix متاح. + - إصدارات OpenClaw المجمّعة الحالية تتضمنه بالفعل. + - يمكن لعمليات التثبيت الأقدم/المخصصة إضافته يدويًا باستخدام الأوامر أعلاه. 2. أنشئ حساب Matrix على الخادم المنزلي الخاص بك. -3. كوّن `channels.matrix` باستخدام أحد الخيارين: +3. هيّئ `channels.matrix` باستخدام أحد الخيارين: - `homeserver` + `accessToken`، أو - `homeserver` + `userId` + `password`. -4. أعد تشغيل البوابة. -5. ابدأ رسالة مباشرة مع البوت أو ادعه إلى غرفة. - - تعمل دعوات Matrix الجديدة فقط عندما يسمح `channels.matrix.autoJoin` بذلك. +4. أعد تشغيل Gateway. +5. ابدأ رسالة خاصة مع البوت أو ادعه إلى غرفة. + - لا تعمل دعوات Matrix الجديدة إلا عندما يسمح بها `channels.matrix.autoJoin`. مسارات الإعداد التفاعلية: @@ -65,25 +65,25 @@ openclaw configure --section channels - عنوان URL للخادم المنزلي - طريقة المصادقة: رمز وصول أو كلمة مرور - معرّف المستخدم (لمصادقة كلمة المرور فقط) -- اسم جهاز اختياري -- ما إذا كنت تريد تمكين E2EE -- ما إذا كنت تريد تكوين الوصول إلى الغرف والانضمام التلقائي للدعوات +- اسم الجهاز الاختياري +- ما إذا كان يجب تمكين التشفير من الطرف إلى الطرف +- ما إذا كان يجب إعداد وصول الغرف والانضمام التلقائي للدعوات -سلوكيات المعالج الأساسية: +السلوكيات الأساسية للمعالج: -- إذا كانت متغيرات البيئة الخاصة بمصادقة Matrix موجودة بالفعل ولم يكن لدى ذلك الحساب مصادقة محفوظة بالفعل في التكوين، فسيعرض المعالج اختصارًا لاستخدام البيئة للإبقاء على المصادقة في متغيرات البيئة. +- إذا كانت متغيرات بيئة مصادقة Matrix موجودة بالفعل ولم يكن لهذا الحساب مصادقة محفوظة في الإعدادات بعد، فسيعرض المعالج اختصارًا لاستخدام البيئة للإبقاء على المصادقة في متغيرات البيئة. - تتم تسوية أسماء الحسابات إلى معرّف الحساب. على سبيل المثال، يتحول `Ops Bot` إلى `ops-bot`. -- تقبل إدخالات قائمة السماح للرسائل المباشرة `@user:server` مباشرة؛ أما أسماء العرض فلا تعمل إلا عندما يعثر البحث الحي في الدليل على تطابق واحد دقيق. -- تقبل إدخالات قائمة السماح للغرف معرّفات الغرف والأسماء المستعارة مباشرة. يفضل استخدام `!room:server` أو `#alias:server`؛ ويتم تجاهل الأسماء غير المحلولة وقت التشغيل بواسطة دقة قائمة السماح. -- في وضع قائمة السماح للانضمام التلقائي للدعوات، استخدم فقط أهداف الدعوة الثابتة: `!roomId:server` أو `#alias:server` أو `*`. تُرفض أسماء الغرف العادية. +- تقبل إدخالات قائمة السماح للرسائل الخاصة `@user:server` مباشرةً؛ ولا تعمل أسماء العرض إلا عندما يعثر البحث المباشر في الدليل على تطابق واحد دقيق. +- تقبل إدخالات قائمة السماح للغرف معرّفات الغرف والأسماء المستعارة مباشرةً. يُفضَّل `!room:server` أو `#alias:server`؛ ويتم تجاهل الأسماء غير المحلولة وقت التشغيل عند حل قائمة السماح. +- في وضع قائمة السماح للانضمام التلقائي للدعوات، استخدم فقط أهداف دعوات مستقرة: `!roomId:server` أو `#alias:server` أو `*`. يتم رفض أسماء الغرف العادية. - لحل أسماء الغرف قبل الحفظ، استخدم `openclaw channels resolve --channel matrix "Project Room"`. القيمة الافتراضية لـ `channels.matrix.autoJoin` هي `off`. -إذا تركته بدون تعيين، فلن ينضم البوت إلى الغرف المدعو إليها أو الدعوات الجديدة على نمط الرسائل المباشرة، لذلك لن يظهر في المجموعات الجديدة أو الرسائل المباشرة المدعو إليها إلا إذا انضممت يدويًا أولًا. +إذا تركته غير مضبوط، فلن ينضم البوت إلى الغرف المدعو إليها أو إلى دعوات الرسائل الخاصة الجديدة، لذلك لن يظهر في المجموعات الجديدة أو الرسائل الخاصة المدعو إليها ما لم تنضم يدويًا أولًا. -عيّن `autoJoin: "allowlist"` مع `autoJoinAllowlist` لتقييد الدعوات التي يقبلها، أو عيّن `autoJoin: "always"` إذا كنت تريد أن ينضم إلى كل دعوة. +اضبط `autoJoin: "allowlist"` مع `autoJoinAllowlist` لتقييد الدعوات التي يقبلها، أو اضبط `autoJoin: "always"` إذا كنت تريده أن ينضم إلى كل دعوة. في وضع `allowlist`، لا يقبل `autoJoinAllowlist` إلا `!roomId:server` أو `#alias:server` أو `*`. @@ -118,7 +118,7 @@ openclaw configure --section channels } ``` -إعداد حد أدنى قائم على الرمز: +إعداد أساسي باستخدام الرمز المميز: ```json5 { @@ -133,7 +133,7 @@ openclaw configure --section channels } ``` -إعداد قائم على كلمة المرور (يتم تخزين الرمز مؤقتًا بعد تسجيل الدخول): +إعداد باستخدام كلمة المرور (يتم تخزين الرمز المميز مؤقتًا بعد تسجيل الدخول): ```json5 { @@ -149,11 +149,11 @@ openclaw configure --section channels } ``` -يخزن Matrix بيانات الاعتماد المؤقتة في `~/.openclaw/credentials/matrix/`. -ويستخدم الحساب الافتراضي `credentials.json`؛ بينما تستخدم الحسابات المسماة `credentials-.json`. -وعندما توجد بيانات اعتماد مخزنة مؤقتًا هناك، يتعامل OpenClaw مع Matrix على أنه مكوَّن من أجل الإعداد وdoctor واكتشاف حالة القناة حتى إذا لم تكن المصادقة الحالية مضبوطة مباشرة في التكوين. +يخزن Matrix بيانات الاعتماد المخزنة مؤقتًا في `~/.openclaw/credentials/matrix/`. +يستخدم الحساب الافتراضي `credentials.json`؛ وتستخدم الحسابات المسماة `credentials-.json`. +عند وجود بيانات اعتماد مخزنة مؤقتًا هناك، يتعامل OpenClaw مع Matrix على أنه مُهيأ لأغراض الإعداد وdoctor واكتشاف حالة القناة، حتى إذا لم تكن المصادقة الحالية مضبوطة مباشرةً في الإعدادات. -المعادِلات من متغيرات البيئة (تُستخدم عندما لا يكون مفتاح التكوين معيّنًا): +مكافئات متغيرات البيئة (تُستخدم عندما لا يكون مفتاح الإعداد مضبوطًا): - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -162,7 +162,7 @@ openclaw configure --section channels - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -للحسابات غير الافتراضية، استخدم متغيرات البيئة الخاصة بنطاق الحساب: +للحسابات غير الافتراضية، استخدم متغيرات البيئة ذات النطاق الخاص بالحساب: - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -176,19 +176,19 @@ openclaw configure --section channels - `MATRIX_OPS_HOMESERVER` - `MATRIX_OPS_ACCESS_TOKEN` -وبالنسبة إلى معرّف الحساب الموحّد `ops-bot`، استخدم: +لمعرّف الحساب المطبّع `ops-bot`، استخدم: - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -يقوم Matrix بتهريب علامات الترقيم في معرّفات الحسابات لإبقاء متغيرات البيئة المحددة بالنطاق خالية من التعارضات. -فعلى سبيل المثال، يتحول `-` إلى `_X2D_`، لذلك يتحول `ops-prod` إلى `MATRIX_OPS_X2D_PROD_*`. +يقوم Matrix بتهريب علامات الترقيم في معرّفات الحسابات لإبقاء متغيرات البيئة ذات النطاق الخاص خالية من التعارضات. +على سبيل المثال، يتحول `-` إلى `_X2D_`، لذا يتم تعيين `ops-prod` إلى `MATRIX_OPS_X2D_PROD_*`. -لا يعرض المعالج التفاعلي اختصار متغيرات البيئة إلا عندما تكون متغيرات بيئة المصادقة هذه موجودة بالفعل، ولا يكون لدى الحساب المحدد مصادقة Matrix محفوظة بالفعل في التكوين. +لا يعرض المعالج التفاعلي اختصار متغيرات البيئة إلا عندما تكون متغيرات بيئة المصادقة هذه موجودة بالفعل ولا تكون مصادقة Matrix محفوظة في الإعدادات للحساب المحدد. -## مثال على التكوين +## مثال على التهيئة -هذا تكوين أساسي عملي يتضمن اقتران الرسائل المباشرة، وقائمة سماح للغرف، وتمكين E2EE: +هذا إعداد أساسي عملي مع اقتران الرسائل الخاصة، وقائمة سماح للغرف، وتمكين التشفير من الطرف إلى الطرف: ```json5 { @@ -223,17 +223,17 @@ openclaw configure --section channels } ``` -ينطبق `autoJoin` على جميع دعوات Matrix، بما في ذلك الدعوات على نمط الرسائل المباشرة. لا يستطيع OpenClaw -تصنيف الغرفة المدعو إليها بشكل موثوق على أنها رسالة مباشرة أو مجموعة وقت الدعوة، لذلك تمر جميع الدعوات عبر `autoJoin` -أولًا. ويُطبَّق `dm.policy` بعد انضمام البوت وتصنيف الغرفة على أنها رسالة مباشرة. +ينطبق `autoJoin` على جميع دعوات Matrix، بما في ذلك دعوات نمط الرسائل الخاصة. لا يستطيع OpenClaw +تصنيف الغرفة المدعو إليها بشكل موثوق على أنها رسالة خاصة أو مجموعة في وقت الدعوة، لذلك تمر كل الدعوات عبر `autoJoin` +أولًا. يتم تطبيق `dm.policy` بعد انضمام البوت وتصنيف الغرفة على أنها رسالة خاصة. ## معاينات البث -بث الردود في Matrix يتم تمكينه اختياريًا. +بث الردود في Matrix اختياري. -عيّن `channels.matrix.streaming` إلى `"partial"` عندما تريد أن يرسل OpenClaw معاينة حية واحدة -للرد، ويحرر تلك المعاينة في مكانها أثناء قيام النموذج بإنشاء النص، ثم ينهيها عندما -يكتمل الرد: +اضبط `channels.matrix.streaming` على `"partial"` عندما تريد أن يرسل OpenClaw معاينة مباشرة واحدة +للرد، ويعدّل هذه المعاينة في مكانها بينما يقوم النموذج بإنشاء النص، ثم ينهيها عند اكتمال +الرد: ```json5 { @@ -246,37 +246,37 @@ openclaw configure --section channels ``` - `streaming: "off"` هو الإعداد الافتراضي. ينتظر OpenClaw الرد النهائي ويرسله مرة واحدة. -- `streaming: "partial"` ينشئ رسالة معاينة واحدة قابلة للتحرير لكتلة المساعد الحالية باستخدام رسائل Matrix النصية العادية. يحافظ ذلك على سلوك الإشعار القديم في Matrix الذي يعتمد على المعاينة أولًا، لذلك قد تُظهر العملاء القياسية إشعارًا عند أول نص معاينة متدفق بدلًا من الكتلة المكتملة. -- `streaming: "quiet"` ينشئ إشعار معاينة هادئًا واحدًا قابلاً للتحرير لكتلة المساعد الحالية. استخدم هذا فقط عندما تكون قد كوّنت أيضًا قواعد دفع للمستلمين من أجل تعديلات المعاينة النهائية. -- `blockStreaming: true` يفعّل رسائل تقدم منفصلة في Matrix. عند تمكين بث المعاينة، يحتفظ Matrix بالمسودة الحية للكتلة الحالية ويحافظ على الكتل المكتملة كرسائل منفصلة. -- عند تشغيل بث المعاينة وإيقاف `blockStreaming`، يقوم Matrix بتحرير المسودة الحية في مكانها وينهي الحدث نفسه عندما تنتهي الكتلة أو الدور. -- إذا لم تعد المعاينة تلائم حدث Matrix واحدًا، يوقف OpenClaw بث المعاينة ويعود إلى التسليم النهائي العادي. -- تستمر ردود الوسائط في إرسال المرفقات بشكل طبيعي. وإذا لم يعد من الممكن إعادة استخدام معاينة قديمة بأمان، يقوم OpenClaw بحذفها قبل إرسال رد الوسائط النهائي. -- تتطلب تعديلات المعاينة استدعاءات إضافية إلى Matrix API. اترك البث متوقفًا إذا كنت تريد السلوك الأكثر تحفظًا فيما يتعلق بحدود المعدل. +- `streaming: "partial"` ينشئ رسالة معاينة واحدة قابلة للتحرير لكتلة المساعد الحالية باستخدام رسائل Matrix النصية العادية. يحافظ هذا على سلوك الإشعارات القديم في Matrix القائم على المعاينة أولًا، لذا قد تُرسل التطبيقات القياسية إشعارًا عند أول نص معاينة متدفق بدلًا من الكتلة المكتملة. +- `streaming: "quiet"` ينشئ إشعار معاينة هادئًا واحدًا قابلًا للتحرير لكتلة المساعد الحالية. استخدم هذا فقط عندما تهيئ أيضًا قواعد دفع للمستلمين من أجل تعديلات المعاينات النهائية. +- `blockStreaming: true` يمكّن رسائل تقدم Matrix المنفصلة. عند تمكين بث المعاينة، يحتفظ Matrix بالمسودة الحية للكتلة الحالية ويحافظ على الكتل المكتملة كرسائل منفصلة. +- عند تشغيل بث المعاينة وإيقاف `blockStreaming`، يقوم Matrix بتحرير المسودة الحية في مكانها وينهي الحدث نفسه عند اكتمال الكتلة أو الدور. +- إذا لم تعد المعاينة تتسع في حدث Matrix واحد، يوقف OpenClaw بث المعاينة ويعود إلى التسليم النهائي العادي. +- ما زالت ردود الوسائط ترسل المرفقات بشكل طبيعي. إذا تعذر إعادة استخدام معاينة قديمة بأمان، فسيقوم OpenClaw بحذفها قبل إرسال رد الوسائط النهائي. +- تكلف تعديلات المعاينة استدعاءات إضافية إلى Matrix API. اترك البث معطّلًا إذا كنت تريد السلوك الأكثر تحفظًا من ناحية حدود المعدل. لا يقوم `blockStreaming` بتمكين معاينات المسودات بمفرده. استخدم `streaming: "partial"` أو `streaming: "quiet"` لتعديلات المعاينة؛ ثم أضف `blockStreaming: true` فقط إذا كنت تريد أيضًا أن تظل كتل المساعد المكتملة مرئية كرسائل تقدم منفصلة. -إذا كنت تحتاج إلى إشعارات Matrix القياسية بدون قواعد دفع مخصصة، فاستخدم `streaming: "partial"` لسلوك المعاينة أولًا أو اترك `streaming` متوقفًا للتسليم النهائي فقط. مع `streaming: "off"`: +إذا كنت بحاجة إلى إشعارات Matrix القياسية من دون قواعد دفع مخصصة، فاستخدم `streaming: "partial"` لسلوك المعاينة أولًا أو اترك `streaming` معطّلًا للتسليم النهائي فقط. عند استخدام `streaming: "off"`: -- `blockStreaming: true` يرسل كل كتلة مكتملة كرسالة Matrix عادية مُشعِرة. -- `blockStreaming: false` يرسل فقط الرد النهائي المكتمل كرسالة Matrix عادية مُشعِرة. +- يرسل `blockStreaming: true` كل كتلة مكتملة كرسالة Matrix عادية مُرسِلة للإشعارات. +- يرسل `blockStreaming: false` الرد المكتمل النهائي فقط كرسالة Matrix عادية مُرسِلة للإشعارات. -### قواعد الدفع المستضافة ذاتيًا للمعاينات النهائية الهادئة +### قواعد دفع مستضافة ذاتيًا للمعاينات الهادئة النهائية -إذا كنت تشغّل بنية Matrix الخاصة بك وتريد أن تُشعِر المعاينات الهادئة فقط عند اكتمال كتلة أو -رد نهائي، فعيّن `streaming: "quiet"` وأضف قاعدة دفع لكل مستخدم لتعديلات المعاينة النهائية. +إذا كنت تشغّل بنية Matrix التحتية الخاصة بك وتريد أن ترسل المعاينات الهادئة إشعارًا فقط عند اكتمال كتلة أو +الرد النهائي، فاضبط `streaming: "quiet"` وأضف قاعدة دفع لكل مستخدم من أجل تعديلات المعاينات النهائية. -يكون هذا عادة إعدادًا على مستوى المستخدم المستلم، وليس تغييرًا عامًا في تكوين الخادم المنزلي: +يكون هذا عادة إعدادًا على مستوى المستخدم المستلم، وليس تغييرًا عامًا في إعدادات الخادم المنزلي: خريطة سريعة قبل أن تبدأ: -- المستخدم المستلم = الشخص الذي ينبغي أن يتلقى الإشعار +- المستخدم المستلم = الشخص الذي يجب أن يتلقى الإشعار - مستخدم البوت = حساب Matrix الخاص بـ OpenClaw الذي يرسل الرد - استخدم رمز وصول المستخدم المستلم في استدعاءات API أدناه - طابق `sender` في قاعدة الدفع مع MXID الكامل لمستخدم البوت -1. كوّن OpenClaw لاستخدام المعاينات الهادئة: +1. هيّئ OpenClaw لاستخدام المعاينات الهادئة: ```json5 { @@ -288,13 +288,13 @@ openclaw configure --section channels } ``` -2. تأكد من أن حساب المستلم يتلقى بالفعل إشعارات دفع Matrix العادية. لا تعمل قواعد - المعاينة الهادئة إلا إذا كان لدى ذلك المستخدم بالفعل pushers/أجهزة تعمل. +2. تأكد من أن حساب المستلم يتلقى بالفعل إشعارات دفع Matrix العادية. لا تعمل + قواعد المعاينات الهادئة إلا إذا كان لذلك المستخدم pushers/devices عاملة بالفعل. 3. احصل على رمز وصول المستخدم المستلم. - استخدم رمز المستخدم المتلقي، وليس رمز البوت. - - تكون إعادة استخدام رمز جلسة عميل موجودة هي الأسهل عادة. - - إذا كنت بحاجة إلى إنشاء رمز جديد، يمكنك تسجيل الدخول عبر Matrix Client-Server API القياسي: + - غالبًا ما يكون إعادة استخدام رمز جلسة عميل موجودة هو الأسهل. + - إذا كنت بحاجة إلى إصدار رمز جديد، يمكنك تسجيل الدخول عبر Matrix Client-Server API القياسي: ```bash curl -sS -X POST \ @@ -318,10 +318,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushers" ``` -إذا أعاد هذا الاستدعاء عدم وجود pushers/أجهزة نشطة، فأصلِح إشعارات Matrix العادية أولًا قبل إضافة +إذا لم يُرجع هذا أي pushers/devices نشطة، فأصلح إشعارات Matrix العادية أولًا قبل إضافة قاعدة OpenClaw أدناه. -يضع OpenClaw علامة على تعديلات المعاينة النصية النهائية فقط باستخدام: +يضع OpenClaw علامة على تعديلات المعاينات النهائية النصية فقط بالقيمة التالية: ```json { @@ -329,7 +329,7 @@ curl -sS \ } ``` -5. أنشئ قاعدة دفع من نوع override لكل حساب مستلم ينبغي أن يتلقى هذه الإشعارات: +5. أنشئ قاعدة دفع override لكل حساب مستلم يجب أن يتلقى هذه الإشعارات: ```bash curl -sS -X PUT \ @@ -362,22 +362,22 @@ curl -sS -X PUT \ استبدل هذه القيم قبل تشغيل الأمر: - `https://matrix.example.org`: عنوان URL الأساسي للخادم المنزلي لديك -- `$USER_ACCESS_TOKEN`: رمز وصول المستخدم المستلم -- `openclaw-finalized-preview-botname`: معرّف قاعدة فريد لهذا البوت لهذا المستخدم المستلم -- `@bot:example.org`: MXID بوت Matrix الخاص بـ OpenClaw لديك، وليس MXID المستخدم المستلم +- `$USER_ACCESS_TOKEN`: رمز وصول المستخدم المتلقي +- `openclaw-finalized-preview-botname`: معرّف قاعدة فريد لهذا البوت لهذا المستخدم المتلقي +- `@bot:example.org`: MXID بوت Matrix الخاص بـ OpenClaw لديك، وليس MXID المستخدم المتلقي -مهم لإعدادات البوتات المتعددة: +مهم لإعدادات تعدد البوتات: -- تُفهرس قواعد الدفع باستخدام `ruleId`. تؤدي إعادة تشغيل `PUT` على معرّف القاعدة نفسه إلى تحديث تلك القاعدة الواحدة. -- إذا كان ينبغي لمستخدم مستلم واحد أن يتلقى إشعارات لعدة حسابات بوت Matrix تابعة لـ OpenClaw، فأنشئ قاعدة واحدة لكل بوت مع معرّف قاعدة فريد لكل تطابق مرسل. -- نمط بسيط هو `openclaw-finalized-preview-`، مثل `openclaw-finalized-preview-ops` أو `openclaw-finalized-preview-support`. +- تتم فهرسة قواعد الدفع باستخدام `ruleId`. تؤدي إعادة تشغيل `PUT` على معرّف القاعدة نفسه إلى تحديث تلك القاعدة فقط. +- إذا كان يجب على مستخدم مستلم واحد تلقي إشعارات من عدة حسابات Matrix bot خاصة بـ OpenClaw، فأنشئ قاعدة واحدة لكل bot مع معرّف قاعدة فريد لكل تطابق `sender`. +- نمط بسيط لذلك هو `openclaw-finalized-preview-`، مثل `openclaw-finalized-preview-ops` أو `openclaw-finalized-preview-support`. يتم تقييم القاعدة مقابل مرسل الحدث: -- قم بالمصادقة باستخدام رمز المستخدم المستلم -- طابق `sender` مع MXID بوت OpenClaw +- صادق باستخدام رمز المستخدم المستلم +- طابق `sender` مع MXID الخاص ببوت OpenClaw -6. تحقق من وجود القاعدة: +6. تحقّق من وجود القاعدة: ```bash curl -sS \ @@ -385,8 +385,8 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -7. اختبر ردًا متدفقًا. في الوضع الهادئ، ينبغي أن تُظهر الغرفة معاينة مسودة هادئة وأن - يُرسل التعديل النهائي في مكانه إشعارًا واحدًا عند انتهاء الكتلة أو الدور. +7. اختبر ردًا متدفقًا. في الوضع الهادئ، يجب أن تعرض الغرفة معاينة مسودة هادئة، ويجب أن يرسل + التعديل النهائي في مكانه إشعارًا واحدًا عند اكتمال الكتلة أو الدور. إذا احتجت إلى إزالة القاعدة لاحقًا، فاحذف معرّف القاعدة نفسه باستخدام رمز المستخدم المستلم: @@ -398,33 +398,33 @@ curl -sS -X DELETE \ ملاحظات: -- أنشئ القاعدة باستخدام رمز وصول المستخدم المستلم، وليس رمز البوت. -- تُدرج قواعد `override` المعرّفة من قبل المستخدم الجديدة قبل قواعد المنع الافتراضية، لذلك لا حاجة إلى معامل ترتيب إضافي. -- يؤثر هذا فقط في تعديلات المعاينة النصية النهائية التي يستطيع OpenClaw إنهاءها بأمان في مكانها. أما بدائل الوسائط وبدائل المعاينات القديمة فما تزال تستخدم تسليم Matrix العادي. +- أنشئ القاعدة باستخدام رمز وصول المستخدم المستلم، وليس رمز bot. +- يتم إدراج قواعد `override` الجديدة المعرّفة من قبل المستخدم قبل قواعد الكتم الافتراضية، لذلك لا حاجة إلى أي معامل ترتيب إضافي. +- يؤثر هذا فقط في تعديلات المعاينات النصية النهائية التي يستطيع OpenClaw إنهاءها بأمان في مكانها. أما بدائل الوسائط وبدائل المعاينات القديمة فتستمر في استخدام تسليم Matrix العادي. - إذا أظهر `GET /_matrix/client/v3/pushers` عدم وجود pushers، فهذا يعني أن المستخدم لا يملك بعد تسليم دفع Matrix عاملًا لهذا الحساب/الجهاز. #### Synapse -بالنسبة إلى Synapse، يكون الإعداد أعلاه كافيًا عادة بمفرده: +بالنسبة إلى Synapse، يكون الإعداد أعلاه كافيًا عادةً بمفرده: -- لا يلزم أي تغيير خاص في `homeserver.yaml` لإشعارات معاينة OpenClaw النهائية. +- لا يلزم أي تغيير خاص في `homeserver.yaml` لإشعارات معاينات OpenClaw النهائية. - إذا كان نشر Synapse لديك يرسل بالفعل إشعارات دفع Matrix العادية، فإن رمز المستخدم + استدعاء `pushrules` أعلاه هما خطوة الإعداد الأساسية. -- إذا كنت تشغّل Synapse خلف وكيل عكسي أو workers، فتأكد من أن `/_matrix/client/.../pushrules/` يصل إلى Synapse بشكل صحيح. -- إذا كنت تشغّل Synapse workers، فتأكد من أن pushers تعمل بشكل سليم. تتم معالجة تسليم الدفع بواسطة العملية الرئيسية أو `synapse.app.pusher` / عمال pusher المكوّنين. +- إذا كنت تشغّل Synapse خلف reverse proxy أو workers، فتأكد من أن `/_matrix/client/.../pushrules/` يصل إلى Synapse بشكل صحيح. +- إذا كنت تشغّل Synapse workers، فتأكد من أن pushers سليمة. تتم معالجة تسليم الدفع بواسطة العملية الرئيسية أو `synapse.app.pusher` / workers الخاصة بـ pusher المهيأة. #### Tuwunel -بالنسبة إلى Tuwunel، استخدم تدفق الإعداد نفسه واستدعاء API لقواعد الدفع كما هو موضح أعلاه: +بالنسبة إلى Tuwunel، استخدم تدفق الإعداد نفسه واستدعاء API الخاص بـ push-rule الموضح أعلاه: -- لا يلزم أي تكوين خاص بـ Tuwunel لعلامة المعاينة النهائية نفسها. +- لا يلزم أي إعداد خاص بـ Tuwunel لمؤشر المعاينة النهائية نفسه. - إذا كانت إشعارات Matrix العادية تعمل بالفعل لذلك المستخدم، فإن رمز المستخدم + استدعاء `pushrules` أعلاه هما خطوة الإعداد الأساسية. -- إذا بدا أن الإشعارات تختفي أثناء نشاط المستخدم على جهاز آخر، فتحقق مما إذا كان `suppress_push_when_active` مفعّلًا. أضاف Tuwunel هذا الخيار في Tuwunel 1.4.2 بتاريخ 12 سبتمبر 2025، ويمكنه أن يمنع عمدًا الإشعارات المرسلة إلى الأجهزة الأخرى أثناء نشاط أحد الأجهزة. +- إذا بدا أن الإشعارات تختفي بينما يكون المستخدم نشطًا على جهاز آخر، فتحقق مما إذا كان `suppress_push_when_active` مُمكّنًا. أضاف Tuwunel هذا الخيار في Tuwunel 1.4.2 بتاريخ 12 سبتمبر 2025، ويمكنه عمدًا كتم الإشعارات إلى الأجهزة الأخرى أثناء نشاط أحد الأجهزة. -## غرف البوت إلى البوت +## غرف bot إلى bot -بشكل افتراضي، يتم تجاهل رسائل Matrix الواردة من حسابات Matrix أخرى مكوّنة لـ OpenClaw. +بشكل افتراضي، يتم تجاهل رسائل Matrix الواردة من حسابات Matrix OpenClaw الأخرى المهيأة. -استخدم `allowBots` عندما تريد عمدًا حركة Matrix بين الوكلاء: +استخدم `allowBots` عندما تريد عمدًا حركة مرور Matrix بين الوكلاء: ```json5 { @@ -441,17 +441,17 @@ curl -sS -X DELETE \ } ``` -- `allowBots: true` يقبل الرسائل من حسابات بوت Matrix أخرى مكوّنة في الغرف المسموح بها والرسائل المباشرة. -- `allowBots: "mentions"` يقبل تلك الرسائل فقط عندما تذكر هذا البوت بوضوح في الغرف. وتظل الرسائل المباشرة مسموحًا بها. -- يقوم `groups..allowBots` بتجاوز الإعداد على مستوى الحساب لغرفة واحدة. -- ما يزال OpenClaw يتجاهل الرسائل من معرّف مستخدم Matrix نفسه لتجنب حلقات الرد الذاتي. -- لا يكشف Matrix هنا عن علامة بوت أصلية؛ ويتعامل OpenClaw مع "مكتوبة بواسطة بوت" على أنها "مرسلة بواسطة حساب Matrix آخر مكوَّن على بوابة OpenClaw هذه". +- يقبل `allowBots: true` الرسائل من حسابات Matrix bot الأخرى المهيأة في الغرف المسموح بها والرسائل الخاصة. +- يقبل `allowBots: "mentions"` تلك الرسائل فقط عندما تذكر هذا bot بوضوح داخل الغرف. وتبقى الرسائل الخاصة مسموحًا بها. +- يتجاوز `groups..allowBots` الإعداد على مستوى الحساب لغرفة واحدة. +- ما زال OpenClaw يتجاهل الرسائل من معرّف مستخدم Matrix نفسه لتجنب حلقات الرد الذاتي. +- لا يوفّر Matrix هنا علامة bot أصلية؛ ويتعامل OpenClaw مع "مكتوب بواسطة bot" على أنه "مرسل بواسطة حساب Matrix آخر مهيأ على Gateway OpenClaw هذا". -استخدم قوائم سماح صارمة للغرف ومتطلبات الذكر عند تمكين حركة البوت إلى البوت في الغرف المشتركة. +استخدم قوائم سماح صارمة للغرف ومتطلبات الذكر عند تمكين حركة bot إلى bot في الغرف المشتركة. ## التشفير والتحقق -في الغرف المشفرة (E2EE)، تستخدم أحداث الصور الصادرة `thumbnail_file` بحيث تُشفَّر معاينات الصور إلى جانب المرفق الكامل. وتستمر الغرف غير المشفرة في استخدام `thumbnail_url` العادي. لا يلزم أي تكوين — تكتشف الإضافة حالة E2EE تلقائيًا. +في الغرف المشفرة (E2EE)، تستخدم أحداث الصور الصادرة `thumbnail_file` بحيث يتم تشفير معاينات الصور إلى جانب المرفق الكامل. أما الغرف غير المشفرة فتستمر في استخدام `thumbnail_url` العادي. لا يلزم أي إعداد — يكتشف Plugin حالة E2EE تلقائيًا. تمكين التشفير: @@ -475,31 +475,31 @@ curl -sS -X DELETE \ openclaw matrix verify status ``` -الحالة المفصلة (تشخيصات كاملة): +حالة مفصّلة (تشخيصات كاملة): ```bash openclaw matrix verify status --verbose ``` -تضمين مفتاح الاسترداد المخزَّن في المخرجات القابلة للقراءة آليًا: +تضمين مفتاح الاسترداد المخزن في مخرجات قابلة للقراءة آليًا: ```bash openclaw matrix verify status --include-recovery-key --json ``` -تهيئة التوقيع المتقاطع وحالة التحقق: +تهيئة حالة cross-signing والتحقق: ```bash openclaw matrix verify bootstrap ``` -تشخيصات التهيئة التفصيلية: +تشخيصات bootstrap مفصلة: ```bash openclaw matrix verify bootstrap --verbose ``` -فرض إعادة تعيين جديدة لهوية التوقيع المتقاطع قبل التهيئة: +فرض إعادة تعيين جديدة لهوية cross-signing قبل bootstrap: ```bash openclaw matrix verify bootstrap --force-reset-cross-signing @@ -511,7 +511,7 @@ openclaw matrix verify bootstrap --force-reset-cross-signing openclaw matrix verify device "" ``` -تفاصيل التحقق المفصلة للجهاز: +تفاصيل مفصلة للتحقق من الجهاز: ```bash openclaw matrix verify device "" --verbose @@ -523,7 +523,7 @@ openclaw matrix verify device "" --verbose openclaw matrix verify backup status ``` -تشخيصات سلامة النسخ الاحتياطي المفصلة: +تشخيصات مفصلة لسلامة النسخ الاحتياطي: ```bash openclaw matrix verify backup status --verbose @@ -535,25 +535,25 @@ openclaw matrix verify backup status --verbose openclaw matrix verify backup restore ``` -تشخيصات الاستعادة المفصلة: +تشخيصات مفصلة للاستعادة: ```bash openclaw matrix verify backup restore --verbose ``` -احذف النسخة الاحتياطية الحالية على الخادم وأنشئ خط أساس جديدًا للنسخ الاحتياطي. إذا تعذر تحميل -مفتاح النسخة الاحتياطية المخزن بشكل نظيف، فقد تؤدي إعادة التعيين هذه أيضًا إلى إعادة إنشاء التخزين السري بحيث -تستطيع عمليات البدء البارد المستقبلية تحميل مفتاح النسخة الاحتياطية الجديد: +احذف النسخة الاحتياطية الحالية على الخادم وأنشئ خط أساس جديدًا للنسخ الاحتياطي. إذا تعذر +تحميل مفتاح النسخ الاحتياطي المخزن بشكل سليم، فيمكن لإعادة التعيين هذه أيضًا إعادة إنشاء التخزين السري بحيث +تتمكن عمليات البدء البارد المستقبلية من تحميل مفتاح النسخ الاحتياطي الجديد: ```bash openclaw matrix verify backup reset --yes ``` -تكون جميع أوامر `verify` موجزة افتراضيًا (بما في ذلك السجل الداخلي الهادئ لـ SDK) وتعرض تشخيصات مفصلة فقط مع `--verbose`. -استخدم `--json` للحصول على مخرجات كاملة قابلة للقراءة آليًا عند كتابة السكربتات. +تكون جميع أوامر `verify` موجزة بشكل افتراضي (بما في ذلك تسجيل SDK الداخلي الهادئ) ولا تعرض تشخيصات مفصلة إلا مع `--verbose`. +استخدم `--json` للحصول على مخرجات كاملة قابلة للقراءة آليًا عند الاستخدام في السكربتات. في إعدادات الحسابات المتعددة، تستخدم أوامر Matrix CLI حساب Matrix الافتراضي الضمني ما لم تمرر `--account `. -إذا قمت بتكوين عدة حسابات مسماة، فعيّن `channels.matrix.defaultAccount` أولًا وإلا فستتوقف عمليات CLI الضمنية تلك وتطلب منك اختيار حساب بشكل صريح. +إذا قمت بتهيئة عدة حسابات مسماة، فاضبط `channels.matrix.defaultAccount` أولًا وإلا ستتوقف عمليات CLI الضمنية هذه وتطلب منك اختيار حساب صراحةً. استخدم `--account` كلما أردت أن تستهدف عمليات التحقق أو الجهاز حسابًا مسمى بشكل صريح: ```bash @@ -562,43 +562,43 @@ openclaw matrix verify backup restore --account assistant openclaw matrix devices list --account assistant ``` -عندما يكون التشفير معطلًا أو غير متاح لحساب مسمى، تشير تحذيرات Matrix وأخطاء التحقق إلى مفتاح تكوين ذلك الحساب، مثل `channels.matrix.accounts.assistant.encryption`. +عندما يكون التشفير معطّلًا أو غير متاح لحساب مسمى، تشير تحذيرات Matrix وأخطاء التحقق إلى مفتاح إعداد هذا الحساب، مثل `channels.matrix.accounts.assistant.encryption`. -### ما معنى "تم التحقق" +### ما معنى "مُتحقَّق منه" -يتعامل OpenClaw مع جهاز Matrix هذا على أنه تم التحقق منه فقط عندما يتم التحقق منه بواسطة هوية التوقيع المتقاطع الخاصة بك. +يتعامل OpenClaw مع جهاز Matrix هذا على أنه مُتحقَّق منه فقط عندما يتم التحقق منه بواسطة هوية cross-signing الخاصة بك. عمليًا، يعرض `openclaw matrix verify status --verbose` ثلاث إشارات ثقة: -- `Locally trusted`: هذا الجهاز موثوق به من قبل العميل الحالي فقط -- `Cross-signing verified`: يبلّغ SDK أن الجهاز قد تم التحقق منه عبر التوقيع المتقاطع -- `Signed by owner`: الجهاز موقَّع بواسطة مفتاح التوقيع الذاتي الخاص بك +- `Locally trusted`: هذا الجهاز موثوق من قبل العميل الحالي فقط +- `Cross-signing verified`: يفيد SDK بأن الجهاز مُتحقَّق منه عبر cross-signing +- `Signed by owner`: تم توقيع الجهاز بواسطة مفتاح self-signing الخاص بك -تتحول `Verified by owner` إلى `yes` فقط عندما يكون التحقق عبر التوقيع المتقاطع أو توقيع المالك موجودًا. -ولا تكفي الثقة المحلية وحدها لكي يتعامل OpenClaw مع الجهاز على أنه متحقق منه بالكامل. +تصبح قيمة `Verified by owner` هي `yes` فقط عند وجود تحقق cross-signing أو توقيع من المالك. +ولا تكفي الثقة المحلية وحدها لكي يعامل OpenClaw الجهاز على أنه مُتحقَّق منه بالكامل. -### ما الذي تفعله التهيئة +### ما الذي يفعله bootstrap -يعد `openclaw matrix verify bootstrap` أمر الإصلاح والإعداد لحسابات Matrix المشفرة. -وينفذ كل ما يلي بالترتيب: +الأمر `openclaw matrix verify bootstrap` هو أمر الإصلاح والإعداد لحسابات Matrix المشفرة. +وهو ينفذ كل ما يلي بالترتيب: -- يهيئ التخزين السري، مع إعادة استخدام مفتاح استرداد موجود عند الإمكان -- يهيئ التوقيع المتقاطع ويرفع مفاتيح التوقيع المتقاطع العامة المفقودة -- يحاول وضع علامة على الجهاز الحالي وتوقيعه توقيعًا متقاطعًا -- ينشئ نسخة احتياطية جديدة على الخادم لمفاتيح الغرف إذا لم تكن موجودة بالفعل +- يهيّئ التخزين السري، مع إعادة استخدام مفتاح استرداد موجود متى أمكن +- يهيّئ cross-signing ويرفع مفاتيح cross-signing العامة الناقصة +- يحاول تعليم الجهاز الحالي وتوقيعه عبر cross-signing +- ينشئ نسخة احتياطية جديدة لمفاتيح الغرف على جهة الخادم إذا لم تكن موجودة بالفعل -إذا كان الخادم المنزلي يتطلب مصادقة تفاعلية لرفع مفاتيح التوقيع المتقاطع، يحاول OpenClaw الرفع بدون مصادقة أولًا، ثم باستخدام `m.login.dummy`، ثم باستخدام `m.login.password` عندما يكون `channels.matrix.password` مكوّنًا. +إذا كان الخادم المنزلي يتطلب مصادقة تفاعلية لرفع مفاتيح cross-signing، يحاول OpenClaw الرفع أولًا من دون مصادقة، ثم باستخدام `m.login.dummy`، ثم باستخدام `m.login.password` عندما تكون `channels.matrix.password` مهيأة. -استخدم `--force-reset-cross-signing` فقط عندما تريد عمدًا التخلص من هوية التوقيع المتقاطع الحالية وإنشاء هوية جديدة. +استخدم `--force-reset-cross-signing` فقط عندما تريد عمدًا تجاهل هوية cross-signing الحالية وإنشاء هوية جديدة. -إذا كنت تريد عمدًا التخلص من النسخة الاحتياطية الحالية لمفاتيح الغرف وبدء +إذا كنت تريد عمدًا تجاهل النسخة الاحتياطية الحالية لمفاتيح الغرف وبدء خط أساس جديد للنسخ الاحتياطي للرسائل المستقبلية، فاستخدم `openclaw matrix verify backup reset --yes`. -افعل ذلك فقط إذا كنت تقبل بأن السجل المشفر القديم غير القابل للاسترداد سيظل -غير متاح، وأن OpenClaw قد يعيد إنشاء التخزين السري إذا تعذر تحميل سر -النسخة الاحتياطية الحالية بأمان. +افعل ذلك فقط عندما تكون موافقًا على أن السجل المشفر القديم غير القابل للاسترداد سيبقى +غير متاح، وأن OpenClaw قد يعيد إنشاء التخزين السري إذا تعذر تحميل سر النسخ الاحتياطي الحالي +بأمان. ### خط أساس جديد للنسخ الاحتياطي -إذا كنت تريد إبقاء الرسائل المشفرة المستقبلية تعمل وتقبل فقدان السجل القديم غير القابل للاسترداد، فشغّل هذه الأوامر بالترتيب: +إذا كنت تريد الإبقاء على الرسائل المشفرة المستقبلية عاملة وتقبل فقدان السجل القديم غير القابل للاسترداد، فشغّل هذه الأوامر بالترتيب: ```bash openclaw matrix verify backup reset --yes @@ -610,50 +610,50 @@ openclaw matrix verify status ### سلوك بدء التشغيل -عندما يكون `encryption: true`، يعيّن Matrix القيمة الافتراضية لـ `startupVerification` إلى `"if-unverified"`. -عند بدء التشغيل، إذا ظل هذا الجهاز غير متحقق منه، فسيطلب Matrix تحققًا ذاتيًا في عميل Matrix آخر، -ويتخطى الطلبات المكررة عندما يكون أحدها معلقًا بالفعل، ويطبق مهلة محلية قبل إعادة المحاولة بعد إعادة التشغيل. -تعاد محاولة الطلبات الفاشلة أسرع من إنشاء الطلبات الناجحة افتراضيًا. -عيّن `startupVerification: "off"` لتعطيل طلبات بدء التشغيل التلقائية، أو اضبط `startupVerificationCooldownHours` +عندما تكون `encryption: true`، تكون القيمة الافتراضية لـ Matrix في `startupVerification` هي `"if-unverified"`. +عند بدء التشغيل، إذا كان هذا الجهاز ما يزال غير متحقق منه، فسيطلب Matrix التحقق الذاتي في عميل Matrix آخر، +وسيتخطى الطلبات المكررة عندما يكون أحدها قيد الانتظار بالفعل، ويطبق فترة تهدئة محلية قبل إعادة المحاولة بعد إعادة التشغيل. +تعاد محاولة الطلبات الفاشلة أسرع افتراضيًا من إنشاء الطلبات الناجحة. +اضبط `startupVerification: "off"` لتعطيل طلبات بدء التشغيل التلقائية، أو عدّل `startupVerificationCooldownHours` إذا كنت تريد نافذة إعادة محاولة أقصر أو أطول. -ينفذ بدء التشغيل أيضًا تمريرة تهيئة تشفير محافظة تلقائيًا. -وتحاول تلك التمريرة أولًا إعادة استخدام التخزين السري الحالي وهوية التوقيع المتقاطع الحالية، وتتجنب إعادة تعيين التوقيع المتقاطع إلا إذا شغّلت تدفق إصلاح تهيئة صريحًا. +ينفذ بدء التشغيل أيضًا تمريرة bootstrap مشفرة متحفظة تلقائيًا. +تحاول هذه التمريرة أولًا إعادة استخدام التخزين السري الحالي وهوية cross-signing الحالية، وتتجنب إعادة تعيين cross-signing ما لم تشغّل تدفق إصلاح bootstrap صريحًا. -إذا اكتشف بدء التشغيل حالة تهيئة معطلة وكان `channels.matrix.password` مكوّنًا، فيمكن لـ OpenClaw محاولة مسار إصلاح أكثر صرامة. -وإذا كان الجهاز الحالي موقّعًا من المالك بالفعل، يحافظ OpenClaw على تلك الهوية بدلًا من إعادة تعيينها تلقائيًا. +إذا اكتشف بدء التشغيل حالة bootstrap معطوبة وكانت `channels.matrix.password` مهيأة، يمكن لـ OpenClaw محاولة مسار إصلاح أكثر صرامة. +إذا كان الجهاز الحالي موقّعًا بالفعل من المالك، فسيحافظ OpenClaw على تلك الهوية بدلًا من إعادة تعيينها تلقائيًا. -راجع [ترحيل Matrix](/ar/install/migrating-matrix) للحصول على تدفق الترقية الكامل، والقيود، وأوامر الاسترداد، ورسائل الترحيل الشائعة. +راجع [Matrix migration](/ar/install/migrating-matrix) لمعرفة تدفق الترقية الكامل والقيود وأوامر الاسترداد ورسائل الترحيل الشائعة. ### إشعارات التحقق -ينشر Matrix إشعارات دورة حياة التحقق مباشرة في غرفة التحقق الصارمة للرسائل المباشرة كرسائل `m.notice`. -ويتضمن ذلك: +ينشر Matrix إشعارات دورة حياة التحقق مباشرةً داخل غرفة الرسائل الخاصة الصارمة الخاصة بالتحقق كرسائل `m.notice`. +ويشمل ذلك: - إشعارات طلب التحقق -- إشعارات جاهزية التحقق (مع إرشاد صريح "تحقق عبر الرموز التعبيرية") +- إشعارات جاهزية التحقق (مع إرشاد صريح "تحقق عبر emoji") - إشعارات بدء التحقق واكتماله -- تفاصيل SAS (الرموز التعبيرية والأرقام العشرية) عند توفرها +- تفاصيل SAS (emoji والأرقام العشرية) عند توفرها -يتم تتبع طلبات التحقق الواردة من عميل Matrix آخر وقبولها تلقائيًا بواسطة OpenClaw. -وبالنسبة إلى تدفقات التحقق الذاتي، يبدأ OpenClaw أيضًا تدفق SAS تلقائيًا عندما يصبح التحقق بالرموز التعبيرية متاحًا ويؤكد جانبه الخاص. -أما بالنسبة إلى طلبات التحقق الواردة من مستخدم/جهاز Matrix آخر، فيقبل OpenClaw الطلب تلقائيًا ثم ينتظر أن يتابع تدفق SAS بشكل طبيعي. -ولا يزال يتعين عليك مقارنة SAS الرمزية أو العشرية في عميل Matrix لديك وتأكيد "إنها متطابقة" هناك لإكمال التحقق. +تتم متابعة طلبات التحقق الواردة من عميل Matrix آخر وقبولها تلقائيًا بواسطة OpenClaw. +وفي تدفقات التحقق الذاتي، يبدأ OpenClaw أيضًا تدفق SAS تلقائيًا عندما يصبح التحقق عبر emoji متاحًا ويؤكد جانبه بنفسه. +أما طلبات التحقق من مستخدم/جهاز Matrix آخر، فيقبل OpenClaw الطلب تلقائيًا ثم ينتظر أن يستمر تدفق SAS بشكل طبيعي. +وما زلت بحاجة إلى مقارنة SAS المكوّن من emoji أو الأرقام العشرية في عميل Matrix لديك وتأكيد "They match" هناك لإكمال التحقق. -لا يقبل OpenClaw تلقائيًا التدفقات المكررة التي بدأها بنفسه بشكل أعمى. ويتخطى بدء التشغيل إنشاء طلب جديد عندما يكون طلب تحقق ذاتي معلقًا بالفعل. +لا يقبل OpenClaw التدفقات المكررة التي يبدأها بنفسه بشكل أعمى. ويتخطى بدء التشغيل إنشاء طلب جديد عندما يكون طلب التحقق الذاتي قيد الانتظار بالفعل. -لا يتم تمرير إشعارات بروتوكول/نظام التحقق إلى مسار دردشة الوكيل، لذلك لا تنتج `NO_REPLY`. +لا تتم إعادة توجيه إشعارات التحقق الخاصة بالبروتوكول/النظام إلى مسار دردشة الوكيل، لذلك لا تنتج `NO_REPLY`. ### نظافة الأجهزة -يمكن أن تتراكم أجهزة Matrix القديمة التي يديرها OpenClaw على الحساب وتجعل فهم الثقة في الغرف المشفرة أصعب. +يمكن أن تتراكم أجهزة Matrix القديمة التي يديرها OpenClaw في الحساب وتجعل الثقة في الغرف المشفرة أصعب في الفهم. اعرضها باستخدام: ```bash openclaw matrix devices list ``` -أزل الأجهزة القديمة التي يديرها OpenClaw باستخدام: +أزل أجهزة OpenClaw Matrix القديمة باستخدام: ```bash openclaw matrix devices prune-stale @@ -661,15 +661,15 @@ openclaw matrix devices prune-stale ### مخزن التشفير -يستخدم E2EE في Matrix مسار التشفير Rust الرسمي في `matrix-js-sdk` على Node، مع `fake-indexeddb` كطبقة محاكاة لـ IndexedDB. تُحفظ حالة التشفير في ملف لقطة (`crypto-idb-snapshot.json`) وتُستعاد عند بدء التشغيل. ويُعد ملف اللقطة حالة تشغيل حساسة مخزنة بأذونات ملفات مقيّدة. +يستخدم Matrix E2EE مسار التشفير Rust الرسمي في `matrix-js-sdk` على Node، مع `fake-indexeddb` كطبقة IndexedDB بديلة. تُحفَظ حالة التشفير في ملف snapshot (`crypto-idb-snapshot.json`) وتُستعاد عند بدء التشغيل. يُعد ملف snapshot حالة تشغيل حساسة ويتم تخزينه بأذونات ملفات مقيّدة. -تعيش حالة التشغيل المشفرة تحت جذور لكل حساب ولكل مستخدم ولكل تجزئة رمز في +توجد حالة التشغيل المشفرة تحت جذور لكل حساب ولكل مستخدم بحسب تجزئة الرمز المميز في `~/.openclaw/matrix/accounts//__//`. -ويحتوي ذلك الدليل على مخزن المزامنة (`bot-storage.json`)، ومخزن التشفير (`crypto/`)، -وملف مفتاح الاسترداد (`recovery-key.json`)، ولقطة IndexedDB (`crypto-idb-snapshot.json`)، -وروابط الخيوط (`thread-bindings.json`)، وحالة التحقق عند بدء التشغيل (`startup-verification.json`). -وعندما يتغير الرمز مع بقاء هوية الحساب نفسها، يعيد OpenClaw استخدام أفضل جذر موجود -لهذا الصفيف account/homeserver/user بحيث تظل حالة المزامنة السابقة وحالة التشفير وروابط الخيوط +ويحتوي هذا الدليل على مخزن المزامنة (`bot-storage.json`) ومخزن التشفير (`crypto/`)، +وملف مفتاح الاسترداد (`recovery-key.json`)، وsnapshot لـ IndexedDB (`crypto-idb-snapshot.json`)، +وربط سلاسل الرسائل (`thread-bindings.json`)، وحالة التحقق عند بدء التشغيل (`startup-verification.json`). +عندما يتغير الرمز المميز بينما تبقى هوية الحساب نفسها، يعيد OpenClaw استخدام أفضل جذر موجود +لهذا الثلاثي account/homeserver/user بحيث تظل حالة المزامنة السابقة، وحالة التشفير، وروابط سلاسل الرسائل، وحالة التحقق عند بدء التشغيل مرئية. ## إدارة الملف الشخصي @@ -681,49 +681,49 @@ openclaw matrix profile set --name "OpenClaw Assistant" openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png ``` -أضف `--account ` عندما تريد استهداف حساب مسمى بشكل صريح. +أضف `--account ` عندما تريد استهداف حساب Matrix مسمى بشكل صريح. -يقبل Matrix عناوين URL للصور الرمزية من نوع `mxc://` مباشرة. وعندما تمرر عنوان URL للصورة الرمزية من نوع `http://` أو `https://`، يقوم OpenClaw برفعه إلى Matrix أولًا ثم يخزن عنوان `mxc://` الناتج مرة أخرى في `channels.matrix.avatarUrl` (أو تجاوز الحساب المحدد). +يقبل Matrix عناوين URL للصورة الرمزية بصيغة `mxc://` مباشرةً. وعندما تمرر عنوان URL للصورة الرمزية بصيغة `http://` أو `https://`، يقوم OpenClaw أولًا برفعه إلى Matrix ثم يخزن عنوان `mxc://` الناتج مرة أخرى في `channels.matrix.avatarUrl` (أو تجاوز الحساب المحدد). -## الخيوط +## سلاسل الرسائل -يدعم Matrix خيوط Matrix الأصلية لكل من الردود التلقائية وعمليات الإرسال عبر أدوات الرسائل. +يدعم Matrix سلاسل Matrix الأصلية لكل من الردود التلقائية وعمليات الإرسال عبر أدوات الرسائل. -- يبقي `dm.sessionScope: "per-user"` (الافتراضي) توجيه الرسائل المباشرة في Matrix ضمن نطاق المرسل، بحيث يمكن لعدة غرف رسائل مباشرة مشاركة جلسة واحدة عندما تُحل إلى النظير نفسه. -- يعزل `dm.sessionScope: "per-room"` كل غرفة رسائل مباشرة في Matrix داخل مفتاح جلسة خاص بها مع الاستمرار في استخدام فحوصات مصادقة الرسائل المباشرة وقائمة السماح العادية. -- تظل روابط محادثات Matrix الصريحة ذات أولوية على `dm.sessionScope`، لذلك تحتفظ الغرف والخيوط المرتبطة بالجلسة الهدف التي اختيرت لها. -- يبقي `threadReplies: "off"` الردود على المستوى الأعلى ويبقي الرسائل الواردة ذات الخيوط على جلسة الرسالة الأصل. -- يرد `threadReplies: "inbound"` داخل خيط فقط عندما تكون الرسالة الواردة موجودة بالفعل في ذلك الخيط. -- يبقي `threadReplies: "always"` ردود الغرفة في خيط متجذر في الرسالة المحفزة ويوجه تلك المحادثة عبر الجلسة المطابقة ذات نطاق الخيط بدءًا من أول رسالة محفزة. -- يتجاوز `dm.threadReplies` الإعداد الأعلى مستوى للرسائل المباشرة فقط. على سبيل المثال، يمكنك إبقاء خيوط الغرف معزولة مع إبقاء الرسائل المباشرة مسطحة. -- تتضمن الرسائل الواردة ذات الخيوط رسالة جذر الخيط كسياق إضافي للوكيل. -- ترث عمليات الإرسال عبر أدوات الرسائل خيط Matrix الحالي تلقائيًا عندما يكون الهدف هو الغرفة نفسها أو الهدف نفسه لمستخدم الرسائل المباشرة، ما لم يتم توفير `threadId` صريح. -- لا يعمل إعادة استخدام الهدف نفسه لمستخدم الرسائل المباشرة ضمن الجلسة نفسها إلا عندما تثبت بيانات تعريف الجلسة الحالية النظير نفسه في الرسائل المباشرة على حساب Matrix نفسه؛ وإلا يعود OpenClaw إلى التوجيه العادي ضمن نطاق المستخدم. -- عندما يكتشف OpenClaw أن غرفة رسائل مباشرة في Matrix تتصادم مع غرفة رسائل مباشرة أخرى على جلسة الرسائل المباشرة المشتركة نفسها في Matrix، فإنه ينشر `m.notice` لمرة واحدة في تلك الغرفة مع مخرج `/focus` عندما تكون روابط الخيوط ممكّنة وتلميح `dm.sessionScope`. -- يتم دعم روابط الخيوط وقت التشغيل في Matrix. تعمل `/focus` و`/unfocus` و`/agents` و`/session idle` و`/session max-age` و`/acp spawn` المرتبط بالخيط في غرف Matrix والرسائل المباشرة. -- يقوم `/focus` على المستوى الأعلى في غرفة/رسائل مباشرة في Matrix بإنشاء خيط Matrix جديد وربطه بالجلسة الهدف عندما يكون `threadBindings.spawnSubagentSessions=true`. -- يؤدي تشغيل `/focus` أو `/acp spawn --thread here` داخل خيط Matrix موجود إلى ربط ذلك الخيط الحالي بدلًا من ذلك. +- يحتفظ `dm.sessionScope: "per-user"` (الافتراضي) بتوجيه Matrix DM على نطاق المرسل، بحيث يمكن لعدة غرف DM مشاركة جلسة واحدة عندما تُحل إلى النظير نفسه. +- يعزل `dm.sessionScope: "per-room"` كل غرفة Matrix DM داخل مفتاح جلسة خاص بها مع الاستمرار في استخدام مصادقة DM العادية وفحوصات قائمة السماح. +- تظل روابط محادثات Matrix الصريحة لها الأولوية على `dm.sessionScope`، لذلك تحتفظ الغرف وسلاسل الرسائل المرتبطة بالجلسة المستهدفة التي تم اختيارها. +- يجعل `threadReplies: "off"` الردود على المستوى الأعلى ويحافظ على الرسائل الواردة ضمن سلاسل الرسائل على جلسة الرسالة الأصلية. +- يرد `threadReplies: "inbound"` داخل سلسلة رسائل فقط عندما تكون الرسالة الواردة موجودة بالفعل في تلك السلسلة. +- يجعل `threadReplies: "always"` ردود الغرف ضمن سلسلة رسائل جذرها الرسالة المحفزة ويوجّه تلك المحادثة عبر الجلسة المطابقة ذات نطاق سلسلة الرسائل بدءًا من أول رسالة محفزة. +- يتجاوز `dm.threadReplies` الإعداد الأعلى مستوى للرسائل الخاصة فقط. على سبيل المثال، يمكنك إبقاء سلاسل الغرف معزولة مع إبقاء الرسائل الخاصة مسطحة. +- تتضمن الرسائل الواردة ضمن سلاسل الرسائل رسالة جذر السلسلة كسياق إضافي للوكيل. +- ترث عمليات الإرسال عبر أدوات الرسائل سلسلة Matrix الحالية تلقائيًا عندما يكون الهدف هو الغرفة نفسها، أو هدف مستخدم DM نفسه، ما لم يتم توفير `threadId` صريح. +- لا يعمل إعادة استخدام هدف مستخدم DM للجلسة نفسها إلا عندما تثبت بيانات تعريف الجلسة الحالية وجود النظير نفسه في DM وعلى حساب Matrix نفسه؛ وإلا يعود OpenClaw إلى التوجيه العادي على نطاق المستخدم. +- عندما يكتشف OpenClaw أن غرفة Matrix DM تتصادم مع غرفة DM أخرى على جلسة Matrix DM المشتركة نفسها، فإنه ينشر `m.notice` لمرة واحدة في تلك الغرفة مع مخرج `/focus` عند تمكين روابط سلاسل الرسائل وتلميح `dm.sessionScope`. +- يتم دعم روابط سلاسل الرسائل أثناء التشغيل في Matrix. تعمل أوامر `/focus` و`/unfocus` و`/agents` و`/session idle` و`/session max-age` و`/acp spawn` المرتبط بسلسلة رسائل في غرف Matrix والرسائل الخاصة. +- ينشئ `/focus` على مستوى غرفة/DM في Matrix سلسلة Matrix جديدة ويربطها بالجلسة المستهدفة عندما تكون `threadBindings.spawnSubagentSessions=true`. +- يؤدي تشغيل `/focus` أو `/acp spawn --thread here` داخل سلسلة Matrix موجودة إلى ربط تلك السلسلة الحالية بدلًا من ذلك. ## روابط محادثات ACP -يمكن تحويل غرف Matrix والرسائل المباشرة وخيوط Matrix الموجودة إلى مساحات عمل ACP دائمة دون تغيير واجهة الدردشة. +يمكن تحويل غرف Matrix والرسائل الخاصة وسلاسل Matrix الموجودة إلى مساحات عمل ACP دائمة دون تغيير سطح الدردشة. -تدفق المشغّل السريع: +تدفق سريع للمشغّل: -- شغّل `/acp spawn codex --bind here` داخل رسالة Matrix المباشرة أو الغرفة أو الخيط الموجود الذي تريد الاستمرار في استخدامه. -- في رسالة Matrix مباشرة أو غرفة على المستوى الأعلى، تبقى الرسالة المباشرة/الغرفة الحالية هي واجهة الدردشة، وتُوجَّه الرسائل المستقبلية إلى جلسة ACP التي تم إنشاؤها. -- داخل خيط Matrix موجود، يقوم `--bind here` بربط ذلك الخيط الحالي في مكانه. -- يقوم `/new` و`/reset` بإعادة تعيين جلسة ACP المرتبطة نفسها في مكانها. -- يقوم `/acp close` بإغلاق جلسة ACP وإزالة الربط. +- شغّل `/acp spawn codex --bind here` داخل رسالة Matrix الخاصة، أو الغرفة، أو سلسلة الرسائل الموجودة التي تريد الاستمرار في استخدامها. +- في رسالة Matrix خاصة أو غرفة من المستوى الأعلى، يبقى DM/الغرفة الحالية هي سطح الدردشة وتُوجَّه الرسائل المستقبلية إلى جلسة ACP التي تم إنشاؤها. +- داخل سلسلة Matrix موجودة، يربط `--bind here` تلك السلسلة الحالية في مكانها. +- يعيد `/new` و`/reset` تعيين جلسة ACP المرتبطة نفسها في مكانها. +- يغلق `/acp close` جلسة ACP ويزيل الرابط. ملاحظات: -- لا ينشئ `--bind here` خيط Matrix فرعيًا. -- لا يكون `threadBindings.spawnAcpSessions` مطلوبًا إلا مع `/acp spawn --thread auto|here`، حيث يحتاج OpenClaw إلى إنشاء خيط Matrix فرعي أو ربطه. +- لا ينشئ `--bind here` سلسلة Matrix فرعية. +- تكون `threadBindings.spawnAcpSessions` مطلوبة فقط مع `/acp spawn --thread auto|here`، حيث يحتاج OpenClaw إلى إنشاء سلسلة Matrix فرعية أو ربطها. -### تكوين ربط الخيوط +### تهيئة ربط سلاسل الرسائل -يرث Matrix القيم الافتراضية العامة من `session.threadBindings`، كما يدعم أيضًا تجاوزات لكل قناة: +يرث Matrix القيم الافتراضية العامة من `session.threadBindings`، ويدعم أيضًا تجاوزات لكل قناة: - `threadBindings.enabled` - `threadBindings.idleHours` @@ -731,35 +731,35 @@ openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -علامات إنشاء الخيوط المرتبطة في Matrix اختيارية: +إشارات الإنشاء المرتبط بسلسلة الرسائل في Matrix اختيارية: -- عيّن `threadBindings.spawnSubagentSessions: true` للسماح لـ `/focus` على المستوى الأعلى بإنشاء خيوط Matrix جديدة وربطها. -- عيّن `threadBindings.spawnAcpSessions: true` للسماح لـ `/acp spawn --thread auto|here` بربط جلسات ACP بخيوط Matrix. +- اضبط `threadBindings.spawnSubagentSessions: true` للسماح لـ `/focus` من المستوى الأعلى بإنشاء سلاسل Matrix جديدة وربطها. +- اضبط `threadBindings.spawnAcpSessions: true` للسماح لـ `/acp spawn --thread auto|here` بربط جلسات ACP بسلاسل Matrix. ## التفاعلات -يدعم Matrix إجراءات التفاعلات الصادرة، وإشعارات التفاعلات الواردة، وتفاعلات الإقرار الواردة. +يدعم Matrix إجراءات التفاعل الصادرة، وإشعارات التفاعل الواردة، وتفاعلات التأكيد الواردة. -- يتم التحكم في أدوات التفاعل الصادر بواسطة `channels["matrix"].actions.reactions`. +- يتم ضبط أدوات التفاعل الصادر بواسطة `channels["matrix"].actions.reactions`. - يضيف `react` تفاعلًا إلى حدث Matrix محدد. - يسرد `reactions` ملخص التفاعلات الحالي لحدث Matrix محدد. -- تؤدي `emoji=""` إلى إزالة تفاعلات حساب البوت نفسه على ذلك الحدث. -- تؤدي `remove: true` إلى إزالة تفاعل الرمز التعبيري المحدد فقط من حساب البوت. +- يؤدي `emoji=""` إلى إزالة تفاعلات حساب bot نفسه على ذلك الحدث. +- يؤدي `remove: true` إلى إزالة تفاعل emoji المحدد فقط من حساب bot. -يُحل نطاق تفاعلات الإقرار وفق ترتيب OpenClaw القياسي: +يستخدم نطاق تفاعلات التأكيد ترتيب الحل القياسي في OpenClaw: - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- الرجوع إلى الرمز التعبيري لهوية الوكيل +- الرجوع إلى emoji هوية الوكيل -يُحل نطاق تفاعل الإقرار بهذا الترتيب: +يُحل نطاق تفاعلات التأكيد بهذا الترتيب: - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` - `messages.ackReactionScope` -يُحل وضع إشعارات التفاعلات بهذا الترتيب: +يُحل وضع إشعارات التفاعل بهذا الترتيب: - `channels["matrix"].accounts..reactionNotifications` - `channels["matrix"].reactionNotifications` @@ -767,30 +767,30 @@ openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png السلوك: -- `reactionNotifications: "own"` يمرر أحداث `m.reaction` المضافة عندما تستهدف رسائل Matrix التي أنشأها البوت. -- `reactionNotifications: "off"` يعطل أحداث نظام التفاعلات. -- لا يتم توليف عمليات إزالة التفاعلات إلى أحداث نظام لأن Matrix يعرضها كعمليات حذف redactions، وليس كعمليات إزالة مستقلة لـ `m.reaction`. +- يقوم `reactionNotifications: "own"` بتمرير أحداث `m.reaction` المضافة عندما تستهدف رسائل Matrix صادرة عن bot. +- يقوم `reactionNotifications: "off"` بتعطيل أحداث نظام التفاعل. +- لا تتم محاكاة إزالة التفاعلات كأحداث نظام لأن Matrix يعرضها كعمليات redact، وليس كعمليات إزالة `m.reaction` مستقلة. ## سياق السجل -- يتحكم `channels.matrix.historyLimit` في عدد رسائل الغرفة الأخيرة التي تُضمَّن باعتبارها `InboundHistory` عندما تُحفّز رسالة غرفة Matrix الوكيل. ويرجع إلى `messages.groupChat.historyLimit`؛ وإذا لم يكن أيٌّ منهما معيّنًا، تكون القيمة الافتراضية الفعلية `0`. عيّن `0` للتعطيل. -- يقتصر سجل غرف Matrix على الغرفة فقط. وتستمر الرسائل المباشرة في استخدام سجل الجلسة العادي. -- سجل غرف Matrix معلق فقط: يخزن OpenClaw رسائل الغرفة التي لم تُحفّز ردًا بعد، ثم يلتقط تلك النافذة عندما تصل إشارة أو محفز آخر. -- لا تُضمَّن رسالة التحفيز الحالية في `InboundHistory`؛ بل تبقى في النص الرئيسي الوارد لذلك الدور. -- تعيد محاولات الحدث نفسه في Matrix استخدام لقطة السجل الأصلية بدلًا من الانجراف إلى رسائل أحدث في الغرفة. +- يتحكم `channels.matrix.historyLimit` في عدد رسائل الغرف الأخيرة التي يتم تضمينها كـ `InboundHistory` عندما تؤدي رسالة غرفة Matrix إلى تشغيل الوكيل. ويعود إلى `messages.groupChat.historyLimit`؛ وإذا لم يتم ضبط الاثنين، فالقيمة الافتراضية الفعلية هي `0`. اضبط `0` للتعطيل. +- يكون سجل غرف Matrix خاصًا بالغرفة فقط. وتستمر الرسائل الخاصة في استخدام سجل الجلسة العادي. +- يكون سجل غرف Matrix معلّقًا فقط: يخزّن OpenClaw رسائل الغرف التي لم تؤدِّ إلى رد بعد، ثم يلتقط snapshot لتلك النافذة عند وصول mention أو محفز آخر. +- لا يتم تضمين رسالة التحفيز الحالية في `InboundHistory`؛ بل تبقى في متن الرسالة الواردة الرئيسي لذلك الدور. +- تعيد إعادة محاولة الحدث نفسه في Matrix استخدام snapshot السجل الأصلي بدلًا من الانجراف إلى رسائل الغرفة الأحدث. -## رؤية السياق +## ظهور السياق -يدعم Matrix عنصر التحكم المشترك `contextVisibility` للسياق التكميلي للغرفة مثل نص الرد المجلوِب وجذور الخيوط والسجل المعلق. +يدعم Matrix عنصر التحكم المشترك `contextVisibility` للسياق الإضافي للغرفة، مثل نص الرد الذي تم جلبه، وجذور سلاسل الرسائل، والسجل المعلق. -- `contextVisibility: "all"` هو الإعداد الافتراضي. يُحتفظ بالسياق التكميلي كما تم استلامه. -- `contextVisibility: "allowlist"` يرشح السياق التكميلي إلى المرسلين المسموح بهم وفق فحوصات قائمة السماح النشطة للغرفة/المستخدم. -- `contextVisibility: "allowlist_quote"` يتصرف مثل `allowlist`، لكنه يحتفظ مع ذلك برد مقتبس صريح واحد. +- `contextVisibility: "all"` هو الافتراضي. يتم الاحتفاظ بالسياق الإضافي كما تم استلامه. +- يقوم `contextVisibility: "allowlist"` بتصفية السياق الإضافي إلى المرسلين المسموح بهم وفقًا لفحوصات قائمة السماح النشطة للغرفة/المستخدم. +- يعمل `contextVisibility: "allowlist_quote"` مثل `allowlist`، لكنه يحتفظ مع ذلك برد مقتبس صريح واحد. -يؤثر هذا الإعداد في رؤية السياق التكميلي، وليس في ما إذا كانت الرسالة الواردة نفسها تستطيع تحفيز رد. -ولا يزال تفويض التحفيز يأتي من إعدادات `groupPolicy` و`groups` و`groupAllowFrom` وسياسة الرسائل المباشرة. +يؤثر هذا الإعداد في ظهور السياق الإضافي، وليس في ما إذا كانت الرسالة الواردة نفسها يمكن أن تؤدي إلى رد. +ويظل تفويض التحفيز ناتجًا عن إعدادات `groupPolicy` و`groups` و`groupAllowFrom` وسياسات الرسائل الخاصة. -## سياسة الرسائل المباشرة والغرف +## سياسة الرسائل الخاصة والغرف ```json5 { @@ -813,84 +813,84 @@ openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png } ``` -راجع [Groups](/ar/channels/groups) لمعرفة سلوك تقييد الإشارات وقائمة السماح. +راجع [Groups](/ar/channels/groups) لمعرفة سلوك تقييد mentions وقائمة السماح. -مثال على الاقتران للرسائل المباشرة في Matrix: +مثال اقتران لرسائل Matrix الخاصة: ```bash openclaw pairing list matrix openclaw pairing approve matrix ``` -إذا استمر مستخدم Matrix غير معتمد في مراسلتك قبل الموافقة، يعيد OpenClaw استخدام رمز الاقتران المعلق نفسه، وقد يرسل رد تذكير مرة أخرى بعد فترة تهدئة قصيرة بدلًا من إنشاء رمز جديد. +إذا استمر مستخدم Matrix غير المعتمد في مراسلتك قبل الموافقة، يعيد OpenClaw استخدام رمز الاقتران المعلّق نفسه وقد يرسل رد تذكير مرة أخرى بعد فترة تهدئة قصيرة بدلًا من إنشاء رمز جديد. -راجع [Pairing](/ar/channels/pairing) لمعرفة تدفق اقتران الرسائل المباشرة المشترك وتخطيط التخزين. +راجع [Pairing](/ar/channels/pairing) لمعرفة تدفق اقتران الرسائل الخاصة المشترك وتخطيط التخزين. -## إصلاح الغرف المباشرة +## إصلاح الغرفة المباشرة -إذا خرجت حالة الرسائل المباشرة عن التزامن، فقد ينتهي الأمر بـ OpenClaw إلى وجود تعيينات `m.direct` قديمة تشير إلى غرف فردية قديمة بدلًا من الرسالة المباشرة الحية. افحص التعيين الحالي لنظير باستخدام: +إذا أصبحت حالة الرسائل المباشرة غير متزامنة، فقد ينتهي الأمر بـ OpenClaw إلى وجود تعيينات `m.direct` قديمة تشير إلى غرف فردية قديمة بدلًا من DM الحي. افحص التعيين الحالي لنظير باستخدام: ```bash openclaw matrix direct inspect --user-id @alice:example.org ``` -أصلحه باستخدام: +وأصلحه باستخدام: ```bash openclaw matrix direct repair --user-id @alice:example.org ``` -يقوم تدفق الإصلاح بما يلي: +تدفق الإصلاح: -- يفضل رسالة مباشرة صارمة 1:1 تكون مُعيَّنة بالفعل في `m.direct` -- يعود إلى أي رسالة مباشرة صارمة 1:1 منضم إليها حاليًا مع ذلك المستخدم -- ينشئ غرفة مباشرة جديدة ويعيد كتابة `m.direct` إذا لم تكن هناك رسالة مباشرة سليمة +- يفضّل DM صارمًا 1:1 تم تعيينه بالفعل في `m.direct` +- يعود إلى أي DM صارم 1:1 منضم إليه حاليًا مع ذلك المستخدم +- ينشئ غرفة مباشرة جديدة ويعيد كتابة `m.direct` إذا لم توجد DM سليمة -لا يحذف تدفق الإصلاح الغرف القديمة تلقائيًا. بل يختار فقط الرسالة المباشرة السليمة ويحدّث التعيين بحيث تستهدف عمليات الإرسال الجديدة في Matrix وإشعارات التحقق وغيرها من تدفقات الرسائل المباشرة الغرفة الصحيحة مرة أخرى. +لا يحذف تدفق الإصلاح الغرف القديمة تلقائيًا. بل يختار DM السليمة فقط ويحدّث التعيين بحيث تستهدف عمليات الإرسال الجديدة في Matrix، وإشعارات التحقق، وتدفقات الرسائل المباشرة الأخرى، الغرفة الصحيحة مرة أخرى. ## موافقات Exec -يمكن لـ Matrix أن يعمل كعميل موافقة أصلي لحساب Matrix. وتظل -عناصر التحكم الأصلية لتوجيه الرسائل المباشرة/القنوات موجودة ضمن تكوين موافقات exec: +يمكن أن يعمل Matrix كعميل موافقة أصلي لحساب Matrix. وتظل +عناصر توجيه DM/القناة الأصلية موجودة تحت تهيئة موافقات exec: - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers` (اختياري؛ ويرجع إلى `channels.matrix.dm.allowFrom`) +- `channels.matrix.execApprovals.approvers` (اختياري؛ يرجع إلى `channels.matrix.dm.allowFrom`) - `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`، الافتراضي: `dm`) - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -يجب أن يكون الموافقون معرّفات مستخدمي Matrix مثل `@owner:example.org`. يقوم Matrix بتمكين الموافقات الأصلية تلقائيًا عندما يكون `enabled` غير معيّن أو `"auto"` ويكون من الممكن حلّ معتمد واحد على الأقل. تستخدم موافقات Exec مجموعة الموافقين من `execApprovals.approvers` أولًا ويمكنها الرجوع إلى `channels.matrix.dm.allowFrom`. وتفوض موافقات الإضافة من خلال `channels.matrix.dm.allowFrom`. عيّن `enabled: false` لتعطيل Matrix كعميل موافقة أصلي بشكل صريح. بخلاف ذلك، تعود طلبات الموافقة إلى مسارات الموافقة الأخرى المكوّنة أو إلى سياسة الرجوع للموافقة. +يجب أن يكون الموافقون معرّفات مستخدمي Matrix مثل `@owner:example.org`. يقوم Matrix بتمكين الموافقات الأصلية تلقائيًا عندما تكون `enabled` غير مضبوطة أو `"auto"` ويمكن حل موافق واحد على الأقل. تستخدم موافقات Exec `execApprovals.approvers` أولًا ويمكنها الرجوع إلى `channels.matrix.dm.allowFrom`. وتفوض موافقات Plugin عبر `channels.matrix.dm.allowFrom`. اضبط `enabled: false` لتعطيل Matrix كعميل موافقة أصلي صراحةً. وإلا ستعود طلبات الموافقة إلى مسارات موافقة مهيأة أخرى أو إلى سياسة الرجوع الخاصة بالموافقة. -يدعم التوجيه الأصلي في Matrix كلا نوعي الموافقات: +يدعم التوجيه الأصلي في Matrix نوعَي الموافقة: -- يتحكم `channels.matrix.execApprovals.*` في وضع التوزيع الأصلي للرسائل المباشرة/القنوات لمطالبات موافقة Matrix. -- تستخدم موافقات Exec مجموعة الموافقين التنفيذيين من `execApprovals.approvers` أو `channels.matrix.dm.allowFrom`. -- تستخدم موافقات الإضافات قائمة السماح للرسائل المباشرة في Matrix من `channels.matrix.dm.allowFrom`. -- تنطبق اختصارات التفاعلات في Matrix وتحديثات الرسائل على موافقات exec والإضافات معًا. +- تتحكم `channels.matrix.execApprovals.*` في وضع التوزيع الأصلي للرسائل الخاصة/القنوات لمطالبات الموافقة في Matrix. +- تستخدم موافقات Exec مجموعة الموافقين الخاصة بـ exec من `execApprovals.approvers` أو `channels.matrix.dm.allowFrom`. +- تستخدم موافقات Plugin قائمة السماح للرسائل الخاصة في Matrix من `channels.matrix.dm.allowFrom`. +- تنطبق اختصارات التفاعل في Matrix وتحديثات الرسائل على كل من موافقات exec وPlugin. قواعد التسليم: -- `target: "dm"` يرسل مطالبات الموافقة إلى الرسائل المباشرة للموافقين -- `target: "channel"` يرسل المطالبة مرة أخرى إلى غرفة Matrix أو الرسالة المباشرة الأصلية -- `target: "both"` يرسل إلى الرسائل المباشرة للموافقين وإلى غرفة Matrix أو الرسالة المباشرة الأصلية +- يرسل `target: "dm"` مطالبات الموافقة إلى الرسائل الخاصة للموافقين +- يرسل `target: "channel"` المطالبة مرة أخرى إلى غرفة Matrix أو الرسالة الخاصة الأصلية +- يرسل `target: "both"` إلى الرسائل الخاصة للموافقين وإلى غرفة Matrix أو الرسالة الخاصة الأصلية -تزرع مطالبات الموافقة في Matrix اختصارات التفاعلات على رسالة الموافقة الأساسية: +تُنشئ مطالبات الموافقة في Matrix اختصارات تفاعل على رسالة الموافقة الأساسية: -- `✅` = السماح مرة واحدة -- `❌` = الرفض -- `♾️` = السماح دائمًا عندما يكون هذا القرار مسموحًا به وفق سياسة exec الفعالة +- `✅` = سماح مرة واحدة +- `❌` = رفض +- `♾️` = سماح دائم عندما يكون هذا القرار مسموحًا به وفق سياسة exec الفعلية يمكن للموافقين التفاعل على تلك الرسالة أو استخدام أوامر الشرطة المائلة البديلة: `/approve allow-once` أو `/approve allow-always` أو `/approve deny`. -يمكن فقط للموافقين الذين تم حلهم الموافقة أو الرفض. وبالنسبة إلى موافقات exec، يتضمن التسليم عبر القناة نص الأمر، لذا لا تمكّن `channel` أو `both` إلا في الغرف الموثوقة. +يمكن فقط للموافقين الذين تم حلهم الموافقة أو الرفض. بالنسبة إلى موافقات exec، يتضمن التسليم عبر القناة نص الأمر، لذا لا تمكّن `channel` أو `both` إلا في الغرف الموثوقة. -التجاوز لكل حساب: +تجاوز لكل حساب: - `channels.matrix.accounts..execApprovals` الوثائق ذات الصلة: [Exec approvals](/ar/tools/exec-approvals) -## الحسابات المتعددة +## حسابات متعددة ```json5 { @@ -920,23 +920,24 @@ openclaw matrix direct repair --user-id @alice:example.org } ``` -تعمل قيم `channels.matrix` في المستوى الأعلى كقيم افتراضية للحسابات المسماة ما لم يتجاوزها أحد الحسابات. -يمكنك تقييد إدخالات الغرف الموروثة إلى حساب Matrix واحد باستخدام `groups..account`. -وتبقى الإدخالات التي لا تحتوي على `account` مشتركة بين جميع حسابات Matrix، كما تظل الإدخالات التي تحتوي على `account: "default"` تعمل عندما يكون الحساب الافتراضي مكوّنًا مباشرة على المستوى الأعلى في `channels.matrix.*`. -ولا تُنشئ القيم الافتراضية المشتركة الجزئية للمصادقة حسابًا افتراضيًا ضمنيًا منفصلًا بمفردها. لا يقوم OpenClaw بإنشاء حساب `default` على المستوى الأعلى إلا عندما يمتلك ذلك الافتراضي مصادقة حديثة (`homeserver` مع `accessToken`، أو `homeserver` مع `userId` و`password`)؛ ويمكن للحسابات المسماة أن تظل قابلة للاكتشاف من `homeserver` مع `userId` عندما تلبّي بيانات الاعتماد المؤقتة المصادقة لاحقًا. -إذا كان لدى Matrix بالفعل حساب مسمى واحد بالضبط، أو كان `defaultAccount` يشير إلى مفتاح حساب مسمى موجود، فإن ترقية الإصلاح/الإعداد من حساب واحد إلى عدة حسابات تحافظ على ذلك الحساب بدلًا من إنشاء إدخال `accounts.default` جديد. لا تنتقل إلى ذلك الحساب المُرقّى إلا مفاتيح المصادقة/التهيئة الخاصة بـ Matrix؛ أما مفاتيح سياسة التسليم المشتركة فتبقى في المستوى الأعلى. -عيّن `defaultAccount` عندما تريد أن يفضّل OpenClaw حساب Matrix مسمى واحدًا للتوجيه الضمني والفحص وعمليات CLI. -إذا قمت بتكوين عدة حسابات مسماة، فعيّن `defaultAccount` أو مرر `--account ` لأوامر CLI التي تعتمد على اختيار حساب ضمني. -مرر `--account ` إلى `openclaw matrix verify ...` و`openclaw matrix devices ...` عندما تريد تجاوز ذلك الاختيار الضمني لأمر واحد. +تعمل القيم في `channels.matrix` على المستوى الأعلى كقيم افتراضية للحسابات المسماة ما لم يقم حساب ما بتجاوزها. +يمكنك تقييد إدخالات الغرف الموروثة بحساب Matrix واحد باستخدام `groups..account`. +تظل الإدخالات التي لا تحتوي على `account` مشتركة بين جميع حسابات Matrix، كما أن الإدخالات التي تحتوي على `account: "default"` تستمر في العمل عندما يكون الحساب الافتراضي مهيأ مباشرةً على `channels.matrix.*` في المستوى الأعلى. +لا تؤدي القيم الافتراضية الجزئية المشتركة للمصادقة إلى إنشاء حساب افتراضي ضمني منفصل بمفردها. لا ينشئ OpenClaw حساب `default` في المستوى الأعلى إلا عندما تكون لدى هذا الحساب الافتراضي مصادقة حديثة (`homeserver` مع `accessToken`، أو `homeserver` مع `userId` و`password`)؛ ويمكن أن تظل الحسابات المسماة قابلة للاكتشاف من خلال `homeserver` مع `userId` عندما تلبّي بيانات الاعتماد المخزنة مؤقتًا المصادقة لاحقًا. +إذا كان لدى Matrix بالفعل حساب مسمى واحد بالضبط، أو كان `defaultAccount` يشير إلى مفتاح حساب مسمى موجود، فإن ترقية الإصلاح/الإعداد من حساب واحد إلى حسابات متعددة تحافظ على ذلك الحساب بدلًا من إنشاء إدخال `accounts.default` جديد. يتم نقل مفاتيح مصادقة/bootstrap الخاصة بـ Matrix فقط إلى ذلك الحساب المُرقّى؛ وتبقى مفاتيح سياسة التسليم المشتركة في المستوى الأعلى. +اضبط `defaultAccount` عندما تريد أن يفضّل OpenClaw حساب Matrix مسمى واحدًا للتوجيه الضمني، والفحص، وعمليات CLI. +إذا كانت هناك عدة حسابات Matrix مهيأة وكان أحد معرّفات الحسابات هو `default`، فإن OpenClaw يستخدم ذلك الحساب ضمنيًا حتى إذا لم يكن `defaultAccount` مضبوطًا. +إذا قمت بتهيئة عدة حسابات مسماة، فاضبط `defaultAccount` أو مرّر `--account ` لأوامر CLI التي تعتمد على اختيار الحساب الضمني. +مرّر `--account ` إلى `openclaw matrix verify ...` و`openclaw matrix devices ...` عندما تريد تجاوز هذا الاختيار الضمني لأمر واحد. -راجع [مرجع التكوين](/ar/gateway/configuration-reference#multi-account-all-channels) لمعرفة نمط الحسابات المتعددة المشترك. +راجع [Configuration reference](/ar/gateway/configuration-reference#multi-account-all-channels) لمعرفة النمط المشترك للحسابات المتعددة. -## الخوادم المنزلية الخاصة/الشبكات المحلية +## الخوادم المنزلية الخاصة/ضمن الشبكة المحلية -بشكل افتراضي، يحظر OpenClaw خوادم Matrix المنزلية الخاصة/الداخلية للحماية من SSRF ما لم +بشكل افتراضي، يمنع OpenClaw خوادم Matrix المنزلية الخاصة/الداخلية للحماية من SSRF ما لم تفعّل ذلك صراحةً لكل حساب. -إذا كان الخادم المنزلي لديك يعمل على localhost أو عنوان IP لشبكة LAN/Tailscale أو اسم مضيف داخلي، فقم بتمكين +إذا كان الخادم المنزلي يعمل على localhost، أو عنوان IP ضمن LAN/Tailscale، أو اسم مضيف داخلي، فقم بتمكين `network.dangerouslyAllowPrivateNetwork` لذلك الحساب في Matrix: ```json5 @@ -953,7 +954,7 @@ openclaw matrix direct repair --user-id @alice:example.org } ``` -مثال على إعداد CLI: +مثال على الإعداد عبر CLI: ```bash openclaw matrix account add \ @@ -963,12 +964,12 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -يسمح هذا التفعيل الاختياري فقط بالأهداف الخاصة/الداخلية الموثوقة. أما الخوادم المنزلية العامة ذات النص الصريح مثل -`http://matrix.example.org:8008` فتظل محظورة. ويفضل استخدام `https://` كلما أمكن. +يسمح هذا التفعيل فقط بالأهداف الخاصة/الداخلية الموثوقة. أما الخوادم المنزلية العامة غير المشفرة مثل +`http://matrix.example.org:8008` فتظل محظورة. ويُفضَّل استخدام `https://` كلما أمكن. -## تمرير حركة Matrix عبر وكيل +## تمرير حركة Matrix عبر proxy -إذا كان نشر Matrix لديك يحتاج إلى وكيل HTTP(S) صادر صريح، فعيّن `channels.matrix.proxy`: +إذا كان نشر Matrix لديك يحتاج إلى HTTP(S) proxy صريح للصادر، فاضبط `channels.matrix.proxy`: ```json5 { @@ -982,12 +983,12 @@ openclaw matrix account add \ } ``` -يمكن للحسابات المسماة تجاوز القيمة الافتراضية على المستوى الأعلى باستخدام `channels.matrix.accounts..proxy`. -ويستخدم OpenClaw إعداد الوكيل نفسه لكل من حركة Matrix وقت التشغيل وفحوصات حالة الحساب. +يمكن للحسابات المسماة تجاوز القيمة الافتراضية في المستوى الأعلى باستخدام `channels.matrix.accounts..proxy`. +ويستخدم OpenClaw إعداد proxy نفسه لكل من حركة Matrix أثناء التشغيل وعمليات فحص حالة الحساب. -## دقة الأهداف +## حل الأهداف -يقبل Matrix صيغ الأهداف التالية أينما طلب منك OpenClaw هدف غرفة أو مستخدم: +يقبل Matrix صيغ الأهداف التالية في أي موضع يطلب منك فيه OpenClaw هدف غرفة أو مستخدم: - المستخدمون: `@user:server` أو `user:@user:server` أو `matrix:user:@user:server` - الغرف: `!room:server` أو `room:!room:server` أو `matrix:room:!room:server` @@ -995,73 +996,73 @@ openclaw matrix account add \ يستخدم البحث الحي في الدليل حساب Matrix المسجل دخوله: -- تستعلم عمليات البحث عن المستخدمين عن دليل مستخدمي Matrix على ذلك الخادم المنزلي. -- تقبل عمليات البحث عن الغرف معرّفات الغرف والأسماء المستعارة الصريحة مباشرة، ثم تعود إلى البحث في أسماء الغرف المنضم إليها لذلك الحساب. -- يُعد البحث في أسماء الغرف المنضم إليها أفضل جهد. إذا تعذر حل اسم غرفة إلى معرّف أو اسم مستعار، فسيتم تجاهله بواسطة دقة قائمة السماح وقت التشغيل. +- تستعلم عمليات بحث المستخدمين من دليل مستخدمي Matrix على ذلك الخادم المنزلي. +- تقبل عمليات بحث الغرف معرّفات الغرف الصريحة والأسماء المستعارة مباشرةً، ثم تعود إلى البحث في أسماء الغرف المنضم إليها لذلك الحساب. +- البحث في أسماء الغرف المنضم إليها هو جهد أفضل. إذا تعذر حل اسم غرفة إلى معرّف أو اسم مستعار، فسيتم تجاهله أثناء حل قائمة السماح وقت التشغيل. -## مرجع التكوين +## مرجع التهيئة - `enabled`: تمكين القناة أو تعطيلها. - `name`: تسمية اختيارية للحساب. -- `defaultAccount`: معرّف الحساب المفضل عندما تكون عدة حسابات Matrix مكوّنة. +- `defaultAccount`: معرّف الحساب المفضّل عند تهيئة عدة حسابات Matrix. - `homeserver`: عنوان URL للخادم المنزلي، مثل `https://matrix.example.org`. -- `network.dangerouslyAllowPrivateNetwork`: السماح لهذا الحساب في Matrix بالاتصال بخوادم منزلية خاصة/داخلية. فعّل هذا عندما يُحل الخادم المنزلي إلى `localhost` أو عنوان IP لشبكة LAN/Tailscale أو مضيف داخلي مثل `matrix-synapse`. -- `proxy`: عنوان URL اختياري لوكيل HTTP(S) لحركة Matrix. يمكن للحسابات المسماة تجاوز القيمة الافتراضية على المستوى الأعلى باستخدام `proxy` خاص بها. +- `network.dangerouslyAllowPrivateNetwork`: السماح لهذا الحساب في Matrix بالاتصال بخوادم منزلية خاصة/داخلية. فعّل هذا عندما يُحل الخادم المنزلي إلى `localhost` أو عنوان IP ضمن LAN/Tailscale أو مضيف داخلي مثل `matrix-synapse`. +- `proxy`: عنوان URL اختياري لـ HTTP(S) proxy لحركة Matrix. ويمكن للحسابات المسماة تجاوز القيمة الافتراضية في المستوى الأعلى باستخدام `proxy` الخاصة بها. - `userId`: معرّف مستخدم Matrix الكامل، مثل `@bot:example.org`. -- `accessToken`: رمز وصول للمصادقة القائمة على الرمز. تُدعَم القيم النصية الصريحة وقيم SecretRef لكل من `channels.matrix.accessToken` و`channels.matrix.accounts..accessToken` عبر موفري env/file/exec. راجع [Secrets Management](/ar/gateway/secrets). -- `password`: كلمة مرور لتسجيل الدخول القائم على كلمة المرور. تُدعَم القيم النصية الصريحة وقيم SecretRef. +- `accessToken`: رمز وصول للمصادقة المعتمدة على الرمز. تُدعم القيم النصية الصريحة وقيم SecretRef في `channels.matrix.accessToken` و`channels.matrix.accounts..accessToken` عبر مزودي env/file/exec. راجع [Secrets Management](/ar/gateway/secrets). +- `password`: كلمة المرور لتسجيل الدخول المعتمد على كلمة المرور. تُدعم القيم النصية الصريحة وقيم SecretRef. - `deviceId`: معرّف جهاز Matrix صريح. - `deviceName`: اسم عرض الجهاز لتسجيل الدخول بكلمة المرور. -- `avatarUrl`: عنوان URL للصورة الرمزية الذاتية المخزّن لمزامنة الملف الشخصي وتحديثات `profile set`. +- `avatarUrl`: عنوان URL للصورة الرمزية الذاتية المخزنة لمزامنة الملف الشخصي وتحديثات `profile set`. - `initialSyncLimit`: الحد الأقصى لعدد الأحداث التي يتم جلبها أثناء مزامنة بدء التشغيل. - `encryption`: تمكين E2EE. -- `allowlistOnly`: عندما تكون القيمة `true`، تتم ترقية سياسة الغرف `open` إلى `allowlist`، وتُفرض جميع سياسات الرسائل المباشرة النشطة باستثناء `disabled` (بما في ذلك `pairing` و`open`) إلى `allowlist`. ولا يؤثر ذلك في سياسات `disabled`. -- `allowBots`: السماح بالرسائل من حسابات Matrix أخرى مكوّنة لـ OpenClaw (`true` أو `"mentions"`). -- `groupPolicy`: ‏`open` أو `allowlist` أو `disabled`. -- `contextVisibility`: وضع رؤية سياق الغرفة التكميلي (`all` أو `allowlist` أو `allowlist_quote`). -- `groupAllowFrom`: قائمة سماح لمعرّفات المستخدمين لحركة الغرف. ينبغي أن تكون الإدخالات معرّفات مستخدمي Matrix كاملة؛ وتُتجاهل الأسماء غير المحلولة وقت التشغيل. -- `historyLimit`: الحد الأقصى لرسائل الغرفة التي تُضمَّن كسياق سجل للمجموعات. ويرجع إلى `messages.groupChat.historyLimit`؛ وإذا لم يكن أيٌّ منهما معيّنًا، تكون القيمة الافتراضية الفعلية `0`. عيّن `0` للتعطيل. -- `replyToMode`: ‏`off` أو `first` أو `all` أو `batched`. -- `markdown`: تكوين اختياري لتصيير Markdown في نص Matrix الصادر. -- `streaming`: ‏`off` (الافتراضي) أو `"partial"` أو `"quiet"` أو `true` أو `false`. يقوم `"partial"` و`true` بتمكين تحديثات المسودة المعتمدة على المعاينة أولًا باستخدام رسائل Matrix النصية العادية. ويستخدم `"quiet"` إشعارات معاينة غير مشعرة لإعدادات قواعد الدفع المستضافة ذاتيًا. ويعادل `false` القيمة `"off"`. -- `blockStreaming`: تؤدي `true` إلى تمكين رسائل تقدم منفصلة لكتل المساعد المكتملة أثناء نشاط بث معاينة المسودة. -- `threadReplies`: ‏`off` أو `inbound` أو `always`. -- `threadBindings`: تجاوزات لكل قناة لتوجيه الجلسات المرتبط بالخيوط ودورة حياتها. +- `allowlistOnly`: عندما تكون قيمته `true`، يقوم بترقية سياسة الغرف `open` إلى `allowlist`، ويفرض جميع سياسات الرسائل الخاصة النشطة باستثناء `disabled` (بما في ذلك `pairing` و`open`) إلى `allowlist`. ولا يؤثر في سياسات `disabled`. +- `allowBots`: السماح بالرسائل من حسابات Matrix OpenClaw الأخرى المهيأة (`true` أو `"mentions"`). +- `groupPolicy`: `open` أو `allowlist` أو `disabled`. +- `contextVisibility`: وضع ظهور سياق الغرفة الإضافي (`all` أو `allowlist` أو `allowlist_quote`). +- `groupAllowFrom`: قائمة سماح لمعرّفات المستخدمين لحركة الغرف. يجب أن تكون الإدخالات معرّفات مستخدمي Matrix كاملة؛ ويتم تجاهل الأسماء غير المحلولة وقت التشغيل. +- `historyLimit`: الحد الأقصى لرسائل الغرف التي تُضمَّن كسياق سجل للمجموعة. ويعود إلى `messages.groupChat.historyLimit`؛ وإذا لم يتم ضبط الاثنين، فالقيمة الافتراضية الفعلية هي `0`. اضبط `0` للتعطيل. +- `replyToMode`: `off` أو `first` أو `all` أو `batched`. +- `markdown`: تهيئة اختيارية لتصيير Markdown للنصوص الصادرة في Matrix. +- `streaming`: `off` (الافتراضي)، أو `"partial"`، أو `"quiet"`، أو `true`، أو `false`. تؤدي `"partial"` و`true` إلى تمكين تحديثات المسودات بأسلوب المعاينة أولًا باستخدام رسائل Matrix النصية العادية. وتستخدم `"quiet"` إشعارات معاينة غير مُرسِلة للتنبيه لإعدادات push-rule المستضافة ذاتيًا. ويكافئ `false` القيمة `"off"`. +- `blockStreaming`: تؤدي القيمة `true` إلى تمكين رسائل تقدم منفصلة لكتل المساعد المكتملة أثناء نشاط بث معاينة المسودة. +- `threadReplies`: `off` أو `inbound` أو `always`. +- `threadBindings`: تجاوزات لكل قناة لتوجيه الجلسات المرتبطة بسلاسل الرسائل ودورة حياتها. - `startupVerification`: وضع طلب التحقق الذاتي التلقائي عند بدء التشغيل (`if-unverified` أو `off`). -- `startupVerificationCooldownHours`: فترة التهدئة قبل إعادة محاولة طلبات التحقق التلقائية عند بدء التشغيل. -- `textChunkLimit`: حجم تجزئة الرسالة الصادرة بالأحرف (يُطبّق عندما يكون `chunkMode` هو `length`). -- `chunkMode`: يقوم `length` بتقسيم الرسائل حسب عدد الأحرف؛ ويقوم `newline` بالتقسيم عند حدود الأسطر. +- `startupVerificationCooldownHours`: فترة التهدئة قبل إعادة محاولة طلبات التحقق التلقائي عند بدء التشغيل. +- `textChunkLimit`: حجم تجزئة الرسائل الصادرة بعدد الأحرف (يُطبّق عندما تكون `chunkMode` هي `length`). +- `chunkMode`: تقوم `length` بتقسيم الرسائل حسب عدد الأحرف؛ وتقوم `newline` بالتقسيم عند حدود الأسطر. - `responsePrefix`: سلسلة اختيارية تُسبق بها جميع الردود الصادرة لهذه القناة. -- `ackReaction`: تجاوز اختياري لتفاعل الإقرار لهذه القناة/الحساب. -- `ackReactionScope`: تجاوز اختياري لنطاق تفاعل الإقرار (`group-mentions` أو `group-all` أو `direct` أو `all` أو `none` أو `off`). -- `reactionNotifications`: وضع إشعارات التفاعلات الواردة (`own` أو `off`). -- `mediaMaxMb`: حد حجم الوسائط بالميجابايت للإرسال الصادر ومعالجة الوسائط الواردة. -- `autoJoin`: سياسة الانضمام التلقائي للدعوات (`always` أو `allowlist` أو `off`). الافتراضي: `off`. تنطبق على جميع دعوات Matrix، بما في ذلك الدعوات على نمط الرسائل المباشرة. -- `autoJoinAllowlist`: الغرف/الأسماء المستعارة المسموح بها عندما يكون `autoJoin` هو `allowlist`. تُحل إدخالات الأسماء المستعارة إلى معرّفات غرف أثناء معالجة الدعوة؛ ولا يثق OpenClaw بحالة الاسم المستعار التي تدّعيها الغرفة المدعو إليها. -- `dm`: كتلة سياسة الرسائل المباشرة (`enabled` و`policy` و`allowFrom` و`sessionScope` و`threadReplies`). -- `dm.policy`: يتحكم في الوصول إلى الرسائل المباشرة بعد انضمام OpenClaw إلى الغرفة وتصنيفها كرسالة مباشرة. ولا يغيّر ما إذا كان سيتم الانضمام تلقائيًا إلى الدعوة. -- `dm.allowFrom`: ينبغي أن تكون الإدخالات معرّفات مستخدمي Matrix كاملة ما لم تكن قد قمت بالفعل بحلها عبر البحث الحي في الدليل. -- `dm.sessionScope`: ‏`per-user` (الافتراضي) أو `per-room`. استخدم `per-room` عندما تريد أن تحتفظ كل غرفة رسائل مباشرة في Matrix بسياق منفصل حتى إذا كان النظير نفسه. -- `dm.threadReplies`: تجاوز سياسة الخيوط للرسائل المباشرة فقط (`off` أو `inbound` أو `always`). ويتجاوز الإعداد الأعلى مستوى `threadReplies` لكل من موضع الرد وعزل الجلسة في الرسائل المباشرة. -- `execApprovals`: تسليم موافقات exec الأصلي في Matrix (`enabled` و`approvers` و`target` و`agentFilter` و`sessionFilter`). -- `execApprovals.approvers`: معرّفات مستخدمي Matrix المسموح لهم بالموافقة على طلبات exec. اختياري عندما يكون `dm.allowFrom` يحدد الموافقين بالفعل. -- `execApprovals.target`: ‏`dm | channel | both` (الافتراضي: `dm`). -- `accounts`: تجاوزات مسماة لكل حساب. تعمل قيم `channels.matrix` في المستوى الأعلى كقيم افتراضية لهذه الإدخالات. -- `groups`: خريطة سياسات لكل غرفة. يفضل استخدام معرّفات الغرف أو الأسماء المستعارة؛ وتُتجاهل أسماء الغرف غير المحلولة وقت التشغيل. وتستخدم هوية الجلسة/المجموعة معرّف الغرفة الثابت بعد الحل. -- `groups..account`: قصر إدخال غرفة موروث واحد على حساب Matrix محدد في إعدادات الحسابات المتعددة. -- `groups..allowBots`: تجاوز على مستوى الغرفة للمرسلين من البوتات المكوّنة (`true` أو `"mentions"`). +- `ackReaction`: تجاوز اختياري لتفاعل التأكيد لهذه القناة/الحساب. +- `ackReactionScope`: تجاوز اختياري لنطاق تفاعل التأكيد (`group-mentions` أو `group-all` أو `direct` أو `all` أو `none` أو `off`). +- `reactionNotifications`: وضع إشعارات التفاعل الواردة (`own` أو `off`). +- `mediaMaxMb`: الحد الأقصى لحجم الوسائط بالميغابايت للإرسال الصادر ومعالجة الوسائط الواردة. +- `autoJoin`: سياسة الانضمام التلقائي للدعوات (`always` أو `allowlist` أو `off`). الافتراضي: `off`. تنطبق على جميع دعوات Matrix، بما في ذلك دعوات نمط الرسائل الخاصة. +- `autoJoinAllowlist`: الغرف/الأسماء المستعارة المسموح بها عندما تكون `autoJoin` هي `allowlist`. يتم حل إدخالات الأسماء المستعارة إلى معرّفات غرف أثناء معالجة الدعوات؛ ولا يثق OpenClaw في حالة الاسم المستعار التي تدّعيها الغرفة المدعو إليها. +- `dm`: كتلة سياسة الرسائل الخاصة (`enabled` أو `policy` أو `allowFrom` أو `sessionScope` أو `threadReplies`). +- `dm.policy`: يتحكم في وصول الرسائل الخاصة بعد أن ينضم OpenClaw إلى الغرفة ويصنّفها على أنها DM. ولا يغيّر ما إذا كانت الدعوة تُضم تلقائيًا. +- `dm.allowFrom`: يجب أن تكون الإدخالات معرّفات مستخدمي Matrix كاملة ما لم تكن قد قمت بالفعل بحلّها عبر البحث الحي في الدليل. +- `dm.sessionScope`: `per-user` (الافتراضي) أو `per-room`. استخدم `per-room` عندما تريد أن تحتفظ كل غرفة Matrix DM بسياق منفصل حتى لو كان النظير هو نفسه. +- `dm.threadReplies`: تجاوز لسياسة سلاسل الرسائل خاص بالرسائل الخاصة (`off` أو `inbound` أو `always`). وهو يتجاوز إعداد `threadReplies` في المستوى الأعلى لكل من موضع الرد وعزل الجلسة في الرسائل الخاصة. +- `execApprovals`: تسليم موافقات exec الأصلي في Matrix (`enabled` أو `approvers` أو `target` أو `agentFilter` أو `sessionFilter`). +- `execApprovals.approvers`: معرّفات مستخدمي Matrix المسموح لهم بالموافقة على طلبات exec. وهو اختياري عندما تحدد `dm.allowFrom` الموافقين بالفعل. +- `execApprovals.target`: `dm | channel | both` (الافتراضي: `dm`). +- `accounts`: تجاوزات مسماة لكل حساب. وتعمل قيم `channels.matrix` في المستوى الأعلى كقيم افتراضية لهذه الإدخالات. +- `groups`: خريطة سياسات لكل غرفة. يُفضَّل استخدام معرّفات الغرف أو الأسماء المستعارة؛ ويتم تجاهل أسماء الغرف غير المحلولة وقت التشغيل. وتستخدم هوية الجلسة/المجموعة معرّف الغرفة الثابت بعد الحل. +- `groups..account`: تقييد إدخال غرفة موروث واحد بحساب Matrix محدد في إعدادات الحسابات المتعددة. +- `groups..allowBots`: تجاوز على مستوى الغرفة للمرسلين من bots المهيأة (`true` أو `"mentions"`). - `groups..users`: قائمة سماح للمرسلين لكل غرفة. -- `groups..tools`: تجاوزات السماح/المنع للأدوات لكل غرفة. -- `groups..autoReply`: تجاوز على مستوى الغرفة لتقييد الإشارات. تؤدي `true` إلى تعطيل متطلبات الإشارة لتلك الغرفة؛ بينما تعيد `false` فرضها. +- `groups..tools`: تجاوزات سماح/منع للأدوات لكل غرفة. +- `groups..autoReply`: تجاوز على مستوى الغرفة لتقييد mentions. تؤدي `true` إلى تعطيل متطلبات mention لتلك الغرفة؛ وتؤدي `false` إلى فرضها مجددًا. - `groups..skills`: مرشح Skills اختياري على مستوى الغرفة. -- `groups..systemPrompt`: مقتطف اختياري من system prompt على مستوى الغرفة. +- `groups..systemPrompt`: مقتطف system prompt اختياري على مستوى الغرفة. - `rooms`: اسم مستعار قديم لـ `groups`. -- `actions`: التحكم في الأدوات لكل إجراء (`messages` و`reactions` و`pins` و`profile` و`memberInfo` و`channelInfo` و`verification`). +- `actions`: تقييد الأدوات لكل إجراء (`messages` أو `reactions` أو `pins` أو `profile` أو `memberInfo` أو `channelInfo` أو `verification`). ## ذو صلة -- [نظرة عامة على القنوات](/ar/channels) — جميع القنوات المدعومة -- [Pairing](/ar/channels/pairing) — مصادقة الرسائل المباشرة وتدفق الاقتران -- [Groups](/ar/channels/groups) — سلوك دردشات المجموعات وتقييد الإشارات -- [توجيه القنوات](/ar/channels/channel-routing) — توجيه الجلسات للرسائل -- [الأمان](/ar/gateway/security) — نموذج الوصول والتقوية +- [Channels Overview](/ar/channels) — جميع القنوات المدعومة +- [Pairing](/ar/channels/pairing) — مصادقة الرسائل الخاصة وتدفق الاقتران +- [Groups](/ar/channels/groups) — سلوك دردشة المجموعات وتقييد mentions +- [Channel Routing](/ar/channels/channel-routing) — توجيه الجلسات للرسائل +- [Security](/ar/gateway/security) — نموذج الوصول والتقوية diff --git a/docs/ar/concepts/dreaming.md b/docs/ar/concepts/dreaming.md index f94584d2d..118ef35c2 100644 --- a/docs/ar/concepts/dreaming.md +++ b/docs/ar/concepts/dreaming.md @@ -1,136 +1,141 @@ --- read_when: - تريد أن يعمل ترقية الذاكرة تلقائيًا - - تريد فهم ما الذي تفعله كل مرحلة من مراحل الأحلام - - تريد ضبط الدمج دون تلويث `MEMORY.md` -summary: دمج ذاكرة في الخلفية بمراحل خفيفة وعميقة وREM بالإضافة إلى يوميات الأحلام -title: الأحلام (تجريبي) + - تريد أن تفهم ما الذي تفعله كل مرحلة من مراحل Dreaming + - تريد ضبط التوحيد دون تلويث `MEMORY.md` +summary: توحيد الذاكرة في الخلفية مع مراحل خفيفة وعميقة وREM بالإضافة إلى يوميات الأحلام +title: Dreaming (تجريبي) x-i18n: - generated_at: "2026-04-09T01:27:52Z" + generated_at: "2026-04-15T07:17:44Z" model: gpt-5.4 provider: openai - source_hash: 26476eddb8260e1554098a6adbb069cf7f5e284cf2e09479c6d9d8f8b93280ef + source_hash: 5882a5068f2eabe54ca9893184e5385330a432b921870c38626399ce11c31e25 source_path: concepts/dreaming.md workflow: 15 --- -# الأحلام (تجريبي) +# Dreaming (تجريبي) -الأحلام هي نظام دمج الذاكرة في الخلفية داخل `memory-core`. -وهي تساعد OpenClaw على نقل الإشارات القوية قصيرة الأمد إلى ذاكرة دائمة مع -إبقاء العملية قابلة للتفسير والمراجعة. +Dreaming هو نظام توحيد الذاكرة في الخلفية داخل `memory-core`. +يساعد OpenClaw على نقل الإشارات القوية قصيرة الأجل إلى ذاكرة دائمة مع +الحفاظ على العملية قابلة للتفسير والمراجعة. -الأحلام **تعمل بالاشتراك** وهي معطلة افتراضيًا. +Dreaming هو **اختياري** ومُعطَّل افتراضيًا. -## ما الذي تكتبه الأحلام +## ما الذي يكتبه Dreaming -تحتفظ الأحلام بنوعين من المخرجات: +يحتفظ Dreaming بنوعين من المخرجات: -- **حالة الآلة** في `memory/.dreams/` (مخزن الاستدعاء، إشارات المراحل، نقاط تحقق الإدخال، والأقفال). +- **حالة الآلة** في `memory/.dreams/` (مخزن الاسترجاع، إشارات المراحل، نقاط تحقق الاستيعاب، الأقفال). - **مخرجات قابلة للقراءة البشرية** في `DREAMS.md` (أو `dreams.md` الموجود) وملفات تقارير المراحل الاختيارية ضمن `memory/dreaming//YYYY-MM-DD.md`. -تظل الترقية طويلة الأمد تكتب فقط إلى `MEMORY.md`. +تستمر الترقية طويلة الأجل في الكتابة إلى `MEMORY.md` فقط. ## نموذج المراحل -تستخدم الأحلام ثلاث مراحل تعاونية: +يستخدم Dreaming ثلاث مراحل تعاونية: -| المرحلة | الغرض | الكتابة الدائمة | -| ----- | ----------------------------------------- | ----------------- | -| خفيفة | فرز وتجهيز المواد الحديثة قصيرة الأمد | لا | -| عميقة | تقييم المرشحين الدائمين وترقيتهم | نعم (`MEMORY.md`) | -| REM | التأمل في الموضوعات والأفكار المتكررة | لا | +| المرحلة | الغرض | الكتابة الدائمة | +| ------- | --------------------------------------- | ------------------- | +| Light | فرز وتجهيز المواد الحديثة قصيرة الأجل | لا | +| Deep | تقييم المرشحين الدائمين وترقيتهم | نعم (`MEMORY.md`) | +| REM | التأمل في السمات والأفكار المتكررة | لا | -هذه المراحل تفاصيل تنفيذ داخلية وليست "أوضاعًا" منفصلة يضبطها المستخدم. +هذه المراحل هي تفاصيل تنفيذ داخلية، وليست "أوضاعًا" منفصلة +يمكن للمستخدم إعدادها. -### المرحلة الخفيفة +### مرحلة Light -تستوعب المرحلة الخفيفة إشارات الذاكرة اليومية الحديثة وآثار الاستدعاء، وتزيل -التكرار منها، وتجهز أسطرًا مرشحة. +تستوعب مرحلة Light إشارات الذاكرة اليومية الحديثة وآثار الاسترجاع، وتزيل التكرار منها، +وتجهز سطورًا مرشحة. -- تقرأ من حالة الاستدعاء قصيرة الأمد، وملفات الذاكرة اليومية الحديثة، ونصوص الجلسات المنقحة عند توفرها. -- تكتب كتلة `## Light Sleep` مُدارة عندما يتضمن التخزين مخرجات مضمنة. -- تسجل إشارات تعزيز لاستخدامها لاحقًا في الترتيب العميق. +- تقرأ من حالة الاسترجاع قصيرة الأجل، وملفات الذاكرة اليومية الحديثة، ونصوص الجلسات المنقحة عند توفرها. +- تكتب كتلة `## Light Sleep` مُدارة عندما يتضمن التخزين مخرجات مضمّنة. +- تسجل إشارات تعزيز لاستخدامها لاحقًا في ترتيب Deep. - لا تكتب أبدًا إلى `MEMORY.md`. -### المرحلة العميقة +### مرحلة Deep -تحدد المرحلة العميقة ما الذي يصبح ذاكرة طويلة الأمد. +تقرر مرحلة Deep ما الذي يصبح ذاكرة طويلة الأجل. -- ترتب المرشحين باستخدام تقييم موزون وبوابات عتبة. +- ترتب المرشحين باستخدام التقييم الموزون وبوابات العتبة. - تتطلب اجتياز `minScore` و`minRecallCount` و`minUniqueQueries`. -- تعيد إماهة المقاطع من الملفات اليومية الحية قبل الكتابة، لذلك يتم تخطي المقاطع القديمة أو المحذوفة. +- تعيد ترطيب المقتطفات من الملفات اليومية الحية قبل الكتابة، لذلك يتم تخطي المقتطفات القديمة أو المحذوفة. - تُلحق الإدخالات المُرقّاة إلى `MEMORY.md`. -- تكتب ملخص `## Deep Sleep` داخل `DREAMS.md`، وتكتب اختياريًا إلى `memory/dreaming/deep/YYYY-MM-DD.md`. +- تكتب ملخص `## Deep Sleep` داخل `DREAMS.md`، ويمكنها اختياريًا الكتابة إلى `memory/dreaming/deep/YYYY-MM-DD.md`. ### مرحلة REM تستخرج مرحلة REM الأنماط والإشارات التأملية. -- تبني ملخصات للموضوعات والتأملات من الآثار قصيرة الأمد الحديثة. -- تكتب كتلة `## REM Sleep` مُدارة عندما يتضمن التخزين مخرجات مضمنة. -- تسجل إشارات تعزيز REM المستخدمة في الترتيب العميق. +- تُنشئ ملخصات للسمات والتأملات من آثار قصيرة الأجل حديثة. +- تكتب كتلة `## REM Sleep` مُدارة عندما يتضمن التخزين مخرجات مضمّنة. +- تسجل إشارات تعزيز REM المستخدمة في ترتيب Deep. - لا تكتب أبدًا إلى `MEMORY.md`. -## إدخال نصوص الجلسات +## استيعاب نصوص الجلسات -يمكن للأحلام أن تستوعب نصوص الجلسات المنقحة في مجموعة بيانات الأحلام. عندما -تكون النصوص متاحة، يتم تمريرها إلى المرحلة الخفيفة إلى جانب إشارات الذاكرة -اليومية وآثار الاستدعاء. ويتم تنقيح المحتوى الشخصي والحساس قبل الإدخال. +يمكن لـ Dreaming استيعاب نصوص الجلسات المنقحة ضمن corpus الخاص بـ Dreaming. عند +توفر النصوص، يتم تمريرها إلى مرحلة Light جنبًا إلى جنب مع إشارات +الذاكرة اليومية وآثار الاسترجاع. يتم تنقيح المحتوى الشخصي والحساس +قبل الاستيعاب. -## يوميات الأحلام +## Dream Diary -تحتفظ الأحلام أيضًا بسرد **يوميات الأحلام** في `DREAMS.md`. -بعد أن تمتلك كل مرحلة مادة كافية، يشغّل `memory-core` محاولةً بأفضل جهد -لدورة وكيل فرعي في الخلفية (باستخدام نموذج وقت التشغيل الافتراضي) ثم يُلحق -إدخال يوميات قصيرًا. +يحتفظ Dreaming أيضًا بـ **Dream Diary** سردية داخل `DREAMS.md`. +بعد أن تتوفر لكل مرحلة مادة كافية، يشغّل `memory-core` +دورة فرعية في الخلفية بأفضل جهد ممكن (باستخدام نموذج وقت التشغيل الافتراضي) +ويُلحق إدخال يوميات قصيرًا. هذه اليوميات مخصصة للقراءة البشرية في واجهة Dreams، وليست مصدرًا للترقية. +تُستبعد ملفات اليوميات/التقارير التي يُنشئها Dreaming من +الترقية قصيرة الأجل. فقط مقتطفات الذاكرة المرتكزة على مصادر حقيقية تكون مؤهلة للترقية إلى +`MEMORY.md`. -يوجد أيضًا مسار تعبئة تاريخية مرتكز للمراجعة وأعمال الاستعادة: +يوجد أيضًا مسار تعبئة تاريخية مرتكز على مصادر حقيقية لأعمال المراجعة والاستعادة: -- `memory rem-harness --path ... --grounded` يعرض معاينة لمخرجات يوميات مرتكزة من ملاحظات `YYYY-MM-DD.md` التاريخية. -- `memory rem-backfill --path ...` يكتب إدخالات يوميات مرتكزة قابلة للعكس إلى `DREAMS.md`. -- `memory rem-backfill --path ... --stage-short-term` يجهز مرشحين دائمين مرتكزين في نفس مخزن الأدلة قصيرة الأمد الذي تستخدمه المرحلة العميقة العادية بالفعل. -- `memory rem-backfill --rollback` و`--rollback-short-term` يزيلان عناصر التعبئة الراجعة المُجهزة هذه دون المساس بإدخالات اليوميات العادية أو الاستدعاء الحي قصير الأمد. +- يعاين `memory rem-harness --path ... --grounded` مخرجات يوميات مرتكزة على مصادر حقيقية من ملاحظات `YYYY-MM-DD.md` التاريخية. +- يكتب `memory rem-backfill --path ...` إدخالات يوميات مرتكزة قابلة للعكس داخل `DREAMS.md`. +- يُجهّز `memory rem-backfill --path ... --stage-short-term` مرشحين دائمين مرتكزين على مصادر حقيقية في نفس مخزن الأدلة قصيرة الأجل الذي تستخدمه مرحلة Deep العادية بالفعل. +- يزيل `memory rem-backfill --rollback` و`--rollback-short-term` ملفات التعبئة المرحلية هذه دون المساس بإدخالات اليوميات العادية أو الاسترجاع الحي قصير الأجل. -تعرض واجهة Control UI نفس تدفق التعبئة الراجعة/إعادة التعيين لليوميات حتى تتمكن من -فحص النتائج في مشهد Dreams قبل تقرير ما إذا كان المرشحون المرتكزون -يستحقون الترقية. ويعرض المشهد أيضًا مسارًا مرتكزًا منفصلًا حتى تتمكن من رؤية -إدخالات المدى القصير المُجهزة التي جاءت من إعادة تشغيل تاريخية، والعناصر -المُرقّاة التي قادها التأريض، ومسح الإدخالات المُجهزة المرتكزة فقط دون -المساس بحالة المدى القصير الحية العادية. +تعرض واجهة Control أيضًا نفس تدفق تعبئة/إعادة تعيين اليوميات بحيث يمكنك فحص +النتائج في مشهد Dreams قبل أن تقرر ما إذا كانت المرشحات المرتكزة على مصادر حقيقية +تستحق الترقية. ويعرض المشهد أيضًا مسارًا مرتكزًا مميزًا حتى تتمكن من رؤية +إدخالات المرحلة قصيرة الأجل التي جاءت من إعادة تشغيل تاريخية، والعناصر المُرقّاة +التي كانت مدفوعة بالمحتوى المرتكز، ومسح الإدخالات المرحلية المرتكزة فقط دون +المساس بحالة الإدخالات الحية قصيرة الأجل العادية. -## إشارات الترتيب العميق +## إشارات ترتيب Deep -يستخدم الترتيب العميق ست إشارات أساسية موزونة بالإضافة إلى تعزيز المراحل: +يستخدم ترتيب Deep ست إشارات أساسية موزونة بالإضافة إلى تعزيز المراحل: -| الإشارة | الوزن | الوصف | -| ------------------- | ------ | ------------------------------------------------- | -| التكرار | 0.24 | عدد إشارات المدى القصير التي راكمها الإدخال | -| الصلة | 0.30 | متوسط جودة الاسترجاع للإدخال | -| تنوع الاستعلامات | 0.15 | سياقات الاستعلام/اليوم المميزة التي أظهرته | -| الحداثة | 0.15 | درجة حداثة متناقصة بمرور الوقت | -| الدمج | 0.10 | قوة التكرار عبر عدة أيام | -| الثراء المفاهيمي | 0.06 | كثافة وسوم المفاهيم من المقطع/المسار | +| الإشارة | الوزن | الوصف | +| ------------------- | ----- | ------------------------------------------------ | +| التكرار | 0.24 | عدد الإشارات قصيرة الأجل التي تراكمت للإدخال | +| الصلة | 0.30 | متوسط جودة الاسترجاع للإدخال | +| تنوع الاستعلامات | 0.15 | سياقات الاستعلام/اليوم المميزة التي أظهرته | +| الحداثة | 0.15 | درجة حداثة متضائلة مع الزمن | +| التوحيد | 0.10 | قوة التكرار عبر أيام متعددة | +| الثراء المفاهيمي | 0.06 | كثافة وسوم المفاهيم من المقتطف/المسار | -تضيف إصابات المرحلتين الخفيفة وREM دفعة صغيرة متناقصة مع الحداثة من +تضيف إصابات مرحلتي Light وREM دفعة صغيرة متضائلة مع الزمن من `memory/.dreams/phase-signals.json`. ## الجدولة -عند التمكين، يدير `memory-core` تلقائيًا مهمة cron واحدة لاجتياز كامل -للأحلام. يشغّل كل اجتياز المراحل بالترتيب: خفيفة -> REM -> عميقة. +عند تفعيله، يدير `memory-core` تلقائيًا مهمة Cron واحدة لاجتياز Dreaming كامل. +يشغّل كل اجتياز المراحل بالترتيب: light -> REM -> deep. سلوك الوتيرة الافتراضية: -| الإعداد | الافتراضي | -| -------------------- | ----------- | +| الإعداد | الافتراضي | +| -------------------- | ---------- | | `dreaming.frequency` | `0 3 * * *` | ## البدء السريع -فعّل الأحلام: +فعّل Dreaming: ```json { @@ -148,7 +153,7 @@ x-i18n: } ``` -فعّل الأحلام مع وتيرة اجتياز مخصصة: +فعّل Dreaming مع وتيرة اجتياز مخصصة: ```json { @@ -188,17 +193,17 @@ openclaw memory promote --limit 5 openclaw memory status --deep ``` -يستخدم `memory promote` اليدوي عتبات المرحلة العميقة افتراضيًا ما لم يتم -تجاوزها بعلامات CLI. +يستخدم `memory promote` اليدوي عتبات مرحلة Deep افتراضيًا ما لم يتم تجاوزها +باستخدام أعلام CLI. -اشرح لماذا سيُرقّى مرشح محدد أو لن يُرقّى: +اشرح لماذا سيُرقّى مرشح معيّن أو لن يُرقّى: ```bash openclaw memory promote-explain "router vlan" openclaw memory promote-explain "router vlan" --json ``` -اعرض تأملات REM وحقائق المرشحين ومخرجات الترقية العميقة دون +عاين تأملات REM، والحقائق المرشحة، ومخرجات ترقية Deep دون كتابة أي شيء: ```bash @@ -210,27 +215,27 @@ openclaw memory rem-harness --json توجد جميع الإعدادات تحت `plugins.entries.memory-core.config.dreaming`. -| المفتاح | الافتراضي | -| ----------- | ----------- | -| `enabled` | `false` | +| المفتاح | الافتراضي | +| ---------- | ---------- | +| `enabled` | `false` | | `frequency` | `0 3 * * *` | -سياسة المراحل والعتبات وسلوك التخزين هي تفاصيل تنفيذ داخلية -(وليست إعدادات موجّهة للمستخدم). +سياسة المراحل، والعتبات، وسلوك التخزين هي تفاصيل تنفيذ داخلية +(وليست إعدادات موجهة للمستخدم). راجع [مرجع إعدادات الذاكرة](/ar/reference/memory-config#dreaming-experimental) للحصول على القائمة الكاملة للمفاتيح. ## واجهة Dreams -عند التمكين، تعرض علامة تبويب **Dreams** في Gateway ما يلي: +عند التفعيل، تعرض علامة التبويب **Dreams** في Gateway ما يلي: -- حالة تمكين الأحلام الحالية -- حالة على مستوى المرحلة ووجود الاجتياز المُدار -- أعداد المدى القصير، والمرتكز، والإشارات، وما تمت ترقيته اليوم +- حالة تفعيل Dreaming الحالية +- حالة على مستوى المراحل ووجود اجتياز مُدار +- أعداد العناصر قصيرة الأجل، والمرتكزة، والإشارات، والمُرقّاة اليوم - توقيت التشغيل المجدول التالي -- مسار Scene مرتكز منفصل لإدخالات إعادة التشغيل التاريخية المُجهزة -- قارئ يوميات أحلام قابل للتوسيع ومدعوم بواسطة `doctor.memory.dreamDiary` +- مسار Scene مرتكز مميز لإدخالات إعادة التشغيل التاريخية المرحلية +- قارئ Dream Diary قابل للتوسيع ومدعوم بواسطة `doctor.memory.dreamDiary` ## ذو صلة diff --git a/docs/ar/gateway/local-models.md b/docs/ar/gateway/local-models.md index 20b32f954..8ec8c95c1 100644 --- a/docs/ar/gateway/local-models.md +++ b/docs/ar/gateway/local-models.md @@ -1,28 +1,28 @@ --- read_when: - تريد تقديم النماذج من جهاز GPU الخاص بك - - أنت تُعدّ LM Studio أو وكيلاً متوافقًا مع OpenAI + - أنت تقوم بإعداد LM Studio أو وكيل متوافق مع OpenAI - تحتاج إلى أكثر إرشادات النماذج المحلية أمانًا -summary: شغّل OpenClaw على نماذج اللغة الكبيرة المحلية (LM Studio وvLLM وLiteLLM ونقاط نهاية OpenAI المخصّصة) +summary: شغّل OpenClaw على نماذج LLM المحلية (LM Studio، vLLM، LiteLLM، ونقاط نهاية OpenAI المخصّصة) title: النماذج المحلية x-i18n: - generated_at: "2026-04-14T07:17:43Z" + generated_at: "2026-04-15T07:17:57Z" model: gpt-5.4 provider: openai - source_hash: 1544c522357ba4b18dfa6d05ea8d60c7c6262281b53863d9aee7002464703ca7 + source_hash: 8778cc1c623a356ff3cf306c494c046887f9417a70ec71e659e4a8aae912a780 source_path: gateway/local-models.md workflow: 15 --- # النماذج المحلية -التشغيل المحلي ممكن، لكن OpenClaw يتوقع سياقًا كبيرًا + دفاعات قوية ضد حقن التلقين. البطاقات الصغيرة تقتطع السياق وتُضعف الأمان. استهدف مستوى عالٍ: **استوديوهَا Mac Studio مضبوطتان للحد الأقصى على الأقل أو منصة GPU مكافئة (~أكثر من 30 ألف دولار)**. تعمل وحدة GPU واحدة بسعة **24 GB** فقط مع التلقينات الأخف وبزمن استجابة أعلى. استخدم **أكبر / البديل الكامل الحجم من النموذج الذي يمكنك تشغيله**؛ إذ إن نقاط التحقق المضغوطة بقوة أو “الصغيرة” ترفع مخاطر حقن التلقين (راجع [الأمان](/ar/gateway/security)). +التشغيل المحلي ممكن، لكن OpenClaw يتوقع سياقًا كبيرًا + دفاعات قوية ضد حقن المطالبات. البطاقات الصغيرة تقطع السياق وتُضعف الأمان. استهدف مستوى مرتفعًا: **استوديوهَي Mac Studio على الأقل بكامل المواصفات أو منصة GPU مكافئة (~30 ألف دولار فأكثر)**. تعمل بطاقة GPU واحدة بسعة **24 GB** فقط مع المطالبات الأخف وزمن استجابة أعلى. استخدم **أكبر / النسخة كاملة الحجم من النموذج التي يمكنك تشغيلها**؛ فالإصدارات المضغوطة بشدة أو نقاط التحقق “الصغيرة” تزيد من مخاطر حقن المطالبات (راجع [الأمان](/ar/gateway/security)). -إذا كنت تريد إعدادًا محليًا بأقل قدر من التعقيد، فابدأ بـ [LM Studio](/ar/providers/lmstudio) أو [Ollama](/ar/providers/ollama) و`openclaw onboard`. هذه الصفحة هي الدليل العملي الموجَّه للحِزم المحلية الأعلى مستوى وخوادم OpenAI-compatible المحلية المخصّصة. +إذا كنت تريد إعدادًا محليًا بأقل قدر من التعقيد، فابدأ بـ [LM Studio](/ar/providers/lmstudio) أو [Ollama](/ar/providers/ollama) واستخدم `openclaw onboard`. هذه الصفحة هي الدليل العملي الموجّه للبنى المحلية الأعلى مستوى وخوادم OpenAI المحلية المخصّصة المتوافقة. ## الموصى به: LM Studio + نموذج محلي كبير (Responses API) -أفضل حزمة محلية حاليًا. حمّل نموذجًا كبيرًا في LM Studio (على سبيل المثال، إصدارًا كامل الحجم من Qwen أو DeepSeek أو Llama)، ثم فعّل الخادم المحلي (الافتراضي `http://127.0.0.1:1234`) واستخدم Responses API لإبقاء الاستدلال منفصلًا عن النص النهائي. +أفضل بنية محلية حاليًا. حمّل نموذجًا كبيرًا في LM Studio (على سبيل المثال، إصدارًا كامل الحجم من Qwen أو DeepSeek أو Llama)، وفعّل الخادم المحلي (الافتراضي `http://127.0.0.1:1234`)، واستخدم Responses API للحفاظ على فصل الاستدلال عن النص النهائي. ```json5 { @@ -59,18 +59,18 @@ x-i18n: } ``` -**قائمة الإعداد** +**قائمة إعداد سريعة** - ثبّت LM Studio: [https://lmstudio.ai](https://lmstudio.ai) -- في LM Studio، نزّل **أكبر إصدار نموذج متاح** (تجنّب البدائل “الصغيرة” أو المضغوطة بشدة)، وابدأ الخادم، وتأكد من أن `http://127.0.0.1:1234/v1/models` يعرضه. +- في LM Studio، نزّل **أكبر إصدار متاح من النموذج** (تجنّب الإصدارات “الصغيرة”/المضغوطة بشدة)، ثم شغّل الخادم، وتأكد من أن `http://127.0.0.1:1234/v1/models` يعرضه. - استبدل `my-local-model` بمعرّف النموذج الفعلي الظاهر في LM Studio. -- أبقِ النموذج محمّلًا؛ فالتحميل البارد يضيف زمن بدء تشغيل. -- اضبط `contextWindow`/`maxTokens` إذا كان إصدار LM Studio لديك مختلفًا. -- بالنسبة إلى WhatsApp، التزم بـ Responses API حتى لا يُرسل إلا النص النهائي. +- أبقِ النموذج محمّلًا؛ فالتحميل البارد يضيف زمن بدء. +- اضبط `contextWindow` و`maxTokens` إذا كان إصدار LM Studio لديك مختلفًا. +- بالنسبة إلى WhatsApp، التزم باستخدام Responses API بحيث لا يُرسل سوى النص النهائي. -أبقِ النماذج المستضافة مُعدّة حتى عند التشغيل المحلي؛ استخدم `models.mode: "merge"` حتى تظل خيارات الرجوع الاحتياطي متاحة. +أبقِ النماذج المستضافة مهيأة حتى عند التشغيل المحلي؛ استخدم `models.mode: "merge"` حتى تظل بدائل التراجع متاحة. -### إعداد هجين: نموذج مستضاف أساسي، ونموذج محلي احتياطي +### إعداد هجين: نموذج مستضاف أساسي، وتراجع محلي ```json5 { @@ -113,16 +113,16 @@ x-i18n: ### محلي أولًا مع شبكة أمان مستضافة -بدّل ترتيب الأساسي والاحتياطي؛ وأبقِ كتلة المزوّدين نفسها و`models.mode: "merge"` حتى تتمكن من الرجوع إلى Sonnet أو Opus عندما يتعطل الجهاز المحلي. +بدّل ترتيب النموذج الأساسي وبدائل التراجع؛ وأبقِ كتلة providers نفسها و`models.mode: "merge"` حتى تتمكن من التراجع إلى Sonnet أو Opus عندما يتعطل الجهاز المحلي. ### الاستضافة الإقليمية / توجيه البيانات -- تتوفر أيضًا بدائل MiniMax/Kimi/GLM المستضافة على OpenRouter مع نقاط نهاية مثبّتة حسب المنطقة (مثلًا، مستضافة في الولايات المتحدة). اختر البديل الإقليمي هناك للإبقاء على حركة البيانات داخل النطاق القضائي الذي تختاره مع الاستمرار في استخدام `models.mode: "merge"` كخيارات احتياطية لـ Anthropic/OpenAI. -- يظل التشغيل المحلي فقط هو أقوى مسار للخصوصية؛ أما التوجيه الإقليمي المستضاف فهو الحل الوسط عندما تحتاج إلى مزايا المزوّد لكنك تريد التحكم في تدفق البيانات. +- تتوفر أيضًا إصدارات MiniMax/Kimi/GLM المستضافة على OpenRouter مع نقاط نهاية مثبتة على مناطق محددة (مثل الاستضافة داخل الولايات المتحدة). اختر الإصدار الإقليمي هناك لإبقاء الحركة ضمن النطاق القضائي الذي تختاره، مع الاستمرار في استخدام `models.mode: "merge"` لبدائل التراجع من Anthropic/OpenAI. +- يظل التشغيل المحلي فقط هو المسار الأقوى من ناحية الخصوصية؛ أما التوجيه الإقليمي للاستضافة فهو الحل الوسط عندما تحتاج إلى ميزات المزوّد لكنك تريد التحكم في تدفق البيانات. ## وكلاء محليون آخرون متوافقون مع OpenAI -يعمل vLLM وLiteLLM وOAI-proxy أو البوابات المخصّصة إذا كانت توفّر نقطة نهاية `/v1` بأسلوب OpenAI. استبدل كتلة المزوّد أعلاه بنقطة النهاية ومعرّف النموذج لديك: +يمكن استخدام vLLM أو LiteLLM أو OAI-proxy أو البوابات المخصصة إذا كانت توفّر نقطة نهاية `/v1` بأسلوب OpenAI. استبدل كتلة provider أعلاه بنقطة النهاية ومعرّف النموذج الخاصين بك: ```json5 { @@ -150,42 +150,45 @@ x-i18n: } ``` -أبقِ `models.mode: "merge"` حتى تظل النماذج المستضافة متاحة كخيارات احتياطية. +أبقِ `models.mode: "merge"` حتى تظل النماذج المستضافة متاحة كبدائل تراجع. -ملاحظة سلوكية لخلفيات `/v1` المحلية/الوسيطة: +ملاحظة سلوكية للخلفيات المحلية/المعتمدة على وكيل `/v1`: -- يتعامل OpenClaw مع هذه المسارات على أنها مسارات وسيطة متوافقة مع OpenAI، وليست +- يتعامل OpenClaw مع هذه المسارات على أنها مسارات وكيل متوافقة مع OpenAI، وليست نقاط نهاية OpenAI أصلية -- لا ينطبق هنا تشكيل الطلبات الخاص بـ OpenAI الأصلية فقط: لا - `service_tier`، ولا `store` في Responses، ولا تشكيل حمولة التوافق مع استدلال OpenAI، - ولا تلميحات ذاكرة التخزين المؤقت للتلقين -- لا تُحقن ترويسات الإسناد المخفية الخاصة بـ OpenClaw (`originator` و`version` و`User-Agent`) - في عناوين URL المخصّصة لهذه الوكلاء +- لا ينطبق هنا تشكيل الطلبات الخاص بـ OpenAI الأصلي فقط: لا يوجد + `service_tier`، ولا `store` الخاص بـ Responses، ولا تشكيل حمولة + التوافق مع الاستدلال في OpenAI، ولا تلميحات cache للمطالبة +- لا يتم حقن ترويسات الإسناد المخفية الخاصة بـ OpenClaw (`originator` و`version` و`User-Agent`) + على عناوين URL الخاصة بهذه الوكلاء المخصصة -ملاحظات التوافق للخلفيات الأكثر تشددًا والمتوافقة مع OpenAI: +ملاحظات التوافق للخلفيات الأكثر صرامة والمتوافقة مع OpenAI: -- بعض الخوادم تقبل فقط `messages[].content` كسلسلة نصية في Chat Completions، وليس - مصفوفات أجزاء المحتوى المهيكلة. اضبط - `models.providers..models[].compat.requiresStringContent: true` لنقاط - النهاية تلك. -- بعض الخلفيات المحلية الأصغر أو الأكثر تشددًا تكون غير مستقرة مع شكل التلقين الكامل - لبيئة تشغيل الوكلاء في OpenClaw، خاصةً عند تضمين مخططات الأدوات. إذا كانت - الخلفية تعمل مع استدعاءات `/v1/chat/completions` المباشرة الصغيرة لكنها تفشل في - أدوار الوكيل العادية في OpenClaw، فجرّب أولًا +- تقبل بعض الخوادم فقط `messages[].content` كسلسلة نصية في Chat Completions، وليس + مصفوفات أجزاء المحتوى المنظمة. اضبط + `models.providers..models[].compat.requiresStringContent: true` لتلك + النقاط النهائية. +- تكون بعض الخلفيات المحلية الأصغر أو الأكثر صرامة غير مستقرة مع الشكل الكامل + لمطالبة بيئة تشغيل الوكيل في OpenClaw، خاصةً عند تضمين مخططات الأدوات. إذا كانت + الخلفية تعمل مع طلبات `/v1/chat/completions` المباشرة والصغيرة لكنها تفشل في + دورات الوكيل العادية في OpenClaw، فجرّب أولًا + `agents.defaults.localModelMode: "lean"` لإسقاط الأدوات الافتراضية الثقيلة + مثل `browser` و`cron` و`message`؛ وإذا استمر الفشل بعد ذلك، فجرّب `models.providers..models[].compat.supportsTools: false`. -- إذا استمرت الخلفية في الفشل فقط مع تشغيلات OpenClaw الأكبر، فعادةً ما تكون المشكلة - في سعة النموذج/الخادم المصدر أو في خطأ في الخلفية، وليس في طبقة النقل الخاصة بـ OpenClaw. +- إذا كانت الخلفية لا تزال تفشل فقط في تشغيلات OpenClaw الأكبر، فغالبًا تكون + المشكلة المتبقية سعة النموذج/الخادم من الجهة العليا أو خطأ في الخلفية، وليس + في طبقة النقل الخاصة بـ OpenClaw. ## استكشاف الأخطاء وإصلاحها -- هل يستطيع Gateway الوصول إلى الوكيل؟ `curl http://127.0.0.1:1234/v1/models`. +- هل تستطيع Gateway الوصول إلى الوكيل؟ `curl http://127.0.0.1:1234/v1/models`. - هل تم إلغاء تحميل نموذج LM Studio؟ أعد تحميله؛ فالبدء البارد سبب شائع لـ “التعليق”. - يحذّر OpenClaw عندما تكون نافذة السياق المكتشفة أقل من **32k** ويمنع التشغيل عندما تكون أقل من **16k**. إذا واجهت هذا الفحص المسبق، فارفع حد السياق في الخادم/النموذج أو اختر نموذجًا أكبر. -- أخطاء في السياق؟ خفّض `contextWindow` أو ارفع حد الخادم لديك. -- هل يعيد الخادم المتوافق مع OpenAI الخطأ `messages[].content ... expected a string`؟ +- أخطاء السياق؟ خفّض `contextWindow` أو ارفع حد الخادم لديك. +- هل يُرجع الخادم المتوافق مع OpenAI الخطأ `messages[].content ... expected a string`؟ أضف `compat.requiresStringContent: true` إلى إدخال ذلك النموذج. -- هل تعمل استدعاءات `/v1/chat/completions` الصغيرة المباشرة، لكن `openclaw infer model run` +- تعمل طلبات `/v1/chat/completions` المباشرة والصغيرة، لكن `openclaw infer model run` يفشل مع Gemma أو نموذج محلي آخر؟ عطّل مخططات الأدوات أولًا باستخدام - `compat.supportsTools: false`، ثم اختبر مجددًا. إذا استمر الخادم في التعطل فقط - مع تلقينات OpenClaw الأكبر، فاعتبر ذلك قيدًا في الخادم/النموذج المصدر. -- الأمان: تتجاوز النماذج المحلية عوامل التصفية الموجودة لدى المزوّد؛ لذا اجعل الوكلاء محدودي النطاق وأبقِ Compaction مفعّلًا لتقليل نطاق تأثير حقن التلقين. + `compat.supportsTools: false`، ثم أعد الاختبار. إذا استمر الخادم في الانهيار فقط + مع مطالبات OpenClaw الأكبر، فاعتبر ذلك قيدًا في الخادم/النموذج من الجهة العليا. +- الأمان: تتخطى النماذج المحلية عوامل التصفية على جهة المزوّد؛ أبقِ الوكلاء محدودي النطاق وفعّل Compaction للحد من نطاق تأثير حقن المطالبات. diff --git a/docs/ar/help/testing.md b/docs/ar/help/testing.md index 9d8092624..0cbf8efe2 100644 --- a/docs/ar/help/testing.md +++ b/docs/ar/help/testing.md @@ -2,101 +2,103 @@ read_when: - تشغيل الاختبارات محليًا أو في CI - إضافة اختبارات انحدار لأخطاء النموذج/المزوّد - - تصحيح سلوك Gateway + الوكيل -summary: 'مجموعة الاختبار: مجموعات unit/e2e/live، ومشغّلات Docker، وما الذي يغطيه كل اختبار' + - تصحيح سلوك Gateway والوكيل +summary: 'عدة الاختبار: مجموعات unit/e2e/live، مشغّلات Docker، وما الذي يغطيه كل اختبار' title: الاختبار x-i18n: - generated_at: "2026-04-13T07:28:54Z" + generated_at: "2026-04-15T07:17:48Z" model: gpt-5.4 provider: openai - source_hash: 3db91b4bc36f626cd014958ec66b08b9cecd9faaa20a5746cd3a49ad4b0b1c38 + source_hash: fbf647a5cf13b5861a3ba0cb367dc816c57f0e9c60d3cd6320da193bfadf5609 source_path: help/testing.md workflow: 15 --- # الاختبار -يحتوي OpenClaw على ثلاث مجموعات Vitest (unit/integration و e2e و live) ومجموعة صغيرة من مشغّلات Docker. +يحتوي OpenClaw على ثلاث مجموعات Vitest (unit/integration وe2e وlive) ومجموعة صغيرة من مشغّلات Docker. -هذا المستند هو دليل "كيف نختبر": +هذا المستند هو دليل «كيف نختبر»: - ما الذي تغطيه كل مجموعة (وما الذي لا تغطيه عمدًا) -- الأوامر التي يجب تشغيلها لعمليات العمل الشائعة (محليًا، قبل الدفع، تصحيح الأخطاء) -- كيف تكتشف الاختبارات الحية بيانات الاعتماد وتختار النماذج/المزوّدين -- كيفية إضافة اختبارات انحدار لمشكلات النماذج/المزوّدين الواقعية +- ما الأوامر التي يجب تشغيلها لسير العمل الشائع (محليًا، قبل الدفع، التصحيح) +- كيف تكتشف اختبارات live بيانات الاعتماد وتختار النماذج/المزوّدين +- كيفية إضافة اختبارات انحدار لمشكلات النموذج/المزوّد في العالم الحقيقي -## البداية السريعة +## البدء السريع في معظم الأيام: - البوابة الكاملة (متوقعة قبل الدفع): `pnpm build && pnpm check && pnpm test` -- تشغيل أسرع للمجموعة الكاملة محليًا على جهاز ذي موارد كبيرة: `pnpm test:max` +- تشغيل أسرع محليًا للمجموعة الكاملة على جهاز واسع الموارد: `pnpm test:max` - حلقة مراقبة Vitest مباشرة: `pnpm test:watch` -- الاستهداف المباشر للملفات يمر الآن أيضًا عبر مسارات الامتدادات/القنوات: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- فضّل التشغيلات المستهدفة أولًا عندما تعمل على تكرار إصلاح فشل واحد. +- استهداف الملفات مباشرة يوجّه الآن أيضًا مسارات الامتداد/القناة: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- فضّل عمليات التشغيل المستهدفة أولًا عندما تكون تعمل على تكرار معالجة فشل واحد. - موقع QA مدعوم بـ Docker: `pnpm qa:lab:up` - مسار QA مدعوم بآلة Linux افتراضية: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -عندما تلمس الاختبارات أو تريد مزيدًا من الثقة: +عندما تلمس الاختبارات أو تريد ثقة إضافية: - بوابة التغطية: `pnpm test:coverage` - مجموعة E2E: `pnpm test:e2e` -عند تصحيح مزوّدين/نماذج حقيقية (يتطلب بيانات اعتماد حقيقية): +عند تصحيح المزوّدين/النماذج الحقيقية (يتطلب بيانات اعتماد حقيقية): -- المجموعة الحية (فحوصات النماذج + أدوات/صور Gateway): `pnpm test:live` -- استهدف ملفًا حيًا واحدًا بهدوء: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- مجموعة Live (استقصاءات النماذج + أدوات Gateway/الصور): `pnpm test:live` +- استهدف ملف live واحدًا بهدوء: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -نصيحة: عندما تحتاج فقط إلى حالة فشل واحدة، ففضّل تضييق الاختبارات الحية عبر متغيرات البيئة الخاصة بقائمة السماح الموصوفة أدناه. +نصيحة: عندما تحتاج فقط إلى حالة فاشلة واحدة، ففضّل تضييق اختبارات live عبر متغيرات البيئة الخاصة بقائمة السماح الموصوفة أدناه. -## المشغّلات الخاصة بـ QA +## مشغّلات خاصة بـ QA -توجد هذه الأوامر بجانب مجموعات الاختبار الرئيسية عندما تحتاج إلى واقعية QA-lab: +تأتي هذه الأوامر إلى جانب مجموعات الاختبار الرئيسية عندما تحتاج إلى واقعية qa-lab: - `pnpm openclaw qa suite` - - يشغّل سيناريوهات QA المدعومة من المستودع مباشرة على المضيف. - - يشغّل عدة سيناريوهات محددة بالتوازي افتراضيًا مع عمّال Gateway معزولين، حتى 64 عاملًا أو بعدد السيناريوهات المحددة. استخدم `--concurrency ` لضبط عدد العمال، أو `--concurrency 1` للمسار التسلسلي الأقدم. + - يشغّل سيناريوهات QA المعتمدة على المستودع مباشرة على المضيف. + - يشغّل عدة سيناريوهات محددة بالتوازي افتراضيًا مع عمّال Gateway معزولين، حتى 64 عاملًا أو عدد السيناريوهات المحدد. استخدم `--concurrency ` لضبط عدد العمال، أو `--concurrency 1` للمسار التسلسلي الأقدم. - `pnpm openclaw qa suite --runner multipass` - - يشغّل مجموعة QA نفسها داخل آلة Multipass Linux افتراضية مؤقتة. - - يحتفظ بسلوك اختيار السيناريو نفسه كما في `qa suite` على المضيف. - - يعيد استخدام أعلام اختيار المزوّد/النموذج نفسها الخاصة بـ `qa suite`. - - تعيد التشغيلات الحية تمرير مدخلات مصادقة QA المدعومة والعملية للضيف: - مفاتيح المزوّد المعتمدة على env، ومسار إعداد مزوّد QA الحي، و `CODEX_HOME` عند وجوده. - - يجب أن تبقى مجلدات الإخراج تحت جذر المستودع حتى يتمكن الضيف من الكتابة مرة أخرى عبر مساحة العمل المركّبة. - - يكتب تقرير + ملخص QA العاديين بالإضافة إلى سجلات Multipass تحت + - يشغّل مجموعة QA نفسها داخل آلة افتراضية Linux مؤقتة عبر Multipass. + - يحتفظ بسلوك اختيار السيناريو نفسه الموجود في `qa suite` على المضيف. + - يعيد استخدام علامات اختيار المزوّد/النموذج نفسها الخاصة بـ `qa suite`. + - تمرّر عمليات التشغيل live مدخلات مصادقة QA المدعومة والعملية للضيف: + مفاتيح المزوّد المعتمدة على env، ومسار إعداد مزوّد QA live، و`CODEX_HOME` عند وجوده. + - يجب أن تبقى أدلة الإخراج تحت جذر المستودع حتى يتمكن الضيف من الكتابة مرة أخرى عبر مساحة العمل المركبة. + - يكتب تقرير QA والملخّص المعتادين بالإضافة إلى سجلات Multipass ضمن `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - يبدأ موقع QA المدعوم بـ Docker لأعمال QA بأسلوب المشغّل. - `pnpm openclaw qa matrix` - - يشغّل مسار Matrix QA الحي مقابل خادم Tuwunel منزلي مؤقت ومدعوم بـ Docker. - - يوفّر ثلاثة مستخدمين مؤقتين لـ Matrix (`driver` و `sut` و `observer`) بالإضافة إلى غرفة خاصة واحدة، ثم يبدأ عنصر Gateway فرعي لـ QA باستخدام Matrix Plugin الحقيقي كوسيلة نقل SUT. - - يستخدم صورة Tuwunel المستقرة المثبتة `ghcr.io/matrix-construct/tuwunel:v1.5.1` افتراضيًا. تجاوزها باستخدام `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` عندما تحتاج إلى اختبار صورة مختلفة. - - يدعم Matrix حاليًا فقط `--credential-source env` لأن المسار يوفّر مستخدمين مؤقتين محليًا. - - يكتب تقرير Matrix QA وملخصًا وقطعة observed-events تحت `.artifacts/qa-e2e/...`. + - يشغّل مسار Matrix live QA مقابل خادوم منزلي Tuwunel مؤقت ومدعوم بـ Docker. + - مضيف QA هذا مخصّص للمستودع/التطوير فقط حاليًا. تثبيتات OpenClaw المعبأة لا تشحن `qa-lab`، لذا فهي لا تعرض `openclaw qa`. + - تقوم نسخ المستودع بتحميل المشغّل المضمّن مباشرة؛ ولا حاجة إلى خطوة تثبيت Plugin منفصلة. + - يوفّر ثلاثة مستخدمي Matrix مؤقتين (`driver` و`sut` و`observer`) بالإضافة إلى غرفة خاصة واحدة، ثم يبدأ ابن QA Gateway مع Plugin Matrix الحقيقي بوصفه نقل SUT. + - يستخدم صورة Tuwunel المستقرة المثبتة `ghcr.io/matrix-construct/tuwunel:v1.5.1` افتراضيًا. تجاوزها عبر `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` عندما تحتاج إلى اختبار صورة مختلفة. + - لا يوفّر Matrix علامات مصدر بيانات اعتماد مشتركة لأن المسار يوفّر مستخدمين مؤقتين محليًا. + - يكتب تقرير Matrix QA وملخّصًا وأثرًا للأحداث المرصودة ضمن `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - يشغّل مسار Telegram QA الحي مقابل مجموعة خاصة حقيقية باستخدام رمزي bot الخاصين بـ driver و SUT من env. - - يتطلب `OPENCLAW_QA_TELEGRAM_GROUP_ID` و `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` و `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. يجب أن يكون معرّف المجموعة هو معرّف دردشة Telegram رقميًا. - - يدعم `--credential-source convex` لبيانات الاعتماد المشتركة المجمّعة. استخدم وضع env افتراضيًا، أو اضبط `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` لاختيار عقود الإعارة المجمّعة. - - يتطلب botين مختلفين في المجموعة الخاصة نفسها، على أن يعرّض bot الخاص بـ SUT اسم مستخدم Telegram. - - من أجل ملاحظة مستقرة بين bot وآخر، فعّل وضع Bot-to-Bot Communication Mode في `@BotFather` لكلا botين وتأكد من أن bot الخاص بـ driver يمكنه ملاحظة حركة bot داخل المجموعة. - - يكتب تقرير Telegram QA وملخصًا وقطعة observed-messages تحت `.artifacts/qa-e2e/...`. + - يشغّل مسار Telegram live QA مقابل مجموعة خاصة حقيقية باستخدام رموز bot الخاصة بـ driver وSUT من env. + - يتطلب `OPENCLAW_QA_TELEGRAM_GROUP_ID` و`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` و`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. يجب أن يكون معرّف المجموعة هو معرّف دردشة Telegram رقمي. + - يدعم `--credential-source convex` لبيانات الاعتماد المشتركة المجمّعة. استخدم وضع env افتراضيًا، أو اضبط `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` للاشتراك في عقود التأجير المجمّعة. + - يتطلب botين مختلفين داخل المجموعة الخاصة نفسها، مع كشف bot الخاص بـ SUT لاسم مستخدم Telegram. + - للحصول على رصد مستقر بين bot وbot، فعّل وضع التواصل بين Bot-to-Bot في `@BotFather` لكلا botين وتأكد من أن bot الخاص بـ driver يستطيع رصد حركة bot ضمن المجموعة. + - يكتب تقرير Telegram QA وملخّصًا وأثر الرسائل المرصودة ضمن `.artifacts/qa-e2e/...`. -تشارك مسارات النقل الحية عقدًا معياريًا واحدًا حتى لا تنحرف وسائل النقل الجديدة: +تشترك مسارات النقل live في عقد قياسي واحد حتى لا تنحرف عمليات النقل الجديدة: -يبقى `qa-channel` مجموعة QA تركيبية واسعة وليس جزءًا من مصفوفة تغطية النقل الحي. +يبقى `qa-channel` مجموعة QA الاصطناعية الواسعة وليس جزءًا من مصفوفة تغطية النقل live. -| المسار | Canary | بوابة الإشارة | حظر قائمة السماح | رد على المستوى الأعلى | استئناف بعد إعادة التشغيل | متابعة الخيط | عزل الخيط | ملاحظة التفاعلات | أمر المساعدة | -| ------ | ------ | ------------- | ---------------- | ---------------------- | ------------------------- | ------------ | ---------- | ---------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| المسار | Canary | تقييد الإشارة | حظر قائمة السماح | رد على المستوى الأعلى | استئناف بعد إعادة التشغيل | متابعة السلسلة | عزل السلسلة | رصد التفاعلات | أمر المساعدة | +| ------ | ------ | -------------- | ---------------- | ---------------------- | ------------------------- | -------------- | ------------ | -------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -### بيانات اعتماد Telegram المشتركة عبر Convex (v1) +### بيانات اعتماد Telegram المشتركة عبر Convex (الإصدار v1) -عندما يكون `--credential-source convex` (أو `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) مفعّلًا لـ -`openclaw qa telegram`، يحصل QA lab على إعارة حصرية من مجموعة مدعومة بـ Convex، ويرسل Heartbeat -لتلك الإعارة أثناء تشغيل المسار، ويحرّر الإعارة عند الإيقاف. +عندما يكون `--credential-source convex` (أو `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) مفعّلًا من أجل +`openclaw qa telegram`، يحصل QA lab على عقد تأجير حصري من مجموعة مدعومة بـ Convex، ويرسل Heartbeat +لهذا العقد أثناء تشغيل المسار، ثم يحرّر العقد عند الإيقاف. -هيكل مشروع Convex المرجعي: +مرجع هيكل مشروع Convex: - `qa/convex-credential-broker/` @@ -104,26 +106,26 @@ x-i18n: - `OPENCLAW_QA_CONVEX_SITE_URL` (على سبيل المثال `https://your-deployment.convex.site`) - سر واحد للدور المحدد: - - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` للدور `maintainer` - - `OPENCLAW_QA_CONVEX_SECRET_CI` للدور `ci` + - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` من أجل `maintainer` + - `OPENCLAW_QA_CONVEX_SECRET_CI` من أجل `ci` - اختيار دور بيانات الاعتماد: - CLI: `--credential-role maintainer|ci` - - القيمة الافتراضية في env: `OPENCLAW_QA_CREDENTIAL_ROLE` (القيمة الافتراضية `maintainer`) + - الافتراضي عبر env: `OPENCLAW_QA_CREDENTIAL_ROLE` (الافتراضي `maintainer`) متغيرات env الاختيارية: -- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (القيمة الافتراضية `1200000`) -- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (القيمة الافتراضية `30000`) -- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (القيمة الافتراضية `90000`) -- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (القيمة الافتراضية `15000`) -- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (القيمة الافتراضية `/qa-credentials/v1`) -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (معرّف تتبع اختياري) -- يسمح `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` بعناوين URL الخاصة بـ Convex من نوع `http://` على loopback لأغراض التطوير المحلي فقط. +- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (الافتراضي `1200000`) +- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (الافتراضي `30000`) +- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (الافتراضي `90000`) +- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (الافتراضي `15000`) +- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (الافتراضي `/qa-credentials/v1`) +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (معرّف تتبّع اختياري) +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` يسمح بعناوين Convex من نوع `http://` على local loopback للتطوير المحلي فقط. -يجب أن يستخدم `OPENCLAW_QA_CONVEX_SITE_URL` البروتوكول `https://` في التشغيل العادي. +يجب أن يستخدم `OPENCLAW_QA_CONVEX_SITE_URL` الصيغة `https://` في التشغيل العادي. -تتطلب أوامر الإدارة الخاصة بالمشرفين (إضافة/إزالة/سرد المجموعة) -`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` تحديدًا. +تتطلب أوامر الإدارة الخاصة بالمشرفين (إضافة/إزالة/سرد المجموعة) تحديدًا +`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. مساعدات CLI للمشرفين: @@ -133,14 +135,14 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -استخدم `--json` للحصول على خرج قابل للقراءة آليًا في السكربتات وأدوات CI. +استخدم `--json` لإخراج قابل للقراءة الآلية في السكربتات وأدوات CI. -عقد نقاط النهاية الافتراضي (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +عقد نقطة النهاية الافتراضي (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - الطلب: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - النجاح: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - الاستنفاد/قابل لإعادة المحاولة: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - نفاد المجموعة/قابل لإعادة المحاولة: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - الطلب: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - النجاح: `{ status: "ok" }` (أو `2xx` فارغ) @@ -153,7 +155,7 @@ pnpm openclaw qa credentials remove --credential-id - `POST /admin/remove` (سر maintainer فقط) - الطلب: `{ credentialId, actorId }` - النجاح: `{ status: "ok", changed, credential }` - - حماية الإعارة النشطة: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - حماية العقد النشط: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (سر maintainer فقط) - الطلب: `{ kind?, status?, includePayload?, limit? }` - النجاح: `{ status: "ok", credentials, count }` @@ -161,55 +163,60 @@ pnpm openclaw qa credentials remove --credential-id شكل الحمولة لنوع Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- يجب أن يكون `groupId` سلسلة تمثل معرّف دردشة Telegram رقميًا. -- يتحقق `admin/add` من هذا الشكل لـ `kind: "telegram"` ويرفض الحمولة غير الصحيحة. +- يجب أن يكون `groupId` سلسلة معرّف دردشة Telegram رقمية. +- تتحقق `admin/add` من هذا الشكل عند `kind: "telegram"` وترفض الحمولة غير الصحيحة. ### إضافة قناة إلى QA -تتطلب إضافة قناة إلى نظام QA المكتوب بـ markdown شيئين فقط بالضبط: +إضافة قناة إلى نظام QA المبني على Markdown تتطلب أمرين فقط بالضبط: -1. محول نقل للقناة. +1. مُهايئ نقل للقناة. 2. حزمة سيناريوهات تمارس عقد القناة. -لا تضف مشغّل QA خاصًا بالقناة عندما يمكن لمشغّل `qa-lab` المشترك -أن يمتلك التدفق. +لا تضف جذر أوامر QA جديدًا على المستوى الأعلى عندما يمكن لمضيف `qa-lab` المشترك +امتلاك هذا التدفق. -يمتلك `qa-lab` الآليات المشتركة: +يمتلك `qa-lab` آليات المضيف المشتركة: +- جذر أوامر `openclaw qa` - بدء المجموعة وإنهاؤها -- تزامن العمال -- كتابة القطع -- توليد التقارير +- توازي العمال +- كتابة الآثار +- إنشاء التقارير - تنفيذ السيناريوهات -- الأسماء المستعارة التوافقية لسيناريوهات `qa-channel` الأقدم +- أسماء التوافق البديلة لسيناريوهات `qa-channel` الأقدم -يمتلك محول القناة عقد النقل: +تمتلك Plugins المشغّلات عقد النقل: -- كيفية ضبط Gateway لذلك النقل +- كيفية تركيب `openclaw qa ` تحت جذر `qa` المشترك +- كيفية إعداد Gateway لهذا النقل - كيفية التحقق من الجاهزية - كيفية حقن الأحداث الواردة -- كيفية ملاحظة الرسائل الصادرة +- كيفية رصد الرسائل الصادرة - كيفية كشف النصوص المنسوخة وحالة النقل المطبّعة - كيفية تنفيذ الإجراءات المدعومة بالنقل - كيفية التعامل مع إعادة الضبط أو التنظيف الخاص بالنقل الحد الأدنى لاعتماد قناة جديدة هو: -1. تنفيذ محول النقل على واجهة `qa-lab` المشتركة. -2. تسجيل المحول في سجل النقل. -3. إبقاء الآليات الخاصة بالنقل داخل المحول أو حزام القناة. -4. تأليف أو تكييف سيناريوهات markdown تحت `qa/scenarios/`. -5. استخدام مساعدات السيناريو العامة للسيناريوهات الجديدة. -6. الإبقاء على الأسماء المستعارة التوافقية الحالية عاملة ما لم يكن المستودع يقوم بترحيل مقصود. +1. إبقاء `qa-lab` مالكًا لجذر `qa` المشترك. +2. تنفيذ مشغّل النقل على واجهة مضيف `qa-lab` المشتركة. +3. إبقاء الآليات الخاصة بالنقل داخل Plugin المشغّل أو أداة القناة. +4. تركيب المشغّل كـ `openclaw qa ` بدلًا من تسجيل جذر أوامر منافس. + يجب أن تعلن Plugins المشغّلات `qaRunners` في `openclaw.plugin.json` وأن تصدّر مصفوفة `qaRunnerCliRegistrations` مطابقة من `runtime-api.ts`. + اجعل `runtime-api.ts` خفيفًا؛ يجب أن يبقى CLI الكسول وتنفيذ المشغّل خلف نقاط دخول منفصلة. +5. تأليف أو تكييف سيناريوهات Markdown تحت `qa/scenarios/`. +6. استخدام مساعدات السيناريو العامة للسيناريوهات الجديدة. +7. إبقاء أسماء التوافق البديلة الحالية عاملة ما لم يكن المستودع يجري ترحيلًا مقصودًا. قاعدة القرار صارمة: - إذا أمكن التعبير عن السلوك مرة واحدة في `qa-lab`، فضعه في `qa-lab`. -- إذا كان السلوك يعتمد على نقل قناة واحدة، فأبقِه في ذلك المحول أو حزام Plugin. -- إذا احتاج السيناريو إلى قدرة جديدة يمكن لأكثر من قناة استخدامها، فأضف مساعدًا عامًا بدلًا من فرع خاص بقناة في `suite.ts`. -- إذا كان السلوك ذا معنى فقط لنقل واحد، فأبقِ السيناريو خاصًا بذلك النقل واجعل ذلك واضحًا في عقد السيناريو. +- إذا كان السلوك يعتمد على نقل قناة واحدة، فأبقِه في Plugin ذلك المشغّل أو أداة Plugin. +- إذا احتاج السيناريو إلى قدرة جديدة يمكن لأكثر من قناة استخدامها، فأضف مساعدًا عامًا بدلًا من فرع خاص بقناة داخل `suite.ts`. +- إذا كان السلوك ذا معنى فقط لنقل واحد، فأبقِ السيناريو خاصًا بذلك النقل واجعل ذلك صريحًا في عقد السيناريو. -الأسماء العامة المفضلة للمساعدات في السيناريوهات الجديدة هي: +أسماء المساعدات العامة المفضلة للسيناريوهات الجديدة هي: - `waitForTransportReady` - `waitForChannelReady` @@ -224,7 +231,7 @@ pnpm openclaw qa credentials remove --credential-id - `formatTransportTranscript` - `resetTransport` -تبقى الأسماء المستعارة التوافقية متاحة للسيناريوهات الحالية، بما في ذلك: +تبقى أسماء التوافق البديلة متاحة للسيناريوهات الحالية، بما في ذلك: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -232,102 +239,102 @@ pnpm openclaw qa credentials remove --credential-id - `formatConversationTranscript` - `resetBus` -يجب أن تستخدم الأعمال الجديدة الخاصة بالقنوات أسماء المساعدات العامة. -توجد الأسماء المستعارة التوافقية لتجنب ترحيل شامل دفعة واحدة، وليست نموذجًا +يجب أن تستخدم أعمال القنوات الجديدة أسماء المساعدات العامة. +توجد أسماء التوافق البديلة لتجنّب ترحيل شامل في يوم واحد، وليس لتكون النموذج لتأليف السيناريوهات الجديدة. ## مجموعات الاختبار (ما الذي يعمل وأين) -فكّر في المجموعات على أنها "زيادة في الواقعية" (وزيادة في عدم الاستقرار/التكلفة): +فكّر في المجموعات باعتبارها «واقعية متزايدة» (ومعها زيادة في عدم الاستقرار/الكلفة): ### Unit / integration (الافتراضي) - الأمر: `pnpm test` -- الإعداد: عشر تشغيلات shards متسلسلة (`vitest.full-*.config.ts`) عبر مشاريع Vitest المحددة الموجودة -- الملفات: مخزونات core/unit تحت `src/**/*.test.ts` و `packages/**/*.test.ts` و `test/**/*.test.ts` واختبارات `ui` الخاصة بـ node والمسموح بها والمغطاة بواسطة `vitest.unit.config.ts` +- الإعداد: عشر عمليات shard متسلسلة (`vitest.full-*.config.ts`) فوق مشاريع Vitest المقيّدة الحالية +- الملفات: جرد core/unit تحت `src/**/*.test.ts` و`packages/**/*.test.ts` و`test/**/*.test.ts` واختبارات `ui` الخاصة بـ node والمسموح بها والمشمولة بواسطة `vitest.unit.config.ts` - النطاق: - اختبارات unit خالصة - - اختبارات integration داخل العملية (مصادقة gateway، والتوجيه، والأدوات، والتحليل، والإعداد) + - اختبارات تكامل داخل العملية (مصادقة Gateway، والتوجيه، والأدوات، والتحليل، والإعداد) - اختبارات انحدار حتمية للأخطاء المعروفة - التوقعات: - تعمل في CI - لا تتطلب مفاتيح حقيقية - يجب أن تكون سريعة ومستقرة - ملاحظة المشاريع: - - التشغيل غير المستهدف لـ `pnpm test` يشغّل الآن أحد عشر إعداد shard أصغر (`core-unit-src` و `core-unit-security` و `core-unit-ui` و `core-unit-support` و `core-support-boundary` و `core-contracts` و `core-bundled` و `core-runtime` و `agentic` و `auto-reply` و `extensions`) بدلًا من عملية root-project أصلية واحدة ضخمة. هذا يقلل ذروة RSS على الأجهزة المحمّلة ويتجنب أن تؤدي أعمال auto-reply/extension إلى تجويع المجموعات غير المرتبطة. - - لا يزال `pnpm test --watch` يستخدم رسم المشاريع الأصلي لـ root `vitest.config.ts`، لأن حلقة watch متعددة الـ shards غير عملية. - - `pnpm test` و `pnpm test:watch` و `pnpm test:perf:imports` تمرّر أهداف الملفات/المجلدات الصريحة عبر المسارات المحددة أولًا، لذلك فإن `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` يتجنب تكلفة بدء التشغيل الكاملة لـ root project. - - يقوم `pnpm test:changed` بتوسيع مسارات git المتغيرة إلى المسارات المحددة نفسها عندما يقتصر الفرق على ملفات source/test القابلة للتوجيه؛ أما تعديلات config/setup فتعود إلى إعادة تشغيل root-project الواسعة. - - اختبارات unit الخفيفة من حيث الاستيراد من agents و commands و plugins ومساعدات auto-reply و `plugin-sdk` والمناطق المشابهة من الأدوات الخالصة تمر عبر مسار `unit-fast`، الذي يتجاوز `test/setup-openclaw-runtime.ts`؛ بينما تبقى الملفات ذات الحالة/الكثيفة وقت التشغيل على المسارات الحالية. - - تُربط أيضًا ملفات source المساعدة المحددة في `plugin-sdk` و `commands` في تشغيل changed-mode باختبارات sibling صريحة في تلك المسارات الخفيفة، بحيث تتجنب تعديلات المساعدات إعادة تشغيل المجموعة الثقيلة الكاملة لذلك الدليل. - - يملك `auto-reply` الآن ثلاث مجموعات مخصصة: مساعدات core العلوية، واختبارات integration العلوية `reply.*`، والشجرة الفرعية `src/auto-reply/reply/**`. هذا يُبقي أثقل أعمال harness الخاصة بالردود بعيدًا عن اختبارات status/chunk/token الرخيصة. + - أصبح `pnpm test` غير المستهدف يشغّل الآن أحد عشر إعداد shard أصغر (`core-unit-src` و`core-unit-security` و`core-unit-ui` و`core-unit-support` و`core-support-boundary` و`core-contracts` و`core-bundled` و`core-runtime` و`agentic` و`auto-reply` و`extensions`) بدلًا من عملية جذر مشروع أصلية واحدة ضخمة. هذا يقلّل ذروة RSS على الأجهزة المزدحمة ويمنع أعمال `auto-reply`/الامتدادات من تجويع المجموعات غير المرتبطة. + - ما يزال `pnpm test --watch` يستخدم رسم المشاريع في `vitest.config.ts` الخاص بالجذر الأصلي، لأن حلقة مراقبة متعددة الشظايا ليست عملية. + - أصبح `pnpm test` و`pnpm test:watch` و`pnpm test:perf:imports` يوجّهون أهداف الملفات/الأدلة الصريحة عبر المسارات المقيّدة أولًا، لذا فإن `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` يتجنب كلفة بدء تشغيل مشروع الجذر الكامل. + - يقوم `pnpm test:changed` بتوسيع مسارات git المتغيرة إلى المسارات المقيّدة نفسها عندما يلمس الفرق فقط ملفات مصدر/اختبار قابلة للتوجيه؛ أما تعديلات الإعداد/التهيئة فما تزال تعود إلى إعادة تشغيل واسعة لمشروع الجذر. + - يتم توجيه اختبارات unit خفيفة الاستيراد من الوكلاء، والأوامر، وPlugins، ومساعدات `auto-reply`، و`plugin-sdk`، والمناطق النفعية الخالصة المشابهة عبر مسار `unit-fast`، الذي يتخطى `test/setup-openclaw-runtime.ts`؛ بينما تبقى الملفات الثقيلة من حيث الحالة/وقت التشغيل على المسارات الحالية. + - كما يتم تعيين بعض ملفات المصدر المساعدة المحددة في `plugin-sdk` و`commands` في تشغيل وضع التغييرات إلى اختبارات شقيقة صريحة في تلك المسارات الخفيفة، بحيث تتجنب تعديلات المساعدات إعادة تشغيل المجموعة الثقيلة الكاملة لذلك الدليل. + - أصبح لدى `auto-reply` الآن ثلاث حاويات مخصصة: مساعدات core من المستوى الأعلى، واختبارات التكامل `reply.*` من المستوى الأعلى، والشجرة الفرعية `src/auto-reply/reply/**`. وهذا يبقي أثقل أعمال أدوات `reply` بعيدًا عن اختبارات الحالة/الأجزاء/الرموز الأرخص. - ملاحظة المشغّل المضمّن: - - عندما تغيّر مدخلات اكتشاف أدوات الرسائل أو سياق وقت التشغيل الخاص بـ Compaction، - حافظ على مستويي التغطية كليهما. - - أضف اختبارات انحدار مركزة للمساعدات الخاصة بحدود التوجيه/التطبيع الخالصة. - - وحافظ أيضًا على سلامة مجموعات integration الخاصة بالمشغّل المضمّن: - `src/agents/pi-embedded-runner/compact.hooks.test.ts`، + - عندما تغيّر مدخلات اكتشاف أدوات الرسائل أو سياق وقت تشغيل Compaction، + فحافظ على مستويي التغطية كليهما. + - أضف اختبارات انحدار مركّزة للمساعدات الخاصة بحدود التوجيه/التطبيع الخالصة. + - وحافظ أيضًا على سلامة مجموعات تكامل المشغّل المضمّن: + `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`، و `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - تتحقق هذه المجموعات من أن المعرّفات المحددة وسلوك Compaction لا يزالان يتدفقان + - تتحقق هذه المجموعات من أن المعرّفات المقيّدة وسلوك Compaction ما يزالان يتدفقان عبر المسارات الحقيقية `run.ts` / `compact.ts`؛ ولا تُعد اختبارات المساعدات وحدها - بديلًا كافيًا عن مسارات integration هذه. -- ملاحظة الـ pool: + بديلًا كافيًا عن مسارات التكامل تلك. +- ملاحظة التجميع: - أصبح إعداد Vitest الأساسي يستخدم `threads` افتراضيًا. - - كما يثبّت إعداد Vitest المشترك `isolate: false` ويستخدم المشغّل غير المعزول عبر إعدادات root projects و e2e و live. - - يحتفظ مسار root UI بإعداد `jsdom` والمُحسِّن الخاص به، لكنه يعمل الآن أيضًا على المشغّل المشترك غير المعزول. - - يرث كل shard في `pnpm test` القيم الافتراضية نفسها `threads` + `isolate: false` من إعداد Vitest المشترك. - - يضيف مشغّل `scripts/run-vitest.mjs` المشترك الآن أيضًا `--no-maglev` افتراضيًا لعمليات Node الفرعية الخاصة بـ Vitest لتقليل تذبذب الترجمة في V8 أثناء التشغيلات المحلية الكبيرة. اضبط `OPENCLAW_VITEST_ENABLE_MAGLEV=1` إذا كنت بحاجة إلى المقارنة مع سلوك V8 القياسي. + - كما يثبّت إعداد Vitest المشترك أيضًا `isolate: false` ويستخدم المشغّل غير المعزول عبر مشاريع الجذر وتهيئات e2e وlive. + - يحتفظ مسار UI الخاص بالجذر بإعداد `jsdom` والمُحسّن الخاص به، لكنه يعمل الآن أيضًا على المشغّل المشترك غير المعزول. + - ترث كل shard في `pnpm test` القيم الافتراضية نفسها `threads` + `isolate: false` من إعداد Vitest المشترك. + - يضيف مشغّل `scripts/run-vitest.mjs` المشترك الآن أيضًا `--no-maglev` افتراضيًا لعمليات Node الابنة الخاصة بـ Vitest لتقليل تقلبات ترجمة V8 أثناء عمليات التشغيل المحلية الكبيرة. اضبط `OPENCLAW_VITEST_ENABLE_MAGLEV=1` إذا كنت بحاجة إلى المقارنة مع سلوك V8 الافتراضي. - ملاحظة التكرار المحلي السريع: - - يمر `pnpm test:changed` عبر المسارات المحددة عندما تتطابق المسارات المتغيرة بوضوح مع مجموعة أصغر. - - يحتفظ `pnpm test:max` و `pnpm test:changed:max` بسلوك التوجيه نفسه، فقط مع حد أعلى أكبر للعمال. - - أصبح التحجيم التلقائي المحلي للعمال محافظًا عمدًا الآن، كما أنه يتراجع عندما يكون متوسط حمل المضيف مرتفعًا أصلًا، بحيث تتسبب تشغيلات Vitest المتزامنة المتعددة بضرر أقل افتراضيًا. - - يضع إعداد Vitest الأساسي ملفات المشاريع/الإعداد كـ `forceRerunTriggers` حتى تبقى إعادة التشغيل في changed-mode صحيحة عند تغيّر توصيلات الاختبار. - - يحتفظ الإعداد بتمكين `OPENCLAW_VITEST_FS_MODULE_CACHE` على المضيفين المدعومين؛ اضبط `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` إذا كنت تريد موقع cache صريحًا واحدًا لأغراض profiling المباشر. + - يوجّه `pnpm test:changed` عبر المسارات المقيّدة عندما تطابق المسارات المتغيرة مجموعة أصغر بشكل نظيف. + - يحتفظ `pnpm test:max` و`pnpm test:changed:max` بسلوك التوجيه نفسه، فقط مع حد أعلى أكبر للعمال. + - أصبح التوسّع التلقائي المحلي للعمال محافظًا عمدًا الآن، كما يتراجع أيضًا عندما يكون متوسط حمل المضيف مرتفعًا أصلًا، بحيث تسبب عمليات Vitest المتزامنة المتعددة ضررًا أقل افتراضيًا. + - يضع إعداد Vitest الأساسي ملفات المشاريع/الإعداد كـ `forceRerunTriggers` حتى تبقى إعادة التشغيل في وضع التغييرات صحيحة عندما تتغير توصيلات الاختبار. + - يحتفظ الإعداد بتمكين `OPENCLAW_VITEST_FS_MODULE_CACHE` على المضيفين المدعومين؛ اضبط `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` إذا أردت موقع ذاكرة مؤقتة صريحًا واحدًا لأغراض التحليل المباشر. - ملاحظة تصحيح الأداء: - - يفعّل `pnpm test:perf:imports` تقارير مدة الاستيراد في Vitest بالإضافة إلى خرج تفصيلي للاستيراد. - - يقيّد `pnpm test:perf:imports:changed` عرض profiling نفسه على الملفات المتغيرة منذ `origin/main`. -- يقارن `pnpm test:perf:changed:bench -- --ref ` بين `test:changed` الموجّه ومسار root-project الأصلي لذلك الفرق الملتزم، ويطبع زمن التنفيذ بالإضافة إلى macOS max RSS. -- يقيّم `pnpm test:perf:changed:bench -- --worktree` الشجرة المتسخة الحالية بتمرير قائمة الملفات المتغيرة عبر `scripts/test-projects.mjs` وإعداد root Vitest. - - يكتب `pnpm test:perf:profile:main` ملف تعريف CPU للخيط الرئيسي لزمن بدء Vitest/Vite وكلفة التحويل. - - يكتب `pnpm test:perf:profile:runner` ملفات تعريف CPU+heap الخاصة بالمشغّل لمجموعة unit مع تعطيل التوازي على مستوى الملفات. + - يفعّل `pnpm test:perf:imports` تقارير مدة الاستيراد في Vitest بالإضافة إلى مخرجات تفصيل الاستيراد. + - يقيّد `pnpm test:perf:imports:changed` عرض التحليل نفسه على الملفات المتغيرة منذ `origin/main`. +- يقارن `pnpm test:perf:changed:bench -- --ref ` بين `test:changed` الموجّهة ومسار مشروع الجذر الأصلي لذلك الفرق الملتزم ويطبع زمن التنفيذ بالإضافة إلى أقصى RSS على macOS. +- يقيس `pnpm test:perf:changed:bench -- --worktree` الشجرة الحالية المتسخة عبر توجيه قائمة الملفات المتغيرة من خلال `scripts/test-projects.mjs` وإعداد Vitest الخاص بجذر المشروع. + - يكتب `pnpm test:perf:profile:main` ملف تعريف CPU للخيط الرئيسي لأعباء بدء تشغيل Vitest/Vite والتحويل. + - يكتب `pnpm test:perf:profile:runner` ملفات تعريف CPU+heap للمشغّل لمجموعة unit مع تعطيل التوازي على مستوى الملفات. -### E2E (اختبار smoke لـ gateway) +### E2E (اختبار Gateway دخاني) - الأمر: `pnpm test:e2e` - الإعداد: `vitest.e2e.config.ts` -- الملفات: `src/**/*.e2e.test.ts` و `test/**/*.e2e.test.ts` +- الملفات: `src/**/*.e2e.test.ts` و`test/**/*.e2e.test.ts` - القيم الافتراضية لوقت التشغيل: - - يستخدم `threads` في Vitest مع `isolate: false`، بما يتوافق مع بقية المستودع. - - يستخدم عمالًا متكيفين (CI: حتى 2، محليًا: 1 افتراضيًا). - - يعمل في الوضع الصامت افتراضيًا لتقليل كلفة I/O في الطرفية. + - يستخدم `threads` في Vitest مع `isolate: false`، بما يطابق بقية المستودع. + - يستخدم عمالًا تكيفيين (في CI: حتى 2، ومحليًا: 1 افتراضيًا). + - يعمل في الوضع الصامت افتراضيًا لتقليل كلفة إدخال/إخراج الطرفية. - تجاوزات مفيدة: - `OPENCLAW_E2E_WORKERS=` لفرض عدد العمال (بحد أقصى 16). - - `OPENCLAW_E2E_VERBOSE=1` لإعادة تفعيل خرج الطرفية التفصيلي. + - `OPENCLAW_E2E_VERBOSE=1` لإعادة تفعيل مخرجات الطرفية التفصيلية. - النطاق: - - سلوك gateway من طرف إلى طرف متعدد النسخ + - سلوك Gateway الشامل من النهاية إلى النهاية متعدد النسخ - أسطح WebSocket/HTTP، واقتران Node، والشبكات الأثقل - التوقعات: - - تعمل في CI (عندما تكون مفعّلة في خط التنفيذ) - - لا تتطلب مفاتيح حقيقية - - تحتوي على أجزاء متحركة أكثر من اختبارات unit (وقد تكون أبطأ) + - يعمل في CI (عند تمكينه في خط الأنابيب) + - لا يتطلب مفاتيح حقيقية + - يحتوي على أجزاء متحركة أكثر من اختبارات unit (وقد يكون أبطأ) -### E2E: اختبار smoke للواجهة الخلفية OpenShell +### E2E: اختبار OpenShell الخلفي الدخاني - الأمر: `pnpm test:e2e:openshell` - الملف: `test/openshell-sandbox.e2e.test.ts` - النطاق: - - يبدأ OpenShell gateway معزولًا على المضيف عبر Docker + - يبدأ OpenShell Gateway معزولًا على المضيف عبر Docker - ينشئ sandbox من Dockerfile محلي مؤقت - - يختبر الواجهة الخلفية OpenClaw الخاصة بـ OpenShell عبر `sandbox ssh-config` + تنفيذ SSH الحقيقي - - يتحقق من سلوك نظام الملفات canonical البعيد عبر جسر sandbox fs + - يمارس الواجهة الخلفية OpenShell الخاصة بـ OpenClaw عبر `sandbox ssh-config` وSSH exec حقيقيين + - يتحقق من سلوك نظام الملفات القانوني عن بُعد عبر جسر نظام ملفات sandbox - التوقعات: - - اختيارية فقط؛ وليست جزءًا من التشغيل الافتراضي `pnpm test:e2e` - - تتطلب CLI محليًا لـ `openshell` بالإضافة إلى Docker daemon عامل - - تستخدم `HOME` / `XDG_CONFIG_HOME` معزولين، ثم تدمّر gateway و sandbox الخاصين بالاختبار + - اشتراك اختياري فقط؛ ليس جزءًا من تشغيل `pnpm test:e2e` الافتراضي + - يتطلب CLI محليًا لـ `openshell` بالإضافة إلى Docker daemon عامل + - يستخدم `HOME` / `XDG_CONFIG_HOME` معزولين، ثم يدمّر Gateway وsandbox الخاصين بالاختبار - تجاوزات مفيدة: - `OPENCLAW_E2E_OPENSHELL=1` لتمكين الاختبار عند تشغيل مجموعة e2e الأوسع يدويًا - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` للإشارة إلى ملف CLI ثنائي أو wrapper script غير افتراضي + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` للإشارة إلى ملف CLI ثنائي أو سكربت تغليف غير افتراضي ### Live (مزوّدون حقيقيون + نماذج حقيقية) @@ -336,113 +343,113 @@ pnpm openclaw qa credentials remove --credential-id - الملفات: `src/**/*.live.test.ts` - الافتراضي: **مفعّل** بواسطة `pnpm test:live` (يضبط `OPENCLAW_LIVE_TEST=1`) - النطاق: - - "هل يعمل هذا المزوّد/النموذج فعلًا _اليوم_ باستخدام بيانات اعتماد حقيقية؟" - - اكتشاف تغييرات تنسيق المزوّد، ومراوغات استدعاء الأدوات، ومشكلات المصادقة، وسلوك تحديد المعدل + - «هل يعمل هذا المزوّد/النموذج فعلًا _اليوم_ باستخدام بيانات اعتماد حقيقية؟» + - التقاط تغيّرات تنسيق المزوّد، وخصائص استدعاء الأدوات، ومشكلات المصادقة، وسلوك حدود المعدل - التوقعات: - - غير مستقرة بالنسبة إلى CI بطبيعتها (شبكات حقيقية، وسياسات مزوّد حقيقية، وحصص، وانقطاعات) - - تكلف مالًا / تستخدم حدود المعدل - - يُفضّل تشغيل مجموعات فرعية مضيقة بدلًا من "كل شيء" -- تعتمد التشغيلات الحية على `~/.profile` لالتقاط مفاتيح API الناقصة. -- افتراضيًا، لا تزال التشغيلات الحية تعزل `HOME` وتنسخ مواد config/auth إلى دليل home مؤقت خاص بالاختبار حتى لا تتمكن fixtures الخاصة بـ unit من تعديل `~/.openclaw` الحقيقي لديك. -- اضبط `OPENCLAW_LIVE_USE_REAL_HOME=1` فقط عندما تحتاج عمدًا إلى أن تستخدم الاختبارات الحية دليل home الحقيقي لديك. -- يستخدم `pnpm test:live` الآن وضعًا أكثر هدوءًا افتراضيًا: فهو يحتفظ بخرج التقدّم `[live] ...`، لكنه يخفي إشعار `~/.profile` الإضافي ويكتم سجلات bootstrap الخاصة بـ gateway وضجيج Bonjour. اضبط `OPENCLAW_LIVE_TEST_QUIET=0` إذا كنت تريد استعادة سجلات بدء التشغيل الكاملة. -- تدوير مفاتيح API (خاص بالمزوّد): اضبط `*_API_KEYS` بتنسيق comma/semicolon أو `*_API_KEY_1` و `*_API_KEY_2` (على سبيل المثال `OPENAI_API_KEYS` و `ANTHROPIC_API_KEYS` و `GEMINI_API_KEYS`) أو تجاوزًا لكل اختبار حي عبر `OPENCLAW_LIVE_*_KEY`؛ تعيد الاختبارات المحاولة عند استجابات تحديد المعدل. -- خرج التقدّم/Heartbeat: - - تصدر المجموعات الحية الآن أسطر التقدّم إلى stderr حتى تظهر مكالمات المزوّد الطويلة على أنها نشطة بوضوح حتى عندما يكون التقاط الطرفية في Vitest هادئًا. - - يعطّل `vitest.live.config.ts` اعتراض الطرفية في Vitest بحيث تُبث أسطر التقدّم الخاصة بالمزوّد/ gateway مباشرة أثناء التشغيلات الحية. - - اضبط Heartbeat الخاص بالنموذج المباشر باستخدام `OPENCLAW_LIVE_HEARTBEAT_MS`. - - اضبط Heartbeat الخاص بـ gateway/probe باستخدام `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - ليست مستقرة على CI بطبيعتها (شبكات حقيقية، سياسات مزوّدين حقيقية، حصص، انقطاعات) + - تكلّف مالًا / تستهلك حدود المعدل + - يفضَّل تشغيل مجموعات فرعية مقيّدة بدلًا من «كل شيء» +- تستورد عمليات live الملف `~/.profile` لالتقاط مفاتيح API الناقصة. +- افتراضيًا، ما تزال عمليات live تعزل `HOME` وتنسخ مواد الإعداد/المصادقة إلى home اختباري مؤقت حتى لا تتمكن تجهيزات unit من تعديل `~/.openclaw` الحقيقي لديك. +- اضبط `OPENCLAW_LIVE_USE_REAL_HOME=1` فقط عندما تحتاج عمدًا إلى أن تستخدم اختبارات live دليل home الحقيقي لديك. +- أصبح `pnpm test:live` الآن يستخدم وضعًا أكثر هدوءًا افتراضيًا: فهو يحتفظ بإخراج التقدم `[live] ...`، لكنه يخفي إشعار `~/.profile` الإضافي ويكتم سجلات إقلاع Gateway وضجيج Bonjour. اضبط `OPENCLAW_LIVE_TEST_QUIET=0` إذا أردت استعادة سجلات بدء التشغيل الكاملة. +- تدوير مفاتيح API (خاص بالمزوّد): اضبط `*_API_KEYS` بصيغة فاصلة/فاصلة منقوطة أو `*_API_KEY_1` و`*_API_KEY_2` (مثلًا `OPENAI_API_KEYS` و`ANTHROPIC_API_KEYS` و`GEMINI_API_KEYS`) أو استخدم تجاوزًا خاصًا بـ live عبر `OPENCLAW_LIVE_*_KEY`؛ تعيد الاختبارات المحاولة عند استجابات حد المعدل. +- مخرجات التقدم/Heartbeat: + - أصبحت مجموعات live الآن تصدر أسطر التقدم إلى stderr بحيث يظهر نشاط استدعاءات المزوّد الطويلة بوضوح حتى عندما يكون التقاط طرفية Vitest هادئًا. + - يعطّل `vitest.live.config.ts` اعتراض طرفية Vitest بحيث تتدفق أسطر تقدم المزوّد/Gateway مباشرة أثناء عمليات live. + - اضبط Heartbeat الخاص بالنموذج المباشر عبر `OPENCLAW_LIVE_HEARTBEAT_MS`. + - اضبط Heartbeat الخاص بـ Gateway/الاستقصاء عبر `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## أي مجموعة يجب أن أشغّل؟ استخدم جدول القرار هذا: -- تعديل المنطق/الاختبارات: شغّل `pnpm test` (و `pnpm test:coverage` إذا غيّرت الكثير) -- لمس شبكات gateway / بروتوكول WS / الاقتران: أضف `pnpm test:e2e` -- تصحيح "البوت الخاص بي متوقف" / الأعطال الخاصة بالمزوّد / استدعاء الأدوات: شغّل `pnpm test:live` مضيقًا +- عند تعديل المنطق/الاختبارات: شغّل `pnpm test` (و`pnpm test:coverage` إذا كنت قد غيّرت الكثير) +- عند لمس شبكات Gateway / بروتوكول WS / الاقتران: أضف `pnpm test:e2e` +- عند تصحيح «البوت الخاص بي متوقف» / حالات الفشل الخاصة بالمزوّد / استدعاء الأدوات: شغّل `pnpm test:live` بشكل مقيّد ## Live: مسح قدرات Android Node - الاختبار: `src/gateway/android-node.capabilities.live.test.ts` - السكربت: `pnpm android:test:integration` -- الهدف: استدعاء **كل أمر يتم الإعلان عنه حاليًا** بواسطة Android Node متصل والتحقق من سلوك عقد الأمر. +- الهدف: استدعاء **كل أمر معلَن عنه حاليًا** بواسطة Android Node متصل والتحقق من سلوك عقد الأوامر. - النطاق: - - إعداد يدوي/مسبق الشروط (المجموعة لا تثبّت التطبيق ولا تشغّله ولا تقترنه). - - تحقق `node.invoke` على مستوى gateway أمرًا بأمر من أجل Android Node المحدد. + - إعداد مسبق/يدوي (المجموعة لا تثبّت التطبيق أو تشغّله أو تقترنه). + - تحقق `node.invoke` في Gateway أمرًا بأمر لعقدة Android المحددة. - الإعداد المسبق المطلوب: - - أن يكون تطبيق Android متصلًا ومقترنًا بالفعل بـ gateway. + - تطبيق Android متصل بالفعل + مقترن مع Gateway. - إبقاء التطبيق في الواجهة الأمامية. - - منح الأذونات/الموافقة على الالتقاط للقدرات التي تتوقع نجاحها. + - منح الأذونات/موافقة الالتقاط للقدرات التي تتوقع نجاحها. - تجاوزات الهدف الاختيارية: - `OPENCLAW_ANDROID_NODE_ID` أو `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. - تفاصيل إعداد Android الكاملة: [تطبيق Android](/ar/platforms/android) -## Live: اختبار smoke للنموذج (مفاتيح profile) +## Live: اختبار النموذج الدخاني (مفاتيح الملف الشخصي) -تنقسم الاختبارات الحية إلى طبقتين حتى نتمكن من عزل الإخفاقات: +تنقسم اختبارات live إلى طبقتين حتى يمكننا عزل حالات الفشل: -- يخبرنا "النموذج المباشر" ما إذا كان المزوّد/النموذج قادرًا على الرد أساسًا بالمفتاح المعطى. -- يخبرنا "اختبار smoke لـ Gateway" ما إذا كان خط gateway+agent الكامل يعمل لهذا النموذج (sessions، والسجل، والأدوات، وسياسة sandbox، إلخ). +- يبيّن «النموذج المباشر» ما إذا كان المزوّد/النموذج قادرًا على الإجابة أصلًا باستخدام المفتاح المحدد. +- يبيّن «اختبار Gateway الدخاني» ما إذا كان خط Gateway+الوكيل الكامل يعمل لذلك النموذج (الجلسات، والسجل، والأدوات، وسياسة sandbox، وما إلى ذلك). -### الطبقة 1: إكمال مباشر للنموذج (من دون gateway) +### الطبقة 1: إكمال النموذج المباشر (من دون Gateway) - الاختبار: `src/agents/models.profiles.live.test.ts` - الهدف: - تعداد النماذج المكتشفة - استخدام `getApiKeyForModel` لاختيار النماذج التي لديك بيانات اعتماد لها - - تشغيل إكمال صغير لكل نموذج (واختبارات انحدار مستهدفة عند الحاجة) + - تشغيل إكمال صغير لكل نموذج (واختبارات الانحدار المستهدفة عند الحاجة) - كيفية التمكين: - - `pnpm test:live` (أو `OPENCLAW_LIVE_TEST=1` إذا كنت تستدعي Vitest مباشرة) -- اضبط `OPENCLAW_LIVE_MODELS=modern` (أو `all`، وهو اسم مستعار لـ modern) لتشغيل هذه المجموعة فعلًا؛ وإلا فسيتم تخطيها للحفاظ على تركيز `pnpm test:live` على اختبار smoke لـ gateway + - `pnpm test:live` (أو `OPENCLAW_LIVE_TEST=1` عند استدعاء Vitest مباشرة) +- اضبط `OPENCLAW_LIVE_MODELS=modern` (أو `all`، وهو اسم بديل لـ modern) لتشغيل هذه المجموعة فعلًا؛ وإلا فسيتم تخطيها لإبقاء `pnpm test:live` مركزًا على اختبار Gateway الدخاني - كيفية اختيار النماذج: - - `OPENCLAW_LIVE_MODELS=modern` لتشغيل قائمة السماح الحديثة (Opus/Sonnet 4.6+ و GPT-5.x + Codex و Gemini 3 و GLM 4.7 و MiniMax M2.7 و Grok 4) - - `OPENCLAW_LIVE_MODELS=all` هو اسم مستعار لقائمة السماح الحديثة + - `OPENCLAW_LIVE_MODELS=modern` لتشغيل قائمة السماح الحديثة (`Opus/Sonnet 4.6+`، و`GPT-5.x + Codex`، و`Gemini 3`، و`GLM 4.7`، و`MiniMax M2.7`، و`Grok 4`) + - `OPENCLAW_LIVE_MODELS=all` اسم بديل لقائمة السماح الحديثة - أو `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (قائمة سماح مفصولة بفواصل) - - تستخدم عمليات المسح modern/all حدًا منسقًا عالي الإشارة افتراضيًا؛ اضبط `OPENCLAW_LIVE_MAX_MODELS=0` لمسح حديث شامل أو رقمًا موجبًا لحد أصغر. + - تستخدم عمليات المسح modern/all حدًا منسقًا عالي الإشارة افتراضيًا؛ اضبط `OPENCLAW_LIVE_MAX_MODELS=0` لإجراء مسح modern شامل أو رقمًا موجبًا لحد أصغر. - كيفية اختيار المزوّدين: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (قائمة سماح مفصولة بفواصل) - من أين تأتي المفاتيح: - - افتراضيًا: من مخزن profile والبدائل الاحتياطية في env - - اضبط `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض **مخزن profile** فقط -- لماذا يوجد هذا: - - يفصل بين "واجهة API الخاصة بالمزوّد معطلة / المفتاح غير صالح" و "خط gateway agent معطل" - - يحتوي على اختبارات انحدار صغيرة ومعزولة (مثال: OpenAI Responses/Codex Responses reasoning replay + تدفقات tool-call) + - افتراضيًا: مخزن الملفات الشخصية وبدائل env + - اضبط `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض **مخزن الملفات الشخصية** فقط +- سبب وجود هذا: + - يفصل بين «واجهة API الخاصة بالمزوّد معطلة / المفتاح غير صالح» و«خط Gateway للوكيل معطّل» + - يحتوي على اختبارات انحدار صغيرة ومعزولة (مثال: تدفق إعادة تشغيل الاستدلال + تدفقات استدعاء الأدوات في OpenAI Responses/Codex Responses) -### الطبقة 2: اختبار smoke لـ Gateway + dev agent (ما الذي يفعله "@openclaw" فعليًا) +### الطبقة 2: اختبار Gateway + وكيل التطوير الدخاني (ما الذي يفعله "@openclaw" فعليًا) - الاختبار: `src/gateway/gateway-models.profiles.live.test.ts` - الهدف: - - تشغيل gateway داخل العملية - - إنشاء/ترقيع جلسة `agent:dev:*` (مع تجاوز النموذج في كل تشغيل) + - تشغيل Gateway داخل العملية + - إنشاء/تعديل جلسة `agent:dev:*` (مع تجاوز النموذج في كل تشغيل) - التكرار عبر النماذج التي تملك مفاتيح والتحقق من: - - استجابة "ذات معنى" (من دون أدوات) + - استجابة «ذات معنى» (من دون أدوات) - أن استدعاء أداة حقيقي يعمل (`read` probe) - - probes إضافية اختيارية للأدوات (`exec+read` probe) - - استمرار عمل مسارات انحدار OpenAI (`tool-call-only → follow-up`) -- تفاصيل probes (حتى تتمكن من شرح الإخفاقات بسرعة): - - probe `read`: يكتب الاختبار ملف nonce في مساحة العمل ويطلب من الوكيل `read` قراءته ثم إعادة nonce. - - probe `exec+read`: يطلب الاختبار من الوكيل كتابة nonce في ملف مؤقت عبر `exec`، ثم قراءته مجددًا عبر `read`. - - probe الصورة: يرفق الاختبار ملف PNG مُولّدًا (قطة + رمز عشوائي) ويتوقع من النموذج إرجاع `cat `. - - مرجع التنفيذ: `src/gateway/gateway-models.profiles.live.test.ts` و `src/gateway/live-image-probe.ts`. + - استقصاءات أدوات إضافية اختيارية (`exec+read` probe) + - أن مسارات الانحدار الخاصة بـ OpenAI (من استدعاء أدوات فقط → متابعة) تستمر في العمل +- تفاصيل الاستقصاءات (حتى تتمكن من شرح حالات الفشل بسرعة): + - استقصاء `read`: يكتب الاختبار ملف nonce في مساحة العمل ويطلب من الوكيل `read` قراءته ثم إعادة nonce. + - استقصاء `exec+read`: يطلب الاختبار من الوكيل استخدام `exec` لكتابة nonce في ملف مؤقت، ثم `read` قراءته مرة أخرى. + - استقصاء الصور: يرفق الاختبار ملف PNG مُولّدًا (قط + رمز عشوائي) ويتوقع أن يعيد النموذج `cat `. + - مرجع التنفيذ: `src/gateway/gateway-models.profiles.live.test.ts` و`src/gateway/live-image-probe.ts`. - كيفية التمكين: - `pnpm test:live` (أو `OPENCLAW_LIVE_TEST=1` إذا كنت تستدعي Vitest مباشرة) - كيفية اختيار النماذج: - - الافتراضي: قائمة السماح الحديثة (Opus/Sonnet 4.6+ و GPT-5.x + Codex و Gemini 3 و GLM 4.7 و MiniMax M2.7 و Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` هو اسم مستعار لقائمة السماح الحديثة + - الافتراضي: قائمة السماح الحديثة (`Opus/Sonnet 4.6+`، و`GPT-5.x + Codex`، و`Gemini 3`، و`GLM 4.7`، و`MiniMax M2.7`، و`Grok 4`) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` هو اسم بديل لقائمة السماح الحديثة - أو اضبط `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (أو قائمة مفصولة بفواصل) للتضييق - - تستخدم عمليات المسح gateway الحديثة/`all` حدًا منسقًا عالي الإشارة افتراضيًا؛ اضبط `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` لمسح حديث شامل أو رقمًا موجبًا لحد أصغر. -- كيفية اختيار المزوّدين (تجنّب "كل شيء عبر OpenRouter"): + - تستخدم عمليات مسح Gateway الحديثة/`all` حدًا منسقًا عالي الإشارة افتراضيًا؛ اضبط `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` لإجراء مسح حديث شامل أو رقمًا موجبًا لحد أصغر. +- كيفية اختيار المزوّدين (لتجنب «كل شيء من OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (قائمة سماح مفصولة بفواصل) -- تكون probes الأدوات + الصور مفعّلة دائمًا في هذا الاختبار الحي: - - probe `read` + probe `exec+read` (ضغط على الأدوات) - - يعمل probe الصورة عندما يعلن النموذج دعم إدخال الصور +- تكون استقصاءات الأدوات + الصور مفعّلة دائمًا في هذا الاختبار live: + - استقصاء `read` + استقصاء `exec+read` (ضغط على الأدوات) + - يعمل استقصاء الصور عندما يعلن النموذج دعمه لإدخال الصور - التدفق (على مستوى عالٍ): - - يولّد الاختبار ملف PNG صغيرًا يحتوي على “CAT” + رمز عشوائي (`src/gateway/live-image-probe.ts`) + - يولّد الاختبار ملف PNG صغيرًا يحوي “CAT” + رمزًا عشوائيًا (`src/gateway/live-image-probe.ts`) - يرسله عبر `agent` مع `attachments: [{ mimeType: "image/png", content: "" }]` - يحلل Gateway المرفقات إلى `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - يمرّر الوكيل المضمّن رسالة مستخدم متعددة الوسائط إلى النموذج - - التحقق: يحتوي الرد على `cat` + الرمز (مع سماحية OCR: الأخطاء الطفيفة مسموح بها) + - يمرر الوكيل المضمّن رسالة مستخدم متعددة الوسائط إلى النموذج + - التحقق: يحتوي الرد على `cat` + الرمز (مع سماحية OCR: الأخطاء الطفيفة مقبولة) نصيحة: لمعرفة ما يمكنك اختباره على جهازك (ومعرّفات `provider/model` الدقيقة)، شغّل: @@ -451,17 +458,17 @@ openclaw models list openclaw models list --json ``` -## Live: اختبار smoke للواجهة الخلفية CLI (Claude أو Codex أو Gemini أو CLI محلية أخرى) +## Live: اختبار CLI الخلفي الدخاني (Claude أو Codex أو Gemini أو CLIات محلية أخرى) - الاختبار: `src/gateway/gateway-cli-backend.live.test.ts` - الهدف: التحقق من خط Gateway + الوكيل باستخدام واجهة خلفية CLI محلية، من دون لمس إعدادك الافتراضي. -- توجد القيم الافتراضية لاختبار smoke الخاصة بكل واجهة خلفية مع تعريف `cli-backend.ts` المملوك للامتداد المعني. +- القيم الافتراضية الخاصة بكل واجهة خلفية لاختبار smoke موجودة مع تعريف `cli-backend.ts` الخاص بالامتداد المالك. - التمكين: - `pnpm test:live` (أو `OPENCLAW_LIVE_TEST=1` إذا كنت تستدعي Vitest مباشرة) - `OPENCLAW_LIVE_CLI_BACKEND=1` - القيم الافتراضية: - المزوّد/النموذج الافتراضي: `claude-cli/claude-sonnet-4-6` - - يأتي سلوك الأمر/الوسائط/الصورة من بيانات metadata الخاصة بـ CLI backend Plugin المالكة. + - يأتي سلوك الأمر/الوسائط/الصور من بيانات تعريف Plugin مالك الواجهة الخلفية CLI. - التجاوزات (اختيارية): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` @@ -469,8 +476,8 @@ openclaw models list --json - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` لإرسال مرفق صورة حقيقي (تُحقن المسارات في prompt). - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` لتمرير مسارات ملفات الصور كوسائط CLI بدلًا من حقنها في prompt. - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (أو `"list"`) للتحكم في كيفية تمرير وسائط الصور عند ضبط `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` لإرسال دور ثانٍ والتحقق من تدفق الاستئناف. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` لتعطيل probe الاستمرارية الافتراضي داخل الجلسة نفسها Claude Sonnet -> Opus (اضبطه على `1` لفرض تشغيله عندما يدعم النموذج المحدد هدف تبديل). + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` لإرسال دورة ثانية والتحقق من تدفق الاستئناف. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` لتعطيل استقصاء الاستمرارية الافتراضي للجلسة نفسها من Claude Sonnet إلى Opus (اضبطه إلى `1` لفرض تفعيله عندما يدعم النموذج المحدد هدف تبديل). مثال: @@ -498,27 +505,27 @@ pnpm test:docker:live-cli-backend:gemini ملاحظات: - يوجد مشغّل Docker في `scripts/test-live-cli-backend-docker.sh`. -- يشغّل اختبار smoke الحي لواجهة CLI الخلفية داخل صورة Docker الخاصة بالمستودع كمستخدم `node` غير الجذر. -- يحل metadata الخاصة باختبار smoke للواجهة CLI من الامتداد المالك، ثم يثبت حزمة CLI المطابقة الخاصة بـ Linux (`@anthropic-ai/claude-code` أو `@openai/codex` أو `@google/gemini-cli`) في بادئة قابلة للكتابة ومخزنة مؤقتًا عند `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (الافتراضي: `~/.cache/openclaw/docker-cli-tools`). -- يتطلب `pnpm test:docker:live-cli-backend:claude-subscription` مصادقة OAuth محمولة لاشتراك Claude Code عبر أحد الخيارين: `~/.claude/.credentials.json` مع `claudeAiOauth.subscriptionType` أو `CLAUDE_CODE_OAUTH_TOKEN` من `claude setup-token`. يثبت أولًا نجاح `claude -p` مباشرة داخل Docker، ثم يشغّل دورين لواجهة Gateway CLI الخلفية من دون الاحتفاظ بمتغيرات env الخاصة بمفتاح Anthropic API. يعطّل هذا المسار الخاص بالاشتراك probe أداة/صورة Claude MCP افتراضيًا لأن Claude يوجّه حاليًا استخدام التطبيقات الخارجية عبر فوترة استخدام إضافي بدلًا من حدود خطة الاشتراك العادية. -- يمارس اختبار smoke الحي لواجهة CLI الخلفية الآن التدفق الكامل نفسه من طرف إلى طرف لكل من Claude و Codex و Gemini: دور نصي، ثم دور تصنيف صورة، ثم استدعاء أداة MCP `cron` يتم التحقق منه عبر Gateway CLI. -- كما يقوم اختبار smoke الافتراضي لـ Claude بترقيع الجلسة من Sonnet إلى Opus ويتحقق من أن الجلسة المستأنفة لا تزال تتذكر ملاحظة سابقة. +- يشغّل اختبار smoke للواجهة الخلفية CLI داخل صورة Docker الخاصة بالمستودع كمستخدم `node` غير الجذر. +- يحلّل بيانات تعريف اختبار smoke لـ CLI من الامتداد المالك، ثم يثبت حزمة CLI المطابقة لـ Linux (`@anthropic-ai/claude-code` أو `@openai/codex` أو `@google/gemini-cli`) في بادئة قابلة للكتابة ومخزنة مؤقتًا في `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (الافتراضي: `~/.cache/openclaw/docker-cli-tools`). +- يتطلب `pnpm test:docker:live-cli-backend:claude-subscription` مصادقة OAuth محمولة لاشتراك Claude Code عبر أحد الخيارين: `~/.claude/.credentials.json` مع `claudeAiOauth.subscriptionType` أو `CLAUDE_CODE_OAUTH_TOKEN` من `claude setup-token`. وهو يثبت أولًا نجاح `claude -p` المباشر داخل Docker، ثم يشغّل دورتين للواجهة الخلفية CLI في Gateway من دون الاحتفاظ بمتغيرات env الخاصة بمفتاح Anthropic API. يعطّل هذا المسار الخاص بالاشتراك استقصاءات Claude MCP/tool والصور افتراضيًا لأن Claude يوجّه حاليًا استخدام التطبيقات الخارجية عبر فوترة استخدام إضافية بدلًا من حدود خطة الاشتراك العادية. +- أصبح اختبار smoke للواجهة الخلفية CLI الآن يمارس التدفق نفسه من النهاية إلى النهاية لكل من Claude وCodex وGemini: دورة نصية، ثم دورة تصنيف صور، ثم استدعاء أداة MCP `cron` يجري التحقق منه عبر CLI الخاص بـ Gateway. +- كما أن اختبار smoke الافتراضي لـ Claude يعدّل الجلسة من Sonnet إلى Opus ويتحقق من أن الجلسة المستأنفة ما تزال تتذكر ملاحظة سابقة. -## Live: اختبار smoke لربط ACP (`/acp spawn ... --bind here`) +## Live: اختبار ACP bind الدخاني (`/acp spawn ... --bind here`) - الاختبار: `src/gateway/gateway-acp-bind.live.test.ts` -- الهدف: التحقق من تدفق Conversation-bind الحقيقي لـ ACP باستخدام وكيل ACP حي: +- الهدف: التحقق من تدفق ربط المحادثة الحقيقي في ACP مع وكيل ACP حي: - إرسال `/acp spawn --bind here` - - ربط محادثة channel للرسائل تركيبية في مكانها - - إرسال متابعة عادية على نفس المحادثة - - التحقق من أن المتابعة تصل إلى transcript الجلسة المرتبطة بـ ACP + - ربط محادثة قناة رسائل اصطناعية في مكانها + - إرسال متابعة عادية على المحادثة نفسها + - التحقق من أن المتابعة تصل إلى نص جلسة ACP المنسوخ المرتبط - التمكين: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - القيم الافتراضية: - وكلاء ACP في Docker: `claude,codex,gemini` - - وكيل ACP للتشغيل المباشر `pnpm test:live ...`: `claude` - - القناة التركيبية: سياق محادثة على نمط Slack DM + - وكيل ACP للتشغيل المباشر عبر `pnpm test:live ...`: `claude` + - القناة الاصطناعية: سياق محادثة على نمط الرسائل الخاصة في Slack - الواجهة الخلفية لـ ACP: `acpx` - التجاوزات: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -527,8 +534,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - ملاحظات: - - يستخدم هذا المسار سطح gateway `chat.send` مع حقول originating-route تركيبية مخصصة للمشرف فقط حتى تتمكن الاختبارات من إرفاق سياق قناة الرسائل من دون الادعاء بالتسليم الخارجي. - - عندما لا يكون `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` مضبوطًا، يستخدم الاختبار سجل الوكلاء المضمّن الخاص بـ Plugin `acpx` للوكيل المحدد في harness الخاص بـ ACP. + - يستخدم هذا المسار سطح Gateway `chat.send` مع حقول synthetic originating-route مخصّصة للمشرف فقط حتى تتمكن الاختبارات من إرفاق سياق قناة الرسائل من دون التظاهر بالتسليم خارجيًا. + - عندما لا يكون `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` مضبوطًا، يستخدم الاختبار سجل الوكلاء المضمّن في Plugin `acpx` المضمّن لوكيل حزمة ACP المحدد. مثال: @@ -555,30 +562,30 @@ pnpm test:docker:live-acp-bind:gemini ملاحظات Docker: - يوجد مشغّل Docker في `scripts/test-live-acp-bind-docker.sh`. -- افتراضيًا، يشغّل اختبار smoke لربط ACP مقابل جميع وكلاء CLI الحيين المدعومين بالتسلسل: `claude` ثم `codex` ثم `gemini`. +- افتراضيًا، يشغّل اختبار ACP bind الدخاني مقابل جميع وكلاء CLI الحيين المدعومين بالتتابع: `claude` ثم `codex` ثم `gemini`. - استخدم `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude` أو `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` أو `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` لتضييق المصفوفة. -- يعتمد على `~/.profile`، ويجهّز مادة مصادقة CLI المطابقة داخل الحاوية، ويثبت `acpx` في بادئة npm قابلة للكتابة، ثم يثبت CLI الحي المطلوب (`@anthropic-ai/claude-code` أو `@openai/codex` أو `@google/gemini-cli`) إذا لم يكن موجودًا. -- داخل Docker، يضبط المشغّل `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` حتى يحافظ acpx على متغيرات env الخاصة بالمزوّد من profile الذي جرى تحميله لتكون متاحة لـ harness CLI الفرعي. +- يستورد `~/.profile`، ويجهز مواد مصادقة CLI المطابقة داخل الحاوية، ويثبت `acpx` في بادئة npm قابلة للكتابة، ثم يثبت CLI الحي المطلوب (`@anthropic-ai/claude-code` أو `@openai/codex` أو `@google/gemini-cli`) إذا كان مفقودًا. +- داخل Docker، يضبط المشغّل `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` بحيث يبقي acpx متغيرات env الخاصة بالمزوّد من profile المستورَد متاحةً لـ CLI الابن الخاص بالحزمة. -## Live: اختبار smoke لـ Codex app-server harness +## Live: اختبار Codex app-server harness الدخاني -- الهدف: التحقق من Codex harness المملوك لـ Plugin عبر طريقة gateway - العادية `agent`: +- الهدف: التحقق من أداة Codex المملوكة لـ Plugin عبر + طريقة `agent` العادية في Gateway: - تحميل Plugin `codex` المضمّن - اختيار `OPENCLAW_AGENT_RUNTIME=codex` - - إرسال أول دور للوكيل عبر gateway إلى `codex/gpt-5.4` - - إرسال دور ثانٍ إلى جلسة OpenClaw نفسها والتحقق من أن خيط app-server - يمكنه الاستئناف - - تشغيل `/codex status` و `/codex models` عبر مسار أوامر gateway نفسه + - إرسال أول دورة وكيل في Gateway إلى `codex/gpt-5.4` + - إرسال دورة ثانية إلى جلسة OpenClaw نفسها والتحقق من أن سلسلة + app-server يمكنها الاستئناف + - تشغيل `/codex status` و`/codex models` عبر مسار أوامر Gateway نفسه - الاختبار: `src/gateway/gateway-codex-harness.live.test.ts` - التمكين: `OPENCLAW_LIVE_CODEX_HARNESS=1` - النموذج الافتراضي: `codex/gpt-5.4` -- probe الصورة الاختياري: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- probe MCP/tool الاختياري: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- يضبط اختبار smoke القيمة `OPENCLAW_AGENT_HARNESS_FALLBACK=none` حتى لا يتمكن - Codex harness المعطّل من النجاح عبر الرجوع الاحتياطي الصامت إلى PI. -- المصادقة: `OPENAI_API_KEY` من shell/profile، بالإضافة إلى نسخ اختيارية من - `~/.codex/auth.json` و `~/.codex/config.toml` +- استقصاء صور اختياري: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- استقصاء MCP/tool اختياري: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- يضبط اختبار smoke القيمة `OPENCLAW_AGENT_HARNESS_FALLBACK=none` حتى لا ينجح + عطب أداة Codex عبر الرجوع الصامت إلى PI. +- المصادقة: `OPENAI_API_KEY` من الصدفة/الملف الشخصي، بالإضافة إلى نسخ + اختيارية من `~/.codex/auth.json` و`~/.codex/config.toml` وصفة محلية: @@ -601,30 +608,30 @@ pnpm test:docker:live-codex-harness ملاحظات Docker: - يوجد مشغّل Docker في `scripts/test-live-codex-harness-docker.sh`. -- يعتمد على `~/.profile` المركّب، ويمرّر `OPENAI_API_KEY`، وينسخ ملفات +- يستورد `~/.profile` المركّب، ويمرر `OPENAI_API_KEY`، وينسخ ملفات مصادقة Codex CLI عند وجودها، ويثبت `@openai/codex` في بادئة npm - قابلة للكتابة ومركّبة، ويجهّز شجرة المصدر، ثم يشغّل فقط اختبار Codex-harness الحي. -- يفعّل Docker probes الصورة و MCP/tool افتراضيًا. اضبط + مركبة قابلة للكتابة، ويجهّز شجرة المصدر، ثم يشغّل فقط اختبار Codex-harness الحي. +- يفعّل Docker استقصاءات الصور وMCP/tool افتراضيًا. اضبط `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` أو - `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` عندما تحتاج إلى تشغيل تضييقي أكثر لأغراض التصحيح. -- يصدّر Docker أيضًا `OPENCLAW_AGENT_HARNESS_FALLBACK=none`، بما يتطابق مع - إعداد الاختبار الحي حتى لا يتمكن `openai-codex/*` أو الرجوع الاحتياطي إلى PI من إخفاء - انحدار في Codex harness. + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` عندما تحتاج إلى تشغيل تصحيح أضيق. +- يصدّر Docker أيضًا `OPENCLAW_AGENT_HARNESS_FALLBACK=none`، بما يطابق إعداد + الاختبار الحي حتى لا يتمكن الرجوع إلى `openai-codex/*` أو PI من إخفاء + انحدار في أداة Codex. -### وصفات حية موصى بها +### وصفات live الموصى بها -قوائم السماح الضيقة والصريحة هي الأسرع والأقل عرضة للتذبذب: +قوائم السماح الضيقة والصريحة هي الأسرع والأقل عرضة للتعطل: -- نموذج واحد، مباشر (من دون gateway): +- نموذج واحد، مباشر (من دون Gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- نموذج واحد، اختبار smoke لـ gateway: +- نموذج واحد، اختبار Gateway دخاني: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - استدعاء الأدوات عبر عدة مزوّدين: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- التركيز على Google (مفتاح Gemini API + Antigravity): +- تركيز Google (مفتاح Gemini API + Antigravity): - Gemini (مفتاح API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` @@ -632,33 +639,33 @@ pnpm test:docker:live-codex-harness - يستخدم `google/...` واجهة Gemini API (مفتاح API). - يستخدم `google-antigravity/...` جسر Antigravity OAuth (نقطة نهاية وكيل على نمط Cloud Code Assist). -- يستخدم `google-gemini-cli/...` Gemini CLI المحلي على جهازك (مصادقة منفصلة ومراوغات أدوات منفصلة). +- يستخدم `google-gemini-cli/...` واجهة Gemini CLI المحلية على جهازك (مصادقة منفصلة وخصائص أدوات مختلفة). - Gemini API مقابل Gemini CLI: - - API: يستدعي OpenClaw واجهة Gemini API المستضافة من Google عبر HTTP (مفتاح API / مصادقة profile)؛ وهذا هو ما يقصده معظم المستخدمين عندما يقولون "Gemini". - - CLI: يستدعي OpenClaw ملف `gemini` الثنائي المحلي؛ وله مصادقته الخاصة ويمكن أن يتصرف بشكل مختلف (البث، ودعم الأدوات، واختلاف الإصدارات). + - API: يستدعي OpenClaw واجهة Gemini API المستضافة من Google عبر HTTP (مصادقة مفتاح API / الملف الشخصي)؛ وهذا ما يقصده معظم المستخدمين عندما يقولون «Gemini». + - CLI: ينفّذ OpenClaw أمرًا خارجيًا إلى ملف `gemini` الثنائي المحلي؛ وله مصادقته الخاصة وقد يتصرف بشكل مختلف (الدفق/دعم الأدوات/اختلاف الإصدارات). ## Live: مصفوفة النماذج (ما الذي نغطيه) -لا توجد "قائمة نماذج CI" ثابتة (لأن live اختيارية)، لكن هذه هي النماذج **الموصى بها** للتغطية المنتظمة على جهاز تطوير يملك مفاتيح. +لا توجد «قائمة نماذج CI» ثابتة (لأن live اشتراك اختياري)، لكن هذه هي النماذج **الموصى بها** للتغطية بانتظام على جهاز تطوير يملك مفاتيح. ### مجموعة smoke الحديثة (استدعاء الأدوات + الصور) -هذا هو تشغيل "النماذج الشائعة" الذي نتوقع الحفاظ على عمله: +هذا هو تشغيل «النماذج الشائعة» الذي نتوقع أن يستمر في العمل: - OpenAI (غير Codex): `openai/gpt-5.4` (اختياري: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (أو `anthropic/claude-sonnet-4-6`) -- Google (Gemini API): `google/gemini-3.1-pro-preview` و `google/gemini-3-flash-preview` (تجنب نماذج Gemini 2.x الأقدم) -- Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` و `google-antigravity/gemini-3-flash` +- Google (Gemini API): `google/gemini-3.1-pro-preview` و`google/gemini-3-flash-preview` (تجنب نماذج Gemini 2.x الأقدم) +- Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` و`google-antigravity/gemini-3-flash` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -شغّل اختبار smoke لـ gateway مع الأدوات + الصور: +شغّل اختبار Gateway الدخاني مع الأدوات + الصور: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### خط الأساس: استدعاء الأدوات (Read + Exec اختياري) +### الخط الأساسي: استدعاء الأدوات (`Read` + `Exec` اختياري) -اختر واحدًا على الأقل من كل عائلة مزوّدين: +اختر واحدًا على الأقل من كل عائلة مزوّد: - OpenAI: `openai/gpt-5.4` (أو `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (أو `anthropic/claude-sonnet-4-6`) @@ -666,44 +673,44 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -تغطية إضافية اختيارية (من الجيد توفرها): +تغطية إضافية اختيارية (من الجيد وجودها): - xAI: `xai/grok-4` (أو أحدث إصدار متاح) -- Mistral: `mistral/`… (اختر نموذجًا واحدًا مفعّلًا وقادرًا على `tools`) -- Cerebras: `cerebras/`… (إذا كانت لديك صلاحية وصول) +- Mistral: `mistral/`… (اختر نموذجًا واحدًا قادرًا على «الأدوات» ومفعّلًا لديك) +- Cerebras: `cerebras/`… (إذا كان لديك وصول) - LM Studio: `lmstudio/`… (محلي؛ يعتمد استدعاء الأدوات على وضع API) -### Vision: إرسال الصور (مرفق ← رسالة متعددة الوسائط) +### الرؤية: إرسال الصور (مرفق ← رسالة متعددة الوسائط) -ضمّن نموذجًا واحدًا على الأقل قادرًا على التعامل مع الصور في `OPENCLAW_LIVE_GATEWAY_MODELS` (مثل Claude/Gemini/OpenAI بالإصدارات الداعمة للرؤية، إلخ) لممارسة probe الصور. +ضمّن نموذجًا واحدًا على الأقل قادرًا على التعامل مع الصور في `OPENCLAW_LIVE_GATEWAY_MODELS` (مثل Claude/Gemini/إصدارات OpenAI القادرة على الرؤية، إلخ) لتمرين استقصاء الصور. -### المجمعات / البوابات البديلة +### المجمّعات / Gateways البديلة -إذا كانت لديك مفاتيح مفعّلة، فإننا ندعم أيضًا الاختبار عبر: +إذا كانت لديك مفاتيح مفعّلة، فنحن ندعم أيضًا الاختبار عبر: -- OpenRouter: `openrouter/...` (مئات النماذج؛ استخدم `openclaw models scan` للعثور على المرشحين القادرين على الأدوات+الصور) -- OpenCode: `opencode/...` لـ Zen و `opencode-go/...` لـ Go (المصادقة عبر `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: `openrouter/...` (مئات النماذج؛ استخدم `openclaw models scan` للعثور على مرشحين قادرين على الأدوات+الصور) +- OpenCode: `opencode/...` لـ Zen و`opencode-go/...` لـ Go (المصادقة عبر `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -مزيد من المزوّدين الذين يمكنك تضمينهم في المصفوفة الحية (إذا كانت لديك بيانات الاعتماد/الإعداد): +مزوّدون إضافيون يمكنك تضمينهم في مصفوفة live (إذا كانت لديك بيانات الاعتماد/الإعداد): -- المضمّنون: `openai` و `openai-codex` و `anthropic` و `google` و `google-vertex` و `google-antigravity` و `google-gemini-cli` و `zai` و `openrouter` و `opencode` و `opencode-go` و `xai` و `groq` و `cerebras` و `mistral` و `github-copilot` -- عبر `models.providers` (نقاط نهاية مخصصة): `minimax` (سحابي/API)، بالإضافة إلى أي proxy متوافق مع OpenAI/Anthropic (مثل LM Studio و vLLM و LiteLLM وغيرها) +- مضمّنون: `openai` و`openai-codex` و`anthropic` و`google` و`google-vertex` و`google-antigravity` و`google-gemini-cli` و`zai` و`openrouter` و`opencode` و`opencode-go` و`xai` و`groq` و`cerebras` و`mistral` و`github-copilot` +- عبر `models.providers` (نقاط نهاية مخصّصة): `minimax` (سحابي/API)، بالإضافة إلى أي وكيل متوافق مع OpenAI/Anthropic (مثل LM Studio أو vLLM أو LiteLLM، إلخ) -نصيحة: لا تحاول تثبيت "كل النماذج" بشكل صلب في المستندات. القائمة المرجعية هي ما يعيده `discoverModels(...)` على جهازك + المفاتيح المتاحة. +نصيحة: لا تحاول تثبيت «كل النماذج» بشكل صارم داخل المستندات. القائمة المرجعية الموثوقة هي ما تعيده `discoverModels(...)` على جهازك + أي مفاتيح متاحة. ## بيانات الاعتماد (لا تُلتزم أبدًا) -تكتشف الاختبارات الحية بيانات الاعتماد بالطريقة نفسها التي يعمل بها CLI. الآثار العملية: +تكتشف اختبارات live بيانات الاعتماد بالطريقة نفسها التي يفعلها CLI. والنتائج العملية لذلك: -- إذا كان CLI يعمل، فيجب أن تعثر الاختبارات الحية على المفاتيح نفسها. -- إذا قال اختبار حي "لا توجد بيانات اعتماد"، فقم بالتصحيح بالطريقة نفسها التي ستصحح بها `openclaw models list` / اختيار النموذج. +- إذا كان CLI يعمل، فيجب أن تجد اختبارات live المفاتيح نفسها. +- إذا قالت اختبارات live «لا توجد بيانات اعتماد»، فقم بالتصحيح بالطريقة نفسها التي ستصحح بها `openclaw models list` / اختيار النموذج. -- ملفات profile للمصادقة لكل وكيل: `~/.openclaw/agents//agent/auth-profiles.json` (وهذا ما تعنيه "profile keys" في الاختبارات الحية) +- ملفات مصادقة كل وكيل على حدة: `~/.openclaw/agents//agent/auth-profiles.json` (وهذا هو المقصود بعبارة «مفاتيح الملف الشخصي» في اختبارات live) - الإعداد: `~/.openclaw/openclaw.json` (أو `OPENCLAW_CONFIG_PATH`) -- دليل الحالة القديم: `~/.openclaw/credentials/` (يُنسخ إلى home الحي المجهّز عند وجوده، لكنه ليس مخزن المفاتيح الرئيسي لـ profile) -- تقوم التشغيلات الحية المحلية بنسخ الإعداد النشط وملفات `auth-profiles.json` لكل وكيل و `credentials/` القديم وأدلة مصادقة CLI الخارجية المدعومة إلى home اختبار مؤقت افتراضيًا؛ وتتجاوز البيئات الحية المجهّزة `workspace/` و `sandboxes/`، كما تُزال تجاوزات المسار `agents.*.workspace` / `agentDir` حتى تبقى probes بعيدة عن مساحة العمل الحقيقية على المضيف. +- دليل الحالة القديم: `~/.openclaw/credentials/` (يُنسخ إلى home live المرحلي عند وجوده، لكنه ليس مخزن مفاتيح الملف الشخصي الرئيسي) +- تقوم عمليات live المحلية افتراضيًا بنسخ الإعداد النشط، وملفات `auth-profiles.json` الخاصة بكل وكيل، و`credentials/` القديمة، وأدلة مصادقة CLI الخارجية المدعومة إلى home اختباري مؤقت؛ وتتخطى homes live المرحلية `workspace/` و`sandboxes/`، كما تُزال تجاوزات المسار `agents.*.workspace` / `agentDir` حتى تبقى الاستقصاءات بعيدة عن مساحة العمل الحقيقية على المضيف. -إذا كنت تريد الاعتماد على مفاتيح env (مثل تلك المصدّرة في `~/.profile`)، فشغّل الاختبارات المحلية بعد `source ~/.profile`، أو استخدم مشغّلات Docker أدناه (يمكنها تركيب `~/.profile` داخل الحاوية). +إذا أردت الاعتماد على مفاتيح env (مثل المفاتيح المصدّرة في `~/.profile`)، فشغّل الاختبارات المحلية بعد `source ~/.profile`، أو استخدم مشغّلات Docker أدناه (فيمكنها تحميل `~/.profile` داخل الحاوية). ## Deepgram live (نسخ الصوت) @@ -714,102 +721,106 @@ pnpm test:docker:live-codex-harness - الاختبار: `src/agents/byteplus.live.test.ts` - التمكين: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- تجاوز النموذج الاختياري: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- تجاوز النموذج اختياريًا: `BYTEPLUS_CODING_MODEL=ark-code-latest` ## ComfyUI workflow media live - الاختبار: `extensions/comfy/comfy.live.test.ts` - التمكين: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - النطاق: - - يمارس المسارات المضمّنة الخاصة بـ comfy للصور والفيديو و `music_generate` - - يتجاوز كل قدرة ما لم يكن `models.providers.comfy.` مضبوطًا - - مفيد بعد تغيير تقديم تدفق عمل comfy أو polling أو التنزيلات أو تسجيل Plugin + - يمارس مسارات الصور والفيديو و`music_generate` المضمّنة في comfy + - يتخطى كل قدرة ما لم يكن `models.providers.comfy.` مضبوطًا + - مفيد بعد تغيير إرسال سير عمل comfy أو الاستطلاع أو التنزيلات أو تسجيل Plugin ## Image generation live - الاختبار: `src/image-generation/runtime.live.test.ts` - الأمر: `pnpm test:live src/image-generation/runtime.live.test.ts` -- الحزام: `pnpm test:live:media image` +- أداة الاختبار: `pnpm test:live:media image` - النطاق: - - يعدّد كل Plugin مزوّد مسجل لتوليد الصور - - يحمّل متغيرات env المفقودة الخاصة بالمزوّد من shell تسجيل الدخول (`~/.profile`) قبل الفحص - - يستخدم مفاتيح API الحية/من env قبل ملفات profile المخزنة افتراضيًا، حتى لا تخفي مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات اعتماد shell الحقيقية - - يتجاوز المزوّدين الذين لا يملكون مصادقة/profile/نموذجًا صالحًا - - يشغّل المتغيرات القياسية لتوليد الصور عبر القدرة المشتركة لوقت التشغيل: + - يعدّد كل Plugin مزوّد إنشاء صور مسجّل + - يحمّل متغيرات env المفقودة الخاصة بالمزوّد من صدفة تسجيل الدخول (`~/.profile`) قبل الاستقصاء + - يستخدم مفاتيح API الحية/البيئية قبل ملفات المصادقة المخزنة افتراضيًا، بحيث لا تخفي مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات اعتماد الصدفة الحقيقية + - يتخطى المزوّدين الذين لا يملكون مصادقة/ملفًا شخصيًا/نموذجًا صالحًا + - يشغّل متغيرات إنشاء الصور القياسية عبر قدرة وقت التشغيل المشتركة: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- المزوّدون المضمّنون الحاليون الذين تتم تغطيتهم: +- المزوّدون المضمّنون الحاليون المشمولون: - `openai` - `google` -- التضييق الاختياري: +- تضييق اختياري: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- سلوك المصادقة الاختياري: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن profile وتجاهل التجاوزات المعتمدة على env فقط +- سلوك مصادقة اختياري: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن الملفات الشخصية وتجاهل تجاوزات env فقط ## Music generation live - الاختبار: `extensions/music-generation-providers.live.test.ts` - التمكين: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` -- الحزام: `pnpm test:live:media music` +- أداة الاختبار: `pnpm test:live:media music` - النطاق: - - يمارس المسار المضمّن المشترك لمزوّدات توليد الموسيقى - - يغطي حاليًا Google و MiniMax - - يحمّل متغيرات env الخاصة بالمزوّد من shell تسجيل الدخول (`~/.profile`) قبل الفحص - - يستخدم مفاتيح API الحية/من env قبل ملفات profile المخزنة افتراضيًا، حتى لا تخفي مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات اعتماد shell الحقيقية - - يتجاوز المزوّدين الذين لا يملكون مصادقة/profile/نموذجًا صالحًا + - يمارس مسار مزوّد إنشاء الموسيقى المضمّن المشترك + - يغطي حاليًا Google وMiniMax + - يحمّل متغيرات env الخاصة بالمزوّد من صدفة تسجيل الدخول (`~/.profile`) قبل الاستقصاء + - يستخدم مفاتيح API الحية/البيئية قبل ملفات المصادقة المخزنة افتراضيًا، بحيث لا تخفي مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات اعتماد الصدفة الحقيقية + - يتخطى المزوّدين الذين لا يملكون مصادقة/ملفًا شخصيًا/نموذجًا صالحًا - يشغّل وضعي وقت التشغيل المعلنين كليهما عند توفرهما: - `generate` مع إدخال يعتمد على prompt فقط - `edit` عندما يعلن المزوّد `capabilities.edit.enabled` - - التغطية الحالية في المسار المشترك: - - `google`: `generate` و `edit` + - التغطية الحالية للمسار المشترك: + - `google`: `generate`، `edit` - `minimax`: `generate` - - `comfy`: ملف Comfy حي منفصل، وليس هذا المسح المشترك -- التضييق الاختياري: + - `comfy`: ملف Comfy live منفصل، وليس هذا المسح المشترك +- تضييق اختياري: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- سلوك المصادقة الاختياري: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن profile وتجاهل التجاوزات المعتمدة على env فقط +- سلوك مصادقة اختياري: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن الملفات الشخصية وتجاهل تجاوزات env فقط ## Video generation live - الاختبار: `extensions/video-generation-providers.live.test.ts` - التمكين: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` -- الحزام: `pnpm test:live:media video` +- أداة الاختبار: `pnpm test:live:media video` - النطاق: - - يمارس المسار المضمّن المشترك لمزوّدات توليد الفيديو - - يحمّل متغيرات env الخاصة بالمزوّد من shell تسجيل الدخول (`~/.profile`) قبل الفحص - - يستخدم مفاتيح API الحية/من env قبل ملفات profile المخزنة افتراضيًا، حتى لا تخفي مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات اعتماد shell الحقيقية - - يتجاوز المزوّدين الذين لا يملكون مصادقة/profile/نموذجًا صالحًا - - يشغّل أوضاع وقت التشغيل المعلنة كليهما عند توفرهما: - - `generate` مع إدخال يعتمد على prompt فقط - - `imageToVideo` عندما يعلن المزوّد `capabilities.imageToVideo.enabled` ويقبل المزوّد/النموذج المحدد إدخال الصور المحلية المعتمد على buffer في المسح المشترك - - `videoToVideo` عندما يعلن المزوّد `capabilities.videoToVideo.enabled` ويقبل المزوّد/النموذج المحدد إدخال الفيديو المحلي المعتمد على buffer في المسح المشترك - - المزوّدون المعلن عنهم حاليًا لكن المتجاوزون في المسح المشترك لـ `imageToVideo`: - - `vydra` لأن `veo3` المضمّن نصي فقط و `kling` المضمّن يتطلب عنوان URL بعيدًا للصورة + - يمارس مسار مزوّد إنشاء الفيديو المضمّن المشترك + - يستخدم افتراضيًا مسار smoke الآمن للإصدار: مزوّدون غير FAL، وطلب text-to-video واحد لكل مزوّد، وprompt lobster لمدة ثانية واحدة، وسقف عملية لكل مزوّد من `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (الافتراضي `180000`) + - يتخطى FAL افتراضيًا لأن زمن انتظار الصف لدى المزوّد يمكن أن يهيمن على وقت الإصدار؛ مرّر `--video-providers fal` أو `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` لتشغيله صراحةً + - يحمّل متغيرات env الخاصة بالمزوّد من صدفة تسجيل الدخول (`~/.profile`) قبل الاستقصاء + - يستخدم مفاتيح API الحية/البيئية قبل ملفات المصادقة المخزنة افتراضيًا، بحيث لا تخفي مفاتيح الاختبار القديمة في `auth-profiles.json` بيانات اعتماد الصدفة الحقيقية + - يتخطى المزوّدين الذين لا يملكون مصادقة/ملفًا شخصيًا/نموذجًا صالحًا + - يشغّل `generate` فقط افتراضيًا + - اضبط `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` لتشغيل أوضاع التحويل المعلنة أيضًا عند توفرها: + - `imageToVideo` عندما يعلن المزوّد `capabilities.imageToVideo.enabled` ويقبل المزوّد/النموذج المحدد إدخال صور محلي مدعومًا بالمخزن المؤقت في المسح المشترك + - `videoToVideo` عندما يعلن المزوّد `capabilities.videoToVideo.enabled` ويقبل المزوّد/النموذج المحدد إدخال فيديو محلي مدعومًا بالمخزن المؤقت في المسح المشترك + - المزوّدون الحاليون المعلن عنهم لكن المتخطَّون في `imageToVideo` ضمن المسح المشترك: + - `vydra` لأن `veo3` المضمّن نصّي فقط و`kling` المضمّن يتطلب URL صورة بعيدًا - تغطية Vydra الخاصة بالمزوّد: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - يشغّل هذا الملف `veo3` لتحويل النص إلى فيديو بالإضافة إلى مسار `kling` يستخدم fixture لعنوان URL بعيد للصورة افتراضيًا - - التغطية الحية الحالية لـ `videoToVideo`: + - يشغّل هذا الملف `veo3` لتحويل النص إلى فيديو بالإضافة إلى مسار `kling` يستخدم تجهيز URL صورة بعيد افتراضيًا + - التغطية الحالية لـ `videoToVideo` في live: - `runway` فقط عندما يكون النموذج المحدد هو `runway/gen4_aleph` - - المزوّدون المعلن عنهم حاليًا لكن المتجاوزون في المسح المشترك لـ `videoToVideo`: - - `alibaba` و `qwen` و `xai` لأن هذه المسارات تتطلب حاليًا عناوين URL مرجعية بعيدة من نوع `http(s)` / MP4 - - `google` لأن مسار Gemini/Veo المشترك الحالي يستخدم إدخالًا محليًا معتمدًا على buffer وهذا المسار غير مقبول في المسح المشترك - - `openai` لأن المسار المشترك الحالي يفتقر إلى ضمانات وصول خاصة بالمؤسسة لفيديو inpaint/remix -- التضييق الاختياري: + - المزوّدون الحاليون المعلن عنهم لكن المتخطَّون في `videoToVideo` ضمن المسح المشترك: + - `alibaba` و`qwen` و`xai` لأن هذه المسارات تتطلب حاليًا عناوين URL مرجعية بعيدة من نوع `http(s)` / MP4 + - `google` لأن مسار Gemini/Veo المشترك الحالي يستخدم إدخالًا محليًا مدعومًا بالمخزن المؤقت وهذا المسار غير مقبول في المسح المشترك + - `openai` لأن المسار المشترك الحالي يفتقر إلى ضمانات الوصول الخاصة بالمؤسسة لعمليات inpaint/remix للفيديو +- تضييق اختياري: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` -- سلوك المصادقة الاختياري: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن profile وتجاهل التجاوزات المعتمدة على env فقط + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` لتضمين كل مزوّد في المسح الافتراضي، بما في ذلك FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` لتقليل سقف العملية لكل مزوّد من أجل تشغيل smoke شديد +- سلوك مصادقة اختياري: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لفرض مصادقة مخزن الملفات الشخصية وتجاهل تجاوزات env فقط -## حزام media live +## أداة media live - الأمر: `pnpm test:live:media` - الغرض: - - يشغّل مجموعات image و music و video الحية المشتركة عبر نقطة دخول أصلية واحدة للمستودع + - يشغّل مجموعات live المشتركة الخاصة بالصور والموسيقى والفيديو عبر نقطة دخول أصلية واحدة للمستودع - يحمّل تلقائيًا متغيرات env المفقودة الخاصة بالمزوّد من `~/.profile` - يضيّق تلقائيًا كل مجموعة إلى المزوّدين الذين يملكون حاليًا مصادقة صالحة افتراضيًا - يعيد استخدام `scripts/test-live.mjs`، بحيث يبقى سلوك Heartbeat والوضع الهادئ متسقًا @@ -819,186 +830,186 @@ pnpm test:docker:live-codex-harness - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## مشغّلات Docker (فحوصات اختيارية من نوع "تعمل على Linux") +## مشغّلات Docker (اختيارات «يعمل على Linux») تنقسم مشغّلات Docker هذه إلى فئتين: -- مشغّلات النماذج الحية: `test:docker:live-models` و `test:docker:live-gateway` يشغّلان فقط ملف الاختبار الحي المطابق لكل منهما والمخصص لمفاتيح profile داخل صورة Docker الخاصة بالمستودع (`src/agents/models.profiles.live.test.ts` و `src/gateway/gateway-models.profiles.live.test.ts`)، مع تركيب دليل الإعداد المحلي ومساحة العمل لديك (ومع تحميل `~/.profile` إذا جرى تركيبه). نقاط الدخول المحلية المطابقة هي `test:live:models-profiles` و `test:live:gateway-profiles`. -- تستخدم مشغّلات Docker الحية افتراضيًا حدًا أصغر لاختبار smoke حتى يبقى المسح الكامل داخل Docker عمليًا: +- مشغّلات النماذج الحية: يشغّل `test:docker:live-models` و`test:docker:live-gateway` فقط ملف live المطابق المعتمد على مفاتيح الملف الشخصي داخل صورة Docker الخاصة بالمستودع (`src/agents/models.profiles.live.test.ts` و`src/gateway/gateway-models.profiles.live.test.ts`)، مع تركيب دليل الإعداد المحلي ومساحة العمل لديك (واستيراد `~/.profile` إذا جرى تركيبه). نقاط الدخول المحلية المطابقة هي `test:live:models-profiles` و`test:live:gateway-profiles`. +- تستخدم مشغّلات Docker الحية افتراضيًا حدًا أصغر لاختبارات smoke حتى يبقى المسح الكامل داخل Docker عمليًا: يستخدم `test:docker:live-models` افتراضيًا `OPENCLAW_LIVE_MAX_MODELS=12`، ويستخدم `test:docker:live-gateway` افتراضيًا `OPENCLAW_LIVE_GATEWAY_SMOKE=1`، - و `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`، - و `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`، و + و`OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`، + و`OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`، و `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. تجاوز متغيرات env هذه عندما - تريد صراحةً المسح الأكبر والأشمل. -- يبني `test:docker:all` صورة Docker الحية مرة واحدة عبر `test:docker:live-build`، ثم يعيد استخدامها لمساري Docker الحيين. -- مشغّلات smoke الخاصة بالحاويات: `test:docker:openwebui` و `test:docker:onboard` و `test:docker:gateway-network` و `test:docker:mcp-channels` و `test:docker:plugins` تشغّل حاوية واحدة أو أكثر حقيقية وتتحقق من مسارات تكامل ذات مستوى أعلى. + تريد صراحةً إجراء المسح الشامل الأكبر. +- يقوم `test:docker:all` ببناء صورة Docker الحية مرة واحدة عبر `test:docker:live-build`، ثم يعيد استخدامها لمساري Docker الحيين. +- مشغّلات smoke الخاصة بالحاويات: تقوم `test:docker:openwebui` و`test:docker:onboard` و`test:docker:gateway-network` و`test:docker:mcp-channels` و`test:docker:plugins` بتشغيل حاوية واحدة أو أكثر فعلية والتحقق من مسارات تكامل أعلى مستوى. -تقوم مشغّلات Docker الخاصة بالنماذج الحية أيضًا بتركيب أدلة home الخاصة بمصادقة CLI المطلوبة فقط (أو جميع الأدلة المدعومة عندما لا يكون التشغيل مضيّقًا)، ثم تنسخها إلى home الحاوية قبل التشغيل حتى تتمكن مصادقة OAuth الخاصة بـ CLI الخارجية من تحديث الرموز من دون تعديل مخزن المصادقة على المضيف: +كما تقوم مشغّلات Docker الخاصة بالنماذج الحية أيضًا بتركيب أدلة مصادقة CLI المطلوبة فقط (أو جميع الأدلة المدعومة عندما لا يكون التشغيل مقيّدًا)، ثم تنسخها إلى home الحاوية قبل التشغيل حتى تتمكن OAuth الخاصة بالـ CLI الخارجية من تحديث الرموز من دون تعديل مخزن المصادقة على المضيف: - النماذج المباشرة: `pnpm test:docker:live-models` (السكريبت: `scripts/test-live-models-docker.sh`) -- اختبار smoke لربط ACP: `pnpm test:docker:live-acp-bind` (السكريبت: `scripts/test-live-acp-bind-docker.sh`) -- اختبار smoke لواجهة CLI الخلفية: `pnpm test:docker:live-cli-backend` (السكريبت: `scripts/test-live-cli-backend-docker.sh`) -- اختبار smoke لـ Codex app-server harness: `pnpm test:docker:live-codex-harness` (السكريبت: `scripts/test-live-codex-harness-docker.sh`) -- Gateway + dev agent: `pnpm test:docker:live-gateway` (السكريبت: `scripts/test-live-gateway-models-docker.sh`) -- اختبار smoke حي لـ Open WebUI: `pnpm test:docker:openwebui` (السكريبت: `scripts/e2e/openwebui-docker.sh`) -- معالج onboarding (TTY، تهيئة كاملة): `pnpm test:docker:onboard` (السكريبت: `scripts/e2e/onboard-docker.sh`) -- شبكات Gateway (حاويتان، مصادقة WS + الصحة): `pnpm test:docker:gateway-network` (السكريبت: `scripts/e2e/gateway-network-docker.sh`) -- جسر قناة MCP (Gateway مُهيأ مسبقًا + جسر stdio + اختبار smoke خام لإطارات الإشعارات على نمط Claude): `pnpm test:docker:mcp-channels` (السكريبت: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (اختبار smoke للتثبيت + الاسم المستعار `/plugin` + دلالات إعادة تشغيل Claude-bundle): `pnpm test:docker:plugins` (السكريبت: `scripts/e2e/plugins-docker.sh`) +- اختبار ACP bind الدخاني: `pnpm test:docker:live-acp-bind` (السكريبت: `scripts/test-live-acp-bind-docker.sh`) +- اختبار CLI backend الدخاني: `pnpm test:docker:live-cli-backend` (السكريبت: `scripts/test-live-cli-backend-docker.sh`) +- اختبار Codex app-server harness الدخاني: `pnpm test:docker:live-codex-harness` (السكريبت: `scripts/test-live-codex-harness-docker.sh`) +- Gateway + وكيل التطوير: `pnpm test:docker:live-gateway` (السكريبت: `scripts/test-live-gateway-models-docker.sh`) +- اختبار Open WebUI live الدخاني: `pnpm test:docker:openwebui` (السكريبت: `scripts/e2e/openwebui-docker.sh`) +- معالج الإعداد الأولي (TTY، هيكلة كاملة): `pnpm test:docker:onboard` (السكريبت: `scripts/e2e/onboard-docker.sh`) +- شبكات Gateway (حاويتان، مصادقة WS + السلامة): `pnpm test:docker:gateway-network` (السكريبت: `scripts/e2e/gateway-network-docker.sh`) +- جسر قناة MCP (Gateway مُهيّأ مسبقًا + جسر stdio + اختبار smoke خام لإطار إشعارات Claude): `pnpm test:docker:mcp-channels` (السكريبت: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (اختبار smoke للتثبيت + الاسم البديل `/plugin` + دلالات إعادة تشغيل حزمة Claude): `pnpm test:docker:plugins` (السكريبت: `scripts/e2e/plugins-docker.sh`) -تقوم مشغّلات Docker الخاصة بالنماذج الحية أيضًا بتركيب النسخة الحالية من المستودع -بوضع القراءة فقط وتجهيزها في workdir مؤقت داخل الحاوية. وهذا يُبقي صورة وقت التشغيل -نحيفة، مع الاستمرار في تشغيل Vitest مقابل source/config المحليين الدقيقين لديك. -تتجاوز خطوة التجهيز التخزينات المؤقتة المحلية الكبيرة فقط ومخرجات بناء التطبيقات مثل -`.pnpm-store` و `.worktrees` و `__openclaw_vitest__` وأدلة `.build` المحلية للتطبيق أو -مخرجات Gradle حتى لا تقضي التشغيلات الحية داخل Docker دقائق في نسخ -القطع الأثرية الخاصة بكل جهاز. -كما تضبط أيضًا `OPENCLAW_SKIP_CHANNELS=1` حتى لا تبدأ probes الحية الخاصة بـ gateway -عمّال القنوات الحقيقية مثل Telegram/Discord وغيرها داخل الحاوية. -لا يزال `test:docker:live-models` يشغّل `pnpm test:live`، لذا مرّر -`OPENCLAW_LIVE_GATEWAY_*` أيضًا عندما تحتاج إلى تضييق أو استبعاد تغطية gateway -الحية من مسار Docker هذا. -يُعد `test:docker:openwebui` اختبار smoke توافقًا أعلى مستوى: فهو يبدأ -حاوية OpenClaw gateway مع تمكين نقاط نهاية HTTP المتوافقة مع OpenAI، -ثم يبدأ حاوية Open WebUI مثبتة الإصدار مقابل ذلك gateway، ويسجل الدخول عبر -Open WebUI، ويتحقق من أن `/api/models` يعرّض `openclaw/default`، ثم يرسل -طلب دردشة حقيقيًا عبر proxy الخاص بـ `/api/chat/completions` في Open WebUI. +كما تقوم مشغّلات Docker الخاصة بالنماذج الحية أيضًا بتركيب النسخة الحالية من المستودع للقراءة فقط +وتجهيزها في دليل عمل مؤقت داخل الحاوية. يحافظ هذا على نحافة صورة وقت التشغيل +مع الاستمرار في تشغيل Vitest مقابل المصدر/الإعداد المحليين لديك بدقة. +تتجاوز خطوة التجهيز الذاكرات المؤقتة المحلية الكبيرة فقط وملفات بناء التطبيقات مثل +`.pnpm-store` و`.worktrees` و`__openclaw_vitest__` وأدلة `.build` المحلية للتطبيق أو +أدلة مخرجات Gradle حتى لا تقضي عمليات Docker live دقائق في نسخ +الآثار الخاصة بالجهاز. +كما تضبط أيضًا `OPENCLAW_SKIP_CHANNELS=1` حتى لا تبدأ استقصاءات Gateway live +عمّال قنوات حقيقيين مثل Telegram/Discord وغيرها داخل الحاوية. +ما يزال `test:docker:live-models` يشغّل `pnpm test:live`، لذا مرّر أيضًا +`OPENCLAW_LIVE_GATEWAY_*` عندما تحتاج إلى تضييق أو استبعاد تغطية Gateway +live من ذلك المسار داخل Docker. +يُعد `test:docker:openwebui` اختبار توافق دخانيًا أعلى مستوى: فهو يبدأ +حاوية OpenClaw Gateway مع تفعيل نقاط نهاية HTTP المتوافقة مع OpenAI، +ثم يبدأ حاوية Open WebUI مثبّتة الإصدار مقابل ذلك Gateway، ويسجّل الدخول عبر +Open WebUI، ويتحقق من أن `/api/models` يعرض `openclaw/default`، ثم يرسل +طلب دردشة حقيقيًا عبر وكيل `/api/chat/completions` الخاص بـ Open WebUI. قد يكون التشغيل الأول أبطأ بشكل ملحوظ لأن Docker قد يحتاج إلى سحب -صورة Open WebUI وقد تحتاج Open WebUI إلى إكمال إعداد البدء البارد الخاص بها. +صورة Open WebUI وقد يحتاج Open WebUI إلى إكمال إعداد البدء البارد الخاص به. يتوقع هذا المسار مفتاح نموذج حي صالحًا، ويُعد `OPENCLAW_PROFILE_FILE` -(الافتراضي `~/.profile`) الطريقة الأساسية لتوفيره في التشغيلات داخل Docker. -تطبع التشغيلات الناجحة حمولة JSON صغيرة مثل `{ "ok": true, "model": +(`~/.profile` افتراضيًا) الوسيلة الأساسية لتوفيره في عمليات Dockerized. +تطبع العمليات الناجحة حمولة JSON صغيرة مثل `{ "ok": true, "model": "openclaw/default", ... }`. -يُعد `test:docker:mcp-channels` حتميًا عمدًا ولا يحتاج إلى -حساب حقيقي على Telegram أو Discord أو iMessage. فهو يشغّل حاوية Gateway -مُهيأة مسبقًا، ثم يبدأ حاوية ثانية تشغّل `openclaw mcp serve`، ثم -يتحقق من اكتشاف المحادثات الموجّهة، وقراءة transcript، وmetadata الخاصة بالمرفقات، +يُصمَّم `test:docker:mcp-channels` عمدًا ليكون حتميًا ولا يحتاج إلى +حساب Telegram أو Discord أو iMessage حقيقي. فهو يشغّل حاوية Gateway +مُهيّأة مسبقًا، ثم يبدأ حاوية ثانية تشغّل `openclaw mcp serve`، ثم +يتحقق من اكتشاف المحادثات الموجّهة، وقراءة النصوص المنسوخة، وبيانات المرفقات الوصفية، وسلوك طابور الأحداث الحية، وتوجيه الإرسال الصادر، وإشعارات القناة + -الأذونات على نمط Claude عبر جسر stdio MCP الحقيقي. يفحص اختبار الإشعارات -إطارات stdio MCP الخام مباشرة حتى يتحقق اختبار smoke مما يصدره الجسر -فعليًا، وليس فقط مما تعرضه مجموعة SDK معينة للعميل. +الصلاحيات على نمط Claude عبر جسر stdio MCP الحقيقي. يفحص تحقق الإشعارات +إطارات stdio MCP الخام مباشرةً حتى يثبت اختبار smoke ما يصدره الجسر فعليًا، +وليس فقط ما قد تعرضه حزمة SDK عميل معيّنة. -اختبار smoke يدوي لخيط ACP بلغة طبيعية عادية (ليس في CI): +اختبار ACP اليدوي لسلسلة اللغة الطبيعية (ليس في CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- احتفظ بهذا السكريبت من أجل تدفقات عمل الانحدار/تصحيح الأخطاء. فقد تكون هناك حاجة إليه مرة أخرى للتحقق من توجيه خيوط ACP، لذلك لا تحذفه. +- احتفظ بهذا السكريبت لسير عمل الانحدار/التصحيح. قد تكون هناك حاجة إليه مرة أخرى للتحقق من توجيه سلاسل ACP، لذا لا تحذفه. متغيرات env المفيدة: - `OPENCLAW_CONFIG_DIR=...` (الافتراضي: `~/.openclaw`) ويُركّب إلى `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (الافتراضي: `~/.openclaw/workspace`) ويُركّب إلى `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (الافتراضي: `~/.profile`) ويُركّب إلى `/home/node/.profile` ويُحمّل قبل تشغيل الاختبارات -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (الافتراضي: `~/.cache/openclaw/docker-cli-tools`) ويُركّب إلى `/home/node/.npm-global` من أجل تثبيتات CLI المخزنة مؤقتًا داخل Docker -- تُركّب أدلة/ملفات مصادقة CLI الخارجية تحت `$HOME` بوضع القراءة فقط تحت `/host-auth...`، ثم تُنسخ إلى `/home/node/...` قبل بدء الاختبارات +- `OPENCLAW_PROFILE_FILE=...` (الافتراضي: `~/.profile`) ويُركّب إلى `/home/node/.profile` ويُستورد قبل تشغيل الاختبارات +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (الافتراضي: `~/.cache/openclaw/docker-cli-tools`) ويُركّب إلى `/home/node/.npm-global` لتثبيتات CLI المخزنة مؤقتًا داخل Docker +- تُركّب أدلة/ملفات مصادقة CLI الخارجية ضمن `$HOME` للقراءة فقط تحت `/host-auth...`، ثم تُنسخ إلى `/home/node/...` قبل بدء الاختبارات - الأدلة الافتراضية: `.minimax` - - الملفات الافتراضية: `~/.codex/auth.json` و `~/.codex/config.toml` و `.claude.json` و `~/.claude/.credentials.json` و `~/.claude/settings.json` و `~/.claude/settings.local.json` - - تشغيلات المزوّد المضيّقة تركّب فقط الأدلة/الملفات المطلوبة المستنتجة من `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - تجاوز ذلك يدويًا باستخدام `OPENCLAW_DOCKER_AUTH_DIRS=all` أو `OPENCLAW_DOCKER_AUTH_DIRS=none` أو قائمة مفصولة بفواصل مثل `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - الملفات الافتراضية: `~/.codex/auth.json` و`~/.codex/config.toml` و`.claude.json` و`~/.claude/.credentials.json` و`~/.claude/settings.json` و`~/.claude/settings.local.json` + - تقوم عمليات التشغيل المقيّدة بحسب المزوّد بتركيب الأدلة/الملفات المطلوبة فقط والمستنتجة من `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - يمكن التجاوز يدويًا عبر `OPENCLAW_DOCKER_AUTH_DIRS=all` أو `OPENCLAW_DOCKER_AUTH_DIRS=none` أو قائمة مفصولة بفواصل مثل `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` لتضييق التشغيل - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` لتصفية المزوّدين داخل الحاوية -- `OPENCLAW_SKIP_DOCKER_BUILD=1` لإعادة استخدام صورة `openclaw:local-live` الحالية في إعادة التشغيلات التي لا تحتاج إلى إعادة بناء -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لضمان أن تأتي بيانات الاعتماد من مخزن profile (وليس من env) -- `OPENCLAW_OPENWEBUI_MODEL=...` لاختيار النموذج الذي يعرّضه gateway لاختبار smoke الخاص بـ Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` لتجاوز prompt فحص nonce المستخدم في اختبار smoke الخاص بـ Open WebUI -- `OPENWEBUI_IMAGE=...` لتجاوز وسم صورة Open WebUI المثبتة +- `OPENCLAW_SKIP_DOCKER_BUILD=1` لإعادة استخدام صورة `openclaw:local-live` الموجودة مسبقًا في عمليات الإعادة التي لا تحتاج إلى إعادة بناء +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` لضمان أن تأتي بيانات الاعتماد من مخزن الملفات الشخصية (وليس من env) +- `OPENCLAW_OPENWEBUI_MODEL=...` لاختيار النموذج الذي يعرِضه Gateway لاختبار Open WebUI الدخاني +- `OPENCLAW_OPENWEBUI_PROMPT=...` لتجاوز prompt التحقق من nonce المستخدم في اختبار Open WebUI الدخاني +- `OPENWEBUI_IMAGE=...` لتجاوز وسم صورة Open WebUI المثبّت ## سلامة المستندات شغّل فحوصات المستندات بعد تعديلها: `pnpm check:docs`. -وشغّل التحقق الكامل من روابط/anchors الخاصة بـ Mintlify عندما تحتاج إلى فحوصات عناوين داخل الصفحة أيضًا: `pnpm docs:check-links:anchors`. +وشغّل التحقق الكامل من Anchors في Mintlify عندما تحتاج أيضًا إلى فحوصات العناوين داخل الصفحة: `pnpm docs:check-links:anchors`. -## اختبار انحدار دون اتصال (آمن لـ CI) +## اختبار الانحدار دون اتصال (آمن لـ CI) -هذه اختبارات انحدار "لخط حقيقي" من دون مزوّدين حقيقيين: +هذه اختبارات انحدار «لخط حقيقي» من دون مزوّدين حقيقيين: -- استدعاء أدوات Gateway (OpenAI وهمي، مع gateway + حلقة agent حقيقية): `src/gateway/gateway.test.ts` (الحالة: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- معالج Gateway (‏WS `wizard.start`/`wizard.next`، مع فرض كتابة config + auth): `src/gateway/gateway.test.ts` (الحالة: "runs wizard over ws and writes auth token config") +- استدعاء أدوات Gateway (محاكاة OpenAI، Gateway حقيقي + حلقة وكيل): `src/gateway/gateway.test.ts` (الحالة: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- معالج Gateway (‏WS `wizard.start`/`wizard.next`، مع فرض كتابة الإعداد + المصادقة): `src/gateway/gateway.test.ts` (الحالة: "runs wizard over ws and writes auth token config") ## تقييمات موثوقية الوكيل (Skills) -لدينا بالفعل بعض الاختبارات الآمنة لـ CI التي تتصرف مثل "تقييمات موثوقية الوكيل": +لدينا بالفعل بعض الاختبارات الآمنة لـ CI التي تتصرف مثل «تقييمات موثوقية الوكيل»: -- استدعاء أدوات وهمية عبر حلقة gateway + agent الحقيقية (`src/gateway/gateway.test.ts`). -- تدفقات wizard من طرف إلى طرف تتحقق من توصيل الجلسة وتأثيرات config (`src/gateway/gateway.test.ts`). +- استدعاء أدوات وهمي عبر حلقة Gateway + الوكيل الحقيقية (`src/gateway/gateway.test.ts`). +- تدفقات معالج شاملة تتحقق من توصيل الجلسات وآثار الإعداد (`src/gateway/gateway.test.ts`). -ما لا يزال مفقودًا بالنسبة إلى Skills (راجع [Skills](/ar/tools/skills)): +ما الذي ما يزال مفقودًا بالنسبة إلى Skills (راجع [Skills](/ar/tools/skills)): -- **اتخاذ القرار:** عند إدراج Skills في prompt، هل يختار الوكيل Skill الصحيحة (أو يتجنب غير ذات الصلة)؟ -- **الامتثال:** هل يقرأ الوكيل `SKILL.md` قبل الاستخدام ويلتزم بالخطوات/الوسائط المطلوبة؟ -- **عقود سير العمل:** سيناريوهات متعددة الأدوار تؤكد ترتيب الأدوات، واستمرار سجل الجلسة، وحدود sandbox. +- **اتخاذ القرار:** عندما تُدرج Skills في prompt، هل يختار الوكيل Skill الصحيحة (أو يتجنب غير ذات الصلة)؟ +- **الامتثال:** هل يقرأ الوكيل `SKILL.md` قبل الاستخدام ويتبع الخطوات/الوسائط المطلوبة؟ +- **عقود سير العمل:** سيناريوهات متعددة الأدوار تتحقق من ترتيب الأدوات، وترحيل سجل الجلسة، وحدود sandbox. يجب أن تبقى التقييمات المستقبلية حتمية أولًا: -- مشغّل سيناريوهات يستخدم مزوّدين وهميين لتأكيد استدعاءات الأدوات + ترتيبها، وقراءات ملفات Skill، وتوصيل الجلسات. -- مجموعة صغيرة من السيناريوهات المركزة على Skills (استخدام مقابل تجنب، والبوابات، وحقن prompt). -- تقييمات حية اختيارية (مقيّدة بالبيئة ومفعّلة اختياريًا) فقط بعد وضع المجموعة الآمنة لـ CI. +- مشغّل سيناريوهات يستخدم مزوّدين وهميين للتحقق من استدعاءات الأدوات + ترتيبها، وقراءات ملفات Skill، وتوصيل الجلسات. +- مجموعة صغيرة من السيناريوهات المركزة على Skills (الاستخدام مقابل التجنب، البوابات، حقن prompt). +- تقييمات live اختيارية (اشتراك اختياري ومحكومة بـ env) فقط بعد وجود المجموعة الآمنة لـ CI. ## اختبارات العقود (شكل Plugin والقناة) -تتحقق اختبارات العقود من أن كل Plugin وقناة مسجلين يلتزمان -بعقد الواجهة الخاصة بهما. فهي تتكرر على جميع Plugins المكتشفة وتشغّل مجموعة من -التحققات الخاصة بالشكل والسلوك. يتجاوز مسار unit الافتراضي `pnpm test` -عمدًا هذه الملفات المشتركة الخاصة بالوصلات واختبار smoke؛ شغّل أوامر العقود صراحةً -عندما تلمس الأسطح المشتركة للقنوات أو المزوّدين. +تتحقق اختبارات العقود من أن كل Plugin وقناة مسجلين يطابقان +عقد الواجهة الخاص بهما. فهي تمر على كل Plugins المكتشفة وتشغّل مجموعة من +التحققات الخاصة بالشكل والسلوك. يتخطى مسار unit الافتراضي في `pnpm test` +عمدًا هذه الملفات المشتركة الخاصة بالواجهات واختبارات smoke؛ شغّل أوامر العقود صراحةً +عندما تلمس أسطح القنوات أو المزوّدات المشتركة. ### الأوامر - جميع العقود: `pnpm test:contracts` - عقود القنوات فقط: `pnpm test:contracts:channels` -- عقود المزوّدين فقط: `pnpm test:contracts:plugins` +- عقود المزوّدات فقط: `pnpm test:contracts:plugins` ### عقود القنوات -تقع في `src/channels/plugins/contracts/*.contract.test.ts`: +توجد في `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - شكل Plugin الأساسي (المعرّف، والاسم، والقدرات) +- **plugin** - الشكل الأساسي للـ Plugin (المعرّف، الاسم، القدرات) - **setup** - عقد معالج الإعداد - **session-binding** - سلوك ربط الجلسة - **outbound-payload** - بنية حمولة الرسالة - **inbound** - معالجة الرسائل الواردة - **actions** - معالجات إجراءات القناة -- **threading** - معالجة معرّف الخيط -- **directory** - واجهة API للدليل/القائمة +- **threading** - التعامل مع معرّف السلسلة +- **directory** - API الدليل/القائمة - **group-policy** - فرض سياسة المجموعة ### عقود حالة المزوّد -تقع في `src/plugins/contracts/*.contract.test.ts`. +توجد في `src/plugins/contracts/*.contract.test.ts`. -- **status** - probes حالة القناة +- **status** - استقصاءات حالة القناة - **registry** - شكل سجل Plugin -### عقود المزوّدين +### عقود المزوّد -تقع في `src/plugins/contracts/*.contract.test.ts`: +توجد في `src/plugins/contracts/*.contract.test.ts`: - **auth** - عقد تدفق المصادقة - **auth-choice** - اختيار/تحديد المصادقة -- **catalog** - واجهة API لفهرس النماذج +- **catalog** - API كتالوج النماذج - **discovery** - اكتشاف Plugin - **loader** - تحميل Plugin - **runtime** - وقت تشغيل المزوّد - **shape** - شكل/واجهة Plugin - **wizard** - معالج الإعداد -### متى يجب التشغيل +### متى يجب تشغيلها -- بعد تغيير صادرات أو مسارات `plugin-sdk` -- بعد إضافة Plugin قناة أو مزوّد أو تعديله -- بعد إعادة هيكلة تسجيل Plugin أو اكتشافه +- بعد تغيير صادرات `plugin-sdk` أو مساراتها الفرعية +- بعد إضافة Plugin قناة أو مزوّد أو تعديلها +- بعد إعادة هيكلة تسجيل Plugin أو اكتشافها تعمل اختبارات العقود في CI ولا تتطلب مفاتيح API حقيقية. -## إضافة اختبارات انحدار (إرشادات) +## إضافة اختبارات الانحدار (إرشادات) -عند إصلاح مشكلة مزوّد/نموذج اكتُشفت في live: +عندما تصلح مشكلة مزوّد/نموذج اكتُشفت في live: -- أضف اختبار انحدار آمنًا لـ CI إن أمكن (مزوّد وهمي/بديل، أو التقط شكل تحويل الطلب الدقيق) -- إذا كانت المشكلة حية بطبيعتها فقط (حدود المعدل، وسياسات المصادقة)، فأبقِ الاختبار الحي ضيقًا ومفعّلًا اختياريًا عبر متغيرات env +- أضف اختبار انحدار آمنًا لـ CI إذا أمكن (محاكاة/Stub للمزوّد، أو التقاط تحويل شكل الطلب بدقة) +- إذا كانت المشكلة بطبيعتها live فقط (حدود المعدل، سياسات المصادقة)، فأبقِ الاختبار الحي ضيقًا ومشروطًا عبر متغيرات env - فضّل استهداف أصغر طبقة تلتقط الخطأ: - - خطأ تحويل/إعادة تشغيل طلب المزوّد → اختبار النماذج المباشرة - - خطأ في خط الجلسة/السجل/الأدوات في gateway → اختبار smoke حي لـ gateway أو اختبار gateway وهمي وآمن لـ CI -- حاجز حماية عبور SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` يشتق هدفًا نموذجيًا واحدًا لكل فئة SecretRef من metadata الخاصة بالسجل (`listSecretTargetRegistryEntries()`)، ثم يؤكد رفض معرّفات exec الخاصة بمقاطع العبور. - - إذا أضفت عائلة هدف SecretRef جديدة مع `includeInPlan` في `src/secrets/target-registry-data.ts`، فحدّث `classifyTargetClass` في ذلك الاختبار. يفشل الاختبار عمدًا عند وجود معرّفات هدف غير مصنفة حتى لا يمكن تجاوز الفئات الجديدة بصمت. + - خطأ في تحويل/إعادة تشغيل طلب المزوّد → اختبار النماذج المباشرة + - خطأ في خط جلسة/سجل/أدوات Gateway → اختبار Gateway live الدخاني أو اختبار محاكاة Gateway آمن لـ CI +- حاجز حماية اجتياز SecretRef: + - يقوم `src/secrets/exec-secret-ref-id-parity.test.ts` باشتقاق هدف معيّن واحد لكل فئة SecretRef من بيانات تعريف السجل (`listSecretTargetRegistryEntries()`)، ثم يتحقق من رفض معرّفات exec الخاصة بمقاطع الاجتياز. + - إذا أضفت عائلة أهداف SecretRef جديدة من نوع `includeInPlan` في `src/secrets/target-registry-data.ts`، فحدّث `classifyTargetClass` في ذلك الاختبار. يفشل الاختبار عمدًا عند وجود معرّفات أهداف غير مصنّفة حتى لا يمكن تخطي الفئات الجديدة بصمت. diff --git a/docs/ar/plugins/architecture.md b/docs/ar/plugins/architecture.md index b592faec9..024d5fea8 100644 --- a/docs/ar/plugins/architecture.md +++ b/docs/ar/plugins/architecture.md @@ -1,17 +1,17 @@ --- read_when: - - إنشاء أو تصحيح أخطاء Plugins OpenClaw الأصلية - - فهم نموذج إمكانات Plugin أو حدود الملكية + - بناء Plugins أصلية لـ OpenClaw أو تصحيح أخطائها + - فهم نموذج قدرات Plugin أو حدود الملكية - العمل على مسار تحميل Plugin أو السجل - - تنفيذ مرابط وقت تشغيل الموفّر أو Plugins القنوات + - تنفيذ خطافات وقت تشغيل المزوّد أو Plugins القنوات sidebarTitle: Internals -summary: 'الأجزاء الداخلية لـ Plugin: نموذج الإمكانات، والملكية، والعقود، ومسار التحميل، ومساعدات وقت التشغيل' +summary: 'الأجزاء الداخلية لـ Plugin: نموذج القدرات، الملكية، العقود، مسار التحميل، ومساعدات وقت التشغيل' title: الأجزاء الداخلية لـ Plugin x-i18n: - generated_at: "2026-04-12T23:28:35Z" + generated_at: "2026-04-15T07:17:44Z" model: gpt-5.4 provider: openai - source_hash: 37361c1e9d2da57c77358396f19dfc7f749708b66ff68f1bf737d051b5d7675d + source_hash: f86798b5d2b0ad82d2397a52a6c21ed37fe6eee1dd3d124a9e4150c4f630b841 source_path: plugins/architecture.md workflow: 15 --- @@ -19,92 +19,92 @@ x-i18n: # الأجزاء الداخلية لـ Plugin - هذا هو **المرجع المعماري المتعمق**. للاطلاع على الأدلة العملية، راجع: + هذه هي **المرجعية المعمارية المتعمقة**. للاطلاع على الأدلة العملية، راجع: - [تثبيت Plugins واستخدامها](/ar/tools/plugin) — دليل المستخدم - - [البدء](/ar/plugins/building-plugins) — أول درس تعليمي لـ Plugin - - [Plugins القنوات](/ar/plugins/sdk-channel-plugins) — إنشاء قناة مراسلة - - [Plugins الموفّرين](/ar/plugins/sdk-provider-plugins) — إنشاء موفّر نماذج - - [نظرة عامة على SDK](/ar/plugins/sdk-overview) — خريطة الاستيراد وواجهة API الخاصة بالتسجيل + - [البدء](/ar/plugins/building-plugins) — أول درس تعليمي لـ plugin + - [Plugins القنوات](/ar/plugins/sdk-channel-plugins) — أنشئ قناة مراسلة + - [Plugins المزوّد](/ar/plugins/sdk-provider-plugins) — أنشئ مزوّد نماذج + - [نظرة عامة على SDK](/ar/plugins/sdk-overview) — خريطة الاستيراد وواجهة برمجة التسجيل تغطي هذه الصفحة البنية الداخلية لنظام Plugins في OpenClaw. -## نموذج الإمكانات العام +## نموذج القدرات العام -تمثل الإمكانات نموذج **Plugins الأصلية** العام داخل OpenClaw. يسجل كل -Plugin أصلي في OpenClaw نفسه ضمن نوع واحد أو أكثر من أنواع الإمكانات: +القدرات هي نموذج **Plugins الأصلية** العام داخل OpenClaw. يسجّل كل Plugin أصلي في OpenClaw نفسه مقابل نوع قدرة واحد أو أكثر: -| الإمكانية | طريقة التسجيل | Plugins نموذجية | -| --------------------- | ---------------------------------------------- | ------------------------------------- | -| الاستدلال النصي | `api.registerProvider(...)` | `openai`، `anthropic` | -| خلفية استدلال CLI | `api.registerCliBackend(...)` | `openai`، `anthropic` | -| الكلام | `api.registerSpeechProvider(...)` | `elevenlabs`، `microsoft` | -| النسخ الفوري | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| الصوت الفوري | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| فهم الوسائط | `api.registerMediaUnderstandingProvider(...)` | `openai`، `google` | -| توليد الصور | `api.registerImageGenerationProvider(...)` | `openai`، `google`، `fal`، `minimax` | -| توليد الموسيقى | `api.registerMusicGenerationProvider(...)` | `google`، `minimax` | -| توليد الفيديو | `api.registerVideoGenerationProvider(...)` | `qwen` | -| جلب الويب | `api.registerWebFetchProvider(...)` | `firecrawl` | -| البحث على الويب | `api.registerWebSearchProvider(...)` | `google` | -| القناة / المراسلة | `api.registerChannel(...)` | `msteams`، `matrix` | +| القدرة | طريقة التسجيل | أمثلة على Plugins | +| ---------------------- | ------------------------------------------------ | ------------------------------------ | +| استدلال النص | `api.registerProvider(...)` | `openai`, `anthropic` | +| خلفية استدلال CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| الكلام | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| النسخ الفوري | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| الصوت الفوري | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| فهم الوسائط | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| توليد الصور | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| توليد الموسيقى | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| توليد الفيديو | `api.registerVideoGenerationProvider(...)` | `qwen` | +| جلب الويب | `api.registerWebFetchProvider(...)` | `firecrawl` | +| البحث في الويب | `api.registerWebSearchProvider(...)` | `google` | +| القناة / المراسلة | `api.registerChannel(...)` | `msteams`, `matrix` | -أي Plugin لا يسجل أي إمكانات ولكنه يوفّر مرابط أو أدوات أو -خدمات يُعد Plugin **قديمًا يعتمد على المرابط فقط**. ولا يزال هذا النمط مدعومًا بالكامل. +الـ Plugin الذي يسجّل صفرًا من القدرات لكنه يوفّر خطافات أو أدوات أو +خدمات هو Plugin **قديم يعتمد على الخطافات فقط**. لا يزال هذا النمط مدعومًا بالكامل. ### موقف التوافق الخارجي -تم اعتماد نموذج الإمكانات في النواة ويُستخدم اليوم من قبل -Plugins المجمّعة/الأصلية، لكن توافق Plugins الخارجية لا يزال يحتاج إلى معيار -أكثر صرامة من "إن كان مُصدّرًا فهو إذًا ثابت." +تم اعتماد نموذج القدرات في النواة ويُستخدم اليوم من قِبل Plugins +المضمّنة/الأصلية، لكن توافق Plugins الخارجية لا يزال يحتاج إلى معيار أدق من +"تم تصديره، إذن فهو ثابت." الإرشادات الحالية: -- **Plugins الخارجية الحالية:** حافظ على عمل التكاملات المعتمدة على المرابط؛ - وتعامل مع هذا باعتباره خط الأساس للتوافق -- **Plugins المجمّعة/الأصلية الجديدة:** فضّل التسجيل الصريح للإمكانات بدلًا من - التوغلات الخاصة بالمورّد أو التصاميم الجديدة المعتمدة على المرابط فقط -- **Plugins الخارجية التي تعتمد تسجيل الإمكانات:** هذا مسموح، لكن اعتبر أسطح - المساعدة الخاصة بالإمكانات قابلة للتطور ما لم تذكر الوثائق صراحة أن العقد ثابت +- **Plugins الخارجية الحالية:** حافظ على عمل التكاملات المعتمدة على الخطافات؛ واعتبر + هذا هو خط الأساس للتوافق +- **Plugins المضمّنة/الأصلية الجديدة:** فضّل تسجيل القدرات الصريح بدلًا من + الوصولات الخاصة بالمورّد أو التصاميم الجديدة التي تعتمد على الخطافات فقط +- **Plugins الخارجية التي تعتمد تسجيل القدرات:** مسموح بها، لكن اعتبر + أسطح المساعدات الخاصة بالقدرات في طور التطور ما لم تُشر الوثائق صراحةً إلى أن + العقد مستقر القاعدة العملية: -- واجهات API الخاصة بتسجيل الإمكانات هي الاتجاه المقصود -- تظل المرابط القديمة المسار الأكثر أمانًا لتجنب الكسر بالنسبة إلى Plugins الخارجية أثناء - الانتقال -- ليست كل المسارات الفرعية المصدّرة متساوية؛ فضّل العقد الضيق الموثّق، لا - صادرات المساعدة العرضية +- واجهات تسجيل القدرات هي الاتجاه المقصود +- تظل الخطافات القديمة المسار الأكثر أمانًا لتجنب الأعطال في Plugins الخارجية خلال + مرحلة الانتقال +- ليست كل المسارات الفرعية المصدّرة للمساعدات متساوية؛ فضّل العقد الضيق الموثّق، + وليس تصديرات المساعدات العرضية -### أشكال Plugin +### أشكال Plugins -يصنف OpenClaw كل Plugin محمّل إلى شكل معين بناءً على سلوك التسجيل -الفعلي الخاص به (وليس فقط البيانات الوصفية الثابتة): +يصنّف OpenClaw كل Plugin مُحمّل إلى شكل بناءً على سلوك التسجيل الفعلي +(وليس فقط البيانات الوصفية الثابتة): -- **plain-capability** -- يسجل نوع إمكانية واحدًا فقط بالضبط (على سبيل المثال - Plugin موفّر فقط مثل `mistral`) -- **hybrid-capability** -- يسجل عدة أنواع من الإمكانات (على سبيل المثال - `openai` يملك الاستدلال النصي والكلام وفهم الوسائط وتوليد +- **plain-capability** -- يسجّل نوع قدرة واحدًا فقط (على سبيل المثال + Plugin يوفّر مزوّدًا فقط مثل `mistral`) +- **hybrid-capability** -- يسجّل عدة أنواع من القدرات (على سبيل المثال + `openai` يملك استدلال النص والكلام وفهم الوسائط وتوليد الصور) -- **hook-only** -- يسجل المرابط فقط (مطبوعة أو مخصصة)، من دون إمكانات +- **hook-only** -- يسجّل الخطافات فقط (المكتوبة النوع أو المخصصة)، من دون قدرات أو أدوات أو أوامر أو خدمات -- **non-capability** -- يسجل أدوات أو أوامر أو خدمات أو مسارات لكن من دون - إمكانات +- **non-capability** -- يسجّل أدوات أو أوامر أو خدمات أو مسارات، ولكن من دون + قدرات -استخدم `openclaw plugins inspect ` لرؤية شكل Plugin وتفصيل -الإمكانات الخاصة به. راجع [مرجع CLI](/cli/plugins#inspect) للتفاصيل. +استخدم `openclaw plugins inspect ` لعرض شكل Plugin وتفصيل +القدرات. راجع [مرجع CLI](/cli/plugins#inspect) للحصول على التفاصيل. -### المرابط القديمة +### الخطافات القديمة -لا يزال المرابط `before_agent_start` مدعومًا باعتباره مسار توافق لـ -Plugins المعتمدة على المرابط فقط. لا تزال Plugins حقيقية قديمة تعتمد عليه. +لا يزال الخطاف `before_agent_start` مدعومًا كمسار توافق لPlugins +التي تعتمد على الخطافات فقط. لا تزال Plugins حقيقية قديمة تعتمد عليه. الاتجاه: -- حافظ على عمله -- وثّقه باعتباره قديمًا -- فضّل `before_model_resolve` لأعمال تجاوز النموذج/الموفّر -- فضّل `before_prompt_build` لأعمال تعديل الموجّه -- أزله فقط بعد انخفاض الاستخدام الفعلي وإثبات تغطية التركيبات الاختبارية لأمان الترحيل +- أبقه يعمل +- وثّقه على أنه قديم +- فضّل `before_model_resolve` لأعمال تجاوز النموذج/المزوّد +- فضّل `before_prompt_build` لأعمال تعديل الـ prompt +- لا تُزِله إلا بعد انخفاض الاستخدام الفعلي وإثبات تغطية الـ fixtures لسلامة الترحيل ### إشارات التوافق @@ -113,74 +113,82 @@ Plugins المعتمدة على المرابط فقط. لا تزال Plugins ح | الإشارة | المعنى | | ------------------------- | ------------------------------------------------------------ | -| **config valid** | يُحلَّل الإعداد بشكل صحيح وتُحل Plugins | -| **compatibility advisory** | يستخدم Plugin نمطًا مدعومًا لكنه أقدم (مثل `hook-only`) | -| **legacy warning** | يستخدم Plugin المرابط `before_agent_start`، وهو مهمل | -| **hard error** | الإعداد غير صالح أو فشل تحميل Plugin | +| **config valid** | يتم تحليل الإعدادات بشكل سليم وتُحلّ Plugins | +| **compatibility advisory** | يستخدم Plugin نمطًا مدعومًا لكنه أقدم (مثل `hook-only`) | +| **legacy warning** | يستخدم Plugin `before_agent_start`، وهو مهمل | +| **hard error** | الإعدادات غير صالحة أو فشل تحميل Plugin | -لن يؤدي `hook-only` ولا `before_agent_start` إلى كسر Plugin لديك اليوم -- -فـ `hook-only` إرشادي فقط، و`before_agent_start` لا يؤدي إلا إلى تحذير. كما -تظهر هذه الإشارات أيضًا في `openclaw status --all` و`openclaw plugins doctor`. +لن يؤدي `hook-only` ولا `before_agent_start` إلى كسر Plugin الخاص بك اليوم -- +فـ `hook-only` مجرد تنبيه استشاري، و`before_agent_start` لا يؤدي إلا إلى تحذير. تظهر هذه +الإشارات أيضًا في `openclaw status --all` و`openclaw plugins doctor`. ## نظرة عامة على البنية -يتكون نظام Plugins في OpenClaw من أربع طبقات: +يتكوّن نظام Plugins في OpenClaw من أربع طبقات: 1. **البيان + الاكتشاف** - يعثر OpenClaw على Plugins المرشحة من المسارات المضبوطة، وجذور مساحات العمل، - وجذور الإضافات العامة، والإضافات المجمعة. ويقرأ الاكتشاف أولًا - بيانات `openclaw.plugin.json` الخاصة بـ Plugins الأصلية إضافةً إلى - بيانات الحزم المدعومة. + يعثر OpenClaw على Plugins المرشحة من المسارات المهيأة وجذور مساحات العمل + وجذور الإضافات العامة والإضافات المضمّنة. يقرأ الاكتشاف ملفات البيان الأصلية + `openclaw.plugin.json` إضافةً إلى بيانات الحزم المدعومة أولًا. 2. **التمكين + التحقق** - تقرر النواة ما إذا كان Plugin المكتشف ممكّنًا أو معطّلًا أو محجوبًا أو - محددًا لفتحة حصرية مثل الذاكرة. + تقرر النواة ما إذا كان Plugin المكتشف مفعّلًا أو معطّلًا أو محظورًا أو + محددًا لخانة حصرية مثل الذاكرة. 3. **التحميل وقت التشغيل** - تُحمّل Plugins OpenClaw الأصلية داخل العملية عبر jiti وتُسجل - الإمكانات في سجل مركزي. وتُطبع الحزم المتوافقة إلى سجلات في - السجل من دون استيراد كود وقت التشغيل. -4. **استهلاك السطح** - يقرأ باقي OpenClaw السجل لعرض الأدوات، والقنوات، وإعداد - الموفّر، والمرابط، ومسارات HTTP، وأوامر CLI، والخدمات. + تُحمَّل Plugins OpenClaw الأصلية داخل العملية عبر jiti وتُسجّل + القدرات في سجل مركزي. وتُطبّع الحزم المتوافقة إلى سجلات في السجل + من دون استيراد كود وقت التشغيل. +4. **استهلاك الأسطح** + يقرأ باقي OpenClaw السجل لعرض الأدوات والقنوات وإعداد + المزوّد والخطافات ومسارات HTTP وأوامر CLI والخدمات. -وبالنسبة إلى CLI الخاصة بـ Plugin على وجه التحديد، ينقسم اكتشاف الأمر الجذري إلى مرحلتين: +بالنسبة إلى Plugin CLI تحديدًا، يُقسَّم اكتشاف أمر الجذر إلى مرحلتين: -- تأتي البيانات الوصفية وقت التحليل من `registerCli(..., { descriptors: [...] })` -- يمكن أن تظل وحدة CLI الحقيقية الخاصة بـ Plugin كسولة وتُسجل عند أول استدعاء +- تأتي بيانات وقت التحليل من `registerCli(..., { descriptors: [...] })` +- يمكن أن تظل وحدة Plugin CLI الحقيقية كسولة التحميل وتُسجّل عند أول استدعاء -يحافظ ذلك على كود CLI المملوك لـ Plugin داخل Plugin مع السماح لـ OpenClaw -بحجز أسماء الأوامر الجذرية قبل التحليل. +يحافظ ذلك على كود CLI المملوك للـ Plugin داخل Plugin نفسه، مع السماح لـ OpenClaw +بحجز أسماء أوامر الجذر قبل التحليل. -الحد التصميمي المهم: +الحدّ التصميمي المهم: -- يجب أن يعمل الاكتشاف + التحقق من الإعداد اعتمادًا على **بيانات البيان/المخطط الوصفية** +- يجب أن يعمل الاكتشاف + التحقق من الإعدادات من **بيانات البيان/المخطط** من دون تنفيذ كود Plugin -- يأتي سلوك وقت التشغيل الأصلي من مسار `register(api)` الخاص بوحدة Plugin +- يأتي السلوك الأصلي وقت التشغيل من مسار `register(api)` الخاص بوحدة Plugin -يتيح هذا الفصل لـ OpenClaw التحقق من الإعداد، وشرح Plugins المفقودة/المعطّلة، و -بناء تلميحات الواجهة/المخطط قبل تنشيط وقت التشغيل الكامل. +يسمح هذا الفصل لـ OpenClaw بالتحقق من الإعدادات وشرح Plugins +المفقودة/المعطلة وبناء تلميحات الواجهة/المخطط قبل تنشيط وقت التشغيل الكامل. ### Plugins القنوات وأداة الرسائل المشتركة -لا تحتاج Plugins القنوات إلى تسجيل أداة إرسال/تعديل/تفاعل منفصلة لأفعال -الدردشة العادية. يحتفظ OpenClaw بأداة `message` مشتركة واحدة في النواة، -وتملك Plugins القنوات الاكتشاف والتنفيذ الخاصين بالقناة خلفها. +لا تحتاج Plugins القنوات إلى تسجيل أداة منفصلة للإرسال/التحرير/التفاعل من أجل +إجراءات الدردشة العادية. يحتفظ OpenClaw بأداة `message` مشتركة واحدة في النواة، +بينما تملك Plugins القنوات الاكتشاف والتنفيذ الخاصين بالقناة من خلفها. الحد الحالي هو: -- تملك النواة مضيف أداة `message` المشتركة، وربط الموجّه، ودفتر - الجلسة/الخيط، وتوزيع التنفيذ -- تملك Plugins القنوات اكتشاف الأفعال المقيّدة، واكتشاف الإمكانات، وأي أجزاء - مخطط خاصة بالقناة -- تملك Plugins القنوات قواعد محادثة الجلسة الخاصة بالموفّر، مثل - كيفية ترميز معرفات المحادثة لمعرفات الخيوط أو وراثتها من المحادثات الأصلية -- تنفذ Plugins القنوات الفعل النهائي عبر مهايئ الأفعال الخاص بها +- تملك النواة مضيف أداة `message` المشتركة، وربط الـ prompt، ودفاتر الجلسات/المحادثات + وتنفيذ التوجيه +- تملك Plugins القنوات اكتشاف الإجراءات المقيّدة، واكتشاف القدرات، وأي أجزاء + من المخطط خاصة بالقناة +- تملك Plugins القنوات قواعد محادثة الجلسة الخاصة بالمزوّد، مثل + كيفية ترميز معرّفات المحادثات لمعرّفات السلاسل أو وراثتها من المحادثات الأصل +- تنفذ Plugins القنوات الإجراء النهائي عبر مهايئ الإجراء الخاص بها بالنسبة إلى Plugins القنوات، يكون سطح SDK هو -`ChannelMessageActionAdapter.describeMessageTool(...)`. يسمح -استدعاء الاكتشاف الموحّد هذا لـ Plugin بإرجاع أفعاله المرئية، وإمكاناته، -ومساهمات المخطط معًا حتى لا تنحرف هذه الأجزاء عن بعضها. +`ChannelMessageActionAdapter.describeMessageTool(...)`. تتيح +مكالمة الاكتشاف الموحّدة هذه للـ Plugin إعادة إجراءاته المرئية وقدراته ومساهمات +المخطط معًا حتى لا تنجرف هذه الأجزاء بعيدًا عن بعضها. -تمرر النواة نطاق وقت التشغيل إلى خطوة الاكتشاف هذه. وتشمل الحقول المهمة: +عندما يحمل بارامتر أداة الرسائل الخاص بالقناة مصدر وسائط مثل +مسار محلي أو عنوان URL لوسائط بعيدة، يجب على Plugin أيضًا إعادة +`mediaSourceParams` من `describeMessageTool(...)`. تستخدم النواة هذه +القائمة الصريحة لتطبيق تطبيع مسارات sandbox وتلميحات الوصول إلى الوسائط الصادرة +من دون ترميز ثابت لأسماء البارامترات المملوكة للـ Plugin. +فضّل الخرائط المقيّدة بالإجراء هناك، لا قائمة مسطحة واحدة على مستوى القناة، +حتى لا يُطبَّع بارامتر وسائط خاص بالملف الشخصي على إجراءات غير مرتبطة مثل +`send`. + +تمرّر النواة نطاق وقت التشغيل إلى خطوة الاكتشاف هذه. تشمل الحقول المهمة: - `accountId` - `currentChannelId` @@ -189,126 +197,126 @@ Plugins المعتمدة على المرابط فقط. لا تزال Plugins ح - `sessionKey` - `sessionId` - `agentId` -- `requesterSenderId` الوارد والموثوق +- `requesterSenderId` الوارد الموثوق -وهذا مهم بالنسبة إلى Plugins الحساسة للسياق. يمكن للقناة إخفاء أفعال -الرسائل أو إظهارها بناءً على الحساب النشط، أو الغرفة/الخيط/الرسالة الحالية، أو -هوية الطالب الموثوق بها، من دون ترميز تفرعات خاصة بالقناة داخل أداة -`message` الأساسية في النواة. +وهذا مهم للقنوات الحساسة للسياق. يمكن للقناة إخفاء إجراءات +الرسائل أو إظهارها استنادًا إلى الحساب النشط أو الغرفة/السلسلة/الرسالة الحالية أو +هوية الطالب الموثوق بها، من دون ترميز فروع خاصة بالقناة في أداة `message` +الأساسية. -ولهذا السبب لا تزال تغييرات التوجيه في المشغل المضمّن من عمل Plugin: فالمشغل -مسؤول عن تمرير هوية الدردشة/الجلسة الحالية إلى حد الاكتشاف الخاص بـ Plugin -حتى تعرض أداة `message` المشتركة السطح الصحيح المملوك للقناة في -الدور الحالي. +ولهذا السبب تظل تغييرات توجيه المشغّل المضمّن من أعمال Plugin: فالمشغّل +مسؤول عن تمرير هوية الدردشة/الجلسة الحالية إلى حدّ اكتشاف Plugin +بحيث تكشف أداة `message` المشتركة عن السطح الصحيح المملوك للقناة +للدور الحالي. -وبالنسبة إلى مساعدات التنفيذ المملوكة للقناة، يجب على Plugins المجمعة أن تحتفظ -بوقت تشغيل التنفيذ داخل وحدات الإضافة الخاصة بها. لم تعد النواة تملك أوقات تشغيل -أفعال الرسائل لـ Discord وSlack وTelegram وWhatsApp ضمن `src/agents/tools`. -نحن لا ننشر مسارات فرعية منفصلة `plugin-sdk/*-action-runtime`، ويجب على -Plugins المجمعة استيراد كود وقت التشغيل المحلي الخاص بها مباشرة من -الوحدات المملوكة للإضافة. +بالنسبة إلى مساعدات التنفيذ المملوكة للقناة، ينبغي على Plugins المضمّنة إبقاء +وقت تشغيل التنفيذ داخل وحدات الإضافة الخاصة بها. لم تعد النواة تملك +أوقات تشغيل إجراءات رسائل Discord أو Slack أو Telegram أو WhatsApp ضمن `src/agents/tools`. +نحن لا ننشر مسارات فرعية منفصلة من `plugin-sdk/*-action-runtime`، ويجب على Plugins +المضمّنة استيراد كود وقت التشغيل المحلي الخاص بها مباشرةً من +الوحدات التي تملكها الإضافة. -وينطبق الحد نفسه على أسطح SDK المسماة باسم الموفّر عمومًا: يجب ألا -تستورد النواة حاويات تسهيل خاصة بالقنوات لـ Slack أو Discord أو Signal أو -WhatsApp أو إضافات مشابهة. إذا احتاجت النواة إلى سلوك ما، فإما أن تستهلك -الحاوية `api.ts` / `runtime-api.ts` الخاصة بـ Plugin المجمّع نفسه، أو -ترقّي الحاجة إلى إمكانية عامة ضيقة في SDK المشتركة. +ينطبق الحدّ نفسه على مسارات SDK المسماة بأسماء المزوّدين عمومًا: لا ينبغي +للنواة أن تستورد حاويات تسهيل خاصة بالقنوات لـ Slack أو Discord أو Signal أو +WhatsApp أو الإضافات المشابهة. إذا احتاجت النواة إلى سلوك ما، فإما أن +تستهلك حاوية `api.ts` / `runtime-api.ts` الخاصة بالـ Plugin المضمّن نفسه، أو +ترقّي الحاجة إلى قدرة عامة ضيقة في SDK المشتركة. -وبالنسبة إلى الاستطلاعات على وجه التحديد، يوجد مساران للتنفيذ: +بالنسبة إلى الاستطلاعات تحديدًا، يوجد مساران للتنفيذ: - `outbound.sendPoll` هو خط الأساس المشترك للقنوات التي تناسب نموذج الاستطلاع الشائع -- `actions.handleAction("poll")` هو المسار المفضل لدلالات الاستطلاع - الخاصة بالقناة أو لمعاملات الاستطلاع الإضافية +- `actions.handleAction("poll")` هو المسار المفضّل لدلالات الاستطلاع + الخاصة بالقناة أو لبارامترات الاستطلاع الإضافية -تؤجل النواة الآن تحليل الاستطلاعات المشتركة إلى ما بعد رفض توزيع استطلاعات Plugin -للفعل، حتى تتمكن معالجات الاستطلاعات المملوكة لـ Plugin من قبول حقول استطلاع -خاصة بالقناة من دون أن يحجبها محلل الاستطلاع العام أولًا. +تؤجل النواة الآن تحليل الاستطلاع المشترك إلى ما بعد رفض توجيه استطلاع Plugin +للإجراء، بحيث يمكن لمعالجات الاستطلاع المملوكة للـ Plugin قبول +حقول استطلاع خاصة بالقناة من دون أن يعوقها محلّل الاستطلاع العام أولًا. -راجع [مسار التحميل](#load-pipeline) للتسلسل الكامل لبدء التشغيل. +راجع [مسار التحميل](#load-pipeline) للاطلاع على تسلسل بدء التشغيل الكامل. -## نموذج ملكية الإمكانات +## نموذج ملكية القدرات -يتعامل OpenClaw مع Plugin الأصلية باعتبارها حد الملكية الخاص بـ **شركة** -أو **ميزة**، لا باعتبارها مجموعة عشوائية من التكاملات غير المترابطة. +يتعامل OpenClaw مع Plugin الأصلي بوصفه حدّ الملكية لـ **شركة** أو +**ميزة**، لا بوصفه مجموعة عشوائية من التكاملات غير المرتبطة. وهذا يعني: -- ينبغي عادةً أن تملك Plugin الشركة كل الأسطح الخاصة بتلك الشركة داخل OpenClaw -- ينبغي عادةً أن تملك Plugin الميزة سطح الميزة الكامل الذي تقدمه -- ينبغي أن تستهلك القنوات إمكانات النواة المشتركة بدلًا من إعادة تنفيذ - سلوك الموفّر بصورة مخصصة +- يجب أن يملك Plugin الشركة عادةً جميع الأسطح الخاصة بـ OpenClaw لتلك الشركة +- يجب أن يملك Plugin الميزة عادةً السطح الكامل للميزة التي يقدّمها +- يجب أن تستهلك القنوات القدرات المشتركة للنواة بدلًا من إعادة تنفيذ + سلوك المزوّد بطريقة مخصصة أمثلة: -- تملك Plugin المجمعة `openai` سلوك موفّر نماذج OpenAI وسلوك - OpenAI للكلام + الصوت الفوري + فهم الوسائط + توليد الصور -- تملك Plugin المجمعة `elevenlabs` سلوك الكلام الخاص بـ ElevenLabs -- تملك Plugin المجمعة `microsoft` سلوك الكلام الخاص بـ Microsoft -- تملك Plugin المجمعة `google` سلوك موفّر نماذج Google إضافة إلى - سلوك Google لفهم الوسائط + توليد الصور + البحث على الويب -- تملك Plugin المجمعة `firecrawl` سلوك جلب الويب الخاص بـ Firecrawl -- تملك Plugins المجمعة `minimax` و`mistral` و`moonshot` و`zai` - واجهاتها الخلفية الخاصة بفهم الوسائط -- تملك Plugin المجمعة `qwen` سلوك موفّر النص الخاص بـ Qwen إضافة إلى - فهم الوسائط وسلوك توليد الفيديو -- تُعد Plugin `voice-call` Plugin ميزة: فهي تملك نقل المكالمات، والأدوات، - وCLI، والمسارات، وجسر تدفق الوسائط الخاص بـ Twilio، لكنها تستهلك - إمكانات الكلام المشتركة إضافةً إلى النسخ الفوري والصوت الفوري بدلًا من - استيراد Plugins المورّدين مباشرة +- يملك Plugin المضمّن `openai` سلوك مزوّد نماذج OpenAI وسلوك OpenAI + للكلام + الصوت الفوري + فهم الوسائط + توليد الصور +- يملك Plugin المضمّن `elevenlabs` سلوك الكلام لـ ElevenLabs +- يملك Plugin المضمّن `microsoft` سلوك الكلام لـ Microsoft +- يملك Plugin المضمّن `google` سلوك مزوّد نماذج Google إضافةً إلى سلوك Google + لفهم الوسائط + توليد الصور + البحث في الويب +- يملك Plugin المضمّن `firecrawl` سلوك جلب الويب لـ Firecrawl +- تملك Plugins المضمّنة `minimax` و`mistral` و`moonshot` و`zai` + الواجهات الخلفية لفهم الوسائط +- يملك Plugin المضمّن `qwen` سلوك مزوّد النصوص لـ Qwen إضافةً إلى + سلوك فهم الوسائط وتوليد الفيديو +- يُعد Plugin `voice-call` Plugin ميزة: فهو يملك نقل المكالمات والأدوات + وCLI والمسارات وجسر تدفّق وسائط Twilio، لكنه يستهلك قدرات الكلام المشتركة + إضافةً إلى قدرات النسخ الفوري والصوت الفوري بدلًا من + استيراد Plugins المورّدين مباشرةً الحالة النهائية المقصودة هي: -- تعيش OpenAI داخل Plugin واحدة حتى إن كانت تمتد عبر نماذج النص والكلام والصور و - الفيديو مستقبلًا -- يمكن لمورّد آخر أن يفعل الشيء نفسه ضمن نطاقه الخاص -- لا تهتم القنوات بأي Plugin مورّد تملك الموفّر؛ فهي تستهلك - عقد الإمكانية المشتركة الذي تكشفه النواة +- يعيش OpenAI في Plugin واحد حتى لو امتد عبر نماذج النصوص والكلام والصور + والفيديو مستقبلًا +- ويمكن لمورّد آخر أن يفعل الشيء نفسه ضمن نطاقه الخاص +- ولا تهتم القنوات بأي Plugin مورّد يملك المزوّد؛ فهي تستهلك + عقد القدرة المشتركة الذي تكشفه النواة -وهذا هو التمييز الأساسي: +هذا هو التمييز الأساسي: -- **plugin** = حد الملكية +- **plugin** = حدّ الملكية - **capability** = عقد النواة الذي يمكن لعدة Plugins تنفيذه أو استهلاكه -لذلك إذا أضاف OpenClaw مجالًا جديدًا مثل الفيديو، فليس السؤال الأول هو -"أي موفّر يجب أن يضمّن معالجة الفيديو بشكل صلب؟" بل السؤال الأول هو "ما هو -عقد إمكانية الفيديو في النواة؟" وبمجرد وجود هذا العقد، يمكن Plugins المورّدين -أن تسجل ضمنه ويمكن Plugins القنوات/الميزات أن تستهلكه. +لذلك إذا أضاف OpenClaw مجالًا جديدًا مثل الفيديو، فالسؤال الأول ليس +"أي مزوّد يجب أن يرمّز التعامل مع الفيديو ترميزًا ثابتًا؟" بل السؤال الأول هو +"ما عقد قدرة الفيديو في النواة؟" وبمجرد وجود هذا العقد، يمكن لPlugins المورّدين +التسجيل مقابله ويمكن لPlugins القنوات/الميزات استهلاكه. -إذا لم تكن الإمكانية موجودة بعد، فعادةً تكون الخطوة الصحيحة هي: +إذا لم تكن القدرة موجودة بعد، فعادةً ما تكون الخطوة الصحيحة هي: -1. تعريف الإمكانية المفقودة في النواة -2. كشفها عبر واجهة API الخاصة بـ Plugin/وقت التشغيل بطريقة مطبوعة -3. توصيل القنوات/الميزات بهذه الإمكانية -4. ترك Plugins المورّدين تسجل التنفيذات +1. تعريف القدرة المفقودة في النواة +2. كشفها عبر واجهة Plugin/وقت التشغيل بطريقة مكتوبة النوع +3. ربط القنوات/الميزات بهذه القدرة +4. والسماح لPlugins المورّدين بتسجيل التنفيذات يحافظ ذلك على وضوح الملكية مع تجنب سلوك في النواة يعتمد على -مورّد واحد أو مسار كود خاص بـ Plugin واحدة. +مورّد واحد أو مسار كود خاص بPlugin واحد. -### طبقات الإمكانات +### طبقات القدرات استخدم هذا النموذج الذهني عند تحديد موضع الكود: -- **طبقة الإمكانات في النواة**: التنسيق المشترك، والسياسات، والبدائل الاحتياطية، وقواعد - دمج الإعدادات، ودلالات التسليم، والعقود المطبوعة -- **طبقة Plugin الخاصة بالمورّد**: واجهات API الخاصة بالمورّد، والمصادقة، وفهارس النماذج، وتوليف - الكلام، وتوليد الصور، وواجهات الفيديو الخلفية المستقبلية، ونقاط نهاية الاستخدام -- **طبقة Plugin الخاصة بالقناة/الميزة**: تكامل Slack/Discord/voice-call/إلخ - الذي يستهلك إمكانات النواة ويعرضها على سطح ما +- **طبقة القدرات في النواة**: التنسيق المشترك والسياسات والتراجع وقواعد + دمج الإعدادات ودلالات التسليم والعقود المكتوبة النوع +- **طبقة Plugin المورّد**: واجهات API الخاصة بالمورّد، والمصادقة، وكتالوجات النماذج، واصطناع الكلام، + وتوليد الصور، والواجهات الخلفية المستقبلية للفيديو، ونقاط نهاية الاستخدام +- **طبقة Plugin القناة/الميزة**: تكاملات Slack/Discord/voice-call/إلخ + التي تستهلك قدرات النواة وتعرضها على سطح على سبيل المثال، يتبع TTS هذا الشكل: -- تملك النواة سياسة TTS وقت الرد، وترتيب البدائل الاحتياطية، والتفضيلات، وتسليم القناة -- تملك `openai` و`elevenlabs` و`microsoft` تنفيذات التوليف -- تستهلك `voice-call` مساعد وقت تشغيل TTS الخاص بالاتصال الهاتفي +- تملك النواة سياسة TTS وقت الرد، وترتيب التراجع، والتفضيلات، وتسليم القناة +- يملك `openai` و`elevenlabs` و`microsoft` تنفيذات الاصطناع +- يستهلك `voice-call` مساعد وقت تشغيل TTS الخاص بالهاتف -ويجب تفضيل هذا النمط نفسه للإمكانات المستقبلية. +ويجب تفضيل النمط نفسه للقدرات المستقبلية. -### مثال على Plugin شركة متعددة الإمكانات +### مثال على Plugin شركة متعدد القدرات -يجب أن تبدو Plugin الشركة متماسكة من الخارج. إذا كان OpenClaw يملك عقودًا -مشتركة للنماذج، والكلام، والنسخ الفوري، والصوت الفوري، وفهم الوسائط، -وتوليد الصور، وتوليد الفيديو، وجلب الويب، والبحث على الويب، +يجب أن يبدو Plugin الشركة متماسكًا من الخارج. إذا كان لدى OpenClaw +عقود مشتركة للنماذج والكلام والنسخ الفوري والصوت الفوري وفهم +الوسائط وتوليد الصور وتوليد الفيديو وجلب الويب والبحث في الويب، فيمكن لمورّد أن يملك جميع أسطحه في مكان واحد: ```ts @@ -363,240 +371,242 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -المهم ليس أسماء المساعدات الدقيقة. المهم هو الشكل: +ما يهم ليس أسماء المساعدات الدقيقة. المهم هو الشكل: -- Plugin واحدة تملك سطح المورّد -- لا تزال النواة تملك عقود الإمكانات -- تستهلك Plugins القنوات والميزات مساعدات `api.runtime.*`، لا كود المورّد -- يمكن لاختبارات العقد أن تؤكد أن Plugin سجلت الإمكانات التي - تدّعي أنها تملكها +- Plugin واحد يملك سطح المورّد +- لا تزال النواة تملك عقود القدرات +- تستهلك Plugins القنوات والميزات مساعدات `api.runtime.*`، وليس كود المورّد +- ويمكن لاختبارات العقود التأكد من أن Plugin سجّل القدرات التي + يدّعي ملكيتها -### مثال على الإمكانية: فهم الفيديو +### مثال على قدرة: فهم الفيديو -يعامل OpenClaw بالفعل فهم الصور/الصوت/الفيديو باعتباره -إمكانية مشتركة واحدة. وينطبق نموذج الملكية نفسه هنا: +يعامل OpenClaw بالفعل فهم الصور/الصوت/الفيديو كقدرة +مشتركة واحدة. وينطبق نموذج الملكية نفسه هنا: -1. تعرّف النواة عقد media-understanding -2. تسجل Plugins المورّدين `describeImage` و`transcribeAudio` و - `describeVideo` بحسب الاقتضاء -3. تستهلك Plugins القنوات والميزات السلوك المشترك في النواة بدلًا من - التوصيل مباشرة إلى كود المورّد +1. تعرّف النواة عقد فهم الوسائط +2. تسجّل Plugins المورّدين `describeImage` و`transcribeAudio` و + `describeVideo` حسب الاقتضاء +3. تستهلك Plugins القنوات والميزات سلوك النواة المشترك بدلًا من + الربط المباشر بكود المورّد -ويمنع ذلك تضمين افتراضات الفيديو الخاصة بأحد الموفّرين داخل النواة. إذ تملك Plugin -سطح المورّد؛ بينما تملك النواة عقد الإمكانية وسلوك البدائل الاحتياطية. +يمنع ذلك تضمين افتراضات الفيديو الخاصة بمزوّد واحد داخل النواة. فالـ Plugin يملك +سطح المورّد؛ بينما تملك النواة عقد القدرة وسلوك التراجع. -ويستخدم توليد الفيديو بالفعل التسلسل نفسه: إذ تملك النواة -عقد الإمكانية المطبوعة ومساعد وقت التشغيل، وتسجل Plugins المورّدين -تنفيذات `api.registerVideoGenerationProvider(...)` ضمنه. +يستخدم توليد الفيديو بالفعل التسلسل نفسه: تملك النواة عقد +القدرة المكتوب النوع ومساعد وقت التشغيل، وتسجّل Plugins المورّدين +تنفيذات `api.registerVideoGenerationProvider(...)` مقابله. -هل تحتاج إلى قائمة تحقق عملية للطرح؟ راجع -[دليل الإمكانات](/ar/plugins/architecture). +هل تحتاج إلى قائمة طرح عملية ومحددة؟ راجع +[دليل القدرات العملي](/ar/plugins/architecture). ## العقود وفرضها -سطح API الخاص بـ Plugin مطبوع ومركزي عمدًا في -`OpenClawPluginApi`. يعرّف هذا العقد نقاط التسجيل المدعومة و -مساعدات وقت التشغيل التي يمكن لـ Plugin الاعتماد عليها. +سطح واجهة Plugin مقصود به أن يكون مكتوب النوع ومركزيًا داخل +`OpenClawPluginApi`. يعرّف هذا العقد نقاط التسجيل المدعومة +ومساعدات وقت التشغيل التي يمكن أن يعتمد عليها Plugin. -لماذا هذا مهم: +سبب أهمية ذلك: - يحصل مؤلفو Plugins على معيار داخلي ثابت واحد -- يمكن للنواة رفض الملكية المكررة مثل تسجيل Pluginين لمعرف الموفّر نفسه -- يمكن لبدء التشغيل إظهار تشخيصات عملية لعمليات التسجيل غير الصحيحة -- يمكن لاختبارات العقد فرض ملكية Plugins المجمعة ومنع الانحراف الصامت +- يمكن للنواة رفض الملكية المكررة مثل تسجيل Pluginين لمعرّف + المزوّد نفسه +- يمكن لبدء التشغيل عرض تشخيصات عملية للتسجيلات غير الصحيحة +- يمكن لاختبارات العقود فرض ملكية Plugins المضمّنة ومنع الانجراف الصامت هناك طبقتان من الفرض: 1. **فرض التسجيل وقت التشغيل** - يتحقق سجل Plugins من عمليات التسجيل أثناء تحميل Plugins. أمثلة: - تؤدي معرفات الموفّرين المكررة، ومعرفات موفّري الكلام المكررة، وعمليات - التسجيل غير الصحيحة إلى تشخيصات Plugin بدلًا من سلوك غير معرّف. -2. **اختبارات العقد** - تُلتقط Plugins المجمعة في سجلات العقود أثناء تشغيل الاختبارات حتى - يتمكن OpenClaw من تأكيد الملكية صراحةً. ويُستخدم هذا اليوم مع - موفّري النماذج، وموفّري الكلام، وموفّري البحث على الويب، وملكية التسجيل المجمّع. + يتحقق سجل Plugins من التسجيلات أثناء تحميل Plugins. من الأمثلة: + معرّفات المزوّدين المكررة، ومعرّفات مزوّدي الكلام المكررة، والتسجيلات + غير الصحيحة التي تنتج تشخيصات Plugins بدلًا من سلوك غير معرّف. +2. **اختبارات العقود** + تُلتقط Plugins المضمّنة في سجلات العقود أثناء تشغيل الاختبارات حتى + يتمكن OpenClaw من تأكيد الملكية صراحةً. ويُستخدم هذا اليوم لمزوّدي + النماذج، ومزوّدي الكلام، ومزوّدي البحث في الويب، وملكية التسجيل المضمّن. -والأثر العملي هو أن OpenClaw يعرف مسبقًا أي Plugin تملك أي -سطح. وهذا يتيح للنواة والقنوات التركيب بسلاسة لأن الملكية -معلنة ومطبوعة وقابلة للاختبار بدلًا من أن تكون ضمنية. +والنتيجة العملية هي أن OpenClaw يعرف مسبقًا أي Plugin يملك أي +سطح. ويسمح ذلك للنواة والقنوات بالتركيب السلس لأن الملكية +معلنة ومكتوبة النوع وقابلة للاختبار بدلًا من أن تكون ضمنية. -### ما الذي ينتمي إلى عقد +### ما الذي يجب أن يكون ضمن عقد -العقود الجيدة الخاصة بـ Plugin تكون: +عقود Plugins الجيدة تكون: -- مطبوعة +- مكتوبة النوع - صغيرة -- خاصة بالإمكانات +- خاصة بالقدرة - مملوكة للنواة - قابلة لإعادة الاستخدام بواسطة عدة Plugins -- قابلة للاستهلاك بواسطة القنوات/الميزات من دون معرفة بالمورّد +- قابلة للاستهلاك من القنوات/الميزات دون معرفة بالمورّد -العقود السيئة الخاصة بـ Plugin تكون: +عقود Plugins السيئة تكون: - سياسات خاصة بالمورّد مخفية داخل النواة -- منافذ هروب خاصة بـ Plugin واحدة تتجاوز السجل -- كود قناة يصل مباشرة إلى تنفيذ خاص بمورّد +- منافذ هروب خاصة بPlugin واحد تتجاوز السجل +- كود قناة يصل مباشرةً إلى تنفيذ مورّد - كائنات وقت تشغيل مخصصة ليست جزءًا من `OpenClawPluginApi` أو `api.runtime` -عند الشك، ارفع مستوى التجريد: عرّف الإمكانية أولًا، ثم دع -Plugins تتصل بها. +عند الشك، ارفع مستوى التجريد: عرّف القدرة أولًا، ثم +دع Plugins تتصل بها. ## نموذج التنفيذ تعمل Plugins OpenClaw الأصلية **داخل العملية** مع Gateway. وهي ليست -معزولة. وPlugin أصلية محمّلة لديها حد الثقة نفسه على مستوى العملية مثل -كود النواة. +ضمن sandbox. يمتلك Plugin أصلي مُحمّل حدّ الثقة نفسه على مستوى العملية +الذي يملكه كود النواة. -النتائج المترتبة: +الآثار المترتبة: -- يمكن لـ Plugin أصلية تسجيل أدوات، ومعالجات شبكة، ومرابط، وخدمات -- يمكن لخلل في Plugin أصلية أن يعطّل Gateway أو يزعزع استقراره -- تعادل Plugin أصلية خبيثة تنفيذ كود عشوائي داخل +- يمكن للـ Plugin الأصلي تسجيل أدوات ومعالجات شبكية وخطافات وخدمات +- يمكن لخطأ في Plugin أصلي أن يتسبب في تعطل Gateway أو زعزعة استقراره +- يعادل Plugin أصلي خبيث تنفيذ كود عشوائي داخل عملية OpenClaw -وتكون الحزم المتوافقة أكثر أمانًا افتراضيًا لأن OpenClaw يتعامل معها حاليًا -بوصفها حزم بيانات وصفية/محتوى. وفي الإصدارات الحالية، يعني هذا في الغالب -Skills المجمّعة. +تُعد الحزم المتوافقة أكثر أمانًا افتراضيًا لأن OpenClaw يعاملها حاليًا +كحزم بيانات وصفية/محتوى. وفي الإصدارات الحالية، يعني ذلك غالبًا +Skills المضمّنة. -استخدم قوائم السماح ومسارات التثبيت/التحميل الصريحة بالنسبة إلى Plugins غير المجمعة. وتعامل -مع Plugins مساحة العمل بوصفها كودًا لوقت التطوير، لا إعدادات افتراضية للإنتاج. +استخدم قوائم السماح ومسارات التثبيت/التحميل الصريحة للPlugins غير المضمّنة. +واعتبر Plugins مساحات العمل كودًا لوقت التطوير، لا إعدادات إنتاج افتراضية. -وبالنسبة إلى أسماء حزم مساحة العمل المجمعة، أبقِ معرف Plugin مثبتًا في -اسم npm: `@openclaw/` افتراضيًا، أو لاحقة مطبوعة معتمدة مثل +بالنسبة إلى أسماء حزم مساحة العمل المضمّنة، حافظ على ارتكاز معرّف Plugin ضمن +اسم npm: `@openclaw/` افتراضيًا، أو لاحقة نوعية معتمدة مثل `-provider` أو `-plugin` أو `-speech` أو `-sandbox` أو `-media-understanding` عندما تكشف الحزمة عمدًا عن دور Plugin أضيق. ملاحظة ثقة مهمة: -- `plugins.allow` يثق في **معرفات Plugins**، لا في مصدر المنشأ. -- إن كانت Plugin مساحة عمل تحمل المعرف نفسه الذي تحمله Plugin مجمعة، فإنها - تظلل النسخة المجمعة عمدًا عندما تكون Plugin مساحة العمل تلك ممكّنة/ضمن قائمة السماح. -- هذا سلوك طبيعي ومفيد للتطوير المحلي، واختبار التصحيحات، والإصلاحات العاجلة. +- تثق `plugins.allow` في **معرّفات Plugins**، وليس في مصدرها. +- يعمد Plugin مساحة عمل يحمل المعرّف نفسه الذي يحمله Plugin مضمّن إلى حجب + النسخة المضمّنة عندما يكون Plugin مساحة العمل هذا مفعّلًا/مدرجًا في قائمة السماح. +- وهذا طبيعي ومفيد للتطوير المحلي واختبار التصحيحات والإصلاحات السريعة. -## حد التصدير +## حدّ التصدير -يصدّر OpenClaw الإمكانات، لا وسائل الراحة التنفيذية. +يصدّر OpenClaw القدرات، لا وسائل الراحة التنفيذية. -أبقِ تسجيل الإمكانات عامًا. وقلّص صادرات المساعدات غير التعاقدية: +أبقِ تسجيل القدرات عامًا. وقلّص تصديرات المساعدات غير التعاقدية: -- المسارات الفرعية الخاصة بمساعدات Plugin المجمعة -- المسارات الفرعية لسباكة وقت التشغيل غير المقصودة كواجهة API عامة +- المسارات الفرعية الخاصة بمساعدات Plugins المضمّنة +- المسارات الفرعية لبنية وقت التشغيل غير المقصودة كواجهة API عامة - مساعدات الراحة الخاصة بالمورّد - مساعدات الإعداد/التهيئة التي تُعد تفاصيل تنفيذ -ولا تزال بعض المسارات الفرعية الخاصة بمساعدات Plugins المجمعة موجودة في خريطة -تصدير SDK المولدة لأجل التوافق وصيانة Plugins المجمعة. وتشمل الأمثلة الحالية -`plugin-sdk/feishu` و`plugin-sdk/feishu-setup` و`plugin-sdk/zalo` -و`plugin-sdk/zalo-setup` وعدة حدود `plugin-sdk/matrix*`. تعامل مع هذه -باعتبارها صادرات محفوظة لتفاصيل التنفيذ، لا باعتبارها النمط الموصى به في SDK -لـ Plugins الخارجية الجديدة. +لا تزال بعض المسارات الفرعية لمساعدات Plugins المضمّنة موجودة في +خريطة تصدير SDK المُولّدة لأجل التوافق وصيانة Plugins المضمّنة. من الأمثلة الحالية +`plugin-sdk/feishu` و`plugin-sdk/feishu-setup` و`plugin-sdk/zalo` و +`plugin-sdk/zalo-setup` وعدة حدود من `plugin-sdk/matrix*`. تعامل مع هذه +على أنها تصديرات محجوزة لتفاصيل التنفيذ، لا على أنها نمط SDK الموصى به +لـ Plugins الجهات الخارجية الجديدة. ## مسار التحميل -عند بدء التشغيل، ينفّذ OpenClaw تقريبًا ما يلي: +عند بدء التشغيل، يقوم OpenClaw تقريبًا بما يلي: 1. اكتشاف جذور Plugins المرشحة -2. قراءة بيانات Plugins الأصلية أو الحزم المتوافقة وبيانات الحزم الوصفية +2. قراءة بيانات البيان الأصلية أو بيانات الحزم المتوافقة وبيانات الحزمة الوصفية 3. رفض المرشحين غير الآمنين -4. تطبيع إعداد Plugin (`plugins.enabled` و`allow` و`deny` و`entries`، +4. تطبيع إعدادات Plugins (`plugins.enabled` و`allow` و`deny` و`entries`، و`slots`، و`load.paths`) -5. تحديد التمكين لكل مرشح -6. تحميل الوحدات الأصلية الممكّنة عبر jiti -7. استدعاء مرابط `register(api)` الأصلية (أو `activate(api)` — وهو اسم مستعار قديم) وجمع عمليات التسجيل في سجل Plugin -8. كشف السجل إلى الأوامر وأسطح وقت التشغيل +5. تقرير التمكين لكل مرشح +6. تحميل الوحدات الأصلية المفعلة عبر jiti +7. استدعاء خطافات `register(api)` الأصلية (أو `activate(api)` — وهو اسم مستعار قديم) وجمع التسجيلات في سجل Plugins +8. كشف السجل لأسطح الأوامر/وقت التشغيل -`activate` هو اسم مستعار قديم لـ `register` — إذ يحلّ المحمّل أيّهما موجود (`def.register ?? def.activate`) ويستدعيه في النقطة نفسها. تستخدم جميع Plugins المجمعة `register`؛ وفضّل `register` في Plugins الجديدة. +`activate` اسم مستعار قديم لـ `register` — يحدّد أداة التحميل أيهما موجود (`def.register ?? def.activate`) وتستدعيه في النقطة نفسها. تستخدم جميع Plugins المضمّنة `register`؛ فضّل `register` في Plugins الجديدة. تحدث بوابات الأمان **قبل** تنفيذ وقت التشغيل. ويُحظر المرشحون -عندما يخرج الإدخال عن جذر Plugin، أو يكون المسار قابلاً للكتابة من الجميع، أو -تبدو ملكية المسار مشبوهة بالنسبة إلى Plugins غير المجمعة. +عندما يخرج الإدخال من جذر Plugin، أو يكون المسار قابلاً للكتابة من الجميع، أو +تبدو ملكية المسار مريبة في Plugins غير المضمّنة. -### السلوك المعتمد على البيان أولًا +### سلوك البيان أولًا -يُعد البيان مصدر الحقيقة لطائرة التحكم. ويستخدمه OpenClaw من أجل: +البيان هو مصدر الحقيقة لمستوى التحكم. يستخدمه OpenClaw من أجل: - تحديد Plugin -- اكتشاف القنوات/Skills/مخطط الإعداد المعلنة أو إمكانات الحزمة +- اكتشاف القنوات/Skills/مخطط الإعدادات المعلن عنها أو قدرات الحزمة - التحقق من `plugins.entries..config` -- تعزيز تسميات/عناصر نائبة في Control UI +- تحسين التسميات/العناصر النائبة في واجهة Control UI - عرض بيانات التثبيت/الفهرس الوصفية -- الحفاظ على واصفات تنشيط وتهيئة منخفضة الكلفة من دون تحميل وقت تشغيل Plugin +- الحفاظ على أوصاف تفعيل وإعداد منخفضة التكلفة من دون تحميل وقت تشغيل Plugin -بالنسبة إلى Plugins الأصلية، تكون وحدة وقت التشغيل هي جزء طائرة البيانات. فهي تسجل -السلوك الفعلي مثل المرابط، والأدوات، والأوامر، أو تدفقات الموفّر. +بالنسبة إلى Plugins الأصلية، تكون وحدة وقت التشغيل هي جزء مستوى البيانات. فهي تسجّل +السلوك الفعلي مثل الخطافات أو الأدوات أو الأوامر أو تدفقات المزوّد. -تظل كتل `activation` و`setup` الاختيارية في البيان ضمن طائرة التحكم. -فهي واصفات بيانات وصفية فقط لتخطيط التنشيط واكتشاف الإعداد؛ -ولا تستبدل التسجيل في وقت التشغيل، أو `register(...)`، أو `setupEntry`. -ويستخدم أوائل مستهلكي التنشيط الحي الآن تلميحات الأوامر والقنوات والموفّرين في البيان -لتضييق تحميل Plugins قبل تجسيد السجل على نطاق أوسع: +تظل كتلتَا `activation` و`setup` الاختياريتان في البيان ضمن مستوى التحكم. +وهما واصفان يعتمدان على البيانات الوصفية فقط لتخطيط التفعيل واكتشاف الإعداد؛ +ولا تحلان محل تسجيل وقت التشغيل أو `register(...)` أو `setupEntry`. +يستخدم أول مستهلكي التفعيل الفعليين الآن تلميحات أوامر CLI والقناة والمزوّد من البيان +لتضييق تحميل Plugins قبل تكوين السجل على نطاق أوسع: -- يضيّق تحميل CLI إلى Plugins التي تملك الأمر الأساسي المطلوب -- يضيّق حل إعداد القناة/Plugin إلى Plugins التي تملك - معرف القناة المطلوب -- يضيّق حل إعداد/وقت تشغيل الموفّر الصريح إلى Plugins التي تملك - معرف الموفّر المطلوب +- يقتصر تحميل CLI على Plugins التي تملك الأمر الأساسي المطلوب +- يقتصر إعداد القناة/حلّ Plugin على Plugins التي تملك + معرّف القناة المطلوب +- يقتصر إعداد/حلّ المزوّد الصريح وقت التشغيل على Plugins التي تملك + معرّف المزوّد المطلوب -يفضّل اكتشاف الإعداد الآن المعرفات المملوكة للواصفات مثل `setup.providers` و +يفضّل اكتشاف الإعداد الآن المعرّفات المملوكة للواصفات مثل `setup.providers` و `setup.cliBackends` لتضييق Plugins المرشحة قبل أن يعود إلى -`setup-api` بالنسبة إلى Plugins التي لا تزال تحتاج إلى مرابط وقت تشغيل أثناء الإعداد. وإذا ادّعت -أكثر من Plugin مكتشفة واحدة ملكية معرف موفّر إعداد أو خلفية CLI بعد -تطبيعه، يرفض بحث الإعداد المالك الملتبس بدلًا من الاعتماد على ترتيب الاكتشاف. +`setup-api` للPlugins التي لا تزال تحتاج إلى خطافات وقت تشغيل أثناء الإعداد. وإذا ادّعى +أكثر من Plugin مكتشف واحد المعرّف الموحّد نفسه لمزوّد الإعداد أو +واجهة CLI الخلفية، يرفض البحث عن الإعداد المالك الملتبس بدلًا من الاعتماد على +ترتيب الاكتشاف. -### ما الذي يخزنه المحمّل مؤقتًا +### ما الذي يخبّئه المُحمِّل -يحتفظ OpenClaw بمخازن مؤقتة قصيرة داخل العملية من أجل: +يحتفظ OpenClaw بذاكرات مخبئية قصيرة داخل العملية من أجل: - نتائج الاكتشاف - بيانات سجل البيان - سجلات Plugins المحمّلة -تقلل هذه المخازن المؤقتة من زيادات بدء التشغيل المفاجئة ومن كلفة الأوامر المتكررة. ويمكن -التفكير فيها بأمان على أنها مخازن مؤقتة قصيرة العمر للأداء، لا وسائل تخزين دائم. +تقلّل هذه الذاكرات المخبئية من أعباء بدء التشغيل المتقطعة وتكرار الأوامر. وهي +آمنة من حيث التفكير فيها على أنها ذواكر أداء قصيرة العمر، لا تخزين دائم. -ملاحظة أداء: +ملاحظة حول الأداء: - اضبط `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` أو - `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` لتعطيل هذه المخازن المؤقتة. -- اضبط نوافذ المخزن المؤقت عبر `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` و + `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` لتعطيل هذه الذواكر المخبئية. +- اضبط نوافذ الذاكرة المخبئية باستخدام `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` و `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## نموذج السجل -لا تعدّل Plugins المحمّلة مباشرةً متغيرات النواة العامة العشوائية. بل تسجل في -سجل مركزي لـ Plugin. +لا تقوم Plugins المحمّلة بتعديل متغيرات عامة عشوائية في النواة مباشرةً. بل +تسجّل نفسها في سجل Plugins مركزي. -يتتبع السجل: +يتتبّع السجل ما يلي: -- سجلات Plugin (الهوية، والمصدر، والمنشأ، والحالة، والتشخيصات) +- سجلات Plugins (الهوية، المصدر، المنشأ، الحالة، التشخيصات) - الأدوات -- المرابط القديمة والمرابط المطبوعة +- الخطافات القديمة والخطافات المكتوبة النوع - القنوات -- الموفّرون +- المزوّدات - معالجات Gateway RPC - مسارات HTTP - مسجّلات CLI - الخدمات الخلفية -- الأوامر المملوكة لـ Plugin +- الأوامر المملوكة للـ Plugin -ثم تقرأ ميزات النواة من هذا السجل بدلًا من التحدث إلى وحدات Plugin -مباشرة. وهذا يُبقي التحميل أحادي الاتجاه: +ثم تقرأ ميزات النواة من هذا السجل بدلًا من التحدث إلى وحدات Plugins +مباشرةً. وهذا يُبقي التحميل في اتجاه واحد: - وحدة Plugin -> التسجيل في السجل - وقت تشغيل النواة -> استهلاك السجل -هذا الفصل مهم لقابلية الصيانة. فهو يعني أن معظم أسطح النواة تحتاج فقط +هذا الفصل مهم من أجل سهولة الصيانة. فهو يعني أن معظم أسطح النواة تحتاج فقط إلى نقطة تكامل واحدة: "اقرأ السجل"، وليس "أضف حالة خاصة لكل وحدة Plugin". -## نداءات ربط المحادثة +## استدعاءات ربط المحادثة -يمكن لـ Plugins التي تربط محادثة أن تتفاعل عند حسم الموافقة. +يمكن للPlugins التي تربط محادثة أن تتفاعل عند حسم الموافقة. -استخدم `api.onConversationBindingResolved(...)` لتلقي نداء بعد الموافقة -على طلب الربط أو رفضه: +استخدم `api.onConversationBindingResolved(...)` لتلقّي استدعاء +بعد الموافقة على طلب الربط أو رفضه: ```ts export default { @@ -616,132 +626,133 @@ export default { }; ``` -حقول حمولة النداء: +حقول حمولة الاستدعاء: -- `status`: `"approved"` أو `"denied"` -- `decision`: `"allow-once"` أو `"allow-always"` أو `"deny"` +- `status`: ‏`"approved"` أو `"denied"` +- `decision`: ‏`"allow-once"` أو `"allow-always"` أو `"deny"` - `binding`: الربط المحسوم للطلبات الموافق عليها -- `request`: ملخص الطلب الأصلي، وتلميح الفك، ومعرف المرسل، و - البيانات الوصفية للمحادثة +- `request`: ملخص الطلب الأصلي، وتلميح الفصل، ومعرّف المرسل، + وبيانات المحادثة الوصفية -هذا النداء مخصص للإشعار فقط. فهو لا يغير من يُسمح له بربط +هذا الاستدعاء مخصص للإشعار فقط. وهو لا يغيّر من يُسمح له بربط محادثة، ويعمل بعد انتهاء معالجة الموافقة في النواة. -## مرابط وقت تشغيل الموفّر +## خطافات وقت تشغيل المزوّد -أصبح لدى Plugins الموفّر الآن طبقتان: +تحتوي Plugins المزوّد الآن على طبقتين: -- بيانات البيان الوصفية: `providerAuthEnvVars` لبحث مصادقة الموفّر عبر البيئة - منخفض الكلفة قبل تحميل وقت التشغيل، و`providerAuthAliases` لمتغيرات الموفّر - التي تشترك في المصادقة، و`channelEnvVars` لبحث القناة/الإعداد عبر البيئة - منخفض الكلفة قبل تحميل وقت التشغيل، بالإضافة إلى `providerAuthChoices` - لتسميات الاختيار الخاصة بالتهيئة/المصادقة وبيانات أعلام CLI الوصفية منخفضة الكلفة قبل تحميل وقت التشغيل -- مرابط وقت الإعداد: `catalog` / `discovery` القديم بالإضافة إلى `applyConfigDefaults` -- مرابط وقت التشغيل: `normalizeModelId` و`normalizeTransport`، +- بيانات البيان الوصفية: `providerAuthEnvVars` لبحث مصادقة المزوّد عبر البيئة + بتكلفة منخفضة قبل تحميل وقت التشغيل، و`providerAuthAliases` لمتغيرات + المزوّد التي تشترك في المصادقة، و`channelEnvVars` لبحث + القناة عبر البيئة/الإعداد بتكلفة منخفضة قبل تحميل وقت التشغيل، + بالإضافة إلى `providerAuthChoices` لتسميات الإعداد/اختيار المصادقة منخفضة التكلفة وبيانات + وصف خيارات CLI قبل تحميل وقت التشغيل +- خطافات وقت الإعداد: `catalog` / ‏`discovery` القديم إضافةً إلى `applyConfigDefaults` +- خطافات وقت التشغيل: `normalizeModelId` و`normalizeTransport`، و`normalizeConfig`، - و`applyNativeStreamingUsageCompat` و`resolveConfigApiKey`، - و`resolveSyntheticAuth` و`resolveExternalAuthProfiles`، + و`applyNativeStreamingUsageCompat`، و`resolveConfigApiKey`، + و`resolveSyntheticAuth`، و`resolveExternalAuthProfiles`، و`shouldDeferSyntheticProfileAuth`، - و`resolveDynamicModel` و`prepareDynamicModel` و`normalizeResolvedModel`، - و`contributeResolvedModelCompat` و`capabilities`، - و`normalizeToolSchemas` و`inspectToolSchemas`، - و`resolveReasoningOutputMode` و`prepareExtraParams` و`createStreamFn`، - و`wrapStreamFn` و`resolveTransportTurnState`، - و`resolveWebSocketSessionPolicy` و`formatApiKey` و`refreshOAuth`، - و`buildAuthDoctorHint` و`matchesContextOverflowError`، - و`classifyFailoverReason` و`isCacheTtlEligible`، - و`buildMissingAuthMessage` و`suppressBuiltInModel` و`augmentModelCatalog`، - و`isBinaryThinking` و`supportsXHighThinking`، - و`resolveDefaultThinkingLevel` و`isModernModelRef` و`prepareRuntimeAuth`، - و`resolveUsageAuth` و`fetchUsageSnapshot` و`createEmbeddingProvider`، + و`resolveDynamicModel`، و`prepareDynamicModel`، و`normalizeResolvedModel`، + و`contributeResolvedModelCompat`، و`capabilities`، + و`normalizeToolSchemas`، و`inspectToolSchemas`، + و`resolveReasoningOutputMode`، و`prepareExtraParams`، و`createStreamFn`، + و`wrapStreamFn`، و`resolveTransportTurnState`، + و`resolveWebSocketSessionPolicy`، و`formatApiKey`، و`refreshOAuth`، + و`buildAuthDoctorHint`، و`matchesContextOverflowError`، + و`classifyFailoverReason`، و`isCacheTtlEligible`، + و`buildMissingAuthMessage`، و`suppressBuiltInModel`، و`augmentModelCatalog`، + و`isBinaryThinking`، و`supportsXHighThinking`، + و`resolveDefaultThinkingLevel`، و`isModernModelRef`، و`prepareRuntimeAuth`، + و`resolveUsageAuth`، و`fetchUsageSnapshot`، و`createEmbeddingProvider`، و`buildReplayPolicy`، - و`sanitizeReplayHistory` و`validateReplayTurns` و`onModelSelected` + و`sanitizeReplayHistory`، و`validateReplayTurns`، و`onModelSelected` -لا يزال OpenClaw يملك حلقة الوكيل العامة، والتحويل الاحتياطي، ومعالجة -التفريغ، وسياسة الأدوات. وتمثل هذه المرابط سطح التوسعة الخاص بالسلوك -الخاص بالموفّر من دون الحاجة إلى نقل استدلال مخصص كامل. +لا يزال OpenClaw يملك حلقة الوكيل العامة، والتبديل عند الفشل، والتعامل مع +النصوص، وسياسة الأدوات. وتمثل هذه الخطافات سطح التوسعة للسلوك +الخاص بالمزوّد من دون الحاجة إلى ناقل استدلال مخصص كامل. -استخدم `providerAuthEnvVars` في البيان عندما يكون لدى الموفّر بيانات اعتماد -قائمة على البيئة يجب أن تراها مسارات المصادقة/الحالة/منتقي النماذج العامة من دون تحميل -وقت تشغيل Plugin. واستخدم `providerAuthAliases` في البيان عندما يجب على -معرف موفّر واحد إعادة استخدام متغيرات البيئة وملفات تعريف المصادقة -والمصادقة المعتمدة على الإعداد وخيار تهيئة مفتاح API الخاص -بمعرف موفّر آخر. واستخدم `providerAuthChoices` في البيان عندما ينبغي لأسطح -CLI الخاصة بالتهيئة/اختيار المصادقة أن تعرف معرف اختيار الموفّر، وتسميات المجموعات، -وتوصيل المصادقة البسيط أحادي العلم من دون تحميل وقت تشغيل الموفّر. وأبقِ -`envVars` في وقت تشغيل الموفّر لتلميحات موجّهة للمشغل مثل تسميات -التهيئة أو متغيرات إعداد `client-id`/`client-secret` الخاصة بـ OAuth. +استخدم `providerAuthEnvVars` في البيان عندما يكون لدى المزوّد بيانات اعتماد +معتمدة على البيئة ينبغي أن تراها مسارات المصادقة/الحالة/منتقي النموذج العامة +من دون تحميل وقت تشغيل Plugin. استخدم `providerAuthAliases` في البيان عندما +يجب أن يعيد معرّف مزوّد واحد استخدام متغيرات البيئة وملفات تعريف المصادقة +والمصادقة المعتمدة على الإعداد وخيار إعداد مفتاح API لمعرّف مزوّد آخر. استخدم +`providerAuthChoices` في البيان عندما ينبغي لأسطح CLI الخاصة بالإعداد/اختيار المصادقة +أن تعرف معرّف الاختيار الخاص بالمزوّد وتسميات المجموعات وربط المصادقة +البسيط بعلم واحد من دون تحميل وقت تشغيل المزوّد. احتفظ بـ `envVars` وقت تشغيل المزوّد +لتلميحات موجّهة للمشغّل مثل تسميات الإعداد أو متغيرات إعداد +OAuth client-id/client-secret. استخدم `channelEnvVars` في البيان عندما تكون لدى القناة مصادقة أو إعداد -يعتمد على البيئة ويجب أن تراه آليات الرجوع العامة إلى بيئة الصدفة، أو فحوصات -الإعداد/الحالة، أو مطالبات الإعداد من دون تحميل وقت تشغيل القناة. +مدفوع بالبيئة ينبغي أن تراه آليات الرجوع العامة إلى متغيرات بيئة shell +أو فحوصات الإعداد/الحالة أو مطالبات الإعداد من دون تحميل وقت تشغيل القناة. -### ترتيب المرابط واستخدامها +### ترتيب الخطافات وطريقة استخدامها -بالنسبة إلى Plugins النماذج/الموفّرين، يستدعي OpenClaw المرابط بهذا الترتيب التقريبي. -يمثل العمود "متى يُستخدم" دليل القرار السريع. +بالنسبة إلى Plugins النماذج/المزوّدات، يستدعي OpenClaw الخطافات تقريبًا بهذا الترتيب. +يمثل عمود "متى يُستخدم" دليل القرار السريع. -| # | المرابط | ما الذي يفعله | متى يُستخدم | -| --- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | نشر إعداد الموفّر في `models.providers` أثناء توليد `models.json` | عندما يملك الموفّر فهرسًا أو إعدادات افتراضية أساسية لـ URL | -| 2 | `applyConfigDefaults` | تطبيق الإعدادات الافتراضية العامة المملوكة للموفّر أثناء تجسيد الإعداد | عندما تعتمد الإعدادات الافتراضية على وضع المصادقة أو البيئة أو دلالات عائلة نماذج الموفّر | -| -- | _(البحث عن النموذج المدمج)_ | يحاول OpenClaw أولًا مسار السجل/الفهرس العادي | _(ليس مرابط Plugin)_ | -| 3 | `normalizeModelId` | تطبيع الأسماء المستعارة القديمة أو التجريبية لمعرّف النموذج قبل البحث | عندما يملك الموفّر تنظيف الأسماء المستعارة قبل حل النموذج القياسي | -| 4 | `normalizeTransport` | تطبيع `api` / `baseUrl` الخاصين بعائلة الموفّر قبل التجميع العام للنموذج | عندما يملك الموفّر تنظيف النقل لمعرفات الموفّرين المخصصة ضمن عائلة النقل نفسها | -| 5 | `normalizeConfig` | تطبيع `models.providers.` قبل حل وقت التشغيل/الموفّر | عندما يحتاج الموفّر إلى تنظيف إعداد يجب أن يبقى مع Plugin؛ كما تدعم مساعدات عائلة Google المجمعة إدخالات إعداد Google المدعومة احتياطيًا | -| 6 | `applyNativeStreamingUsageCompat` | تطبيق إعادات كتابة توافق استخدام البث الأصلي على موفّري الإعداد | عندما يحتاج الموفّر إلى إصلاحات بيانات وصفية لاستخدام البث الأصلي مدفوعة بنقطة النهاية | -| 7 | `resolveConfigApiKey` | حل مصادقة علامة البيئة لموفّري الإعداد قبل تحميل مصادقة وقت التشغيل | عندما يملك الموفّر حل مفتاح API بعلامة البيئة خاصًا به؛ كما يملك `amazon-bedrock` هنا محللًا مدمجًا لعلامة بيئة AWS | -| 8 | `resolveSyntheticAuth` | إظهار المصادقة المحلية/المستضافة ذاتيًا أو المعتمدة على الإعداد من دون حفظ النص الصريح | عندما يمكن للموفّر العمل باستخدام علامة اعتماد اصطناعية/محلية | -| 9 | `resolveExternalAuthProfiles` | تراكب ملفات تعريف المصادقة الخارجية المملوكة للموفّر؛ تكون قيمة `persistence` الافتراضية `runtime-only` لاعتمادات CLI/التطبيق المملوكة | عندما يعيد الموفّر استخدام بيانات اعتماد المصادقة الخارجية من دون حفظ رموز تحديث منسوخة | -| 10 | `shouldDeferSyntheticProfileAuth` | خفض أولوية العناصر النائبة الاصطناعية المخزنة في ملفات التعريف خلف المصادقة المعتمدة على البيئة/الإعداد | عندما يخزن الموفّر ملفات تعريف نائبة اصطناعية لا ينبغي أن تتقدم في الأولوية | -| 11 | `resolveDynamicModel` | بديل متزامن لمعرفات النماذج المملوكة للموفّر غير الموجودة بعد في السجل المحلي | عندما يقبل الموفّر معرفات نماذج upstream عشوائية | -| 12 | `prepareDynamicModel` | تهيئة غير متزامنة، ثم يُشغَّل `resolveDynamicModel` مرة أخرى | عندما يحتاج الموفّر إلى بيانات وصفية شبكية قبل حل المعرفات غير المعروفة | -| 13 | `normalizeResolvedModel` | إعادة كتابة نهائية قبل أن يستخدم المشغّل المضمّن النموذج المحلول | عندما يحتاج الموفّر إلى إعادات كتابة للنقل مع الاستمرار في استخدام نقل أساسي | -| 14 | `contributeResolvedModelCompat` | المساهمة بأعلام توافق لنماذج المورّد خلف نقل متوافق آخر | عندما يتعرف الموفّر على نماذجه الخاصة على عمليات نقل وكيلة من دون الاستيلاء على الموفّر | -| 15 | `capabilities` | بيانات وصفية للتفريغ/الأدوات مملوكة للموفّر تستخدمها منطق النواة المشتركة | عندما يحتاج الموفّر إلى خصائص تفريغ/عائلة موفّر خاصة | -| 16 | `normalizeToolSchemas` | تطبيع مخططات الأدوات قبل أن يراها المشغّل المضمّن | عندما يحتاج الموفّر إلى تنظيف مخططات خاص بعائلة النقل | -| 17 | `inspectToolSchemas` | إظهار تشخيصات المخططات المملوكة للموفّر بعد التطبيع | عندما يريد الموفّر تحذيرات للكلمات المفتاحية من دون تعليم النواة قواعد خاصة بالموفّر | -| 18 | `resolveReasoningOutputMode` | اختيار عقد مخرجات الاستدلال الأصلي مقابل المعلّم | عندما يحتاج الموفّر إلى استدلال معلّم/مخرجات نهائية بدلًا من الحقول الأصلية | -| 19 | `prepareExtraParams` | تطبيع معاملات الطلب قبل أغلفة خيارات البث العامة | عندما يحتاج الموفّر إلى معاملات طلب افتراضية أو تنظيف معاملات خاص بكل موفّر | -| 20 | `createStreamFn` | استبدال مسار البث العادي بالكامل بنقل مخصص | عندما يحتاج الموفّر إلى بروتوكول wire مخصص، لا مجرد غلاف | -| 21 | `wrapStreamFn` | غلاف للبث بعد تطبيق الأغلفة العامة | عندما يحتاج الموفّر إلى أغلفة توافق للرؤوس/جسم الطلب/النموذج من دون نقل مخصص | -| 22 | `resolveTransportTurnState` | إرفاق رؤوس أو بيانات وصفية أصلية لكل دور في النقل | عندما يريد الموفّر أن ترسل عمليات النقل العامة هوية الدور الأصلية الخاصة بالموفّر | -| 23 | `resolveWebSocketSessionPolicy` | إرفاق رؤوس WebSocket أصلية أو سياسة تهدئة الجلسة | عندما يريد الموفّر أن تضبط عمليات نقل WS العامة رؤوس الجلسة أو سياسة الرجوع الاحتياطي | -| 24 | `formatApiKey` | منسّق ملف تعريف المصادقة: يتحول ملف التعريف المخزن إلى سلسلة `apiKey` في وقت التشغيل | عندما يخزن الموفّر بيانات وصفية إضافية للمصادقة ويحتاج إلى شكل رمز وقت تشغيل مخصص | -| 25 | `refreshOAuth` | تجاوز تحديث OAuth لنقاط نهاية التحديث المخصصة أو سياسة فشل التحديث | عندما لا يناسب الموفّر محدّثات `pi-ai` المشتركة | -| 26 | `buildAuthDoctorHint` | تلميح إصلاح يُلحق عند فشل تحديث OAuth | عندما يحتاج الموفّر إلى إرشادات إصلاح مصادقة مملوكة له بعد فشل التحديث | -| 27 | `matchesContextOverflowError` | مطابِق تجاوز نافذة السياق المملوك للموفّر | عندما تكون لدى الموفّر أخطاء تجاوز خام لا تلتقطها الاستدلالات العامة | -| 28 | `classifyFailoverReason` | تصنيف سبب التحويل الاحتياطي المملوك للموفّر | عندما يستطيع الموفّر تعيين أخطاء API/النقل الخام إلى تجاوز الحد/الحمل الزائد/إلخ | -| 29 | `isCacheTtlEligible` | سياسة TTL لذاكرة التخزين المؤقت لموفّري الوكيل/الترحيل | عندما يحتاج الموفّر إلى بوابة TTL خاصة بالوكيل | -| 30 | `buildMissingAuthMessage` | بديل لرسالة استرداد المصادقة المفقودة العامة | عندما يحتاج الموفّر إلى تلميح استرداد خاص بالمصادقة المفقودة | -| 31 | `suppressBuiltInModel` | إخفاء النماذج القديمة من upstream مع تلميح اختياري موجّه للمستخدم | عندما يحتاج الموفّر إلى إخفاء صفوف upstream القديمة أو استبدالها بتلميح خاص بالمورّد | -| 32 | `augmentModelCatalog` | صفوف فهرس اصطناعية/نهائية تُلحق بعد الاكتشاف | عندما يحتاج الموفّر إلى صفوف اصطناعية للتوافق المستقبلي في `models list` ومنتقيات النماذج | -| 33 | `isBinaryThinking` | تبديل تشغيل/إيقاف للاستدلال لدى الموفّرين ذوي التفكير الثنائي | عندما يوفّر الموفّر تفكيرًا ثنائيًا تشغيل/إيقاف فقط | -| 34 | `supportsXHighThinking` | دعم الاستدلال `xhigh` لنماذج محددة | عندما يريد الموفّر توفير `xhigh` لجزء فقط من النماذج | -| 35 | `resolveDefaultThinkingLevel` | مستوى `/think` الافتراضي لعائلة نماذج محددة | عندما يملك الموفّر سياسة `/think` الافتراضية لعائلة نماذج | -| 36 | `isModernModelRef` | مطابِق النماذج الحديثة لمرشحات الملفات الحية واختيار الاختبار السريع | عندما يملك الموفّر مطابقة النموذج المفضل للاختبارات الحية/السريعة | -| 37 | `prepareRuntimeAuth` | تبادل اعتماد مُعد مسبقًا إلى الرمز/المفتاح الفعلي في وقت التشغيل مباشرة قبل الاستدلال | عندما يحتاج الموفّر إلى تبادل رمز أو اعتماد طلب قصير العمر | -| 38 | `resolveUsageAuth` | حل بيانات اعتماد الاستخدام/الفوترة لأجل `/usage` والأسطح الأخرى ذات الصلة بالحالة | عندما يحتاج الموفّر إلى تحليل مخصص لرمز الاستخدام/الحصة أو إلى بيانات اعتماد استخدام مختلفة | -| 39 | `fetchUsageSnapshot` | جلب لقطات الاستخدام/الحصة الخاصة بالموفّر وتطبيعها بعد حل المصادقة | عندما يحتاج الموفّر إلى نقطة نهاية استخدام خاصة به أو إلى محلل حمولة خاص بها | -| 40 | `createEmbeddingProvider` | بناء مهايئ تضمين مملوك للموفّر لأجل الذاكرة/البحث | عندما ينتمي سلوك تضمين الذاكرة إلى Plugin الموفّر | -| 41 | `buildReplayPolicy` | إرجاع سياسة إعادة تشغيل تتحكم في معالجة التفريغ الخاصة بالموفّر | عندما يحتاج الموفّر إلى سياسة تفريغ مخصصة (على سبيل المثال، إزالة كتل التفكير) | -| 42 | `sanitizeReplayHistory` | إعادة كتابة سجل إعادة التشغيل بعد التنظيف العام للتفريغ | عندما يحتاج الموفّر إلى إعادات كتابة خاصة بإعادة التشغيل تتجاوز مساعدات Compaction المشتركة | -| 43 | `validateReplayTurns` | التحقق النهائي من أدوار إعادة التشغيل أو إعادة تشكيلها قبل المشغّل المضمّن | عندما يحتاج نقل الموفّر إلى تحقق أشد صرامة من الأدوار بعد التنقية العامة | -| 44 | `onModelSelected` | تشغيل آثار جانبية مملوكة للموفّر بعد اختيار النموذج | عندما يحتاج الموفّر إلى القياس عن بُعد أو إلى حالة مملوكة له عند تفعيل نموذج ما | +| # | الخطاف | ما الذي يفعله | متى يُستخدم | +| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | ينشر إعدادات المزوّد في `models.providers` أثناء توليد `models.json` | عندما يملك المزوّد فهرسًا أو إعدادات افتراضية لـ base URL | +| 2 | `applyConfigDefaults` | يطبّق إعدادات افتراضية عامة مملوكة للمزوّد أثناء تشكيل الإعدادات | عندما تعتمد القيم الافتراضية على وضع المصادقة أو البيئة أو دلالات عائلة نماذج المزوّد | +| -- | _(البحث المضمّن عن النموذج)_ | يحاول OpenClaw أولًا مسار السجل/الفهرس العادي | _(ليس خطاف Plugin)_ | +| 3 | `normalizeModelId` | يطبّع الأسماء المستعارة القديمة أو التجريبية لمعرّفات النماذج قبل البحث | عندما يملك المزوّد تنظيف الأسماء المستعارة قبل الحلّ القياسي للنموذج | +| 4 | `normalizeTransport` | يطبّع `api` / `baseUrl` لعائلة المزوّد قبل التجميع العام للنموذج | عندما يملك المزوّد تنظيف النقل لمعرّفات مزوّدين مخصصة ضمن عائلة النقل نفسها | +| 5 | `normalizeConfig` | يطبّع `models.providers.` قبل حلّ وقت التشغيل/المزوّد | عندما يحتاج المزوّد إلى تنظيف إعدادات ينبغي أن يبقى مع Plugin؛ كما أن مساعدات عائلة Google المضمّنة تدعم أيضًا إدخالات إعدادات Google المدعومة | +| 6 | `applyNativeStreamingUsageCompat` | يطبّق إعادة كتابة توافق استخدام التدفق الأصلي على مزوّدي الإعدادات | عندما يحتاج المزوّد إلى إصلاحات لبيانات استخدام التدفق الأصلية تعتمد على نقطة النهاية | +| 7 | `resolveConfigApiKey` | يحلّ مصادقة واسم البيئة للمزوّدات المهيأة قبل تحميل مصادقة وقت التشغيل | عندما يملك المزوّد حلّ مفتاح API عبر واسم بيئة مملوكًا للمزوّد؛ ويحتوي `amazon-bedrock` أيضًا هنا على محلّل مضمّن لواسم بيئة AWS | +| 8 | `resolveSyntheticAuth` | يعرض المصادقة المحلية/المستضافة ذاتيًا أو المعتمدة على الإعدادات من دون حفظ نص واضح | عندما يمكن للمزوّد العمل باستخدام واسم بيانات اعتماد اصطناعي/محلي | +| 9 | `resolveExternalAuthProfiles` | يضيف طبقات من ملفات تعريف المصادقة الخارجية المملوكة للمزوّد؛ وتكون `persistence` الافتراضية هي `runtime-only` لاعتمادات CLI/التطبيق | عندما يعيد المزوّد استخدام بيانات اعتماد المصادقة الخارجية من دون حفظ رموز التحديث المنسوخة | +| 10 | `shouldDeferSyntheticProfileAuth` | يخفض أولوية العناصر النائبة المخزنة لملفات التعريف الاصطناعية مقارنةً بالمصادقة المعتمدة على البيئة/الإعدادات | عندما يخزن المزوّد ملفات تعريف اصطناعية نائبة لا ينبغي أن تسبق غيرها | +| 11 | `resolveDynamicModel` | تراجع متزامن لمعرّفات نماذج مملوكة للمزوّد ليست موجودة بعد في السجل المحلي | عندما يقبل المزوّد معرّفات نماذج عشوائية من المصدر العلوي | +| 12 | `prepareDynamicModel` | إحماء غير متزامن، ثم يُشغَّل `resolveDynamicModel` مرة أخرى | عندما يحتاج المزوّد إلى بيانات وصفية شبكية قبل حلّ المعرّفات غير المعروفة | +| 13 | `normalizeResolvedModel` | إعادة كتابة نهائية قبل أن يستخدم المشغّل المضمّن النموذج المحلول | عندما يحتاج المزوّد إلى إعادة كتابة النقل مع الاستمرار في استخدام نقل من النواة | +| 14 | `contributeResolvedModelCompat` | يضيف رايات توافق لنماذج المورّد خلف نقل متوافق آخر | عندما يتعرف المزوّد على نماذجه الخاصة على وسائل نقل وكيلة من دون أن يتولى المزوّد نفسه | +| 15 | `capabilities` | بيانات وصفية خاصة بالمزوّد للنصوص/الأدوات تستخدمها منطق النواة المشتركة | عندما يحتاج المزوّد إلى فروق خاصة بالنصوص أو بعائلة المزوّد | +| 16 | `normalizeToolSchemas` | يطبّع مخططات الأدوات قبل أن يراها المشغّل المضمّن | عندما يحتاج المزوّد إلى تنظيف مخطط خاص بعائلة النقل | +| 17 | `inspectToolSchemas` | يعرض تشخيصات مخطط مملوكة للمزوّد بعد التطبيع | عندما يريد المزوّد تحذيرات الكلمات المفتاحية من دون تعليم النواة قواعد خاصة بالمزوّد | +| 18 | `resolveReasoningOutputMode` | يحدّد عقد مخرجات الاستدلال الأصلي مقابل المعلّم بالوسوم | عندما يحتاج المزوّد إلى استدلال/مخرجات نهائية معلّمة بدلًا من الحقول الأصلية | +| 19 | `prepareExtraParams` | تطبيع بارامترات الطلب قبل مغلّفات خيارات التدفق العامة | عندما يحتاج المزوّد إلى بارامترات طلب افتراضية أو تنظيف بارامترات خاصًا بكل مزوّد | +| 20 | `createStreamFn` | يستبدل مسار التدفق العادي بالكامل بنقل مخصص | عندما يحتاج المزوّد إلى بروتوكول نقل مخصص، لا مجرد مغلّف | +| 21 | `wrapStreamFn` | مغلّف للتدفق بعد تطبيق المغلّفات العامة | عندما يحتاج المزوّد إلى مغلّفات توافق للرؤوس/الجسم/النموذج من دون نقل مخصص | +| 22 | `resolveTransportTurnState` | يرفق رؤوسًا أو بيانات وصفية أصلية لكل دور في النقل | عندما يريد المزوّد أن ترسل وسائل النقل العامة هوية الدور الأصلية الخاصة به | +| 23 | `resolveWebSocketSessionPolicy` | يرفق رؤوس WebSocket أصلية أو سياسة تهدئة للجلسة | عندما يريد المزوّد أن تضبط وسائل نقل WebSocket العامة رؤوس الجلسة أو سياسة التراجع | +| 24 | `formatApiKey` | منسّق ملف تعريف المصادقة: يتحول الملف المخزن إلى سلسلة `apiKey` لوقت التشغيل | عندما يخزن المزوّد بيانات مصادقة إضافية ويحتاج إلى شكل رمز مميز مخصص لوقت التشغيل | +| 25 | `refreshOAuth` | تجاوز تحديث OAuth لنقاط نهاية التحديث المخصصة أو لسياسة فشل التحديث | عندما لا يتوافق المزوّد مع أدوات التحديث المشتركة `pi-ai` | +| 26 | `buildAuthDoctorHint` | تلميح إصلاح يُضاف عند فشل تحديث OAuth | عندما يحتاج المزوّد إلى إرشادات إصلاح مصادقة مملوكة له بعد فشل التحديث | +| 27 | `matchesContextOverflowError` | مطابِق مملوك للمزوّد لأخطاء تجاوز نافذة السياق | عندما تكون لدى المزوّد أخطاء تجاوز خام لن تلتقطها الاستدلالات العامة | +| 28 | `classifyFailoverReason` | تصنيف مملوك للمزوّد لأسباب التبديل عند الفشل | عندما يمكن للمزوّد تحويل أخطاء API/النقل الخام إلى تصنيفات مثل حدّ المعدل/الحمل الزائد/إلخ | +| 29 | `isCacheTtlEligible` | سياسة الذاكرة المخبئية الفورية لمزوّدي الوكيل/النقل الخلفي | عندما يحتاج المزوّد إلى تقييد مدة صلاحية الذاكرة المخبئية خاص بالوكيل | +| 30 | `buildMissingAuthMessage` | بديل عن رسالة الاسترداد العامة عند غياب المصادقة | عندما يحتاج المزوّد إلى تلميح استرداد خاص به عند غياب المصادقة | +| 31 | `suppressBuiltInModel` | إخفاء النماذج القديمة من المصدر العلوي مع تلميح خطأ اختياري للمستخدم | عندما يحتاج المزوّد إلى إخفاء صفوف قديمة من المصدر العلوي أو استبدالها بتلميح خاص بالمورّد | +| 32 | `augmentModelCatalog` | صفوف فهرس اصطناعية/نهائية تُضاف بعد الاكتشاف | عندما يحتاج المزوّد إلى صفوف توافق أمامي اصطناعية في `models list` وأدوات الاختيار | +| 33 | `isBinaryThinking` | تبديل تشغيل/إيقاف الاستدلال لمزوّدي الاستدلال الثنائي | عندما يوفّر المزوّد استدلالًا ثنائيًا تشغيل/إيقاف فقط | +| 34 | `supportsXHighThinking` | دعم استدلال `xhigh` لنماذج مختارة | عندما يريد المزوّد تفعيل `xhigh` لمجموعة فرعية فقط من النماذج | +| 35 | `resolveDefaultThinkingLevel` | مستوى `/think` الافتراضي لعائلة نماذج محددة | عندما يملك المزوّد سياسة `/think` الافتراضية لعائلة نماذج | +| 36 | `isModernModelRef` | مطابقة النماذج الحديثة لمرشحات الملفات الحية واختيار اختبارات smoke | عندما يملك المزوّد مطابقة النماذج المفضلة للاختبارات الحية/اختبارات smoke | +| 37 | `prepareRuntimeAuth` | يستبدل بيانات اعتماد مهيأة بالرمز/المفتاح الفعلي لوقت التشغيل مباشرة قبل الاستدلال | عندما يحتاج المزوّد إلى تبادل رمز أو بيانات اعتماد طلب قصيرة العمر | +| 38 | `resolveUsageAuth` | يحلّ بيانات اعتماد الاستخدام/الفوترة من أجل `/usage` والأسطح ذات الصلة بالحالة | عندما يحتاج المزوّد إلى تحليل مخصص لرمز الاستخدام/الحصة أو إلى بيانات اعتماد استخدام مختلفة | +| 39 | `fetchUsageSnapshot` | يجلب ويطبّع لقطات الاستخدام/الحصة الخاصة بالمزوّد بعد حلّ المصادقة | عندما يحتاج المزوّد إلى نقطة نهاية استخدام خاصة به أو إلى محلّل حمولة خاص به | +| 40 | `createEmbeddingProvider` | يبني مهايئ embeddings مملوكًا للمزوّد من أجل الذاكرة/البحث | عندما يكون سلوك embeddings الخاص بالذاكرة مملوكًا لPlugin المزوّد | +| 41 | `buildReplayPolicy` | يعيد سياسة replay تتحكم في التعامل مع النصوص بالنسبة إلى المزوّد | عندما يحتاج المزوّد إلى سياسة نصوص مخصصة (مثل إزالة كتل التفكير) | +| 42 | `sanitizeReplayHistory` | يعيد كتابة سجل replay بعد التنظيف العام للنصوص | عندما يحتاج المزوّد إلى إعادة كتابة خاصة بـ replay تتجاوز مساعدات Compaction المشتركة | +| 43 | `validateReplayTurns` | يتحقق نهائيًا من أدوار replay أو يعيد تشكيلها قبل المشغّل المضمّن | عندما يحتاج نقل المزوّد إلى تحقق أشد من الأدوار بعد التنظيف العام | +| 44 | `onModelSelected` | يشغّل آثارًا جانبية بعد الاختيار يملكها المزوّد | عندما يحتاج المزوّد إلى telemetry أو حالة مملوكة له عند تفعيل نموذج | -يقوم `normalizeModelId` و`normalizeTransport` و`normalizeConfig` أولًا بفحص -Plugin الموفّر المطابق، ثم ينتقل إلى Plugins الموفّرين الأخرى القادرة على استخدام المرابط -حتى يغيّر أحدها فعلًا معرف النموذج أو النقل/الإعداد. وهذا يُبقي -الطبقات الوسيطة للأسماء المستعارة/التوافق الخاصة بالموفّر عاملة من دون أن يضطر المستدعي إلى معرفة -أي Plugin مجمّعة تملك إعادة الكتابة. وإذا لم يقم أي مرابط موفّر بإعادة كتابة -إدخال إعداد مدعوم من عائلة Google، فسيظل مطبّع إعداد Google المجمّع -يطبّق تنظيف التوافق هذا. +يتحقق `normalizeModelId` و`normalizeTransport` و`normalizeConfig` أولًا من +Plugin المزوّد المطابق، ثم ينتقل إلى Plugins المزوّد الأخرى القادرة على استخدام الخطافات +حتى يُحدث أحدها تغييرًا فعليًا في معرّف النموذج أو النقل/الإعدادات. ويحافظ ذلك على +عمل طبقات الأسماء المستعارة/التوافق الخاصة بالمزوّد من دون الحاجة إلى أن يعرف المستدعي +أي Plugin مضمّن يملك إعادة الكتابة. وإذا لم يُعِد أي خطاف مزوّد كتابة +إدخال إعدادات مدعوم من عائلة Google، فسيظل مطبّع إعدادات Google المضمّن يطبّق +تنظيف التوافق هذا. -إذا كان الموفّر يحتاج إلى بروتوكول wire مخصص بالكامل أو منفّذ طلبات مخصص، -فهذه فئة مختلفة من التوسعة. هذه المرابط مخصصة لسلوك الموفّر -الذي لا يزال يعمل ضمن حلقة الاستدلال العادية في OpenClaw. +إذا كان المزوّد يحتاج إلى بروتوكول سلكي مخصص بالكامل أو إلى منفّذ طلبات مخصص، +فهذه فئة مختلفة من الامتدادات. هذه الخطافات مخصصة لسلوك المزوّد الذي +لا يزال يعمل ضمن حلقة الاستدلال العادية في OpenClaw. -### مثال على موفّر +### مثال على مزوّد ```ts api.registerProvider({ @@ -795,121 +806,122 @@ api.registerProvider({ }); ``` -### أمثلة مدمجة +### أمثلة مضمّنة -- يستخدم Anthropic المرابط `resolveDynamicModel` و`capabilities` و`buildAuthDoctorHint`، +- يستخدم Anthropic الخطافات `resolveDynamicModel` و`capabilities` و`buildAuthDoctorHint`، و`resolveUsageAuth` و`fetchUsageSnapshot` و`isCacheTtlEligible`، و`resolveDefaultThinkingLevel` و`applyConfigDefaults` و`isModernModelRef`، - و`wrapStreamFn` لأنه يملك التوافق المستقبلي لـ Claude 4.6، - وتلميحات عائلة الموفّر، وإرشادات إصلاح المصادقة، وتكامل نقطة نهاية الاستخدام، - وأهلية ذاكرة التخزين المؤقت للموجّه، والإعدادات الافتراضية المعتمدة على المصادقة، وسياسة - التفكير الافتراضي/التكيفي لـ Claude، وتشكيل البث الخاص بـ Anthropic من أجل + و`wrapStreamFn` لأنه يملك توافق Claude 4.6 الأمامي، + وتلميحات عائلة المزوّد، وإرشادات إصلاح المصادقة، وتكامل نقطة نهاية الاستخدام، + وأهلية Prompt Cache، والقيم الافتراضية للإعدادات المدركة للمصادقة، وسياسة + التفكير الافتراضي/التكيفي لـ Claude، وتشكيل التدفق الخاص بـ Anthropic من أجل رؤوس beta، و`/fast` / `serviceTier`، و`context1m`. -- تبقى مساعدات البث الخاصة بـ Claude في Anthropic حاليًا ضمن الحد العام - `api.ts` / `contract-api.ts` الخاص بـ Plugin المجمّعة نفسها. إذ يصدّر سطح - الحزمة هذا `wrapAnthropicProviderStream` و`resolveAnthropicBetas`، - و`resolveAnthropicFastMode` و`resolveAnthropicServiceTier`، إضافة إلى - بُناة أغلفة Anthropic الأدنى مستوى بدلًا من توسيع SDK العامة حول - قواعد رؤوس beta الخاصة بموفّر واحد. -- تستخدم OpenAI المرابط `resolveDynamicModel` و`normalizeResolvedModel` و - `capabilities` بالإضافة إلى `buildMissingAuthMessage` و`suppressBuiltInModel`، +- تبقى مساعدات التدفق الخاصة بـ Claude في Anthropic ضمن + الحدّ العام `api.ts` / `contract-api.ts` الخاص بالPlugin المضمّن نفسه في الوقت الحالي. ويصدّر + سطح الحزمة هذا `wrapAnthropicProviderStream` و`resolveAnthropicBetas`، + و`resolveAnthropicFastMode` و`resolveAnthropicServiceTier`، وبناة + مغلّفات Anthropic منخفضة المستوى بدلًا من توسيع SDK العامة حول + قواعد رؤوس beta الخاصة بمزوّد واحد. +- يستخدم OpenAI الخطافات `resolveDynamicModel` و`normalizeResolvedModel` و + `capabilities` إضافةً إلى `buildMissingAuthMessage` و`suppressBuiltInModel`، و`augmentModelCatalog` و`supportsXHighThinking` و`isModernModelRef` - لأنها تملك التوافق المستقبلي لـ GPT-5.4، وتطبيع - `openai-completions` -> `openai-responses` المباشر الخاص بـ OpenAI، - وتلميحات المصادقة الواعية بـ Codex، وإخفاء Spark، وصفوف قائمة OpenAI الاصطناعية، - وسياسة التفكير/النموذج الحي لـ GPT-5؛ بينما تملك عائلة البث - `openai-responses-defaults` أغلفة OpenAI Responses الأصلية المشتركة من أجل - رؤوس الإسناد، و`/fast`/`serviceTier`، وإسهاب النص، وبحث الويب الأصلي لـ Codex، + لأنه يملك توافق GPT-5.4 الأمامي، وتطبيع OpenAI المباشر من + `openai-completions` -> `openai-responses`، وتلميحات المصادقة المدركة لـ Codex، + وإخفاء Spark، وصفوف قائمة OpenAI الاصطناعية، وسياسة التفكير / النماذج الحية لـ GPT-5؛ + كما تملك عائلة تدفقات `openai-responses-defaults` + مغلّفات OpenAI Responses الأصلية المشتركة لرؤوس الإسناد، + و`/fast`/`serviceTier`، وإسهاب النص، وبحث الويب الأصلي في Codex، وتشكيل حمولة توافق الاستدلال، وإدارة سياق Responses. -- تستخدم OpenRouter المرابط `catalog` بالإضافة إلى `resolveDynamicModel` و - `prepareDynamicModel` لأن الموفّر تمريري وقد يكشف معرفات نماذج جديدة قبل - تحديثات الفهرس الثابت في OpenClaw؛ كما يستخدم +- يستخدم OpenRouter `catalog` إضافةً إلى `resolveDynamicModel` و + `prepareDynamicModel` لأن المزوّد يعمل كوسيط وقد يعرض + معرّفات نماذج جديدة قبل تحديث الفهرس الثابت في OpenClaw؛ كما يستخدم `capabilities` و`wrapStreamFn` و`isCacheTtlEligible` لإبقاء - رؤوس الطلب الخاصة بالموفّر، وبيانات التوجيه الوصفية، ورقع الاستدلال، وسياسة - ذاكرة التخزين المؤقت للموجّه خارج النواة. وتأتي سياسة إعادة التشغيل الخاصة به من - عائلة `passthrough-gemini`، بينما تملك عائلة البث `openrouter-thinking` - حقن الاستدلال الوكيل وتخطي النماذج غير المدعومة / `auto`. -- يستخدم GitHub Copilot المرابط `catalog` و`auth` و`resolveDynamicModel` و - `capabilities` بالإضافة إلى `prepareRuntimeAuth` و`fetchUsageSnapshot` لأنه - يحتاج إلى تسجيل دخول الجهاز المملوك للموفّر، وسلوك الرجوع إلى النماذج، - وخصائص تفريغ Claude، وتبادل رمز GitHub إلى رمز Copilot، ونقطة نهاية - استخدام مملوكة للموفّر. -- يستخدم OpenAI Codex المرابط `catalog` و`resolveDynamicModel`، - و`normalizeResolvedModel` و`refreshOAuth` و`augmentModelCatalog` بالإضافة - إلى `prepareExtraParams` و`resolveUsageAuth` و`fetchUsageSnapshot` لأنه - لا يزال يعمل على عمليات نقل OpenAI الأساسية لكنه يملك - تطبيع النقل/‏base URL، وسياسة الرجوع الاحتياطي لتحديث OAuth، واختيار النقل الافتراضي، - وصفوف فهرس Codex الاصطناعية، وتكامل نقطة نهاية استخدام ChatGPT؛ وهو - يشارك عائلة البث `openai-responses-defaults` نفسها مع OpenAI المباشرة. -- تستخدم Google AI Studio وGemini CLI OAuth المرابط `resolveDynamicModel`، + رؤوس الطلبات الخاصة بالمزوّد وبيانات التوجيه الوصفية وتصحيحات الاستدلال وسياسة + Prompt Cache خارج النواة. وتأتي سياسة replay الخاصة به من + عائلة `passthrough-gemini`، بينما تملك عائلة التدفقات `openrouter-thinking` + حقن الاستدلال الوكيل وتخطّي النماذج غير المدعومة / `auto`. +- يستخدم GitHub Copilot `catalog` و`auth` و`resolveDynamicModel` و + `capabilities` إضافةً إلى `prepareRuntimeAuth` و`fetchUsageSnapshot` لأنه + يحتاج إلى تسجيل دخول جهاز مملوك للمزوّد، وسلوك تراجع النماذج، وفروق + نصوص Claude، وتبادل GitHub token -> Copilot token، + ونقطة نهاية استخدام يملكها المزوّد. +- يستخدم OpenAI Codex `catalog` و`resolveDynamicModel`، + و`normalizeResolvedModel` و`refreshOAuth` و`augmentModelCatalog` إضافةً إلى + `prepareExtraParams` و`resolveUsageAuth` و`fetchUsageSnapshot` لأنه + لا يزال يعمل على وسائل نقل OpenAI الأساسية لكنه يملك + تطبيع النقل/‏base URL، وسياسة التراجع في تحديث OAuth، واختيار النقل + الافتراضي، وصفوف فهرس Codex الاصطناعية، وتكامل نقطة نهاية استخدام ChatGPT؛ كما + يشارك عائلة التدفقات `openai-responses-defaults` نفسها مع OpenAI المباشر. +- يستخدم Google AI Studio وGemini CLI OAuth الخطافات `resolveDynamicModel`، و`buildReplayPolicy`، و`sanitizeReplayHistory`، و`resolveReasoningOutputMode`، و`wrapStreamFn`، و`isModernModelRef` لأن - عائلة إعادة التشغيل `google-gemini` تملك الرجوع الاحتياطي للتوافق المستقبلي لـ Gemini 3.1، - والتحقق الأصلي من إعادة تشغيل Gemini، وتنقية إعادة تشغيل bootstrap، + عائلة replay `google-gemini` تملك تراجع التوافق الأمامي لـ Gemini 3.1، + والتحقق الأصلي من replay في Gemini، وتنظيف replay الأولي، ووضع مخرجات الاستدلال المعلّم، ومطابقة النماذج الحديثة، بينما - تملك عائلة البث `google-thinking` تطبيع حمولة تفكير Gemini؛ - كما يستخدم Gemini CLI OAuth أيضًا `formatApiKey` و`resolveUsageAuth` و - `fetchUsageSnapshot` لتنسيق الرمز، وتحليل الرمز، وتوصيل نقطة نهاية - الحصة. + تملك عائلة التدفقات `google-thinking` تطبيع حمولة التفكير في Gemini؛ + كما يستخدم Gemini CLI OAuth الخطافات `formatApiKey` و`resolveUsageAuth` و + `fetchUsageSnapshot` لتنسيق الرمز، وتحليل الرمز، وربط نقطة نهاية الحصة. - يستخدم Anthropic Vertex `buildReplayPolicy` عبر - عائلة إعادة التشغيل `anthropic-by-model` بحيث يبقى تنظيف إعادة التشغيل الخاص بـ Claude - محصورًا ضمن معرفات Claude بدلًا من كل نقل `anthropic-messages`. + عائلة replay ‏`anthropic-by-model` حتى يبقى تنظيف replay + الخاص بـ Claude مقيّدًا بمعرّفات Claude بدلًا من كل وسائل النقل `anthropic-messages`. - يستخدم Amazon Bedrock `buildReplayPolicy` و`matchesContextOverflowError`، و`classifyFailoverReason`، و`resolveDefaultThinkingLevel` لأنه يملك - التصنيف الخاص بـ Bedrock لأخطاء الاختناق/عدم الجاهزية/تجاوز السياق - الخاصة بحركة Anthropic-on-Bedrock؛ وما تزال سياسة إعادة التشغيل لديه تشترك في - الحارس الخاص بـ Claude فقط نفسه `anthropic-by-model`. -- تستخدم OpenRouter وKilocode وOpencode وOpencode Go المرابط `buildReplayPolicy` - عبر عائلة إعادة التشغيل `passthrough-gemini` لأنها توكّل نماذج Gemini - عبر عمليات نقل متوافقة مع OpenAI وتحتاج إلى - تنقية thought-signature الخاصة بـ Gemini من دون التحقق الأصلي من إعادة تشغيل Gemini أو - إعادات كتابة bootstrap. -- يستخدم MiniMax `buildReplayPolicy` عبر - عائلة إعادة التشغيل `hybrid-anthropic-openai` لأن موفّرًا واحدًا يملك كِلا - دلالتي رسائل Anthropic وOpenAI-compatible؛ فهو يُبقي - إسقاط كتل التفكير الخاصة بـ Claude فقط على جانب Anthropic مع إعادة تجاوز وضع - مخرجات الاستدلال إلى الوضع الأصلي، بينما تملك عائلة البث `minimax-fast-mode` - إعادات كتابة نماذج الوضع السريع على مسار البث المشترك. -- يستخدم Moonshot `catalog` بالإضافة إلى `wrapStreamFn` لأنه لا يزال يستخدم - نقل OpenAI المشترك لكنه يحتاج إلى تطبيع حمولة التفكير المملوك للموفّر؛ - إذ تعيّن عائلة البث `moonshot-thinking` الإعداد بالإضافة إلى حالة `/think` إلى - حمولة التفكير الثنائية الأصلية الخاصة بها. -- يستخدم Kilocode المرابط `catalog` و`capabilities` و`wrapStreamFn` و - `isCacheTtlEligible` لأنه يحتاج إلى رؤوس طلبات مملوكة للموفّر، - وتطبيع حمولة الاستدلال، وتلميحات تفريغ Gemini، وبوابة TTL الخاصة بذاكرة Anthropic - المؤقتة؛ وتُبقي عائلة البث `kilocode-thinking` حقن التفكير الخاص بـ Kilo - على مسار البث الوكيل المشترك مع تخطي `kilo/auto` و - معرفات النماذج الوكيلة الأخرى التي لا تدعم حمولات الاستدلال الصريحة. -- تستخدم Z.AI المرابط `resolveDynamicModel` و`prepareExtraParams` و`wrapStreamFn`، + تصنيف أخطاء Bedrock الخاصة بالخنق/عدم الجاهزية/تجاوز السياق + لحركة Anthropic-on-Bedrock؛ بينما لا تزال سياسة replay الخاصة به تشارك + حارس `anthropic-by-model` المخصّص لـ Claude فقط. +- يستخدم OpenRouter وKilocode وOpencode وOpencode Go الخطاف `buildReplayPolicy` + عبر عائلة replay ‏`passthrough-gemini` لأنهم يمررون نماذج Gemini + عبر وسائل نقل متوافقة مع OpenAI ويحتاجون إلى + تنظيف thought-signature في Gemini من دون تحقق replay أصلي لـ Gemini أو + إعادة كتابة أولية. +- يستخدم MiniMax الخطاف `buildReplayPolicy` عبر + عائلة replay ‏`hybrid-anthropic-openai` لأن مزوّدًا واحدًا يملك كلاً من + دلالات Anthropic-message والدلالات المتوافقة مع OpenAI؛ إذ يبقي + إسقاط كتل التفكير الخاصة بـ Claude على جانب Anthropic مع تجاوز وضع + مخرجات الاستدلال إلى الوضع الأصلي، بينما تملك عائلة التدفقات `minimax-fast-mode` + إعادة كتابة نماذج fast-mode على مسار التدفق المشترك. +- يستخدم Moonshot `catalog` إضافةً إلى `wrapStreamFn` لأنه لا يزال يستخدم + نقل OpenAI المشترك لكنه يحتاج إلى تطبيع حمولة التفكير المملوكة للمزوّد؛ كما + تربط عائلة التدفقات `moonshot-thinking` الإعدادات مع حالة `/think` بحمولة + التفكير الثنائية الأصلية الخاصة بها. +- يستخدم Kilocode الخطافات `catalog` و`capabilities` و`wrapStreamFn` و + `isCacheTtlEligible` لأنه يحتاج إلى رؤوس طلبات مملوكة للمزوّد، + وتطبيع حمولة الاستدلال، وتلميحات نصوص Gemini، وتقييد TTL الخاص بذاكرة Anthropic المخبئية؛ + كما تحافظ عائلة التدفقات `kilocode-thinking` على حقن التفكير في Kilo + ضمن مسار التدفق الوكيل المشترك مع تخطي `kilo/auto` و + معرّفات نماذج وكيلة أخرى لا تدعم حمولات الاستدلال الصريحة. +- يستخدم Z.AI الخطافات `resolveDynamicModel` و`prepareExtraParams` و`wrapStreamFn`، و`isCacheTtlEligible` و`isBinaryThinking` و`isModernModelRef`، - و`resolveUsageAuth` و`fetchUsageSnapshot` لأنها تملك الرجوع الاحتياطي لـ GLM-5، - والإعدادات الافتراضية `tool_stream`، وتجربة التفكير الثنائية، ومطابقة النماذج الحديثة، وكِلا - مصادقة الاستخدام + جلب الحصة؛ بينما تُبقي عائلة البث `tool-stream-default-on` - غلاف `tool_stream` المُفعَّل افتراضيًا خارج الوصل المكتوب يدويًا لكل موفّر. -- تستخدم xAI المرابط `normalizeResolvedModel` و`normalizeTransport`، + و`resolveUsageAuth` و`fetchUsageSnapshot` لأنه يملك تراجع GLM-5، + والقيم الافتراضية لـ `tool_stream`، وتجربة الاستخدام الخاصة بالتفكير الثنائي، + ومطابقة النماذج الحديثة، وكذلك مصادقة الاستخدام وجلب الحصة؛ بينما + تُبقي عائلة التدفقات `tool-stream-default-on` + مغلّف `tool_stream` الافتراضي المُفعّل بعيدًا عن الربط اليدوي لكل مزوّد. +- يستخدم xAI الخطافات `normalizeResolvedModel` و`normalizeTransport`، و`contributeResolvedModelCompat` و`prepareExtraParams` و`wrapStreamFn`، و`resolveSyntheticAuth` و`resolveDynamicModel` و`isModernModelRef` - لأنها تملك تطبيع نقل xAI Responses الأصلي، وإعادات كتابة الأسماء المستعارة - للوضع السريع في Grok، و`tool_stream` الافتراضي، وتنظيف - strict-tool / حمولة الاستدلال، وإعادة استخدام مصادقة الرجوع الاحتياطي للأدوات المملوكة لـ Plugin، - وحل نماذج Grok المتوافق مستقبليًا، ورقع التوافق المملوكة للموفّر مثل - ملف تعريف مخطط أدوات xAI، والكلمات المفتاحية غير المدعومة في المخطط، و`web_search` الأصلي، - وفك ترميز وسائط استدعاء الأدوات لكيانات HTML. -- تستخدم Mistral وOpenCode Zen وOpenCode Go المرابط `capabilities` فقط - لإبقاء خصائص التفريغ/الأدوات خارج النواة. -- يستخدم موفّرو الحزم المجمّعة المعتمدون على الفهرس فقط مثل `byteplus` و`cloudflare-ai-gateway`، + لأنه يملك تطبيع نقل xAI Responses الأصلي، وإعادة كتابة + الأسماء المستعارة لـ fast-mode في Grok، والقيمة الافتراضية `tool_stream`، وتنظيف + strict-tool / reasoning-payload، وإعادة استخدام مصادقة التراجع للأدوات + المملوكة للـ Plugin، وحل نماذج Grok بالتوافق الأمامي، + وتصحيحات التوافق المملوكة للمزوّد مثل ملف تعريف مخطط أدوات xAI، + والكلمات المفتاحية غير المدعومة في المخطط، و`web_search` الأصلي، + وفك ترميز وسائط HTML في بارامترات استدعاء الأدوات. +- يستخدم Mistral وOpenCode Zen وOpenCode Go الخطاف `capabilities` فقط + لإبقاء فروق النصوص/الأدوات خارج النواة. +- يستخدم مزوّدو الفهرس فقط المضمّنون مثل `byteplus` و`cloudflare-ai-gateway`، و`huggingface` و`kimi-coding` و`nvidia` و`qianfan`، و`synthetic` و`together` و`venice` و`vercel-ai-gateway` و`volcengine` - `catalog` فقط. -- يستخدم Qwen `catalog` لموفّر النصوص الخاص به بالإضافة إلى تسجيلات - media-understanding وتوليد الفيديو المشتركة لأسطحه متعددة الوسائط. -- يستخدم MiniMax وXiaomi `catalog` بالإضافة إلى مرابط الاستخدام لأن سلوك - `/usage` الخاص بهما مملوك لـ Plugin حتى وإن ظل الاستدلال يعمل عبر - عمليات النقل المشتركة. + الخطاف `catalog` فقط. +- يستخدم Qwen الخطاف `catalog` لمزوّد النصوص الخاص به إضافةً إلى تسجيلات + فهم الوسائط وتوليد الفيديو المشتركة لأسطحه متعددة الوسائط. +- يستخدم MiniMax وXiaomi `catalog` إضافةً إلى خطافات الاستخدام لأن سلوك + `/usage` الخاص بهما مملوك للـ Plugin رغم أن الاستدلال لا يزال يعمل عبر + وسائل النقل المشتركة. ## مساعدات وقت التشغيل -يمكن لـ Plugins الوصول إلى بعض مساعدات النواة المحددة عبر `api.runtime`. بالنسبة إلى TTS: +يمكن للPlugins الوصول إلى مساعدات محددة من النواة عبر `api.runtime`. بالنسبة إلى TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -930,14 +942,14 @@ const voices = await api.runtime.tts.listVoices({ ملاحظات: -- يعيد `textToSpeech` حمولة خرج TTS العادية في النواة لأسطح الملفات/الملاحظات الصوتية. -- يستخدم إعداد `messages.tts` الأساسي واختيار الموفّر. -- يعيد مخزنًا مؤقتًا لصوت PCM + معدل العينة. ويجب على Plugins إعادة أخذ العينات/الترميز للمورّدين. -- `listVoices` اختياري لكل موفّر. استخدمه لمنتقيات الأصوات المملوكة للمورّد أو تدفقات الإعداد. -- يمكن أن تتضمن قوائم الأصوات بيانات وصفية أغنى مثل اللغة والمنطقة، والجنس، ووسوم الشخصية لأجل منتقيات واعية بالموفّر. -- تدعم OpenAI وElevenLabs الاتصال الهاتفي اليوم. ولا تدعم Microsoft ذلك. +- يعيد `textToSpeech` حمولة خرج TTS العادية من النواة لأسطح الملفات/الملاحظات الصوتية. +- يستخدم إعداد `messages.tts` الأساسي واختيار المزوّد. +- يعيد PCM audio buffer + sample rate. ويجب على Plugins إعادة أخذ العينات/الترميز للمزوّدات. +- `listVoices` اختياري لكل مزوّد. استخدمه لمنتقيات الأصوات أو تدفقات الإعداد المملوكة للمورّد. +- يمكن أن تتضمن قوائم الأصوات بيانات وصفية أغنى مثل اللغة والمنطقة، والجنس، ووسوم الشخصية لمنتقيات مدركة للمزوّد. +- يدعم OpenAI وElevenLabs الهاتفية اليوم. أما Microsoft فلا يدعمها. -يمكن لـ Plugins أيضًا تسجيل موفّري الكلام عبر `api.registerSpeechProvider(...)`. +يمكن للPlugins أيضًا تسجيل مزوّدي الكلام عبر `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -957,15 +969,15 @@ api.registerSpeechProvider({ ملاحظات: -- أبقِ سياسة TTS، والبدائل الاحتياطية، وتسليم الردود في النواة. -- استخدم موفّري الكلام لسلوك التوليف المملوك للمورّد. -- يُطبَّع إدخال Microsoft `edge` القديم إلى معرف الموفّر `microsoft`. -- نموذج الملكية المفضل موجه نحو الشركة: يمكن لـ Plugin مورّد واحدة أن تملك - موفّري النص والكلام والصور والوسائط المستقبلية مع إضافة OpenClaw لتلك - العقود الخاصة بالإمكانات. +- أبقِ سياسة TTS والتراجع وتسليم الردود في النواة. +- استخدم مزوّدي الكلام لسلوك الاصطناع المملوك للمورّد. +- يُطبَّع الإدخال القديم Microsoft `edge` إلى معرّف المزوّد `microsoft`. +- نموذج الملكية المفضّل موجه للشركات: يمكن لPlugin مورّد واحد أن يملك + مزوّدي النصوص والكلام والصور ومزوّدي الوسائط مستقبلًا مع إضافة OpenClaw + لعقود تلك القدرات. -بالنسبة إلى فهم الصور/الصوت/الفيديو، تسجل Plugins موفّرًا مطبوعًا واحدًا لـ -media-understanding بدلًا من حقيبة مفتاح/قيمة عامة: +بالنسبة إلى فهم الصور/الصوت/الفيديو، تسجّل Plugins مزوّدًا واحدًا مكتوب النوع +لفهم الوسائط بدلًا من حقيبة مفتاح/قيمة عامة: ```ts api.registerMediaUnderstandingProvider({ @@ -979,16 +991,16 @@ api.registerMediaUnderstandingProvider({ ملاحظات: -- أبقِ التنسيق، والبدائل الاحتياطية، والإعداد، وتوصيل القنوات في النواة. -- أبقِ سلوك المورّد في Plugin الموفّر. -- يجب أن يبقى التوسع الإضافي مطبوعًا: أساليب اختيارية جديدة، وحقول نتائج - اختيارية جديدة، وإمكانات اختيارية جديدة. -- يتبع توليد الفيديو النمط نفسه بالفعل: - - تملك النواة عقد الإمكانية ومساعد وقت التشغيل - - تسجل Plugins المورّدين `api.registerVideoGenerationProvider(...)` - - تستهلك Plugins الميزات/القنوات `api.runtime.videoGeneration.*` +- أبقِ التنسيق والتراجع والإعدادات وربط القنوات في النواة. +- أبقِ سلوك المورّد داخل Plugin المزوّد. +- يجب أن يبقى التوسع الإضافي مكتوب النوع: أساليب اختيارية جديدة، وحقول + نتائج اختيارية جديدة، وقدرات اختيارية جديدة. +- يتبع توليد الفيديو بالفعل النمط نفسه: + - تملك النواة عقد القدرة ومساعد وقت التشغيل + - تسجّل Plugins المورّدين `api.registerVideoGenerationProvider(...)` + - تستهلك Plugins الميزة/القناة `api.runtime.videoGeneration.*` -وبالنسبة إلى مساعدات وقت تشغيل media-understanding، يمكن لـ Plugins استدعاء: +بالنسبة إلى مساعدات وقت التشغيل الخاصة بفهم الوسائط، يمكن للPlugins استدعاء: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -1003,8 +1015,8 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -وبالنسبة إلى نسخ الصوت، يمكن لـ Plugins استخدام وقت تشغيل -media-understanding أو الاسم المستعار الأقدم STT: +بالنسبة إلى نسخ الصوت، يمكن للPlugins استخدام وقت تشغيل فهم الوسائط +أو الاسم المستعار الأقدم STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ @@ -1019,11 +1031,11 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ - يُعد `api.runtime.mediaUnderstanding.*` السطح المشترك المفضل من أجل فهم الصور/الصوت/الفيديو. -- يستخدم إعداد الصوت الخاص بـ media-understanding في النواة (`tools.media.audio`) وترتيب البدائل الاحتياطية الخاص بالموفّر. +- يستخدم إعداد الصوت الخاص بفهم الوسائط في النواة (`tools.media.audio`) وترتيب التراجع بين المزوّدين. - يعيد `{ text: undefined }` عندما لا يتم إنتاج مخرجات نسخ (على سبيل المثال عند تخطي الإدخال أو عدم دعمه). -- يبقى `api.runtime.stt.transcribeAudioFile(...)` اسمًا مستعارًا للتوافق. +- يظل `api.runtime.stt.transcribeAudioFile(...)` اسمًا مستعارًا للتوافق. -يمكن لـ Plugins أيضًا إطلاق تشغيلات وكلاء فرعيين في الخلفية عبر `api.runtime.subagent`: +يمكن للPlugins أيضًا تشغيل تنفيذات subagent في الخلفية عبر `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1037,14 +1049,14 @@ const result = await api.runtime.subagent.run({ ملاحظات: -- `provider` و`model` هما تجاوزان اختياريان لكل تشغيل، وليسا تغييرات دائمة على الجلسة. -- لا يلتزم OpenClaw بحقول التجاوز هذه إلا للمستدعين الموثوقين. -- بالنسبة إلى تشغيلات البدائل الاحتياطية المملوكة لـ Plugin، يجب على المشغلين تفعيل ذلك صراحةً عبر `plugins.entries..subagent.allowModelOverride: true`. -- استخدم `plugins.entries..subagent.allowedModels` لتقييد Plugins الموثوقة بأهداف `provider/model` القياسية المحددة، أو `"*"` للسماح بأي هدف صراحةً. -- تظل تشغيلات الوكلاء الفرعيين الخاصة بـ Plugins غير الموثوقة تعمل، لكن طلبات التجاوز تُرفض بدلًا من الرجوع الاحتياطي بصمت. +- الحقلان `provider` و`model` هما تجاوزان اختياريان لكل تنفيذ، وليسا تغييرات دائمة على الجلسة. +- لا يحترم OpenClaw حقول التجاوز هذه إلا للمستدعين الموثوقين. +- بالنسبة إلى تنفيذات التراجع المملوكة للـ Plugin، يجب على المشغّلين تفعيل ذلك صراحةً عبر `plugins.entries..subagent.allowModelOverride: true`. +- استخدم `plugins.entries..subagent.allowedModels` لتقييد Plugins الموثوقة إلى أهداف `provider/model` قياسية محددة، أو `"*"` للسماح صراحةً بأي هدف. +- لا تزال تنفيذات subagent الخاصة بالPlugins غير الموثوقة تعمل، لكن تُرفض طلبات التجاوز بدلًا من الرجوع بصمت. -وبالنسبة إلى البحث على الويب، يمكن لـ Plugins استهلاك مساعد وقت التشغيل المشترك بدلًا من -الوصول إلى توصيل أداة الوكيل: +بالنسبة إلى البحث في الويب، يمكن للPlugins استهلاك مساعد وقت التشغيل المشترك بدلًا من +الوصول إلى ربط أداة الوكيل: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1060,14 +1072,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -كما يمكن لـ Plugins أيضًا تسجيل موفّري البحث على الويب عبر +يمكن للPlugins أيضًا تسجيل مزوّدي البحث في الويب عبر `api.registerWebSearchProvider(...)`. ملاحظات: -- أبقِ اختيار الموفّر، وحل بيانات الاعتماد، ودلالات الطلب المشتركة في النواة. -- استخدم موفّري البحث على الويب لعمليات النقل الخاصة بالبحث والمملوكة للمورّد. -- يُعد `api.runtime.webSearch.*` السطح المشترك المفضل بالنسبة إلى Plugins الميزات/القنوات التي تحتاج إلى سلوك البحث من دون الاعتماد على غلاف أداة الوكيل. +- أبقِ اختيار المزوّد، وحلّ بيانات الاعتماد، ودلالات الطلب المشتركة في النواة. +- استخدم مزوّدي البحث في الويب لوسائل نقل البحث الخاصة بالمورّد. +- يُعد `api.runtime.webSearch.*` السطح المشترك المفضل لPlugins الميزات/القنوات التي تحتاج إلى سلوك بحث من دون الاعتماد على مغلّف أداة الوكيل. ### `api.runtime.imageGeneration` @@ -1082,12 +1094,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: توليد صورة باستخدام سلسلة موفّري توليد الصور المضبوطة. -- `listProviders(...)`: عرض موفّري توليد الصور المتاحين وإمكاناتهم. +- ‏`generate(...)`: أنشئ صورة باستخدام سلسلة مزوّد توليد الصور المهيأة. +- ‏`listProviders(...)`: اعرض مزوّدي توليد الصور المتاحين وقدراتهم. ## مسارات Gateway HTTP -يمكن لـ Plugins كشف نقاط نهاية HTTP عبر `api.registerHttpRoute(...)`. +يمكن للPlugins كشف نقاط نهاية HTTP عبر `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -1104,266 +1116,263 @@ api.registerHttpRoute({ حقول المسار: -- `path`: مسار route ضمن خادم Gateway HTTP. -- `auth`: مطلوب. استخدم `"gateway"` لطلب مصادقة Gateway العادية، أو `"plugin"` للمصادقة التي تديرها Plugin/التحقق من Webhook. +- `path`: مسار route تحت خادم Gateway HTTP. +- `auth`: مطلوب. استخدم `"gateway"` لطلب مصادقة Gateway العادية، أو `"plugin"` للمصادقة/التحقق من Webhook الذي يديره Plugin. - `match`: اختياري. `"exact"` (الافتراضي) أو `"prefix"`. -- `replaceExisting`: اختياري. يتيح لـ Plugin نفسها استبدال تسجيل مسارها الحالي. -- `handler`: أعد `true` عندما يكون المسار قد عالج الطلب. +- `replaceExisting`: اختياري. يسمح للـ Plugin نفسه باستبدال تسجيل مساره الحالي. +- `handler`: أعد `true` عندما يتعامل route مع الطلب. ملاحظات: -- تمت إزالة `api.registerHttpHandler(...)` وسيتسبب في خطأ تحميل Plugin. استخدم `api.registerHttpRoute(...)` بدلًا منه. -- يجب على مسارات Plugin التصريح عن `auth` صراحةً. -- تُرفض تعارضات `path + match` المطابقة إلا إذا كان `replaceExisting: true`، ولا يمكن لـ Plugin واحدة استبدال مسار Plugin أخرى. -- تُرفض المسارات المتداخلة ذات مستويات `auth` المختلفة. أبقِ سلاسل السقوط `exact`/`prefix` ضمن مستوى auth نفسه فقط. -- لا تتلقى مسارات `auth: "plugin"` تلقائيًا نطاقات وقت تشغيل المشغل. فهي مخصصة لـ Webhook الذي تديره Plugin/التحقق من التوقيع، وليست لاستدعاءات مساعدات Gateway ذات الامتيازات. +- تمت إزالة `api.registerHttpHandler(...)` وسيتسبب في خطأ أثناء تحميل Plugin. استخدم `api.registerHttpRoute(...)` بدلًا منه. +- يجب على مسارات Plugins أن تصرّح بـ `auth` صراحةً. +- تُرفض تعارضات `path + match` المتطابقة ما لم يكن `replaceExisting: true`، ولا يمكن لـ Plugin أن يستبدل مسار Plugin آخر. +- تُرفض المسارات المتداخلة ذات مستويات `auth` المختلفة. احصر سلاسل fallthrough من `exact`/`prefix` ضمن مستوى المصادقة نفسه فقط. +- لا تتلقى مسارات `auth: "plugin"` نطاقات وقت تشغيل المشغّل تلقائيًا. فهي مخصصة لـ Webhooks/التحقق من التوقيع الذي يديره Plugin، وليست لاستدعاءات مساعد Gateway ذات الامتيازات. - تعمل مسارات `auth: "gateway"` داخل نطاق وقت تشغيل طلب Gateway، لكن هذا النطاق محافظ عمدًا: - - تبقي مصادقة bearer ذات السر المشترك (`gateway.auth.mode = "token"` / `"password"`) نطاقات وقت تشغيل مسار Plugin مثبتة على `operator.write`، حتى لو أرسل المستدعي `x-openclaw-scopes` - - تحترم أوضاع HTTP الموثوقة والحاملة للهوية (على سبيل المثال `trusted-proxy` أو `gateway.auth.mode = "none"` على ingress خاص) قيمة `x-openclaw-scopes` فقط عندما يكون الرأس موجودًا صراحةً - - إذا كان `x-openclaw-scopes` غائبًا في طلبات مسار Plugin الحاملة للهوية تلك، يعود نطاق وقت التشغيل إلى `operator.write` -- القاعدة العملية: لا تفترض أن مسار Plugin ذي مصادقة gateway هو سطح إدارة ضمني. إذا كان مسارك يحتاج إلى سلوك خاص بالمشرف فقط، فاطلب وضع مصادقة حاملًا للهوية ووثّق عقد الرأس `x-openclaw-scopes` الصريح. + - تؤدي مصادقة bearer بالمفتاح المشترك (`gateway.auth.mode = "token"` / `"password"`) إلى إبقاء نطاقات وقت تشغيل مسارات Plugins مثبتة عند `operator.write`، حتى إذا أرسل المستدعي `x-openclaw-scopes` + - تحترم أوضاع HTTP الموثوقة الحاملة للهوية (على سبيل المثال `trusted-proxy` أو `gateway.auth.mode = "none"` على مدخل خاص) قيمة `x-openclaw-scopes` فقط عندما يكون الرأس موجودًا صراحةً + - إذا كان `x-openclaw-scopes` غائبًا في طلبات مسارات Plugins الحاملة للهوية تلك، يعود نطاق وقت التشغيل إلى `operator.write` +- القاعدة العملية: لا تفترض أن مسار Plugin المصادق عبر gateway هو سطح إدارة ضمني. إذا كان مسارك يحتاج إلى سلوك مخصص للمشرف فقط، فاطلب وضع مصادقة حاملًا للهوية ووثّق عقد الرأس `x-openclaw-scopes` الصريح. ## مسارات استيراد Plugin SDK استخدم المسارات الفرعية لـ SDK بدلًا من الاستيراد الأحادي `openclaw/plugin-sdk` عند تأليف Plugins: -- `openclaw/plugin-sdk/plugin-entry` لبدائيات تسجيل Plugin. -- `openclaw/plugin-sdk/core` للعقد المشترك العام الموجّه إلى Plugin. -- `openclaw/plugin-sdk/config-schema` لتصدير مخطط Zod الجذري لـ `openclaw.json` +- `openclaw/plugin-sdk/plugin-entry` لأساسيات تسجيل Plugin. +- `openclaw/plugin-sdk/core` للعقد المشترك العام المواجه للـ Plugin. +- `openclaw/plugin-sdk/config-schema` لتصدير مخطط Zod الجذر لـ `openclaw.json` (`OpenClawSchema`). -- بدائيات القنوات الثابتة مثل `openclaw/plugin-sdk/channel-setup`، - و`openclaw/plugin-sdk/setup-runtime`, - و`openclaw/plugin-sdk/setup-adapter-runtime`, - و`openclaw/plugin-sdk/setup-tools`, - و`openclaw/plugin-sdk/channel-pairing`, - و`openclaw/plugin-sdk/channel-contract`, - و`openclaw/plugin-sdk/channel-feedback`, - و`openclaw/plugin-sdk/channel-inbound`, - و`openclaw/plugin-sdk/channel-lifecycle`, - و`openclaw/plugin-sdk/channel-reply-pipeline`, - و`openclaw/plugin-sdk/command-auth`, +- الأساسيات المستقرة للقنوات مثل `openclaw/plugin-sdk/channel-setup`، + و`openclaw/plugin-sdk/setup-runtime`، + و`openclaw/plugin-sdk/setup-adapter-runtime`، + و`openclaw/plugin-sdk/setup-tools`، + و`openclaw/plugin-sdk/channel-pairing`، + و`openclaw/plugin-sdk/channel-contract`، + و`openclaw/plugin-sdk/channel-feedback`، + و`openclaw/plugin-sdk/channel-inbound`، + و`openclaw/plugin-sdk/channel-lifecycle`، + و`openclaw/plugin-sdk/channel-reply-pipeline`، + و`openclaw/plugin-sdk/command-auth`، و`openclaw/plugin-sdk/secret-input`، و - `openclaw/plugin-sdk/webhook-ingress` من أجل التوصيل المشترك للإعداد/المصادقة/الرد/Webhook. - ويُعد `channel-inbound` الموطن المشترك لإزالة الارتداد، ومطابقة الإشارات، ومساعدات - سياسة الإشارة الواردة، وتنسيق المغلّفات، ومساعدات سياق المغلف الوارد. - ويُعد `channel-setup` حد الإعداد الضيق للتثبيت الاختياري. + `openclaw/plugin-sdk/webhook-ingress` لربط + الإعداد/المصادقة/الرد/Webhook المشترك. يُعد `channel-inbound` الموطن المشترك للتخفيف من التكرار، ومطابقة الإشارات، ومساعدات سياسة الإشارة الواردة، وتنسيق envelopes، ومساعدات سياق envelopes الواردة. + ويُعد `channel-setup` حدّ الإعداد الضيق للتثبيت الاختياري. ويُعد `setup-runtime` سطح الإعداد الآمن لوقت التشغيل المستخدم بواسطة `setupEntry` / - بدء التشغيل المؤجل، بما في ذلك مهايئات رقع الإعداد الآمنة للاستيراد. - ويُعد `setup-adapter-runtime` حد مهايئ إعداد الحساب الواعي بالبيئة. - ويُعد `setup-tools` الحد الصغير لمساعدات CLI/الأرشيف/الوثائق (`formatCliCommand`، + وبدء التشغيل المؤجل، بما في ذلك مهايئات تصحيح الإعداد الآمنة للاستيراد. + ويُعد `setup-adapter-runtime` حدّ مهايئ إعداد الحساب المدرك للبيئة. + ويُعد `setup-tools` الحدّ الصغير لمساعدات CLI/الأرشيف/الوثائق (`formatCliCommand`، و`detectBinary`، و`extractArchive`، و`resolveBrewExecutable`، و`formatDocsLink`، و`CONFIG_DIR`). -- المسارات الفرعية الخاصة بالمجال مثل `openclaw/plugin-sdk/channel-config-helpers`, - و`openclaw/plugin-sdk/allow-from`, - و`openclaw/plugin-sdk/channel-config-schema`, - و`openclaw/plugin-sdk/telegram-command-config`, - و`openclaw/plugin-sdk/channel-policy`, - و`openclaw/plugin-sdk/approval-gateway-runtime`, - و`openclaw/plugin-sdk/approval-handler-adapter-runtime`, - و`openclaw/plugin-sdk/approval-handler-runtime`, - و`openclaw/plugin-sdk/approval-runtime`, - و`openclaw/plugin-sdk/config-runtime`, - و`openclaw/plugin-sdk/infra-runtime`, - و`openclaw/plugin-sdk/agent-runtime`, - و`openclaw/plugin-sdk/lazy-runtime`, - و`openclaw/plugin-sdk/reply-history`, - و`openclaw/plugin-sdk/routing`, - و`openclaw/plugin-sdk/status-helpers`, - و`openclaw/plugin-sdk/text-runtime`, +- المسارات الفرعية الخاصة بالمجالات مثل `openclaw/plugin-sdk/channel-config-helpers`، + و`openclaw/plugin-sdk/allow-from`، + و`openclaw/plugin-sdk/channel-config-schema`، + و`openclaw/plugin-sdk/telegram-command-config`، + و`openclaw/plugin-sdk/channel-policy`، + و`openclaw/plugin-sdk/approval-gateway-runtime`، + و`openclaw/plugin-sdk/approval-handler-adapter-runtime`، + و`openclaw/plugin-sdk/approval-handler-runtime`، + و`openclaw/plugin-sdk/approval-runtime`، + و`openclaw/plugin-sdk/config-runtime`، + و`openclaw/plugin-sdk/infra-runtime`، + و`openclaw/plugin-sdk/agent-runtime`، + و`openclaw/plugin-sdk/lazy-runtime`، + و`openclaw/plugin-sdk/reply-history`، + و`openclaw/plugin-sdk/routing`، + و`openclaw/plugin-sdk/status-helpers`، + و`openclaw/plugin-sdk/text-runtime`، و`openclaw/plugin-sdk/runtime-store`، و - `openclaw/plugin-sdk/directory-runtime` لمساعدات وقت التشغيل/الإعداد المشتركة. - ويُعد `telegram-command-config` الحد العام الضيق لتطبيع/التحقق من - الأوامر المخصصة في Telegram، ويظل متاحًا حتى إذا كان سطح العقد المجمّع الخاص بـ - Telegram غير متاح مؤقتًا. - ويُعد `text-runtime` الحد المشترك للنص/Markdown/التسجيل، بما في ذلك - إزالة النص المرئي للمساعد، ومساعدات عرض/تجزئة Markdown، ومساعدات - الإخفاء، ومساعدات وسم التوجيهات، وأدوات النص الآمن. -- يجب أن تفضّل الحدود الخاصة بالقنوات المتعلقة بالموافقات عقد `approvalCapability` - واحدًا على Plugin. ثم تقرأ النواة مصادقة الموافقة، والتسليم، والعرض، - والتوجيه الأصلي، وسلوك المعالج الأصلي الكسول عبر تلك الإمكانية الواحدة - بدلًا من خلط سلوك الموافقات في حقول Plugin غير المرتبطة. -- تم إهمال `openclaw/plugin-sdk/channel-runtime` ويظل فقط - كتوافق مع Plugins الأقدم. ويجب على الكود الجديد استيراد البدائيات العامة الأضيق بدلًا من ذلك، - ويجب ألا يضيف كود المستودع استيرادات جديدة لهذا الغلاف التوافقي. -- تظل الأجزاء الداخلية للإضافات المجمعة خاصة. يجب على Plugins الخارجية استخدام - المسارات الفرعية `openclaw/plugin-sdk/*` فقط. ويمكن لكود النواة/الاختبار في OpenClaw - استخدام نقاط الإدخال العامة في المستودع ضمن جذر حزمة Plugin مثل `index.js` و`api.js`، + `openclaw/plugin-sdk/directory-runtime` لمساعدات وقت التشغيل/الإعدادات المشتركة. + ويُعد `telegram-command-config` الحدّ العام الضيق لتطبيع/التحقق من الأوامر + المخصصة في Telegram، ويظل متاحًا حتى إذا كان سطح عقد Telegram المضمّن + غير متاح مؤقتًا. + ويُعد `text-runtime` الحدّ المشترك للنص/Markdown/التسجيل، بما في ذلك + إزالة النص المرئي للمساعد، ومساعدات عرض/تجزئة markdown، ومساعدات + التنقيح، ومساعدات وسوم التوجيه، وأدوات النص الآمن. +- يجب أن تفضّل حدود القنوات الخاصة بالموافقات عقد `approvalCapability` + واحدًا على Plugin. ثم تقرأ النواة مصادقة الموافقات والتسليم والعرض + والتوجيه الأصلي وسلوك المعالج الأصلي الكسول عبر تلك القدرة الواحدة + بدلًا من خلط سلوك الموافقة في حقول Plugin غير المرتبطة. +- تم إهمال `openclaw/plugin-sdk/channel-runtime` ولم يعد موجودًا إلا كطبقة + توافقية لPlugins الأقدم. يجب على الكود الجديد استيراد الأساسيات العامة الأضيق بدلًا منه، ويجب ألا يضيف كود المستودع استيرادات جديدة من + هذه الطبقة. +- تظل الأجزاء الداخلية للإضافات المضمّنة خاصة. يجب على Plugins الخارجية استخدام + المسارات الفرعية `openclaw/plugin-sdk/*` فقط. ويمكن لكود/اختبارات OpenClaw الأساسية استخدام + نقاط الدخول العامة للمستودع تحت جذر حزمة Plugin مثل `index.js` و`api.js`، و`runtime-api.js` و`setup-entry.js`، والملفات الضيقة النطاق مثل - `login-qr-api.js`. ولا تستورد مطلقًا `src/*` الخاص بحزمة Plugin من النواة أو من + `login-qr-api.js`. ولا تستورد أبدًا `src/*` من حزمة Plugin من النواة أو من إضافة أخرى. -- تقسيم نقاط إدخال المستودع: +- تقسيم نقطة دخول المستودع: `/api.js` هو حاوية المساعدات/الأنواع، - و`/runtime-api.js` هو حاوية وقت التشغيل فقط، - و`/index.js` هو إدخال Plugin المجمعة، - و`/setup-entry.js` هو إدخال Plugin للإعداد. -- أمثلة موفّرين مجمّعين حاليين: - - يستخدم Anthropic `api.js` / `contract-api.js` لمساعدات بث Claude مثل + و`/runtime-api.js` هو الحاوية الخاصة بوقت التشغيل فقط، + و`/index.js` هو مدخل Plugin المضمّن، + و`/setup-entry.js` هو مدخل Plugin الخاص بالإعداد. +- أمثلة حالية على المزوّدات المضمّنة: + - يستخدم Anthropic `api.js` / `contract-api.js` لمساعدات تدفق Claude مثل `wrapAnthropicProviderStream`، ومساعدات رؤوس beta، وتحليل `service_tier`. - - تستخدم OpenAI `api.js` لبناة الموفّر، ومساعدات النموذج الافتراضي، وبناة - موفّر الوقت الحقيقي. - - تستخدم OpenRouter `api.js` لباني الموفّر الخاص بها إضافة إلى مساعدات - الإعداد/التهيئة، بينما يمكن لـ `register.runtime.js` أن يعيد تصدير مساعدات - `plugin-sdk/provider-stream` العامة للاستخدام المحلي في المستودع. -- تفضّل نقاط الإدخال العامة المحمّلة عبر الواجهة Snapshot إعداد وقت التشغيل النشط - عندما يكون موجودًا، ثم تعود إلى ملف الإعداد المحلول على القرص عندما - لا يكون OpenClaw قد بدأ بعد في تقديم Snapshot وقت تشغيل. -- تظل البدائيات العامة المشتركة هي عقد SDK العام المفضل. ولا تزال توجد - مجموعة توافق صغيرة ومحفوظة من حدود المساعدات الموسومة بأسماء القنوات المجمعة. تعامل - مع تلك باعتبارها حدود صيانة/توافق خاصة بالحزم المجمعة، لا أهداف استيراد جديدة - لأطراف ثالثة؛ ويجب أن تُضاف العقود الجديدة العابرة للقنوات إلى - المسارات الفرعية العامة `plugin-sdk/*` أو إلى الحاويات المحلية لـ Plugin مثل `api.js` / - `runtime-api.js`. + - يستخدم OpenAI `api.js` لبناة المزوّدات، ومساعدات النماذج الافتراضية، + وبناة المزوّدات الفورية. + - يستخدم OpenRouter `api.js` لباني المزوّد الخاص به إضافةً إلى مساعدات + الإعداد/التهيئة، بينما لا يزال بإمكان `register.runtime.js` إعادة تصدير + مساعدات `plugin-sdk/provider-stream` العامة للاستخدام المحلي داخل المستودع. +- تفضّل نقاط الدخول العامة المحمّلة عبر facade لقطة إعدادات وقت التشغيل النشطة + عندما تكون موجودة، ثم تعود إلى ملف الإعدادات المحلول على القرص عندما + لا يكون OpenClaw قد بدأ بعد في تقديم لقطة وقت التشغيل. +- تظل الأساسيات العامة المشتركة هي عقد SDK العام المفضل. ولا تزال هناك + مجموعة توافقية صغيرة ومحجوزة من حدود المساعدات ذات العلامات الخاصة بالقنوات المضمّنة. + تعامل مع هذه على أنها حدود للصيانة/التوافق الخاصة بالحزم المضمّنة، لا كأهداف استيراد جديدة لجهات خارجية؛ ويجب أن تستمر العقود الجديدة العابرة للقنوات في + الوصول إلى المسارات الفرعية العامة `plugin-sdk/*` أو الحاويات المحلية للـ Plugin + `api.js` / `runtime-api.js`. -ملاحظة التوافق: +ملاحظة حول التوافق: -- تجنب حاوية الجذر `openclaw/plugin-sdk` في الكود الجديد. -- فضّل أولًا البدائيات الثابتة الضيقة. فالمسارات الفرعية الأحدث الخاصة بالإعداد/الاقتران/الرد/ - الملاحظات/العقد/الوارد/الخيوط/الأوامر/secret-input/Webhook/infra/ - allowlist/status/message-tool هي العقد المقصود لأعمال Plugins الجديدة - المجمعة والخارجية. - ينتمي تحليل/مطابقة الهدف إلى `openclaw/plugin-sdk/channel-targets`. - وتنتمي بوابات أفعال الرسائل ومساعدات معرف رسالة التفاعل إلى +- تجنّب حاوية الجذر `openclaw/plugin-sdk` في الكود الجديد. +- فضّل أولًا الأساسيات المستقرة الضيقة. فالمسارات الفرعية الأحدث الخاصة بالإعداد/الإقران/الرد/ + التغذية الراجعة/العقد/الوارد/الخيوط/الأوامر/secret-input/Webhook/البنية التحتية/ + قائمة السماح/الحالة/أداة الرسائل هي العقد المقصود لأعمال Plugins الجديدة + المضمّنة والخارجية. + يجب أن يكون تحليل/مطابقة الهدف على `openclaw/plugin-sdk/channel-targets`. + ويجب أن تكون بوابات إجراءات الرسائل ومساعدات معرّف رسالة التفاعل على `openclaw/plugin-sdk/channel-actions`. -- لا تُعد حاويات المساعدات الخاصة بالإضافات المجمعة والمحددة افتراضيًا ثابتة. إذا كانت - المساعدة مطلوبة فقط لإضافة مجمعة، فأبقها خلف الحد المحلي - `api.js` أو `runtime-api.js` الخاص بتلك الإضافة بدلًا من ترقيتها إلى +- لا تُعد حاويات المساعدات الخاصة بالإضافات المضمّنة والمحددة افتراضيًا مستقرة. إذا كانت + هناك حاجة إلى مساعد فقط من قِبل إضافة مضمّنة، فأبقِه خلف + الحدّ المحلي `api.js` أو `runtime-api.js` الخاص بتلك الإضافة بدلًا من ترقيته إلى `openclaw/plugin-sdk/`. -- يجب أن تكون حدود المساعدات المشتركة الجديدة عامة، لا موسومة باسم قناة. ينتمي تحليل - الأهداف المشتركة إلى `openclaw/plugin-sdk/channel-targets`؛ أما الأجزاء الداخلية - الخاصة بالقناة فتبقى خلف الحد المحلي `api.js` أو `runtime-api.js` - المملوك لـ Plugin. -- توجد مسارات فرعية خاصة بالإمكانات مثل `image-generation`، - و`media-understanding`، و`speech` لأن Plugins المجمعة/الأصلية تستخدمها - اليوم. ووجودها لا يعني بحد ذاته أن كل مساعدة مُصدّرة هي - عقدًا خارجيًا مجمّدًا على المدى الطويل. +- يجب أن تكون حدود المساعدات المشتركة الجديدة عامة، لا ممهورة بعلامة قناة محددة. يجب أن يكون تحليل + الأهداف المشتركة على `openclaw/plugin-sdk/channel-targets`؛ أما + الأجزاء الداخلية الخاصة بالقنوات فتبقى خلف الحدّ المحلي `api.js` أو `runtime-api.js` + للـ Plugin المالك. +- توجد مسارات فرعية خاصة بالقدرات مثل `image-generation`، + و`media-understanding`، و`speech` لأن Plugins المضمّنة/الأصلية تستخدمها + اليوم. ولا يعني وجودها بحد ذاته أن كل مساعد مُصدَّر هو + عقد خارجي مجمّد طويل الأمد. ## مخططات أداة الرسائل -يجب أن تملك Plugins مساهمات المخطط الخاصة بـ `describeMessageTool(...)` -الخاصة بالقناة. أبقِ الحقول الخاصة بالموفّر داخل Plugin، لا في النواة المشتركة. +يجب أن تملك Plugins مساهمات مخطط `describeMessageTool(...)` الخاصة بالقنوات. +أبقِ الحقول الخاصة بالمزوّد في Plugin، لا في النواة المشتركة. -وبالنسبة إلى أجزاء المخطط المحمولة المشتركة، أعد استخدام المساعدات العامة المصدّرة عبر -`openclaw/plugin-sdk/channel-actions`: +بالنسبة إلى أجزاء المخطط المشتركة القابلة للنقل، أعد استخدام المساعدات العامة +المصدّرة عبر `openclaw/plugin-sdk/channel-actions`: - `createMessageToolButtonsSchema()` لحمولات بأسلوب شبكة الأزرار - `createMessageToolCardSchema()` لحمولات البطاقات المنظمة -إذا كان شكل المخطط لا يكون منطقيًا إلا لموفّر واحد، فعرّفه في -مصدر Plugin نفسه بدلًا من ترقيته إلى SDK المشتركة. +إذا كان شكل المخطط منطقيًا فقط لمزوّد واحد، فعرّفه في المصدر +الخاص بذلك Plugin بدلًا من ترقيته إلى SDK المشتركة. -## حل هدف القناة +## حلّ أهداف القنوات -يجب أن تملك Plugins القنوات دلالات الأهداف الخاصة بالقناة. أبقِ -مضيف الإرسال الخارجي عامًا واستخدم سطح مهايئ المراسلة لقواعد الموفّر: +يجب أن تملك Plugins القنوات دلالات الأهداف الخاصة بالقنوات. أبقِ +المضيف العام للإرسال الصادر عامًا واستخدم سطح مهايئ المراسلة لقواعد المزوّد: -- يقرر `messaging.inferTargetChatType({ to })` ما إذا كان الهدف المطبّع - يجب أن يُعامل كـ `direct` أو `group` أو `channel` قبل البحث في الدليل. -- يخبر `messaging.targetResolver.looksLikeId(raw, normalized)` النواة بما إذا كان - ينبغي لإدخال ما أن يتجاوز مباشرة إلى حل شبيه بالمعرف بدلًا من البحث في الدليل. -- يُعد `messaging.targetResolver.resolveTarget(...)` بديل Plugin الاحتياطي عندما - تحتاج النواة إلى حل نهائي مملوك للموفّر بعد التطبيع أو بعد - عدم العثور في الدليل. -- يملك `messaging.resolveOutboundSessionRoute(...)` إنشاء مسار الجلسة الخاص بالموفّر - بمجرد حل الهدف. +- تحدد `messaging.inferTargetChatType({ to })` ما إذا كان الهدف المطبّع + يجب أن يُعامل باعتباره `direct` أو `group` أو `channel` قبل البحث في الدليل. +- تخبر `messaging.targetResolver.looksLikeId(raw, normalized)` النواة بما إذا كان + الإدخال يجب أن يتجاوز مباشرة إلى حلّ شبيه بالمعرّف بدلًا من البحث في الدليل. +- تمثل `messaging.targetResolver.resolveTarget(...)` تراجع Plugin عندما + تحتاج النواة إلى حلّ نهائي مملوك للمزوّد بعد التطبيع أو بعد + إخفاق البحث في الدليل. +- تملك `messaging.resolveOutboundSessionRoute(...)` إنشاء مسار الجلسة + الخاص بالمزوّد بمجرد حلّ الهدف. التقسيم الموصى به: - استخدم `inferTargetChatType` لقرارات التصنيف التي يجب أن تحدث قبل البحث في الأقران/المجموعات. -- استخدم `looksLikeId` لفحوصات "عامل هذا كمعرف هدف صريح/أصلي". -- استخدم `resolveTarget` كبديل تطبيع خاص بالموفّر، لا +- استخدم `looksLikeId` لفحوصات "عامل هذا كمعرّف هدف صريح/أصلي". +- استخدم `resolveTarget` للتراجع الخاص بالتطبيع عند المزوّد، لا للبحث الواسع في الدليل. -- أبقِ المعرفات الأصلية الخاصة بالموفّر مثل معرفات الدردشة، ومعرفات الخيوط، وJIDs، - والمعالجات، ومعرفات الغرف داخل قيم `target` أو ضمن معاملات خاصة بالموفّر، لا - في حقول SDK عامة. +- أبقِ المعرّفات الأصلية للمزوّد مثل معرّفات الدردشة، ومعرّفات السلاسل، وJIDs، والمعالجات، ومعرّفات الغرف + داخل قيم `target` أو البارامترات الخاصة بالمزوّد، لا في حقول SDK العامة. -## الأدلة المعتمدة على الإعداد +## الأدلة المعتمدة على الإعدادات -يجب على Plugins التي تستمد إدخالات الدليل من الإعداد أن تُبقي هذا المنطق داخل +يجب على Plugins التي تستمد إدخالات الدليل من الإعدادات أن تُبقي هذا المنطق داخل Plugin وأن تعيد استخدام المساعدات المشتركة من `openclaw/plugin-sdk/directory-runtime`. -استخدم هذا عندما تحتاج القناة إلى أقران/مجموعات معتمدة على الإعداد مثل: +استخدم هذا عندما تحتاج القناة إلى أقران/مجموعات معتمدة على الإعدادات مثل: -- أقران الرسائل المباشرة المدفوعة بقائمة السماح -- خرائط القنوات/المجموعات المكوّنة -- بدائل الدليل الثابتة ذات النطاق الخاص بالحساب +- أقران DM مدفوعين بقائمة السماح +- خرائط القنوات/المجموعات المهيأة +- تراجعات الدليل الثابتة المقيّدة بالحساب لا تتعامل المساعدات المشتركة في `directory-runtime` إلا مع العمليات العامة: -- تصفية الاستعلام -- تطبيق الحد +- تصفية الاستعلامات +- تطبيق الحدود - مساعدات إزالة التكرار/التطبيع - بناء `ChannelDirectoryEntry[]` -يجب أن يبقى فحص الحساب الخاص بالقناة وتطبيع المعرفات داخل +يجب أن يبقى فحص الحساب الخاص بالقناة وتطبيع المعرّفات في تنفيذ Plugin. -## فهارس الموفّرين +## فهارس المزوّدات -يمكن لـ Plugins الموفّر تعريف فهارس النماذج للاستدلال باستخدام +يمكن لPlugins المزوّدات تعريف فهارس نماذج للاستدلال باستخدام `registerProvider({ catalog: { run(...) { ... } } })`. -يعيد `catalog.run(...)` البنية نفسها التي يكتبها OpenClaw في +يعيد `catalog.run(...)` البنية نفسها التي يكتبها OpenClaw إلى `models.providers`: -- `{ provider }` لإدخال موفّر واحد -- `{ providers }` لعدة إدخالات موفّر +- `{ provider }` لإدخال مزوّد واحد +- `{ providers }` لعدة إدخالات مزوّد -استخدم `catalog` عندما تملك Plugin معرفات نماذج خاصة بالموفّر، أو إعدادات افتراضية لـ base URL، أو بيانات وصفية للنماذج محكومة بالمصادقة. +استخدم `catalog` عندما يملك Plugin معرّفات نماذج خاصة بالمزوّد، أو قيمًا افتراضية لـ base URL، أو بيانات وصفية للنماذج محكومة بالمصادقة. -يتحكم `catalog.order` في توقيت دمج فهرس Plugin نسبةً إلى -الموفّرين الضمنيين المدمجين في OpenClaw: +تتحكم `catalog.order` في وقت دمج فهرس Plugin بالنسبة إلى المزوّدات +الضمنية المضمّنة في OpenClaw: -- `simple`: موفّرون عاديون معتمدون على مفتاح API أو البيئة -- `profile`: موفّرون يظهرون عند وجود ملفات تعريف للمصادقة -- `paired`: موفّرون يركّبون عدة إدخالات موفّر مترابطة -- `late`: التمرير الأخير، بعد الموفّرين الضمنيين الآخرين +- `simple`: مزوّدات تعتمد على مفتاح API عادي أو البيئة +- `profile`: مزوّدات تظهر عندما توجد ملفات تعريف للمصادقة +- `paired`: مزوّدات تُنشئ عدة إدخالات مزوّدات مرتبطة +- `late`: المرور الأخير، بعد المزوّدات الضمنية الأخرى -يفوز الموفّرون اللاحقون عند تعارض المفاتيح، لذلك يمكن لـ Plugins أن -تتجاوز عمدًا إدخال موفّر مدمجًا يحمل معرف الموفّر نفسه. +يفوز المزوّد اللاحق عند تعارض المفاتيح، لذا يمكن للPlugins أن تتعمد تجاوز +إدخال مزوّد مضمّن يحمل معرّف المزوّد نفسه. التوافق: - لا يزال `discovery` يعمل كاسم مستعار قديم -- إذا تم تسجيل `catalog` و`discovery` معًا، يستخدم OpenClaw `catalog` +- إذا تم تسجيل كلٍّ من `catalog` و`discovery`، يستخدم OpenClaw `catalog` ## فحص القنوات للقراءة فقط -إذا كانت Plugin لديك تسجل قناة، فافضّل تنفيذ +إذا كان Plugin الخاص بك يسجّل قناة، ففضّل تنفيذ `plugin.config.inspectAccount(cfg, accountId)` إلى جانب `resolveAccount(...)`. السبب: -- يمثل `resolveAccount(...)` مسار وقت التشغيل. ويُسمح له بأن يفترض أن بيانات الاعتماد - قد جُسدت بالكامل ويمكنه الفشل بسرعة عند غياب الأسرار المطلوبة. -- لا ينبغي لمسارات الأوامر المخصصة للقراءة فقط مثل `openclaw status` و`openclaw status --all`، - و`openclaw channels status`، و`openclaw channels resolve`، وتدفقات - إصلاح doctor/config أن تحتاج إلى تجسيد بيانات اعتماد وقت التشغيل فقط من أجل - وصف الإعداد. +- يمثل `resolveAccount(...)` مسار وقت التشغيل. ويُسمح له بافتراض أن بيانات الاعتماد + قد تجسدت بالكامل ويمكنه الفشل سريعًا عند غياب الأسرار المطلوبة. +- لا ينبغي أن تحتاج مسارات الأوامر المخصصة للقراءة فقط مثل `openclaw status` و`openclaw status --all`، + و`openclaw channels status`، و`openclaw channels resolve`، وتدفقات doctor/config + repair إلى تجسيد بيانات اعتماد وقت التشغيل فقط + لوصف الإعدادات. السلوك الموصى به لـ `inspectAccount(...)`: -- أعد فقط حالة حساب وصفية. +- أعد حالة وصفية للحساب فقط. - حافظ على `enabled` و`configured`. - ضمّن حقول مصدر/حالة بيانات الاعتماد عند الصلة، مثل: - - `tokenSource`، `tokenStatus` - - `botTokenSource`، `botTokenStatus` - - `appTokenSource`، `appTokenStatus` - - `signingSecretSource`، `signingSecretStatus` -- لا تحتاج إلى إرجاع قيم الرموز الخام فقط للإبلاغ عن - التوفر للقراءة فقط. يكفي إرجاع `tokenStatus: "available"` (مع حقل المصدر المطابق) + - `tokenSource`، و`tokenStatus` + - `botTokenSource`، و`botTokenStatus` + - `appTokenSource`، و`appTokenStatus` + - `signingSecretSource`، و`signingSecretStatus` +- لا تحتاج إلى إعادة قيم الرموز الخام فقط للإبلاغ عن + التوافر للقراءة فقط. يكفي إعادة `tokenStatus: "available"` (ومعه حقل المصدر المطابق) لأوامر على نمط الحالة. -- استخدم `configured_unavailable` عندما تكون بيانات الاعتماد مضبوطة عبر SecretRef لكن +- استخدم `configured_unavailable` عندما تكون بيانات الاعتماد مهيأة عبر SecretRef ولكن غير متاحة في مسار الأمر الحالي. -وهذا يتيح للأوامر المخصصة للقراءة فقط الإبلاغ عن "مضبوط لكنه غير متاح في مسار الأمر هذا" -بدلًا من التعطل أو الإبلاغ بشكل خاطئ أن الحساب غير مضبوط. +يسمح ذلك لأوامر القراءة فقط بالإبلاغ عن "مهيأ لكنه غير متاح في مسار الأمر هذا" +بدلًا من التعطل أو الإبلاغ خطأً عن الحساب على أنه غير مهيأ. ## حزم Package -يمكن أن يتضمن دليل Plugin ملف `package.json` مع `openclaw.extensions`: +يمكن أن يتضمن دليل Plugin ملف `package.json` يحتوي على `openclaw.extensions`: ```json { @@ -1375,65 +1384,65 @@ Plugin وأن تعيد استخدام المساعدات المشتركة من } ``` -يصبح كل إدخال Plugin. وإذا سردت الحزمة عدة extensions، فإن معرف Plugin -يصبح `name/`. +يصبح كل إدخال Plugin. وإذا كانت الحزمة تسرد عدة extensions، يصبح معرّف Plugin +`name/`. -إذا كانت Plugin لديك تستورد تبعيات npm، فثبّتها في ذلك الدليل حتى -يصبح `node_modules` متاحًا (`npm install` / `pnpm install`). +إذا كان Plugin الخاص بك يستورد تبعيات npm، فثبّتها في ذلك الدليل بحيث +يكون `node_modules` متاحًا (`npm install` / `pnpm install`). -حاجز أمان: يجب أن يبقى كل إدخال في `openclaw.extensions` داخل دليل Plugin -بعد حل الروابط الرمزية. وتُرفض الإدخالات التي تخرج من دليل الحزمة. +حاجز أمان: يجب أن يبقى كل إدخال ضمن `openclaw.extensions` داخل دليل Plugin +بعد حلّ الروابط الرمزية. وتُرفض الإدخالات التي تخرج من دليل الحزمة. -ملاحظة أمان: يقوم `openclaw plugins install` بتثبيت تبعيات Plugin باستخدام -`npm install --omit=dev --ignore-scripts` (من دون نصوص دورة حياة، ومن دون تبعيات تطوير وقت التشغيل). أبقِ أشجار تبعيات Plugin -"JavaScript/TypeScript خالصة" وتجنب الحزم التي تتطلب عمليات بناء `postinstall`. +ملاحظة أمنية: يثبّت `openclaw plugins install` تبعيات Plugin باستخدام +`npm install --omit=dev --ignore-scripts` (من دون lifecycle scripts، ومن دون تبعيات تطوير وقت التشغيل). أبقِ أشجار تبعيات Plugin +"JS/TS خالصة" وتجنّب الحزم التي تتطلب بناء `postinstall`. اختياري: يمكن أن يشير `openclaw.setupEntry` إلى وحدة خفيفة مخصصة للإعداد فقط. -عندما يحتاج OpenClaw إلى أسطح إعداد لقناة Plugin معطّلة، أو -عندما تكون قناة Plugin ممكّنة لكنها لا تزال غير مضبوطة، فإنه يحمّل `setupEntry` -بدلًا من الإدخال الكامل لـ Plugin. ويبقي ذلك بدء التشغيل والإعداد أخف -عندما يكون إدخال Plugin الرئيسي أيضًا يوصل أدوات أو مرابط أو كودًا آخر -خاصًا بوقت التشغيل فقط. +عندما يحتاج OpenClaw إلى أسطح إعداد Plugin قناة معطّل، أو +عندما يكون Plugin القناة مفعّلًا لكنه لا يزال غير مهيأ، فإنه يحمّل `setupEntry` +بدلًا من مدخل Plugin الكامل. ويحافظ ذلك على خفة بدء التشغيل والإعداد +عندما يكون مدخل Plugin الرئيسي لديك يربط أيضًا أدوات أو خطافات أو كودًا آخر +مخصصًا لوقت التشغيل فقط. -اختياري: يمكن أن يفعّل -`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -لقناة Plugin المسار نفسه `setupEntry` خلال -مرحلة بدء التشغيل السابقة للاستماع في Gateway، حتى عندما تكون القناة مضبوطة بالفعل. +اختياري: يمكن لـ `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` +أن يضمّ Plugin القناة إلى مسار `setupEntry` نفسه خلال +مرحلة بدء التشغيل السابقة للاستماع في Gateway، حتى عندما تكون القناة مهيأة بالفعل. -استخدم هذا فقط عندما يغطي `setupEntry` سطح بدء التشغيل بالكامل الذي يجب أن يوجد -قبل أن تبدأ Gateway بالاستماع. وعمليًا، هذا يعني أن إدخال الإعداد -يجب أن يسجل كل إمكانية مملوكة للقناة يعتمد عليها بدء التشغيل، مثل: +استخدم هذا فقط عندما يغطي `setupEntry` بالكامل سطح بدء التشغيل الذي يجب أن يوجد +قبل أن يبدأ Gateway الاستماع. وعمليًا، يعني هذا أن مدخل الإعداد +يجب أن يسجّل كل قدرة مملوكة للقناة يعتمد عليها بدء التشغيل، مثل: -- تسجيل القناة نفسها -- أي مسارات HTTP يجب أن تكون متاحة قبل أن تبدأ Gateway بالاستماع +- تسجيل القناة نفسه +- أي مسارات HTTP يجب أن تكون متاحة قبل أن يبدأ Gateway الاستماع - أي أساليب Gateway أو أدوات أو خدمات يجب أن توجد خلال النافذة نفسها -إذا كان الإدخال الكامل لا يزال يملك أي إمكانية مطلوبة لبدء التشغيل، فلا تفعّل -هذا العلم. وأبقِ Plugin على السلوك الافتراضي ودع OpenClaw يحمّل الإدخال -الكامل أثناء بدء التشغيل. +إذا كان المدخل الكامل لا يزال يملك أي قدرة بدء تشغيل مطلوبة، فلا تفعّل +هذا العلم. أبقِ Plugin على السلوك الافتراضي ودَع OpenClaw يحمّل +المدخل الكامل أثناء بدء التشغيل. -يمكن للقنوات المجمعة أيضًا نشر مساعدات سطح عقد مخصصة للإعداد فقط يمكن للنواة -الرجوع إليها قبل تحميل وقت تشغيل القناة الكامل. ويكون سطح ترقية الإعداد الحالي: +يمكن للقنوات المضمّنة أيضًا نشر مساعدات لسطح العقد مخصصة للإعداد فقط بحيث تستطيع النواة +استشارتها قبل تحميل وقت تشغيل القناة الكامل. سطح الترقية الحالي للإعداد +هو: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` تستخدم النواة هذا السطح عندما تحتاج إلى ترقية إعداد قناة قديم ذي حساب واحد -إلى `channels..accounts.*` من دون تحميل الإدخال الكامل لـ Plugin. -ويمثل Matrix المثال المجمّع الحالي: فهو ينقل فقط مفاتيح المصادقة/bootstrap -إلى حساب مُرقّى مسمى عندما تكون الحسابات المسماة موجودة بالفعل، ويمكنه -الحفاظ على مفتاح حساب افتراضي مضبوط وغير قياسي بدلًا من إنشاء +إلى `channels..accounts.*` من دون تحميل مدخل Plugin الكامل. +وتُعد Matrix المثال المضمّن الحالي: فهي تنقل فقط مفاتيح المصادقة/التمهيد إلى +حساب مُرقّى مسمّى عندما توجد حسابات مسمّاة بالفعل، ويمكنها الحفاظ على +مفتاح حساب افتراضي غير قياسي مُهيأ بدلًا من إنشاء `accounts.default` دائمًا. -تحافظ مهايئات رقع الإعداد هذه على كسل اكتشاف سطح العقد المجمّع. إذ يبقى وقت -الاستيراد خفيفًا؛ ويتم تحميل سطح الترقية فقط عند أول استخدام بدلًا من إعادة -الدخول في بدء تشغيل القناة المجمعة عند استيراد الوحدة. +تحافظ مهايئات تصحيح الإعداد هذه على كسل اكتشاف سطح العقد المضمّن. يبقى وقت +الاستيراد خفيفًا؛ ولا يُحمَّل سطح الترقية إلا عند أول استخدام بدلًا من +إعادة الدخول إلى بدء تشغيل القناة المضمّنة عند استيراد الوحدة. -وعندما تتضمن أسطح بدء التشغيل تلك أساليب Gateway RPC، فأبقها ضمن -بادئة خاصة بـ Plugin. فمساحات أسماء إدارة النواة (`config.*`، -`exec.approvals.*`، `wizard.*`، `update.*`) تبقى محفوظة وتُحل دائمًا -إلى `operator.admin`، حتى لو طلبت Plugin نطاقًا أضيق. +عندما تتضمن أسطح بدء التشغيل هذه أساليب Gateway RPC، فأبقِها على +بادئة خاصة بالـ Plugin. وتظل مساحات أسماء الإدارة الأساسية (`config.*`، +`exec.approvals.*`، `wizard.*`، `update.*`) محجوزة وتُحلّ دائمًا +إلى `operator.admin`، حتى لو طلب Plugin نطاقًا أضيق. مثال: @@ -1450,10 +1459,10 @@ Plugin وأن تعيد استخدام المساعدات المشتركة من } ``` -### البيانات الوصفية لفهرس القناة +### بيانات وصفية لفهرس القنوات -يمكن لـ Plugins القنوات الإعلان عن بيانات الإعداد/الاكتشاف الوصفية عبر `openclaw.channel` و -تلميحات التثبيت عبر `openclaw.install`. وهذا يُبقي بيانات فهرس النواة خالية من البيانات. +يمكن لPlugins القنوات الإعلان عن بيانات وصفية للإعداد/الاكتشاف عبر `openclaw.channel` وعن +تلميحات التثبيت عبر `openclaw.install`. وهذا يُبقي بيانات الفهرس الأساسية خالية من البيانات الصلبة. مثال: @@ -1481,22 +1490,22 @@ Plugin وأن تعيد استخدام المساعدات المشتركة من } ``` -حقول `openclaw.channel` المفيدة إلى جانب المثال الأدنى: +من الحقول المفيدة في `openclaw.channel` إلى جانب المثال الأدنى: -- `detailLabel`: تسمية ثانوية لأسطح الفهرس/الحالة الأكثر غنى -- `docsLabel`: تجاوز نص الرابط الخاص بالوثائق -- `preferOver`: معرفات Plugin/قناة الأقل أولوية التي يجب أن يتفوق عليها هذا الإدخال في الفهرس -- `selectionDocsPrefix` و`selectionDocsOmitLabel` و`selectionExtras`: عناصر تحكم في النص لسطح الاختيار -- `markdownCapable`: يميز القناة على أنها قادرة على Markdown لقرارات التنسيق الصادر -- `exposure.configured`: إخفاء القناة من أسطح عرض القنوات المضبوطة عندما تضبط على `false` -- `exposure.setup`: إخفاء القناة من منتقيات الإعداد/التهيئة التفاعلية عندما تضبط على `false` -- `exposure.docs`: وسم القناة على أنها داخلية/خاصة لأسطح التنقل في الوثائق -- `showConfigured` / `showInSetup`: أسماء مستعارة قديمة ما تزال مقبولة للتوافق؛ وفضّل `exposure` -- `quickstartAllowFrom`: ضم القناة إلى تدفق `allowFrom` القياسي في البدء السريع -- `forceAccountBinding`: طلب ربط صريح للحساب حتى عند وجود حساب واحد فقط -- `preferSessionLookupForAnnounceTarget`: تفضيل البحث في الجلسة عند حل أهداف الإشعار +- `detailLabel`: تسمية ثانوية لأسطح فهرس/حالة أكثر غنى +- `docsLabel`: تجاوز نص الرابط الخاص برابط الوثائق +- `preferOver`: معرّفات Plugin/قناة أقل أولوية يجب أن يتفوّق عليها إدخال الفهرس هذا +- `selectionDocsPrefix` و`selectionDocsOmitLabel` و`selectionExtras`: عناصر تحكم لنسخة سطح الاختيار +- `markdownCapable`: يعلّم القناة على أنها قادرة على Markdown لقرارات التنسيق الصادر +- `exposure.configured`: يخفي القناة من أسطح سرد القنوات المهيأة عندما يُضبط على `false` +- `exposure.setup`: يخفي القناة من منتقيات الإعداد/التهيئة التفاعلية عندما يُضبط على `false` +- `exposure.docs`: يعلّم القناة على أنها داخلية/خاصة لأسطح التنقل في الوثائق +- `showConfigured` / `showInSetup`: أسماء مستعارة قديمة لا تزال مقبولة للتوافق؛ فضّل `exposure` +- `quickstartAllowFrom`: يضمّ القناة إلى تدفق `allowFrom` القياسي للبداية السريعة +- `forceAccountBinding`: يفرض ربط الحساب صراحةً حتى عندما يوجد حساب واحد فقط +- `preferSessionLookupForAnnounceTarget`: يفضّل البحث في الجلسة عند حلّ أهداف الإعلان -يمكن لـ OpenClaw أيضًا دمج **فهارس قنوات خارجية** (على سبيل المثال، تصدير سجل +يمكن لـ OpenClaw أيضًا دمج **فهارس القنوات الخارجية** (على سبيل المثال، تصدير سجل MPM). ضع ملف JSON في أحد المواقع التالية: - `~/.openclaw/mpm/plugins.json` @@ -1504,19 +1513,19 @@ MPM). ضع ملف JSON في أحد المواقع التالية: - `~/.openclaw/plugins/catalog.json` أو وجّه `OPENCLAW_PLUGIN_CATALOG_PATHS` (أو `OPENCLAW_MPM_CATALOG_PATHS`) إلى -ملف JSON واحد أو أكثر (مفصولة بفواصل/فواصل منقوطة/محددة بـ `PATH`). يجب أن -يحتوي كل ملف على `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. كما يقبل المحلل -`"packages"` أو `"plugins"` بوصفها أسماء مستعارة قديمة للمفتاح `"entries"`. +ملف JSON واحد أو أكثر (مفصولة بفواصل/فواصل منقوطة/محددة بـ `PATH`). يجب أن يحتوي كل ملف +على `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. ويقبل المحلّل أيضًا +`"packages"` أو `"plugins"` كأسماء مستعارة قديمة للمفتاح `"entries"`. -## Plugins محرّك السياق +## Plugins محرك السياق -تملك Plugins محرّك السياق تنسيق سياق الجلسة لعمليات الإدخال والتجميع و -Compaction. سجّلها من Plugin لديك باستخدام -`api.registerContextEngine(id, factory)`، ثم حدّد المحرّك النشط عبر +تملك Plugins محرك السياق تنسيق سياق الجلسة لعمليات الإدخال والتجميع +وCompaction. سجّلها من Plugin الخاص بك باستخدام +`api.registerContextEngine(id, factory)`، ثم حدّد المحرك النشط عبر `plugins.slots.contextEngine`. -استخدم هذا عندما تحتاج Plugin لديك إلى استبدال مسار السياق الافتراضي أو توسيعه -بدلًا من مجرد إضافة بحث في الذاكرة أو مرابط. +استخدم هذا عندما يحتاج Plugin الخاص بك إلى استبدال خط أنابيب السياق الافتراضي +أو توسيعه بدلًا من مجرد إضافة بحث الذاكرة أو الخطافات. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1544,8 +1553,8 @@ export default function (api) { } ``` -إذا كان محرّكك **لا** يملك خوارزمية Compaction، فأبقِ `compact()` -منفّذًا وفوّضه صراحةً: +إذا كان محركك **لا** يملك خوارزمية Compaction، فأبقِ `compact()` +مُنفّذًا وفوّضه صراحةً: ```ts import { @@ -1580,50 +1589,50 @@ export default function (api) { } ``` -## إضافة إمكانية جديدة +## إضافة قدرة جديدة -عندما تحتاج Plugin إلى سلوك لا يناسب API الحالية، فلا تتجاوز -نظام Plugins عبر توغل خاص. أضف الإمكانية المفقودة. +عندما يحتاج Plugin إلى سلوك لا يتناسب مع واجهة API الحالية، فلا تتجاوز +نظام Plugins عبر وصول خاص مباشر. أضف القدرة المفقودة. التسلسل الموصى به: 1. تعريف عقد النواة - قرر السلوك المشترك الذي يجب أن تملكه النواة: السياسة، والبديل الاحتياطي، ودمج الإعداد، - ودورة الحياة، والدلالات المواجهة للقناة، وشكل مساعد وقت التشغيل. -2. إضافة أسطح Plugin/وقت التشغيل المطبوعة للتسجيل + حدّد السلوك المشترك الذي يجب أن تملكه النواة: السياسة، والتراجع، ودمج الإعدادات، + ودورة الحياة، والدلالات المواجهة للقنوات، وشكل مساعد وقت التشغيل. +2. إضافة أسطح تسجيل/وقت تشغيل مكتوبة النوع للـ Plugin وسّع `OpenClawPluginApi` و/أو `api.runtime` بأصغر - سطح إمكانية مطبوع ومفيد. -3. توصيل النواة + مستهلكي القنوات/الميزات - يجب أن تستهلك Plugins القنوات والميزات الإمكانية الجديدة عبر النواة، - لا عن طريق استيراد تنفيذ مورّد مباشرة. + سطح قدرة مكتوب النوع ومفيد. +3. ربط مستهلكي النواة + القناة/الميزة + يجب أن تستهلك القنوات وPlugins الميزات القدرة الجديدة عبر النواة، + لا عبر استيراد تنفيذ مورّد مباشرة. 4. تسجيل تنفيذات المورّد - عندها تسجّل Plugins المورّدين واجهاتها الخلفية ضمن الإمكانية. -5. إضافة تغطية للعقود - أضف اختبارات حتى تبقى الملكية وشكل التسجيل صريحين بمرور الوقت. + بعدها تسجّل Plugins المورّدين واجهاتها الخلفية مقابل القدرة. +5. إضافة تغطية العقود + أضف اختبارات حتى تبقى الملكية وشكل التسجيل واضحين مع مرور الوقت. -بهذه الطريقة يبقى OpenClaw صاحب رأي من دون أن يصبح مضمّنًا بشكل صلب في -رؤية موفّر واحد للعالم. راجع [دليل الإمكانات](/ar/plugins/architecture) -للحصول على قائمة ملفات عملية ومثال مطبّق. +هكذا يبقى OpenClaw ذا توجه واضح من دون أن يصبح مقيّدًا برؤية +مزود واحد للعالم. راجع [دليل القدرات العملي](/ar/plugins/architecture) +للحصول على قائمة ملفات عملية ومثال تطبيقي. -### قائمة التحقق الخاصة بالإمكانات +### قائمة التحقق الخاصة بالقدرات -عندما تضيف إمكانية جديدة، فعادةً يجب أن يطال التنفيذ -هذه الأسطح معًا: +عند إضافة قدرة جديدة، ينبغي عادةً أن يلمس التنفيذ هذه +الأسطح معًا: -- أنواع عقد النواة في `src//types.ts` -- مساعد المشغّل/وقت التشغيل في النواة في `src//runtime.ts` -- سطح تسجيل API الخاصة بـ Plugin في `src/plugins/types.ts` -- توصيل سجل Plugin في `src/plugins/registry.ts` +- أنواع عقود النواة في `src//types.ts` +- مشغّل/مساعد وقت تشغيل النواة في `src//runtime.ts` +- سطح تسجيل واجهة Plugin API في `src/plugins/types.ts` +- ربط سجل Plugins في `src/plugins/registry.ts` - كشف وقت تشغيل Plugin في `src/plugins/runtime/*` عندما تحتاج - Plugins الميزات/القنوات إلى استهلاكه + Plugins الميزة/القناة إلى استهلاكه - مساعدات الالتقاط/الاختبار في `src/test-utils/plugin-registration.ts` - تأكيدات الملكية/العقد في `src/plugins/contracts/registry.ts` -- وثائق المشغل/Plugin في `docs/` +- وثائق المشغّل/Plugin في `docs/` -إذا كان أحد هذه الأسطح مفقودًا، فغالبًا ما تكون هذه علامة على أن الإمكانية +إذا كان أحد هذه الأسطح مفقودًا، فعادةً ما تكون هذه علامة على أن القدرة لم تُدمج بالكامل بعد. -### قالب الإمكانية +### قالب القدرة النمط الأدنى: @@ -1659,7 +1668,7 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); وهذا يُبقي القاعدة بسيطة: -- تملك النواة عقد الإمكانية + التنسيق +- تملك النواة عقد القدرة + التنسيق - تملك Plugins المورّدين تنفيذات المورّد -- تستهلك Plugins الميزات/القنوات مساعدات وقت التشغيل -- تُبقي اختبارات العقد الملكية صريحة +- تستهلك Plugins الميزة/القناة مساعدات وقت التشغيل +- تُبقي اختبارات العقود الملكية واضحة diff --git a/docs/ar/plugins/manifest.md b/docs/ar/plugins/manifest.md index 4b5459331..2f5d8b038 100644 --- a/docs/ar/plugins/manifest.md +++ b/docs/ar/plugins/manifest.md @@ -1,74 +1,75 @@ --- read_when: - - أنت تبني Plugin لـ OpenClaw + - أنت تقوم ببناء Plugin لـ OpenClaw - تحتاج إلى شحن مخطط إعدادات Plugin أو تصحيح أخطاء التحقق من صحة Plugin -summary: متطلبات Plugin manifest + مخطط JSON ‏(التحقق الصارم من صحة الإعدادات) +summary: متطلبات Plugin manifest + مخطط JSON (التحقق الصارم من صحة الإعدادات) title: Plugin Manifest x-i18n: - generated_at: "2026-04-12T23:28:37Z" + generated_at: "2026-04-15T07:18:06Z" model: gpt-5.4 provider: openai - source_hash: 93b57c7373e4ccd521b10945346db67991543bd2bed4cc8b6641e1f215b48579 + source_hash: ba2183bfa8802871e4ef33a0ebea290606e8351e9e83e25ee72456addb768730 source_path: plugins/manifest.md workflow: 15 --- -# Plugin manifest ‏(`openclaw.plugin.json`) +# Plugin manifest (`openclaw.plugin.json`) هذه الصفحة مخصّصة فقط لـ **Plugin manifest الأصلي في OpenClaw**. -للتعرف على تخطيطات الحزم المتوافقة، راجع [حزم Plugin](/ar/plugins/bundles). +للاطّلاع على تنسيقات الحِزم المتوافقة، راجع [Plugin bundles](/ar/plugins/bundles). -تستخدم تنسيقات الحزم المتوافقة ملفات manifest مختلفة: +تستخدم تنسيقات الحِزم المتوافقة ملفات manifest مختلفة: - حزمة Codex: `.codex-plugin/plugin.json` -- حزمة Claude: `.claude-plugin/plugin.json` أو تخطيط مكوّن Claude الافتراضي - من دون manifest +- حزمة Claude: `.claude-plugin/plugin.json` أو تنسيق مكوّن Claude الافتراضي + بدون manifest - حزمة Cursor: `.cursor-plugin/plugin.json` -يكتشف OpenClaw تلقائيًا تخطيطات الحزم هذه أيضًا، لكنها لا تُتحقق -مقابل مخطط `openclaw.plugin.json` الموضّح هنا. +يكتشف OpenClaw هذه تنسيقات الحِزم تلقائيًا أيضًا، لكنها لا تُتحقَّق +مقارنتها بمخطط `openclaw.plugin.json` الموضَّح هنا. -بالنسبة إلى الحزم المتوافقة، يقرأ OpenClaw حاليًا بيانات تعريف الحزمة بالإضافة إلى -جذور skill المعلنة، وجذور أوامر Claude، والقيم الافتراضية لملف `settings.json` في حزمة Claude، -والقيم الافتراضية لـ Claude bundle LSP، وحِزم Hook المدعومة عندما يطابق التخطيط -توقعات وقت تشغيل OpenClaw. +بالنسبة إلى الحِزم المتوافقة، يقرأ OpenClaw حاليًا بيانات الحزمة الوصفية +بالإضافة إلى جذور Skills المعلنة، وجذور أوامر Claude، والقيم الافتراضية +لملف `settings.json` في حزمة Claude، والقيم الافتراضية لـ Claude bundle LSP، +وحِزم hooks المدعومة عندما يطابق التنسيق توقعات وقت تشغيل OpenClaw. -يجب على كل Plugin أصلي في OpenClaw **أن** يوفّر ملف `openclaw.plugin.json` داخل -**جذر Plugin**. يستخدم OpenClaw هذا الـ manifest للتحقق من صحة الإعدادات +يجب على كل Plugin أصلي في OpenClaw **أن يضمّ** ملف `openclaw.plugin.json` في +**جذر Plugin**. يستخدم OpenClaw هذا manifest للتحقق من صحة الإعدادات **من دون تنفيذ كود Plugin**. وتُعامل ملفات manifest المفقودة أو غير الصالحة -كأخطاء Plugin وتمنع التحقق من صحة الإعدادات. +على أنها أخطاء في Plugin وتمنع التحقق من صحة الإعدادات. -راجع الدليل الكامل لنظام Plugin: [Plugins](/ar/tools/plugin). -وللاطلاع على نموذج القدرات الأصلي وإرشادات التوافق الخارجي الحالية: -[نموذج القدرات](/ar/plugins/architecture#public-capability-model). +راجع الدليل الكامل لنظام Plugins: [Plugins](/ar/tools/plugin). +وللاطّلاع على نموذج القدرات الأصلي وإرشادات التوافق الخارجي الحالية: +[Capability model](/ar/plugins/architecture#public-capability-model). -## ما وظيفة هذا الملف +## ما الذي يفعله هذا الملف -`openclaw.plugin.json` هو ملف البيانات الوصفية الذي يقرأه OpenClaw قبل أن يحمّل +`openclaw.plugin.json` هو البيانات الوصفية التي يقرأها OpenClaw قبل أن يحمّل كود Plugin الخاص بك. استخدمه من أجل: - هوية Plugin - التحقق من صحة الإعدادات -- بيانات تعريف المصادقة والإعداد الأولي التي يجب أن تكون متاحة من دون تشغيل وقت تشغيل Plugin -- تلميحات تنشيط خفيفة يمكن لأسطح مستوى التحكم فحصها قبل تحميل وقت التشغيل -- واصفات إعداد خفيفة يمكن لأسطح الإعداد/التهيئة الأولية فحصها قبل +- بيانات auth وonboarding الوصفية التي يجب أن تكون متاحة دون تشغيل وقت تشغيل Plugin +- تلميحات تنشيط منخفضة الكلفة يمكن لأسطح control plane فحصها قبل تحميل وقت التشغيل +- واصفات إعداد منخفضة الكلفة يمكن لأسطح الإعداد/التهيئة الأولية فحصها قبل تحميل وقت التشغيل -- بيانات تعريف الأسماء البديلة والتمكين التلقائي التي يجب حلها قبل تحميل وقت تشغيل Plugin -- بيانات تعريف مختصرة لملكية عائلة النموذج يجب أن تفعّل - Plugin تلقائيًا قبل تحميل وقت التشغيل -- لقطات ثابتة لملكية القدرات تُستخدم في أسلاك التوافق المجمّعة وتغطية العقود -- بيانات تعريف إعدادات خاصة بالقنوات يجب دمجها في أسطح الكتالوج والتحقق - من دون تحميل وقت التشغيل +- بيانات alias وauto-enable الوصفية التي يجب حلّها قبل تحميل وقت تشغيل Plugin +- بيانات وصفية مختصرة لملكية عائلة النموذج ينبغي أن تفعّل Plugin تلقائيًا قبل تحميل وقت التشغيل +- لقطات ثابتة لملكية القدرات تُستخدم في توصيل التوافق المضمّن وتغطية العقود +- بيانات وصفية منخفضة الكلفة لمشغّل QA يمكن للمضيف المشترك `openclaw qa` فحصها + قبل تحميل وقت تشغيل Plugin +- بيانات وصفية خاصة بإعدادات القنوات ينبغي دمجها في أسطح الفهرسة والتحقق + من الصحة من دون تحميل وقت التشغيل - تلميحات واجهة المستخدم للإعدادات لا تستخدمه من أجل: - تسجيل سلوك وقت التشغيل -- تعريف نقاط دخول الكود -- بيانات تعريف تثبيت npm +- التصريح بنقاط دخول الكود +- بيانات `npm` الوصفية الخاصة بالتثبيت فهذه تنتمي إلى كود Plugin الخاص بك وإلى `package.json`. @@ -85,7 +86,7 @@ x-i18n: } ``` -## مثال موسّع +## مثال غني ```json { @@ -143,62 +144,63 @@ x-i18n: ## مرجع الحقول ذات المستوى الأعلى -| الحقل | مطلوب | النوع | المعنى | -| ----------------------------------- | ------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | نعم | `string` | معرّف Plugin القياسي. هذا هو المعرّف المستخدم في `plugins.entries.`. | -| `configSchema` | نعم | `object` | مخطط JSON Schema مضمن لإعدادات هذا Plugin. | -| `enabledByDefault` | لا | `true` | يحدّد أن Plugin المجمّع مفعّل افتراضيًا. احذف هذا الحقل، أو اضبطه على أي قيمة ليست `true`، لترك Plugin معطّلًا افتراضيًا. | -| `legacyPluginIds` | لا | `string[]` | معرّفات قديمة تُطبّع إلى معرّف Plugin القياسي هذا. | -| `autoEnableWhenConfiguredProviders` | لا | `string[]` | معرّفات Provider التي يجب أن تفعّل هذا Plugin تلقائيًا عندما تشير إليها المصادقة أو الإعدادات أو مراجع النموذج. | -| `kind` | لا | `"memory"` \| `"context-engine"` | يصرّح بنوع Plugin حصري يُستخدم بواسطة `plugins.slots.*`. | -| `channels` | لا | `string[]` | معرّفات القنوات التي يملكها هذا Plugin. تُستخدم للاكتشاف والتحقق من صحة الإعدادات. | -| `providers` | لا | `string[]` | معرّفات Provider التي يملكها هذا Plugin. | -| `modelSupport` | لا | `object` | بيانات تعريف مختصرة لعائلة النموذج يملكها manifest وتُستخدم لتحميل Plugin تلقائيًا قبل وقت التشغيل. | -| `cliBackends` | لا | `string[]` | معرّفات واجهات CLI الخلفية للاستدلال التي يملكها هذا Plugin. تُستخدم للتنشيط التلقائي عند بدء التشغيل من مراجع الإعدادات الصريحة. | -| `commandAliases` | لا | `object[]` | أسماء الأوامر التي يملكها هذا Plugin والتي يجب أن تنتج إعدادات خاصة بالـ Plugin وتشخيصات CLI قبل تحميل وقت التشغيل. | -| `providerAuthEnvVars` | لا | `Record` | بيانات تعريف خفيفة لمتغيرات بيئة مصادقة Provider يمكن لـ OpenClaw فحصها من دون تحميل كود Plugin. | -| `providerAuthAliases` | لا | `Record` | معرّفات Provider التي يجب أن تعيد استخدام معرّف Provider آخر لبحث المصادقة، مثل Provider خاص بالبرمجة يشارك مفتاح API الأساسي وملفات تعريف المصادقة مع Provider الأساسي. | -| `channelEnvVars` | لا | `Record` | بيانات تعريف خفيفة لمتغيرات بيئة القنوات يمكن لـ OpenClaw فحصها من دون تحميل كود Plugin. استخدم هذا لأسطح إعداد القنوات أو المصادقة المعتمدة على البيئة التي ينبغي أن تراها مساعدات بدء التشغيل/الإعداد العامة. | -| `providerAuthChoices` | لا | `object[]` | بيانات تعريف خفيفة لاختيارات المصادقة لمحددات الإعداد الأولي، وحل Provider المفضّل، وربط أعلام CLI البسيطة. | -| `activation` | لا | `object` | تلميحات تنشيط خفيفة لتحميل يعتمد على Provider أو الأمر أو القناة أو المسار أو القدرات. بيانات تعريف فقط؛ وما يزال وقت تشغيل Plugin يملك السلوك الفعلي. | -| `setup` | لا | `object` | واصفات إعداد/تهيئة أولية خفيفة يمكن لأسطح الاكتشاف والإعداد فحصها من دون تحميل وقت تشغيل Plugin. | -| `contracts` | لا | `object` | لقطة قدرات ثابتة مجمّعة لملكية speech وrealtime transcription وrealtime voice وmedia-understanding وimage-generation وmusic-generation وvideo-generation وweb-fetch وweb search والأدوات. | -| `channelConfigs` | لا | `Record` | بيانات تعريف إعدادات القنوات المملوكة من manifest والتي تُدمج في أسطح الاكتشاف والتحقق قبل تحميل وقت التشغيل. | -| `skills` | لا | `string[]` | أدلة Skills التي يجب تحميلها، نسبةً إلى جذر Plugin. | -| `name` | لا | `string` | اسم Plugin مقروء للبشر. | -| `description` | لا | `string` | ملخص قصير يظهر في أسطح Plugin. | -| `version` | لا | `string` | إصدار معلوماتي لـ Plugin. | -| `uiHints` | لا | `Record` | تسميات واجهة المستخدم، والعناصر النائبة، وتلميحات الحساسية لحقول الإعدادات. | +| الحقل | مطلوب | النوع | ما الذي يعنيه | +| ----------------------------------- | ------ | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | نعم | `string` | المعرّف القياسي لـ Plugin. هذا هو المعرّف المستخدم في `plugins.entries.`. | +| `configSchema` | نعم | `object` | مخطط JSON مضمن لإعدادات هذا Plugin. | +| `enabledByDefault` | لا | `true` | يحدّد أن Plugin مضمّن ومفعّل افتراضيًا. احذفه، أو اضبطه على أي قيمة غير `true`، لترك Plugin معطّلًا افتراضيًا. | +| `legacyPluginIds` | لا | `string[]` | معرّفات قديمة تُطبَّع إلى معرّف Plugin القياسي هذا. | +| `autoEnableWhenConfiguredProviders` | لا | `string[]` | معرّفات providers التي يجب أن تفعّل هذا Plugin تلقائيًا عندما تشير auth أو الإعدادات أو مراجع النماذج إليها. | +| `kind` | لا | `"memory"` \| `"context-engine"` | يصرّح بنوع Plugin حصري يُستخدم بواسطة `plugins.slots.*`. | +| `channels` | لا | `string[]` | معرّفات القنوات المملوكة لهذا Plugin. تُستخدم للاكتشاف والتحقق من صحة الإعدادات. | +| `providers` | لا | `string[]` | معرّفات providers المملوكة لهذا Plugin. | +| `modelSupport` | لا | `object` | بيانات وصفية مختصرة مملوكة للـ manifest لعائلة النماذج وتُستخدم لتحميل Plugin تلقائيًا قبل وقت التشغيل. | +| `cliBackends` | لا | `string[]` | معرّفات backends الخاصة بالاستدلال في CLI والمملوكة لهذا Plugin. تُستخدم للتنشيط التلقائي عند بدء التشغيل من مراجع إعدادات صريحة. | +| `commandAliases` | لا | `object[]` | أسماء الأوامر المملوكة لهذا Plugin والتي يجب أن تنتج إعدادات وتشخيصات CLI مدركة للـ Plugin قبل تحميل وقت التشغيل. | +| `providerAuthEnvVars` | لا | `Record` | بيانات وصفية منخفضة الكلفة لمتغيرات بيئة auth الخاصة بالـ provider يمكن لـ OpenClaw فحصها من دون تحميل كود Plugin. | +| `providerAuthAliases` | لا | `Record` | معرّفات providers التي يجب أن تعيد استخدام معرّف provider آخر لبحث auth، مثل provider للبرمجة يشارك مفتاح API الأساسي وملفات auth التعريفية الخاصة بالـ provider الأساسي. | +| `channelEnvVars` | لا | `Record` | بيانات وصفية منخفضة الكلفة لمتغيرات بيئة القنوات يمكن لـ OpenClaw فحصها من دون تحميل كود Plugin. استخدم هذا لإعداد القنوات المعتمد على البيئة أو لأسطح auth التي ينبغي أن تراها مساعدات البدء/الإعداد العامة. | +| `providerAuthChoices` | لا | `object[]` | بيانات وصفية منخفضة الكلفة لاختيارات auth من أجل منتقيات onboarding، وحل provider المفضّل، وربط أعلام CLI البسيط. | +| `activation` | لا | `object` | تلميحات تنشيط منخفضة الكلفة لتحميل يعتمد على provider أو command أو channel أو route أو capability. بيانات وصفية فقط؛ لا يزال وقت تشغيل Plugin يملك السلوك الفعلي. | +| `setup` | لا | `object` | واصفات إعداد/تهيئة أولية منخفضة الكلفة يمكن لأسطح الاكتشاف والإعداد فحصها من دون تحميل وقت تشغيل Plugin. | +| `qaRunners` | لا | `object[]` | واصفات منخفضة الكلفة لمشغّلات QA يستخدمها المضيف المشترك `openclaw qa` قبل تحميل وقت تشغيل Plugin. | +| `contracts` | لا | `object` | لقطة قدرات ثابتة ومضمّنة لـ speech وrealtime transcription وrealtime voice وmedia-understanding وimage-generation وmusic-generation وvideo-generation وweb-fetch وweb search وملكية الأدوات. | +| `channelConfigs` | لا | `Record` | بيانات وصفية مملوكة للـ manifest لإعدادات القنوات تُدمج في أسطح الاكتشاف والتحقق قبل تحميل وقت التشغيل. | +| `skills` | لا | `string[]` | أدلة Skills المطلوب تحميلها، نسبةً إلى جذر Plugin. | +| `name` | لا | `string` | اسم Plugin مقروء للبشر. | +| `description` | لا | `string` | ملخص قصير يظهر في أسطح Plugin. | +| `version` | لا | `string` | إصدار Plugin لأغراض معلوماتية. | +| `uiHints` | لا | `Record` | تسميات واجهة المستخدم، والعناصر النائبة، وتلميحات الحساسية لحقول الإعدادات. | ## مرجع `providerAuthChoices` -يصف كل إدخال في `providerAuthChoices` خيار إعداد أولي أو مصادقة واحدًا. -يقرأ OpenClaw هذا قبل تحميل وقت تشغيل Provider. +يصف كل عنصر في `providerAuthChoices` خيارًا واحدًا من خيارات onboarding أو auth. +يقرأ OpenClaw هذا قبل تحميل وقت تشغيل provider. -| الحقل | مطلوب | النوع | المعنى | -| -------------------- | ------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------ | -| `provider` | نعم | `string` | معرّف Provider الذي ينتمي إليه هذا الخيار. | -| `method` | نعم | `string` | معرّف طريقة المصادقة المراد التوجيه إليها. | -| `choiceId` | نعم | `string` | معرّف ثابت لخيار المصادقة يُستخدم في مسارات الإعداد الأولي وCLI. | -| `choiceLabel` | لا | `string` | تسمية موجهة للمستخدم. إذا تم حذفها، يعود OpenClaw إلى `choiceId`. | -| `choiceHint` | لا | `string` | نص مساعد قصير للمحدد. | -| `assistantPriority` | لا | `number` | القيم الأقل تُرتّب أولًا في المحددات التفاعلية التي يقودها المساعد. | -| `assistantVisibility`| لا | `"visible"` \| `"manual-only"` | إخفاء الخيار من محددات المساعد مع الاستمرار في السماح بالاختيار اليدوي عبر CLI. | -| `deprecatedChoiceIds`| لا | `string[]` | معرّفات خيارات قديمة يجب أن تعيد توجيه المستخدمين إلى هذا الخيار البديل. | -| `groupId` | لا | `string` | معرّف مجموعة اختياري لتجميع الخيارات ذات الصلة. | -| `groupLabel` | لا | `string` | تسمية موجهة للمستخدم لتلك المجموعة. | -| `groupHint` | لا | `string` | نص مساعد قصير للمجموعة. | -| `optionKey` | لا | `string` | مفتاح خيار داخلي لمسارات المصادقة البسيطة ذات العلم الواحد. | -| `cliFlag` | لا | `string` | اسم علم CLI، مثل `--openrouter-api-key`. | -| `cliOption` | لا | `string` | الشكل الكامل لخيار CLI، مثل `--openrouter-api-key `. | -| `cliDescription` | لا | `string` | الوصف المستخدم في مساعدة CLI. | -| `onboardingScopes` | لا | `Array<"text-inference" \| "image-generation">` | أسطح الإعداد الأولي التي يجب أن يظهر فيها هذا الخيار. إذا تم حذفه، تكون القيمة الافتراضية `["text-inference"]`. | +| الحقل | مطلوب | النوع | ما الذي يعنيه | +| -------------------- | ------ | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | +| `provider` | نعم | `string` | معرّف Provider الذي ينتمي إليه هذا الخيار. | +| `method` | نعم | `string` | معرّف طريقة auth المطلوب التوجيه إليها. | +| `choiceId` | نعم | `string` | معرّف ثابت لخيار auth تستخدمه تدفقات onboarding وCLI. | +| `choiceLabel` | لا | `string` | تسمية موجهة للمستخدم. إذا حُذفت، يعود OpenClaw إلى `choiceId`. | +| `choiceHint` | لا | `string` | نص مساعد قصير للمنتقي. | +| `assistantPriority` | لا | `number` | تُرتَّب القيم الأقل أولًا في المنتقيات التفاعلية التي يقودها المساعد. | +| `assistantVisibility`| لا | `"visible"` \| `"manual-only"` | يُخفي الخيار من منتقيات المساعد مع الاستمرار في السماح بالاختيار اليدوي عبر CLI. | +| `deprecatedChoiceIds`| لا | `string[]` | معرّفات خيارات قديمة يجب أن تعيد توجيه المستخدمين إلى هذا الخيار البديل. | +| `groupId` | لا | `string` | معرّف مجموعة اختياري لتجميع الخيارات ذات الصلة. | +| `groupLabel` | لا | `string` | تسمية موجهة للمستخدم لتلك المجموعة. | +| `groupHint` | لا | `string` | نص مساعد قصير للمجموعة. | +| `optionKey` | لا | `string` | مفتاح خيار داخلي لتدفقات auth البسيطة التي تعتمد على علم واحد. | +| `cliFlag` | لا | `string` | اسم علم CLI، مثل `--openrouter-api-key`. | +| `cliOption` | لا | `string` | الشكل الكامل لخيار CLI، مثل `--openrouter-api-key `. | +| `cliDescription` | لا | `string` | الوصف المستخدم في تعليمات CLI. | +| `onboardingScopes` | لا | `Array<"text-inference" \| "image-generation">` | أسطح onboarding التي يجب أن يظهر فيها هذا الخيار. إذا حُذفت، تكون القيمة الافتراضية `["text-inference"]`. | ## مرجع `commandAliases` -استخدم `commandAliases` عندما يملك Plugin اسم أمر وقت تشغيل قد يضعه المستخدمون -عن طريق الخطأ في `plugins.allow` أو يحاولون تشغيله كأمر CLI جذري. يستخدم OpenClaw -هذه البيانات الوصفية لأغراض التشخيص من دون استيراد كود وقت تشغيل Plugin. +استخدم `commandAliases` عندما يملك Plugin اسم أمر في وقت التشغيل قد يضعه +المستخدمون عن طريق الخطأ في `plugins.allow` أو يحاولون تشغيله كأمر CLI جذري. +يستخدم OpenClaw هذه البيانات الوصفية للتشخيصات من دون استيراد كود وقت تشغيل Plugin. ```json { @@ -212,22 +214,46 @@ x-i18n: } ``` -| الحقل | مطلوب | النوع | المعنى | -| ----------- | ------ | ----------------- | ---------------------------------------------------------------------------- | -| `name` | نعم | `string` | اسم الأمر الذي ينتمي إلى هذا Plugin. | -| `kind` | لا | `"runtime-slash"` | يحدد الاسم البديل كأمر slash للدردشة بدلًا من أمر CLI جذري. | -| `cliCommand`| لا | `string` | أمر CLI جذري ذو صلة يُقترح لعمليات CLI، إذا كان موجودًا. | +| الحقل | مطلوب | النوع | ما الذي يعنيه | +| ----------- | ------ | ----------------- | -------------------------------------------------------------------------- | +| `name` | نعم | `string` | اسم الأمر الذي ينتمي إلى هذا Plugin. | +| `kind` | لا | `"runtime-slash"` | يحدّد أن alias هو أمر slash للدردشة وليس أمر CLI جذريًا. | +| `cliCommand`| لا | `string` | أمر CLI جذري ذو صلة يُقترح لعمليات CLI، إذا كان موجودًا. | ## مرجع `activation` -استخدم `activation` عندما يمكن لـ Plugin أن يصرّح بتكلفة منخفضة عن أحداث مستوى التحكم +استخدم `activation` عندما يستطيع Plugin التصريح بكلفة منخفضة عن أحداث control plane التي ينبغي أن تفعّله لاحقًا. -هذه الكتلة عبارة عن بيانات وصفية فقط. فهي لا تسجل سلوك وقت التشغيل، ولا -تحل محل `register(...)` أو `setupEntry` أو نقاط دخول وقت التشغيل/Plugin الأخرى. -يستخدمها المستهلكون الحاليون كتلميح تضييق قبل تحميل Plugin الأوسع، لذلك فإن -غياب بيانات تعريف التنشيط عادةً لا يكلّف سوى الأداء؛ ولا ينبغي أن -يغيّر الصحة ما دامت آليات fallback القديمة لملكية manifest لا تزال موجودة. +## مرجع `qaRunners` + +استخدم `qaRunners` عندما يساهم Plugin بمشغّل نقل واحد أو أكثر تحت الجذر +المشترك `openclaw qa`. احرص على أن تكون هذه البيانات الوصفية منخفضة الكلفة +وثابتة؛ إذ لا يزال وقت تشغيل Plugin يملك تسجيل CLI الفعلي من خلال سطح +`runtime-api.ts` خفيف يصدّر `qaRunnerCliRegistrations`. + +```json +{ + "qaRunners": [ + { + "commandName": "matrix", + "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver" + } + ] +} +``` + +| الحقل | مطلوب | النوع | ما الذي يعنيه | +| ------------ | ------ | -------- | ---------------------------------------------------------------------------- | +| `commandName`| نعم | `string` | الأمر الفرعي المُثبت تحت `openclaw qa`، مثل `matrix`. | +| `description`| لا | `string` | نص مساعدة احتياطي يُستخدم عندما يحتاج المضيف المشترك إلى أمر stub. | + +هذه الكتلة هي بيانات وصفية فقط. فهي لا تسجل سلوك وقت التشغيل، ولا تستبدل +`register(...)` أو `setupEntry` أو نقاط دخول وقت التشغيل/Plugin الأخرى. +يستخدمها المستهلكون الحاليون كتلميح للتضييق قبل تحميل Plugin على نطاق أوسع، +لذا فإن غياب بيانات activation الوصفية يؤدي عادةً فقط إلى تكلفة في الأداء؛ +ولا ينبغي أن يغيّر الصحة ما دامت آليات الرجوع إلى ملكية manifest القديمة +لا تزال موجودة. ```json { @@ -241,28 +267,28 @@ x-i18n: } ``` -| الحقل | مطلوب | النوع | المعنى | -| ---------------- | ------ | ---------------------------------------------------- | ------------------------------------------------------------- | -| `onProviders` | لا | `string[]` | معرّفات Provider التي ينبغي أن تفعّل هذا Plugin عند طلبها. | -| `onCommands` | لا | `string[]` | معرّفات الأوامر التي ينبغي أن تفعّل هذا Plugin. | -| `onChannels` | لا | `string[]` | معرّفات القنوات التي ينبغي أن تفعّل هذا Plugin. | -| `onRoutes` | لا | `string[]` | أنواع المسارات التي ينبغي أن تفعّل هذا Plugin. | -| `onCapabilities` | لا | `Array<"provider" \| "channel" \| "tool" \| "hook">` | تلميحات قدرات عامة تُستخدم في تخطيط التنشيط على مستوى التحكم. | +| الحقل | مطلوب | النوع | ما الذي يعنيه | +| ---------------- | ------ | ---------------------------------------------------- | ------------------------------------------------------------------ | +| `onProviders` | لا | `string[]` | معرّفات providers التي يجب أن تفعّل هذا Plugin عند طلبها. | +| `onCommands` | لا | `string[]` | معرّفات الأوامر التي يجب أن تفعّل هذا Plugin. | +| `onChannels` | لا | `string[]` | معرّفات القنوات التي يجب أن تفعّل هذا Plugin. | +| `onRoutes` | لا | `string[]` | أنواع routes التي يجب أن تفعّل هذا Plugin. | +| `onCapabilities` | لا | `Array<"provider" \| "channel" \| "tool" \| "hook">` | تلميحات قدرات عامة تُستخدم في تخطيط التنشيط ضمن control plane. | -المستهلكون الحاليون الفعليون: +المستهلكون المباشرون الحاليون: -- تخطيط CLI المُفعّل بالأوامر يعود إلى الآلية القديمة - `commandAliases[].cliCommand` أو `commandAliases[].name` -- تخطيط الإعداد/القنوات المُفعّل بالقنوات يعود إلى ملكية - `channels[]` القديمة عندما تكون بيانات تعريف تنشيط القنوات الصريحة مفقودة -- تخطيط الإعداد/وقت التشغيل المُفعّل بمزوّد Provider يعود إلى الملكية القديمة - `providers[]` وملكية `cliBackends[]` ذات المستوى الأعلى عندما تكون بيانات تعريف - تنشيط Provider الصريحة مفقودة +- يعود تخطيط CLI المحفَّز بالأوامر إلى + `commandAliases[].cliCommand` أو `commandAliases[].name` القديمين +- يعود تخطيط الإعداد/القنوات المحفَّز بالقنوات إلى ملكية `channels[]` القديمة + عندما تكون بيانات تنشيط القنوات الصريحة مفقودة +- يعود تخطيط الإعداد/وقت التشغيل المحفَّز بالـ provider إلى ملكية + `providers[]` وملكية `cliBackends[]` ذات المستوى الأعلى القديمة عندما + تكون بيانات تنشيط provider الصريحة مفقودة ## مرجع `setup` -استخدم `setup` عندما تحتاج أسطح الإعداد والتهيئة الأولية إلى بيانات تعريف منخفضة الكلفة يملكها Plugin -قبل تحميل وقت التشغيل. +استخدم `setup` عندما تحتاج أسطح الإعداد والتهيئة الأولية إلى بيانات وصفية +منخفضة الكلفة ومملوكة للـ Plugin قبل تحميل وقت التشغيل. ```json { @@ -281,41 +307,41 @@ x-i18n: } ``` -يبقى `cliBackends` ذو المستوى الأعلى صالحًا ويستمر في وصف -واجهات CLI الخلفية للاستدلال. أمّا `setup.cliBackends` فهو سطح الواصفات -الخاص بالإعداد لمسارات مستوى التحكم/الإعداد التي ينبغي أن تبقى بيانات وصفية فقط. +يبقى `cliBackends` على المستوى الأعلى صالحًا ويواصل وصف backends الخاصة +بالاستدلال في CLI. أما `setup.cliBackends` فهو سطح الواصفات الخاص بالإعداد +لتدفقات control plane/الإعداد التي ينبغي أن تبقى بيانات وصفية فقط. -عند وجودها، تُعد `setup.providers` و`setup.cliBackends` سطح البحث المفضل -القائم على الواصفات أولًا لاكتشاف الإعداد. وإذا كان الواصف يضيّق فقط -Plugin المرشح وكان الإعداد لا يزال يحتاج إلى Hooks وقت تشغيل أغنى في وقت الإعداد، -فاضبط `requiresRuntime: true` وأبقِ `setup-api` في مكانه +عند وجوده، يكون `setup.providers` و`setup.cliBackends` هما سطح البحث المفضّل +المعتمد على الواصفات أولًا لاكتشاف الإعداد. إذا كان الواصف يضيّق فقط نطاق +Plugin المرشّح ولا يزال الإعداد يحتاج إلى hooks أغنى خاصة بوقت الإعداد ضمن +وقت التشغيل، فاضبط `requiresRuntime: true` وأبقِ `setup-api` في مكانه كمسار تنفيذ احتياطي. -ولأن بحث الإعداد يمكن أن ينفّذ كود `setup-api` يملكه Plugin، -فيجب أن تبقى القيم المطَبَّعة في `setup.providers[].id` و`setup.cliBackends[]` -فريدة عبر Plugins المكتشفة. وتفشل الملكية الملتبسة بشكل مغلق بدلًا من -اختيار فائز بحسب ترتيب الاكتشاف. +نظرًا إلى أن بحث الإعداد يمكنه تنفيذ كود `setup-api` المملوك للـ Plugin، +فيجب أن تبقى القيم المطَبَّعة لكل من `setup.providers[].id` و +`setup.cliBackends[]` فريدة عبر Plugins المكتشفة. تُغلَق الملكية الملتبسة +احترازيًا بدلًا من اختيار فائز وفق ترتيب الاكتشاف. ### مرجع `setup.providers` -| الحقل | مطلوب | النوع | المعنى | -| ------------- | ------ | ---------- | --------------------------------------------------------------------------------------- | -| `id` | نعم | `string` | معرّف Provider المُعرَض أثناء الإعداد أو التهيئة الأولية. حافظ على فرادة المعرّفات المطَبَّعة عالميًا. | -| `authMethods` | لا | `string[]` | معرّفات أساليب الإعداد/المصادقة التي يدعمها هذا Provider من دون تحميل وقت التشغيل الكامل. | +| الحقل | مطلوب | النوع | ما الذي يعنيه | +| ------------- | ------ | ---------- | ----------------------------------------------------------------------------------- | +| `id` | نعم | `string` | معرّف Provider الذي يُعرَض أثناء الإعداد أو onboarding. احرص على أن تبقى المعرّفات المطَبَّعة فريدة عالميًا. | +| `authMethods` | لا | `string[]` | معرّفات طرق الإعداد/auth التي يدعمها هذا الـ Provider من دون تحميل وقت التشغيل الكامل. | | `envVars` | لا | `string[]` | متغيرات البيئة التي يمكن لأسطح الإعداد/الحالة العامة التحقق منها قبل تحميل وقت تشغيل Plugin. | ### حقول `setup` -| الحقل | مطلوب | النوع | المعنى | -| ------------------ | ------ | ---------- | ------------------------------------------------------------------------------------------------- | -| `providers` | لا | `object[]` | واصفات إعداد Provider المعروضة أثناء الإعداد والتهيئة الأولية. | -| `cliBackends` | لا | `string[]` | معرّفات الواجهات الخلفية وقت الإعداد المستخدمة للبحث القائم على الواصفات أولًا. حافظ على فرادة المعرّفات المطَبَّعة عالميًا. | -| `configMigrations` | لا | `string[]` | معرّفات ترحيل الإعدادات التي يملكها سطح الإعداد لهذا Plugin. | -| `requiresRuntime` | لا | `boolean` | ما إذا كان الإعداد لا يزال يحتاج إلى تنفيذ `setup-api` بعد البحث القائم على الواصفات. | +| الحقل | مطلوب | النوع | ما الذي يعنيه | +| ------------------ | ------ | ---------- | -------------------------------------------------------------------------------------------------- | +| `providers` | لا | `object[]` | واصفات إعداد providers التي تُعرَض أثناء الإعداد وonboarding. | +| `cliBackends` | لا | `string[]` | معرّفات backends في وقت الإعداد والمستخدمة للبحث المعتمد على الواصفات أولًا. احرص على أن تبقى المعرّفات المطَبَّعة فريدة عالميًا. | +| `configMigrations` | لا | `string[]` | معرّفات ترحيل الإعدادات المملوكة لسطح الإعداد الخاص بهذا Plugin. | +| `requiresRuntime` | لا | `boolean` | ما إذا كان الإعداد لا يزال يحتاج إلى تنفيذ `setup-api` بعد البحث المعتمد على الواصفات. | ## مرجع `uiHints` -`uiHints` هو خريطة من أسماء حقول الإعدادات إلى تلميحات عرض صغيرة. +`uiHints` عبارة عن خريطة من أسماء حقول الإعدادات إلى تلميحات عرض صغيرة. ```json { @@ -330,20 +356,20 @@ Plugin المرشح وكان الإعداد لا يزال يحتاج إلى Hook } ``` -يمكن أن يتضمن كل تلميح حقل ما يلي: +يمكن أن يتضمن تلميح كل حقل ما يلي: -| الحقل | النوع | المعنى | -| ------------ | ---------- | -------------------------------------- | -| `label` | `string` | تسمية الحقل الموجهة للمستخدم. | -| `help` | `string` | نص مساعد قصير. | -| `tags` | `string[]` | وسوم واجهة مستخدم اختيارية. | -| `advanced` | `boolean` | يحدد الحقل على أنه متقدم. | -| `sensitive` | `boolean` | يحدد الحقل على أنه سري أو حساس. | -| `placeholder`| `string` | نص العنصر النائب لحقول النماذج. | +| الحقل | النوع | ما الذي يعنيه | +| ------------- | ---------- | ------------------------------------- | +| `label` | `string` | تسمية الحقل الموجّهة للمستخدم. | +| `help` | `string` | نص مساعد قصير. | +| `tags` | `string[]` | وسوم واجهة مستخدم اختيارية. | +| `advanced` | `boolean` | يحدّد الحقل على أنه متقدم. | +| `sensitive` | `boolean` | يحدّد الحقل على أنه سرّي أو حسّاس. | +| `placeholder` | `string` | نص العنصر النائب لمدخلات النماذج. | ## مرجع `contracts` -استخدم `contracts` فقط لبيانات تعريف ملكية القدرات الثابتة التي يمكن لـ OpenClaw +استخدم `contracts` فقط لبيانات وصفية ثابتة لملكية القدرات يمكن لـ OpenClaw قراءتها من دون استيراد وقت تشغيل Plugin. ```json @@ -364,22 +390,22 @@ Plugin المرشح وكان الإعداد لا يزال يحتاج إلى Hook كل قائمة اختيارية: -| الحقل | النوع | المعنى | -| -------------------------------- | ---------- | ---------------------------------------------------------- | -| `speechProviders` | `string[]` | معرّفات موفري Speech التي يملكها هذا Plugin. | -| `realtimeTranscriptionProviders` | `string[]` | معرّفات موفري realtime-transcription التي يملكها هذا Plugin. | -| `realtimeVoiceProviders` | `string[]` | معرّفات موفري realtime-voice التي يملكها هذا Plugin. | -| `mediaUnderstandingProviders` | `string[]` | معرّفات موفري media-understanding التي يملكها هذا Plugin. | -| `imageGenerationProviders` | `string[]` | معرّفات موفري image-generation التي يملكها هذا Plugin. | -| `videoGenerationProviders` | `string[]` | معرّفات موفري video-generation التي يملكها هذا Plugin. | -| `webFetchProviders` | `string[]` | معرّفات موفري web-fetch التي يملكها هذا Plugin. | -| `webSearchProviders` | `string[]` | معرّفات موفري web-search التي يملكها هذا Plugin. | -| `tools` | `string[]` | أسماء أدوات الوكيل التي يملكها هذا Plugin لفحوصات العقود المجمّعة. | +| الحقل | النوع | ما الذي يعنيه | +| ------------------------------- | ---------- | --------------------------------------------------------------- | +| `speechProviders` | `string[]` | معرّفات providers الخاصة بـ speech التي يملكها هذا Plugin. | +| `realtimeTranscriptionProviders`| `string[]` | معرّفات providers الخاصة بـ realtime-transcription التي يملكها هذا Plugin. | +| `realtimeVoiceProviders` | `string[]` | معرّفات providers الخاصة بـ realtime-voice التي يملكها هذا Plugin. | +| `mediaUnderstandingProviders` | `string[]` | معرّفات providers الخاصة بـ media-understanding التي يملكها هذا Plugin. | +| `imageGenerationProviders` | `string[]` | معرّفات providers الخاصة بـ image-generation التي يملكها هذا Plugin. | +| `videoGenerationProviders` | `string[]` | معرّفات providers الخاصة بـ video-generation التي يملكها هذا Plugin. | +| `webFetchProviders` | `string[]` | معرّفات providers الخاصة بـ web-fetch التي يملكها هذا Plugin. | +| `webSearchProviders` | `string[]` | معرّفات providers الخاصة بـ web-search التي يملكها هذا Plugin. | +| `tools` | `string[]` | أسماء أدوات agent التي يملكها هذا Plugin لفحوصات العقود المضمّنة. | ## مرجع `channelConfigs` -استخدم `channelConfigs` عندما يحتاج Plugin قناة إلى بيانات تعريف إعدادات منخفضة الكلفة قبل -تحميل وقت التشغيل. +استخدم `channelConfigs` عندما يحتاج Plugin قناة إلى بيانات وصفية منخفضة الكلفة +للإعدادات قبل تحميل وقت التشغيل. ```json { @@ -408,18 +434,18 @@ Plugin المرشح وكان الإعداد لا يزال يحتاج إلى Hook يمكن أن يتضمن كل إدخال قناة ما يلي: -| الحقل | النوع | المعنى | -| ------------ | ------------------------ | --------------------------------------------------------------------------------------- | -| `schema` | `object` | JSON Schema لـ `channels.`. مطلوب لكل إدخال إعدادات قناة مُعلن عنه. | -| `uiHints` | `Record` | تسميات واجهة مستخدم/عناصر نائبة/تلميحات حساسية اختيارية لقسم إعدادات تلك القناة. | -| `label` | `string` | تسمية القناة المدمجة في أسطح الاختيار والفحص عندما لا تكون بيانات تعريف وقت التشغيل جاهزة. | -| `description`| `string` | وصف قصير للقناة لأسطح الفحص والكتالوج. | -| `preferOver` | `string[]` | معرّفات Plugin قديمة أو أقل أولوية ينبغي أن تتفوق عليها هذه القناة في أسطح الاختيار. | +| الحقل | النوع | ما الذي يعنيه | +| ------------- | ------------------------ | --------------------------------------------------------------------------------------------- | +| `schema` | `object` | مخطط JSON لـ `channels.`. مطلوب لكل إدخال مُعلَن لإعدادات القناة. | +| `uiHints` | `Record` | تسميات واجهة مستخدم/عناصر نائبة/تلميحات حساسية اختيارية لذلك القسم من إعدادات القناة. | +| `label` | `string` | تسمية القناة المدمجة في أسطح المنتقي والفحص عندما لا تكون بيانات وقت التشغيل الوصفية جاهزة. | +| `description` | `string` | وصف قصير للقناة لأسطح الفحص والفهرس. | +| `preferOver` | `string[]` | معرّفات Plugins قديمة أو أقل أولوية ينبغي أن تتفوّق عليها هذه القناة في أسطح الاختيار. | ## مرجع `modelSupport` -استخدم `modelSupport` عندما ينبغي لـ OpenClaw أن يستنتج Plugin Provider الخاص بك من -معرّفات نماذج مختصرة مثل `gpt-5.4` أو `claude-sonnet-4.6` قبل أن يُحمَّل وقت تشغيل Plugin. +استخدم `modelSupport` عندما ينبغي لـ OpenClaw استنتاج Plugin الـ provider الخاص بك +من معرّفات نماذج مختصرة مثل `gpt-5.4` أو `claude-sonnet-4.6` قبل تحميل وقت تشغيل Plugin. ```json { @@ -430,75 +456,73 @@ Plugin المرشح وكان الإعداد لا يزال يحتاج إلى Hook } ``` -يطبّق OpenClaw أسبقية الترتيب التالية: +يطبّق OpenClaw ترتيب الأولوية التالي: -- تستخدم مراجع `provider/model` الصريحة بيانات تعريف manifest المملوكة في `providers` -- تتفوق `modelPatterns` على `modelPrefixes` -- إذا طابق Plugin غير مجمّع وPlugin مجمّع معًا، فإن - Plugin غير المجمّع يفوز -- يتم تجاهل أي غموض متبقٍ حتى يحدد المستخدم أو الإعدادات Provider +- تستخدم مراجع `provider/model` الصريحة بيانات manifest الخاصة بالملكية في `providers` +- تتفوّق `modelPatterns` على `modelPrefixes` +- إذا طابق كل من Plugin غير مضمّن وPlugin مضمّن، يفوز الـ Plugin غير المضمّن +- يُتجاهل أي غموض متبقٍّ إلى أن يحدّد المستخدم أو الإعدادات provider الحقول: -| الحقل | النوع | المعنى | -| -------------- | ---------- | ----------------------------------------------------------------------------- | -| `modelPrefixes`| `string[]` | بادئات تتم مطابقتها باستخدام `startsWith` مع معرّفات النماذج المختصرة. | -| `modelPatterns`| `string[]` | مصادر Regex تتم مطابقتها مع معرّفات النماذج المختصرة بعد إزالة لاحقة profile. | +| الحقل | النوع | ما الذي يعنيه | +| -------------- | ---------- | -------------------------------------------------------------------------------- | +| `modelPrefixes`| `string[]` | بادئات تُطابَق باستخدام `startsWith` مع معرّفات النماذج المختصرة. | +| `modelPatterns`| `string[]` | مصادر Regex تُطابَق مع معرّفات النماذج المختصرة بعد إزالة لاحقة profile. | -مفاتيح القدرات القديمة ذات المستوى الأعلى أصبحت مهجورة. استخدم `openclaw doctor --fix` -لنقل `speechProviders` و`realtimeTranscriptionProviders`، -و`realtimeVoiceProviders` و`mediaUnderstandingProviders`، -و`imageGenerationProviders` و`videoGenerationProviders`، -و`webFetchProviders` و`webSearchProviders` إلى `contracts`؛ ولم يعد -تحميل manifest العادي يعامل تلك الحقول ذات المستوى الأعلى على أنها -ملكية للقدرات. +مفاتيح القدرات القديمة ذات المستوى الأعلى مهجورة. استخدم `openclaw doctor --fix` +لنقل `speechProviders` و`realtimeTranscriptionProviders` و +`realtimeVoiceProviders` و`mediaUnderstandingProviders` و +`imageGenerationProviders` و`videoGenerationProviders` و +`webFetchProviders` و`webSearchProviders` إلى `contracts`؛ لم يعد تحميل +manifest العادي يتعامل مع تلك الحقول ذات المستوى الأعلى على أنها ملكية للقدرات. -## الـ Manifest مقابل `package.json` +## manifest مقابل package.json يخدم الملفان وظيفتين مختلفتين: -| الملف | استخدمه من أجل | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | الاكتشاف، والتحقق من صحة الإعدادات، وبيانات تعريف خيارات المصادقة، وتلميحات واجهة المستخدم التي يجب أن توجد قبل تشغيل كود Plugin | -| `package.json` | بيانات تعريف npm، وتثبيت التبعيات، وكتلة `openclaw` المستخدمة لنقاط الدخول، وبوابات التثبيت، والإعداد، أو بيانات تعريف الكتالوج | +| الملف | استخدمه من أجل | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | الاكتشاف، والتحقق من صحة الإعدادات، وبيانات auth-choice الوصفية، وتلميحات واجهة المستخدم التي يجب أن تكون موجودة قبل تشغيل كود Plugin | +| `package.json` | بيانات npm الوصفية، وتثبيت الاعتماديات، وكتلة `openclaw` المستخدمة لنقاط الدخول، أو بوابات التثبيت، أو الإعداد، أو بيانات الفهرس الوصفية | -إذا لم تكن متأكدًا من موضع قطعة بيانات تعريف معينة، فاستخدم هذه القاعدة: +إذا لم تكن متأكدًا من الموضع الذي تنتمي إليه معلومة وصفية ما، فاستخدم هذه القاعدة: -- إذا كان يجب على OpenClaw معرفتها قبل تحميل كود Plugin، فضعها في `openclaw.plugin.json` -- إذا كانت تتعلق بالتغليف أو ملفات الدخول أو سلوك تثبيت npm، فضعها في `package.json` +- إذا كان يجب على OpenClaw معرفتها قبل تحميل كود Plugin، فضَعها في `openclaw.plugin.json` +- إذا كانت تتعلق بالتغليف، أو ملفات الدخول، أو سلوك تثبيت npm، فضَعها في `package.json` ### حقول `package.json` التي تؤثر في الاكتشاف -توجد بعض بيانات تعريف Plugin السابقة لوقت التشغيل عمدًا داخل `package.json` تحت +توجد بعض بيانات Plugin الوصفية السابقة لوقت التشغيل عمدًا داخل `package.json` تحت كتلة `openclaw` بدلًا من `openclaw.plugin.json`. أمثلة مهمة: -| الحقل | المعنى | -| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | يصرّح بنقاط دخول Plugin الأصلية. | -| `openclaw.setupEntry` | نقطة دخول خفيفة مخصّصة للإعداد فقط تُستخدم أثناء التهيئة الأولية وبدء تشغيل القنوات المؤجل. | -| `openclaw.channel` | بيانات تعريف خفيفة لكتالوج القنوات مثل التسميات، ومسارات المستندات، والأسماء البديلة، ونصوص الاختيار. | -| `openclaw.channel.configuredState` | بيانات تعريف خفيفة لفاحص حالة التهيئة يمكنها الإجابة عن سؤال "هل يوجد إعداد قائم على البيئة فقط بالفعل؟" من دون تحميل وقت تشغيل القناة الكامل. | -| `openclaw.channel.persistedAuthState` | بيانات تعريف خفيفة لفاحص المصادقة المحفوظة يمكنها الإجابة عن سؤال "هل توجد أي عملية تسجيل دخول بالفعل؟" من دون تحميل وقت تشغيل القناة الكامل. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | تلميحات التثبيت/التحديث الخاصة بالـ Plugins المجمّعة والمنشورة خارجيًا. | -| `openclaw.install.defaultChoice` | مسار التثبيت المفضل عند توفر عدة مصادر للتثبيت. | -| `openclaw.install.minHostVersion` | الحد الأدنى لإصدار مضيف OpenClaw المدعوم، باستخدام حد semver أدنى مثل `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | يسمح بمسار استرداد ضيق لإعادة تثبيت Plugin مجمّع عندما تكون الإعدادات غير صالحة. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`| يتيح تحميل أسطح القنوات الخاصة بالإعداد فقط قبل تحميل Plugin القناة الكامل أثناء بدء التشغيل. | +| الحقل | ما الذي يعنيه | +| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | يصرّح بنقاط دخول Plugin الأصلية. | +| `openclaw.setupEntry` | نقطة دخول خفيفة مخصّصة للإعداد فقط وتُستخدم أثناء onboarding وبدء تشغيل القناة المؤجل. | +| `openclaw.channel` | بيانات وصفية منخفضة الكلفة لفهرس القنوات مثل التسميات، ومسارات الوثائق، وaliases، ونصوص الاختيار. | +| `openclaw.channel.configuredState` | بيانات وصفية خفيفة لوحدة فحص الحالة المُعدّة يمكنها الإجابة عن سؤال "هل يوجد إعداد يعتمد على البيئة فقط بالفعل؟" من دون تحميل وقت تشغيل القناة الكامل. | +| `openclaw.channel.persistedAuthState` | بيانات وصفية خفيفة لوحدة فحص auth المحفوظة يمكنها الإجابة عن سؤال "هل تم تسجيل الدخول إلى أي شيء بالفعل؟" من دون تحميل وقت تشغيل القناة الكامل. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | تلميحات التثبيت/التحديث للـ Plugins المضمّنة والمنشورة خارجيًا. | +| `openclaw.install.defaultChoice` | مسار التثبيت المفضّل عند توفر عدة مصادر تثبيت. | +| `openclaw.install.minHostVersion` | الحد الأدنى المدعوم من إصدار مضيف OpenClaw، باستخدام حد أدنى semver مثل `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | يسمح بمسار تعافٍ ضيق لإعادة تثبيت Plugin مضمّن عندما تكون الإعدادات غير صالحة. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | يسمح بتحميل أسطح القنوات المخصّصة للإعداد فقط قبل Plugin القناة الكامل أثناء بدء التشغيل. | -يتم فرض `openclaw.install.minHostVersion` أثناء التثبيت -وأثناء تحميل سجل manifest. تُرفض القيم غير الصالحة؛ أما القيم الصحيحة -ولكن الأحدث فتتسبب في تخطي Plugin على المضيفات الأقدم. +يُفرَض `openclaw.install.minHostVersion` أثناء التثبيت وتحميل سجل manifest. +تُرفَض القيم غير الصالحة؛ أما القيم الأحدث ولكن الصالحة فتتخطى Plugin +على المضيفات الأقدم. -إن `openclaw.install.allowInvalidConfigRecovery` ضيق النطاق عمدًا. فهو -لا يجعل الإعدادات المعطوبة التعسفية قابلة للتثبيت. اليوم، هو يسمح فقط -لمسارات التثبيت بالتعافي من إخفاقات ترقية معينة قديمة تخص Plugins المجمّعة، مثل -مسار Plugin مجمّع مفقود أو إدخال `channels.` قديم لذلك Plugin المجمّع نفسه. -أما أخطاء الإعدادات غير ذات الصلة فما تزال تمنع التثبيت وتوجّه المشغلين -إلى `openclaw doctor --fix`. +إن `openclaw.install.allowInvalidConfigRecovery` ضيق النطاق عمدًا. فهو لا +يجعل الإعدادات المعطوبة بشكل عشوائي قابلة للتثبيت. في الوقت الحالي، يسمح فقط +لتدفقات التثبيت بالتعافي من حالات فشل ترقية محددة وقديمة لPlugin مضمّن، +مثل غياب مسار Plugin مضمّن أو وجود إدخال `channels.` قديم لذلك Plugin +المضمّن نفسه. أما أخطاء الإعدادات غير المرتبطة فلا تزال تمنع التثبيت وتوجّه +المشغّلين إلى `openclaw doctor --fix`. -يمثل `openclaw.channel.persistedAuthState` بيانات تعريف حزمة لوحدة فحص صغيرة: +إن `openclaw.channel.persistedAuthState` هي بيانات وصفية للحزمة لوحدة فحص صغيرة: ```json { @@ -514,13 +538,12 @@ Plugin المرشح وكان الإعداد لا يزال يحتاج إلى Hook } ``` -استخدمه عندما تحتاج مسارات الإعداد أو doctor أو الحالة المهيأة إلى -فحص مصادقة بسيط بنعم/لا قبل تحميل Plugin القناة الكامل. ينبغي أن يكون -التصدير الهدف دالة صغيرة تقرأ الحالة المحفوظة فقط؛ ولا توجّهها -عبر شريط وقت تشغيل القناة الكامل. +استخدمها عندما تحتاج تدفقات الإعداد أو doctor أو الحالة المُعدّة إلى فحص auth +خفيف بنعم/لا قبل تحميل Plugin القناة الكامل. يجب أن يكون التصدير الهدف +دالة صغيرة تقرأ الحالة المحفوظة فقط؛ لا تمرّرها عبر barrel الخاص بوقت تشغيل القناة الكامل. -يتبع `openclaw.channel.configuredState` الشكل نفسه من أجل فحوصات التهيئة -البسيطة المعتمدة على البيئة فقط: +يتبع `openclaw.channel.configuredState` الشكل نفسه لعمليات الفحص الخفيفة +للحالة المُعدّة المعتمدة على البيئة فقط: ```json { @@ -536,65 +559,68 @@ Plugin المرشح وكان الإعداد لا يزال يحتاج إلى Hook } ``` -استخدمه عندما تتمكن قناة من تحديد حالة التهيئة من البيئة أو من مدخلات صغيرة -أخرى غير تشغيلية. وإذا كان الفحص يحتاج إلى حل كامل للإعدادات أو إلى -وقت تشغيل القناة الحقيقي، فأبقِ هذا المنطق داخل Hook -`config.hasConfiguredState` في Plugin بدلًا من ذلك. +استخدمه عندما تستطيع قناة ما الإجابة عن الحالة المُعدّة اعتمادًا على البيئة +أو مدخلات صغيرة أخرى غير مرتبطة بوقت التشغيل. إذا كان الفحص يحتاج إلى الحل +الكامل للإعدادات أو إلى وقت تشغيل القناة الحقيقي، فأبقِ هذا المنطق في hook +`config.hasConfiguredState` الخاص بالـ Plugin بدلًا من ذلك. -## متطلبات JSON Schema +## متطلبات مخطط JSON -- **يجب على كل Plugin أن يوفّر JSON Schema**، حتى لو كان لا يقبل أي إعدادات. -- يُعد المخطط الفارغ مقبولًا (على سبيل المثال، `{ "type": "object", "additionalProperties": false }`). -- يتم التحقق من المخططات وقت قراءة/كتابة الإعدادات، وليس في وقت التشغيل. +- **يجب على كل Plugin أن يضمّ مخطط JSON**، حتى إذا كان لا يقبل أي إعدادات. +- يُقبل مخطط فارغ (على سبيل المثال، `{ "type": "object", "additionalProperties": false }`). +- تُتحقَّق المخططات عند قراءة/كتابة الإعدادات، وليس في وقت التشغيل. -## سلوك التحقق +## سلوك التحقق من الصحة -- تُعد مفاتيح `channels.*` غير المعروفة **أخطاء**، ما لم يكن معرّف القناة معلنًا بواسطة - manifest خاص بـ Plugin. +- مفاتيح `channels.*` غير المعروفة هي **أخطاء**، ما لم يكن معرّف القناة + مُعلَنًا بواسطة manifest تابع لـ Plugin. - يجب أن تشير `plugins.entries.` و`plugins.allow` و`plugins.deny` و`plugins.slots.*` - إلى معرّفات Plugin **قابلة للاكتشاف**. وتُعد المعرّفات غير المعروفة **أخطاء**. -- إذا كان Plugin مثبتًا لكن manifest أو schema الخاص به معطوبًا أو مفقودًا، - يفشل التحقق ويبلّغ Doctor عن خطأ Plugin. -- إذا كانت إعدادات Plugin موجودة لكن Plugin **معطّل**، يتم الاحتفاظ بالإعدادات - وتظهر **تحذير** في Doctor + السجلات. + إلى معرّفات Plugins **قابلة للاكتشاف**. والمعرّفات غير المعروفة هي **أخطاء**. +- إذا كان Plugin مثبّتًا لكن لديه manifest أو schema معطوب أو مفقود، + يفشل التحقق من الصحة ويبلّغ Doctor عن خطأ Plugin. +- إذا كانت إعدادات Plugin موجودة لكن Plugin **معطّل**، فستُحفَظ الإعدادات + ويظهر **تحذير** في Doctor + السجلات. -راجع [مرجع الإعدادات](/ar/gateway/configuration) للاطلاع على مخطط `plugins.*` الكامل. +راجع [Configuration reference](/ar/gateway/configuration) للاطلاع على مخطط `plugins.*` الكامل. ## ملاحظات -- إن الـ manifest **مطلوب للـ Plugins الأصلية في OpenClaw**، بما في ذلك التحميلات المحلية من نظام الملفات. -- ما يزال وقت التشغيل يحمّل وحدة Plugin بشكل منفصل؛ والـ manifest مخصّص فقط - للاكتشاف + التحقق. -- يتم تحليل ملفات manifest الأصلية باستخدام JSON5، لذا تُقبل التعليقات والفواصل اللاحقة - والمفاتيح غير المحاطة بعلامات اقتباس ما دامت القيمة النهائية لا تزال كائنًا. -- لا يقرأ محمّل manifest سوى حقول manifest الموثقة. تجنّب إضافة +- ملف manifest **مطلوب للـ Plugins الأصلية في OpenClaw**، بما في ذلك التحميلات المحلية من نظام الملفات. +- لا يزال وقت التشغيل يحمّل وحدة Plugin بشكل منفصل؛ manifest مخصّص فقط + للاكتشاف + التحقق من الصحة. +- تُحلَّل ملفات manifest الأصلية باستخدام JSON5، لذا تُقبل التعليقات، + والفواصل اللاحقة، والمفاتيح غير الموضوعة بين علامات اقتباس ما دامت + القيمة النهائية لا تزال كائنًا. +- لا يقرأ مُحمِّل manifest إلا حقول manifest الموثقة. تجنّب إضافة مفاتيح مخصّصة ذات مستوى أعلى هنا. -- يمثل `providerAuthEnvVars` مسار البيانات الوصفية منخفض الكلفة لفحوصات المصادقة، والتحقق من - علامات البيئة، والأسطح المماثلة لمصادقة Provider التي ينبغي ألا تشغّل وقت تشغيل Plugin - لمجرد فحص أسماء متغيرات البيئة. -- يتيح `providerAuthAliases` لمتغيرات Provider إعادة استخدام متغيرات بيئة المصادقة الخاصة بـ Provider آخر، - وملفات تعريف المصادقة، والمصادقة المعتمدة على الإعدادات، وخيار التهيئة الأولية بمفتاح API - من دون ترميز هذه العلاقة بشكل صريح داخل النواة. -- يمثل `channelEnvVars` مسار البيانات الوصفية منخفض الكلفة للرجوع إلى shell-env، وموجّهات الإعداد، - والأسطح المماثلة الخاصة بالقنوات التي ينبغي ألا تشغّل وقت تشغيل Plugin - لمجرد فحص أسماء متغيرات البيئة. -- يمثل `providerAuthChoices` مسار البيانات الوصفية منخفض الكلفة لمحددات خيارات المصادقة، - وحل `--auth-choice`، وربط Provider المفضل، وتسجيل أعلام CLI البسيطة الخاصة بالتهيئة الأولية - قبل تحميل وقت تشغيل Provider. أما بيانات تعريف المعالج التفاعلي في وقت التشغيل - التي تتطلب كود Provider، فراجع - [Provider runtime hooks](/ar/plugins/architecture#provider-runtime-hooks). -- يتم اختيار أنواع Plugin الحصرية عبر `plugins.slots.*`. +- `providerAuthEnvVars` هو مسار البيانات الوصفية منخفضة الكلفة لفحوصات auth، + والتحقق من env-marker، والأسطح المشابهة الخاصة بـ provider-auth التي + لا ينبغي أن تشغّل وقت تشغيل Plugin لمجرد فحص أسماء env. +- يتيح `providerAuthAliases` لمتغيرات provider إعادة استخدام متغيرات env + الخاصة بـ auth لProvider آخر، وملفات auth التعريفية الخاصة به، وauth + المدعوم بالإعدادات، وخيار onboarding الخاص بمفتاح API، من دون ترميز هذه + العلاقة بشكل ثابت في النواة. +- `channelEnvVars` هو مسار البيانات الوصفية منخفضة الكلفة لبدائل shell-env، + ورسائل الإعداد، والأسطح المشابهة الخاصة بالقنوات التي لا ينبغي أن تشغّل + وقت تشغيل Plugin لمجرد فحص أسماء env. +- `providerAuthChoices` هو مسار البيانات الوصفية منخفضة الكلفة لمنتقيات + auth-choice، وحل `--auth-choice`، وربط provider المفضّل، وتسجيل أعلام CLI + البسيطة الخاصة بالتهيئة الأولية قبل تحميل وقت تشغيل provider. أما بالنسبة + إلى بيانات wizard الوصفية الخاصة بوقت التشغيل التي تتطلب كود provider، + فراجع [Provider runtime hooks](/ar/plugins/architecture#provider-runtime-hooks). +- تُختار أنواع Plugins الحصرية عبر `plugins.slots.*`. - يتم اختيار `kind: "memory"` بواسطة `plugins.slots.memory`. - يتم اختيار `kind: "context-engine"` بواسطة `plugins.slots.contextEngine` - (الافتراضي: `legacy` المدمج). -- يمكن حذف `channels` و`providers` و`cliBackends` و`skills` عندما لا - يحتاجها Plugin. + (الافتراضي: `legacy` المضمّن). +- يمكن حذف `channels` و`providers` و`cliBackends` و`skills` عندما لا يحتاج + Plugin إليها. - إذا كان Plugin الخاص بك يعتمد على وحدات أصلية، فوثّق خطوات البناء وأي - متطلبات قائمة سماح لمدير الحزم (على سبيل المثال، `allow-build-scripts` في pnpm + متطلبات لقائمة السماح الخاصة بمدير الحزم (على سبيل المثال، `allow-build-scripts` + في pnpm - `pnpm rebuild `). ## ذو صلة -- [بناء Plugins](/ar/plugins/building-plugins) — بدء العمل مع Plugins -- [بنية Plugin](/ar/plugins/architecture) — البنية الداخلية -- [نظرة عامة على SDK](/ar/plugins/sdk-overview) — مرجع Plugin SDK +- [Building Plugins](/ar/plugins/building-plugins) — البدء باستخدام Plugins +- [Plugin Architecture](/ar/plugins/architecture) — البنية الداخلية +- [SDK Overview](/ar/plugins/sdk-overview) — مرجع Plugin SDK diff --git a/docs/ar/plugins/sdk-channel-plugins.md b/docs/ar/plugins/sdk-channel-plugins.md index 2b72d9464..ce051f3dd 100644 --- a/docs/ar/plugins/sdk-channel-plugins.md +++ b/docs/ar/plugins/sdk-channel-plugins.md @@ -1,102 +1,113 @@ --- read_when: - - أنت تبني plugin جديدًا لقناة مراسلة + - أنت تبني Plugin جديدًا لقناة مراسلة - تريد ربط OpenClaw بمنصة مراسلة - - تحتاج إلى فهم واجهة المهايئ ChannelPlugin + - تحتاج إلى فهم واجهة المهايئ `ChannelPlugin` sidebarTitle: Channel Plugins -summary: دليل خطوة بخطوة لبناء plugin لقناة مراسلة لـ OpenClaw -title: بناء plugins القنوات +summary: دليل خطوة بخطوة لبناء Plugin لقناة مراسلة لـ OpenClaw +title: بناء Plugins القنوات x-i18n: - generated_at: "2026-04-11T02:46:30Z" + generated_at: "2026-04-15T07:17:51Z" model: gpt-5.4 provider: openai - source_hash: 8a026e924f9ae8a3ddd46287674443bcfccb0247be504261522b078e1f440aef + source_hash: a7f4c746fe3163a8880e14c433f4db4a1475535d91716a53fb879551d8d62f65 source_path: plugins/sdk-channel-plugins.md workflow: 15 --- -# بناء plugins القنوات +# بناء Plugins القنوات -يرشدك هذا الدليل خلال بناء plugin قناة يربط OpenClaw بمنصة -مراسلة. وبنهاية هذا الدليل، سيكون لديك قناة عاملة مع أمان DM، -والاقتران، وتسلسل الردود، والمراسلة الصادرة. +يشرح هذا الدليل كيفية بناء Plugin قناة يربط OpenClaw بمنصة +مراسلة. وبنهاية هذا الدليل سيكون لديك قناة عاملة تتضمن أمان الرسائل +المباشرة، والاقتران، وتوجيه الردود ضمن السلاسل، والرسائل الصادرة. - إذا لم تكن قد بنيت أي plugin لـ OpenClaw من قبل، فاقرأ - [البدء](/ar/plugins/building-plugins) أولًا للتعرّف على البنية الأساسية - للحزمة وإعداد manifest. + إذا لم تكن قد أنشأت أي Plugin لـ OpenClaw من قبل، فاقرأ + [البدء](/ar/plugins/building-plugins) أولًا لمعرفة بنية الحزمة + الأساسية وإعداد ملف البيان. -## كيف تعمل plugins القنوات +## كيف تعمل Plugins القنوات -لا تحتاج plugins القنوات إلى أدوات send/edit/react خاصة بها. يحتفظ OpenClaw -بأداة `message` مشتركة واحدة في core. ويتولى plugin الخاص بك: +لا تحتاج Plugins القنوات إلى أدوات send/edit/react خاصة بها. يحتفظ OpenClaw +بأداة `message` واحدة مشتركة في النواة. ويتولى Plugin الخاص بك ما يلي: -- **الإعدادات** — تحليل الحسابات ومعالج الإعداد -- **الأمان** — سياسة DM وقوائم السماح -- **الاقتران** — تدفق الموافقة على DM -- **بنية الجلسة** — كيفية ربط معرّفات المحادثات الخاصة بالمزوّد بالدردشات الأساسية ومعرّفات السلاسل والرجوع إلى الأصل -- **الصادر** — إرسال النصوص والوسائط واستطلاعات الرأي إلى المنصة +- **الإعداد** — حلّ الحسابات ومعالج الإعداد +- **الأمان** — سياسة الرسائل المباشرة وقوائم السماح +- **الاقتران** — تدفق الموافقة على الرسائل المباشرة +- **صياغة الجلسة** — كيفية ربط معرّفات المحادثات الخاصة بالموفّر بالمحادثات الأساسية ومعرّفات السلاسل وبدائل الأصل +- **الإرسال الصادر** — إرسال النصوص والوسائط والاستطلاعات إلى المنصة - **التسلسل** — كيفية ترتيب الردود ضمن السلاسل -يتولى core أداة الرسائل المشتركة، وربط الموجّهات، وبنية مفتاح الجلسة الخارجية، -ومسك الدفاتر العام لـ `:thread:`، والإرسال. +تتولى النواة أداة الرسائل المشتركة، وربط الـ prompt، والشكل الخارجي لمفتاح +الجلسة، وتتبع `:thread:` العام، والإرسال. -إذا كانت منصتك تخزّن نطاقًا إضافيًا داخل معرّفات المحادثات، فأبقِ هذا التحليل -داخل plugin باستخدام `messaging.resolveSessionConversation(...)`. فهذا هو -المدخل القياسي لربط `rawId` بمعرّف المحادثة الأساسي، ومعرّف السلسلة الاختياري، +إذا كانت قناتك تضيف معاملات إلى أداة الرسائل تحمل مصادر وسائط، فاكشف عن أسماء +هذه المعاملات عبر `describeMessageTool(...).mediaSourceParams`. تستخدم النواة +هذه القائمة الصريحة لتطبيع مسارات sandbox ولسياسة الوصول إلى الوسائط الصادرة، +لذلك لا تحتاج Plugins إلى حالات خاصة في النواة المشتركة لمعاملات الصور الرمزية +أو المرفقات أو صور الغلاف الخاصة بموفّر معيّن. +ويُفضّل إرجاع خريطة مفاتيحها مبنية على الإجراء مثل +`{ "set-profile": ["avatarUrl", "avatarPath"] }` حتى لا ترث الإجراءات غير +ذات الصلة معاملات الوسائط الخاصة بإجراء آخر. ولا يزال المصفوفة المسطحة تعمل مع +المعاملات التي يُقصد مشاركتها عمدًا عبر كل إجراء مكشوف. + +إذا كانت منصتك تخزّن نطاقًا إضافيًا داخل معرّفات المحادثة، فأبقِ هذا التحليل +داخل Plugin باستخدام `messaging.resolveSessionConversation(...)`. هذا هو +الخطاف المعتمد لربط `rawId` بمعرّف المحادثة الأساسي، ومعرّف السلسلة الاختياري، و`baseConversationId` الصريح، وأي `parentConversationCandidates`. -وعندما تعيد `parentConversationCandidates`، فأبقِ ترتيبها من -الأصل الأضيق إلى المحادثة الأساسية/الأوسع. +وعندما تُرجع `parentConversationCandidates`، فاحرص على إبقائها مرتبة من +الأصل الأضيق إلى الأصل الأوسع/المحادثة الأساسية. -يمكن أيضًا لـ plugins المضمّنة التي تحتاج إلى التحليل نفسه قبل تشغيل -سجل القنوات أن تعرض ملف `session-key-api.ts` من المستوى الأعلى مع -تصدير مطابق لـ `resolveSessionConversation(...)`. ويستخدم core هذا السطح -الآمن للتهيئة فقط عندما لا يكون سجل plugin في وقت التشغيل متاحًا بعد. +يمكن أيضًا لـ Plugins المضمّنة التي تحتاج إلى التحليل نفسه قبل تشغيل سجل +القنوات أن تكشف عن ملف `session-key-api.ts` على المستوى الأعلى مع +تصدير مطابق لـ `resolveSessionConversation(...)`. تستخدم النواة هذا السطح +الآمن أثناء الإقلاع فقط عندما لا يكون سجل Plugins وقت التشغيل متاحًا بعد. -لا يزال `messaging.resolveParentConversationCandidates(...)` متاحًا كحل -توافقي قديم عندما يحتاج plugin فقط إلى الرجوع إلى المحادثات الأصلية -فوق المعرّف العام/الخام. وإذا وُجد كلا المدخلين، يستخدم core -أولًا `resolveSessionConversation(...).parentConversationCandidates` ثم يعود -إلى `resolveParentConversationCandidates(...)` فقط عندما يهملهما المدخل القياسي. +لا يزال `messaging.resolveParentConversationCandidates(...)` متاحًا كبديل +توافقي قديم عندما يحتاج Plugin فقط إلى بدائل الأصل فوق المعرّف العام/الخام. +إذا وُجد الخطافان معًا، تستخدم النواة +`resolveSessionConversation(...).parentConversationCandidates` أولًا ولا +تعود إلى `resolveParentConversationCandidates(...)` إلا عندما يهمل الخطاف +المعتمد إرجاعها. -## الموافقات وإمكانات القنوات +## الموافقات وإمكانات القناة -لا تحتاج معظم plugins القنوات إلى شيفرة خاصة بالموافقات. +لا تحتاج معظم Plugins القنوات إلى كود خاص بالموافقات. -- يتولى core الأمر `/approve` داخل الدردشة نفسها، وحمولات أزرار الموافقة المشتركة، وآلية التسليم الاحتياطي العامة. -- فضّل كائن `approvalCapability` واحدًا على plugin القناة عندما تحتاج القناة إلى سلوك خاص بالموافقة. -- تمت إزالة `ChannelPlugin.approvals`. ضع حقائق تسليم/أصلي/عرض/مصادقة الموافقة ضمن `approvalCapability`. -- يقتصر `plugin.auth` على login/logout فقط؛ ولم يعد core يقرأ مداخل مصادقة الموافقات من هذا الكائن. -- يُعد `approvalCapability.authorizeActorAction` و`approvalCapability.getActionAvailabilityState` مدخل المصادقة القياسي للموافقات. -- استخدم `approvalCapability.getActionAvailabilityState` لتوفّر مصادقة الموافقة داخل الدردشة نفسها. -- إذا كانت قناتك تعرض موافقات exec أصلية، فاستخدم `approvalCapability.getExecInitiatingSurfaceState` لحالة السطح المبدئي/العميل الأصلي عندما تختلف عن مصادقة الموافقة داخل الدردشة نفسها. ويستخدم core هذا المدخل الخاص بـ exec للتمييز بين `enabled` و`disabled`، وتحديد ما إذا كانت القناة المبدئية تدعم موافقات exec الأصلية، وإدراج القناة في إرشادات العميل الأصلي الاحتياطية. ويملأ `createApproverRestrictedNativeApprovalCapability(...)` ذلك للحالة الشائعة. +- تتولى النواة `/approve` داخل المحادثة نفسها، وحمولات أزرار الموافقة المشتركة، وآلية التسليم العامة البديلة. +- يُفضَّل استخدام كائن `approvalCapability` واحد على Plugin القناة عندما تحتاج القناة إلى سلوك خاص بالموافقة. +- تمت إزالة `ChannelPlugin.approvals`. ضع حقائق تسليم/أصلية/عرض/مصادقة الموافقة على `approvalCapability`. +- يقتصر `plugin.auth` على login/logout فقط؛ لم تعد النواة تقرأ خطافات مصادقة الموافقة من هذا الكائن. +- يُعد `approvalCapability.authorizeActorAction` و`approvalCapability.getActionAvailabilityState` الواجهة المعتمدة لمصادقة الموافقات. +- استخدم `approvalCapability.getActionAvailabilityState` لإتاحة مصادقة الموافقة داخل المحادثة نفسها. +- إذا كانت قناتك تكشف عن موافقات تنفيذ أصلية، فاستخدم `approvalCapability.getExecInitiatingSurfaceState` لحالة سطح البدء/العميل الأصلي عندما تختلف عن مصادقة الموافقة داخل المحادثة نفسها. تستخدم النواة هذا الخطاف الخاص بالتنفيذ للتمييز بين `enabled` و`disabled`، وتحديد ما إذا كانت القناة الداعية تدعم موافقات التنفيذ الأصلية، وإدراج القناة في إرشادات الرجوع إلى العميل الأصلي. يقوم `createApproverRestrictedNativeApprovalCapability(...)` بملء ذلك في الحالة الشائعة. - استخدم `outbound.shouldSuppressLocalPayloadPrompt` أو `outbound.beforeDeliverPayload` لسلوك دورة حياة الحمولة الخاص بالقناة، مثل إخفاء مطالبات الموافقة المحلية المكررة أو إرسال مؤشرات الكتابة قبل التسليم. -- استخدم `approvalCapability.delivery` فقط لتوجيه الموافقة الأصلية أو منع التسليم الاحتياطي. -- استخدم `approvalCapability.nativeRuntime` للحقائق الأصلية للموافقة المملوكة للقناة. وأبقِه كسول التحميل في نقاط دخول القنوات الساخنة باستخدام `createLazyChannelApprovalNativeRuntimeAdapter(...)`، الذي يمكنه استيراد module وقت التشغيل الخاص بك عند الطلب مع السماح لـ core بتجميع دورة حياة الموافقة. -- استخدم `approvalCapability.render` فقط عندما تحتاج القناة فعلًا إلى حمولات موافقة مخصصة بدلًا من العارض المشترك. -- استخدم `approvalCapability.describeExecApprovalSetup` عندما تريد القناة أن يشرح رد مسار التعطيل مقابض الإعدادات الدقيقة اللازمة لتمكين موافقات exec الأصلية. ويتلقى هذا المدخل `{ channel, channelLabel, accountId }`؛ ويجب على القنوات ذات الحسابات المسماة أن تعرض مسارات ضمن نطاق الحساب مثل `channels..accounts..execApprovals.*` بدلًا من الإعدادات الافتراضية في المستوى الأعلى. -- إذا كانت القناة تستطيع استنتاج هويات DM مستقرة شبيهة بالمالك من الإعدادات الموجودة، فاستخدم `createResolvedApproverActionAuthAdapter` من `openclaw/plugin-sdk/approval-runtime` لتقييد `/approve` داخل الدردشة نفسها من دون إضافة منطق في core خاص بالموافقات. -- إذا كانت القناة تحتاج إلى تسليم موافقة أصلية، فأبقِ شيفرة القناة مركزة على تطبيع الهدف وحقائق النقل/العرض. واستخدم `createChannelExecApprovalProfile` و`createChannelNativeOriginTargetResolver` و`createChannelApproverDmTargetResolver` و`createApproverRestrictedNativeApprovalCapability` من `openclaw/plugin-sdk/approval-runtime`. وضع الحقائق الخاصة بالقناة خلف `approvalCapability.nativeRuntime`، ويفضَّل عبر `createChannelApprovalNativeRuntimeAdapter(...)` أو `createLazyChannelApprovalNativeRuntimeAdapter(...)`، حتى يتمكن core من تجميع المعالج وامتلاك تصفية الطلبات والتوجيه وإزالة التكرار وانتهاء الصلاحية واشتراك gateway وإشعارات "تم التوجيه إلى مكان آخر". وينقسم `nativeRuntime` إلى عدة مداخل أصغر: -- `availability` — ما إذا كان الحساب مكوّنًا وما إذا كان يجب التعامل مع الطلب -- `presentation` — ربط نموذج العرض المشترك للموافقة بحمولات أصلية معلّقة/محسومة/منتهية أو بإجراءات نهائية -- `transport` — إعداد الأهداف بالإضافة إلى إرسال/تحديث/حذف رسائل الموافقة الأصلية -- `interactions` — مداخل اختيارية لربط/فك/مسح الإجراءات للأزرار أو التفاعلات الأصلية -- `observe` — مداخل اختيارية لتشخيصات التسليم -- إذا كانت القناة تحتاج إلى كائنات مملوكة لوقت التشغيل مثل عميل أو رمز أو تطبيق Bolt أو مستقبِل webhook، فسجّلها عبر `openclaw/plugin-sdk/channel-runtime-context`. يتيح سجل runtime-context العام لـ core تهيئة المعالجات المعتمدة على الإمكانات من حالة بدء القناة من دون إضافة طبقة ربط خاصة بالموافقات. -- لا تلجأ إلى `createChannelApprovalHandler` أو `createChannelNativeApprovalRuntime` ذوي المستوى الأدنى إلا عندما لا يكون المدخل المعتمد على الإمكانات قادرًا على التعبير عما تحتاجه بعد. -- يجب على القنوات الأصلية للموافقات توجيه كلٍّ من `accountId` و`approvalKind` عبر هذه المساعدات. إذ يبقي `accountId` سياسة الموافقات متعددة الحسابات ضمن نطاق حساب البوت الصحيح، بينما يبقي `approvalKind` سلوك موافقة exec مقابل موافقة plugin متاحًا للقناة من دون تفرعات ثابتة في core. -- يتولى core الآن أيضًا إشعارات إعادة توجيه الموافقات. لذلك يجب ألا ترسل plugins القنوات رسائل متابعة خاصة بها من نوع "تم إرسال الموافقة إلى الرسائل الخاصة / قناة أخرى" من `createChannelNativeApprovalRuntime`؛ بل عرّض بدلًا من ذلك توجيهًا دقيقًا للأصل + DM الخاص بالموافِق عبر مساعدات إمكانات الموافقة المشتركة ودَع core يجمع عمليات التسليم الفعلية قبل نشر أي إشعار مرة أخرى إلى الدردشة التي بدأت الطلب. -- حافظ على نوع معرّف الموافقة المُسلَّم من البداية إلى النهاية. يجب ألا تقوم العملاء الأصلية - بتخمين أو إعادة كتابة توجيه موافقة exec مقابل موافقة plugin استنادًا إلى حالة محلية في القناة. -- يمكن عمدًا لأنواع الموافقات المختلفة أن تعرض أسطحًا أصلية مختلفة. - من الأمثلة المضمّنة الحالية: - - يحتفظ Slack بإتاحة توجيه الموافقات الأصلية لكل من معرّفات exec وplugin. - - يحتفظ Matrix بنفس توجيه DM/القناة الأصلي وتجربة التفاعل عبر reactions لموافقات exec - وplugin، مع الاستمرار في السماح باختلاف المصادقة حسب نوع الموافقة. -- لا يزال `createApproverRestrictedNativeApprovalAdapter` موجودًا كغلاف توافق، لكن الشيفرة الجديدة يجب أن تفضّل منشئ الإمكانات وتعرض `approvalCapability` على plugin. +- استخدم `approvalCapability.delivery` فقط لتوجيه الموافقات الأصلية أو منع التسليم الاحتياطي. +- استخدم `approvalCapability.nativeRuntime` للحقائق الأصلية الخاصة بالموافقة التي تملكها القناة. أبقه كسول التحميل في نقاط دخول القنوات الساخنة باستخدام `createLazyChannelApprovalNativeRuntimeAdapter(...)`، إذ يمكنه استيراد وحدة وقت التشغيل عند الطلب مع الاستمرار في تمكين النواة من تجميع دورة حياة الموافقة. +- استخدم `approvalCapability.render` فقط عندما تحتاج القناة فعلًا إلى حمولات موافقة مخصّصة بدلًا من العارض المشترك. +- استخدم `approvalCapability.describeExecApprovalSetup` عندما تريد القناة أن يشرح رد المسار المعطّل مفاتيح الإعداد الدقيقة اللازمة لتمكين موافقات التنفيذ الأصلية. يتلقى الخطاف `{ channel, channelLabel, accountId }`؛ ويجب على القنوات ذات الحسابات المسمّاة عرض مسارات بنطاق الحساب مثل `channels..accounts..execApprovals.*` بدلًا من الإعدادات الافتراضية على المستوى الأعلى. +- إذا كانت القناة تستطيع استنتاج هويات رسائل مباشرة مستقرة شبيهة بالمالك من الإعداد الحالي، فاستخدم `createResolvedApproverActionAuthAdapter` من `openclaw/plugin-sdk/approval-runtime` لتقييد `/approve` داخل المحادثة نفسها من دون إضافة منطق خاص بالموافقة إلى النواة. +- إذا كانت القناة تحتاج إلى تسليم موافقات أصلية، فأبقِ كود القناة مركّزًا على تطبيع الهدف وحقائق النقل/العرض. استخدم `createChannelExecApprovalProfile` و`createChannelNativeOriginTargetResolver` و`createChannelApproverDmTargetResolver` و`createApproverRestrictedNativeApprovalCapability` من `openclaw/plugin-sdk/approval-runtime`. ضع الحقائق الخاصة بالقناة خلف `approvalCapability.nativeRuntime`، ويفضّل أن يكون ذلك عبر `createChannelApprovalNativeRuntimeAdapter(...)` أو `createLazyChannelApprovalNativeRuntimeAdapter(...)`، حتى تتمكن النواة من تجميع المعالج وتولّي تصفية الطلبات والتوجيه وإزالة التكرار والانتهاء والاشتراك في Gateway وإشعارات التوجيه إلى مكان آخر. ينقسم `nativeRuntime` إلى عدد قليل من الواجهات الأصغر: +- `availability` — ما إذا كان الحساب مضبوطًا وما إذا كان ينبغي معالجة الطلب +- `presentation` — ربط نموذج عرض الموافقة المشترك بحمولات أصلية معلّقة/محلولة/منتهية أو بإجراءات نهائية +- `transport` — إعداد الأهداف ثم إرسال/تحديث/حذف رسائل الموافقة الأصلية +- `interactions` — خطافات اختيارية لربط/فصل/مسح الإجراءات للأزرار أو التفاعلات الأصلية +- `observe` — خطافات اختيارية لتشخيصات التسليم +- إذا كانت القناة تحتاج إلى كائنات يملكها وقت التشغيل مثل عميل أو رمز أو تطبيق Bolt أو مستقبل Webhook، فسجّلها عبر `openclaw/plugin-sdk/channel-runtime-context`. يتيح سجل سياق وقت التشغيل العام للنواة إقلاع المعالجات المبنية على الإمكانات انطلاقًا من حالة بدء القناة من دون إضافة طبقة ربط خاصة بالموافقة. +- لا تلجأ إلى `createChannelApprovalHandler` أو `createChannelNativeApprovalRuntime` منخفضَي المستوى إلا عندما لا تكون الواجهة المعتمدة على الإمكانات معبّرة بما يكفي بعد. +- يجب على قنوات الموافقة الأصلية تمرير كلٍّ من `accountId` و`approvalKind` عبر هذه المساعدات. يُبقي `accountId` سياسة الموافقة متعددة الحسابات ضمن نطاق حساب البوت الصحيح، ويُبقي `approvalKind` سلوك موافقة التنفيذ مقابل موافقة Plugin متاحًا للقناة من دون تفرعات مضمّنة في النواة. +- تتولى النواة الآن أيضًا إشعارات إعادة توجيه الموافقة. يجب ألا ترسل Plugins القنوات رسائل متابعة خاصة بها من نوع "تم إرسال الموافقة إلى الرسائل المباشرة / قناة أخرى" من `createChannelNativeApprovalRuntime`؛ بل اكشف بدلًا من ذلك عن توجيه دقيق للأصل + الرسائل المباشرة للموافق عبر مساعدات إمكانات الموافقة المشتركة، ودع النواة تجمع عمليات التسليم الفعلية قبل نشر أي إشعار مرة أخرى إلى محادثة البدء. +- حافظ على نوع معرّف الموافقة المُسلَّم من البداية إلى النهاية. يجب ألا + تخمّن العملاء الأصلية أو تعيد كتابة توجيه موافقة التنفيذ مقابل موافقة Plugin + اعتمادًا على حالة محلية خاصة بالقناة. +- يمكن لأنواع الموافقة المختلفة أن تكشف عمدًا عن أسطح أصلية مختلفة. + الأمثلة المضمّنة الحالية: + - يُبقي Slack توجيه الموافقات الأصلية متاحًا لكلٍّ من معرّفات موافقة التنفيذ وموافقة Plugin. + - يُبقي Matrix توجيه الرسائل المباشرة/القناة الأصلي نفسه وتجربة UX نفسها القائمة على التفاعل لكلٍّ من موافقات التنفيذ وموافقات Plugin، مع الاستمرار في السماح باختلاف المصادقة حسب نوع الموافقة. +- لا يزال `createApproverRestrictedNativeApprovalAdapter` موجودًا كغلاف توافقي، لكن يجب أن يفضّل الكود الجديد باني الإمكانات وأن يكشف `approvalCapability` على Plugin. -بالنسبة إلى نقاط دخول القنوات الساخنة، فضّل المسارات الفرعية الأضيق لوقت التشغيل عندما تحتاج فقط +بالنسبة إلى نقاط دخول القنوات الساخنة، يُفضّل استخدام المسارات الفرعية الأضيق لوقت التشغيل عندما تحتاج فقط إلى جزء واحد من هذه المجموعة: - `openclaw/plugin-sdk/approval-auth-runtime` @@ -109,90 +120,94 @@ x-i18n: - `openclaw/plugin-sdk/approval-reply-runtime` - `openclaw/plugin-sdk/channel-runtime-context` -وبالمثل، فضّل `openclaw/plugin-sdk/setup-runtime`، +وبالمثل، يُفضّل `openclaw/plugin-sdk/setup-runtime`، و`openclaw/plugin-sdk/setup-adapter-runtime`، و`openclaw/plugin-sdk/reply-runtime`، و`openclaw/plugin-sdk/reply-dispatch-runtime`، و`openclaw/plugin-sdk/reply-reference`، و -`openclaw/plugin-sdk/reply-chunking` عندما لا تحتاج إلى السطح -الأوسع. +`openclaw/plugin-sdk/reply-chunking` عندما لا تحتاج إلى السطح الأشمل +ذي المظلة الأوسع. وبالنسبة إلى الإعداد تحديدًا: - يغطي `openclaw/plugin-sdk/setup-runtime` مساعدات الإعداد الآمنة لوقت التشغيل: - مهايئات ترقيع الإعدادات الآمنة للاستيراد (`createPatchedAccountSetupAdapter`, - و`createEnvPatchedAccountSetupAdapter`, - و`createSetupInputPresenceValidator`)، ومخرجات + مهايئات ترقيع الإعداد الآمنة للاستيراد (`createPatchedAccountSetupAdapter`, + `createEnvPatchedAccountSetupAdapter`, + `createSetupInputPresenceValidator`)، ومخرجات ملاحظات البحث، و`promptResolvedAllowFrom`، و`splitSetupEntries`، وبُناة - setup-proxy المُفوَّضة -- يمثل `openclaw/plugin-sdk/setup-adapter-runtime` المدخل الضيق - الواعي بالبيئة لـ `createEnvPatchedAccountSetupAdapter` -- يغطي `openclaw/plugin-sdk/channel-setup` بُناة الإعداد ذات التثبيت الاختياري بالإضافة إلى بعض العناصر الأولية الآمنة للإعداد: - `createOptionalChannelSetupSurface` و`createOptionalChannelSetupAdapter`، + الوكيل المفوّض للإعداد +- يمثّل `openclaw/plugin-sdk/setup-adapter-runtime` الواجهة + الضيقة الواعية بالبيئة الخاصة بـ `createEnvPatchedAccountSetupAdapter` +- يغطي `openclaw/plugin-sdk/channel-setup` بُناة الإعداد + الخاصة بالتثبيت الاختياري بالإضافة إلى بعض الأساسيات الآمنة للإعداد: + `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -إذا كانت قناتك تدعم الإعداد أو المصادقة المدفوعين بالبيئة ويجب أن تعرف تدفقات البدء/الإعدادات العامة -أسماء متغيرات البيئة هذه قبل تحميل وقت التشغيل، فأعلن عنها في -manifest الخاص بـ plugin ضمن `channelEnvVars`. وأبقِ `envVars` الخاصة بوقت تشغيل القناة أو الثوابت المحلية -للنص الموجّه للمشغّل فقط. -`createOptionalChannelSetupWizard`، و`DEFAULT_ACCOUNT_ID`، -و`createTopLevelChannelDmPolicy`، و`setSetupChannelEnabled`، و +إذا كانت قناتك تدعم إعدادًا أو مصادقة مدفوعَين بالبيئة وكان ينبغي أن تعرف +تدفقات الإقلاع/الإعداد العامة أسماء متغيرات البيئة هذه قبل تحميل وقت التشغيل، +فصرّح بها في ملف بيان Plugin عبر `channelEnvVars`. واحتفظ بـ +`envVars` الخاص بوقت تشغيل القناة أو الثوابت المحلية لنسخ النصوص الموجّهة +للمشغّل فقط. +`createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, +`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`، و `splitSetupEntries` -- استخدم المدخل الأوسع `openclaw/plugin-sdk/setup` فقط عندما تحتاج أيضًا إلى - مساعدات الإعداد/التهيئة المشتركة الأثقل مثل +- استخدم واجهة `openclaw/plugin-sdk/setup` الأوسع فقط عندما تحتاج أيضًا إلى + مساعدات الإعداد/الضبط المشتركة الأثقل مثل `moveSingleAccountChannelSectionToDefaultAccount(...)` -إذا كانت قناتك تريد فقط الإعلان عن "ثبّت هذا plugin أولًا" في أسطح الإعداد، -ففضّل `createOptionalChannelSetupSurface(...)`. إذ يفشل المهايئ/المعالج المولَّدان -في مسارات كتابة الإعدادات والإنهاء بشكل مغلق، ويعيدان استخدام الرسالة نفسها -المطلوبة للتثبيت عبر التحقق والإنهاء ونص رابط الوثائق. +إذا كانت قناتك تريد فقط الإعلان عن "ثبّت هذا Plugin أولًا" في +أسطح الإعداد، ففضّل `createOptionalChannelSetupSurface(...)`. يفشل +المهايئ/المعالج المُنشأان بإغلاق آمن عند كتابة الإعدادات وعند الإنهاء، +ويعيدان استخدام رسالة "التثبيت مطلوب" نفسها عبر التحقق والإنهاء ونسخة +رابط التوثيق. -وبالنسبة إلى المسارات الساخنة الأخرى في القنوات، فضّل المساعدات الضيقة بدلًا من الأسطح القديمة الأوسع: +بالنسبة إلى مسارات القنوات الساخنة الأخرى، يُفضّل استخدام المساعدات الضيقة بدلًا من +الأسطح القديمة الأوسع: -- `openclaw/plugin-sdk/account-core`، - و`openclaw/plugin-sdk/account-id`، +- `openclaw/plugin-sdk/account-core`, + و`openclaw/plugin-sdk/account-id`, و`openclaw/plugin-sdk/account-resolution`، و - `openclaw/plugin-sdk/account-helpers` لإعدادات الحسابات المتعددة + `openclaw/plugin-sdk/account-helpers` للإعدادات متعددة الحسابات والرجوع إلى الحساب الافتراضي - `openclaw/plugin-sdk/inbound-envelope` و - `openclaw/plugin-sdk/inbound-reply-dispatch` لمسار/غلاف الوارد - وربط التسجيل والإرسال -- `openclaw/plugin-sdk/messaging-targets` لتحليل/مطابقة الأهداف + `openclaw/plugin-sdk/inbound-reply-dispatch` لربط + المسار/الغلاف الوارد وتسجيله ثم إرساله +- `openclaw/plugin-sdk/messaging-targets` لتحليل الأهداف ومطابقتها - `openclaw/plugin-sdk/outbound-media` و - `openclaw/plugin-sdk/outbound-runtime` لتحميل الوسائط بالإضافة إلى - مفوّضي الهوية/الإرسال الصادر + `openclaw/plugin-sdk/outbound-runtime` لتحميل الوسائط + بالإضافة إلى مفوّضي الهوية/الإرسال الصادر - `openclaw/plugin-sdk/thread-bindings-runtime` لدورة حياة ربط السلاسل وتسجيل المهايئات -- `openclaw/plugin-sdk/agent-media-payload` فقط عندما يظل هناك حاجة إلى - تخطيط حقول حمولة agent/media قديم -- `openclaw/plugin-sdk/telegram-command-config` لتطبيع الأوامر المخصصة في Telegram، - والتحقق من التكرار/التعارض، وعقد إعدادات الأوامر - المستقر احتياطيًا +- `openclaw/plugin-sdk/agent-media-payload` فقط عندما يكون تنسيق حقل + حمولة agent/media القديم لا يزال مطلوبًا +- `openclaw/plugin-sdk/telegram-command-config` لتطبيع + الأوامر المخصصة في Telegram، والتحقق من التكرار/التعارض، وعقد إعداد + أوامر ثابت كبديل احتياطي -يمكن للقنوات الخاصة بالمصادقة فقط عادةً الاكتفاء بالمسار الافتراضي: يتولى core الموافقات، ويعرض plugin فقط إمكانات الصادر/المصادقة. أما قنوات الموافقات الأصلية مثل Matrix وSlack وTelegram ووسائط الدردشة المخصصة، فيجب أن تستخدم المساعدات الأصلية المشتركة بدلًا من بناء دورة حياة الموافقة الخاصة بها. +يمكن لقنوات المصادقة فقط عادةً الاكتفاء بالمسار الافتراضي: تتولى النواة الموافقات ويكشف Plugin فقط عن إمكانات الإرسال الصادر/المصادقة. أما قنوات الموافقة الأصلية مثل Matrix وSlack وTelegram ووسائط الدردشة المخصصة، فيجب أن تستخدم المساعدات الأصلية المشتركة بدلًا من بناء دورة حياة الموافقة الخاصة بها. -## سياسة الإشارة في الوارد +## سياسة الإشارة الواردة -أبقِ التعامل مع الإشارات الواردة مقسّمًا إلى طبقتين: +أبقِ معالجة الإشارات الواردة مقسّمة إلى طبقتين: -- جمع الأدلة المملوك لـ plugin +- جمع الأدلة الذي يملكه Plugin - تقييم السياسة المشتركة استخدم `openclaw/plugin-sdk/channel-inbound` للطبقة المشتركة. -ما يناسب المنطق المحلي في plugin: +ملائم لمنطق Plugin المحلي: - اكتشاف الرد على البوت - اكتشاف الاقتباس من البوت -- فحوصات المشاركة في السلاسل -- استثناءات رسائل الخدمة/النظام -- الذاكرات المؤقتة الأصلية للمنصة اللازمة لإثبات مشاركة البوت +- التحقق من المشاركة في السلسلة +- استبعاد رسائل الخدمة/النظام +- الذاكرات المؤقتة الأصلية الخاصة بالمنصة اللازمة لإثبات مشاركة البوت -ما يناسب المساعد المشترك: +ملائم للمساعد المشترك: - `requireMention` - نتيجة الإشارة الصريحة -- قائمة السماح للإشارة الضمنية +- قائمة سماح الإشارة الضمنية - تجاوز الأوامر - قرار التخطي النهائي @@ -200,7 +215,7 @@ manifest الخاص بـ plugin ضمن `channelEnvVars`. وأبقِ `envVars` ا 1. احسب حقائق الإشارة المحلية. 2. مرّر هذه الحقائق إلى `resolveInboundMentionDecision({ facts, policy })`. -3. استخدم `decision.effectiveWasMentioned` و`decision.shouldBypassMention` و`decision.shouldSkip` في بوابة الوارد الخاصة بك. +3. استخدم `decision.effectiveWasMentioned` و`decision.shouldBypassMention` و`decision.shouldSkip` في بوابة الوارد لديك. ```typescript import { @@ -240,7 +255,7 @@ if (decision.shouldSkip) return; ``` يكشف `api.runtime.channel.mentions` عن مساعدات الإشارة المشتركة نفسها -لـ plugins القنوات المضمّنة التي تعتمد أصلًا على حقن وقت التشغيل: +لـ Plugins القنوات المضمّنة التي تعتمد بالفعل على حقن وقت التشغيل: - `buildMentionRegexes` - `matchesMentionPatterns` @@ -248,18 +263,18 @@ if (decision.shouldSkip) return; - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -تظل مساعدات `resolveMentionGating*` الأقدم موجودة على -`openclaw/plugin-sdk/channel-inbound` كتصديرات توافق فقط. ويجب أن تستخدم الشيفرة الجديدة -`resolveInboundMentionDecision({ facts, policy })`. +تبقى مساعدات `resolveMentionGating*` الأقدم موجودة على +`openclaw/plugin-sdk/channel-inbound` كتصديرات توافقية فقط. يجب أن يستخدم +الكود الجديد `resolveInboundMentionDecision({ facts, policy })`. ## شرح عملي - - أنشئ ملفات plugin القياسية. الحقل `channel` في `package.json` هو - ما يجعل هذا plugin قناة. وللاطلاع على السطح الكامل لبيانات تعريف الحزمة، - راجع [إعداد plugin وتهيئته](/ar/plugins/sdk-setup#openclaw-channel): + + أنشئ ملفات Plugin القياسية. إن الحقل `channel` في `package.json` هو + ما يجعل هذا Plugin قناة. وللاطلاع على سطح بيانات الحزمة الكامل، + راجع [إعداد Plugin وضبطه](/ar/plugins/sdk-setup#openclaw-channel): ```json package.json @@ -308,7 +323,7 @@ if (decision.shouldSkip) return; - + تحتوي الواجهة `ChannelPlugin` على العديد من أسطح المهايئات الاختيارية. ابدأ بالحد الأدنى — `id` و`setup` — ثم أضف المهايئات حسب الحاجة. @@ -405,24 +420,24 @@ if (decision.shouldSkip) return; }); ``` - - بدلًا من تنفيذ واجهات المهايئات منخفضة المستوى يدويًا، فإنك تمرر - خيارات تعريفية ويتولى المنشئ تركيبها: + + بدلًا من تنفيذ واجهات المهايئات منخفضة المستوى يدويًا، تمرّر + خيارات تصريحية ويتولى الباني تجميعها: - | الخيار | ما الذي يربطه | + | Option | ما الذي يربطه | | --- | --- | - | `security.dm` | محلل أمان DM ضمن النطاق من حقول الإعدادات | - | `pairing.text` | تدفق اقتران DM قائم على النص مع تبادل الرمز | - | `threading` | محلل وضع reply-to (ثابت، أو ضمن نطاق الحساب، أو مخصص) | - | `outbound.attachedResults` | دوال إرسال تُرجع بيانات تعريف النتيجة (معرّفات الرسائل) | + | `security.dm` | محلّل أمان الرسائل المباشرة المقيّد بنطاق حقول الإعداد | + | `pairing.text` | تدفق اقتران رسائل مباشرة قائم على النص مع تبادل الرموز | + | `threading` | محلّل نمط الرد (ثابت، مقيّد بالحساب، أو مخصص) | + | `outbound.attachedResults` | دوال إرسال تُرجع بيانات تعريفية للنتيجة (معرّفات الرسائل) | - يمكنك أيضًا تمرير كائنات مهايئات خام بدلًا من الخيارات التعريفية + يمكنك أيضًا تمرير كائنات مهايئ خام بدلًا من الخيارات التصريحية إذا كنت تحتاج إلى تحكم كامل. - + أنشئ `index.ts`: ```typescript index.ts @@ -458,21 +473,21 @@ if (decision.shouldSkip) return; }); ``` - ضع واصفات CLI المملوكة للقناة في `registerCliMetadata(...)` حتى يتمكن OpenClaw - من عرضها في تعليمات الجذر من دون تفعيل وقت تشغيل القناة الكامل، - بينما تستمر عمليات التحميل الكاملة العادية في التقاط الواصفات نفسها لتسجيل الأوامر - الفعلي. وأبقِ `registerFull(...)` للأعمال الخاصة بوقت التشغيل فقط. - وإذا كان `registerFull(...)` يسجل أساليب Gateway RPC، فاستخدم - بادئة خاصة بـ plugin. تظل نطاقات الإدارة المحجوزة في core (`config.*`, - و`exec.approvals.*`، و`wizard.*`، و`update.*`) محجوزة وتُحل دائمًا + ضع واصفات CLI التي تملكها القناة في `registerCliMetadata(...)` حتى يتمكن OpenClaw + من عرضها في المساعدة الجذرية من دون تفعيل وقت تشغيل القناة الكامل، + بينما تلتقط عمليات التحميل الكاملة العادية الواصفات نفسها لتسجيل + الأوامر الفعلي. وأبقِ `registerFull(...)` للأعمال الخاصة بوقت التشغيل فقط. + إذا كان `registerFull(...)` يسجّل أساليب Gateway RPC، فاستخدم + بادئة خاصة بالـ Plugin. تظل مساحات أسماء إدارة النواة (`config.*`, + `exec.approvals.*`, `wizard.*`, `update.*`) محجوزة وتُحل دائمًا إلى `operator.admin`. - يتولى `defineChannelPluginEntry` فصل أوضاع التسجيل تلقائيًا. راجع - [نقاط الإدخال](/ar/plugins/sdk-entrypoints#definechannelpluginentry) للاطلاع على جميع + يتولى `defineChannelPluginEntry` معالجة تقسيم وضع التسجيل تلقائيًا. راجع + [نقاط الدخول](/ar/plugins/sdk-entrypoints#definechannelpluginentry) لمعرفة جميع الخيارات. - + أنشئ `setup-entry.ts` للتحميل الخفيف أثناء الإعداد الأولي: ```typescript setup-entry.ts @@ -482,16 +497,16 @@ if (decision.shouldSkip) return; export default defineSetupPluginEntry(acmeChatPlugin); ``` - يحمّل OpenClaw هذا بدلًا من الإدخال الكامل عندما تكون القناة معطلة - أو غير مكوّنة. وهذا يتجنب سحب شيفرة وقت تشغيل ثقيلة أثناء تدفقات الإعداد. - راجع [الإعداد والتهيئة](/ar/plugins/sdk-setup#setup-entry) لمزيد من التفاصيل. + يحمّل OpenClaw هذا بدلًا من نقطة الدخول الكاملة عندما تكون القناة معطّلة + أو غير مهيأة. وهذا يتجنب سحب كود وقت تشغيل ثقيل أثناء تدفقات الإعداد. + راجع [الإعداد والضبط](/ar/plugins/sdk-setup#setup-entry) لمعرفة التفاصيل. - - يحتاج plugin الخاص بك إلى استقبال الرسائل من المنصة وتمريرها إلى - OpenClaw. والنمط المعتاد هو webhook يتحقق من الطلب - ويرسله عبر معالج الوارد الخاص بقناتك: + + يحتاج Plugin الخاص بك إلى استلام الرسائل من المنصة وتمريرها إلى + OpenClaw. النمط الشائع هو Webhook يتحقق من الطلب ثم + يرسله عبر معالج الوارد الخاص بقناتك: ```typescript registerFull(api) { @@ -515,16 +530,16 @@ if (decision.shouldSkip) return; ``` - معالجة الرسائل الواردة خاصة بكل قناة. فكل plugin قناة يملك - مسار الوارد الخاص به. انظر إلى plugins القنوات المضمّنة - (مثل حزمة plugin الخاصة بـ Microsoft Teams أو Google Chat) للاطلاع على أنماط فعلية. + معالجة الرسائل الواردة خاصة بكل قناة. كل Plugin قناة يملك + خط أنبوب الوارد الخاص به. انظر إلى Plugins القنوات المضمّنة + (مثل حزمة Plugin الخاصة بـ Microsoft Teams أو Google Chat) للاطلاع على أنماط فعلية. -اكتب اختبارات موضوعة بجانب الشيفرة في `src/channel.test.ts`: +اكتب اختبارات مرافقة في `src/channel.test.ts`: ```typescript src/channel.test.ts import { describe, it, expect } from "vitest"; @@ -571,8 +586,8 @@ if (decision.shouldSkip) return; ``` /acme-chat/ -├── package.json # بيانات تعريف openclaw.channel -├── openclaw.plugin.json # Manifest مع مخطط الإعدادات +├── package.json # بيانات openclaw.channel الوصفية +├── openclaw.plugin.json # ملف البيان مع مخطط الإعداد ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry ├── api.ts # التصديرات العامة (اختياري) @@ -580,7 +595,7 @@ if (decision.shouldSkip) return; └── src/ ├── channel.ts # ChannelPlugin عبر createChatChannelPlugin ├── channel.test.ts # الاختبارات - ├── client.ts # عميل API الخاص بالمنصة + ├── client.ts # عميل API للمنصة └── runtime.ts # مخزن وقت التشغيل (عند الحاجة) ``` @@ -588,7 +603,7 @@ if (decision.shouldSkip) return; - أوضاع reply ثابتة أو ضمن نطاق الحساب أو مخصصة + أوضاع رد ثابتة، أو مقيّدة بالحساب، أو مخصصة describeMessageTool واكتشاف الإجراءات @@ -602,15 +617,15 @@ if (decision.shouldSkip) return; -لا تزال بعض المداخل المساعدة المضمّنة موجودة لصيانة plugins المضمّنة -ولأغراض التوافق. لكنها ليست النمط الموصى به لـ plugins القنوات الجديدة؛ -فضّل المسارات الفرعية العامة channel/setup/reply/runtime من -سطح SDK المشترك ما لم تكن تصون تلك العائلة من plugins المضمّنة مباشرة. +لا تزال بعض واجهات المساعدات المضمّنة موجودة لصيانة Plugins المضمّنة +ولأغراض التوافق. وهي ليست النمط الموصى به لـ Plugins القنوات الجديدة؛ +بل يُفضّل استخدام المسارات الفرعية العامة channel/setup/reply/runtime من +سطح SDK المشترك ما لم تكن تصون تلك العائلة من Plugins المضمّنة مباشرةً. ## الخطوات التالية -- [plugins المزوّد](/ar/plugins/sdk-provider-plugins) — إذا كان plugin الخاص بك يوفّر أيضًا نماذج -- [نظرة عامة على SDK](/ar/plugins/sdk-overview) — المرجع الكامل لاستيراد المسارات الفرعية +- [Plugins الموفّرات](/ar/plugins/sdk-provider-plugins) — إذا كان Plugin الخاص بك يوفّر النماذج أيضًا +- [نظرة عامة على SDK](/ar/plugins/sdk-overview) — المرجع الكامل للاستيراد عبر المسارات الفرعية - [اختبار SDK](/ar/plugins/sdk-testing) — أدوات الاختبار واختبارات العقود -- [Manifest الخاص بـ plugin](/ar/plugins/manifest) — المخطط الكامل لـ manifest +- [ملف بيان Plugin](/ar/plugins/manifest) — المخطط الكامل لملف البيان diff --git a/docs/ar/reference/RELEASING.md b/docs/ar/reference/RELEASING.md index 4fe3c829c..3a39d1096 100644 --- a/docs/ar/reference/RELEASING.md +++ b/docs/ar/reference/RELEASING.md @@ -5,10 +5,10 @@ read_when: summary: قنوات الإصدار العامة، وتسمية الإصدارات، والوتيرة title: سياسة الإصدار x-i18n: - generated_at: "2026-04-14T07:17:39Z" + generated_at: "2026-04-15T07:17:46Z" model: gpt-5.4 provider: openai - source_hash: 3eaf9f1786b8c9fd4f5a9c657b623cb69d1a485958e1a9b8f108511839b63587 + source_hash: 88724307269ab783a9fbf8a0540fea198d8a3add68457f4e64d5707114fa518c source_path: reference/RELEASING.md workflow: 15 --- @@ -17,178 +17,171 @@ x-i18n: لدى OpenClaw ثلاث مسارات إصدار عامة: -- stable: إصدارات موسومة تُنشر إلى npm `beta` افتراضيًا، أو إلى npm `latest` عند الطلب الصريح -- beta: وسوم إصدارات تمهيدية تُنشر إلى npm `beta` +- stable: إصدارات موسومة تُنشَر إلى npm `beta` افتراضيًا، أو إلى npm `latest` عند الطلب الصريح +- beta: وسوم إصدارات تمهيدية تُنشَر إلى npm `beta` - dev: الرأس المتحرك لفرع `main` ## تسمية الإصدارات - إصدار الإصدار المستقر: `YYYY.M.D` - وسم Git: `vYYYY.M.D` -- إصدار تصحيح الإصدار المستقر: `YYYY.M.D-N` +- إصدار التصحيح للإصدار المستقر: `YYYY.M.D-N` - وسم Git: `vYYYY.M.D-N` -- إصدار بيتا التمهيدي: `YYYY.M.D-beta.N` +- إصدار beta التمهيدي: `YYYY.M.D-beta.N` - وسم Git: `vYYYY.M.D-beta.N` -- لا تُضِف أصفارًا بادئة إلى الشهر أو اليوم +- لا تضف أصفارًا بادئة إلى الشهر أو اليوم - `latest` يعني إصدار npm المستقر المُرقّى الحالي -- `beta` يعني هدف تثبيت بيتا الحالي -- تُنشر الإصدارات المستقرة وإصدارات التصحيح المستقرة إلى npm `beta` افتراضيًا؛ ويمكن لمشغّلي الإصدار استهداف `latest` صراحةً، أو ترقية بنية بيتا مُتحقَّق منها لاحقًا -- يشحن كل إصدار من OpenClaw حزمة npm وتطبيق macOS معًا +- `beta` يعني هدف تثبيت beta الحالي +- تُنشَر الإصدارات المستقرة وتصحيحات الإصدارات المستقرة إلى npm `beta` افتراضيًا؛ ويمكن لمشغّلي الإصدار استهداف `latest` صراحةً، أو ترقية بنية beta تم التحقق منها لاحقًا +- كل إصدار من OpenClaw يشحن حزمة npm وتطبيق macOS معًا ## وتيرة الإصدار -- تبدأ الإصدارات من beta أولًا -- لا يأتي stable إلا بعد التحقق من أحدث beta -- إجراء الإصدار التفصيلي، والموافقات، وبيانات الاعتماد، وملاحظات الاسترداد +- تبدأ الإصدارات عبر beta أولًا +- لا يأتي الإصدار المستقر إلا بعد التحقق من أحدث إصدار beta +- إن إجراءات الإصدار التفصيلية، والموافقات، وبيانات الاعتماد، وملاحظات الاسترداد مخصّصة للمشرفين فقط -## التحقق المسبق للإصدار +## الفحوصات التمهيدية للإصدار - شغّل `pnpm build && pnpm ui:build` قبل `pnpm release:check` حتى تكون - عناصر إصدار `dist/*` المتوقعة وحزمة Control UI موجودة من أجل + عناصر الإصدار المتوقعة `dist/*` وحزمة Control UI موجودة من أجل خطوة التحقق من الحزمة - شغّل `pnpm release:check` قبل كل إصدار موسوم -- تعمل الآن فحوصات الإصدار ضمن سير عمل يدوي منفصل: +- تعمل فحوصات الإصدار الآن ضمن سير عمل يدوي منفصل: `OpenClaw Release Checks` -- هذا الفصل مقصود: إبقاء مسار إصدار npm الحقيقي قصيرًا، +- يتم إرسال التحقق من التثبيت والترقية عبر الأنظمة المختلفة وقت التشغيل من + سير العمل الخاص المستدعي + `openclaw/releases-private/.github/workflows/openclaw-cross-os-release-checks.yml`, + الذي يستدعي سير العمل العام القابل لإعادة الاستخدام + `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` +- هذا الفصل مقصود: للحفاظ على مسار إصدار npm الفعلي قصيرًا، وحتميًا، ومركّزًا على العناصر، بينما تبقى الفحوصات الحية الأبطأ في - مسارها الخاص حتى لا تؤخر النشر أو تمنعه -- يجب تشغيل فحوصات الإصدار من مرجع سير العمل `main` حتى تبقى - منطقية سير العمل والأسرار معتمدة وموحدة -- يقبل سير العمل هذا إما وسم إصدار موجودًا أو SHA الكامل الحالي - المكوّن من 40 حرفًا لالتزام `main` -- في وضع commit-SHA، لا يقبل إلا HEAD الحالي لـ `origin/main`؛ استخدم - وسم إصدار للالتزامات الأقدم الخاصة بالإصدار -- يقبل التحقق المسبق للتحقق فقط في `OpenClaw NPM Release` أيضًا - SHA الكامل الحالي المكوّن من 40 حرفًا لالتزام `main` من دون الحاجة إلى وسم مدفوع -- هذا المسار المعتمد على SHA مخصص للتحقق فقط ولا يمكن ترقيته إلى نشر حقيقي -- في وضع SHA، ينشئ سير العمل `v` فقط - من أجل فحص بيانات تعريف الحزمة؛ ولا يزال النشر الحقيقي يتطلب وسم إصدار حقيقي -- يُبقي كلا سيرَي العمل مسار النشر والترقية الحقيقيين على مشغّلات GitHub المستضافة، - بينما يمكن لمسار التحقق غير المُعدِّل استخدام مشغّلات - Blacksmith Linux الأكبر + مسارها الخاص حتى لا تؤخر أو تمنع النشر +- يجب إرسال فحوصات الإصدار من مرجع سير عمل `main` حتى تبقى + منطقية سير العمل والأسرار معتمدة وقياسية +- يقبل سير العمل هذا إما وسم إصدار موجودًا أو قيمة SHA كاملة من 40 حرفًا + لالتزام `main` الحالي +- في وضع SHA الخاص بالالتزام، لا يقبل إلا HEAD الحالي لـ `origin/main`؛ استخدم + وسم إصدار لالتزامات الإصدار الأقدم +- إن الفحص التمهيدي للتحقق فقط في `OpenClaw NPM Release` يقبل أيضًا + قيمة SHA كاملة من 40 حرفًا لالتزام `main` الحالي دون الحاجة إلى وسم مدفوع +- هذا المسار الخاص بـ SHA مخصّص للتحقق فقط ولا يمكن ترقيته إلى نشر فعلي +- في وضع SHA، ينشئ سير العمل `v` فقط من أجل + فحص بيانات الحزمة؛ أما النشر الفعلي فما زال يتطلب وسم إصدار حقيقي +- يحافظ كلا سيرَي العمل على مسار النشر والترقية الفعليين على + GitHub-hosted runners، بينما يمكن لمسار التحقق غير المعدِّل استخدام + مشغلات Blacksmith Linux الأكبر - يشغّل سير العمل هذا `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` - باستخدام سريَي سير العمل `OPENAI_API_KEY` و`ANTHROPIC_API_KEY` -- لم يعد التحقق المسبق لإصدار npm ينتظر مسار فحوصات الإصدار المنفصل + باستخدام سريَّي سير العمل `OPENAI_API_KEY` و`ANTHROPIC_API_KEY` +- لم يعد الفحص التمهيدي لإصدار npm ينتظر مسار فحوصات الإصدار المنفصل - شغّل `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` (أو وسم beta/التصحيح المطابق) قبل الموافقة - بعد نشر npm، شغّل `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` - (أو إصدار beta/التصحيح المطابق) للتحقق من - مسار التثبيت من السجل المنشور في بادئة temp جديدة -- تستخدم الآن أتمتة الإصدار الخاصة بالمشرفين أسلوب التحقق المسبق ثم الترقية: - - يجب أن يمر نشر npm الحقيقي عبر `preflight_run_id` ناجح لـ npm + (أو إصدار beta/التصحيح المطابق) للتحقق من مسار التثبيت من السجل المنشور + في بادئة مؤقتة جديدة +- تستخدم أتمتة الإصدار الخاصة بالمشرفين الآن أسلوب الفحص التمهيدي ثم الترقية: + - يجب أن يجتاز نشر npm الفعلي قيمة `preflight_run_id` ناجحة لـ npm - تُوجَّه إصدارات npm المستقرة إلى `beta` افتراضيًا - - يمكن أن يستهدف نشر npm المستقر `latest` صراحةً عبر إدخال سير العمل - - ما تزال ترقية npm المستقرة من `beta` إلى `latest` متاحة كوضع يدوي صريح ضمن سير العمل الموثوق `OpenClaw NPM Release` - - يمكن أيضًا لعمليات النشر المستقرة المباشرة تشغيل وضع مزامنة `dist-tag` صريح - يشير فيه كل من `latest` و`beta` إلى الإصدار المستقر المنشور بالفعل - - ما تزال أوضاع `dist-tag` هذه تحتاج إلى `NPM_TOKEN` صالح في بيئة `npm-release` لأن إدارة npm `dist-tag` منفصلة عن النشر الموثوق - - إصدار `macOS Release` العام مخصص للتحقق فقط - - يجب أن يمر نشر mac الخاص الحقيقي والخاص عبر - `preflight_run_id` و`validate_run_id` ناجحين لـ mac الخاص - - تروّج مسارات النشر الحقيقية للعناصر المُحضّرة بدلًا من إعادة بنائها - مرة أخرى -- بالنسبة إلى إصدارات التصحيح المستقرة مثل `YYYY.M.D-N`، يتحقق مُراجِع ما بعد النشر - أيضًا من مسار الترقية نفسه في بادئة temp من `YYYY.M.D` إلى `YYYY.M.D-N` - حتى لا تترك تصحيحات الإصدار بصمت عمليات التثبيت العالمية الأقدم على + - يمكن لنشر npm المستقر استهداف `latest` صراحةً عبر مدخلات سير العمل + - أصبحت عملية تغيير npm dist-tag المعتمدة على الرمز المميز موجودة الآن في + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` + لأسباب أمنية، لأن `npm dist-tag add` لا يزال يحتاج إلى `NPM_TOKEN` بينما يحتفظ + المستودع العام بنشر يعتمد على OIDC فقط + - إن `macOS Release` العام مخصّص للتحقق فقط + - يجب أن يجتاز النشر الخاص الفعلي لـ mac قيمة mac خاصة ناجحة لكل من + `preflight_run_id` و`validate_run_id` + - تقوم مسارات النشر الفعلية بترقية العناصر المُحضّرة بدلًا من + إعادة بنائها مرة أخرى +- بالنسبة إلى إصدارات التصحيح المستقرة مثل `YYYY.M.D-N`، يتحقق فاحص ما بعد النشر + أيضًا من مسار الترقية نفسه في البادئة المؤقتة من `YYYY.M.D` إلى `YYYY.M.D-N` + حتى لا تترك تصحيحات الإصدار تثبيتات global الأقدم بصمت على الحمولة الأساسية للإصدار المستقر -- يفشل التحقق المسبق لإصدار npm بشكل مغلق ما لم تتضمن الحزمة المضغوطة كلاً من - `dist/control-ui/index.html` وحمولة غير فارغة ضمن `dist/control-ui/assets/` - حتى لا نشحن مجددًا لوحة متصفح فارغة -- يفرض `pnpm test:install:smoke` أيضًا ميزانية `unpackedSize` الخاصة بحزمة npm - على الحزمة المرشحة للتحديث، بحيث تلتقط اختبارات e2e الخاصة بالمثبّت تضخم الحزمة غير المقصود - قبل مسار نشر الإصدار -- إذا كانت أعمال الإصدار قد مست تخطيط CI أو بيانات توقيت الإضافات أو - مصفوفات اختبارات الإضافات، فأعِد توليد وراجِع - مخرجات مصفوفة سير العمل `checks-node-extensions` المملوكة للمخطِّط من `.github/workflows/ci.yml` - قبل الموافقة حتى لا تصف ملاحظات الإصدار تخطيط CI قديمًا -- تتضمن جاهزية إصدار macOS المستقر أيضًا أسطح أداة التحديث: - - يجب أن ينتهي إصدار GitHub محتويًا على `.zip` و`.dmg` و`.dSYM.zip` المُعبأة +- يفشل الفحص التمهيدي لإصدار npm بشكل مغلق ما لم تتضمن الحزمة المضغوطة كِلا + `dist/control-ui/index.html` وحمولة غير فارغة لـ `dist/control-ui/assets/` + حتى لا نشحن لوحة تحكم متصفح فارغة مرة أخرى +- يفرض `pnpm test:install:smoke` أيضًا ميزانية `unpackedSize` الخاصة بحزمة npm على + الحزمة المضغوطة المرشحة للتحديث، بحيث تلتقط اختبارات المُثبّت الشاملة + التضخم العرضي في الحزمة قبل مسار نشر الإصدار +- إذا لمس عمل الإصدار تخطيط CI أو ملفات توقيت الإضافات أو + مصفوفات اختبارات الإضافات، فأعد توليد وراجع مخرجات مصفوفة سير العمل + `checks-node-extensions` المملوكة للمخطط من `.github/workflows/ci.yml` + قبل الموافقة حتى لا تصف ملاحظات الإصدار بنية CI قديمة +- يتضمن جاهزية إصدار macOS المستقر أيضًا أسطح التحديث: + - يجب أن ينتهي إصدار GitHub مع الحزم `.zip` و`.dmg` و`.dSYM.zip` - يجب أن يشير `appcast.xml` على `main` إلى ملف zip المستقر الجديد بعد النشر - - يجب أن يحافظ التطبيق المُعبأ على معرّف حزمة غير تصحيحي، وURL غير فارغ - لخلاصة Sparkle، و`CFBundleVersion` يساوي أو يفوق حد Sparkle الأدنى القياسي - لإصدار ذلك الإصدار + - يجب أن يحتفظ التطبيق المعبأ بمعرّف حزمة غير خاص بالتصحيح، وعنوان URL غير فارغ + لخلاصة Sparkle، وقيمة `CFBundleVersion` تساوي أو تتجاوز الحد الأدنى + المعتمد لبناء Sparkle لذلك الإصدار -## مُدخلات سير عمل NPM +## مدخلات سير عمل NPM -يقبل `OpenClaw NPM Release` مُدخلات يتحكم بها المشغّل كما يلي: +يقبل `OpenClaw NPM Release` مدخلات يتحكم بها المشغّل التالية: -- `tag`: وسم الإصدار المطلوب مثل `v2026.4.2` أو `v2026.4.2-1` أو - `v2026.4.2-beta.1`؛ وعند `preflight_only=true`، يمكن أن يكون أيضًا - SHA الكامل الحالي المكوّن من 40 حرفًا لالتزام `main` من أجل تحقق مسبق للتحقق فقط -- `preflight_only`: القيمة `true` للتحقق/البناء/الحزمة فقط، و`false` لمسار - النشر الحقيقي -- `preflight_run_id`: مطلوب في مسار النشر الحقيقي حتى يعيد سير العمل استخدام - الحزمة المضغوطة المُحضّرة من تشغيل التحقق المسبق الناجح +- `tag`: وسم إصدار مطلوب مثل `v2026.4.2` أو `v2026.4.2-1` أو + `v2026.4.2-beta.1`; وعندما يكون `preflight_only=true`، يمكن أن يكون أيضًا + قيمة SHA كاملة من 40 حرفًا لالتزام `main` الحالي للتحقق التمهيدي فقط +- `preflight_only`: `true` للتحقق/البناء/الحزمة فقط، و`false` لمسار النشر + الفعلي +- `preflight_run_id`: مطلوب في مسار النشر الفعلي حتى يعيد سير العمل استخدام + الحزمة المضغوطة المُحضّرة من تشغيل الفحص التمهيدي الناجح - `npm_dist_tag`: وسم npm الهدف لمسار النشر؛ والقيمة الافتراضية هي `beta` -- `promote_beta_to_latest`: القيمة `true` لتخطي النشر ونقل - بنية `beta` مستقرة منشورة بالفعل إلى `latest` -- `sync_stable_dist_tags`: القيمة `true` لتخطي النشر وتوجيه كل من `latest` و - `beta` إلى إصدار مستقر منشور بالفعل -يقبل `OpenClaw Release Checks` مُدخلات يتحكم بها المشغّل كما يلي: +يقبل `OpenClaw Release Checks` مدخلات يتحكم بها المشغّل التالية: -- `ref`: وسم إصدار موجود أو SHA الكامل الحالي المكوّن من 40 حرفًا لالتزام `main` - للتحقق +- `ref`: وسم إصدار موجود أو قيمة SHA كاملة من 40 حرفًا لالتزام `main` + الحالي من أجل التحقق القواعد: -- يمكن لوسوم stable ووسوم التصحيح النشر إلى `beta` أو `latest` +- يمكن لوسوم stable وcorrection النشر إلى `beta` أو `latest` - يمكن لوسوم beta التمهيدية النشر إلى `beta` فقط - يُسمح بإدخال SHA الكامل للالتزام فقط عندما يكون `preflight_only=true` -- يتطلب وضع commit-SHA في فحوصات الإصدار أيضًا HEAD الحالي لـ `origin/main` -- يجب أن يستخدم مسار النشر الحقيقي القيمة نفسها لـ `npm_dist_tag` المستخدمة أثناء التحقق المسبق؛ - ويتحقق سير العمل من تلك البيانات التعريفية قبل متابعة النشر -- يجب أن يستخدم وضع الترقية وسم stable أو وسم تصحيح، و`preflight_only=false`، - و`preflight_run_id` فارغًا، و`npm_dist_tag=beta` -- يجب أن يستخدم وضع مزامنة `dist-tag` وسم stable أو وسم تصحيح، - و`preflight_only=false`، و`preflight_run_id` فارغًا، و`npm_dist_tag=latest`، - و`promote_beta_to_latest=false` -- تتطلب أوضاع الترقية ومزامنة `dist-tag` أيضًا `NPM_TOKEN` صالحًا لأن - `npm dist-tag add` ما يزال يحتاج إلى مصادقة npm العادية؛ أما النشر الموثوق - فيغطي مسار نشر الحزمة فقط +- يتطلب وضع SHA الخاص بالالتزام في فحوصات الإصدار أيضًا HEAD الحالي لـ `origin/main` +- يجب أن يستخدم مسار النشر الفعلي نفس `npm_dist_tag` المستخدم أثناء الفحص التمهيدي؛ + ويتحقق سير العمل من تلك البيانات الوصفية قبل متابعة النشر ## تسلسل إصدار npm المستقر عند إصدار نسخة npm مستقرة: 1. شغّل `OpenClaw NPM Release` مع `preflight_only=true` - - قبل وجود وسم، يمكنك استخدام SHA الكامل الحالي لالتزام `main` من أجل - تشغيل جاف للتحقق فقط من سير عمل التحقق المسبق -2. اختر `npm_dist_tag=beta` للتدفق العادي الذي يبدأ بـ beta، أو `latest` فقط + - قبل وجود وسم، يمكنك استخدام قيمة SHA الكاملة الحالية لفرع `main` + لإجراء تشغيل تجريبي للتحقق فقط من سير عمل الفحص التمهيدي +2. اختر `npm_dist_tag=beta` للتدفق المعتاد الذي يبدأ عبر beta، أو `latest` فقط عندما تريد عمدًا نشر إصدار مستقر مباشر 3. شغّل `OpenClaw Release Checks` بشكل منفصل باستخدام الوسم نفسه أو - SHA الكامل الحالي لـ `main` عندما تريد تغطية حية لذاكرة التخزين المؤقت للمطالبات - - هذا فصل مقصود حتى تبقى التغطية الحية متاحة من دون + قيمة SHA الكاملة الحالية لفرع `main` عندما تريد تغطية حية لذاكرة التخزين المؤقت للمطالبات + - هذا الفصل مقصود حتى يبقى التغطية الحية متاحة دون إعادة ربط الفحوصات الطويلة أو غير المستقرة بسير عمل النشر -4. احفظ `preflight_run_id` الناجح -5. شغّل `OpenClaw NPM Release` مرة أخرى مع `preflight_only=false`، و`tag` - نفسه، و`npm_dist_tag` نفسه، و`preflight_run_id` المحفوظ -6. إذا وصل الإصدار إلى `beta`، فشغّل `OpenClaw NPM Release` لاحقًا باستخدام - وسم stable نفسه، و`promote_beta_to_latest=true`، و`preflight_only=false`، - و`preflight_run_id` فارغًا، و`npm_dist_tag=beta` عندما تريد نقل ذلك - الإصدار المنشور إلى `latest` -7. إذا نُشر الإصدار عمدًا مباشرةً إلى `latest` وكان يجب أن يتبع `beta` - البنية المستقرة نفسها، فشغّل `OpenClaw NPM Release` باستخدام - وسم stable نفسه، و`sync_stable_dist_tags=true`، و`promote_beta_to_latest=false`، - و`preflight_only=false`، و`preflight_run_id` فارغًا، و`npm_dist_tag=latest` +4. احفظ قيمة `preflight_run_id` الناجحة +5. شغّل `OpenClaw NPM Release` مرة أخرى مع `preflight_only=false`، ونفس + `tag`، ونفس `npm_dist_tag`، وقيمة `preflight_run_id` المحفوظة +6. إذا نزل الإصدار إلى `beta`، فاستخدم سير العمل الخاص + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` + لترقية ذلك الإصدار المستقر من `beta` إلى `latest` +7. إذا نُشر الإصدار عمدًا مباشرة إلى `latest` وكان ينبغي أن يتبعه `beta` + بالبنية المستقرة نفسها فورًا، فاستخدم سير العمل الخاص نفسه + لتوجيه كلا dist-tags إلى الإصدار المستقر، أو اترك مزامنة الإصلاح الذاتي + المجدولة تنقل `beta` لاحقًا -ما تزال أوضاع الترقية ومزامنة `dist-tag` تتطلب موافقة بيئة `npm-release` -و`NPM_TOKEN` صالحًا يمكن لسير العمل هذا الوصول إليه. +توجد عملية تعديل dist-tag في المستودع الخاص لأسباب أمنية لأنها ما تزال +تتطلب `NPM_TOKEN`، بينما يحتفظ المستودع العام بنشر يعتمد على OIDC فقط. -هذا يُبقي كلاً من مسار النشر المباشر ومسار الترقية الذي يبدأ بـ beta -موثقين ومرئيين للمشغّل. +وهذا يُبقي كلاً من مسار النشر المباشر ومسار الترقية الذي يبدأ عبر beta +موثّقين ومرئيين للمشغّل. -## مراجع عامة +## المراجع العامة - [`.github/workflows/openclaw-npm-release.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-npm-release.yml) - [`.github/workflows/openclaw-release-checks.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-release-checks.yml) +- [`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-cross-os-release-checks-reusable.yml) - [`scripts/openclaw-npm-release-check.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/openclaw-npm-release-check.ts) - [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh) - [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh) -يستخدم المشرفون مستندات الإصدار الخاصة في +يستخدم المشرفون وثائق الإصدار الخاصة في [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) -كدليل التشغيل الفعلي. +لدليل التشغيل الفعلي. diff --git a/docs/ar/reference/secretref-credential-surface.md b/docs/ar/reference/secretref-credential-surface.md index 5c2dfb210..385ef8a7e 100644 --- a/docs/ar/reference/secretref-credential-surface.md +++ b/docs/ar/reference/secretref-credential-surface.md @@ -1,29 +1,29 @@ --- read_when: - - التحقق من تغطية بيانات اعتماد SecretRef - - تدقيق ما إذا كانت بيانات اعتماد مؤهلة لـ `secrets configure` أو `secrets apply` - - التحقق من سبب كون بيانات اعتماد خارج السطح المدعوم -summary: السطح القياسي المعتمد وغير المعتمد لبيانات اعتماد SecretRef -title: سطح بيانات اعتماد SecretRef + - التحقق من تغطية اعتمادات SecretRef + - تدقيق ما إذا كان الاعتماد مؤهلًا لـ `secrets configure` أو `secrets apply` + - التحقق من سبب كون الاعتماد خارج السطح المدعوم +summary: السطح المعياري المدعوم وغير المدعوم لاعتمادات SecretRef +title: سطح اعتماد SecretRef x-i18n: - generated_at: "2026-04-07T07:21:48Z" + generated_at: "2026-04-15T07:18:19Z" model: gpt-5.4 provider: openai - source_hash: 211f4b504c5808f7790683066fc2c8b700c705c598f220a264daf971b81cc593 + source_hash: dd0b9c379236b17a72f552d6360b8b5a2269009e019c138c6bb50f4f7328ddaf source_path: reference/secretref-credential-surface.md workflow: 15 --- -# سطح بيانات اعتماد SecretRef +# سطح اعتماد SecretRef -تحدد هذه الصفحة السطح القياسي لبيانات اعتماد SecretRef. +تحدد هذه الصفحة السطح المعياري لاعتمادات SecretRef. -الغرض من النطاق: +مقصود النطاق: -- ضمن النطاق: بيانات الاعتماد التي يزوّدها المستخدم مباشرةً والتي لا يقوم OpenClaw بإصدارها أو تدويرها. -- خارج النطاق: بيانات الاعتماد التي تُصدر أثناء التشغيل أو التي تتناوب، ومواد تحديث OAuth، والعناصر الشبيهة بالجلسات. +- ضمن النطاق: الاعتمادات التي يزوّدها المستخدم مباشرةً ولا يقوم OpenClaw بإصدارها أو تدويرها. +- خارج النطاق: الاعتمادات التي تُصدر في وقت التشغيل أو التي يتم تدويرها، ومواد تحديث OAuth، والعناصر الشبيهة بالجلسات. -## بيانات الاعتماد المدعومة +## الاعتمادات المدعومة ### أهداف `openclaw.json` (`secrets configure` + `secrets apply` + `secrets audit`) @@ -49,6 +49,7 @@ x-i18n: - `messages.tts.providers.*.apiKey` - `tools.web.fetch.firecrawl.apiKey` - `plugins.entries.brave.config.webSearch.apiKey` +- `plugins.entries.exa.config.webSearch.apiKey` - `plugins.entries.google.config.webSearch.apiKey` - `plugins.entries.xai.config.webSearch.apiKey` - `plugins.entries.moonshot.config.webSearch.apiKey` @@ -107,33 +108,33 @@ x-i18n: - `channels.zalo.webhookSecret` - `channels.zalo.accounts.*.botToken` - `channels.zalo.accounts.*.webhookSecret` -- `channels.googlechat.serviceAccount` عبر النظير `serviceAccountRef` (استثناء توافق) -- `channels.googlechat.accounts.*.serviceAccount` عبر النظير `serviceAccountRef` (استثناء توافق) +- `channels.googlechat.serviceAccount` عبر `serviceAccountRef` المجاور (استثناء توافق) +- `channels.googlechat.accounts.*.serviceAccount` عبر `serviceAccountRef` المجاور (استثناء توافق) ### أهداف `auth-profiles.json` (`secrets configure` + `secrets apply` + `secrets audit`) -- `profiles.*.keyRef` (`type: "api_key"`؛ غير مدعوم عندما تكون `auth.profiles..mode = "oauth"`) -- `profiles.*.tokenRef` (`type: "token"`؛ غير مدعوم عندما تكون `auth.profiles..mode = "oauth"`) +- `profiles.*.keyRef` (`type: "api_key"`؛ غير مدعوم عندما يكون `auth.profiles..mode = "oauth"`) +- `profiles.*.tokenRef` (`type: "token"`؛ غير مدعوم عندما يكون `auth.profiles..mode = "oauth"`) [//]: # "secretref-supported-list-end" ملاحظات: -- تتطلب أهداف خطة ملف تعريف المصادقة `agentId`. -- تستهدف إدخالات الخطة `profiles.*.key` / `profiles.*.token` وتكتب المراجع النظيرة (`keyRef` / `tokenRef`). -- تُدرج مراجع ملفات تعريف المصادقة في تحليل وقت التشغيل وتغطية التدقيق. -- حاجز سياسة OAuth: لا يمكن دمج `auth.profiles..mode = "oauth"` مع مدخلات SecretRef لذلك الملف التعريفي. يفشل بدء التشغيل/إعادة التحميل وتحليل ملف تعريف المصادقة بسرعة عند انتهاك هذه السياسة. -- بالنسبة إلى موفري النماذج المُدارين عبر SecretRef، تستمر إدخالات `agents/*/agent/models.json` المُنشأة في حفظ علامات غير سرية (وليس القيم السرية المحلَّلة) لأسطح `apiKey`/الترويسات. -- حفظ العلامات ذو مصدر موثوق: يكتب OpenClaw العلامات من لقطة تهيئة المصدر النشطة (قبل التحليل)، وليس من القيم السرية المحلَّلة وقت التشغيل. +- تتطلب أهداف خطة ملف التعريف الخاص بالمصادقة `agentId`. +- تستهدف إدخالات الخطة `profiles.*.key` / `profiles.*.token` وتكتب المراجع المجاورة (`keyRef` / `tokenRef`). +- يتم تضمين مراجع ملف التعريف الخاص بالمصادقة في دقة وقت التشغيل وتغطية التدقيق. +- حاجز سياسة OAuth: لا يمكن دمج `auth.profiles..mode = "oauth"` مع مدخلات SecretRef لهذا الملف التعريفي. يفشل بدء التشغيل/إعادة التحميل ودقة ملف التعريف الخاص بالمصادقة بسرعة عند انتهاك هذه السياسة. +- بالنسبة إلى موفري النماذج المُدارين بواسطة SecretRef، تحتفظ الإدخالات المُولَّدة في `agents/*/agent/models.json` بمؤشرات غير سرية (وليس القيم السرية التي تم حلها) لأسطح `apiKey`/الرؤوس. +- استمرار المؤشرات يعتمد على المصدر بشكل موثوق: يكتب OpenClaw المؤشرات من لقطة إعدادات المصدر النشطة (قبل الحل)، وليس من قيم الأسرار المحلولة في وقت التشغيل. - بالنسبة إلى البحث على الويب: - - في وضع الموفّر الصريح (مع تعيين `tools.web.search.provider`)، يكون مفتاح الموفّر المحدد فقط نشطًا. - - في الوضع التلقائي (عندما لا يكون `tools.web.search.provider` معيّنًا)، يكون مفتاح الموفّر الأول فقط الذي يُحل وفق الأسبقية نشطًا. + - في وضع الموفّر الصريح (عند تعيين `tools.web.search.provider`) يكون مفتاح الموفّر المحدد فقط نشطًا. + - في الوضع التلقائي (عند عدم تعيين `tools.web.search.provider`) يكون مفتاح الموفّر الأول الذي يتم حله حسب الأسبقية فقط هو النشط. - في الوضع التلقائي، تُعامل مراجع الموفّرين غير المحددين على أنها غير نشطة حتى يتم تحديدها. - - ما تزال مسارات الموفّر القديمة `tools.web.search.*` تُحل خلال نافذة التوافق، لكن السطح القياسي لـ SecretRef هو `plugins.entries..config.webSearch.*`. + - لا تزال مسارات الموفّر القديمة `tools.web.search.*` تُحل خلال نافذة التوافق، لكن سطح SecretRef المعياري هو `plugins.entries..config.webSearch.*`. -## بيانات الاعتماد غير المدعومة +## الاعتمادات غير المدعومة -تشمل بيانات الاعتماد الخارجة عن النطاق ما يلي: +تشمل الاعتمادات خارج النطاق ما يلي: [//]: # "secretref-unsupported-list-start" @@ -149,6 +150,6 @@ x-i18n: [//]: # "secretref-unsupported-list-end" -المبررات: +المبرر: -- تُصدر هذه البيانات الاعتمادية، أو تُدوَّر، أو تحمل جلسات، أو تنتمي إلى فئات OAuth دائمة لا تتوافق مع تحليل SecretRef الخارجي للقراءة فقط. +- هذه الاعتمادات مُصدَرة، أو مُدوَّرة، أو مرتبطة بالجلسات، أو من فئات OAuth دائمة لا تتوافق مع حل SecretRef الخارجي للقراءة فقط. diff --git a/docs/ar/start/showcase.md b/docs/ar/start/showcase.md index bc640ec0c..7cbb60491 100644 --- a/docs/ar/start/showcase.md +++ b/docs/ar/start/showcase.md @@ -1,133 +1,160 @@ --- +description: Real-world OpenClaw projects from the community read_when: - - تبحث عن أمثلة حقيقية لاستخدام OpenClaw - - تقوم بتحديث أبرز مشروعات المجتمع -summary: مشروعات وتكاملات من بناء المجتمع تعمل بواسطة OpenClaw -title: واجهة العرض + - أبحث عن أمثلة حقيقية على استخدام OpenClaw + - تحديث أبرز مشاريع المجتمع +summary: مشاريع وتكاملات أنشأها المجتمع ومدعومة بواسطة OpenClaw +title: العرض x-i18n: - generated_at: "2026-04-05T12:57:37Z" + generated_at: "2026-04-15T07:18:25Z" model: gpt-5.4 provider: openai - source_hash: 2917e9a476ef527ddb3e51c610bbafbd145e705c9cc29f191639fb63d238ef70 + source_hash: 797d0b85c9eca920240c79d870eb9636216714f3eba871c5ebd0f7f40cf7bbf1 source_path: start/showcase.md workflow: 15 --- -# واجهة العرض + -مشروعات حقيقية من المجتمع. تعرّف على ما يبنيه الناس باستخدام OpenClaw. +# العرض + +
+

مبني داخل الدردشات، والمحطات الطرفية، والمتصفحات، وغرف المعيشة

+

+ مشاريع OpenClaw ليست عروضًا تجريبية بسيطة. الناس يطلقون حلقات مراجعة PR، وتطبيقات جوال، وأتمتة منزلية، + وأنظمة صوتية، وأدوات تطوير، وسير عمل كثيف الذاكرة من القنوات التي يستخدمونها بالفعل. +

+ +
+
+ بناءات أصلية للدردشة + Telegram وWhatsApp وDiscord وBeeper ودردشة الويب وسير العمل المعتمد على الطرفية أولًا. +
+
+ أتمتة حقيقية + الحجز، والتسوق، والدعم، وإعداد التقارير، والتحكم في المتصفح دون انتظار واجهة API. +
+
+ العالم المحلي والمادي + الطابعات، والمكانس، والكاميرات، والبيانات الصحية، والأنظمة المنزلية، وقواعد المعرفة الشخصية. +
+
+
-**هل تريد أن يظهر مشروعك هنا؟** شارك مشروعك في [#self-promotion on Discord](https://discord.gg/clawd) أو [ضع إشارة @openclaw على X](https://x.com/openclaw). +**هل تريد أن يظهر مشروعك هنا؟** شارك مشروعك في [#self-promotion on Discord](https://discord.gg/clawd) أو [ضع إشارة إلى @openclaw على X](https://x.com/openclaw). -## 🎥 OpenClaw أثناء العمل - -شرح كامل للإعداد (28 دقيقة) من VelvetShark. - -
-