chore(i18n): refresh ar translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
45fbe3855b
commit
5a0a31a59f
@ -1,40 +1,33 @@
|
||||
---
|
||||
read_when:
|
||||
- تحتاج إلى شرح مساحة عمل الوكيل أو بنية ملفاتها
|
||||
- تريد نسخ مساحة عمل الوكيل احتياطيًا أو ترحيلها
|
||||
summary: 'مساحة عمل الوكيل: الموقع، والبنية، واستراتيجية النسخ الاحتياطي'
|
||||
- تحتاج إلى شرح مساحة عمل الوكيل أو تخطيط ملفاته
|
||||
- تريد إجراء نسخة احتياطية أو ترحيل مساحة عمل وكيل
|
||||
summary: 'مساحة عمل الوكيل: الموقع، التخطيط، واستراتيجية النسخ الاحتياطي'
|
||||
title: مساحة عمل الوكيل
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T12:40:04Z"
|
||||
generated_at: "2026-04-18T07:14:51Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3735633f1098c733415369f9836fdbbc0bf869636a24ed42e95e6784610d964a
|
||||
source_hash: dd2e74614d8d45df04b1bbda48e2224e778b621803d774d38e4b544195eb234e
|
||||
source_path: concepts/agent-workspace.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# مساحة عمل الوكيل
|
||||
|
||||
مساحة العمل هي موطن الوكيل. وهي دليل العمل الوحيد المستخدم لأدوات
|
||||
الملفات ولسياق مساحة العمل. حافظ على خصوصيتها وتعامل معها على أنها ذاكرة.
|
||||
مساحة العمل هي منزل الوكيل. وهي دليل العمل الوحيد المستخدم لأدوات الملفات ولسياق مساحة العمل. أبقها خاصة وتعامل معها على أنها ذاكرة.
|
||||
|
||||
وهذا منفصل عن `~/.openclaw/`، الذي يخزّن التكوين وبيانات الاعتماد
|
||||
والجلسات.
|
||||
وهذا منفصل عن `~/.openclaw/`، الذي يخزن الإعدادات وبيانات الاعتماد والجلسات.
|
||||
|
||||
**مهم:** مساحة العمل هي **الدليل الحالي الافتراضي**، وليست sandbox صارمة. تقوم
|
||||
الأدوات بحل المسارات النسبية اعتمادًا على مساحة العمل، لكن لا تزال المسارات المطلقة
|
||||
قادرة على الوصول إلى أماكن أخرى على المضيف ما لم يتم تمكين sandboxing. إذا كنت
|
||||
تحتاج إلى العزل، فاستخدم
|
||||
[`agents.defaults.sandbox`](/gateway/sandboxing) (و/أو تكوين sandbox لكل وكيل).
|
||||
عند تمكين sandboxing وعندما لا تكون `workspaceAccess` مساوية لـ `"rw"`، تعمل الأدوات
|
||||
داخل مساحة عمل sandbox ضمن `~/.openclaw/sandboxes`، وليس داخل مساحة عمل المضيف.
|
||||
**مهم:** مساحة العمل هي **cwd الافتراضي**، وليست صندوق عزل صارمًا. تحل الأدوات المسارات النسبية نسبةً إلى مساحة العمل، لكن لا يزال بإمكان المسارات المطلقة الوصول إلى أماكن أخرى على المضيف ما لم يكن العزل مفعّلًا. إذا كنت بحاجة إلى العزل، فاستخدم [`agents.defaults.sandbox`](/ar/gateway/sandboxing) (و/أو إعدادات العزل لكل وكيل على حدة).
|
||||
عند تفعيل العزل وعدم ضبط `workspaceAccess` على `"rw"`، تعمل الأدوات داخل مساحة عمل معزولة تحت `~/.openclaw/sandboxes` بدلًا من مساحة العمل على المضيف.
|
||||
|
||||
## الموقع الافتراضي
|
||||
|
||||
- الافتراضي: `~/.openclaw/workspace`
|
||||
- إذا تم ضبط `OPENCLAW_PROFILE` ولم تكن قيمته `"default"`، يصبح الافتراضي
|
||||
- إذا كان `OPENCLAW_PROFILE` مضبوطًا ولم يكن `"default"`، يصبح الافتراضي
|
||||
`~/.openclaw/workspace-<profile>`.
|
||||
- يمكنك التجاوز في `~/.openclaw/openclaw.json`:
|
||||
- تجاوز الإعداد في `~/.openclaw/openclaw.json`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -45,12 +38,12 @@ x-i18n:
|
||||
```
|
||||
|
||||
سيقوم `openclaw onboard` أو `openclaw configure` أو `openclaw setup` بإنشاء
|
||||
مساحة العمل وتهيئة ملفات bootstrap إذا كانت مفقودة.
|
||||
لا تقبل نسخ seed الخاصة بـ sandbox إلا الملفات العادية داخل مساحة العمل؛ ويتم تجاهل
|
||||
الأسماء البديلة من symlink/hardlink التي تُحل خارج مساحة العمل المصدر.
|
||||
مساحة العمل وإضافة ملفات التهيئة الأولية إذا كانت مفقودة.
|
||||
تقبل نسخ البذور المعزولة فقط الملفات العادية داخل مساحة العمل؛ أما الأسماء
|
||||
المستعارة من symlink/hardlink التي تُحل خارج مساحة العمل المصدر فيتم تجاهلها.
|
||||
|
||||
إذا كنت تدير ملفات مساحة العمل بنفسك بالفعل، فيمكنك تعطيل إنشاء
|
||||
ملفات bootstrap:
|
||||
إذا كنت تدير ملفات مساحة العمل بنفسك بالفعل، فيمكنك تعطيل إنشاء ملفات
|
||||
التهيئة الأولية:
|
||||
|
||||
```json5
|
||||
{ agent: { skipBootstrap: true } }
|
||||
@ -58,30 +51,30 @@ x-i18n:
|
||||
|
||||
## مجلدات مساحة العمل الإضافية
|
||||
|
||||
قد تكون عمليات التثبيت الأقدم قد أنشأت `~/openclaw`. وقد يؤدي الاحتفاظ بعدة
|
||||
أدلة لمساحة العمل إلى حدوث انحرافات مربكة في المصادقة أو الحالة، لأن
|
||||
مساحة عمل واحدة فقط تكون نشطة في كل مرة.
|
||||
قد تكون الإصدارات الأقدم قد أنشأت `~/openclaw`. إن الاحتفاظ بعدة أدلة لمساحة
|
||||
العمل يمكن أن يسبب التباسًا في المصادقة أو انجرافًا في الحالة، لأن مساحة عمل
|
||||
واحدة فقط تكون نشطة في كل مرة.
|
||||
|
||||
**التوصية:** احتفظ بمساحة عمل نشطة واحدة. وإذا لم تعد تستخدم
|
||||
المجلدات الإضافية، فأرشفها أو انقلها إلى سلة المهملات (مثل `trash ~/openclaw`).
|
||||
**التوصية:** احتفظ بمساحة عمل نشطة واحدة. إذا لم تعد تستخدم المجلدات
|
||||
الإضافية، فقم بأرشفتها أو نقلها إلى سلة المهملات (مثلًا `trash ~/openclaw`).
|
||||
إذا كنت تحتفظ عمدًا بعدة مساحات عمل، فتأكد من أن
|
||||
`agents.defaults.workspace` يشير إلى النشطة منها.
|
||||
`agents.defaults.workspace` يشير إلى المساحة النشطة.
|
||||
|
||||
يعرض `openclaw doctor` تحذيرًا عندما يكتشف أدلة إضافية لمساحة العمل.
|
||||
يحذّر `openclaw doctor` عند اكتشافه أدلة إضافية لمساحة العمل.
|
||||
|
||||
## خريطة ملفات مساحة العمل (ما الذي يعنيه كل ملف)
|
||||
## خريطة ملفات مساحة العمل (ماذا يعني كل ملف)
|
||||
|
||||
هذه هي الملفات القياسية التي يتوقعها OpenClaw داخل مساحة العمل:
|
||||
هذه هي الملفات القياسية التي يتوقع OpenClaw وجودها داخل مساحة العمل:
|
||||
|
||||
- `AGENTS.md`
|
||||
- تعليمات تشغيلية للوكيل وكيفية استخدامه للذاكرة.
|
||||
- تعليمات التشغيل الخاصة بالوكيل وكيفية استخدامه للذاكرة.
|
||||
- يُحمَّل في بداية كل جلسة.
|
||||
- مكان مناسب للقواعد والأولويات وتفاصيل "كيفية التصرف".
|
||||
|
||||
- `SOUL.md`
|
||||
- الشخصية، والنبرة، والحدود.
|
||||
- الشخصية والنبرة والحدود.
|
||||
- يُحمَّل في كل جلسة.
|
||||
- الدليل: [دليل شخصية SOUL.md](/concepts/soul)
|
||||
- الدليل: [دليل شخصية SOUL.md](/ar/concepts/soul)
|
||||
|
||||
- `USER.md`
|
||||
- من هو المستخدم وكيفية مخاطبته.
|
||||
@ -89,75 +82,74 @@ x-i18n:
|
||||
|
||||
- `IDENTITY.md`
|
||||
- اسم الوكيل وطابعه وemoji الخاص به.
|
||||
- يُنشأ/يُحدَّث أثناء طقس bootstrap.
|
||||
- يُنشأ/يُحدَّث أثناء طقس التهيئة الأولية.
|
||||
|
||||
- `TOOLS.md`
|
||||
- ملاحظات حول أدواتك المحلية والاصطلاحات الخاصة بك.
|
||||
- لا يتحكم في توفر الأدوات؛ فهو مجرد إرشاد.
|
||||
- ملاحظات حول أدواتك المحلية وأعرافك.
|
||||
- لا يتحكم في توفر الأدوات؛ بل هو مجرد إرشادات.
|
||||
|
||||
- `HEARTBEAT.md`
|
||||
- قائمة تحقق صغيرة اختيارية لتشغيلات heartbeat.
|
||||
- اجعله قصيرًا لتجنب استهلاك token.
|
||||
- قائمة تحقق صغيرة اختيارية لتشغيلات Heartbeat.
|
||||
- أبقه قصيرًا لتجنب استهلاك التوكنات.
|
||||
|
||||
- `BOOT.md`
|
||||
- قائمة تحقق اختيارية عند بدء التشغيل تُنفذ عند إعادة تشغيل البوابة عندما تكون hooks الداخلية مفعلة.
|
||||
- اجعلها قصيرة؛ واستخدم أداة الرسائل للإرسال الصادر.
|
||||
- قائمة تحقق اختيارية عند بدء التشغيل تُنفذ عند إعادة تشغيل Gateway عندما تكون الخطافات الداخلية مفعلة.
|
||||
- أبقها قصيرة؛ واستخدم أداة الرسائل للإرسال إلى الخارج.
|
||||
|
||||
- `BOOTSTRAP.md`
|
||||
- طقس تشغيل أولي لمرة واحدة.
|
||||
- لا يُنشأ إلا لمساحة عمل جديدة تمامًا.
|
||||
- طقس أول تشغيل يُنفذ مرة واحدة.
|
||||
- يُنشأ فقط لمساحة عمل جديدة تمامًا.
|
||||
- احذفه بعد اكتمال الطقس.
|
||||
|
||||
- `memory/YYYY-MM-DD.md`
|
||||
- سجل ذاكرة يومي (ملف واحد لكل يوم).
|
||||
- سجل الذاكرة اليومي (ملف واحد لكل يوم).
|
||||
- يُنصح بقراءة ملف اليوم + الأمس عند بدء الجلسة.
|
||||
|
||||
- `MEMORY.md` (اختياري)
|
||||
- ذاكرة طويلة المدى منسقة.
|
||||
- لا تُحمَّل إلا في الجلسة الرئيسية الخاصة (وليس في السياقات المشتركة/الجماعية).
|
||||
- ذاكرة طويلة الأمد منسقة.
|
||||
- لا يُحمَّل إلا في الجلسة الرئيسية الخاصة (وليس في السياقات المشتركة/الجماعية).
|
||||
|
||||
راجع [الذاكرة](/concepts/memory) لمعرفة سير العمل والتفريغ التلقائي للذاكرة.
|
||||
راجع [الذاكرة](/ar/concepts/memory) للاطلاع على سير العمل والتفريغ التلقائي للذاكرة.
|
||||
|
||||
- `skills/` (اختياري)
|
||||
- Skills خاصة بمساحة العمل.
|
||||
- موقع Skills الأعلى أولوية لتلك المساحة.
|
||||
- يتجاوز Skills وكيل المشروع، وSkills الوكيل الشخصية، وSkills المُدارة، وSkills المضمنة، و`skills.load.extraDirs` عند تعارض الأسماء.
|
||||
- يتجاوز Skills وكلاء المشروع، وSkills الوكيل الشخصية، وSkills المُدارة، وSkills المضمّنة، و`skills.load.extraDirs` عند تعارض الأسماء.
|
||||
|
||||
- `canvas/` (اختياري)
|
||||
- ملفات واجهة Canvas لعرض العُقد (مثل `canvas/index.html`).
|
||||
- ملفات واجهة Canvas لعرض Node (مثل `canvas/index.html`).
|
||||
|
||||
إذا كان أي ملف bootstrap مفقودًا، فسيحقن OpenClaw علامة "ملف مفقود" داخل
|
||||
الجلسة ويتابع العمل. وتُقتطع ملفات bootstrap الكبيرة عند حقنها؛ ويمكنك
|
||||
تعديل الحدود باستخدام `agents.defaults.bootstrapMaxChars` (الافتراضي: 20000) و
|
||||
`agents.defaults.bootstrapTotalMaxChars` (الافتراضي: 150000).
|
||||
يمكن لـ `openclaw setup` إعادة إنشاء الإعدادات الافتراضية المفقودة من دون الكتابة فوق
|
||||
إذا كان أي ملف من ملفات التهيئة الأولية مفقودًا، يضيف OpenClaw علامة "ملف مفقود"
|
||||
إلى الجلسة ويتابع التشغيل. يتم اقتطاع ملفات التهيئة الأولية الكبيرة عند إدراجها؛
|
||||
اضبط الحدود باستخدام `agents.defaults.bootstrapMaxChars` (الافتراضي: 12000) و
|
||||
`agents.defaults.bootstrapTotalMaxChars` (الافتراضي: 60000).
|
||||
يمكن لـ `openclaw setup` إعادة إنشاء الإعدادات الافتراضية المفقودة دون الكتابة فوق
|
||||
الملفات الموجودة.
|
||||
|
||||
## ما الذي لا يوجد في مساحة العمل
|
||||
## ما الذي **ليس** داخل مساحة العمل
|
||||
|
||||
توجد هذه العناصر ضمن `~/.openclaw/` ويجب **عدم** الالتزام بها في مستودع مساحة العمل:
|
||||
توجد هذه العناصر تحت `~/.openclaw/` ويجب **عدم** الالتزام بها داخل مستودع مساحة العمل:
|
||||
|
||||
- `~/.openclaw/openclaw.json` (التكوين)
|
||||
- `~/.openclaw/openclaw.json` (الإعدادات)
|
||||
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (ملفات تعريف مصادقة النماذج: OAuth + مفاتيح API)
|
||||
- `~/.openclaw/credentials/` (حالة القنوات/المزوّدين بالإضافة إلى بيانات استيراد OAuth القديمة)
|
||||
- `~/.openclaw/agents/<agentId>/sessions/` (نصوص الجلسات + البيانات الوصفية)
|
||||
- `~/.openclaw/skills/` (Skills مُدارة)
|
||||
- `~/.openclaw/credentials/` (حالة القناة/المزوّد بالإضافة إلى بيانات استيراد OAuth القديمة)
|
||||
- `~/.openclaw/agents/<agentId>/sessions/` (سجلات الجلسات + البيانات الوصفية)
|
||||
- `~/.openclaw/skills/` (Skills المُدارة)
|
||||
|
||||
إذا كنت تحتاج إلى ترحيل الجلسات أو التكوين، فانسخها بشكل منفصل وأبقها
|
||||
خارج version control.
|
||||
إذا كنت بحاجة إلى ترحيل الجلسات أو الإعدادات، فانسخها بشكل منفصل وأبقها
|
||||
خارج التحكم بالإصدارات.
|
||||
|
||||
## النسخ الاحتياطي باستخدام Git (موصى به، خاص)
|
||||
## النسخ الاحتياطي عبر Git (موصى به، خاص)
|
||||
|
||||
تعامل مع مساحة العمل على أنها ذاكرة خاصة. ضعها في مستودع git **خاص**
|
||||
حتى تكون منسوخة احتياطيًا وقابلة للاستعادة.
|
||||
تعامل مع مساحة العمل على أنها ذاكرة خاصة. ضعها في مستودع git **خاص** بحيث
|
||||
تكون محفوظة احتياطيًا وقابلة للاسترجاع.
|
||||
|
||||
نفّذ هذه الخطوات على الجهاز الذي تعمل عليه البوابة (فهناك توجد
|
||||
مساحة العمل).
|
||||
نفّذ هذه الخطوات على الجهاز الذي يعمل عليه Gateway (فهناك توجد مساحة العمل).
|
||||
|
||||
### 1) تهيئة المستودع
|
||||
|
||||
إذا كان git مثبتًا، فستتم تهيئة مساحات العمل الجديدة تمامًا تلقائيًا. وإذا لم تكن
|
||||
مساحة العمل هذه مستودعًا بالفعل، فشغّل:
|
||||
إذا كان git مثبتًا، فستُهيَّأ مساحات العمل الجديدة تلقائيًا. إذا لم تكن مساحة
|
||||
العمل هذه مستودعًا بالفعل، فشغّل:
|
||||
|
||||
```bash
|
||||
cd ~/.openclaw/workspace
|
||||
@ -166,14 +158,14 @@ git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
|
||||
git commit -m "Add agent workspace"
|
||||
```
|
||||
|
||||
### 2) أضف remote خاصًا (خيارات مناسبة للمبتدئين)
|
||||
### 2) إضافة remote خاص (خيارات سهلة للمبتدئين)
|
||||
|
||||
الخيار A: واجهة GitHub على الويب
|
||||
|
||||
1. أنشئ مستودعًا جديدًا **خاصًا** على GitHub.
|
||||
2. لا تهيّئه بملف README (لتجنب تعارضات الدمج).
|
||||
3. انسخ عنوان remote بنمط HTTPS.
|
||||
4. أضف remote وادفع التغييرات:
|
||||
1. أنشئ مستودعًا **خاصًا** جديدًا على GitHub.
|
||||
2. لا تهيئه بملف README (لتجنب تعارضات الدمج).
|
||||
3. انسخ عنوان remote بصيغة HTTPS.
|
||||
4. أضف remote وادفع:
|
||||
|
||||
```bash
|
||||
git branch -M main
|
||||
@ -190,10 +182,10 @@ gh repo create openclaw-workspace --private --source . --remote origin --push
|
||||
|
||||
الخيار C: واجهة GitLab على الويب
|
||||
|
||||
1. أنشئ مستودعًا جديدًا **خاصًا** على GitLab.
|
||||
2. لا تهيّئه بملف README (لتجنب تعارضات الدمج).
|
||||
3. انسخ عنوان remote بنمط HTTPS.
|
||||
4. أضف remote وادفع التغييرات:
|
||||
1. أنشئ مستودعًا **خاصًا** جديدًا على GitLab.
|
||||
2. لا تهيئه بملف README (لتجنب تعارضات الدمج).
|
||||
3. انسخ عنوان remote بصيغة HTTPS.
|
||||
4. أضف remote وادفع:
|
||||
|
||||
```bash
|
||||
git branch -M main
|
||||
@ -212,16 +204,16 @@ git push
|
||||
|
||||
## لا تلتزم بالأسرار
|
||||
|
||||
حتى في المستودع الخاص، تجنب تخزين الأسرار في مساحة العمل:
|
||||
حتى داخل مستودع خاص، تجنب تخزين الأسرار في مساحة العمل:
|
||||
|
||||
- مفاتيح API أو OAuth tokens أو كلمات المرور أو بيانات الاعتماد الخاصة.
|
||||
- أي شيء ضمن `~/.openclaw/`.
|
||||
- عمليات تفريغ خام للدردشات أو المرفقات الحساسة.
|
||||
- مفاتيح API أو رموز OAuth أو كلمات المرور أو بيانات الاعتماد الخاصة.
|
||||
- أي شيء تحت `~/.openclaw/`.
|
||||
- تفريغات خام للمحادثات أو المرفقات الحساسة.
|
||||
|
||||
إذا اضطررت إلى تخزين مراجع حساسة، فاستخدم عناصر نائبة واحتفظ بالسر
|
||||
الحقيقي في مكان آخر (مدير كلمات المرور، أو متغيرات البيئة، أو `~/.openclaw/`).
|
||||
إذا اضطررت إلى تخزين مراجع حساسة، فاستخدم عناصر نائبة واحتفظ بالسر الحقيقي
|
||||
في مكان آخر (مدير كلمات مرور، أو متغيرات البيئة، أو `~/.openclaw/`).
|
||||
|
||||
بداية مقترحة لملف `.gitignore`:
|
||||
ملف `.gitignore` مقترح للبدء:
|
||||
|
||||
```gitignore
|
||||
.DS_Store
|
||||
@ -235,20 +227,20 @@ git push
|
||||
|
||||
1. انسخ المستودع إلى المسار المطلوب (الافتراضي `~/.openclaw/workspace`).
|
||||
2. اضبط `agents.defaults.workspace` على ذلك المسار في `~/.openclaw/openclaw.json`.
|
||||
3. شغّل `openclaw setup --workspace <path>` لتهيئة أي ملفات مفقودة.
|
||||
4. إذا كنت تحتاج إلى الجلسات، فانقل `~/.openclaw/agents/<agentId>/sessions/` من
|
||||
3. شغّل `openclaw setup --workspace <path>` لإضافة أي ملفات مفقودة.
|
||||
4. إذا كنت بحاجة إلى الجلسات، فانقل `~/.openclaw/agents/<agentId>/sessions/` من
|
||||
الجهاز القديم بشكل منفصل.
|
||||
|
||||
## ملاحظات متقدمة
|
||||
|
||||
- يمكن أن يستخدم التوجيه متعدد الوكلاء مساحات عمل مختلفة لكل وكيل. راجع
|
||||
[توجيه القنوات](/channels/channel-routing) لمعرفة تكوين التوجيه.
|
||||
- إذا كان `agents.defaults.sandbox` مفعّلًا، فيمكن للجلسات غير الرئيسية استخدام
|
||||
مساحات عمل sandbox لكل جلسة ضمن `agents.defaults.sandbox.workspaceRoot`.
|
||||
- يمكن للتوجيه متعدد الوكلاء استخدام مساحات عمل مختلفة لكل وكيل. راجع
|
||||
[توجيه القنوات](/ar/channels/channel-routing) للحصول على إعدادات التوجيه.
|
||||
- إذا كان `agents.defaults.sandbox` مفعّلًا، فقد تستخدم الجلسات غير الرئيسية
|
||||
مساحات عمل معزولة لكل جلسة تحت `agents.defaults.sandbox.workspaceRoot`.
|
||||
|
||||
## ذو صلة
|
||||
|
||||
- [الأوامر الدائمة](/automation/standing-orders) — تعليمات مستمرة في ملفات مساحة العمل
|
||||
- [Heartbeat](/gateway/heartbeat) — ملف مساحة العمل HEARTBEAT.md
|
||||
- [الجلسة](/concepts/session) — مسارات تخزين الجلسات
|
||||
- [Sandboxing](/gateway/sandboxing) — وصول مساحة العمل في البيئات المعزولة
|
||||
- [الأوامر الدائمة](/ar/automation/standing-orders) — تعليمات دائمة في ملفات مساحة العمل
|
||||
- [Heartbeat](/ar/gateway/heartbeat) — ملف مساحة العمل HEARTBEAT.md
|
||||
- [الجلسة](/ar/concepts/session) — مسارات تخزين الجلسات
|
||||
- [العزل](/ar/gateway/sandboxing) — الوصول إلى مساحة العمل في البيئات المعزولة
|
||||
|
||||
@ -1,115 +1,115 @@
|
||||
---
|
||||
read_when:
|
||||
- تريد فهم ما الذي يعنيه "السياق" في OpenClaw
|
||||
- أنت تستكشف سبب "معرفة" النموذج لشيء ما (أو سبب نسيانه له)
|
||||
- تريد تقليل حمل السياق (/context، /status، /compact)
|
||||
summary: 'السياق: ما الذي يراه النموذج، وكيفية بنائه، وكيفية فحصه'
|
||||
- تريد أن تفهم ما الذي يعنيه «السياق» في OpenClaw
|
||||
- أنت تصحّح سبب «معرفة» النموذج لشيء ما (أو سبب نسيانه)
|
||||
- تريد تقليل الحمل الزائد للسياق (`/context`، `/status`، `/compact`)
|
||||
summary: 'السياق: ما يراه النموذج، وكيفية بنائه، وكيفية فحصه'
|
||||
title: السياق
|
||||
x-i18n:
|
||||
generated_at: "2026-04-12T23:28:02Z"
|
||||
generated_at: "2026-04-18T07:14:54Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3620db1a8c1956d91a01328966df491388d3a32c4003dc4447197eb34316c77d
|
||||
source_hash: 477ccb1d9654968d0e904b6846b32b8c14db6b6c0d3d2ec2b7409639175629f9
|
||||
source_path: concepts/context.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# السياق
|
||||
|
||||
"السياق" هو **كل ما يرسله OpenClaw إلى النموذج أثناء التشغيل**. وهو مقيّد بـ **نافذة السياق** الخاصة بالنموذج (حد الرموز).
|
||||
«السياق» هو **كل ما يرسله OpenClaw إلى النموذج أثناء التشغيل**. وهو مقيّد بـ **نافذة السياق** الخاصة بالنموذج (حد الرموز).
|
||||
|
||||
نموذج ذهني للمبتدئين:
|
||||
نموذج ذهني مبسّط للمبتدئين:
|
||||
|
||||
- **موجّه النظام** (يبنيه OpenClaw): القواعد، والأدوات، وقائمة Skills، والوقت/بيئة التشغيل، وملفات مساحة العمل المحقونة.
|
||||
- **توجيه النظام** (يبنيه OpenClaw): القواعد، والأدوات، وقائمة Skills، والوقت/بيئة التشغيل، وملفات مساحة العمل المُدرجة.
|
||||
- **سجل المحادثة**: رسائلك + رسائل المساعد في هذه الجلسة.
|
||||
- **استدعاءات/نتائج الأدوات + المرفقات**: مخرجات الأوامر، وقراءات الملفات، والصور/الصوت، وغير ذلك.
|
||||
- **استدعاءات الأدوات/نتائجها + المرفقات**: مخرجات الأوامر، وقراءات الملفات، والصور/الصوت، وغير ذلك.
|
||||
|
||||
السياق _ليس هو نفسه_ "الذاكرة": يمكن تخزين الذاكرة على القرص وإعادة تحميلها لاحقًا؛ أما السياق فهو ما يوجد داخل نافذة النموذج الحالية.
|
||||
السياق _ليس الشيء نفسه_ الذي تعنيه «الذاكرة»: يمكن تخزين الذاكرة على القرص وإعادة تحميلها لاحقًا؛ أما السياق فهو ما يوجد داخل نافذة النموذج الحالية.
|
||||
|
||||
## بدء سريع (فحص السياق)
|
||||
## بداية سريعة (فحص السياق)
|
||||
|
||||
- `/status` → عرض سريع لـ "ما مدى امتلاء نافذتي؟" + إعدادات الجلسة.
|
||||
- `/context list` → ما الذي تم حقنه + أحجام تقريبية (لكل ملف + الإجماليات).
|
||||
- `/context detail` → تفصيل أعمق: لكل ملف، وأحجام مخططات كل أداة، وأحجام إدخالات كل Skill، وحجم موجّه النظام.
|
||||
- `/usage tokens` → إلحاق تذييل استخدام لكل رد ضمن الردود العادية.
|
||||
- `/compact` → تلخيص السجل الأقدم إلى إدخال مضغوط لتحرير مساحة في النافذة.
|
||||
- `/status` ← عرض سريع يجيب عن سؤال: «إلى أي مدى امتلأت نافذتي؟» + إعدادات الجلسة.
|
||||
- `/context list` ← ما الذي تم إدراجه + أحجام تقريبية (لكل ملف + الإجماليات).
|
||||
- `/context detail` ← تفصيل أعمق: أحجام كل ملف، وأحجام مخططات كل أداة، وأحجام إدخالات كل Skill، وحجم توجيه النظام.
|
||||
- `/usage tokens` ← يضيف تذييلًا لاستهلاك الرموز لكل رد إلى الردود العادية.
|
||||
- `/compact` ← يلخّص السجل الأقدم في إدخال مضغوط لتفريغ مساحة في النافذة.
|
||||
|
||||
راجع أيضًا: [أوامر الشرطة المائلة](/ar/tools/slash-commands)، [استخدام الرموز والتكاليف](/ar/reference/token-use)، [Compaction](/ar/concepts/compaction).
|
||||
انظر أيضًا: [أوامر الشرطة المائلة](/ar/tools/slash-commands)، [استخدام الرموز والتكاليف](/ar/reference/token-use)، [Compaction](/ar/concepts/compaction).
|
||||
|
||||
## مثال على المخرجات
|
||||
|
||||
تختلف القيم حسب النموذج، والموفّر، وسياسة الأدوات، وما يوجد في مساحة عملك.
|
||||
تختلف القيم حسب النموذج، والمزوّد، وسياسة الأدوات، وما يوجد في مساحة عملك.
|
||||
|
||||
### `/context list`
|
||||
|
||||
```
|
||||
🧠 Context breakdown
|
||||
Workspace: <workspaceDir>
|
||||
Bootstrap max/file: 20,000 chars
|
||||
🧠 تفصيل السياق
|
||||
مساحة العمل: <workspaceDir>
|
||||
الحد الأقصى للتمهيد/لكل ملف: 12,000 حرف
|
||||
Sandbox: mode=non-main sandboxed=false
|
||||
System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok))
|
||||
توجيه النظام (التشغيل): 38,412 حرفًا (~9,603 رموز) (سياق المشروع 23,901 حرفًا (~5,976 رموز))
|
||||
|
||||
Injected workspace files:
|
||||
- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok)
|
||||
- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok)
|
||||
- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok)
|
||||
- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok)
|
||||
- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok)
|
||||
- HEARTBEAT.md: MISSING | raw 0 | injected 0
|
||||
- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok)
|
||||
ملفات مساحة العمل المُدرجة:
|
||||
- AGENTS.md: OK | الخام 1,742 حرفًا (~436 رموز) | المُدرج 1,742 حرفًا (~436 رموز)
|
||||
- SOUL.md: OK | الخام 912 حرفًا (~228 رموز) | المُدرج 912 حرفًا (~228 رموز)
|
||||
- TOOLS.md: TRUNCATED | الخام 54,210 حرفًا (~13,553 رموز) | المُدرج 20,962 حرفًا (~5,241 رموز)
|
||||
- IDENTITY.md: OK | الخام 211 حرفًا (~53 رموز) | المُدرج 211 حرفًا (~53 رموز)
|
||||
- USER.md: OK | الخام 388 حرفًا (~97 رموز) | المُدرج 388 حرفًا (~97 رموز)
|
||||
- HEARTBEAT.md: MISSING | الخام 0 | المُدرج 0
|
||||
- BOOTSTRAP.md: OK | الخام 0 حرفًا (~0 رموز) | المُدرج 0 حرفًا (~0 رموز)
|
||||
|
||||
Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills)
|
||||
Tools: read, edit, write, exec, process, browser, message, sessions_send, …
|
||||
Tool list (system prompt text): 1,032 chars (~258 tok)
|
||||
Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text)
|
||||
Tools: (same as above)
|
||||
قائمة Skills (نص توجيه النظام): 2,184 حرفًا (~546 رموز) (12 Skills)
|
||||
الأدوات: read, edit, write, exec, process, browser, message, sessions_send, …
|
||||
قائمة الأدوات (نص توجيه النظام): 1,032 حرفًا (~258 رموز)
|
||||
مخططات الأدوات (JSON): 31,988 حرفًا (~7,997 رموز) (تُحتسب ضمن السياق؛ لا تُعرض كنص)
|
||||
الأدوات: (كما سبق)
|
||||
|
||||
Session tokens (cached): 14,250 total / ctx=32,000
|
||||
رموز الجلسة (مخزنة مؤقتًا): 14,250 إجمالًا / ctx=32,000
|
||||
```
|
||||
|
||||
### `/context detail`
|
||||
|
||||
```
|
||||
🧠 Context breakdown (detailed)
|
||||
🧠 تفصيل السياق (مفصل)
|
||||
…
|
||||
Top skills (prompt entry size):
|
||||
- frontend-design: 412 chars (~103 tok)
|
||||
- oracle: 401 chars (~101 tok)
|
||||
… (+10 more skills)
|
||||
أكبر Skills (حجم إدخال التوجيه):
|
||||
- frontend-design: 412 حرفًا (~103 رموز)
|
||||
- oracle: 401 حرفًا (~101 رموز)
|
||||
… (+10 أخرى من Skills)
|
||||
|
||||
Top tools (schema size):
|
||||
- browser: 9,812 chars (~2,453 tok)
|
||||
- exec: 6,240 chars (~1,560 tok)
|
||||
… (+N more tools)
|
||||
أكبر الأدوات (حجم المخطط):
|
||||
- browser: 9,812 حرفًا (~2,453 رموز)
|
||||
- exec: 6,240 حرفًا (~1,560 رموز)
|
||||
… (+N أدوات أخرى)
|
||||
```
|
||||
|
||||
## ما الذي يُحتسب ضمن نافذة السياق
|
||||
|
||||
كل ما يستقبله النموذج يُحتسب، بما في ذلك:
|
||||
كل ما يتلقاه النموذج يُحتسب، بما في ذلك:
|
||||
|
||||
- موجّه النظام (جميع الأقسام).
|
||||
- توجيه النظام (كل الأقسام).
|
||||
- سجل المحادثة.
|
||||
- استدعاءات الأدوات + نتائج الأدوات.
|
||||
- المرفقات/التفريغات النصية (الصور/الصوت/الملفات).
|
||||
- ملخصات Compaction وآثار التشذيب.
|
||||
- "الأغلفة" الخاصة بالموفّر أو الرؤوس المخفية (غير مرئية، لكنها تُحتسب).
|
||||
- المرفقات/النصوص المفرّغة (صور/صوت/ملفات).
|
||||
- ملخصات Compaction وعناصر التقليم.
|
||||
- «الأغلفة» الخاصة بالمزوّد أو الرؤوس المخفية (غير مرئية، لكنها لا تزال محتسبة).
|
||||
|
||||
## كيف يبني OpenClaw موجّه النظام
|
||||
## كيف يبني OpenClaw توجيه النظام
|
||||
|
||||
موجّه النظام **مملوك لـ OpenClaw** ويُعاد بناؤه في كل تشغيل. ويتضمن:
|
||||
توجيه النظام **مملوك لـ OpenClaw** ويُعاد بناؤه في كل تشغيل. وهو يتضمن:
|
||||
|
||||
- قائمة الأدوات + أوصافًا قصيرة.
|
||||
- قائمة الأدوات + أوصافًا مختصرة.
|
||||
- قائمة Skills (بيانات وصفية فقط؛ انظر أدناه).
|
||||
- موقع مساحة العمل.
|
||||
- الوقت (UTC + وقت المستخدم المحوّل إذا كان مضبوطًا).
|
||||
- بيانات وصفية لبيئة التشغيل (المضيف/نظام التشغيل/النموذج/التفكير).
|
||||
- ملفات bootstrap المحقونة لمساحة العمل ضمن **سياق المشروع**.
|
||||
- الوقت (UTC + وقت المستخدم بعد التحويل إذا كان مضبوطًا).
|
||||
- بيانات وقت التشغيل الوصفية (المضيف/نظام التشغيل/النموذج/التفكير).
|
||||
- ملفات تمهيد مساحة العمل المُدرجة ضمن **سياق المشروع**.
|
||||
|
||||
التفصيل الكامل: [موجّه النظام](/ar/concepts/system-prompt).
|
||||
للاطلاع على التفصيل الكامل: [توجيه النظام](/ar/concepts/system-prompt).
|
||||
|
||||
## ملفات مساحة العمل المحقونة (سياق المشروع)
|
||||
## ملفات مساحة العمل المُدرجة (سياق المشروع)
|
||||
|
||||
افتراضيًا، يحقن OpenClaw مجموعة ثابتة من ملفات مساحة العمل (إذا كانت موجودة):
|
||||
بشكل افتراضي، يدرج OpenClaw مجموعة ثابتة من ملفات مساحة العمل (إذا كانت موجودة):
|
||||
|
||||
- `AGENTS.md`
|
||||
- `SOUL.md`
|
||||
@ -119,69 +119,68 @@ Top tools (schema size):
|
||||
- `HEARTBEAT.md`
|
||||
- `BOOTSTRAP.md` (في التشغيل الأول فقط)
|
||||
|
||||
تُقتطع الملفات الكبيرة لكل ملف باستخدام `agents.defaults.bootstrapMaxChars` (الافتراضي `20000` حرف). كما يفرض OpenClaw حدًا إجماليًا لحقن bootstrap عبر جميع الملفات باستخدام `agents.defaults.bootstrapTotalMaxChars` (الافتراضي `150000` حرف). يعرض `/context` أحجام **الخام مقابل المحقون** وما إذا كان الاقتطاع قد حدث.
|
||||
تُقتطع الملفات الكبيرة لكل ملف على حدة باستخدام `agents.defaults.bootstrapMaxChars` (القيمة الافتراضية `12000` حرف). كما يفرض OpenClaw حدًا إجماليًا لحقن التمهيد عبر جميع الملفات باستخدام `agents.defaults.bootstrapTotalMaxChars` (القيمة الافتراضية `60000` حرف). يعرض `/context` الأحجام **الخام مقابل المُدرج** وما إذا كان قد حدث اقتطاع.
|
||||
|
||||
عند حدوث اقتطاع، يمكن لبيئة التشغيل حقن كتلة تحذير داخل الموجّه ضمن سياق المشروع. اضبط هذا عبر `agents.defaults.bootstrapPromptTruncationWarning` (`off` أو `once` أو `always`؛ الافتراضي `once`).
|
||||
عند حدوث اقتطاع، يمكن لوقت التشغيل إدراج كتلة تحذير داخل التوجيه ضمن سياق المشروع. اضبط ذلك عبر `agents.defaults.bootstrapPromptTruncationWarning` (`off` أو `once` أو `always`؛ والقيمة الافتراضية `once`).
|
||||
|
||||
## Skills: المحقونة مقابل المحمّلة عند الطلب
|
||||
## Skills: المُدرج مقابل المُحمّل عند الطلب
|
||||
|
||||
يتضمن موجّه النظام **قائمة Skills** مضغوطة (الاسم + الوصف + الموقع). لهذه القائمة حمل فعلي.
|
||||
يتضمن توجيه النظام **قائمة Skills** مضغوطة (الاسم + الوصف + الموقع). لهذه القائمة حمل فعلي.
|
||||
|
||||
تعليمات Skill _لا_ تُضمّن افتراضيًا. ومن المتوقع أن يستخدم النموذج `read` لقراءة ملف `SKILL.md` الخاص بالـ Skill **فقط عند الحاجة**.
|
||||
لا تُدرج تعليمات Skill _بشكل افتراضي_. من المتوقع أن يستخدم النموذج `read` لقراءة ملف `SKILL.md` الخاص بالـ Skill **عند الحاجة فقط**.
|
||||
|
||||
## الأدوات: هناك تكلفتان
|
||||
|
||||
تؤثر الأدوات في السياق بطريقتين:
|
||||
|
||||
1. **نص قائمة الأدوات** في موجّه النظام (ما تراه باسم "Tooling").
|
||||
2. **مخططات الأدوات** (JSON). تُرسل هذه إلى النموذج حتى يتمكن من استدعاء الأدوات. وهي تُحتسب ضمن السياق رغم أنك لا تراها كنص عادي.
|
||||
1. **نص قائمة الأدوات** في توجيه النظام (ما تراه تحت اسم «Tooling»).
|
||||
2. **مخططات الأدوات** (JSON). تُرسل هذه إلى النموذج حتى يتمكن من استدعاء الأدوات. وهي تُحتسب ضمن السياق حتى لو لم ترها كنص عادي.
|
||||
|
||||
يقسم `/context detail` أكبر مخططات الأدوات حتى تتمكن من معرفة ما الذي يهيمن.
|
||||
يقسم `/context detail` أكبر مخططات الأدوات حتى تتمكن من معرفة ما الذي يهيمن على الحجم.
|
||||
|
||||
## الأوامر، والتوجيهات، و"الاختصارات المضمنة"
|
||||
## الأوامر، والتوجيهات، و"الاختصارات المضمّنة"
|
||||
|
||||
تعالج Gateway أوامر الشرطة المائلة. وهناك عدة سلوكيات مختلفة:
|
||||
تتعامل Gateway مع أوامر الشرطة المائلة. وهناك عدة سلوكيات مختلفة:
|
||||
|
||||
- **الأوامر المستقلة**: الرسالة التي تحتوي فقط على `/...` تُنفّذ كأمر.
|
||||
- **التوجيهات**: تتم إزالة `/think` و`/verbose` و`/trace` و`/reasoning` و`/elevated` و`/model` و`/queue` قبل أن يرى النموذج الرسالة.
|
||||
- **أوامر مستقلة**: إذا كانت الرسالة تحتوي فقط على `/...`، تُنفّذ كأمر.
|
||||
- **توجيهات**: `/think` و`/verbose` و`/trace` و`/reasoning` و`/elevated` و`/model` و`/queue` تُزال قبل أن يرى النموذج الرسالة.
|
||||
- الرسائل التي تحتوي على توجيهات فقط تحفظ إعدادات الجلسة.
|
||||
- التوجيهات المضمنة داخل رسالة عادية تعمل كتلميحات خاصة بتلك الرسالة.
|
||||
- **الاختصارات المضمنة** (للمرسلين المسموح لهم فقط): يمكن لبعض رموز `/...` داخل رسالة عادية أن تُنفّذ فورًا (مثال: "hey /status")، وتتم إزالتها قبل أن يرى النموذج النص المتبقي.
|
||||
- التوجيهات المضمّنة داخل رسالة عادية تعمل كتلميحات خاصة بتلك الرسالة.
|
||||
- **اختصارات مضمّنة** (للمرسلين المسموح لهم فقط): يمكن لبعض رموز `/...` داخل رسالة عادية أن تُنفّذ فورًا (مثال: “hey /status”)، وتُزال قبل أن يرى النموذج النص المتبقي.
|
||||
|
||||
التفاصيل: [أوامر الشرطة المائلة](/ar/tools/slash-commands).
|
||||
للتفاصيل: [أوامر الشرطة المائلة](/ar/tools/slash-commands).
|
||||
|
||||
## الجلسات وCompaction والتشذيب (ما الذي يستمر)
|
||||
## الجلسات، وCompaction، والتقليم (ما الذي يستمر)
|
||||
|
||||
ما الذي يستمر عبر الرسائل يعتمد على الآلية:
|
||||
يعتمد ما يستمر عبر الرسائل على الآلية:
|
||||
|
||||
- **السجل العادي** يستمر في تفريغ الجلسة حتى يتم ضغطه/تشذيبه وفق السياسة.
|
||||
- **Compaction** يحتفظ بملخص داخل التفريغ ويحافظ على الرسائل الحديثة كما هي.
|
||||
- **التشذيب** يزيل نتائج الأدوات القديمة من الموجّه _داخل الذاكرة_ أثناء التشغيل، لكنه لا يعيد كتابة التفريغ.
|
||||
- **السجل العادي** يستمر في نص الجلسة حتى يُضغط/يُقلَّم حسب السياسة.
|
||||
- **Compaction** يحفظ ملخصًا داخل النص ويُبقي الرسائل الحديثة كما هي.
|
||||
- **التقليم** يزيل نتائج الأدوات القديمة من التوجيه _الموجود في الذاكرة_ أثناء التشغيل، لكنه لا يعيد كتابة النص.
|
||||
|
||||
الوثائق: [الجلسة](/ar/concepts/session)، [Compaction](/ar/concepts/compaction)، [تشذيب الجلسة](/ar/concepts/session-pruning).
|
||||
الوثائق: [الجلسة](/ar/concepts/session)، [Compaction](/ar/concepts/compaction)، [تقليم الجلسة](/ar/concepts/session-pruning).
|
||||
|
||||
افتراضيًا، يستخدم OpenClaw محرّك السياق المدمج `legacy` للتجميع و
|
||||
بشكل افتراضي، يستخدم OpenClaw محرك السياق المدمج `legacy` للتجميع و
|
||||
Compaction. إذا ثبّتَّ Plugin يوفّر `kind: "context-engine"` و
|
||||
حددتَه باستخدام `plugins.slots.contextEngine`، فإن OpenClaw يفوّض تجميع
|
||||
السياق، و`/compact`، ومرابط دورة حياة سياق الوكيل الفرعي ذات الصلة إلى ذلك
|
||||
المحرّك بدلًا من ذلك. لا يؤدي `ownsCompaction: false` إلى الرجوع تلقائيًا إلى
|
||||
المحرّك `legacy`؛ إذ يجب على المحرّك النشط أن يطبّق `compact()` بشكل صحيح
|
||||
رغم ذلك. راجع
|
||||
[Context Engine](/ar/concepts/context-engine) للاطلاع على الواجهة
|
||||
القابلة للتوصيل كاملةً، ومرابط دورة الحياة، والإعدادات.
|
||||
اخترته باستخدام `plugins.slots.contextEngine`، فسيفوّض OpenClaw
|
||||
تجميع السياق، و`/compact`، وخطافات دورة حياة سياق الوكيل الفرعي ذات الصلة إلى ذلك
|
||||
المحرك بدلًا من ذلك. إن `ownsCompaction: false` لا يؤدي إلى رجوع تلقائي إلى المحرك
|
||||
`legacy`؛ بل يجب على المحرك النشط أن يطبّق `compact()` بشكل صحيح. راجع
|
||||
[Context Engine](/ar/concepts/context-engine) للاطلاع على الواجهة الكاملة
|
||||
القابلة للتوصيل، وخطافات دورة الحياة، والإعدادات.
|
||||
|
||||
## ما الذي يبلّغ عنه `/context` فعليًا
|
||||
## ماذا يعرض `/context` فعليًا
|
||||
|
||||
يفضّل `/context` أحدث تقرير **لموجّه نظام مبنيّ أثناء التشغيل** عندما يكون متاحًا:
|
||||
يفضّل `/context` أحدث تقرير لتوجيه النظام **المبني أثناء التشغيل** عندما يكون متاحًا:
|
||||
|
||||
- `System prompt (run)` = مُلتقط من آخر تشغيل مضمن (قابل لاستخدام الأدوات) ومحفوظ في مخزن الجلسة.
|
||||
- `System prompt (estimate)` = يُحسب لحظيًا عندما لا يوجد تقرير تشغيل (أو عند التشغيل عبر واجهة CLI خلفية لا تولّد التقرير).
|
||||
- `System prompt (run)` = مُلتقط من آخر تشغيل مضمن (قادر على استخدام الأدوات) ومحفوظ في مخزن الجلسة.
|
||||
- `System prompt (estimate)` = يُحتسب أثناء التنفيذ عند عدم وجود تقرير تشغيل (أو عند التشغيل عبر خلفية CLI لا تُنشئ التقرير).
|
||||
|
||||
في كلتا الحالتين، يبلّغ عن الأحجام وأكبر المساهمين؛ لكنه **لا** يعرض موجّه النظام الكامل أو مخططات الأدوات.
|
||||
في كلتا الحالتين، يعرض الأحجام وأكبر المساهمين؛ لكنه **لا** يفرّغ توجيه النظام الكامل أو مخططات الأدوات.
|
||||
|
||||
## ذو صلة
|
||||
|
||||
- [Context Engine](/ar/concepts/context-engine) — حقن سياق مخصص عبر Plugins
|
||||
- [Compaction](/ar/concepts/compaction) — تلخيص المحادثات الطويلة
|
||||
- [موجّه النظام](/ar/concepts/system-prompt) — كيف يُبنى موجّه النظام
|
||||
- [توجيه النظام](/ar/concepts/system-prompt) — كيف يُبنى توجيه النظام
|
||||
- [حلقة الوكيل](/ar/concepts/agent-loop) — دورة تنفيذ الوكيل الكاملة
|
||||
|
||||
@ -1,33 +1,33 @@
|
||||
---
|
||||
read_when:
|
||||
- توسيع qa-lab أو qa-channel
|
||||
- إضافة سيناريوهات ضمان جودة مدعومة بالمستودع
|
||||
- بناء أتمتة ضمان جودة ذات واقعية أعلى حول لوحة تحكم Gateway
|
||||
summary: الشكل الخاص لأتمتة ضمان الجودة لـ qa-lab وqa-channel والسيناريوهات المُهيأة مسبقًا وتقارير البروتوكول
|
||||
title: أتمتة ضمان الجودة من البداية إلى النهاية
|
||||
- إضافة سيناريوهات QA مدعومة من المستودع
|
||||
- بناء أتمتة QA أعلى واقعية حول لوحة معلومات Gateway
|
||||
summary: شكل أتمتة QA الخاصة لـ qa-lab وqa-channel والسيناريوهات المُهيأة مسبقًا وتقارير البروتوكول
|
||||
title: أتمتة QA الشاملة من البداية إلى النهاية
|
||||
x-i18n:
|
||||
generated_at: "2026-04-17T07:17:52Z"
|
||||
generated_at: "2026-04-18T07:14:55Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 51f97293c184d7c04c95d9858305668fbc0f93273f587ec7e54896ad5d603ab0
|
||||
source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4
|
||||
source_path: concepts/qa-e2e-automation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# أتمتة ضمان الجودة من البداية إلى النهاية
|
||||
# أتمتة QA الشاملة من البداية إلى النهاية
|
||||
|
||||
تهدف حزمة ضمان الجودة الخاصة إلى اختبار OpenClaw بطريقة أكثر واقعية وبهيئة قنوات، مقارنةً بما يمكن أن يحققه اختبار وحدات واحد.
|
||||
تهدف حزمة QA الخاصة إلى اختبار OpenClaw بطريقة أكثر واقعية وتشبه القنوات أكثر مما يمكن أن يفعله اختبار وحدة واحد.
|
||||
|
||||
المكوّنات الحالية:
|
||||
الأجزاء الحالية:
|
||||
|
||||
- `extensions/qa-channel`: قناة رسائل اصطناعية تتضمن أسطح الرسائل الخاصة، والقنوات، والخيوط، والتفاعلات، والتعديل، والحذف.
|
||||
- `extensions/qa-lab`: واجهة Debugger وممر ضمان جودة لمراقبة النص الحواري، وحقن الرسائل الواردة، وتصدير تقرير Markdown.
|
||||
- `qa/`: أصول تهيئة مدعومة بالمستودع لمهمة البداية وسيناريوهات ضمان الجودة الأساسية.
|
||||
- `extensions/qa-channel`: قناة رسائل اصطناعية تتضمن أسطح الرسائل الخاصة، والقنوات، وسلاسل المحادثات، والتفاعلات، والتحرير، والحذف.
|
||||
- `extensions/qa-lab`: واجهة مستخدم للتصحيح وناقل QA لمراقبة النص الحواري، وحقن الرسائل الواردة، وتصدير تقرير Markdown.
|
||||
- `qa/`: أصول تهيئة مدعومة من المستودع لمهمة البداية وسيناريوهات QA الأساسية.
|
||||
|
||||
تدفّق تشغيل ضمان الجودة الحالي عبارة عن موقع ضمان جودة ذي لوحتين:
|
||||
تدفق عمل مشغّل QA الحالي هو موقع QA مكوّن من لوحتين:
|
||||
|
||||
- اليسار: لوحة تحكم Gateway (Control UI) مع الوكيل.
|
||||
- اليمين: QA Lab، ويعرض نصًا حواريًا شبيهًا بـ Slack وخطة السيناريو.
|
||||
- اليسار: لوحة معلومات Gateway (Control UI) مع الوكيل.
|
||||
- اليمين: QA Lab، يعرض نصًا حواريًا شبيهًا بـ Slack وخطة السيناريو.
|
||||
|
||||
شغّله باستخدام:
|
||||
|
||||
@ -35,9 +35,9 @@ x-i18n:
|
||||
pnpm qa:lab:up
|
||||
```
|
||||
|
||||
يقوم ذلك ببناء موقع ضمان الجودة، وبدء مسار Gateway مدعومًا بـ Docker، وكشف صفحة QA Lab حيث يمكن لمشغّل أو لحلقة أتمتة إسناد مهمة ضمان جودة إلى الوكيل، ومراقبة سلوك القناة الفعلي، وتسجيل ما نجح وما فشل وما بقي معطّلًا.
|
||||
يقوم ذلك ببناء موقع QA، وبدء مسار Gateway المدعوم بـ Docker، وكشف صفحة QA Lab حيث يمكن لمشغّل أو حلقة أتمتة إعطاء الوكيل مهمة QA، ومراقبة سلوك القناة الفعلي، وتسجيل ما نجح أو فشل أو ظل معطّلًا.
|
||||
|
||||
للحصول على تكرار أسرع في واجهة QA Lab من دون إعادة بناء صورة Docker في كل مرة، ابدأ الحزمة باستخدام حزمة QA Lab مركّبة عبر bind mount:
|
||||
للحصول على تكرار أسرع لواجهة مستخدم QA Lab دون إعادة بناء صورة Docker في كل مرة، ابدأ الحزمة باستخدام حزمة QA Lab مثبّتة عبر bind mount:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa docker-build-image
|
||||
@ -46,112 +46,115 @@ pnpm qa:lab:up:fast
|
||||
pnpm qa:lab:watch
|
||||
```
|
||||
|
||||
يبقي `qa:lab:up:fast` خدمات Docker على صورة مبنية مسبقًا، ويجري bind-mount للدليل `extensions/qa-lab/web/dist` داخل حاوية `qa-lab`. ويعيد `qa:lab:watch` بناء تلك الحزمة عند التغيير، ويُعاد تحميل المتصفح تلقائيًا عند تغيّر بصمة أصول QA Lab.
|
||||
يبقي `qa:lab:up:fast` خدمات Docker على صورة مبنية مسبقًا ويستخدم bind mount للمسار `extensions/qa-lab/web/dist` داخل حاوية `qa-lab`. ويعيد `qa:lab:watch` بناء تلك الحزمة عند التغيير، ويُعاد تحميل المتصفح تلقائيًا عندما تتغير بصمة أصول QA Lab.
|
||||
|
||||
لتشغيل مسار فحص Matrix حقيقي على مستوى النقل، شغّل:
|
||||
لتشغيل مسار Matrix اختباري حقيقي على مستوى النقل، شغّل:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa matrix
|
||||
```
|
||||
|
||||
يقوم هذا المسار بتهيئة خادم منزلي Tuwunel مؤقت داخل Docker، وتسجيل مستخدمين مؤقتين للسائق وSUT والمراقب، وإنشاء غرفة خاصة واحدة، ثم تشغيل Plugin Matrix الفعلي داخل عملية فرعية لـ QA gateway. ويحافظ مسار النقل الحي على إعدادات العملية الفرعية محصورة في النقل قيد الاختبار، بحيث يعمل Matrix من دون `qa-channel` في إعدادات العملية الفرعية. كما يكتب مخرجات التقرير المنظَّمة وسجلًا مدمجًا لـ stdout/stderr داخل دليل إخراج Matrix QA المحدد. ولالتقاط مخرجات البناء/المشغّل الخارجية من `scripts/run-node.mjs` أيضًا، اضبط `OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` إلى ملف سجل محلي داخل المستودع.
|
||||
يوفّر هذا المسار خادم Tuwunel homeserver مؤقتًا داخل Docker، ويسجّل مستخدمين مؤقتين للسائق، وSUT، والمراقب، وينشئ غرفة خاصة واحدة، ثم يشغّل Plugin Matrix الحقيقي داخل child خاص بـ QA gateway. يحافظ مسار النقل الحي على ضبط إعدادات child ضمن النقل الجاري اختباره، لذا يعمل Matrix بدون `qa-channel` في إعدادات child. ويكتب أصول التقارير المنظّمة وسجل stdout/stderr المجمّع في دليل إخراج Matrix QA المحدد. لالتقاط مخرجات البناء/التشغيل الخاصة بـ `scripts/run-node.mjs` الخارجية أيضًا، اضبط `OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` إلى ملف سجل محلي داخل المستودع.
|
||||
|
||||
لتشغيل مسار فحص Telegram حقيقي على مستوى النقل، شغّل:
|
||||
لتشغيل مسار Telegram اختباري حقيقي على مستوى النقل، شغّل:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa telegram
|
||||
```
|
||||
|
||||
يستهدف هذا المسار مجموعة Telegram خاصة حقيقية واحدة بدلًا من تهيئة خادم مؤقت. ويتطلب `OPENCLAW_QA_TELEGRAM_GROUP_ID` و`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` و`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`، بالإضافة إلى روبوتين مختلفين داخل المجموعة الخاصة نفسها. يجب أن يملك روبوت SUT اسم مستخدم Telegram، وتعمل المراقبة بين الروبوتات على أفضل نحو عندما يكون لدى كلا الروبوتين وضع Bot-to-Bot Communication Mode مفعّلًا في `@BotFather`.
|
||||
يستهدف هذا المسار مجموعة Telegram خاصة حقيقية واحدة بدلًا من توفير خادم مؤقت. ويتطلب `OPENCLAW_QA_TELEGRAM_GROUP_ID` و`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` و`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`، بالإضافة إلى روبوتين مختلفين في المجموعة الخاصة نفسها. يجب أن يملك روبوت SUT اسم مستخدم على Telegram، وتعمل المراقبة بين الروبوتات بأفضل شكل عندما يكون Bot-to-Bot Communication Mode مفعّلًا لكلا الروبوتين في `@BotFather`.
|
||||
|
||||
تتشارك مسارات النقل الحية الآن عقدًا أصغر واحدًا بدلًا من أن يبتكر كل مسار منها شكل قائمة السيناريوهات الخاصة به.
|
||||
تتشارك مسارات النقل الحي الآن عقدًا أصغر واحدًا بدلًا من أن يخترع كلٌّ منها شكله الخاص لقائمة السيناريوهات.
|
||||
|
||||
يبقى `qa-channel` مجموعة الاختبارات الاصطناعية الواسعة لسلوك المنتج وليس جزءًا من مصفوفة تغطية النقل الحي.
|
||||
يبقى `qa-channel` مجموعة سلوك المنتج الاصطناعية الواسعة وليس جزءًا من مصفوفة تغطية النقل الحي.
|
||||
|
||||
| المسار | 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 |
|
||||
|
||||
يحافظ هذا على `qa-channel` بوصفه مجموعة اختبارات سلوك المنتج الواسعة، بينما تتشارك Matrix وTelegram ووسائط النقل الحية المستقبلية قائمة تحقق صريحة واحدة لعقد النقل.
|
||||
يحافظ هذا على `qa-channel` كمجموعة سلوك المنتج الواسعة بينما تتشارك Matrix وTelegram ووسائط النقل الحية المستقبلية قائمة تحقق صريحة واحدة لعقد النقل.
|
||||
|
||||
لتشغيل مسار Linux VM مؤقت من دون إدخال Docker في مسار ضمان الجودة، شغّل:
|
||||
لتشغيل مسار Linux VM مؤقت دون إدخال Docker في مسار QA، شغّل:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
|
||||
```
|
||||
|
||||
يقوم هذا بتشغيل ضيف Multipass جديد، وتثبيت الاعتماديات، وبناء OpenClaw داخل الضيف، وتشغيل `qa suite`، ثم نسخ تقرير ضمان الجودة العادي والملخص إلى `.artifacts/qa-e2e/...` على المضيف.
|
||||
يقوم هذا بتشغيل ضيف Multipass جديد، وتثبيت التبعيات، وبناء OpenClaw داخل الضيف، وتشغيل `qa suite`، ثم نسخ تقرير QA والملخص المعتادين مرة أخرى إلى `.artifacts/qa-e2e/...` على المضيف.
|
||||
ويعيد استخدام سلوك اختيار السيناريو نفسه الذي تستخدمه `qa suite` على المضيف.
|
||||
وتنفّذ عمليات suite على المضيف وMultipass عدة سيناريوهات محددة بالتوازي مع عمّال Gateway معزولين افتراضيًا، حتى 64 عاملًا أو عدد السيناريوهات المحددة. استخدم `--concurrency <count>` لضبط عدد العمّال، أو `--concurrency 1` للتنفيذ التسلسلي.
|
||||
وتُمرَّر في التشغيلات الحية مدخلات مصادقة ضمان الجودة المدعومة والعملية داخل الضيف: مفاتيح الموفر المعتمدة على البيئة، ومسار إعدادات موفر QA الحي، و`CODEX_HOME` عند وجوده. أبقِ `--output-dir` تحت جذر المستودع حتى يتمكن الضيف من الكتابة عكسيًا عبر مساحة العمل المركّبة.
|
||||
تنفذ تشغيلات الحزمة على المضيف وMultipass عدة سيناريوهات محددة بالتوازي مع عمّال Gateway معزولين افتراضيًا، حتى 64 عاملًا أو عدد السيناريوهات المحدد. استخدم `--concurrency <count>` لضبط عدد العمّال، أو `--concurrency 1` للتنفيذ التسلسلي.
|
||||
تُمرَّر في التشغيلات الحية مدخلات مصادقة QA المدعومة والعملية للضيف: مفاتيح المزوّد المعتمدة على البيئة، ومسار إعدادات مزوّد QA الحي، و`CODEX_HOME` عند توفره. أبقِ `--output-dir` تحت جذر المستودع حتى يتمكن الضيف من الكتابة مرة أخرى عبر مساحة العمل المركبة.
|
||||
|
||||
## البذور المدعومة بالمستودع
|
||||
## الأصول المهيأة مسبقًا والمدعومة من المستودع
|
||||
|
||||
توجد أصول التهيئة في `qa/`:
|
||||
|
||||
- `qa/scenarios/index.md`
|
||||
- `qa/scenarios/*.md`
|
||||
- `qa/scenarios/<theme>/*.md`
|
||||
|
||||
وهذه موجودة عمدًا في git حتى تكون خطة ضمان الجودة مرئية لكلٍّ من البشر والوكيل.
|
||||
هذه موجودة عمدًا في git حتى تكون خطة QA مرئية للبشر وللوكيل معًا.
|
||||
|
||||
يجب أن يظل `qa-lab` مشغّل Markdown عامًا. ويجب أن يكون كل ملف Markdown للسيناريو هو مصدر الحقيقة لتشغيل اختبار واحد، وأن يعرّف ما يلي:
|
||||
يجب أن يظل `qa-lab` مشغّل Markdown عامًا. كل ملف Markdown للسيناريو هو مصدر الحقيقة لتشغيل اختبار واحد ويجب أن يحدد:
|
||||
|
||||
- بيانات وصفية للسيناريو
|
||||
- بيانات تعريف السيناريو
|
||||
- بيانات تعريف اختيارية للفئة، والقدرة، والمسار، والمخاطر
|
||||
- مراجع الوثائق والكود
|
||||
- متطلبات Plugin اختيارية
|
||||
- تصحيح اختياري لإعدادات Gateway
|
||||
- تصحيحًا اختياريًا لإعدادات Gateway
|
||||
- `qa-flow` القابل للتنفيذ
|
||||
|
||||
يُسمح لسطح وقت التشغيل القابل لإعادة الاستخدام الذي يدعم `qa-flow` بأن يظل عامًا وعابرًا للجوانب. على سبيل المثال، يمكن لسيناريوهات Markdown أن تجمع بين أدوات مساعدة على جانب النقل وأخرى على جانب المتصفح تدفع Control UI المضمّنة عبر واجهة Gateway `browser.request` من دون إضافة مشغّل مخصص لحالة خاصة.
|
||||
يُسمح لسطح التشغيل القابل لإعادة الاستخدام الذي يدعم `qa-flow` بأن يظل عامًا وعابرًا للاهتمامات. على سبيل المثال، يمكن لسيناريوهات Markdown دمج مساعدين من جانب النقل مع مساعدين من جانب المتصفح يقودون Control UI المضمّن عبر واجهة Gateway `browser.request` من دون إضافة مشغّل ذي حالات خاصة.
|
||||
|
||||
يجب أن تظل القائمة الأساسية واسعة بما يكفي لتغطية:
|
||||
يجب تجميع ملفات السيناريو حسب قدرة المنتج بدلًا من مجلد شجرة المصدر. أبقِ معرّفات السيناريو ثابتة عند نقل الملفات؛ واستخدم `docsRefs` و`codeRefs` لتتبّع التنفيذ.
|
||||
|
||||
- المحادثة في الرسائل الخاصة والقنوات
|
||||
- سلوك الخيوط
|
||||
يجب أن تبقى القائمة الأساسية واسعة بما يكفي لتغطية:
|
||||
|
||||
- محادثات الرسائل الخاصة والقنوات
|
||||
- سلوك السلاسل
|
||||
- دورة حياة إجراءات الرسائل
|
||||
- استدعاءات Cron
|
||||
- استرجاع الذاكرة
|
||||
- تبديل النماذج
|
||||
- تسليم المهام إلى وكيل فرعي
|
||||
- تسليم المهام إلى وكلاء فرعيين
|
||||
- قراءة المستودع وقراءة الوثائق
|
||||
- مهمة بناء صغيرة واحدة مثل Lobster Invaders
|
||||
- مهمة بناء صغيرة مثل Lobster Invaders
|
||||
|
||||
## مسارات محاكاة الموفّر
|
||||
## مسارات محاكاة المزوّد
|
||||
|
||||
يتضمن `qa suite` مسارين محليين لمحاكاة الموفّر:
|
||||
تحتوي `qa suite` على مسارين محليين لمحاكاة المزوّد:
|
||||
|
||||
- `mock-openai` هو محاكي OpenClaw الواعي بالسيناريو. ويظل مسار المحاكاة الحتمي الافتراضي لضمان الجودة المدعوم بالمستودع ولبوابات التماثل.
|
||||
- `aimock` يشغّل خادم موفّر مدعومًا بـ AIMock لتغطية البروتوكولات والتجهيزات والتسجيل/إعادة التشغيل وحالات الفوضى على نحو تجريبي. وهو إضافة مكملة ولا يستبدل موزّع السيناريو `mock-openai`.
|
||||
- `mock-openai` هو محاكي OpenClaw الواعي بالسيناريو. ويظل مسار المحاكاة الحتمي الافتراضي لـ QA المدعوم من المستودع وبوابات التكافؤ.
|
||||
- `aimock` يشغّل خادم مزوّد مدعومًا بـ AIMock لتغطية تجريبية للبروتوكول، والملفات الثابتة، والتسجيل/إعادة التشغيل، والفوضى. وهو إضافة ولا يستبدل موزّع السيناريو `mock-openai`.
|
||||
|
||||
يوجد تنفيذ مسار الموفّر تحت `extensions/qa-lab/src/providers/`.
|
||||
ويمتلك كل موفّر إعداداته الافتراضية، وبدء تشغيل خادمه المحلي، وإعدادات نموذج Gateway، واحتياجات تجهيز ملف المصادقة، وأعلام القدرات الحية/الوهمية. ويجب أن يمرّ كود suite وGateway المشترك عبر سجل الموفّرين بدلًا من التفرع بناءً على أسماء الموفّرين.
|
||||
يوجد تنفيذ مسار المزوّد تحت `extensions/qa-lab/src/providers/`.
|
||||
ويمتلك كل مزوّد إعداداته الافتراضية، وبدء خادمه المحلي، وإعدادات نموذج Gateway، واحتياجات تجهيز ملف تعريف المصادقة، وأعلام القدرات الحية/الوهمية الخاصة به. يجب أن يمر الكود المشترك للحزمة وGateway عبر سجل المزوّدين بدلًا من التفريع على أسماء المزوّدين.
|
||||
|
||||
## مُكيّفات النقل
|
||||
## محوّلات النقل
|
||||
|
||||
يمتلك `qa-lab` واجهة نقل عامة لسيناريوهات ضمان الجودة المعتمدة على Markdown.
|
||||
ويُعد `qa-channel` أول مُكيّف على هذه الواجهة، لكن الهدف التصميمي أوسع: يجب أن تتمكن القنوات المستقبلية، سواء كانت حقيقية أو اصطناعية، من الاندماج في مشغّل suite نفسه بدلًا من إضافة مشغّل ضمان جودة خاص بالنقل.
|
||||
يمتلك `qa-lab` واجهة نقل عامة لسيناريوهات QA المكتوبة بـ Markdown.
|
||||
ويُعد `qa-channel` أول محوّل على هذه الواجهة، لكن هدف التصميم أوسع: يجب أن تتمكن القنوات المستقبلية، الحقيقية أو الاصطناعية، من الاندماج في مشغّل الحزمة نفسه بدلًا من إضافة مشغّل QA خاص بالنقل.
|
||||
|
||||
على مستوى المعمارية، يكون التقسيم كما يلي:
|
||||
على مستوى البنية، يكون التقسيم كالتالي:
|
||||
|
||||
- يمتلك `qa-lab` تنفيذ السيناريوهات العامة، وتوازي العمّال، وكتابة المخرجات، وإعداد التقارير.
|
||||
- يمتلك مُكيّف النقل إعدادات Gateway، والجاهزية، ومراقبة الوارد والصادر، وإجراءات النقل، وحالة النقل المطَبَّعة.
|
||||
- تحدد ملفات سيناريو Markdown ضمن `qa/scenarios/` تشغيل الاختبار؛ ويوفّر `qa-lab` سطح وقت التشغيل القابل لإعادة الاستخدام الذي ينفذها.
|
||||
- يمتلك `qa-lab` تنفيذ السيناريو العام، وتوازي العمّال، وكتابة الأصول، وإعداد التقارير.
|
||||
- يمتلك محوّل النقل إعدادات Gateway، والجاهزية، ومراقبة الوارد والصادر، وإجراءات النقل، وحالة النقل الموحّدة.
|
||||
- تحدد ملفات سيناريو Markdown تحت `qa/scenarios/` تشغيل الاختبار؛ ويقدم `qa-lab` سطح التشغيل القابل لإعادة الاستخدام الذي ينفذه.
|
||||
|
||||
توجد إرشادات الاعتماد الموجهة للمشرفين لمُكيّفات القنوات الجديدة في
|
||||
توجد إرشادات التبنّي للمشرفين الخاصة بمحوّلات القنوات الجديدة في
|
||||
[الاختبار](/ar/help/testing#adding-a-channel-to-qa).
|
||||
|
||||
## إعداد التقارير
|
||||
|
||||
يصدّر `qa-lab` تقرير بروتوكول بصيغة Markdown من المخطط الزمني للممر المرصود.
|
||||
ويجب أن يجيب التقرير عن:
|
||||
يصدّر `qa-lab` تقرير بروتوكول بصيغة Markdown من المخطط الزمني لناقل المراقبة.
|
||||
يجب أن يجيب التقرير عن:
|
||||
|
||||
- ما الذي نجح
|
||||
- ما الذي فشل
|
||||
- ما الذي بقي معطّلًا
|
||||
- ما سيناريوهات المتابعة الجديرة بالإضافة
|
||||
- ما الذي ظل معطّلًا
|
||||
- ما سيناريوهات المتابعة التي تستحق الإضافة
|
||||
|
||||
لفحوصات الطابع والأسلوب، شغّل السيناريو نفسه عبر عدة مراجع لنماذج حية واكتب تقرير Markdown خاضعًا للتحكيم:
|
||||
لفحوصات الشخصية والأسلوب، شغّل السيناريو نفسه عبر عدة مراجع نماذج حية واكتب تقرير Markdown مُحكَّمًا:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa character-eval \
|
||||
@ -170,18 +173,17 @@ pnpm openclaw qa character-eval \
|
||||
--judge-concurrency 16
|
||||
```
|
||||
|
||||
يشغّل هذا الأمر عمليات QA gateway فرعية محلية، وليس Docker. يجب أن تضبط سيناريوهات تقييم الطابع الشخصية عبر `SOUL.md`، ثم تُجري أدوار مستخدم عادية مثل المحادثة، ومساعدة مساحة العمل، والمهام الصغيرة على الملفات. ويجب ألا يُبلَّغ النموذج المرشح بأنه قيد التقييم. ويحافظ الأمر على كل نص حواري كامل، ويسجل إحصاءات التشغيل الأساسية، ثم يطلب من نماذج التحكيم في الوضع السريع مع استدلال `xhigh` ترتيب التشغيلات بحسب الطبيعية والطابع والفكاهة.
|
||||
استخدم `--blind-judge-models` عند المقارنة بين الموفّرين: سيظل موجّه التحكيم يتلقى كل نص حواري وحالة تشغيل، لكن ستُستبدل مراجع المرشحين بتسميات محايدة مثل `candidate-01`؛ ويعيد التقرير ربط الترتيب بالمراجع الحقيقية بعد التحليل.
|
||||
تستخدم تشغيلات المرشحين افتراضيًا مستوى تفكير `high`، مع `xhigh` لنماذج OpenAI التي تدعمه. ويمكنك تجاوز مرشح محدد ضمنيًا باستخدام
|
||||
`--model provider/model,thinking=<level>`. وما زال `--thinking <level>` يضبط قيمة احتياطية عامة، كما يُحتفظ بالشكل الأقدم `--model-thinking <provider/model=level>` من أجل التوافق.
|
||||
تستخدم مراجع المرشحين الخاصة بـ OpenAI الوضع السريع افتراضيًا بحيث تُستخدم المعالجة ذات الأولوية عندما يدعمها الموفّر. أضف `,fast` أو `,no-fast` أو `,fast=false` ضمنيًا عندما يحتاج مرشح واحد أو حكم واحد إلى تجاوز. مرّر `--fast` فقط عندما تريد فرض الوضع السريع على كل نموذج مرشح. وتُسجَّل مدد تشغيل المرشحين والحكام في التقرير لتحليل المقاييس، لكن توجيهات التحكيم تنص صراحةً على عدم الترتيب حسب السرعة.
|
||||
يشغّل هذا الأمر عمليات child محلية لـ QA gateway، وليس Docker. يجب أن تضبط سيناريوهات تقييم الشخصية الشخصيةَ عبر `SOUL.md`، ثم تنفذ أدوار مستخدم عادية مثل الدردشة، ومساعدة مساحة العمل، ومهام الملفات الصغيرة. ويجب ألا يُخبَر النموذج المرشح بأنه قيد التقييم. يحتفظ الأمر بكل نص حواري كامل، ويسجّل إحصاءات التشغيل الأساسية، ثم يطلب من نماذج التحكيم في الوضع السريع مع استدلال `xhigh` ترتيب التشغيلات حسب الطبيعية والطابع وروح الدعابة.
|
||||
استخدم `--blind-judge-models` عند مقارنة المزوّدين: إذ يستمر موجه التحكيم في الحصول على كل نص حواري وحالة تشغيل، لكن تُستبدل مراجع المرشحين بتسميات محايدة مثل `candidate-01`؛ ثم يربط التقرير التصنيفات مرة أخرى بالمراجع الحقيقية بعد التحليل.
|
||||
تستخدم تشغيلات المرشحين افتراضيًا مستوى تفكير `high`، مع `xhigh` لنماذج OpenAI التي تدعمه. يمكنك تجاوز مرشح محدد ضمنيًا باستخدام
|
||||
`--model provider/model,thinking=<level>`. ولا يزال `--thinking <level>` يضبط قيمة احتياطية عامة، ويُحتفظ بالنموذج الأقدم `--model-thinking <provider/model=level>` من أجل التوافق.
|
||||
تستخدم مراجع المرشحين الخاصة بـ OpenAI الوضع السريع افتراضيًا حتى تُستخدم المعالجة ذات الأولوية حيثما كان المزوّد يدعمها. أضف `,fast` أو `,no-fast` أو `,fast=false` ضمنيًا عندما يحتاج مرشح واحد أو حكم واحد إلى تجاوز. مرّر `--fast` فقط عندما تريد فرض الوضع السريع لكل نموذج مرشح. وتُسجَّل مدد المرشحين والحكام في التقرير لتحليل المقاييس، لكن موجهات التحكيم تنص صراحةً على عدم الترتيب حسب السرعة.
|
||||
تستخدم تشغيلات نماذج المرشحين والحكام افتراضيًا توازيًا مقداره 16. خفّض
|
||||
`--concurrency` أو `--judge-concurrency` عندما تجعل حدود الموفّر أو ضغط Gateway المحلي التشغيل صاخبًا أكثر من اللازم.
|
||||
عندما لا يُمرَّر أي `--model` للمرشح، يستخدم تقييم الطابع افتراضيًا
|
||||
`openai/gpt-5.4` و`openai/gpt-5.2` و`openai/gpt-5` و`anthropic/claude-opus-4-6` و`anthropic/claude-sonnet-4-6` و`zai/glm-5.1` و
|
||||
`moonshot/kimi-k2.5` و
|
||||
`--concurrency` أو `--judge-concurrency` عندما تجعل حدود المزوّد أو ضغط Gateway المحلي التشغيل مشوشًا أكثر من اللازم.
|
||||
عند عدم تمرير أي `--model` للمرشح، يستخدم تقييم الشخصية افتراضيًا
|
||||
`openai/gpt-5.4` و`openai/gpt-5.2` و`openai/gpt-5` و`anthropic/claude-opus-4-6` و`anthropic/claude-sonnet-4-6` و`zai/glm-5.1` و`moonshot/kimi-k2.5` و
|
||||
`google/gemini-3.1-pro-preview`.
|
||||
وعندما لا يُمرَّر أي `--judge-model`، تكون النماذج الحكَمية الافتراضية هي
|
||||
وعند عدم تمرير أي `--judge-model`، تكون النماذج الحاكمة الافتراضية هي
|
||||
`openai/gpt-5.4,thinking=xhigh,fast` و
|
||||
`anthropic/claude-opus-4-6,thinking=high`.
|
||||
|
||||
@ -189,4 +191,4 @@ pnpm openclaw qa character-eval \
|
||||
|
||||
- [الاختبار](/ar/help/testing)
|
||||
- [قناة QA](/ar/channels/qa-channel)
|
||||
- [لوحة التحكم](/web/dashboard)
|
||||
- [لوحة المعلومات](/web/dashboard)
|
||||
|
||||
@ -1,104 +1,101 @@
|
||||
---
|
||||
read_when:
|
||||
- تحرير نص موجه النظام، أو قائمة الأدوات، أو أقسام الوقت/Heartbeat
|
||||
- تغيير سلوك تهيئة مساحة العمل أو حقن Skills
|
||||
summary: ما الذي يحتويه موجه نظام OpenClaw وكيف يتم تجميعه
|
||||
title: موجه النظام
|
||||
- تحرير نص مطالبة النظام أو قائمة الأدوات أو أقسام الوقت/Heartbeat
|
||||
- تغيير تهيئة مساحة العمل أو سلوك حقن Skills
|
||||
summary: ما الذي تتضمنه مطالبة نظام OpenClaw وكيف يتم تجميعها
|
||||
title: مطالبة النظام
|
||||
x-i18n:
|
||||
generated_at: "2026-04-15T19:41:40Z"
|
||||
generated_at: "2026-04-18T07:14:51Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4
|
||||
source_hash: e60705994cebdd9768926168cb1c6d17ab717d7ff02353a5d5e7478ba8191cab
|
||||
source_path: concepts/system-prompt.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# موجه النظام
|
||||
# مطالبة النظام
|
||||
|
||||
يبني OpenClaw موجه نظام مخصصًا لكل تشغيل وكيل. الموجه **مملوك لـ OpenClaw** ولا يستخدم الموجه الافتراضي الخاص بـ pi-coding-agent.
|
||||
ينشئ OpenClaw مطالبة نظام مخصصة لكل تشغيل وكيل. تكون المطالبة **مملوكة لـ OpenClaw** ولا تستخدم المطالبة الافتراضية الخاصة بـ pi-coding-agent.
|
||||
|
||||
يتم تجميع الموجه بواسطة OpenClaw وحقنه في كل تشغيل وكيل.
|
||||
يتم تجميع المطالبة بواسطة OpenClaw وحقنها في كل تشغيل وكيل.
|
||||
|
||||
يمكن لإضافات الموفر المساهمة بإرشادات موجه تراعي الذاكرة المؤقتة دون استبدال
|
||||
موجه OpenClaw الكامل المملوك له. يمكن لبيئة تشغيل الموفر القيام بما يلي:
|
||||
يمكن لإضافات الموفر المساهمة بإرشادات مطالبة تراعي التخزين المؤقت دون استبدال
|
||||
مطالبة OpenClaw الكاملة المملوكة له. يمكن لوقت تشغيل الموفر أن:
|
||||
|
||||
- استبدال مجموعة صغيرة من الأقسام الأساسية المسماة (`interaction_style`,
|
||||
- يستبدل مجموعة صغيرة من الأقسام الأساسية المسمّاة (`interaction_style`,
|
||||
`tool_call_style`, `execution_bias`)
|
||||
- حقن **بادئة مستقرة** فوق حد الذاكرة المؤقتة للموجه
|
||||
- حقن **لاحقة ديناميكية** أسفل حد الذاكرة المؤقتة للموجه
|
||||
- يحقن **بادئة مستقرة** فوق حد التخزين المؤقت للمطالبة
|
||||
- يحقن **لاحقة ديناميكية** تحت حد التخزين المؤقت للمطالبة
|
||||
|
||||
استخدم المساهمات المملوكة للموفر من أجل الضبط الخاص بعائلة النموذج. أبقِ
|
||||
التعديل القديم للموجه عبر `before_prompt_build` من أجل التوافق أو تغييرات
|
||||
الموجه العامة فعلًا، وليس لسلوك الموفر المعتاد.
|
||||
استخدم المساهمات المملوكة للموفر من أجل الضبط الخاص بعائلة النماذج. أبقِ
|
||||
تعديل المطالبة القديم `before_prompt_build` من أجل التوافق أو تغييرات
|
||||
المطالبة العالمية فعلًا، وليس لسلوك الموفر المعتاد.
|
||||
|
||||
## البنية
|
||||
|
||||
الموجه مضغوط عمدًا ويستخدم أقسامًا ثابتة:
|
||||
المطالبة مضغوطة عمدًا وتستخدم أقسامًا ثابتة:
|
||||
|
||||
- **الأدوات**: تذكير بالمصدر المرجعي المنظم للأدوات بالإضافة إلى إرشادات وقت التشغيل لاستخدام الأدوات.
|
||||
- **السلامة**: تذكير قصير بالضوابط لتجنب السلوك الساعي إلى القوة أو تجاوز الإشراف.
|
||||
- **Skills** (عند توفرها): يوضح للنموذج كيفية تحميل تعليمات المهارات عند الطلب.
|
||||
- **الأدوات**: تذكير منظَّم بمصدر الحقيقة للأدوات المهيكلة مع إرشادات استخدام الأدوات أثناء وقت التشغيل.
|
||||
- **السلامة**: تذكير مختصر بالضوابط الوقائية لتجنب السلوك الساعي إلى السلطة أو تجاوز الإشراف.
|
||||
- **Skills** (عند توفرها): يوضح للنموذج كيفية تحميل تعليمات المهارة عند الطلب.
|
||||
- **التحديث الذاتي لـ OpenClaw**: كيفية فحص الإعدادات بأمان باستخدام
|
||||
`config.schema.lookup`، وتصحيح الإعدادات باستخدام `config.patch`، واستبدال
|
||||
الإعدادات بالكامل باستخدام `config.apply`، وتشغيل `update.run` فقط عند طلب
|
||||
المستخدم الصريح. كما أن أداة `gateway` المخصصة للمالك فقط ترفض أيضًا إعادة
|
||||
كتابة `tools.exec.ask` / `tools.exec.security`، بما في ذلك الأسماء
|
||||
`config.schema.lookup`، وتعديل الإعدادات باستخدام `config.patch`، واستبدال
|
||||
الإعدادات كاملة باستخدام `config.apply`، وتشغيل `update.run` فقط عند طلب
|
||||
المستخدم الصريح. كما أن أداة `gateway` المخصَّصة للمالك فقط ترفض أيضًا
|
||||
إعادة كتابة `tools.exec.ask` / `tools.exec.security`، بما في ذلك الأسماء
|
||||
المستعارة القديمة `tools.bash.*` التي تُطبَّع إلى مسارات exec المحمية تلك.
|
||||
- **مساحة العمل**: دليل العمل (`agents.defaults.workspace`).
|
||||
- **التوثيق**: المسار المحلي إلى وثائق OpenClaw (المستودع أو حزمة npm) ومتى يجب قراءتها.
|
||||
- **ملفات مساحة العمل (محقونة)**: يشير إلى أن ملفات التهيئة الأولية مضمنة أدناه.
|
||||
- **Sandbox** (عند التمكين): يشير إلى بيئة تشغيل معزولة، ومسارات sandbox، وما إذا كان التنفيذ المرتفع الصلاحيات متاحًا.
|
||||
- **ملفات مساحة العمل (محقونة)**: تشير إلى أن ملفات التهيئة الأولية مضمنة أدناه.
|
||||
- **Sandbox** (عند التمكين): يوضح بيئة التشغيل المعزولة، ومسارات Sandbox، وما إذا كان التنفيذ المرفوع الصلاحيات متاحًا.
|
||||
- **التاريخ والوقت الحاليان**: الوقت المحلي للمستخدم، والمنطقة الزمنية، وتنسيق الوقت.
|
||||
- **وسوم الرد**: صياغة وسوم الرد الاختيارية للموفرين المدعومين.
|
||||
- **Heartbeats**: موجه Heartbeat وسلوك الإقرار، عندما تكون Heartbeats مفعلة للوكيل الافتراضي.
|
||||
- **وقت التشغيل**: المضيف، ونظام التشغيل، وnode، والنموذج، وجذر المستودع (عند اكتشافه)، ومستوى التفكير (سطر واحد).
|
||||
- **الاستدلال**: مستوى الرؤية الحالي + تلميح تبديل /reasoning.
|
||||
- **Heartbeats**: مطالبة Heartbeat وسلوك الإقرار، عندما تكون Heartbeats مفعلة للوكيل الافتراضي.
|
||||
- **وقت التشغيل**: المضيف، ونظام التشغيل، وNode، والنموذج، وجذر المستودع (عند اكتشافه)، ومستوى التفكير (سطر واحد).
|
||||
- **الاستدلال**: مستوى الرؤية الحالي + تلميح تبديل `/reasoning`.
|
||||
|
||||
يتضمن قسم الأدوات أيضًا إرشادات وقت التشغيل للأعمال طويلة التشغيل:
|
||||
يتضمن قسم الأدوات أيضًا إرشادات أثناء وقت التشغيل للعمل طويل الأمد:
|
||||
|
||||
- استخدم Cron للمتابعة المستقبلية (`check back later`، والتذكيرات، والأعمال المتكررة)
|
||||
- استخدم Cron للمتابعة المستقبلية (`check back later`، والتذكيرات، والعمل المتكرر)
|
||||
بدلًا من حلقات السكون عبر `exec`، أو حيل التأخير `yieldMs`، أو الاستطلاع
|
||||
المتكرر لـ `process`
|
||||
- استخدم `exec` / `process` فقط للأوامر التي تبدأ الآن وتستمر في العمل في
|
||||
الخلفية
|
||||
- عند تمكين التنبيه التلقائي عند الاكتمال، ابدأ الأمر مرة واحدة ثم اعتمد على
|
||||
مسار التنبيه المعتمد على الدفع عندما يصدر مخرجات أو يفشل
|
||||
- استخدم `exec` / `process` فقط للأوامر التي تبدأ الآن وتستمر في العمل
|
||||
في الخلفية
|
||||
- عند تمكين التنبيه التلقائي عند الاكتمال، ابدأ الأمر مرة واحدة واعتمد على
|
||||
مسار التنبيه القائم على الدفع عندما يُخرج مخرجات أو يفشل
|
||||
- استخدم `process` للسجلات، أو الحالة، أو الإدخال، أو التدخل عندما تحتاج إلى
|
||||
فحص أمر قيد التشغيل
|
||||
- إذا كانت المهمة أكبر، ففضّل `sessions_spawn`; يكتمل الوكيل الفرعي بأسلوب
|
||||
قائم على الدفع ويعلن تلقائيًا الرجوع إلى الطالب
|
||||
- لا تستطلع `subagents list` / `sessions_list` في حلقة فقط لانتظار
|
||||
- إذا كانت المهمة أكبر، ففضّل `sessions_spawn`؛ إذ إن اكتمال الوكيل الفرعي
|
||||
قائم على الدفع ويُعلَن عنه تلقائيًا لصاحب الطلب
|
||||
- لا تستطلع `subagents list` / `sessions_list` ضمن حلقة لمجرد انتظار
|
||||
الاكتمال
|
||||
|
||||
عند تمكين الأداة التجريبية `update_plan`، يوضح قسم الأدوات أيضًا للنموذج أن
|
||||
يستخدمها فقط للأعمال غير التافهة متعددة الخطوات، وأن يُبقي خطوة واحدة فقط
|
||||
`in_progress`، وأن يتجنب تكرار الخطة كاملة بعد كل تحديث.
|
||||
عند تمكين أداة `update_plan` التجريبية، يوجّه قسم الأدوات النموذج أيضًا إلى
|
||||
استخدامها فقط للأعمال غير البسيطة متعددة الخطوات، والحفاظ على خطوة واحدة فقط
|
||||
بحالة `in_progress`، وتجنب تكرار الخطة كاملة بعد كل تحديث.
|
||||
|
||||
ضوابط السلامة في موجه النظام إرشادية. فهي توجه سلوك النموذج لكنها لا تفرض سياسة. استخدم سياسة الأدوات، وموافقات exec، وsandboxing، وقوائم السماح الخاصة بالقنوات من أجل الفرض الصارم؛ ويمكن للمشغلين تعطيل هذه الأمور عمدًا.
|
||||
ضوابط السلامة في مطالبة النظام إرشادية. فهي توجه سلوك النموذج لكنها لا تفرض السياسة. استخدم سياسة الأدوات، وموافقات exec، وSandbox، وقوائم السماح الخاصة بالقنوات لفرض التنفيذ الصارم؛ ويمكن للمشغلين تعطيل هذه الأمور عمدًا.
|
||||
|
||||
في القنوات التي تحتوي على بطاقات/أزرار موافقة أصلية، يوجه موجه وقت التشغيل الآن
|
||||
الوكيل إلى الاعتماد أولًا على واجهة الموافقة الأصلية هذه. ولا ينبغي أن يتضمن
|
||||
أمر `/approve` يدويًا إلا عندما تشير نتيجة الأداة إلى أن موافقات الدردشة غير
|
||||
متاحة أو أن الموافقة اليدوية هي المسار الوحيد.
|
||||
في القنوات التي تحتوي على بطاقات/أزرار موافقة أصلية، توضح مطالبة وقت التشغيل الآن
|
||||
للوكيل أن يعتمد أولًا على واجهة الموافقة الأصلية تلك. ولا ينبغي له تضمين أمر
|
||||
`/approve` يدوي إلا عندما تشير نتيجة الأداة إلى أن موافقات الدردشة غير متاحة أو
|
||||
أن الموافقة اليدوية هي المسار الوحيد.
|
||||
|
||||
## أوضاع الموجه
|
||||
## أوضاع المطالبة
|
||||
|
||||
يمكن لـ OpenClaw عرض موجهات نظام أصغر للوكلاء الفرعيين. يحدد وقت التشغيل
|
||||
`promptMode` لكل تشغيل (وليس إعدادًا ظاهرًا للمستخدم):
|
||||
يمكن لـ OpenClaw عرض مطالبات نظام أصغر للوكلاء الفرعيين. يضبط وقت التشغيل
|
||||
`promptMode` لكل تشغيل (وليس إعدادًا مرئيًا للمستخدم):
|
||||
|
||||
- `full` (افتراضي): يتضمن جميع الأقسام أعلاه.
|
||||
- `minimal`: يُستخدم للوكلاء الفرعيين؛ ويحذف **Skills**، و**استدعاء الذاكرة**، و**التحديث الذاتي لـ OpenClaw**، و**أسماء النماذج المستعارة**، و**هوية المستخدم**، و**وسوم الرد**،
|
||||
و**المراسلة**، و**الردود الصامتة**، و**Heartbeats**. وتظل الأدوات، و**السلامة**،
|
||||
ومساحة العمل، وSandbox، والتاريخ والوقت الحاليان (عند معرفتهما)، ووقت التشغيل، والسياق
|
||||
المحقون متاحة.
|
||||
- `none`: يعيد سطر الهوية الأساسي فقط.
|
||||
- `full` (الافتراضي): يتضمن جميع الأقسام المذكورة أعلاه.
|
||||
- `minimal`: يُستخدم للوكلاء الفرعيين؛ ويحذف **Skills** و**استدعاء الذاكرة** و**التحديث الذاتي لـ OpenClaw** و**الأسماء المستعارة للنماذج** و**هوية المستخدم** و**وسوم الرد** و**المراسلة** و**الردود الصامتة** و**Heartbeats**. وتبقى الأدوات، و**السلامة**، ومساحة العمل، وSandbox، و**التاريخ والوقت الحاليان** (عند معرفتهما)، ووقت التشغيل، والسياق المحقون متاحة.
|
||||
- `none`: يعيد فقط سطر الهوية الأساسي.
|
||||
|
||||
عندما يكون `promptMode=minimal`، تُسمى الموجهات الإضافية المحقونة **سياق الوكيل
|
||||
الفرعي** بدلًا من **سياق الدردشة الجماعية**.
|
||||
عندما يكون `promptMode=minimal`، تُوسم المطالبات الإضافية المحقونة باسم **سياق الوكيل الفرعي**
|
||||
بدلًا من **سياق الدردشة الجماعية**.
|
||||
|
||||
## حقن تهيئة مساحة العمل
|
||||
## حقن التهيئة الأولية لمساحة العمل
|
||||
|
||||
تُقص ملفات التهيئة الأولية وتُلحق تحت **سياق المشروع** حتى يرى النموذج سياق الهوية والملف الشخصي دون الحاجة إلى قراءات صريحة:
|
||||
تُقص ملفات التهيئة الأولية وتُلحق تحت **سياق المشروع** بحيث يرى النموذج الهوية وسياق الملف الشخصي دون الحاجة إلى قراءات صريحة:
|
||||
|
||||
- `AGENTS.md`
|
||||
- `SOUL.md`
|
||||
@ -109,48 +106,48 @@ x-i18n:
|
||||
- `BOOTSTRAP.md` (فقط في مساحات العمل الجديدة تمامًا)
|
||||
- `MEMORY.md` عند وجوده، وإلا `memory.md` كبديل بأحرف صغيرة
|
||||
|
||||
كل هذه الملفات **تُحقن داخل نافذة السياق** في كل دورة ما لم
|
||||
تنطبق بوابة خاصة بالملف. يُحذف `HEARTBEAT.md` في التشغيلات العادية عندما تكون
|
||||
Heartbeats معطلة للوكيل الافتراضي أو عندما يكون
|
||||
`agents.defaults.heartbeat.includeSystemPromptSection` يساوي false. أبقِ الملفات
|
||||
المحقونة موجزة — خاصة `MEMORY.md`، الذي يمكن أن ينمو مع الوقت ويؤدي إلى
|
||||
استخدام سياق أعلى من المتوقع وCompaction أكثر تكرارًا.
|
||||
تُحقن كل هذه الملفات **في نافذة السياق** عند كل دورة ما لم
|
||||
ينطبق حاجز خاص بملف معين. يُحذف `HEARTBEAT.md` في التشغيلات العادية عندما
|
||||
تكون Heartbeats معطلة للوكيل الافتراضي أو عندما تكون
|
||||
`agents.defaults.heartbeat.includeSystemPromptSection` مساوية لـ false. أبقِ الملفات
|
||||
المحقونة موجزة — وخصوصًا `MEMORY.md` الذي قد يكبر بمرور الوقت ويؤدي إلى
|
||||
استخدام مرتفع غير متوقع للسياق وCompaction أكثر تكرارًا.
|
||||
|
||||
> **ملاحظة:** ملفات `memory/*.md` اليومية **ليست** جزءًا من سياق المشروع
|
||||
> الافتراضي للتهيئة الأولية. ففي الدورات العادية يتم الوصول إليها عند الطلب عبر
|
||||
> أداتي `memory_search` و`memory_get`، لذلك لا تُحتسب ضمن نافذة السياق
|
||||
> ما لم يقرأها النموذج صراحةً. وتمثل دورات `/new` و`/reset` المجردة
|
||||
> الاستثناء: إذ يمكن لوقت التشغيل أن يسبق ذاكرة يومية حديثة
|
||||
> **ملاحظة:** ملفات `memory/*.md` اليومية **ليست** جزءًا من
|
||||
> **سياق المشروع** العادي الخاص بالتهيئة الأولية. في الدورات العادية، يُصل إليها
|
||||
> عند الطلب عبر أداتي `memory_search` و`memory_get`، لذلك لا تُحتسب ضمن
|
||||
> نافذة السياق إلا إذا قرأها النموذج صراحة. أما دورات `/new` و`/reset` المجردة
|
||||
> فهي الاستثناء: إذ يمكن لوقت التشغيل أن يضيف مقدمًا ذاكرة يومية حديثة
|
||||
> ككتلة سياق بدء لمرة واحدة لتلك الدورة الأولى.
|
||||
|
||||
تُقتطع الملفات الكبيرة مع علامة. ويُتحكم في الحد الأقصى لحجم كل ملف عبر
|
||||
`agents.defaults.bootstrapMaxChars` (الافتراضي: 20000). كما أن إجمالي محتوى
|
||||
التهيئة الأولية المحقون عبر الملفات مقيّد بواسطة
|
||||
`agents.defaults.bootstrapTotalMaxChars`
|
||||
(الافتراضي: 150000). وتحقن الملفات المفقودة علامة قصيرة تدل على فقدان الملف. وعند حدوث الاقتطاع،
|
||||
يمكن لـ OpenClaw حقن كتلة تحذير في سياق المشروع؛ ويمكن التحكم في ذلك عبر
|
||||
`agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`;
|
||||
الافتراضي: `once`).
|
||||
تُقتطع الملفات الكبيرة مع علامة. يتحكم
|
||||
`agents.defaults.bootstrapMaxChars` في الحد الأقصى لحجم كل ملف
|
||||
(الافتراضي: 12000). ويُحدد سقف إجمالي محتوى التهيئة الأولية المحقون عبر الملفات
|
||||
بواسطة `agents.defaults.bootstrapTotalMaxChars`
|
||||
(الافتراضي: 60000). وتحقن الملفات المفقودة علامة قصيرة تفيد بفقدان الملف. عند حدوث الاقتطاع،
|
||||
يمكن لـ OpenClaw حقن كتلة تحذير في سياق المشروع؛ تحكم في ذلك باستخدام
|
||||
`agents.defaults.bootstrapPromptTruncationWarning` (`off` أو `once` أو `always`؛
|
||||
والافتراضي: `once`).
|
||||
|
||||
جلسات الوكيل الفرعي تحقن فقط `AGENTS.md` و`TOOLS.md` (تُرشَّح ملفات التهيئة الأولية الأخرى
|
||||
لإبقاء سياق الوكيل الفرعي صغيرًا).
|
||||
لا تحقن جلسات الوكيل الفرعي سوى `AGENTS.md` و`TOOLS.md` (تُرشَّح بقية ملفات التهيئة الأولية
|
||||
للحفاظ على صغر سياق الوكيل الفرعي).
|
||||
|
||||
يمكن للخطافات الداخلية اعتراض هذه الخطوة عبر `agent:bootstrap` لتعديل أو استبدال
|
||||
ملفات التهيئة الأولية المحقونة (على سبيل المثال استبدال `SOUL.md` بشخصية بديلة).
|
||||
ملفات التهيئة الأولية المحقونة (مثل تبديل `SOUL.md` بشخصية بديلة).
|
||||
|
||||
إذا كنت تريد جعل الوكيل يبدو أقل عمومية، فابدأ من
|
||||
إذا أردت أن تجعل الوكيل يبدو أقل عمومية، فابدأ بـ
|
||||
[دليل شخصية SOUL.md](/ar/concepts/soul).
|
||||
|
||||
لفحص مقدار مساهمة كل ملف محقون (الخام مقابل المحقون، والاقتطاع، بالإضافة إلى حمل مخطط الأداة)، استخدم `/context list` أو `/context detail`. راجع [السياق](/ar/concepts/context).
|
||||
لفحص مقدار مساهمة كل ملف محقون (الخام مقابل المحقون، والاقتطاع، إضافة إلى الحمل الزائد لمخطط الأداة)، استخدم `/context list` أو `/context detail`. انظر [السياق](/ar/concepts/context).
|
||||
|
||||
## التعامل مع الوقت
|
||||
|
||||
يتضمن موجه النظام قسمًا مخصصًا بعنوان **التاريخ والوقت الحاليان** عندما تكون
|
||||
المنطقة الزمنية للمستخدم معروفة. وللحفاظ على استقرار الذاكرة المؤقتة للموجه، فهو الآن
|
||||
يتضمن فقط **المنطقة الزمنية** (من دون ساعة ديناميكية أو تنسيق وقت).
|
||||
تتضمن مطالبة النظام قسمًا مخصصًا بعنوان **التاريخ والوقت الحاليان** عندما تكون
|
||||
المنطقة الزمنية للمستخدم معروفة. وللحفاظ على استقرار التخزين المؤقت للمطالبة، فهي
|
||||
تتضمن الآن فقط **المنطقة الزمنية** (من دون ساعة ديناميكية أو تنسيق وقت).
|
||||
|
||||
استخدم `session_status` عندما يحتاج الوكيل إلى الوقت الحالي؛
|
||||
تتضمن بطاقة الحالة سطر طابع زمني. ويمكن للأداة نفسها أيضًا تعيين
|
||||
تتضمن بطاقة الحالة سطرًا للطابع الزمني. ويمكن للأداة نفسها اختياريًا ضبط
|
||||
تجاوز نموذج خاص بكل جلسة (`model=default` يمسحه).
|
||||
|
||||
اضبط ذلك باستخدام:
|
||||
@ -158,19 +155,20 @@ Heartbeats معطلة للوكيل الافتراضي أو عندما يكون
|
||||
- `agents.defaults.userTimezone`
|
||||
- `agents.defaults.timeFormat` (`auto` | `12` | `24`)
|
||||
|
||||
راجع [التاريخ والوقت](/ar/date-time) للحصول على التفاصيل الكاملة للسلوك.
|
||||
انظر [التاريخ والوقت](/ar/date-time) للحصول على التفاصيل الكاملة للسلوك.
|
||||
|
||||
## Skills
|
||||
|
||||
عندما تكون هناك Skills مؤهلة، يحقن OpenClaw **قائمة Skills متاحة** مضغوطة
|
||||
عندما توجد Skills مؤهلة، يحقن OpenClaw **قائمة Skills متاحة** مضغوطة
|
||||
(`formatSkillsForPrompt`) تتضمن **مسار الملف** لكل Skill. وتوجّه
|
||||
الموجه النموذج لاستخدام `read` لتحميل ملف SKILL.md في الموقع المدرج
|
||||
(مساحة العمل، أو المُدار، أو المضمّن). وإذا لم توجد Skills مؤهلة، فيُحذف قسم
|
||||
المطالبة النموذج إلى استخدام `read` لتحميل SKILL.md من الموقع المدرج
|
||||
(مساحة العمل، أو المدار، أو المضمَّن). وإذا لم توجد Skills مؤهلة، يُحذف قسم
|
||||
Skills.
|
||||
|
||||
تشمل الأهلية بوابات بيانات تعريف Skill، وفحوصات بيئة التشغيل/الإعدادات،
|
||||
وقائمة السماح الفعلية لمهارات الوكيل عند ضبط `agents.defaults.skills` أو
|
||||
`agents.list[].skills`.
|
||||
تشمل الأهلية بوابات بيانات Skill الوصفية، وفحوصات بيئة/إعدادات وقت التشغيل،
|
||||
وقائمة السماح الفعلية لـ Skills الخاصة بالوكيل عندما تكون
|
||||
`agents.defaults.skills` أو
|
||||
`agents.list[].skills` مضبوطة.
|
||||
|
||||
```
|
||||
<available_skills>
|
||||
@ -182,26 +180,26 @@ Skills.
|
||||
</available_skills>
|
||||
```
|
||||
|
||||
يبقي هذا الموجه الأساسي صغيرًا مع الاستمرار في تمكين استخدام Skills المستهدفة.
|
||||
يحافظ ذلك على صغر المطالبة الأساسية مع الاستمرار في تمكين استخدام Skills بشكل مستهدف.
|
||||
|
||||
تعود ملكية ميزانية قائمة Skills إلى نظام Skills الفرعي:
|
||||
تملك المنظومة الفرعية لـ Skills ميزانية قائمة Skills:
|
||||
|
||||
- الافتراضي العام: `skills.limits.maxSkillsPromptChars`
|
||||
- تجاوز لكل وكيل: `agents.list[].skillsLimits.maxSkillsPromptChars`
|
||||
- التجاوز لكل وكيل: `agents.list[].skillsLimits.maxSkillsPromptChars`
|
||||
|
||||
تستخدم المقاطع المحدودة العامة لوقت التشغيل سطحًا مختلفًا:
|
||||
أما المقاطع العامة المقيّدة في وقت التشغيل فتستخدم سطحًا مختلفًا:
|
||||
|
||||
- `agents.defaults.contextLimits.*`
|
||||
- `agents.list[].contextLimits.*`
|
||||
|
||||
يبقي هذا الفصل تحديد حجم Skills منفصلًا عن تحديد حجم القراءة/الحقن في وقت التشغيل مثل
|
||||
`memory_get`، ونتائج الأدوات الحية، وتحديثات AGENTS.md بعد Compaction.
|
||||
يبقي هذا الفصل حجم Skills منفصلًا عن حجم القراءة/الحقن في وقت التشغيل مثل
|
||||
`memory_get`، ونتائج الأدوات الحية، وتحديثات `AGENTS.md` بعد Compaction.
|
||||
|
||||
## التوثيق
|
||||
|
||||
عند توفره، يتضمن موجه النظام قسم **التوثيق** الذي يشير إلى
|
||||
عند توفره، تتضمن مطالبة النظام قسم **التوثيق** الذي يشير إلى
|
||||
دليل وثائق OpenClaw المحلي (إما `docs/` في مساحة عمل المستودع أو وثائق حزمة npm
|
||||
المضمنة)، كما يذكر أيضًا النسخة العامة المطابقة، ومستودع المصدر، وDiscord المجتمع،
|
||||
وClawHub ([https://clawhub.ai](https://clawhub.ai)) لاكتشاف Skills. ويوجه الموجه النموذج إلى الرجوع إلى
|
||||
الوثائق المحلية أولًا فيما يخص سلوك OpenClaw، أو الأوامر، أو الإعدادات، أو
|
||||
البنية، وأن يشغّل `openclaw status` بنفسه عندما يكون ذلك ممكنًا (ولا يسأل المستخدم إلا عند عدم توفر الوصول).
|
||||
المضمَّنة)، ويذكر أيضًا المرآة العامة، ومستودع المصدر، وDiscord الخاص بالمجتمع،
|
||||
وClawHub ([https://clawhub.ai](https://clawhub.ai)) لاكتشاف Skills. وتوجّه المطالبة النموذج إلى الرجوع إلى الوثائق المحلية أولًا
|
||||
لسلوك OpenClaw أو الأوامر أو الإعدادات أو البنية، وإلى تشغيل
|
||||
`openclaw status` بنفسه متى أمكن (وسؤال المستخدم فقط عندما يفتقر إلى إمكانية الوصول).
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,34 +1,34 @@
|
||||
---
|
||||
read_when:
|
||||
- تنفيذ عملاء WS لـ Gateway أو تحديثهم
|
||||
- تصحيح أخطاء عدم تطابق البروتوكول أو حالات فشل الاتصال
|
||||
- تنفيذ عملاء Gateway WS أو تحديثهم
|
||||
- تصحيح حالات عدم تطابق البروتوكول أو حالات فشل الاتصال
|
||||
- إعادة توليد مخطط/نماذج البروتوكول
|
||||
summary: 'بروتوكول WebSocket لـ Gateway: المصافحة، الإطارات، إدارة الإصدارات'
|
||||
summary: 'بروتوكول Gateway WebSocket: المصافحة، الإطارات، إصدار النسخ'
|
||||
title: بروتوكول Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-04-16T07:18:16Z"
|
||||
generated_at: "2026-04-18T07:14:59Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 683e61ebe993a2d739bc34860060b0e3eda36b5c57267a2bcc03d177ec612fb3
|
||||
source_hash: 4f0eebcfdd8c926c90b4753a6d96c59e3134ddb91740f65478f11eb75be85e41
|
||||
source_path: gateway/protocol.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# بروتوكول Gateway (WebSocket)
|
||||
|
||||
يُعد بروتوكول WS الخاص بـ Gateway **مستوى التحكم الوحيد + ناقل العقد** لـ
|
||||
يُعد بروتوكول Gateway WS **مستوى التحكم الوحيد + ناقل العقد** في
|
||||
OpenClaw. تتصل جميع العملاء (CLI، وواجهة الويب، وتطبيق macOS، وعقد iOS/Android،
|
||||
والعقد عديمة الواجهة) عبر WebSocket وتُعلن **الدور** + **النطاق** الخاصين بها وقت
|
||||
المصافحة.
|
||||
والعقد عديمة الواجهة) عبر WebSocket وتُصرّح عن **الدور** + **النطاق**
|
||||
في وقت المصافحة.
|
||||
|
||||
## النقل
|
||||
|
||||
- WebSocket، وإطارات نصية بحمولة JSON.
|
||||
- WebSocket، بإطارات نصية تحتوي على حمولات JSON.
|
||||
- يجب أن يكون الإطار الأول **بالضرورة** طلب `connect`.
|
||||
|
||||
## المصافحة (`connect`)
|
||||
|
||||
Gateway → العميل (تحدي ما قبل الاتصال):
|
||||
Gateway ← العميل (تحدي ما قبل الاتصال):
|
||||
|
||||
```json
|
||||
{
|
||||
@ -38,7 +38,7 @@ Gateway → العميل (تحدي ما قبل الاتصال):
|
||||
}
|
||||
```
|
||||
|
||||
العميل → Gateway:
|
||||
العميل ← Gateway:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -73,7 +73,7 @@ Gateway → العميل (تحدي ما قبل الاتصال):
|
||||
}
|
||||
```
|
||||
|
||||
Gateway → العميل:
|
||||
Gateway ← العميل:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -95,10 +95,23 @@ Gateway → العميل:
|
||||
}
|
||||
```
|
||||
|
||||
`server` و`features` و`snapshot` و`policy` كلها مطلوبة بحسب المخطط
|
||||
(`src/gateway/protocol/schema/frames.ts`). ويُعد كل من `auth` و`canvasHostUrl` اختياريًا.
|
||||
تُعد الحقول `server` و`features` و`snapshot` و`policy` مطلوبة جميعًا بحسب المخطط
|
||||
(`src/gateway/protocol/schema/frames.ts`). ويُعد `canvasHostUrl` اختياريًا. وتعرض
|
||||
`auth` الدور/النطاقات التي تم التفاوض عليها عند توفرها، وتتضمن `deviceToken`
|
||||
عندما يصدر الـ gateway واحدًا.
|
||||
|
||||
عند إصدار رمز جهاز مميز، يتضمن `hello-ok` أيضًا:
|
||||
عند عدم إصدار رمز جهاز مميز، يمكن أن تعرض `hello-ok.auth` الأذونات التي تم التفاوض عليها رغم ذلك:
|
||||
|
||||
```json
|
||||
{
|
||||
"auth": {
|
||||
"role": "operator",
|
||||
"scopes": ["operator.read", "operator.write"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
عند إصدار رمز جهاز مميز، تتضمن `hello-ok` أيضًا:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -110,8 +123,7 @@ Gateway → العميل:
|
||||
}
|
||||
```
|
||||
|
||||
أثناء تسليم bootstrap الموثوق، قد يتضمن `hello-ok.auth` أيضًا إدخالات أدوار إضافية
|
||||
مقيدة ضمن `deviceTokens`:
|
||||
أثناء تسليم التمهيد الموثوق، قد تتضمن `hello-ok.auth` أيضًا إدخالات أدوار إضافية مقيّدة في `deviceTokens`:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -130,14 +142,14 @@ Gateway → العميل:
|
||||
}
|
||||
```
|
||||
|
||||
في تدفق bootstrap المدمج للعقدة/المشغّل، يبقى الرمز المميز الأساسي للعقدة
|
||||
`scopes: []`، وأي رمز مميز للمشغّل يتم تسليمه يبقى مقيدًا بقائمة السماح الخاصة
|
||||
بمشغّل bootstrap (`operator.approvals` و`operator.read` و`operator.talk.secrets`
|
||||
و`operator.write`). وتظل فحوصات النطاق في bootstrap ذات بادئة مرتبطة بالدور:
|
||||
إدخالات المشغّل تلبّي فقط طلبات المشغّل، بينما لا تزال الأدوار غير التابعة
|
||||
للمشغّل تحتاج إلى نطاقات ضمن بادئة الدور الخاصة بها.
|
||||
في تدفق التمهيد المضمن للعقدة/المشغّل، يبقى رمز العقدة الأساسي
|
||||
`scopes: []` وأي رمز مشغّل مُسلَّم يظل مقيّدًا بقائمة سماح مشغّل التمهيد
|
||||
(`operator.approvals`, `operator.read`,
|
||||
`operator.talk.secrets`, `operator.write`). وتظل عمليات التحقق من نطاقات التمهيد
|
||||
مسبوقة بالدور: لا تلبّي إدخالات المشغّل إلا طلبات المشغّل، وما زالت الأدوار غير المشغّلة
|
||||
تحتاج إلى نطاقات تحت بادئة دورها الخاصة.
|
||||
|
||||
### مثال للعقدة
|
||||
### مثال على عقدة
|
||||
|
||||
```json
|
||||
{
|
||||
@ -174,18 +186,18 @@ Gateway → العميل:
|
||||
|
||||
## التأطير
|
||||
|
||||
- **الطلب**: `{type:"req", id, method, params}`
|
||||
- **الاستجابة**: `{type:"res", id, ok, payload|error}`
|
||||
- **الحدث**: `{type:"event", event, payload, seq?, stateVersion?}`
|
||||
- **طلب**: `{type:"req", id, method, params}`
|
||||
- **استجابة**: `{type:"res", id, ok, payload|error}`
|
||||
- **حدث**: `{type:"event", event, payload, seq?, stateVersion?}`
|
||||
|
||||
تتطلب الطرق ذات الآثار الجانبية **مفاتيح idempotency** (راجع المخطط).
|
||||
تتطلب الأساليب ذات الآثار الجانبية **مفاتيح idempotency** (راجع المخطط).
|
||||
|
||||
## الأدوار + النطاقات
|
||||
|
||||
### الأدوار
|
||||
|
||||
- `operator` = عميل مستوى التحكم (CLI/UI/الأتمتة).
|
||||
- `node` = مضيف القدرات (camera/screen/canvas/system.run).
|
||||
- `node` = مضيف الإمكانات (camera/screen/canvas/system.run).
|
||||
|
||||
### النطاقات (`operator`)
|
||||
|
||||
@ -201,321 +213,320 @@ Gateway → العميل:
|
||||
يتطلب `talk.config` مع `includeSecrets: true` النطاق `operator.talk.secrets`
|
||||
(أو `operator.admin`).
|
||||
|
||||
قد تطلب طرق Gateway RPC المسجلة من Plugin نطاق مشغّل خاصًا بها، لكن بادئات
|
||||
الإدارة الأساسية المحجوزة (`config.*` و`exec.approvals.*` و`wizard.*` و`update.*`)
|
||||
تُحل دائمًا إلى `operator.admin`.
|
||||
قد تطلب أساليب Gateway RPC المسجّلة بواسطة Plugin نطاق مشغّل خاصًا بها، لكن
|
||||
بادئات الإدارة الأساسية المحجوزة (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) تُحل دائمًا إلى `operator.admin`.
|
||||
|
||||
نطاق الطريقة ليس سوى البوابة الأولى. بعض أوامر الشرطة المائلة التي يتم الوصول
|
||||
إليها عبر `chat.send` تطبق فحوصات أكثر صرامة على مستوى الأمر فوق ذلك. على سبيل
|
||||
المثال، تتطلب عمليات الكتابة الدائمة لـ `/config set` و`/config unset`
|
||||
النطاق `operator.admin`.
|
||||
يُعد نطاق الأسلوب هو بوابة التحقق الأولى فقط. فبعض أوامر الشرطة المائلة التي يتم الوصول إليها
|
||||
عبر `chat.send` تطبّق عمليات تحقق أكثر صرامة على مستوى الأمر فوق ذلك. على سبيل المثال،
|
||||
تتطلب عمليات الكتابة الدائمة في `/config set` و`/config unset` النطاق `operator.admin`.
|
||||
|
||||
يحتوي `node.pair.approve` أيضًا على فحص نطاق إضافي وقت الموافقة فوق نطاق الطريقة
|
||||
الأساسي:
|
||||
ويمتلك `node.pair.approve` أيضًا تحقق نطاق إضافيًا في وقت الموافقة فوق نطاق الأسلوب الأساسي:
|
||||
|
||||
- الطلبات من دون أوامر: `operator.pairing`
|
||||
- الطلبات التي تتضمن أوامر عقدة غير تنفيذية: `operator.pairing` + `operator.write`
|
||||
- الطلبات بلا أوامر: `operator.pairing`
|
||||
- الطلبات التي تحتوي على أوامر عقدة غير تنفيذية: `operator.pairing` + `operator.write`
|
||||
- الطلبات التي تتضمن `system.run` أو `system.run.prepare` أو `system.which`:
|
||||
`operator.pairing` + `operator.admin`
|
||||
|
||||
### `caps`/`commands`/`permissions` (`node`)
|
||||
|
||||
تعلن العقد مطالبات القدرات عند وقت الاتصال:
|
||||
تُصرّح العقد بادعاءات الإمكانات عند وقت الاتصال:
|
||||
|
||||
- `caps`: فئات القدرات عالية المستوى.
|
||||
- `commands`: قائمة سماح الأوامر للاستدعاء.
|
||||
- `caps`: فئات إمكانات عالية المستوى.
|
||||
- `commands`: قائمة سماح الأوامر لعملية invoke.
|
||||
- `permissions`: مفاتيح تبديل دقيقة (مثل `screen.record` و`camera.capture`).
|
||||
|
||||
يتعامل Gateway مع هذه القيم على أنها **مطالبات** ويفرض قوائم السماح على جانب الخادم.
|
||||
يتعامل Gateway مع هذه على أنها **ادعاءات** ويفرض قوائم سماح من جهة الخادم.
|
||||
|
||||
## الحضور
|
||||
|
||||
- يعيد `system-presence` إدخالات مفهرسة بحسب هوية الجهاز.
|
||||
- تتضمن إدخالات الحضور `deviceId` و`roles` و`scopes` لكي تتمكن واجهات المستخدم من عرض صف واحد لكل جهاز
|
||||
- تتضمن إدخالات الحضور `deviceId` و`roles` و`scopes` بحيث يمكن لواجهات المستخدم عرض صف واحد لكل جهاز
|
||||
حتى عندما يتصل بصفته **operator** و**node** معًا.
|
||||
|
||||
## عائلات طرق RPC الشائعة
|
||||
## عائلات أساليب RPC الشائعة
|
||||
|
||||
هذه الصفحة ليست تفريغًا مولدًا كاملًا، لكن سطح WS العام أوسع من أمثلة
|
||||
المصافحة/المصادقة الواردة أعلاه. وهذه هي عائلات الطرق الرئيسية التي يعرّضها
|
||||
Gateway اليوم.
|
||||
هذه الصفحة ليست تفريغًا كاملًا مُولّدًا، لكن سطح WS العام أوسع
|
||||
من أمثلة المصافحة/المصادقة أعلاه. وهذه هي عائلات الأساليب الرئيسية التي
|
||||
يعرّضها Gateway اليوم.
|
||||
|
||||
تُعد `hello-ok.features.methods` قائمة اكتشاف محافظة مبنية من
|
||||
`src/gateway/server-methods-list.ts` إضافةً إلى صادرات الطرق المحمّلة من
|
||||
Plugin/channel. تعامل معها على أنها لاكتشاف الميزات، لا على أنها تفريغ مولد
|
||||
لكل مساعد قابل للاستدعاء مُنفّذ في `src/gateway/server-methods/*.ts`.
|
||||
تُعد `hello-ok.features.methods` قائمة اكتشاف متحفظة مبنية من
|
||||
`src/gateway/server-methods-list.ts` بالإضافة إلى صادرات أساليب Plugins/القنوات المحمّلة.
|
||||
تعامل معها على أنها لاكتشاف الميزات، لا كتفريغ مُولّد لكل مساعد قابل للاستدعاء
|
||||
ومنفذ في `src/gateway/server-methods/*.ts`.
|
||||
|
||||
### النظام والهوية
|
||||
|
||||
- يعيد `health` لقطة الحالة الصحية المخزنة مؤقتًا لـ gateway أو التي جرى فحصها حديثًا.
|
||||
- يعيد `status` ملخص gateway بأسلوب `/status`؛ وتُضمَّن الحقول الحساسة فقط
|
||||
لعملاء المشغّل ذوي نطاق الإدارة.
|
||||
- يعيد `gateway.identity.get` هوية جهاز gateway المستخدمة في تدفقات relay
|
||||
والإقران.
|
||||
- يعيد `system-presence` لقطة الحضور الحالية للأجهزة المتصلة من نوع
|
||||
operator/node.
|
||||
- يضيف `system-event` حدث نظام ويمكنه تحديث/بث سياق الحضور.
|
||||
- يعيد `health` لقطة صحة الـ gateway المخبأة أو التي جرى فحصها حديثًا.
|
||||
- يعيد `status` ملخص الـ gateway على نمط `/status`؛ وتُضمَّن الحقول الحساسة
|
||||
فقط لعملاء المشغّل ذوي النطاق الإداري.
|
||||
- يعيد `gateway.identity.get` هوية جهاز الـ gateway المستخدمة في تدفقات relay
|
||||
والاقتران.
|
||||
- يعيد `system-presence` لقطة الحضور الحالية للأجهزة المتصلة
|
||||
من نوع operator/node.
|
||||
- يضيف `system-event` حدث نظام ويمكنه تحديث/بث سياق
|
||||
الحضور.
|
||||
- يعيد `last-heartbeat` أحدث حدث Heartbeat محفوظ.
|
||||
- يبدّل `set-heartbeats` معالجة Heartbeat على الـ gateway.
|
||||
|
||||
### النماذج والاستخدام
|
||||
|
||||
- يعيد `models.list` فهرس النماذج المسموح بها وقت التشغيل.
|
||||
- يعيد `usage.status` نوافذ استخدام المزوّد/ملخصات الحصة المتبقية.
|
||||
- يعيد `usage.status` ملخصات نوافذ استخدام المزوّد/الحصة المتبقية.
|
||||
- يعيد `usage.cost` ملخصات تكلفة الاستخدام المجمعة لنطاق زمني.
|
||||
- يعيد `doctor.memory.status` جاهزية الذاكرة المتجهية / التضمين لمساحة عمل
|
||||
الوكيل الافتراضية النشطة.
|
||||
- يعيد `doctor.memory.status` جاهزية الذاكرة المتجهية / التضمينات
|
||||
لمساحة عمل الوكيل الافتراضي النشطة.
|
||||
- يعيد `sessions.usage` ملخصات الاستخدام لكل جلسة.
|
||||
- يعيد `sessions.usage.timeseries` سلسلة زمنية للاستخدام لجلسة واحدة.
|
||||
- يعيد `sessions.usage.logs` إدخالات سجل الاستخدام لجلسة واحدة.
|
||||
|
||||
### القنوات ومساعدات تسجيل الدخول
|
||||
|
||||
- يعيد `channels.status` ملخصات حالة القنوات/Plugin المدمجة والمجمعة.
|
||||
- يسجّل `channels.logout` الخروج من قناة/حساب محدد حيث تدعم القناة
|
||||
تسجيل الخروج.
|
||||
- يبدأ `web.login.start` تدفق تسجيل دخول QR/الويب لمزوّد قناة الويب الحالي
|
||||
القادر على QR.
|
||||
- ينتظر `web.login.wait` اكتمال تدفق تسجيل دخول QR/الويب هذا ويبدأ القناة
|
||||
عند النجاح.
|
||||
- يرسل `push.test` دفعة APNs اختبارية إلى عقدة iOS مسجلة.
|
||||
- يعيد `voicewake.get` مشغلات كلمة التنبيه المخزنة.
|
||||
- يحدّث `voicewake.set` مشغلات كلمة التنبيه ويبث التغيير.
|
||||
- يعيد `channels.status` ملخصات حالة القنوات/Plugins المضمنة والمجمعة.
|
||||
- يسجّل `channels.logout` الخروج من قناة/حساب محدد حيثما كانت القناة
|
||||
تدعم تسجيل الخروج.
|
||||
- يبدأ `web.login.start` تدفق تسجيل دخول QR/ويب لمزوّد قناة الويب
|
||||
القادر على QR الحالي.
|
||||
- ينتظر `web.login.wait` اكتمال تدفق تسجيل دخول QR/ويب هذا ويبدأ
|
||||
القناة عند النجاح.
|
||||
- يرسل `push.test` إشعار APNs تجريبيًا إلى عقدة iOS مسجلة.
|
||||
- يعيد `voicewake.get` محفزات كلمات التنبيه المخزنة.
|
||||
- يحدّث `voicewake.set` محفزات كلمات التنبيه ويبث التغيير.
|
||||
|
||||
### المراسلة والسجلات
|
||||
|
||||
- يُعد `send` RPC التسليم الصادر المباشر لعمليات الإرسال المستهدفة إلى
|
||||
القناة/الحساب/المحادثة خارج مشغّل الدردشة.
|
||||
- يعيد `logs.tail` ذيل سجل ملفات gateway المهيأ مع عناصر التحكم
|
||||
cursor/limit والحد الأقصى للبايتات.
|
||||
- يُعد `send` أسلوب RPC للتسليم الصادر المباشر لعمليات الإرسال
|
||||
الموجّهة إلى قناة/حساب/محادثة خارج مشغّل الدردشة.
|
||||
- يعيد `logs.tail` ذيل سجل ملفات الـ gateway المُهيأ مع المؤشر/الحد
|
||||
وعناصر التحكم في الحد الأقصى للبايتات.
|
||||
|
||||
### Talk وTTS
|
||||
|
||||
- يعيد `talk.config` حمولة تهيئة Talk الفعالة؛ ويتطلب `includeSecrets`
|
||||
- يعيد `talk.config` حمولة إعدادات Talk الفعالة؛ ويتطلب `includeSecrets`
|
||||
النطاق `operator.talk.secrets` (أو `operator.admin`).
|
||||
- يضبط `talk.mode` حالة وضع Talk الحالية لعملاء WebChat/Control UI
|
||||
ويقوم ببثها.
|
||||
- يقوم `talk.speak` بتوليف الكلام عبر مزود كلام Talk النشط.
|
||||
- يعيد `tts.status` حالة تمكين TTS، والمزوّد النشط، ومزوّدي الاحتياط،
|
||||
وحالة تهيئة المزوّد.
|
||||
- يعيد `tts.providers` قائمة مزوّدي TTS الظاهرين.
|
||||
- يضبط `talk.mode` حالة وضع Talk الحالية ويبثها لعملاء WebChat/Control UI.
|
||||
- يُركّب `talk.speak` الكلام عبر مزوّد الكلام النشط لـ Talk.
|
||||
- يعيد `tts.status` حالة تمكين TTS، والمزوّد النشط، ومزوّدي الرجوع الاحتياطي،
|
||||
وحالة إعدادات المزوّد.
|
||||
- يعيد `tts.providers` جرد مزوّدي TTS المرئيين.
|
||||
- يبدّل `tts.enable` و`tts.disable` حالة تفضيلات TTS.
|
||||
- يحدّث `tts.setProvider` مزوّد TTS المفضل.
|
||||
- ينفّذ `tts.convert` تحويل نص إلى كلام لمرة واحدة.
|
||||
- يشغّل `tts.convert` تحويل نص إلى كلام لمرة واحدة.
|
||||
|
||||
### الأسرار والتهيئة والتحديث والمعالج
|
||||
### الأسرار والإعدادات والتحديث والمعالج
|
||||
|
||||
- يعيد `secrets.reload` حل SecretRefs النشطة ويستبدل حالة الأسرار وقت التشغيل
|
||||
- يعيد `secrets.reload` حل SecretRefs النشطة ويبدّل حالة الأسرار وقت التشغيل
|
||||
فقط عند النجاح الكامل.
|
||||
- يحل `secrets.resolve` تعيينات الأسرار المستهدفة بالأوامر لمجموعة
|
||||
- يعيد `secrets.resolve` حل تعيينات الأسرار المستهدفة للأوامر لمجموعة
|
||||
أوامر/أهداف محددة.
|
||||
- يعيد `config.get` لقطة التهيئة الحالية وقيمة hash.
|
||||
- يكتب `config.set` حمولة تهيئة تم التحقق منها.
|
||||
- يدمج `config.patch` تحديث تهيئة جزئيًا.
|
||||
- يتحقق `config.apply` من حمولة التهيئة الكاملة ويستبدلها.
|
||||
- يعيد `config.schema` حمولة مخطط التهيئة الحي المستخدم من Control UI وأدوات
|
||||
- يعيد `config.get` لقطة الإعدادات الحالية وhash الخاص بها.
|
||||
- يكتب `config.set` حمولة إعدادات تم التحقق من صحتها.
|
||||
- يدمج `config.patch` تحديث إعدادات جزئيًا.
|
||||
- يتحقق `config.apply` من حمولة الإعدادات الكاملة ويستبدلها.
|
||||
- يعيد `config.schema` حمولة مخطط الإعدادات الحية التي تستخدمها Control UI وأدوات
|
||||
CLI: المخطط، و`uiHints`، والإصدار، وبيانات التوليد الوصفية، بما في ذلك
|
||||
بيانات مخطط Plugin + channel الوصفية عندما يتمكن وقت التشغيل من تحميلها. يتضمن
|
||||
المخطط بيانات الحقول `title` / `description` المشتقة من نفس التسميات
|
||||
ونصوص المساعدة التي تستخدمها واجهة المستخدم، بما في ذلك الفروع المتداخلة
|
||||
للكائنات، والرموز العامة، وعناصر المصفوفات، وتركيبات
|
||||
`anyOf` / `oneOf` / `allOf` عندما تتوفر وثائق مطابقة للحقول.
|
||||
- يعيد `config.schema.lookup` حمولة بحث محددة بالمسار لمسار تهيئة واحد:
|
||||
المسار المطبّع، وعقدة مخطط سطحية، و`hint` المطابق + `hintPath`،
|
||||
وملخصات الأبناء المباشرين للتنقل التفصيلي في UI/CLI.
|
||||
- تحتفظ عقد مخطط البحث بالوثائق المواجهة للمستخدم وحقول التحقق الشائعة:
|
||||
بيانات مخطط Plugin + القناة عندما يستطيع وقت التشغيل تحميلها. ويتضمن المخطط
|
||||
بيانات `title` / `description` للحقل المستمدة من نفس التسميات
|
||||
ونصوص المساعدة المستخدمة في واجهة المستخدم، بما في ذلك الكائنات المتداخلة،
|
||||
وعناصر wildcard، وعناصر المصفوفات، وفروع التركيب `anyOf` / `oneOf` / `allOf`
|
||||
عندما توجد وثائق حقل مطابقة.
|
||||
- يعيد `config.schema.lookup` حمولة بحث مقيّدة بالمسار لمسار إعدادات
|
||||
واحد: المسار الموحّد، وعقدة مخطط سطحية، و`hint` المطابق + `hintPath`،
|
||||
وملخصات الأبناء المباشرين للتنقل المتدرج في UI/CLI.
|
||||
- تحتفظ عقد مخطط البحث بالتوثيق المواجه للمستخدم وحقول التحقق الشائعة:
|
||||
`title` و`description` و`type` و`enum` و`const` و`format` و`pattern`،
|
||||
وحدود الأرقام/السلاسل/المصفوفات/الكائنات، وأعلام منطقية مثل
|
||||
`additionalProperties` و`deprecated` و`readOnly` و`writeOnly`.
|
||||
- تعرض ملخصات الأبناء `key` و`path` المطبّع و`type` و`required` و`hasChildren`،
|
||||
- تعرض ملخصات الأبناء `key` و`path` الموحّد و`type` و`required` و`hasChildren`،
|
||||
بالإضافة إلى `hint` / `hintPath` المطابقين.
|
||||
- يشغّل `update.run` تدفق تحديث gateway ويجدول إعادة تشغيل فقط عندما
|
||||
- يشغّل `update.run` تدفق تحديث الـ gateway ويجدول إعادة تشغيل فقط عندما
|
||||
ينجح التحديث نفسه.
|
||||
- توفّر `wizard.start` و`wizard.next` و`wizard.status` و`wizard.cancel`
|
||||
معالج الإعداد الأولي عبر WS RPC.
|
||||
- تعرض `wizard.start` و`wizard.next` و`wizard.status` و`wizard.cancel`
|
||||
معالج الإعداد الأوّلي عبر WS RPC.
|
||||
|
||||
### العائلات الرئيسية الحالية
|
||||
|
||||
#### مساعدات الوكيل ومساحة العمل
|
||||
|
||||
- يعيد `agents.list` إدخالات الوكلاء المهيأة.
|
||||
- يعيد `agents.list` إدخالات الوكلاء المُهيأة.
|
||||
- تدير `agents.create` و`agents.update` و`agents.delete` سجلات الوكلاء
|
||||
وربط مساحة العمل.
|
||||
- تدير `agents.files.list` و`agents.files.get` و`agents.files.set` ملفات
|
||||
مساحة عمل bootstrap المكشوفة لوكيل.
|
||||
- يعيد `agent.identity.get` هوية المساعد الفعالة لوكيل أو جلسة.
|
||||
- ينتظر `agent.wait` انتهاء التشغيل ويعيد اللقطة الطرفية عند توفرها.
|
||||
مساحة العمل الخاصة بالتمهيد المعروضة لوكيل.
|
||||
- يعيد `agent.identity.get` هوية المساعد الفعالة لوكيل أو
|
||||
جلسة.
|
||||
- ينتظر `agent.wait` اكتمال التشغيل ويعيد اللقطة النهائية عند
|
||||
توفرها.
|
||||
|
||||
#### التحكم في الجلسة
|
||||
|
||||
- يعيد `sessions.list` فهرس الجلسات الحالي.
|
||||
- يبدّل `sessions.subscribe` و`sessions.unsubscribe` اشتراكات أحداث تغيّر الجلسة
|
||||
- يبدّل `sessions.subscribe` و`sessions.unsubscribe` اشتراكات أحداث تغيّر الجلسات
|
||||
لعميل WS الحالي.
|
||||
- يبدّل `sessions.messages.subscribe` و`sessions.messages.unsubscribe`
|
||||
اشتراكات أحداث النصوص/الرسائل لجلسة واحدة.
|
||||
- يعيد `sessions.preview` معاينات نصوص مقيدة لمفاتيح جلسات محددة.
|
||||
- يقوم `sessions.resolve` بحل هدف جلسة أو جعله بالشكل القياسي.
|
||||
- يعيد `sessions.preview` معاينات نصوص محصورة لمفاتيح جلسات
|
||||
محددة.
|
||||
- يحل `sessions.resolve` هدف جلسة أو يوحّده.
|
||||
- ينشئ `sessions.create` إدخال جلسة جديدًا.
|
||||
- يرسل `sessions.send` رسالة إلى جلسة موجودة.
|
||||
- يُعد `sessions.steer` صيغة المقاطعة وإعادة التوجيه لجلسة نشطة.
|
||||
- يوقف `sessions.abort` العمل النشط لجلسة ما.
|
||||
- يحدّث `sessions.patch` بيانات تعريف الجلسة/التجاوزات.
|
||||
- تنفّذ `sessions.reset` و`sessions.delete` و`sessions.compact`
|
||||
صيانة الجلسة.
|
||||
- يعيد `sessions.get` صف الجلسة المخزّن الكامل.
|
||||
- لا يزال تنفيذ الدردشة يستخدم `chat.history` و`chat.send` و`chat.abort` و
|
||||
- يحدّث `sessions.patch` بيانات الجلسة الوصفية/التجاوزات.
|
||||
- تنفّذ `sessions.reset` و`sessions.delete` و`sessions.compact` صيانة
|
||||
الجلسة.
|
||||
- يعيد `sessions.get` صف الجلسة المخزن كاملًا.
|
||||
- ما زال تنفيذ الدردشة يستخدم `chat.history` و`chat.send` و`chat.abort` و
|
||||
`chat.inject`.
|
||||
- جرى تطبيع `chat.history` للعرض لعملاء UI: تُزال وسوم التوجيه المضمنة من
|
||||
النص المرئي، وتُزال حمولات XML النصية العادية لاستدعاء الأدوات (بما في ذلك
|
||||
`<tool_call>...</tool_call>` و`<function_call>...</function_call>` و
|
||||
`<tool_calls>...</tool_calls>` و`<function_calls>...</function_calls>` و
|
||||
كتل استدعاء الأدوات المقتطعة)، كما تُزال رموز التحكم بالنموذج المتسربة
|
||||
بنمط ASCII/العرض الكامل، وتُحذف صفوف المساعد التي تتكون فقط من رموز صامتة
|
||||
مثل `NO_REPLY` / `no_reply` تمامًا، ويمكن استبدال الصفوف كبيرة الحجم
|
||||
بعناصر نائبة.
|
||||
- يُطبَّع `chat.history` للعرض لعملاء UI: تُزال وسوم التوجيه المضمنة من
|
||||
النص المرئي، وتُزال حمولات XML الخاصة باستدعاء الأدوات بالنص العادي (بما في ذلك
|
||||
`<tool_call>...</tool_call>` و`<function_call>...</function_call>`،
|
||||
و`<tool_calls>...</tool_calls>` و`<function_calls>...</function_calls>`،
|
||||
وكتل استدعاء الأدوات المبتورة) ورموز التحكم الخاصة بالنموذج المتسربة بصيغة ASCII/العرض الكامل،
|
||||
وتُحذف صفوف المساعد التي تحتوي فقط على رموز صامتة مثل `NO_REPLY` /
|
||||
`no_reply` تمامًا، ويمكن استبدال الصفوف كبيرة الحجم بعناصر نائبة.
|
||||
|
||||
#### إقران الأجهزة ورموز الأجهزة المميزة
|
||||
#### اقتران الأجهزة ورموز الأجهزة
|
||||
|
||||
- يعيد `device.pair.list` الأجهزة المقترنة المعلقة والموافق عليها.
|
||||
- تدير `device.pair.approve` و`device.pair.reject` و`device.pair.remove`
|
||||
سجلات إقران الأجهزة.
|
||||
- يقوم `device.token.rotate` بتدوير رمز جهاز مقترن ضمن حدود الدور
|
||||
والنطاق الموافق عليهما.
|
||||
- يلغي `device.token.revoke` رمز جهاز مقترن.
|
||||
سجلات اقتران الأجهزة.
|
||||
- يدوّر `device.token.rotate` رمز جهاز مقترن ضمن حدود
|
||||
الدور والنطاق الموافق عليهما.
|
||||
- يلغي `device.token.revoke` رمز جهاز مقترنًا.
|
||||
|
||||
#### إقران العقد والاستدعاء والعمل المعلّق
|
||||
#### اقتران العقدة والاستدعاء والعمل المعلّق
|
||||
|
||||
- تغطي `node.pair.request` و`node.pair.list` و`node.pair.approve` و
|
||||
`node.pair.reject` و`node.pair.verify` إقران العقد والتحقق من bootstrap.
|
||||
- يعيد `node.list` و`node.describe` حالة العقد المعروفة/المتصلة.
|
||||
`node.pair.reject` و`node.pair.verify` اقتران العقدة والتحقق من
|
||||
التمهيد.
|
||||
- يعيد `node.list` و`node.describe` حالة العقدة المعروفة/المتصلة.
|
||||
- يحدّث `node.rename` تسمية عقدة مقترنة.
|
||||
- يمرر `node.invoke` أمرًا إلى عقدة متصلة.
|
||||
- يعيد `node.invoke.result` نتيجة طلب استدعاء.
|
||||
- يحمل `node.event` الأحداث الصادرة من العقدة عائدًا إلى gateway.
|
||||
- يحدّث `node.canvas.capability.refresh` رموز canvas المميزة ذات النطاق المحدد.
|
||||
- تُعد `node.pending.pull` و`node.pending.ack` واجهات API لطابور
|
||||
العقدة المتصلة.
|
||||
- تدير `node.pending.enqueue` و`node.pending.drain` العمل المعلق الدائم
|
||||
للعقد غير المتصلة/غير المتاحة.
|
||||
- يحمل `node.event` الأحداث الصادرة من العقدة إلى الـ gateway.
|
||||
- يجدّد `node.canvas.capability.refresh` رموز إمكانات canvas
|
||||
المقيّدة.
|
||||
- تُعد `node.pending.pull` و`node.pending.ack` واجهات API لطابور العقدة
|
||||
المتصلة.
|
||||
- تدير `node.pending.enqueue` و`node.pending.drain` العمل المعلّق المتين
|
||||
للعقد غير المتصلة/غير المتصلة حاليًا.
|
||||
|
||||
#### عائلات الموافقات
|
||||
|
||||
- تغطي `exec.approval.request` و`exec.approval.get` و`exec.approval.list` و
|
||||
`exec.approval.resolve` طلبات موافقة exec لمرة واحدة إضافةً إلى
|
||||
`exec.approval.resolve` طلبات موافقة التنفيذ لمرة واحدة بالإضافة إلى
|
||||
البحث/إعادة التشغيل للموافقات المعلقة.
|
||||
- ينتظر `exec.approval.waitDecision` قرار موافقة exec واحدًا معلقًا ويعيد
|
||||
- ينتظر `exec.approval.waitDecision` قرار موافقة تنفيذ واحدة معلقة ويعيد
|
||||
القرار النهائي (أو `null` عند انتهاء المهلة).
|
||||
- تدير `exec.approvals.get` و`exec.approvals.set` لقطات سياسة موافقة exec
|
||||
الخاصة بـ gateway.
|
||||
- تدير `exec.approvals.node.get` و`exec.approvals.node.set` سياسة موافقة exec
|
||||
- تدير `exec.approvals.get` و`exec.approvals.set` لقطات سياسة موافقات
|
||||
التنفيذ في الـ gateway.
|
||||
- تدير `exec.approvals.node.get` و`exec.approvals.node.set` سياسة موافقات التنفيذ
|
||||
المحلية للعقدة عبر أوامر relay الخاصة بالعقدة.
|
||||
- تغطي `plugin.approval.request` و`plugin.approval.list` و
|
||||
`plugin.approval.waitDecision` و`plugin.approval.resolve`
|
||||
تدفقات الموافقة المعرّفة من Plugin.
|
||||
تدفقات الموافقات التي يعرّفها Plugin.
|
||||
|
||||
#### عائلات رئيسية أخرى
|
||||
|
||||
- الأتمتة:
|
||||
- يجدول `wake` حقن نص تنبيه فوريًا أو عند Heartbeat التالي
|
||||
- `cron.list` و`cron.status` و`cron.add` و`cron.update` و`cron.remove` و
|
||||
`cron.run` و`cron.runs`
|
||||
- يجدول `wake` إدخال نص تنبيه فوري أو عند Heartbeat التالي
|
||||
- `cron.list` و`cron.status` و`cron.add` و`cron.update` و`cron.remove`،
|
||||
و`cron.run` و`cron.runs`
|
||||
- Skills/الأدوات: `commands.list` و`skills.*` و`tools.catalog` و`tools.effective`
|
||||
|
||||
### عائلات الأحداث الشائعة
|
||||
|
||||
- `chat`: تحديثات دردشة UI مثل `chat.inject` وأحداث الدردشة الأخرى الخاصة
|
||||
بالنص فقط.
|
||||
- `session.message` و`session.tool`: تحديثات النص/تدفق الأحداث لجلسة
|
||||
مشترَك فيها.
|
||||
- `chat`: تحديثات دردشة UI مثل `chat.inject` وغيرها من
|
||||
أحداث الدردشة الخاصة بالنص فقط.
|
||||
- `session.message` و`session.tool`: تحديثات النص/دفق الأحداث لجلسة
|
||||
مشترَك بها.
|
||||
- `sessions.changed`: تغيّر فهرس الجلسات أو بياناتها الوصفية.
|
||||
- `presence`: تحديثات لقطة حضور النظام.
|
||||
- `tick`: حدث keepalive / liveliness دوري.
|
||||
- `health`: تحديث لقطة سلامة gateway.
|
||||
- `heartbeat`: تحديث تدفق أحداث Heartbeat.
|
||||
- `tick`: حدث keepalive / حيوية دوري.
|
||||
- `health`: تحديث لقطة صحة الـ gateway.
|
||||
- `heartbeat`: تحديث دفق أحداث Heartbeat.
|
||||
- `cron`: حدث تغيّر تشغيل/مهمة Cron.
|
||||
- `shutdown`: إشعار إيقاف تشغيل gateway.
|
||||
- `node.pair.requested` / `node.pair.resolved`: دورة حياة إقران العقدة.
|
||||
- `node.invoke.request`: بث طلب استدعاء العقدة.
|
||||
- `shutdown`: إشعار إيقاف الـ gateway.
|
||||
- `node.pair.requested` / `node.pair.resolved`: دورة حياة اقتران العقدة.
|
||||
- `node.invoke.request`: بث طلب استدعاء عقدة.
|
||||
- `device.pair.requested` / `device.pair.resolved`: دورة حياة الجهاز المقترن.
|
||||
- `voicewake.changed`: تغيّرت تهيئة مشغّل كلمة التنبيه.
|
||||
- `voicewake.changed`: تغيّر إعدادات محفز كلمات التنبيه.
|
||||
- `exec.approval.requested` / `exec.approval.resolved`: دورة حياة
|
||||
موافقة exec.
|
||||
موافقة التنفيذ.
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved`: دورة حياة موافقة
|
||||
Plugin.
|
||||
|
||||
### طرق مساعدة العقدة
|
||||
### أساليب مساعدة العقدة
|
||||
|
||||
- يمكن للعقد استدعاء `skills.bins` لجلب القائمة الحالية للملفات التنفيذية الخاصة بـ Skills
|
||||
للتحقق من السماح التلقائي.
|
||||
من أجل عمليات التحقق التلقائية من السماح.
|
||||
|
||||
### طرق مساعدة المشغّل
|
||||
### أساليب مساعدة المشغّل
|
||||
|
||||
- يمكن للمشغّلين استدعاء `commands.list` (`operator.read`) لجلب قائمة الأوامر
|
||||
وقت التشغيل لوكيل.
|
||||
- يمكن للمشغّلين استدعاء `commands.list` (`operator.read`) لجلب مخزون الأوامر وقت التشغيل
|
||||
لوكيل ما.
|
||||
- `agentId` اختياري؛ احذفه لقراءة مساحة عمل الوكيل الافتراضية.
|
||||
- يتحكم `scope` في السطح الذي يستهدفه `name` الأساسي:
|
||||
- يعيد `text` رمز الأمر النصي الأساسي من دون الشرطة المائلة `/`
|
||||
- يعيد `native` ومسار `both` الافتراضي أسماء أصلية مدركة للمزوّد
|
||||
- يعيد `text` رمز أمر النص الأساسي دون الشرطة المائلة البادئة `/`
|
||||
- يعيد `native` ومسار `both` الافتراضي أسماء native المدركة للمزوّد
|
||||
عند توفرها
|
||||
- يحمل `textAliases` الأسماء المستعارة الدقيقة ذات الشرطة المائلة مثل
|
||||
`/model` و`/m`.
|
||||
- يحمل `nativeName` اسم الأمر الأصلي المدرك للمزوّد عندما يكون موجودًا.
|
||||
- `provider` اختياري ولا يؤثر إلا في التسمية الأصلية وإتاحة أوامر Plugin
|
||||
الأصلية.
|
||||
- يؤدي `includeArgs=false` إلى حذف بيانات الوسائط التسلسلية من الاستجابة.
|
||||
- يمكن للمشغّلين استدعاء `tools.catalog` (`operator.read`) لجلب فهرس الأدوات وقت التشغيل لوكيل.
|
||||
تتضمن الاستجابة أدوات مجمعة وبيانات تعريف المصدر:
|
||||
- يحمل `textAliases` الأسماء المستعارة الدقيقة ذات الشرطة المائلة مثل `/model` و`/m`.
|
||||
- يحمل `nativeName` اسم الأمر native المدرك للمزوّد عندما يوجد.
|
||||
- `provider` اختياري ويؤثر فقط في التسمية native وتوفر أوامر Plugin
|
||||
native.
|
||||
- يؤدي `includeArgs=false` إلى حذف بيانات الوسائط المسلسلة من الاستجابة.
|
||||
- يمكن للمشغّلين استدعاء `tools.catalog` (`operator.read`) لجلب فهرس الأدوات وقت التشغيل لوكيل
|
||||
ما. وتتضمن الاستجابة أدوات مجمّعة وبيانات وصفية للمصدر:
|
||||
- `source`: `core` أو `plugin`
|
||||
- `pluginId`: مالك Plugin عندما تكون `source="plugin"`
|
||||
- `pluginId`: مالك Plugin عندما يكون `source="plugin"`
|
||||
- `optional`: ما إذا كانت أداة Plugin اختيارية
|
||||
- يمكن للمشغّلين استدعاء `tools.effective` (`operator.read`) لجلب فهرس الأدوات الفعّال
|
||||
وقت التشغيل لجلسة.
|
||||
- يمكن للمشغّلين استدعاء `tools.effective` (`operator.read`) لجلب
|
||||
مخزون الأدوات الفعّال وقت التشغيل لجلسة ما.
|
||||
- `sessionKey` مطلوب.
|
||||
- يستخلص gateway سياق وقت تشغيل موثوقًا من الجلسة على جانب الخادم بدلًا من قبول
|
||||
سياق المصادقة أو التسليم المزوَّد من المستدعي.
|
||||
- تكون الاستجابة ذات نطاق جلسة وتعكس ما يمكن للمحادثة النشطة استخدامه الآن،
|
||||
بما في ذلك أدوات core وPlugin وchannel.
|
||||
- يمكن للمشغّلين استدعاء `skills.status` (`operator.read`) لجلب قائمة
|
||||
Skills المرئية لوكيل.
|
||||
- يستمد الـ gateway سياق وقت تشغيل موثوقًا من الجلسة من جهة الخادم بدلًا من قبول
|
||||
سياق مصادقة أو تسليم يزوّده المستدعي.
|
||||
- تكون الاستجابة مقيّدة بالجلسة وتعكس ما يمكن للمحادثة النشطة استخدامه الآن،
|
||||
بما في ذلك أدوات core وPlugin والقناة.
|
||||
- يمكن للمشغّلين استدعاء `skills.status` (`operator.read`) لجلب
|
||||
مخزون Skills المرئي لوكيل.
|
||||
- `agentId` اختياري؛ احذفه لقراءة مساحة عمل الوكيل الافتراضية.
|
||||
- تتضمن الاستجابة الأهلية، والمتطلبات الناقصة، وفحوصات التهيئة،
|
||||
وخيارات التثبيت المنقحة من دون كشف قيم الأسرار الخام.
|
||||
- يمكن للمشغّلين استدعاء `skills.search` و`skills.detail` (`operator.read`) لبيانات
|
||||
اكتشاف ClawHub الوصفية.
|
||||
- تتضمن الاستجابة الأهلية، والمتطلبات المفقودة، وعمليات تحقق الإعدادات،
|
||||
وخيارات التثبيت المنقحة دون كشف القيم السرية الخام.
|
||||
- يمكن للمشغّلين استدعاء `skills.search` و`skills.detail` (`operator.read`) للحصول على
|
||||
بيانات الاكتشاف الوصفية لـ ClawHub.
|
||||
- يمكن للمشغّلين استدعاء `skills.install` (`operator.admin`) في وضعين:
|
||||
- وضع ClawHub: يثبّت `{ source: "clawhub", slug, version?, force? }`
|
||||
مجلد skill في دليل `skills/` الخاص بمساحة عمل الوكيل الافتراضية.
|
||||
- وضع مُثبّت Gateway: يشغّل `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
|
||||
إجراء `metadata.openclaw.install` مُعلنًا على مضيف gateway.
|
||||
- وضع ClawHub: `{ source: "clawhub", slug, version?, force? }` يثبّت
|
||||
مجلد Skill في دليل `skills/` الخاص بمساحة عمل الوكيل الافتراضية.
|
||||
- وضع مُثبّت Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
|
||||
يشغّل إجراء `metadata.openclaw.install` مُعلَنًا على مضيف الـ gateway.
|
||||
- يمكن للمشغّلين استدعاء `skills.update` (`operator.admin`) في وضعين:
|
||||
- يحدّث وضع ClawHub معرّف slug متتبعًا واحدًا أو جميع تثبيتات ClawHub
|
||||
المتتبعة في مساحة عمل الوكيل الافتراضية.
|
||||
- يقوم وضع التهيئة بترقيع قيم `skills.entries.<skillKey>` مثل `enabled`
|
||||
و`apiKey` و`env`.
|
||||
- يحدّث وضع ClawHub slug واحدًا متتبَّعًا أو جميع عمليات تثبيت ClawHub المتتبعة في
|
||||
مساحة عمل الوكيل الافتراضية.
|
||||
- يقوم وضع الإعدادات بترقيع قيم `skills.entries.<skillKey>` مثل `enabled`،
|
||||
و`apiKey`، و`env`.
|
||||
|
||||
## موافقات Exec
|
||||
## موافقات التنفيذ
|
||||
|
||||
- عندما يحتاج طلب exec إلى موافقة، يبث gateway الحدث `exec.approval.requested`.
|
||||
- يحل عملاء المشغّل ذلك عبر استدعاء `exec.approval.resolve` (ويتطلب النطاق `operator.approvals`).
|
||||
- بالنسبة إلى `host=node`، يجب أن يتضمن `exec.approval.request` القيمة `systemRunPlan`
|
||||
(القيَم القياسية `argv`/`cwd`/`rawCommand`/بيانات تعريف الجلسة). وتُرفض الطلبات
|
||||
التي تفتقد `systemRunPlan`.
|
||||
- عندما يحتاج طلب تنفيذ إلى موافقة، يبث الـ gateway `exec.approval.requested`.
|
||||
- يحل عملاء المشغّل ذلك عبر استدعاء `exec.approval.resolve` (يتطلب النطاق `operator.approvals`).
|
||||
- بالنسبة إلى `host=node`، يجب أن يتضمن `exec.approval.request` الحقل `systemRunPlan` (الحقول القياسية `argv`/`cwd`/`rawCommand`/بيانات الجلسة الوصفية). وتُرفض الطلبات التي تفتقد `systemRunPlan`.
|
||||
- بعد الموافقة، تعيد استدعاءات `node.invoke system.run` الممررة استخدام
|
||||
`systemRunPlan` القياسي هذا بوصفه السياق المرجعي للأمر/`cwd`/الجلسة.
|
||||
`systemRunPlan` القياسي هذا باعتباره السياق المعتمد للأمر/`cwd`/الجلسة.
|
||||
- إذا عدّل مستدعٍ `command` أو`rawCommand` أو`cwd` أو`agentId` أو
|
||||
`sessionKey` بين التحضير وتمرير `system.run` الموافق عليه نهائيًا،
|
||||
يرفض gateway التشغيل بدلًا من الوثوق بالحمولة المعدلة.
|
||||
`sessionKey` بين التحضير والتمرير النهائي الموافق عليه لـ `system.run`، فإن
|
||||
الـ gateway يرفض التشغيل بدلًا من الثقة بالحمولة المعدّلة.
|
||||
|
||||
## بديل تسليم الوكيل
|
||||
## الرجوع الاحتياطي لتسليم الوكيل
|
||||
|
||||
- يمكن أن تتضمن طلبات `agent` القيمة `deliver=true` لطلب تسليم صادر.
|
||||
- يحافظ `bestEffortDeliver=false` على السلوك الصارم: تعيد أهداف التسليم غير المحلولة أو الداخلية فقط القيمة `INVALID_REQUEST`.
|
||||
- يسمح `bestEffortDeliver=true` بالرجوع إلى التنفيذ ضمن الجلسة فقط عندما يتعذر حل مسار خارجي قابل للتسليم (على سبيل المثال جلسات internal/webchat أو إعدادات متعددة القنوات ملتبسة).
|
||||
- يمكن أن تتضمن طلبات `agent` الحقل `deliver=true` لطلب التسليم الصادر.
|
||||
- يُبقي `bestEffortDeliver=false` السلوك الصارم: إذ تُرجع أهداف التسليم غير المحلولة أو الداخلية فقط `INVALID_REQUEST`.
|
||||
- يسمح `bestEffortDeliver=true` بالرجوع الاحتياطي إلى التنفيذ على مستوى الجلسة عندما لا يمكن حل أي مسار تسليم خارجي قابل للتسليم (مثلًا جلسات internal/webchat أو إعدادات متعددة القنوات ملتبسة).
|
||||
|
||||
## إدارة الإصدارات
|
||||
## إصدار النسخ
|
||||
|
||||
- يوجد `PROTOCOL_VERSION` في `src/gateway/protocol/schema/protocol-schemas.ts`.
|
||||
- يرسل العملاء `minProtocol` + `maxProtocol`؛ ويرفض الخادم حالات عدم التطابق.
|
||||
- يرسل العملاء `minProtocol` و`maxProtocol`؛ ويرفض الخادم حالات عدم التطابق.
|
||||
- تُولَّد المخططات + النماذج من تعريفات TypeBox:
|
||||
- `pnpm protocol:gen`
|
||||
- `pnpm protocol:gen:swift`
|
||||
@ -524,116 +535,116 @@ Plugin/channel. تعامل معها على أنها لاكتشاف الميزا
|
||||
### ثوابت العميل
|
||||
|
||||
يستخدم العميل المرجعي في `src/gateway/client.ts` هذه القيم الافتراضية. وهذه القيم
|
||||
مستقرة عبر البروتوكول v3 وهي خط الأساس المتوقع لعملاء الجهات الخارجية.
|
||||
مستقرة عبر البروتوكول v3 وهي خط الأساس المتوقع للعملاء من الجهات الخارجية.
|
||||
|
||||
| الثابت | الافتراضي | المصدر |
|
||||
| --- | --- | --- |
|
||||
| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |
|
||||
| مهلة الطلب (لكل RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) |
|
||||
| مهلة ما قبل المصادقة / تحدي الاتصال | `10_000` ms | `src/gateway/handshake-timeouts.ts` (التقييد `250`–`10_000`) |
|
||||
| مهلة التراجع الأولية لإعادة الاتصال | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
|
||||
| الحد الأقصى لمهلة التراجع لإعادة الاتصال | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
|
||||
| تقييد إعادة المحاولة السريعة بعد إغلاق رمز الجهاز المميز | `250` ms | `src/gateway/client.ts` |
|
||||
| التراجع الأولي لإعادة الاتصال | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
|
||||
| الحد الأقصى للتراجع لإعادة الاتصال | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
|
||||
| تقييد إعادة المحاولة السريعة بعد إغلاق رمز الجهاز | `250` ms | `src/gateway/client.ts` |
|
||||
| مهلة السماح قبل `terminate()` في الإيقاف القسري | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
|
||||
| المهلة الافتراضية لـ `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |
|
||||
| الفاصل الزمني الافتراضي لـ tick (قبل `hello-ok`) | `30_000` ms | `src/gateway/client.ts` |
|
||||
| إغلاق مهلة tick | الرمز `4000` عندما يتجاوز الصمت `tickIntervalMs * 2` | `src/gateway/client.ts` |
|
||||
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` |
|
||||
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` |
|
||||
|
||||
يعلن الخادم عن القيم الفعالة `policy.tickIntervalMs` و`policy.maxPayload`
|
||||
و`policy.maxBufferedBytes` في `hello-ok`؛ ويجب على العملاء الالتزام بهذه القيم
|
||||
يعلن الخادم عن القيم الفعالة لـ `policy.tickIntervalMs` و`policy.maxPayload`
|
||||
و`policy.maxBufferedBytes` في `hello-ok`؛ ويجب على العملاء احترام هذه القيم
|
||||
بدلًا من القيم الافتراضية السابقة للمصافحة.
|
||||
|
||||
## المصادقة
|
||||
|
||||
- تستخدم مصادقة Gateway ذات السر المشترك `connect.params.auth.token` أو
|
||||
`connect.params.auth.password`، بحسب وضع المصادقة المهيأ.
|
||||
- الأوضاع الحاملة للهوية مثل Tailscale Serve
|
||||
- تستخدم مصادقة الـ gateway ذات السر المشترك `connect.params.auth.token` أو
|
||||
`connect.params.auth.password`، بحسب وضع المصادقة المُهيأ.
|
||||
- أوضاع حمل الهوية مثل Tailscale Serve
|
||||
(`gateway.auth.allowTailscale: true`) أو
|
||||
`gateway.auth.mode: "trusted-proxy"` غير المعتمد على loopback
|
||||
تستوفي فحص مصادقة الاتصال من ترويسات الطلب بدلًا من `connect.params.auth.*`.
|
||||
- يتجاوز `gateway.auth.mode: "none"` الخاص بالإدخال الخاص مصادقة الاتصال
|
||||
ذات السر المشترك بالكامل؛ لا تعرّض هذا الوضع على إدخال عام/غير موثوق.
|
||||
- بعد الإقران، يُصدر Gateway **رمز جهاز مميزًا** ذا نطاق محدد بحسب دور الاتصال + نطاقاته.
|
||||
ويُعاد ضمن `hello-ok.auth.deviceToken` ويجب أن يحتفظ به العميل
|
||||
للاتصالات المستقبلية.
|
||||
- يجب على العملاء حفظ `hello-ok.auth.deviceToken` الأساسي بعد أي
|
||||
تستوفي فحص مصادقة الاتصال من
|
||||
ترويسات الطلب بدلًا من `connect.params.auth.*`.
|
||||
- يتجاوز `gateway.auth.mode: "none"` على ingress الخاص مصادقة الاتصال ذات السر المشترك
|
||||
بالكامل؛ لا تعرض هذا الوضع على ingress عام/غير موثوق.
|
||||
- بعد الاقتران، يصدر Gateway **رمز جهاز** مقيّدًا بدور الاتصال +
|
||||
النطاقات. ويُعاد في `hello-ok.auth.deviceToken` ويجب على العميل
|
||||
الاحتفاظ به للاتصالات المستقبلية.
|
||||
- يجب على العملاء الاحتفاظ بالرمز الأساسي `hello-ok.auth.deviceToken` بعد أي
|
||||
اتصال ناجح.
|
||||
- يجب أن تؤدي إعادة الاتصال باستخدام رمز الجهاز المميز **المحفوظ** هذا أيضًا إلى إعادة استخدام
|
||||
مجموعة النطاقات الموافق عليها والمحفوظة لهذا الرمز. يحافظ ذلك على صلاحيات
|
||||
الوصول للقراءة/الفحص/الحالة التي مُنحت سابقًا ويتجنب تقليص عمليات
|
||||
إعادة الاتصال بصمت إلى نطاق إدارة ضمني أضيق فقط.
|
||||
- تجميع مصادقة الاتصال على جانب العميل (`selectConnectAuth` في
|
||||
- يجب أن تؤدي إعادة الاتصال باستخدام رمز الجهاز **المحفوظ** هذا أيضًا إلى إعادة استخدام
|
||||
مجموعة النطاقات الموافق عليها والمحفوظة لذلك الرمز. وهذا يحافظ على وصول
|
||||
القراءة/الفحص/الحالة الذي مُنح مسبقًا ويتجنب تقليص عمليات إعادة الاتصال بصمت إلى
|
||||
نطاق إداري ضمني أضيق فقط.
|
||||
- تجميع مصادقة الاتصال من جهة العميل (`selectConnectAuth` في
|
||||
`src/gateway/client.ts`):
|
||||
- `auth.password` مستقل ويُمرَّر دائمًا عند ضبطه.
|
||||
- يُملأ `auth.token` وفق ترتيب أولوية: الرمز المشترك الصريح أولًا،
|
||||
ثم `deviceToken` صريح، ثم رمز محفوظ لكل جهاز (مفهرس حسب
|
||||
- يُملأ `auth.token` بحسب أولوية الترتيب التالية: الرمز المشترك الصريح أولًا،
|
||||
ثم `deviceToken` صريح، ثم رمز محفوظ لكل جهاز (مفهرس بواسطة
|
||||
`deviceId` + `role`).
|
||||
- لا يُرسل `auth.bootstrapToken` إلا عندما لا يحل أي مما سبق قيمة
|
||||
`auth.token`. ويؤدي الرمز المشترك أو أي رمز جهاز مميز محلول إلى منعه.
|
||||
- الترقية التلقائية لرمز جهاز محفوظ في إعادة المحاولة الوحيدة
|
||||
`AUTH_TOKEN_MISMATCH` مقيّدة **بنقاط النهاية الموثوقة فقط** —
|
||||
loopback، أو `wss://` مع `tlsFingerprint` مثبت. ولا يُعد `wss://` العام
|
||||
من دون تثبيت مؤهلًا.
|
||||
- تُعد إدخالات `hello-ok.auth.deviceTokens` الإضافية رموز تسليم bootstrap.
|
||||
احتفظ بها فقط عندما يكون الاتصال قد استخدم مصادقة bootstrap على نقل موثوق
|
||||
مثل `wss://` أو loopback/local pairing.
|
||||
- إذا قدّم عميل `deviceToken` **صريحًا** أو `scopes` صريحة، فإن
|
||||
مجموعة النطاقات المطلوبة من المستدعي تبقى هي المرجع؛ ولا يُعاد استخدام
|
||||
- لا يُرسل `auth.bootstrapToken` إلا عندما لا يحل أي مما سبق
|
||||
قيمة `auth.token`. ويؤدي الرمز المشترك أو أي رمز جهاز محلول إلى منعه.
|
||||
- يخضع الترفيع التلقائي لرمز جهاز محفوظ في إعادة المحاولة الوحيدة
|
||||
`AUTH_TOKEN_MISMATCH` إلى **نقاط نهاية موثوقة فقط** —
|
||||
loopback، أو `wss://` مع `tlsFingerprint` مثبّت. ولا يُعد `wss://` العام
|
||||
دون تثبيت مؤهلًا.
|
||||
- تُعد الإدخالات الإضافية `hello-ok.auth.deviceTokens` رموز تسليم تمهيد.
|
||||
احتفظ بها فقط عندما يكون الاتصال قد استخدم مصادقة التمهيد على نقل موثوق
|
||||
مثل `wss://` أو الاقتران المحلي/loopback.
|
||||
- إذا زوّد العميل `deviceToken` **صريحًا** أو `scopes` صريحة، فإن
|
||||
مجموعة النطاقات التي طلبها المستدعي تبقى هي المعتمدة؛ ولا يُعاد استخدام
|
||||
النطاقات المخبأة إلا عندما يعيد العميل استخدام الرمز المحفوظ لكل جهاز.
|
||||
- يمكن تدوير/إبطال رموز الأجهزة عبر `device.token.rotate` و
|
||||
`device.token.revoke` (ويتطلب ذلك النطاق `operator.pairing`).
|
||||
- يظل إصدار/تدوير الرموز محصورًا ضمن مجموعة الأدوار الموافق عليها والمسجلة
|
||||
في إدخال إقران ذلك الجهاز؛ ولا يمكن لتدوير رمز أن يوسّع الجهاز إلى
|
||||
دور لم تمنحه موافقة الإقران أصلًا.
|
||||
- بالنسبة إلى جلسات رموز الأجهزة المقترنة، تكون إدارة الأجهزة محصورة ذاتيًا ما لم يكن
|
||||
لدى المستدعي أيضًا `operator.admin`: لا يمكن للمستدعين غير الإداريين
|
||||
إزالة/إبطال/تدوير إلا إدخال أجهزتهم **هم فقط**.
|
||||
- يتحقق `device.token.rotate` أيضًا من مجموعة نطاقات المشغّل المطلوبة مقارنةً بـ
|
||||
- يمكن تدوير/إلغاء رموز الأجهزة عبر `device.token.rotate` و
|
||||
`device.token.revoke` (يتطلب ذلك النطاق `operator.pairing`).
|
||||
- يبقى إصدار/تدوير الرموز مقيّدًا بمجموعة الأدوار الموافق عليها والمُسجّلة في
|
||||
إدخال اقتران ذلك الجهاز؛ ولا يمكن أن يؤدي تدوير رمز إلى توسيع الجهاز إلى
|
||||
دور لم تمنحه موافقة الاقتران أصلًا.
|
||||
- بالنسبة إلى جلسات رموز الأجهزة المقترنة، تكون إدارة الجهاز مقيّدة بالذات ما لم يكن لدى
|
||||
المستدعي أيضًا `operator.admin`: إذ لا يمكن للمستدعين غير الإداريين إزالة/إلغاء/تدوير
|
||||
إلا إدخال جهازهم **الخاص**.
|
||||
- يتحقق `device.token.rotate` أيضًا من مجموعة نطاقات المشغّل المطلوبة مقارنةً مع
|
||||
نطاقات جلسة المستدعي الحالية. ولا يمكن للمستدعين غير الإداريين تدوير رمز إلى
|
||||
مجموعة نطاقات مشغّل أوسع مما يملكونه بالفعل.
|
||||
- تتضمن حالات فشل المصادقة `error.details.code` إضافةً إلى تلميحات الاسترداد:
|
||||
- `error.details.canRetryWithDeviceToken` (قيمة منطقية)
|
||||
- `error.details.recommendedNextStep` (`retry_with_device_token`، `update_auth_configuration`، `update_auth_credentials`، `wait_then_retry`، `review_auth_configuration`)
|
||||
- تتضمن حالات فشل المصادقة `error.details.code` بالإضافة إلى تلميحات للاسترداد:
|
||||
- `error.details.canRetryWithDeviceToken` (منطقي)
|
||||
- `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`)
|
||||
- سلوك العميل عند `AUTH_TOKEN_MISMATCH`:
|
||||
- يمكن للعملاء الموثوقين محاولة إعادة واحدة محدودة باستخدام رمز محفوظ لكل جهاز.
|
||||
- إذا فشلت إعادة المحاولة هذه، يجب على العملاء إيقاف حلقات إعادة الاتصال التلقائية
|
||||
وإظهار إرشادات للإجراء المطلوب من المشغّل.
|
||||
- يمكن للعملاء الموثوقين محاولة إعادة محاولة واحدة مقيّدة باستخدام رمز محفوظ لكل جهاز.
|
||||
- إذا فشلت إعادة المحاولة هذه، يجب على العملاء إيقاف حلقات إعادة الاتصال التلقائي وعرض إرشادات لاتخاذ إجراء من المشغّل.
|
||||
|
||||
## هوية الجهاز + الإقران
|
||||
## هوية الجهاز + الاقتران
|
||||
|
||||
- يجب أن تتضمن العقد هوية جهاز ثابتة (`device.id`) مشتقة من
|
||||
- يجب أن تتضمن العقد هوية جهاز مستقرة (`device.id`) مشتقة من
|
||||
بصمة زوج مفاتيح.
|
||||
- تُصدر Gateways رموزًا مميزة لكل جهاز + دور.
|
||||
- تتطلب معرّفات الأجهزة الجديدة موافقات إقران ما لم يكن التفعيل المحلي التلقائي
|
||||
للموافقة ممكّنًا.
|
||||
- تتمحور الموافقة التلقائية على الإقران حول اتصالات loopback المحلية المباشرة.
|
||||
- يوفّر OpenClaw أيضًا مسار self-connect ضيقًا محليًا للخلفية/الحاوية
|
||||
لتدفقات المساعد الموثوق ذات السر المشترك.
|
||||
- لا تزال اتصالات tailnet أو LAN على نفس المضيف تُعامل على أنها بعيدة للإقران
|
||||
- تصدر الـ gateways رموزًا لكل جهاز + دور.
|
||||
- تتطلب معرفات الأجهزة الجديدة موافقات اقتران ما لم يكن
|
||||
القبول التلقائي المحلي مفعّلًا.
|
||||
- يتمحور القبول التلقائي للاقتران حول اتصالات loopback المحلية المباشرة.
|
||||
- يمتلك OpenClaw أيضًا مسار اتصال ذاتي ضيقًا محليًا على الخلفية/الحاوية
|
||||
لتدفقات المساعدات الموثوقة ذات السر المشترك.
|
||||
- تظل اتصالات tailnet أو LAN على نفس المضيف تُعامل على أنها بعيدة بالنسبة إلى الاقتران
|
||||
وتتطلب موافقة.
|
||||
- يجب أن تتضمن جميع عملاء WS هوية `device` أثناء `connect` (operator + node).
|
||||
- يجب على جميع عملاء WS تضمين هوية `device` أثناء `connect` (operator + node).
|
||||
يمكن لـ Control UI حذفها فقط في هذه الأوضاع:
|
||||
- `gateway.controlUi.allowInsecureAuth=true` للتوافق مع HTTP غير الآمن على localhost فقط.
|
||||
- نجاح مصادقة operator في `gateway.auth.mode: "trusted-proxy"` لـ Control UI.
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (وضع طوارئ، خفض أمني شديد).
|
||||
- يجب أن توقّع جميع الاتصالات قيمة nonce الخاصة بـ `connect.challenge` التي يوفرها الخادم.
|
||||
- `gateway.controlUi.allowInsecureAuth=true` من أجل توافق HTTP غير الآمن الخاص بـ localhost فقط.
|
||||
- نجاح مصادقة مشغّل Control UI في `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (خيار طوارئ، تخفيض أمني شديد).
|
||||
- يجب على جميع الاتصالات توقيع nonce الخاص بـ `connect.challenge` الذي يوفّره الخادم.
|
||||
|
||||
### تشخيصات ترحيل مصادقة الجهاز
|
||||
|
||||
بالنسبة إلى العملاء القدامى الذين لا يزالون يستخدمون سلوك التوقيع السابق للتحدي، يعيد `connect` الآن
|
||||
رموز التفاصيل `DEVICE_AUTH_*` ضمن `error.details.code` مع `error.details.reason` ثابتة.
|
||||
بالنسبة إلى العملاء القدامى الذين ما زالوا يستخدمون سلوك التوقيع السابق للتحدي، يعيد `connect` الآن
|
||||
رموز تفاصيل `DEVICE_AUTH_*` تحت `error.details.code` مع قيمة `error.details.reason` مستقرة.
|
||||
|
||||
أعطال الترحيل الشائعة:
|
||||
|
||||
| الرسالة | details.code | details.reason | المعنى |
|
||||
| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
|
||||
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | لم يرسل العميل `device.nonce` (أو أرسله فارغًا). |
|
||||
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | أغفل العميل `device.nonce` (أو أرسله فارغًا). |
|
||||
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | وقّع العميل باستخدام nonce قديم/خاطئ. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | لا تطابق حمولة التوقيع حمولة v2. |
|
||||
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | الطابع الزمني الموقّع خارج مقدار الانحراف المسموح. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | حمولة التوقيع لا تطابق حمولة v2. |
|
||||
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | الطابع الزمني الموقّع خارج نطاق الانحراف المسموح. |
|
||||
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | لا يطابق `device.id` بصمة المفتاح العام. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | فشل تنسيق/تطبيع المفتاح العام. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | فشل تنسيق/توحيد المفتاح العام. |
|
||||
|
||||
هدف الترحيل:
|
||||
|
||||
@ -642,17 +653,17 @@ Plugin/channel. تعامل معها على أنها لاكتشاف الميزا
|
||||
- أرسل nonce نفسه في `connect.params.device.nonce`.
|
||||
- حمولة التوقيع المفضلة هي `v3`، التي تربط `platform` و`deviceFamily`
|
||||
بالإضافة إلى حقول device/client/role/scopes/token/nonce.
|
||||
- لا تزال توقيعات `v2` القديمة مقبولة للتوافق، لكن تثبيت بيانات
|
||||
الأجهزة المقترنة الوصفية ما يزال يتحكم في سياسة الأوامر عند إعادة الاتصال.
|
||||
- تظل تواقيع `v2` القديمة مقبولة للتوافق، لكن تثبيت البيانات الوصفية للأجهزة
|
||||
المقترنة ما زال يتحكم في سياسة الأوامر عند إعادة الاتصال.
|
||||
|
||||
## TLS + التثبيت
|
||||
|
||||
- يدعم TLS اتصالات WS.
|
||||
- يمكن للعملاء اختياريًا تثبيت بصمة شهادة gateway (راجع تهيئة `gateway.tls`
|
||||
إضافةً إلى `gateway.remote.tlsFingerprint` أو خيار CLI `--tls-fingerprint`).
|
||||
- يدعم البروتوكول TLS لاتصالات WS.
|
||||
- يمكن للعملاء اختياريًا تثبيت بصمة شهادة الـ gateway (راجع إعدادات `gateway.tls`
|
||||
بالإضافة إلى `gateway.remote.tlsFingerprint` أو خيار CLI `--tls-fingerprint`).
|
||||
|
||||
## النطاق
|
||||
|
||||
يعرض هذا البروتوكول **واجهة API الكاملة لـ gateway** (الحالة، والقنوات، والنماذج، والدردشة،
|
||||
والوكيل، والجلسات، والعقد، والموافقات، وغير ذلك). ويُعرَّف السطح الدقيق بواسطة
|
||||
يكشف هذا البروتوكول **واجهة API الكاملة للـ gateway** (الحالة، والقنوات، والنماذج، والدردشة،
|
||||
والوكيل، والجلسات، والعقد، والموافقات، وما إلى ذلك). ويُعرَّف السطح الدقيق بواسطة
|
||||
مخططات TypeBox في `src/gateway/protocol/schema.ts`.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,76 +1,76 @@
|
||||
---
|
||||
read_when:
|
||||
- تنفيذ ميزات تطبيق macOS
|
||||
- تغيير دورة حياة البوابة أو جسر العقدة على macOS
|
||||
summary: التطبيق المصاحب لـ OpenClaw على macOS (شريط القوائم + وسيط البوابة)
|
||||
- تغيير دورة حياة Gateway أو ربط Node على macOS
|
||||
summary: تطبيق OpenClaw المرافق لنظام macOS (شريط القوائم + وسيط Gateway)
|
||||
title: تطبيق macOS
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T12:50:52Z"
|
||||
generated_at: "2026-04-18T07:14:53Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: bfac937e352ede495f60af47edf3b8e5caa5b692ba0ea01d9fb0de9a44bbc135
|
||||
source_hash: d637df2f73ced110223c48ea3c934045d782e150a46495f434cf924a6a00baf0
|
||||
source_path: platforms/macos.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# التطبيق المصاحب لـ OpenClaw على macOS (شريط القوائم + وسيط البوابة)
|
||||
# تطبيق OpenClaw المرافق لنظام macOS (شريط القوائم + وسيط Gateway)
|
||||
|
||||
تطبيق macOS هو **الرفيق الموجود في شريط القوائم** لـ OpenClaw. وهو يملك الأذونات،
|
||||
ويدير/يرتبط بالبوابة محليًا (launchd أو يدويًا)، ويكشف إمكانات macOS
|
||||
للوكيل باعتبارها عقدة.
|
||||
تطبيق macOS هو **التطبيق المرافق في شريط القوائم** لـ OpenClaw. وهو يتولى الأذونات،
|
||||
ويدير/يرتبط بـ Gateway محليًا (launchd أو يدويًا)، ويعرض إمكانات macOS
|
||||
للوكيل كعقدة.
|
||||
|
||||
## ما الذي يفعله
|
||||
|
||||
- يعرض إشعارات أصلية وحالة في شريط القوائم.
|
||||
- يملك مطالبات TCC (الإشعارات، وإمكانية الوصول، وتسجيل الشاشة، والميكروفون،
|
||||
والتعرّف على الكلام، وAutomation/AppleScript).
|
||||
- يشغّل البوابة أو يتصل بها (محليًا أو عن بُعد).
|
||||
- يكشف الأدوات الخاصة بـ macOS فقط (Canvas، والكاميرا، وتسجيل الشاشة، و`system.run`).
|
||||
- يبدأ خدمة مضيف العقدة المحلي في الوضع **Remote** (launchd)، ويوقفها في الوضع **Local**.
|
||||
- يمكنه استضافة **PeekabooBridge** اختياريًا لأتمتة واجهة المستخدم.
|
||||
- يثبت CLI العالمي (`openclaw`) عند الطلب عبر npm أو pnpm أو bun (يفضّل التطبيق npm، ثم pnpm، ثم bun؛ ويظل Node هو وقت تشغيل البوابة الموصى به).
|
||||
- يعرض الإشعارات الأصلية والحالة في شريط القوائم.
|
||||
- يتولى مطالبات TCC (الإشعارات، تسهيلات الاستخدام، تسجيل الشاشة، الميكروفون،
|
||||
التعرّف على الكلام، الأتمتة/AppleScript).
|
||||
- يشغّل Gateway أو يتصل به (محليًا أو عن بُعد).
|
||||
- يعرّض أدوات macOS فقط (Canvas، الكاميرا، تسجيل الشاشة، `system.run`).
|
||||
- يبدأ خدمة استضافة العقدة المحلية في وضع **remote** (launchd)، ويوقفها في وضع **local**.
|
||||
- يمكنه اختياريًا استضافة **PeekabooBridge** لأتمتة واجهة المستخدم.
|
||||
- يثبّت CLI العام (`openclaw`) عند الطلب عبر npm أو pnpm أو bun (يفضّل التطبيق npm، ثم pnpm، ثم bun؛ ويظل Node بيئة تشغيل Gateway الموصى بها).
|
||||
|
||||
## الوضع المحلي مقابل الوضع البعيد
|
||||
## وضع local مقابل remote
|
||||
|
||||
- **Local** (الافتراضي): يرتبط التطبيق ببوابة محلية قيد التشغيل إذا كانت موجودة؛
|
||||
- **Local** (الافتراضي): يرتبط التطبيق بـ Gateway محلي قيد التشغيل إذا كان موجودًا؛
|
||||
وإلا فإنه يفعّل خدمة launchd عبر `openclaw gateway install`.
|
||||
- **Remote**: يتصل التطبيق ببوابة عبر SSH/Tailscale ولا يبدأ
|
||||
عملية محلية أبدًا.
|
||||
ويبدأ التطبيق **خدمة مضيف العقدة** المحلية حتى تتمكن البوابة البعيدة من الوصول إلى هذا الـ Mac.
|
||||
ولا يقوم التطبيق بتشغيل البوابة كعملية فرعية.
|
||||
يفضّل اكتشاف البوابة الآن أسماء Tailscale MagicDNS على عناوين tailnet IP الخام،
|
||||
لذلك يتعافى تطبيق Mac بشكل أكثر موثوقية عندما تتغير عناوين tailnet IP.
|
||||
- **Remote**: يتصل التطبيق بـ Gateway عبر SSH/Tailscale ولا يبدأ أبدًا
|
||||
عملية محلية.
|
||||
يبدأ التطبيق **خدمة استضافة العقدة** المحلية حتى يتمكن Gateway البعيد من الوصول إلى هذا الـ Mac.
|
||||
لا يشغّل التطبيق Gateway كعملية فرعية.
|
||||
يفضّل اكتشاف Gateway الآن أسماء Tailscale MagicDNS بدلًا من عناوين tailnet IP الخام،
|
||||
لذا يستعيد تطبيق Mac عمله بشكل أكثر موثوقية عند تغيّر عناوين tailnet IP.
|
||||
|
||||
## التحكم في Launchd
|
||||
|
||||
يدير التطبيق LaunchAgent لكل مستخدم بالتصنيف `ai.openclaw.gateway`
|
||||
(أو `ai.openclaw.<profile>` عند استخدام `--profile`/`OPENCLAW_PROFILE`؛ ولا يزال الاسم القديم `com.openclaw.*` يُزال من التحميل).
|
||||
يدير التطبيق LaunchAgent لكل مستخدم يحمل التسمية `ai.openclaw.gateway`
|
||||
(أو `ai.openclaw.<profile>` عند استخدام `--profile`/`OPENCLAW_PROFILE`؛ ولا يزال `com.openclaw.*` القديم يُفرَّغ).
|
||||
|
||||
```bash
|
||||
launchctl kickstart -k gui/$UID/ai.openclaw.gateway
|
||||
launchctl bootout gui/$UID/ai.openclaw.gateway
|
||||
```
|
||||
|
||||
استبدل التصنيف بـ `ai.openclaw.<profile>` عند تشغيل ملف تعريف مسمى.
|
||||
استبدل التسمية بـ `ai.openclaw.<profile>` عند تشغيل ملف تعريف مُسمّى.
|
||||
|
||||
إذا لم يتم تثبيت LaunchAgent، فقم بتفعيله من التطبيق أو شغّل
|
||||
إذا لم يكن LaunchAgent مثبتًا، فقم بتمكينه من التطبيق أو شغّل
|
||||
`openclaw gateway install`.
|
||||
|
||||
## إمكانات العقدة (mac)
|
||||
## إمكانات Node (mac)
|
||||
|
||||
يعرض تطبيق macOS نفسه كعقدة. الأوامر الشائعة:
|
||||
يقدّم تطبيق macOS نفسه كعقدة. الأوامر الشائعة:
|
||||
|
||||
- Canvas: `canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*`
|
||||
- الكاميرا: `camera.snap`, `camera.clip`
|
||||
- الشاشة: `screen.record`
|
||||
- النظام: `system.run`, `system.notify`
|
||||
- Canvas: `canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*`
|
||||
- الكاميرا: `camera.snap`, `camera.clip`
|
||||
- الشاشة: `screen.snapshot`, `screen.record`
|
||||
- النظام: `system.run`, `system.notify`
|
||||
|
||||
تبلّغ العقدة عن خريطة `permissions` حتى تتمكن الوكلاء من تحديد المسموح.
|
||||
تبلّغ العقدة عن خريطة `permissions` حتى تتمكن الوكلاء من تحديد المسموح به.
|
||||
|
||||
خدمة العقدة + IPC في التطبيق:
|
||||
خدمة Node + IPC للتطبيق:
|
||||
|
||||
- عندما تكون خدمة مضيف العقدة headless قيد التشغيل (الوضع البعيد)، فإنها تتصل بـ Gateway WS كعقدة.
|
||||
- يتم تنفيذ `system.run` داخل تطبيق macOS (سياق UI/TCC) عبر مقبس Unix محلي؛ وتبقى المطالبات + المخرجات داخل التطبيق.
|
||||
- عند تشغيل خدمة استضافة العقدة بدون واجهة (وضع remote)، فإنها تتصل بـ Gateway WS كعقدة.
|
||||
- يُنفَّذ `system.run` في تطبيق macOS (سياق UI/TCC) عبر مقبس Unix محلي؛ وتبقى المطالبات والمخرجات داخل التطبيق.
|
||||
|
||||
المخطط (SCI):
|
||||
|
||||
@ -81,10 +81,10 @@ Gateway -> Node Service (WS)
|
||||
Mac App (UI + TCC + system.run)
|
||||
```
|
||||
|
||||
## موافقات Exec (system.run)
|
||||
## موافقات التنفيذ (`system.run`)
|
||||
|
||||
يتم التحكم في `system.run` بواسطة **Exec approvals** في تطبيق macOS (Settings → Exec approvals).
|
||||
وتُخزَّن إعدادات Security + ask + allowlist محليًا على الـ Mac في:
|
||||
يخضع `system.run` إلى **Exec approvals** في تطبيق macOS (الإعدادات ← Exec approvals).
|
||||
ويتم تخزين الأمان + السؤال + قائمة السماح محليًا على جهاز Mac في:
|
||||
|
||||
```
|
||||
~/.openclaw/exec-approvals.json
|
||||
@ -111,12 +111,12 @@ Gateway -> Node Service (WS)
|
||||
|
||||
ملاحظات:
|
||||
|
||||
- إدخالات `allowlist` هي أنماط glob لمسارات الملفات التنفيذية المحلولة.
|
||||
- يُعامل نص أمر shell الخام الذي يحتوي على صيغة تحكم أو توسيع خاصة بـ shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) على أنه فشل في allowlist ويتطلب موافقة صريحة (أو إدراج الملف التنفيذي الخاص بالـ shell في allowlist).
|
||||
- يؤدي اختيار “Always Allow” في المطالبة إلى إضافة ذلك الأمر إلى allowlist.
|
||||
- تتم تصفية تجاوزات البيئة في `system.run` (بحذف `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`) ثم دمجها مع بيئة التطبيق.
|
||||
- بالنسبة إلى مغلفات shell (`bash|sh|zsh ... -c/-lc`)، يتم تقليص تجاوزات البيئة الخاصة بالطلب إلى allowlist صغيرة وصريحة (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
|
||||
- بالنسبة إلى قرارات allow-always في وضع allowlist، تقوم مغلفات الإرسال المعروفة (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) بحفظ مسارات الملفات التنفيذية الداخلية بدلًا من مسارات المغلفات. وإذا لم يكن فك الالتفاف آمنًا، فلن يتم حفظ أي إدخال allowlist تلقائيًا.
|
||||
- إدخالات `allowlist` هي أنماط glob لمسارات الملفات الثنائية المحلولة.
|
||||
- يُعامل نص أمر shell الخام الذي يحتوي على صيغة تحكم أو توسيع shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) على أنه عدم تطابق مع قائمة السماح ويتطلب موافقة صريحة (أو إضافة الملف الثنائي الخاص بالـ shell إلى قائمة السماح).
|
||||
- يؤدي اختيار “السماح دائمًا” في المطالبة إلى إضافة ذلك الأمر إلى قائمة السماح.
|
||||
- تُرشَّح تجاوزات البيئة الخاصة بـ `system.run` (مع إسقاط `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`) ثم تُدمج مع بيئة التطبيق.
|
||||
- بالنسبة إلى أغلفة shell (`bash|sh|zsh ... -c/-lc`)، تُختزل تجاوزات البيئة على مستوى الطلب إلى قائمة سماح صريحة صغيرة (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
|
||||
- بالنسبة إلى قرارات السماح الدائم في وضع قائمة السماح، فإن مغلفات التوجيه المعروفة (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) تحفظ مسارات الملفات التنفيذية الداخلية بدلًا من مسارات المغلفات. وإذا لم يكن فكّ التغليف آمنًا، فلن يتم حفظ أي إدخال في قائمة السماح تلقائيًا.
|
||||
|
||||
## الروابط العميقة
|
||||
|
||||
@ -124,99 +124,99 @@ Gateway -> Node Service (WS)
|
||||
|
||||
### `openclaw://agent`
|
||||
|
||||
يشغّل طلب Gateway `agent`.
|
||||
يحفّز طلب `agent` إلى Gateway.
|
||||
__OC_I18N_900004__
|
||||
معلمات الاستعلام:
|
||||
|
||||
- `message` (مطلوب)
|
||||
- `sessionKey` (اختياري)
|
||||
- `thinking` (اختياري)
|
||||
- `deliver` / `to` / `channel` (اختيارية)
|
||||
- `deliver` / `to` / `channel` (اختياري)
|
||||
- `timeoutSeconds` (اختياري)
|
||||
- `key` (اختياري، مفتاح الوضع غير المراقب)
|
||||
- `key` (اختياري، مفتاح وضع التشغيل غير المراقب)
|
||||
|
||||
السلامة:
|
||||
الأمان:
|
||||
|
||||
- من دون `key`، يطلب التطبيق تأكيدًا.
|
||||
- من دون `key`، يفرض التطبيق حدًا قصيرًا للرسالة في مطالبة التأكيد ويتجاهل `deliver` / `to` / `channel`.
|
||||
- مع `key` صالح، يكون التشغيل غير مراقب (مقصود للأتمتة الشخصية).
|
||||
- بدون `key`، يطلب التطبيق التأكيد.
|
||||
- بدون `key`، يفرض التطبيق حدًا قصيرًا لطول الرسالة في مطالبة التأكيد ويتجاهل `deliver` / `to` / `channel`.
|
||||
- مع `key` صالح، يكون التشغيل غير مراقب (وهو مخصّص للأتمتة الشخصية).
|
||||
|
||||
## تدفق الإعداد الأولي (النموذجي)
|
||||
## تدفق الإعداد الأولي (نموذجي)
|
||||
|
||||
1. ثبّت وشغّل **OpenClaw.app**.
|
||||
2. أكمل قائمة التحقق الخاصة بالأذونات (مطالبات TCC).
|
||||
3. تأكد من أن وضع **Local** نشط وأن البوابة قيد التشغيل.
|
||||
1. ثبّت **OpenClaw.app** وشغّله.
|
||||
2. أكمل قائمة التحقق من الأذونات (مطالبات TCC).
|
||||
3. تأكد من أن وضع **Local** نشط وأن Gateway قيد التشغيل.
|
||||
4. ثبّت CLI إذا كنت تريد الوصول عبر الطرفية.
|
||||
|
||||
## موضع دليل الحالة (macOS)
|
||||
|
||||
تجنب وضع دليل حالة OpenClaw في iCloud أو مجلدات أخرى متزامنة مع السحابة.
|
||||
فالمسارات المدعومة بالمزامنة قد تضيف زمن انتقال وقد تسبب أحيانًا سباقات قفل/مزامنة للملفات في
|
||||
الجلسات وبيانات الاعتماد.
|
||||
تجنب وضع دليل حالة OpenClaw في iCloud أو أي مجلدات أخرى متزامنة عبر السحابة.
|
||||
قد تضيف المسارات المدعومة بالمزامنة زمن انتقال، وقد تتسبب أحيانًا في سباقات قفل الملفات/المزامنة
|
||||
للجلسات وبيانات الاعتماد.
|
||||
|
||||
فضّل مسار حالة محليًا غير متزامن مثل:
|
||||
يفضَّل استخدام مسار حالة محلي غير متزامن مثل:
|
||||
__OC_I18N_900005__
|
||||
إذا اكتشف `openclaw doctor` أن الحالة موجودة تحت:
|
||||
إذا اكتشف `openclaw doctor` حالة ضمن:
|
||||
|
||||
- `~/Library/Mobile Documents/com~apple~CloudDocs/...`
|
||||
- `~/Library/CloudStorage/...`
|
||||
|
||||
فسيصدر تحذيرًا ويوصي بالعودة إلى مسار محلي.
|
||||
فسوف يعرض تحذيرًا ويوصي بالعودة إلى مسار محلي.
|
||||
|
||||
## سير عمل البناء والتطوير (أصلي)
|
||||
|
||||
- `cd apps/macos && swift build`
|
||||
- `swift run OpenClaw` (أو Xcode)
|
||||
- تغليف التطبيق: `scripts/package-mac-app.sh`
|
||||
- تحزيم التطبيق: `scripts/package-mac-app.sh`
|
||||
|
||||
## تصحيح اتصال البوابة (CLI على macOS)
|
||||
## تصحيح اتصال gateway (CLI على macOS)
|
||||
|
||||
استخدم CLI الخاصة بالتصحيح لتجربة مصافحة Gateway WebSocket ومنطق الاكتشاف نفسيهما
|
||||
اللذين يستخدمهما تطبيق macOS، من دون تشغيل التطبيق.
|
||||
استخدم CLI الخاص بالتصحيح لاختبار المنطق نفسه الخاص بمصافحة Gateway WebSocket والاكتشاف
|
||||
الذي يستخدمه تطبيق macOS، من دون تشغيل التطبيق.
|
||||
__OC_I18N_900006__
|
||||
خيارات الاتصال:
|
||||
|
||||
- `--url <ws://host:port>`: تجاوز الإعداد
|
||||
- `--mode <local|remote>`: التحليل من الإعداد (الافتراضي: الإعداد أو local)
|
||||
- `--url <ws://host:port>`: تجاوز الإعدادات
|
||||
- `--mode <local|remote>`: الحل من الإعدادات (الافتراضي: الإعدادات أو local)
|
||||
- `--probe`: فرض فحص سلامة جديد
|
||||
- `--timeout <ms>`: مهلة الطلب (الافتراضي: `15000`)
|
||||
- `--json`: إخراج منظم للمقارنة
|
||||
- `--json`: مخرجات منظَّمة للمقارنة
|
||||
|
||||
خيارات الاكتشاف:
|
||||
|
||||
- `--include-local`: تضمين البوابات التي كان سيتم تصفيتها على أنها “local”
|
||||
- `--include-local`: تضمين Gateways التي كانت ستُصفّى باعتبارها “محلية”
|
||||
- `--timeout <ms>`: نافذة الاكتشاف الإجمالية (الافتراضي: `2000`)
|
||||
- `--json`: إخراج منظم للمقارنة
|
||||
- `--json`: مخرجات منظَّمة للمقارنة
|
||||
|
||||
نصيحة: قارن مع `openclaw gateway discover --json` لمعرفة ما إذا كان
|
||||
خط اكتشاف تطبيق macOS (`local.` بالإضافة إلى النطاق الواسع المُعد، مع
|
||||
الرجوع إلى wide-area وTailscale Serve) يختلف عن
|
||||
اكتشاف Node CLI المعتمد على `dns-sd`.
|
||||
مسار اكتشاف تطبيق macOS (`local.` بالإضافة إلى النطاق الواسع المُعدّ، مع
|
||||
بدائل wide-area وTailscale Serve) يختلف عن
|
||||
اكتشاف CLI الخاص بـ Node المعتمد على `dns-sd`.
|
||||
|
||||
## بنية الاتصال البعيد (أنفاق SSH)
|
||||
## البنية الداخلية للاتصال البعيد (أنفاق SSH)
|
||||
|
||||
عندما يعمل تطبيق macOS في وضع **Remote**، فإنه يفتح نفق SSH حتى تتمكن مكونات
|
||||
واجهة المستخدم المحلية من التحدث إلى البوابة البعيدة وكأنها موجودة على localhost.
|
||||
عندما يعمل تطبيق macOS في وضع **Remote**، فإنه يفتح نفق SSH حتى تتمكن مكونات واجهة المستخدم المحلية
|
||||
من التحدث إلى Gateway بعيد كما لو كان على localhost.
|
||||
|
||||
### نفق التحكم (منفذ Gateway WebSocket)
|
||||
|
||||
- **الغرض:** فحوصات السلامة، والحالة، وWeb Chat، والإعداد، وغيرها من استدعاءات control-plane.
|
||||
- **المنفذ المحلي:** منفذ البوابة (الافتراضي `18789`) وهو دائم الثبات.
|
||||
- **المنفذ البعيد:** منفذ البوابة نفسه على المضيف البعيد.
|
||||
- **الغرض:** فحوصات السلامة، الحالة، Web Chat، الإعدادات، واستدعاءات مستوى التحكم الأخرى.
|
||||
- **المنفذ المحلي:** منفذ Gateway (الافتراضي `18789`) وهو ثابت دائمًا.
|
||||
- **المنفذ البعيد:** منفذ Gateway نفسه على المضيف البعيد.
|
||||
- **السلوك:** لا يوجد منفذ محلي عشوائي؛ يعيد التطبيق استخدام نفق سليم موجود
|
||||
أو يعيد تشغيله إذا لزم الأمر.
|
||||
- **شكل SSH:** `ssh -N -L <local>:127.0.0.1:<remote>` مع BatchMode +
|
||||
ExitOnForwardFailure + خيارات keepalive.
|
||||
- **الإبلاغ عن IP:** يستخدم نفق SSH loopback، لذلك سترى البوابة عنوان IP الخاص بالعقدة
|
||||
على أنه `127.0.0.1`. استخدم النقل **Direct (ws/wss)** إذا كنت تريد ظهور عنوان IP الحقيقي للعميل
|
||||
(راجع [الوصول البعيد على macOS](/platforms/mac/remote)).
|
||||
- **صيغة SSH:** `ssh -N -L <local>:127.0.0.1:<remote>` مع خيارات BatchMode +
|
||||
ExitOnForwardFailure + keepalive.
|
||||
- **الإبلاغ عن IP:** يستخدم نفق SSH عنوان loopback، لذلك سيرى الـ gateway عنوان IP
|
||||
الخاص بالعقدة على أنه `127.0.0.1`. استخدم نقل **Direct (ws/wss)** إذا كنت تريد ظهور
|
||||
عنوان IP الحقيقي للعميل (راجع [الوصول البعيد على macOS](/ar/platforms/mac/remote)).
|
||||
|
||||
للحصول على خطوات الإعداد، راجع [الوصول البعيد على macOS](/platforms/mac/remote). وبالنسبة إلى تفاصيل
|
||||
البروتوكول، راجع [بروتوكول البوابة](/gateway/protocol).
|
||||
لخطوات الإعداد، راجع [الوصول البعيد على macOS](/ar/platforms/mac/remote). ولتفاصيل
|
||||
البروتوكول، راجع [بروتوكول Gateway](/ar/gateway/protocol).
|
||||
|
||||
## مستندات ذات صلة
|
||||
## المستندات ذات الصلة
|
||||
|
||||
- [دليل تشغيل البوابة](/gateway)
|
||||
- [البوابة (macOS)](/platforms/mac/bundled-gateway)
|
||||
- [أذونات macOS](/platforms/mac/permissions)
|
||||
- [Canvas](/platforms/mac/canvas)
|
||||
- [دليل تشغيل Gateway](/ar/gateway)
|
||||
- [Gateway (macOS)](/ar/platforms/mac/bundled-gateway)
|
||||
- [أذونات macOS](/ar/platforms/mac/permissions)
|
||||
- [Canvas](/ar/platforms/mac/canvas)
|
||||
|
||||
@ -5,112 +5,108 @@ read_when:
|
||||
- تحتاج إلى فهم واجهة المهايئ ChannelPlugin
|
||||
sidebarTitle: Channel Plugins
|
||||
summary: دليل خطوة بخطوة لبناء Plugin لقناة مراسلة لـ OpenClaw
|
||||
title: بناء Plugins للقنوات
|
||||
title: بناء Plugins القنوات
|
||||
x-i18n:
|
||||
generated_at: "2026-04-15T19:41:41Z"
|
||||
generated_at: "2026-04-18T07:15:28Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 80e47e61d1e47738361692522b79aff276544446c58a7b41afe5296635dfad4b
|
||||
source_hash: 3dda53c969bc7356a450c2a5bf49fb82bf1283c23e301dec832d8724b11e724b
|
||||
source_path: plugins/sdk-channel-plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# بناء Plugins للقنوات
|
||||
# بناء Plugins القنوات
|
||||
|
||||
يوضح هذا الدليل كيفية بناء Plugin لقناة يربط OpenClaw بمنصة
|
||||
مراسلة. بنهاية هذا الدليل، سيكون لديك قناة عاملة تتضمن أمان الرسائل
|
||||
المباشرة، والاقتران، وتسلسل الردود، والمراسلة الصادرة.
|
||||
يوضح هذا الدليل كيفية بناء Plugin قناة يربط OpenClaw بمنصة مراسلة. وبنهاية هذا الدليل سيكون لديك قناة عاملة تتضمن أمان الرسائل الخاصة، والاقتران، وترابط الردود، والرسائل الصادرة.
|
||||
|
||||
<Info>
|
||||
إذا لم تكن قد بنيت أي Plugin لـ OpenClaw من قبل، فاقرأ
|
||||
[البدء](/ar/plugins/building-plugins) أولًا للتعرّف على بنية
|
||||
الحزمة الأساسية وإعداد ملف البيان.
|
||||
إذا لم تكن قد أنشأت أي Plugin لـ OpenClaw من قبل، فاقرأ
|
||||
[البدء](/ar/plugins/building-plugins) أولًا للتعرف على بنية الحزمة الأساسية
|
||||
وإعداد manifest.
|
||||
</Info>
|
||||
|
||||
## كيف تعمل Plugins القنوات
|
||||
|
||||
لا تحتاج Plugins القنوات إلى أدوات send/edit/react خاصة بها. يحتفظ OpenClaw
|
||||
بأداة `message` واحدة مشتركة في النواة. ويتولى Plugin الخاص بك ما يلي:
|
||||
بأداة `message` مشتركة واحدة في النواة. ويتولى Plugin الخاص بك ما يلي:
|
||||
|
||||
- **الإعداد** — حلّ الحسابات ومعالج الإعداد
|
||||
- **الأمان** — سياسة الرسائل المباشرة وقوائم السماح
|
||||
- **الاقتران** — تدفق الموافقة على الرسائل المباشرة
|
||||
- **بنية الجلسة** — كيفية تعيين معرّفات المحادثات الخاصة بالموفّر إلى الدردشات الأساسية، ومعرّفات السلاسل، وبدائل الأصل
|
||||
- **الإعداد** — تحليل الحسابات ومعالج الإعداد
|
||||
- **الأمان** — سياسة الرسائل الخاصة وقوائم السماح
|
||||
- **الاقتران** — تدفق الموافقة على الرسائل الخاصة
|
||||
- **صياغة الجلسة** — كيفية ربط معرّفات المحادثات الخاصة بالمزوّد بالمحادثات الأساسية، ومعرّفات السلاسل، وبدائل الأصل
|
||||
- **الصادر** — إرسال النصوص والوسائط والاستطلاعات إلى المنصة
|
||||
- **التسلسل** — كيفية تنظيم الردود ضمن سلاسل
|
||||
- **التسلسل** — كيفية ربط الردود ضمن السلاسل
|
||||
|
||||
تتولى النواة أداة الرسائل المشتركة، وتوصيل المطالبات، وشكل مفتاح الجلسة
|
||||
الخارجي، وآلية `:thread:` العامة، والتوجيه.
|
||||
تتولى النواة أداة الرسائل المشتركة، وربط prompt، وشكل مفتاح الجلسة الخارجي،
|
||||
ومسك الدفاتر العام لـ `:thread:`، والإرسال.
|
||||
|
||||
إذا كانت قناتك تضيف معاملات إلى أداة الرسائل تحمل مصادر وسائط، فاكشف عن
|
||||
أسماء هذه المعاملات عبر `describeMessageTool(...).mediaSourceParams`. تستخدم
|
||||
النواة هذه القائمة الصريحة لتطبيع مسارات sandbox وسياسة الوصول إلى الوسائط
|
||||
الصادرة، لذلك لا تحتاج Plugins إلى حالات خاصة مشتركة في النواة لمعلمات
|
||||
الصورة الرمزية أو المرفقات أو صورة الغلاف الخاصة بموفّرين محددين.
|
||||
يُفضَّل إرجاع خريطة مرتبطة بالإجراءات مثل
|
||||
إذا كانت قناتك تضيف معاملات message-tool تحمل مصادر وسائط، فاكشف أسماء هذه
|
||||
المعاملات عبر `describeMessageTool(...).mediaSourceParams`. تستخدم النواة
|
||||
هذه القائمة الصريحة لتطبيع مسارات sandbox وسياسة الوصول إلى الوسائط الصادرة،
|
||||
بحيث لا تحتاج Plugins إلى حالات خاصة في النواة المشتركة لمعلمات الصورة
|
||||
الرمزية أو المرفقات أو صورة الغلاف الخاصة بكل مزوّد.
|
||||
ويُفضَّل إرجاع خريطة مفاتيحها هي الإجراءات مثل
|
||||
`{ "set-profile": ["avatarUrl", "avatarPath"] }` حتى لا ترث الإجراءات غير
|
||||
ذات الصلة معاملات الوسائط الخاصة بإجراء آخر. ولا يزال استخدام مصفوفة
|
||||
مسطحة يعمل مع المعاملات التي يُقصَد مشاركتها عمدًا عبر كل إجراء مكشوف.
|
||||
المرتبطة معاملات الوسائط الخاصة بإجراء آخر. ولا تزال المصفوفة المسطحة تعمل
|
||||
للمعاملات التي تكون مشتركة عمدًا بين جميع الإجراءات المكشوفة.
|
||||
|
||||
إذا كانت منصتك تخزّن نطاقًا إضافيًا داخل معرّفات المحادثات، فأبقِ هذا
|
||||
التحليل داخل Plugin باستخدام `messaging.resolveSessionConversation(...)`.
|
||||
هذا هو الخطاف القياسي لتعيين `rawId` إلى معرّف المحادثة الأساسي، ومعرّف
|
||||
السلسلة الاختياري، و`baseConversationId` الصريح، وأي
|
||||
`parentConversationCandidates`.
|
||||
وعند إرجاع `parentConversationCandidates`، احرص على ترتيبها من الأصل الأكثر
|
||||
تحديدًا إلى الأصل الأوسع/المحادثة الأساسية.
|
||||
إذا كانت منصتك تخزن نطاقًا إضافيًا داخل معرّفات المحادثات، فأبقِ هذا التحليل
|
||||
داخل Plugin باستخدام `messaging.resolveSessionConversation(...)`. فهذا هو
|
||||
الخطاف القياسي لربط `rawId` بمعرّف المحادثة الأساسي، ومعرّف السلسلة الاختياري،
|
||||
و`baseConversationId` الصريح، وأي `parentConversationCandidates`.
|
||||
عند إرجاع `parentConversationCandidates`، احرص على ترتيبها من الأصل الأضيق
|
||||
إلى المحادثة الأوسع/الأساسية.
|
||||
|
||||
يمكن أيضًا لـ Plugins المضمّنة التي تحتاج إلى التحليل نفسه قبل إقلاع سجل
|
||||
القنوات أن تكشف عن ملف `session-key-api.ts` على المستوى الأعلى مع
|
||||
تصدير مطابق لـ `resolveSessionConversation(...)`. تستخدم النواة هذا السطح
|
||||
الآمن لمرحلة الإقلاع فقط عندما لا يكون سجل Plugins وقت التشغيل متاحًا بعد.
|
||||
القنوات أن تكشف ملفًا علوي المستوى باسم `session-key-api.ts` مع تصدير مطابق
|
||||
لـ `resolveSessionConversation(...)`. وتستخدم النواة هذا السطح الآمن للتهيئة
|
||||
فقط عندما لا يكون سجل Plugins وقت التشغيل متاحًا بعد.
|
||||
|
||||
يبقى `messaging.resolveParentConversationCandidates(...)` متاحًا كبديل
|
||||
توافقي قديم عندما يحتاج Plugin فقط إلى بدائل الأصل فوق المعرّف الخام/العام.
|
||||
إذا وُجد الخطافان معًا، تستخدم النواة
|
||||
`resolveSessionConversation(...).parentConversationCandidates` أولًا، ثم
|
||||
تعود إلى `resolveParentConversationCandidates(...)` فقط عندما يتجاهل
|
||||
الخطاف القياسي إرجاعها.
|
||||
يبقى `messaging.resolveParentConversationCandidates(...)` متاحًا كبديل توافق
|
||||
قديم عندما يحتاج Plugin فقط إلى بدائل أصل فوق المعرّف العام/الخام. وإذا
|
||||
وُجد الخطافان معًا، تستخدم النواة
|
||||
`resolveSessionConversation(...).parentConversationCandidates` أولًا، ولا
|
||||
تعود إلى `resolveParentConversationCandidates(...)` إلا إذا أغفلها الخطاف
|
||||
القياسي.
|
||||
|
||||
## الموافقات وإمكانات القنوات
|
||||
## الموافقات وقدرات القنوات
|
||||
|
||||
معظم Plugins القنوات لا تحتاج إلى شيفرة خاصة بالموافقات.
|
||||
لا تحتاج معظم Plugins القنوات إلى شيفرة خاصة بالموافقات.
|
||||
|
||||
- تتولى النواة `/approve` داخل المحادثة نفسها، وحمولات أزرار الموافقة المشتركة، والتسليم الاحتياطي العام.
|
||||
- فضّل استخدام كائن `approvalCapability` واحد على Plugin القناة عندما تحتاج القناة إلى سلوك خاص بالموافقة.
|
||||
- أُزيل `ChannelPlugin.approvals`. ضع حقائق تسليم/أصلي/عرض/مصادقة الموافقة ضمن `approvalCapability`.
|
||||
- يقتصر `plugin.auth` على login/logout فقط؛ لم تعد النواة تقرأ خطافات مصادقة الموافقة من هذا الكائن.
|
||||
- يُعدّ `approvalCapability.authorizeActorAction` و`approvalCapability.getActionAvailabilityState` الواجهة القياسية لمصادقة الموافقات.
|
||||
- استخدم `approvalCapability.getActionAvailabilityState` لإتاحة مصادقة الموافقة داخل المحادثة نفسها.
|
||||
- إذا كانت قناتك تكشف عن موافقات exec أصلية، فاستخدم `approvalCapability.getExecInitiatingSurfaceState` لحالة سطح البدء/العميل الأصلي عندما تختلف عن مصادقة الموافقة داخل المحادثة نفسها. تستخدم النواة هذا الخطاف الخاص بـ exec للتمييز بين `enabled` و`disabled`، وتحديد ما إذا كانت قناة البدء تدعم موافقات exec الأصلية، وإدراج القناة في إرشادات الرجوع إلى العميل الأصلي. يملأ `createApproverRestrictedNativeApprovalCapability(...)` هذا الجزء للحالة الشائعة.
|
||||
- استخدم `outbound.shouldSuppressLocalPayloadPrompt` أو `outbound.beforeDeliverPayload` لسلوك دورة حياة الحمولة الخاص بالقناة، مثل إخفاء مطالبات الموافقة المحلية المكررة أو إرسال مؤشرات الكتابة قبل التسليم.
|
||||
- استخدم `approvalCapability.delivery` فقط لتوجيه الموافقة الأصلي أو منع الرجوع الاحتياطي.
|
||||
- استخدم `approvalCapability.nativeRuntime` للحقائق الأصلية الخاصة بالموافقة التي تملكها القناة. أبقه كسول التحميل في نقاط دخول القنوات الساخنة باستخدام `createLazyChannelApprovalNativeRuntimeAdapter(...)`، والذي يمكنه استيراد وحدة وقت التشغيل عند الطلب مع السماح للنواة بتجميع دورة حياة الموافقة.
|
||||
- فضّل كائن `approvalCapability` واحدًا على Plugin القناة عندما تحتاج القناة إلى سلوك خاص بالموافقة.
|
||||
- تمت إزالة `ChannelPlugin.approvals`. ضع حقائق التسليم/الأصلي/العرض/المصادقة الخاصة بالموافقة على `approvalCapability`.
|
||||
- يقتصر `plugin.auth` على login/logout فقط؛ ولم تعد النواة تقرأ خطافات مصادقة الموافقة من ذلك الكائن.
|
||||
- يمثل `approvalCapability.authorizeActorAction` و`approvalCapability.getActionAvailabilityState` نقطة الربط القياسية لمصادقة الموافقات.
|
||||
- استخدم `approvalCapability.getActionAvailabilityState` لتوفر مصادقة الموافقة داخل المحادثة نفسها.
|
||||
- إذا كانت قناتك تكشف عن موافقات exec أصلية، فاستخدم `approvalCapability.getExecInitiatingSurfaceState` لحالة السطح البادئ/العميل الأصلي عندما تختلف عن مصادقة الموافقة داخل المحادثة نفسها. تستخدم النواة هذا الخطاف الخاص بـ exec للتمييز بين `enabled` و`disabled`، وتقرير ما إذا كانت القناة البادئة تدعم موافقات exec الأصلية، وضم القناة إلى إرشادات fallback الخاصة بالعميل الأصلي. تملأ `createApproverRestrictedNativeApprovalCapability(...)` هذا الجزء للحالة الشائعة.
|
||||
- استخدم `outbound.shouldSuppressLocalPayloadPrompt` أو `outbound.beforeDeliverPayload` لسلوك دورة حياة الحمولات الخاص بالقناة مثل إخفاء مطالبات الموافقة المحلية المكررة أو إرسال مؤشرات الكتابة قبل التسليم.
|
||||
- استخدم `approvalCapability.delivery` فقط لتوجيه الموافقة الأصلية أو تعطيل fallback.
|
||||
- استخدم `approvalCapability.nativeRuntime` للحقائق الأصلية الخاصة بالموافقة التي تملكها القناة. أبقه كسول التحميل على نقاط دخول القنوات الساخنة باستخدام `createLazyChannelApprovalNativeRuntimeAdapter(...)`، الذي يمكنه استيراد وحدة وقت التشغيل لديك عند الطلب مع الاستمرار في تمكين النواة من تجميع دورة حياة الموافقة.
|
||||
- استخدم `approvalCapability.render` فقط عندما تحتاج القناة فعلًا إلى حمولات موافقة مخصصة بدلًا من العارض المشترك.
|
||||
- استخدم `approvalCapability.describeExecApprovalSetup` عندما تريد القناة أن يشرح رد المسار المعطّل مقابض الإعداد الدقيقة اللازمة لتمكين موافقات exec الأصلية. يستقبل الخطاف `{ channel, channelLabel, accountId }`؛ ويجب على القنوات ذات الحسابات المسماة عرض مسارات بنطاق الحساب مثل `channels.<channel>.accounts.<id>.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` — إعداد الأهداف بالإضافة إلى إرسال/تحديث/حذف رسائل الموافقة الأصلية
|
||||
- استخدم `approvalCapability.describeExecApprovalSetup` عندما تريد القناة أن يشرح رد مسار التعطيل مفاتيح الإعداد الدقيقة اللازمة لتمكين موافقات exec الأصلية. يتلقى الخطاف `{ channel, channelLabel, accountId }`؛ ويجب على القنوات ذات الحسابات المسماة عرض مسارات ضمن نطاق الحساب مثل `channels.<channel>.accounts.<id>.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`. يتيح سجل runtime-context العام للنواة إقلاع معالجات مدفوعة بالإمكانات من حالة بدء تشغيل القناة دون إضافة غراء تغليف خاص بالموافقة.
|
||||
- لا تلجأ إلى `createChannelApprovalHandler` أو `createChannelNativeApprovalRuntime` منخفضي المستوى إلا عندما لا تكون الواجهة المدفوعة بالإمكانات معبّرة بما يكفي بعد.
|
||||
- يجب أن تمرّر قنوات الموافقة الأصلية كِلا `accountId` و`approvalKind` عبر هذه المساعدات. يُبقي `accountId` سياسة الموافقة متعددة الحسابات ضمن نطاق حساب البوت الصحيح، ويُبقي `approvalKind` سلوك exec مقابل موافقة Plugin متاحًا للقناة دون تفرعات مشفّرة مسبقًا في النواة.
|
||||
- تتولى النواة الآن أيضًا إشعارات إعادة توجيه الموافقات. يجب ألا ترسل Plugins القنوات رسائل متابعة خاصة بها من نوع "تم إرسال الموافقة إلى الرسائل المباشرة / قناة أخرى" من `createChannelNativeApprovalRuntime`; وبدلًا من ذلك، اكشف عن توجيه دقيق للأصل + الرسائل المباشرة للموافق عبر مساعدات إمكانات الموافقة المشتركة، ودع النواة تجمع عمليات التسليم الفعلية قبل نشر أي إشعار مرة أخرى إلى محادثة البدء.
|
||||
- حافظ على نوع معرّف الموافقة الذي تم تسليمه من البداية إلى النهاية. يجب ألا
|
||||
تخمّن العملاء الأصلية أو تعيد كتابة توجيه موافقة exec مقابل Plugin من حالة
|
||||
محلية خاصة بالقناة.
|
||||
- يمكن لأنواع الموافقات المختلفة عمدًا أن تكشف عن أسطح أصلية مختلفة.
|
||||
الأمثلة المضمّنة الحالية:
|
||||
- يحتفظ Slack بإتاحة توجيه الموافقة الأصلي لكل من معرّفات exec وPlugin.
|
||||
- يحتفظ Matrix بالتوجيه الأصلي نفسه للرسائل المباشرة/القناة وتجربة التفاعل لـ exec
|
||||
وموافقات Plugin، مع الاستمرار في السماح لاختلاف المصادقة حسب نوع الموافقة.
|
||||
- لا يزال `createApproverRestrictedNativeApprovalAdapter` موجودًا كغلاف توافقي، لكن الشيفرة الجديدة يجب أن تفضّل مُنشئ الإمكانات وتكشف عن `approvalCapability` على Plugin.
|
||||
- `observe` — خطافات تشخيص اختيارية للتسليم
|
||||
- إذا كانت القناة تحتاج إلى كائنات يملكها وقت التشغيل مثل عميل أو token أو تطبيق Bolt أو مستقبِل Webhook، فسجّلها عبر `openclaw/plugin-sdk/channel-runtime-context`. يتيح سجل runtime-context العام للنواة تهيئة المعالجات المدفوعة بالقدرات من حالة بدء تشغيل القناة من دون إضافة تعليمات ربط خاصة بالموافقة.
|
||||
- لا تلجأ إلى `createChannelApprovalHandler` أو `createChannelNativeApprovalRuntime` ذوي المستوى الأدنى إلا عندما لا تكون نقطة الربط المدفوعة بالقدرات معبّرة بما يكفي بعد.
|
||||
- يجب على قنوات الموافقات الأصلية تمرير كل من `accountId` و`approvalKind` عبر تلك الأدوات المساعدة. إذ يُبقي `accountId` سياسة الموافقات متعددة الحسابات ضمن نطاق حساب bot الصحيح، بينما يُبقي `approvalKind` سلوك exec مقابل موافقة Plugin متاحًا للقناة من دون فروع مضمّنة في النواة.
|
||||
- تتولى النواة الآن أيضًا إشعارات إعادة توجيه الموافقات. يجب ألا ترسل Plugins القنوات رسائل متابعة خاصة بها من نوع "تم إرسال الموافقة إلى الرسائل الخاصة / إلى قناة أخرى" من `createChannelNativeApprovalRuntime`؛ وبدلًا من ذلك، اكشف عن توجيه origin + الرسائل الخاصة للموافق عبر أدوات المساعدة المشتركة لقدرات الموافقة، ودع النواة تجمع عمليات التسليم الفعلية قبل نشر أي إشعار إلى المحادثة البادئة.
|
||||
- حافظ على نوع معرّف الموافقة المُسلَّمة من البداية إلى النهاية. يجب ألا تقوم العملاء الأصلية
|
||||
بتخمين أو إعادة كتابة توجيه موافقة exec مقابل موافقة Plugin بالاعتماد على حالة محلية للقناة.
|
||||
- يمكن لأنواع الموافقات المختلفة أن تكشف عمدًا عن أسطح أصلية مختلفة.
|
||||
أمثلة حالية من Plugins المضمّنة:
|
||||
- يحتفظ Slack بتوجيه الموافقات الأصلية متاحًا لكل من معرّفات exec وPlugin.
|
||||
- يحتفظ Matrix بالتوجيه الأصلي نفسه للرسائل الخاصة/القناة وتجربة التفاعلات لموافقات exec
|
||||
وPlugin، مع السماح مع ذلك باختلاف المصادقة حسب نوع الموافقة.
|
||||
- لا يزال `createApproverRestrictedNativeApprovalAdapter` موجودًا كغلاف توافق، لكن يجب أن تفضّل الشيفرة الجديدة منشئ القدرات وأن تكشف `approvalCapability` على Plugin.
|
||||
|
||||
لنقاط دخول القنوات الساخنة، فضّل المسارات الفرعية الأضيق لوقت التشغيل عندما
|
||||
تحتاج فقط إلى جزء واحد من هذه المجموعة:
|
||||
بالنسبة إلى نقاط دخول القنوات الساخنة، فضّل المسارات الفرعية الأضيق لوقت التشغيل عندما
|
||||
تحتاج إلى جزء واحد فقط من تلك المجموعة:
|
||||
|
||||
- `openclaw/plugin-sdk/approval-auth-runtime`
|
||||
- `openclaw/plugin-sdk/approval-client-runtime`
|
||||
@ -122,89 +118,90 @@ x-i18n:
|
||||
- `openclaw/plugin-sdk/approval-reply-runtime`
|
||||
- `openclaw/plugin-sdk/channel-runtime-context`
|
||||
|
||||
وبالمثل، فضّل `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/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` مساعدات الإعداد الآمنة لوقت التشغيل:
|
||||
- يغطي `openclaw/plugin-sdk/setup-runtime` أدوات الإعداد الآمنة لوقت التشغيل:
|
||||
مهايئات ترقيع الإعداد الآمنة للاستيراد (`createPatchedAccountSetupAdapter`,
|
||||
`createEnvPatchedAccountSetupAdapter`,
|
||||
`createSetupInputPresenceValidator`)، ومخرجات
|
||||
ملاحظات البحث، و`promptResolvedAllowFrom`، و`splitSetupEntries`، ومنشئات
|
||||
وكيل الإعداد المفوّض
|
||||
- يُعد `openclaw/plugin-sdk/setup-adapter-runtime` الواجهة الضيقة الواعية بالبيئة
|
||||
لـ `createEnvPatchedAccountSetupAdapter`
|
||||
- يغطي `openclaw/plugin-sdk/channel-setup` منشئات الإعداد ذات التثبيت الاختياري
|
||||
بالإضافة إلى بعض البدائيات الآمنة للإعداد:
|
||||
`createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`،
|
||||
`createSetupInputPresenceValidator`)، وإخراج ملاحظات البحث،
|
||||
و`promptResolvedAllowFrom`، و`splitSetupEntries`، وبناة
|
||||
setup-proxy المفوضة
|
||||
- يمثل `openclaw/plugin-sdk/setup-adapter-runtime` نقطة الربط الضيقة
|
||||
الواعية بالبيئة لـ `createEnvPatchedAccountSetupAdapter`
|
||||
- يغطي `openclaw/plugin-sdk/channel-setup` بناة الإعداد ذي التثبيت الاختياري
|
||||
بالإضافة إلى بعض الأساسيات الآمنة للإعداد:
|
||||
`createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`,
|
||||
|
||||
إذا كانت قناتك تدعم إعدادًا أو مصادقة مدفوعين بالبيئة، وكان ينبغي أن تعرف
|
||||
تدفقات البدء/الإعداد العامة أسماء متغيرات البيئة تلك قبل تحميل وقت التشغيل،
|
||||
فصرّح عنها في ملف بيان Plugin باستخدام `channelEnvVars`. واحتفظ بمتغيرات
|
||||
البيئة `envVars` وقت تشغيل القناة أو الثوابت المحلية فقط لنسخة النص
|
||||
الموجّهة للمشغّل.
|
||||
إذا كانت قناتك تدعم الإعداد أو المصادقة المدفوعين بالبيئة وكان ينبغي لتدفقات
|
||||
بدء التشغيل/الإعداد العامة معرفة أسماء متغيرات البيئة هذه قبل تحميل وقت التشغيل،
|
||||
فصرّح بها في manifest الخاص بـ Plugin باستخدام `channelEnvVars`. واحتفظ
|
||||
بـ `envVars` في وقت تشغيل القناة أو الثوابت المحلية فقط للنصوص الموجّهة
|
||||
للمشغّل.
|
||||
`createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`,
|
||||
`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, و
|
||||
`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-resolution`، و
|
||||
`openclaw/plugin-sdk/account-helpers` لإعداد الحسابات المتعددة و
|
||||
الرجوع إلى الحساب الافتراضي
|
||||
`openclaw/plugin-sdk/account-helpers` لإعدادات الحسابات المتعددة
|
||||
وfallback الحساب الافتراضي
|
||||
- `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` فقط عندما يكون تخطيط حقول
|
||||
حمولة الوكيل/الوسائط القديم لا يزال مطلوبًا
|
||||
- `openclaw/plugin-sdk/telegram-command-config` لتطبيع أوامر Telegram المخصصة،
|
||||
والتحقق من التكرار/التعارض، وعقد إعداد الأوامر المستقر عند الرجوع الاحتياطي
|
||||
الحمولات القديمة للوكيل/الوسائط لا يزال مطلوبًا
|
||||
- `openclaw/plugin-sdk/telegram-command-config` لتطبيع الأوامر المخصصة في Telegram،
|
||||
والتحقق من التكرارات/التعارضات، وعقد إعدادات الأوامر الثابت في fallback
|
||||
|
||||
يمكن للقنوات التي تعتمد على المصادقة فقط عادةً الاكتفاء بالمسار الافتراضي: تتولى النواة الموافقات، ويكشف Plugin فقط عن إمكانات الصادر/المصادقة. يجب على قنوات الموافقة الأصلية مثل Matrix وSlack وTelegram ووسائط نقل الدردشة المخصصة استخدام المساعدات الأصلية المشتركة بدلًا من بناء دورة حياة الموافقة الخاصة بها.
|
||||
يمكن للقنوات التي تقتصر على المصادقة فقط أن تتوقف عادة عند المسار الافتراضي: تتولى النواة الموافقات، ويكشف Plugin فقط عن قدرات الصادر/المصادقة. أما قنوات الموافقات الأصلية مثل Matrix وSlack وTelegram ووسائط الدردشة المخصصة، فيجب أن تستخدم الأدوات المساعدة الأصلية المشتركة بدلًا من بناء دورة حياة الموافقة الخاصة بها.
|
||||
|
||||
## سياسة الإشارات الواردة
|
||||
|
||||
احرص على إبقاء معالجة الإشارات الواردة مقسّمة إلى طبقتين:
|
||||
أبقِ معالجة الإشارات الواردة مقسمة إلى طبقتين:
|
||||
|
||||
- جمع الأدلة المملوك لـ Plugin
|
||||
- جمع الأدلة الذي يملكه Plugin
|
||||
- تقييم السياسة المشتركة
|
||||
|
||||
استخدم `openclaw/plugin-sdk/channel-inbound` للطبقة المشتركة.
|
||||
استخدم `openclaw/plugin-sdk/channel-mention-gating` لقرارات سياسة الإشارات.
|
||||
واستخدم `openclaw/plugin-sdk/channel-inbound` فقط عندما تحتاج إلى
|
||||
شريط أدوات inbound الأوسع.
|
||||
|
||||
ما يناسب المنطق المحلي في Plugin:
|
||||
حالات مناسبة للمنطق المحلي داخل Plugin:
|
||||
|
||||
- اكتشاف الرد على البوت
|
||||
- اكتشاف الاقتباس من البوت
|
||||
- اكتشاف الرد على bot
|
||||
- اكتشاف الاقتباس من bot
|
||||
- التحقق من المشاركة في السلسلة
|
||||
- استبعاد رسائل الخدمة/النظام
|
||||
- الذاكرات المؤقتة الأصلية للمنصة اللازمة لإثبات مشاركة البوت
|
||||
- ذاكرات تخزين أصلية للمنصة لازمة لإثبات مشاركة bot
|
||||
|
||||
ما يناسب المساعد المشترك:
|
||||
حالات مناسبة للأداة المساعدة المشتركة:
|
||||
|
||||
- `requireMention`
|
||||
- نتيجة الإشارة الصريحة
|
||||
@ -212,11 +209,11 @@ x-i18n:
|
||||
- تجاوز الأوامر
|
||||
- قرار التخطي النهائي
|
||||
|
||||
التدفق المفضّل:
|
||||
التدفق المفضل:
|
||||
|
||||
1. احسب حقائق الإشارة المحلية.
|
||||
2. مرّر هذه الحقائق إلى `resolveInboundMentionDecision({ facts, policy })`.
|
||||
3. استخدم `decision.effectiveWasMentioned` و`decision.shouldBypassMention` و`decision.shouldSkip` في بوابة الوارد الخاصة بك.
|
||||
2. مرر هذه الحقائق إلى `resolveInboundMentionDecision({ facts, policy })`.
|
||||
3. استخدم `decision.effectiveWasMentioned` و`decision.shouldBypassMention` و`decision.shouldSkip` في بوابة inbound الخاصة بك.
|
||||
|
||||
```typescript
|
||||
import {
|
||||
@ -255,8 +252,8 @@ const decision = resolveInboundMentionDecision({
|
||||
if (decision.shouldSkip) return;
|
||||
```
|
||||
|
||||
يكشف `api.runtime.channel.mentions` عن مساعدات الإشارة المشتركة نفسها من أجل
|
||||
Plugins القنوات المضمّنة التي تعتمد بالفعل على حقن وقت التشغيل:
|
||||
يكشف `api.runtime.channel.mentions` عن أدوات الإشارات المشتركة نفسها
|
||||
لـ Plugins القنوات المضمّنة التي تعتمد بالفعل على حقن وقت التشغيل:
|
||||
|
||||
- `buildMentionRegexes`
|
||||
- `matchesMentionPatterns`
|
||||
@ -264,18 +261,23 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على
|
||||
- `implicitMentionKindWhen`
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
تبقى مساعدات `resolveMentionGating*` الأقدم على
|
||||
`openclaw/plugin-sdk/channel-inbound` كتصديرات توافقية فقط. يجب أن تستخدم
|
||||
إذا كنت تحتاج فقط إلى `implicitMentionKindWhen` و
|
||||
`resolveInboundMentionDecision`، فاستورد من
|
||||
`openclaw/plugin-sdk/channel-mention-gating` لتجنب تحميل أدوات
|
||||
وقت تشغيل inbound غير المرتبطة.
|
||||
|
||||
تبقى أدوات `resolveMentionGating*` الأقدم موجودة على
|
||||
`openclaw/plugin-sdk/channel-inbound` كتصديرات توافق فقط. ويجب أن تستخدم
|
||||
الشيفرة الجديدة `resolveInboundMentionDecision({ facts, policy })`.
|
||||
|
||||
## شرح عملي
|
||||
|
||||
<Steps>
|
||||
<a id="step-1-package-and-manifest"></a>
|
||||
<Step title="الحزمة وملف البيان">
|
||||
أنشئ ملفات Plugin القياسية. الحقل `channel` في `package.json` هو
|
||||
ما يجعل هذا Plugin قناة. وللاطلاع على سطح بيانات وصف الحزمة الكامل،
|
||||
راجع [إعداد Plugin والتهيئة](/ar/plugins/sdk-setup#openclaw-channel):
|
||||
<Step title="الحزمة وmanifest">
|
||||
أنشئ ملفات Plugin القياسية. إن الحقل `channel` في `package.json` هو
|
||||
ما يجعل هذا Plugin قناة. وللاطلاع على سطح بيانات الحزمة الوصفية الكامل،
|
||||
راجع [إعداد Plugin وConfig](/ar/plugins/sdk-setup#openclaw-channel):
|
||||
|
||||
<CodeGroup>
|
||||
```json package.json
|
||||
@ -324,7 +326,7 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="بناء كائن Plugin للقناة">
|
||||
<Step title="ابنِ كائن Plugin القناة">
|
||||
تحتوي الواجهة `ChannelPlugin` على العديد من أسطح المهايئات الاختيارية. ابدأ
|
||||
بالحد الأدنى — `id` و`setup` — ثم أضف المهايئات حسب حاجتك.
|
||||
|
||||
@ -336,7 +338,7 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على
|
||||
createChannelPluginBase,
|
||||
} from "openclaw/plugin-sdk/channel-core";
|
||||
import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
|
||||
import { acmeChatApi } from "./client.js"; // عميل API الخاص بمنصتك
|
||||
import { acmeChatApi } from "./client.js"; // your platform API client
|
||||
|
||||
type ResolvedAccount = {
|
||||
accountId: string | null;
|
||||
@ -377,7 +379,7 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على
|
||||
},
|
||||
}),
|
||||
|
||||
// أمان الرسائل المباشرة: من يمكنه مراسلة البوت
|
||||
// DM security: who can message the bot
|
||||
security: {
|
||||
dm: {
|
||||
channelKey: "acme-chat",
|
||||
@ -387,21 +389,21 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على
|
||||
},
|
||||
},
|
||||
|
||||
// الاقتران: تدفق الموافقة لجهات الاتصال الجديدة في الرسائل المباشرة
|
||||
// Pairing: approval flow for new DM contacts
|
||||
pairing: {
|
||||
text: {
|
||||
idLabel: "اسم مستخدم Acme Chat",
|
||||
message: "أرسل هذا الرمز للتحقق من هويتك:",
|
||||
idLabel: "Acme Chat username",
|
||||
message: "Send this code to verify your identity:",
|
||||
notify: async ({ target, code }) => {
|
||||
await acmeChatApi.sendDm(target, `Pairing code: ${code}`);
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
// التسلسل: كيفية تسليم الردود
|
||||
// Threading: how replies are delivered
|
||||
threading: { topLevelReplyToMode: "reply" },
|
||||
|
||||
// الصادر: إرسال الرسائل إلى المنصة
|
||||
// Outbound: send messages to the platform
|
||||
outbound: {
|
||||
attachedResults: {
|
||||
sendText: async (params) => {
|
||||
@ -421,16 +423,16 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على
|
||||
});
|
||||
```
|
||||
|
||||
<Accordion title="ما الذي ينجزه `createChatChannelPlugin` لك">
|
||||
بدلًا من تنفيذ واجهات المهايئات منخفضة المستوى يدويًا، فإنك تمرّر
|
||||
خيارات تصريحية ويتولى المُنشئ تركيبها:
|
||||
<Accordion title="ما الذي يفعله `createChatChannelPlugin` من أجلك">
|
||||
بدلًا من تنفيذ واجهات مهايئات منخفضة المستوى يدويًا، تمرر
|
||||
خيارات تصريحية ويقوم البنّاء بتجميعها:
|
||||
|
||||
| الخيار | ما الذي يوصله |
|
||||
| الخيار | ما الذي يربطه |
|
||||
| --- | --- |
|
||||
| `security.dm` | محلّل أمان الرسائل المباشرة المقيّد بنطاق حقول التهيئة |
|
||||
| `pairing.text` | تدفق اقتران رسائل مباشرة قائم على النص مع تبادل الرمز |
|
||||
| `threading` | محلّل وضع الرد (ثابت أو مقيّد بالحساب أو مخصص) |
|
||||
| `outbound.attachedResults` | دوال إرسال تُرجع بيانات وصفية للنتيجة (معرّفات الرسائل) |
|
||||
| `security.dm` | محلل أمان رسائل خاصة محدد النطاق من حقول config |
|
||||
| `pairing.text` | تدفق اقتران رسائل خاصة قائم على النص مع تبادل رمز |
|
||||
| `threading` | محلل وضع reply-to (ثابت، أو ضمن نطاق الحساب، أو مخصص) |
|
||||
| `outbound.attachedResults` | دوال send تُرجع بيانات وصفية للنتيجة (معرّفات الرسائل) |
|
||||
|
||||
يمكنك أيضًا تمرير كائنات مهايئات خام بدلًا من الخيارات التصريحية
|
||||
إذا كنت بحاجة إلى تحكم كامل.
|
||||
@ -438,7 +440,7 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="توصيل نقطة الإدخال">
|
||||
<Step title="اربط نقطة الإدخال">
|
||||
أنشئ `index.ts`:
|
||||
|
||||
```typescript index.ts
|
||||
@ -474,22 +476,22 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على
|
||||
});
|
||||
```
|
||||
|
||||
ضع واصفات CLI المملوكة للقناة في `registerCliMetadata(...)` حتى يتمكن OpenClaw
|
||||
ضع واصفات CLI التي تملكها القناة في `registerCliMetadata(...)` حتى يتمكن OpenClaw
|
||||
من عرضها في المساعدة الجذرية دون تفعيل وقت تشغيل القناة الكامل،
|
||||
بينما تستمر التحميلات الكاملة العادية في التقاط الواصفات نفسها لتسجيل
|
||||
الأوامر الفعلي. أبقِ `registerFull(...)` للأعمال الخاصة بوقت التشغيل فقط.
|
||||
وإذا كان `registerFull(...)` يسجّل أساليب Gateway RPC، فاستخدم
|
||||
بادئة خاصة بـ Plugin. تبقى مساحات أسماء الإدارة في النواة (`config.*`,
|
||||
و`exec.approvals.*`، و`wizard.*`، و`update.*`) محجوزة وتُحل دائمًا إلى
|
||||
`operator.admin`.
|
||||
يتولى `defineChannelPluginEntry` معالجة فصل أوضاع التسجيل تلقائيًا. راجع
|
||||
[نقاط الإدخال](/ar/plugins/sdk-entrypoints#definechannelpluginentry) لجميع
|
||||
الخيارات.
|
||||
بينما تلتقط التحميلات الكاملة العادية الواصفات نفسها أيضًا من أجل التسجيل
|
||||
الفعلي للأوامر. وأبقِ `registerFull(...)` للأعمال الخاصة بوقت التشغيل فقط.
|
||||
إذا كان `registerFull(...)` يسجل أساليب Gateway RPC، فاستخدم
|
||||
بادئة خاصة بـ Plugin. تظل مساحات أسماء الإدارة في النواة (`config.*`,
|
||||
و`exec.approvals.*`, و`wizard.*`, و`update.*`) محجوزة وتُحل دائمًا
|
||||
إلى `operator.admin`.
|
||||
يتولى `defineChannelPluginEntry` فصل أوضاع التسجيل تلقائيًا. راجع
|
||||
[نقاط الإدخال](/ar/plugins/sdk-entrypoints#definechannelpluginentry) لمعرفة
|
||||
جميع الخيارات.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="إضافة نقطة إدخال للإعداد">
|
||||
أنشئ `setup-entry.ts` للتحميل الخفيف أثناء الإعداد الأولي:
|
||||
<Step title="أضف نقطة إدخال للإعداد">
|
||||
أنشئ `setup-entry.ts` للتحميل الخفيف أثناء الإلحاق الأولي:
|
||||
|
||||
```typescript setup-entry.ts
|
||||
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
@ -498,33 +500,33 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على
|
||||
export default defineSetupPluginEntry(acmeChatPlugin);
|
||||
```
|
||||
|
||||
يحمّل OpenClaw هذا بدلًا من نقطة الإدخال الكاملة عندما تكون القناة معطّلة
|
||||
أو غير مهيأة. وهذا يتجنب سحب شيفرة وقت تشغيل ثقيلة أثناء تدفقات الإعداد.
|
||||
راجع [الإعداد والتهيئة](/ar/plugins/sdk-setup#setup-entry) لمزيد من التفاصيل.
|
||||
يحمّل OpenClaw هذا بدلًا من نقطة الإدخال الكاملة عندما تكون القناة معطلة
|
||||
أو غير مضبوطة. وهذا يتجنب سحب شيفرة وقت تشغيل ثقيلة أثناء تدفقات الإعداد.
|
||||
راجع [الإعداد وConfig](/ar/plugins/sdk-setup#setup-entry) للحصول على التفاصيل.
|
||||
|
||||
يمكن لقنوات مساحة العمل المضمّنة التي تفصل التصديرات الآمنة للإعداد في
|
||||
وحدات جانبية أن تستخدم `defineBundledChannelSetupEntry(...)` من
|
||||
يمكن لقنوات مساحة العمل المضمّنة التي تقسم الصادرات الآمنة للإعداد إلى وحدات
|
||||
جانبية أن تستخدم `defineBundledChannelSetupEntry(...)` من
|
||||
`openclaw/plugin-sdk/channel-entry-contract` عندما تحتاج أيضًا إلى
|
||||
مُعيّن صريح لوقت التشغيل في وقت الإعداد.
|
||||
محدد صريح لوقت تشغيل الإعداد.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="معالجة الرسائل الواردة">
|
||||
يحتاج Plugin الخاص بك إلى تلقي الرسائل من المنصة وتمريرها إلى
|
||||
OpenClaw. النمط المعتاد هو Webhook يتحقق من الطلب ويقوم
|
||||
بإرساله عبر معالج الوارد الخاص بقناتك:
|
||||
<Step title="تعامل مع الرسائل الواردة">
|
||||
يحتاج Plugin الخاص بك إلى استقبال الرسائل من المنصة وتمريرها إلى
|
||||
OpenClaw. والنمط المعتاد هو Webhook يتحقق من الطلب ويقوم
|
||||
بإرساله عبر معالج inbound الخاص بقناتك:
|
||||
|
||||
```typescript
|
||||
registerFull(api) {
|
||||
api.registerHttpRoute({
|
||||
path: "/acme-chat/webhook",
|
||||
auth: "plugin", // مصادقة يديرها Plugin (تحقق من التواقيع بنفسك)
|
||||
auth: "plugin", // plugin-managed auth (verify signatures yourself)
|
||||
handler: async (req, res) => {
|
||||
const event = parseWebhookPayload(req);
|
||||
|
||||
// يقوم معالج الوارد الخاص بك بإرسال الرسالة إلى OpenClaw.
|
||||
// يعتمد التوصيل الدقيق على SDK الخاص بمنصتك —
|
||||
// راجع مثالًا حقيقيًا في حزمة Plugin المضمّنة الخاصة بـ Microsoft Teams أو Google Chat.
|
||||
// Your inbound handler dispatches the message to OpenClaw.
|
||||
// The exact wiring depends on your platform SDK —
|
||||
// see a real example in the bundled Microsoft Teams or Google Chat plugin package.
|
||||
await handleAcmeChatInbound(api, event);
|
||||
|
||||
res.statusCode = 200;
|
||||
@ -536,23 +538,23 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على
|
||||
```
|
||||
|
||||
<Note>
|
||||
معالجة الرسائل الواردة خاصة بكل قناة. كل Plugin قناة يملك
|
||||
مسار الوارد الخاص به. انظر إلى Plugins القنوات المضمّنة
|
||||
إن معالجة الرسائل الواردة خاصة بكل قناة. يمتلك كل Plugin قناة
|
||||
مسار inbound الخاص به. انظر إلى Plugins القنوات المضمّنة
|
||||
(مثل حزمة Plugin الخاصة بـ Microsoft Teams أو Google Chat) للاطلاع على أنماط حقيقية.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
|
||||
<a id="step-6-test"></a>
|
||||
<Step title="الاختبار">
|
||||
<Step title="اختبر">
|
||||
اكتب اختبارات موضوعة بجوار الشيفرة في `src/channel.test.ts`:
|
||||
|
||||
```typescript src/channel.test.ts
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { acmeChatPlugin } from "./channel.js";
|
||||
|
||||
describe("acme-chat plugin", () => {
|
||||
it("resolves account from config", () => {
|
||||
describe("plugin acme-chat", () => {
|
||||
it("يحل الحساب من الإعدادات", () => {
|
||||
const cfg = {
|
||||
channels: {
|
||||
"acme-chat": { token: "test-token", allowFrom: ["user1"] },
|
||||
@ -562,7 +564,7 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على
|
||||
expect(account.token).toBe("test-token");
|
||||
});
|
||||
|
||||
it("inspects account without materializing secrets", () => {
|
||||
it("يفحص الحساب دون إظهار الأسرار", () => {
|
||||
const cfg = {
|
||||
channels: { "acme-chat": { token: "test-token" } },
|
||||
} as any;
|
||||
@ -571,7 +573,7 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على
|
||||
expect(result.tokenStatus).toBe("available");
|
||||
});
|
||||
|
||||
it("reports missing config", () => {
|
||||
it("يبلّغ عن الإعدادات المفقودة", () => {
|
||||
const cfg = { channels: {} } as any;
|
||||
const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined);
|
||||
expect(result.configured).toBe(false);
|
||||
@ -583,7 +585,7 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على
|
||||
pnpm test -- <bundled-plugin-root>/acme-chat/
|
||||
```
|
||||
|
||||
بالنسبة إلى مساعدات الاختبار المشتركة، راجع [الاختبار](/ar/plugins/sdk-testing).
|
||||
للاطلاع على أدوات الاختبار المساعدة المشتركة، راجع [الاختبار](/ar/plugins/sdk-testing).
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -593,45 +595,45 @@ Plugins القنوات المضمّنة التي تعتمد بالفعل على
|
||||
```
|
||||
<bundled-plugin-root>/acme-chat/
|
||||
├── package.json # بيانات openclaw.channel الوصفية
|
||||
├── openclaw.plugin.json # ملف البيان مع مخطط التهيئة
|
||||
├── openclaw.plugin.json # Manifest مع مخطط config
|
||||
├── index.ts # defineChannelPluginEntry
|
||||
├── setup-entry.ts # defineSetupPluginEntry
|
||||
├── api.ts # التصديرات العامة (اختياري)
|
||||
├── runtime-api.ts # تصديرات وقت التشغيل الداخلية (اختياري)
|
||||
├── api.ts # الصادرات العامة (اختياري)
|
||||
├── runtime-api.ts # صادرات وقت التشغيل الداخلية (اختياري)
|
||||
└── src/
|
||||
├── channel.ts # ChannelPlugin عبر createChatChannelPlugin
|
||||
├── channel.test.ts # الاختبارات
|
||||
├── client.ts # عميل API الخاص بالمنصة
|
||||
├── client.ts # عميل API للمنصة
|
||||
└── runtime.ts # مخزن وقت التشغيل (عند الحاجة)
|
||||
```
|
||||
|
||||
## موضوعات متقدمة
|
||||
## مواضيع متقدمة
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="خيارات التسلسل" icon="git-branch" href="/ar/plugins/sdk-entrypoints#registration-mode">
|
||||
أوضاع رد ثابتة، أو مقيّدة بالحساب، أو مخصصة
|
||||
أوضاع رد ثابتة، أو ضمن نطاق الحساب، أو مخصصة
|
||||
</Card>
|
||||
<Card title="تكامل أداة الرسائل" icon="puzzle" href="/ar/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
<Card title="تكامل أداة message" icon="puzzle" href="/ar/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
describeMessageTool واكتشاف الإجراءات
|
||||
</Card>
|
||||
<Card title="حل الأهداف" icon="crosshair" href="/ar/plugins/architecture#channel-target-resolution">
|
||||
<Card title="تحليل الوجهة" icon="crosshair" href="/ar/plugins/architecture#channel-target-resolution">
|
||||
inferTargetChatType, looksLikeId, resolveTarget
|
||||
</Card>
|
||||
<Card title="مساعدات وقت التشغيل" icon="settings" href="/ar/plugins/sdk-runtime">
|
||||
<Card title="أدوات وقت التشغيل المساعدة" icon="settings" href="/ar/plugins/sdk-runtime">
|
||||
TTS وSTT والوسائط وsubagent عبر api.runtime
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Note>
|
||||
لا تزال بعض واجهات المساعدة المضمّنة موجودة لصيانة Plugins المضمّنة
|
||||
والتوافق. وهي ليست النمط الموصى به لـ Plugins القنوات الجديدة؛
|
||||
فضّل المسارات الفرعية العامة للقناة/الإعداد/الرد/وقت التشغيل من سطح SDK
|
||||
المشترك ما لم تكن تصون تلك العائلة من Plugins المضمّنة مباشرةً.
|
||||
لا تزال بعض نقاط الربط الخاصة بالأدوات المساعدة المضمّنة موجودة لصيانة Plugins
|
||||
المضمّنة ولأغراض التوافق. لكنها ليست النمط الموصى به لـ Plugins القنوات الجديدة؛
|
||||
بل يُفضّل استخدام المسارات الفرعية العامة للقنوات/الإعداد/الرد/وقت التشغيل من سطح
|
||||
SDK المشترك، إلا إذا كنت تصون عائلة Plugin المضمّنة تلك مباشرة.
|
||||
</Note>
|
||||
|
||||
## الخطوات التالية
|
||||
|
||||
- [Plugins الموفّرين](/ar/plugins/sdk-provider-plugins) — إذا كان Plugin الخاص بك يوفّر أيضًا نماذج
|
||||
- [Plugins المزودين](/ar/plugins/sdk-provider-plugins) — إذا كان Plugin الخاص بك يوفر أيضًا نماذج
|
||||
- [نظرة عامة على SDK](/ar/plugins/sdk-overview) — المرجع الكامل لاستيراد المسارات الفرعية
|
||||
- [اختبار SDK](/ar/plugins/sdk-testing) — أدوات الاختبار واختبارات العقود
|
||||
- [ملف بيان Plugin](/ar/plugins/manifest) — مخطط ملف البيان الكامل
|
||||
- [اختبار SDK](/ar/plugins/sdk-testing) — أدوات الاختبار المساعدة واختبارات العقود
|
||||
- [Plugin Manifest](/ar/plugins/manifest) — مخطط manifest الكامل
|
||||
|
||||
@ -1,30 +1,30 @@
|
||||
---
|
||||
read_when:
|
||||
- تحتاج إلى معرفة أي مسار فرعي من SDK يجب الاستيراد منه
|
||||
- تريد مرجعًا لجميع أساليب التسجيل في `OpenClawPluginApi`
|
||||
- تريد مرجعًا لجميع أساليب التسجيل في OpenClawPluginApi
|
||||
- أنت تبحث عن تصدير محدد في SDK
|
||||
sidebarTitle: SDK Overview
|
||||
summary: خريطة الاستيراد، مرجع API للتسجيل، وبنية SDK
|
||||
summary: مرجع Import map وواجهة برمجة تطبيقات التسجيل وبنية SDK
|
||||
title: نظرة عامة على Plugin SDK
|
||||
x-i18n:
|
||||
generated_at: "2026-04-17T07:17:56Z"
|
||||
generated_at: "2026-04-18T07:15:30Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b177fdb6830f415d998a24812bc2c7db8124d3ba77b0174c9a67ac7d747f7e5a
|
||||
source_hash: 05d3d0022cca32d29c76f6cea01cdf4f88ac69ef0ef3d7fb8a60fbf9a6b9b331
|
||||
source_path: plugins/sdk-overview.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# نظرة عامة على Plugin SDK
|
||||
|
||||
يمثل Plugin SDK العقد المطبوع بين المكونات الإضافية والنواة. تُعد هذه الصفحة
|
||||
يمثل Plugin SDK العقد المطبوع بين Plugins والنواة. وهذه الصفحة هي
|
||||
المرجع الخاص بـ **ما الذي يجب استيراده** و**ما الذي يمكنك تسجيله**.
|
||||
|
||||
<Tip>
|
||||
**هل تبحث عن دليل إرشادي؟**
|
||||
- أول مكوّن إضافي؟ ابدأ من [البدء](/ar/plugins/building-plugins)
|
||||
- مكوّن إضافي للقنوات؟ راجع [المكونات الإضافية للقنوات](/ar/plugins/sdk-channel-plugins)
|
||||
- مكوّن إضافي للموفّر؟ راجع [المكونات الإضافية للموفّر](/ar/plugins/sdk-provider-plugins)
|
||||
- أول Plugin؟ ابدأ من [البدء](/ar/plugins/building-plugins)
|
||||
- Plugin قناة؟ راجع [Plugins القنوات](/ar/plugins/sdk-channel-plugins)
|
||||
- Plugin موفّر؟ راجع [Plugins الموفّرين](/ar/plugins/sdk-provider-plugins)
|
||||
</Tip>
|
||||
|
||||
## اصطلاح الاستيراد
|
||||
@ -36,39 +36,39 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
```
|
||||
|
||||
كل مسار فرعي هو وحدة صغيرة مستقلة بذاتها. يساعد ذلك في إبقاء بدء التشغيل سريعًا
|
||||
ويمنع مشكلات التبعيات الدائرية. بالنسبة إلى مساعدات الإدخال/البناء الخاصة بالقنوات،
|
||||
فإن المسار المفضّل هو `openclaw/plugin-sdk/channel-core`؛ واحتفظ بـ `openclaw/plugin-sdk/core`
|
||||
للسطح الأشمل والمساعدات المشتركة مثل
|
||||
كل مسار فرعي هو وحدة صغيرة مستقلة بذاتها. وهذا يحافظ على سرعة بدء التشغيل
|
||||
ويمنع مشكلات التبعيات الدائرية. وبالنسبة إلى مساعدات إدخال/بناء القنوات الخاصة،
|
||||
فإن المسار المفضل هو `openclaw/plugin-sdk/channel-core`؛ واحتفظ بـ `openclaw/plugin-sdk/core` من أجل
|
||||
السطح الأشمل الجامع والمساعدات المشتركة مثل
|
||||
`buildChannelConfigSchema`.
|
||||
|
||||
لا تُضف أو تعتمد على مسارات ربط مريحة تحمل أسماء موفّرين مثل
|
||||
`openclaw/plugin-sdk/slack` أو `openclaw/plugin-sdk/discord` أو
|
||||
`openclaw/plugin-sdk/signal` أو `openclaw/plugin-sdk/whatsapp` أو
|
||||
مسارات المساعدات ذات العلامات الخاصة بالقنوات. يجب على المكونات الإضافية المضمّنة
|
||||
تجميع المسارات الفرعية العامة من SDK داخل ملفات `api.ts` أو `runtime-api.ts`
|
||||
الخاصة بها، ويجب على النواة إما استخدام هذه الملفات المحلية الخاصة بالمكوّن الإضافي
|
||||
أو إضافة عقد عام ضيق في SDK عندما تكون الحاجة فعلًا عابرة للقنوات.
|
||||
لا تضف أو تعتمد على طبقات تسهيلية مسماة باسم الموفّر مثل
|
||||
`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
|
||||
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`، أو
|
||||
طبقات مساعدة موسومة باسم القناة. يجب أن تقوم Plugins المجمّعة بتركيب
|
||||
المسارات الفرعية العامة لـ SDK داخل ملفات `api.ts` أو `runtime-api.ts` الخاصة بها، ويجب على النواة
|
||||
إما استخدام هذه الملفات المحلية الخاصة بالـ Plugin أو إضافة عقد SDK عام ضيق
|
||||
عندما تكون الحاجة فعلًا عابرة للقنوات.
|
||||
|
||||
لا تزال خريطة التصدير المُولَّدة تحتوي على مجموعة صغيرة من مسارات المساعدات الخاصة
|
||||
بالمكونات الإضافية المضمّنة مثل `plugin-sdk/feishu` و`plugin-sdk/feishu-setup`
|
||||
و`plugin-sdk/zalo` و`plugin-sdk/zalo-setup` و`plugin-sdk/matrix*`. توجد هذه
|
||||
المسارات الفرعية فقط لصيانة المكونات الإضافية المضمّنة والتوافق، ولذلك أُزيلت عمدًا
|
||||
من الجدول الشائع أدناه وليست مسار الاستيراد الموصى به للمكونات الإضافية الجديدة من
|
||||
جهات خارجية.
|
||||
لا تزال خريطة التصدير المولدة تحتوي على مجموعة صغيرة من
|
||||
طبقات المساعدة الخاصة بالـ Plugins المجمّعة مثل `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
|
||||
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup`, و `plugin-sdk/matrix*`. هذه
|
||||
المسارات الفرعية موجودة فقط لصيانة Plugins المجمّعة والتوافق؛ وهي
|
||||
مستبعدة عمدًا من الجدول الشائع أدناه وليست مسار الاستيراد الموصى به
|
||||
لـ Plugins الخارجية الجديدة.
|
||||
|
||||
## مرجع المسارات الفرعية
|
||||
|
||||
أكثر المسارات الفرعية استخدامًا، مجمّعة حسب الغرض. توجد القائمة الكاملة
|
||||
المُولَّدة التي تضم أكثر من 200 مسار فرعي في `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
أكثر المسارات الفرعية استخدامًا، مجمعة حسب الغرض. وتوجد القائمة الكاملة المولدة التي تضم
|
||||
أكثر من 200 مسار فرعي في `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
|
||||
لا تزال مسارات المساعدات المحجوزة الخاصة بالمكونات الإضافية المضمّنة تظهر في تلك
|
||||
القائمة المُولَّدة. تعامل معها على أنها أسطح تنفيذ داخلية/توافقية ما لم تروّج لها
|
||||
صفحة توثيق صراحةً باعتبارها عامة.
|
||||
لا تزال المسارات الفرعية المحجوزة لمساعدات Plugins المجمّعة تظهر في تلك القائمة المولدة.
|
||||
تعامل معها على أنها تفاصيل تنفيذ/أسطح توافق ما لم تقم صفحة توثيق
|
||||
بترقية أحدها صراحةً إلى سطح عام.
|
||||
|
||||
### إدخال المكوّن الإضافي
|
||||
### إدخال Plugin
|
||||
|
||||
| المسار الفرعي | أهم التصديرات |
|
||||
| Subpath | Key exports |
|
||||
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
|
||||
@ -77,188 +77,202 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="المسارات الفرعية للقنوات">
|
||||
| المسار الفرعي | أهم التصديرات |
|
||||
| Subpath | Key exports |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/config-schema` | تصدير مخطط Zod الجذري لـ `openclaw.json` (`OpenClawSchema`) |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`، بالإضافة إلى `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/setup` | مساعدات معالج الإعداد المشتركة، ومطالبات قائمة السماح، وبناة حالة الإعداد |
|
||||
| `plugin-sdk/setup` | مساعدات معالج الإعداد المشتركة، ومطالبات قائمة السماح، ومنشئات حالة الإعداد |
|
||||
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | مساعدات تهيئة/بوابة إجراءات متعددة الحسابات، ومساعدات الرجوع إلى الحساب الافتراضي |
|
||||
| `plugin-sdk/account-core` | مساعدات إعدادات/بوابة إجراءات متعددة الحسابات، ومساعدات الرجوع إلى الحساب الافتراضي |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`، ومساعدات تطبيع معرّف الحساب |
|
||||
| `plugin-sdk/account-resolution` | مساعدات البحث عن الحساب + الرجوع الافتراضي |
|
||||
| `plugin-sdk/account-resolution` | البحث عن الحساب + مساعدات الرجوع إلى الافتراضي |
|
||||
| `plugin-sdk/account-helpers` | مساعدات ضيقة لقائمة الحسابات/إجراءات الحساب |
|
||||
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | أنواع مخطط تهيئة القناة |
|
||||
| `plugin-sdk/telegram-command-config` | مساعدات تطبيع/تحقق الأوامر المخصصة في Telegram مع الرجوع إلى العقد المضمّن |
|
||||
| `plugin-sdk/channel-config-schema` | أنواع مخطط إعدادات القناة |
|
||||
| `plugin-sdk/telegram-command-config` | مساعدات تطبيع/تحقق الأوامر المخصصة لـ Telegram مع الرجوع إلى العقد المجمّع |
|
||||
| `plugin-sdk/command-gating` | مساعدات ضيقة لبوابة تفويض الأوامر |
|
||||
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
|
||||
| `plugin-sdk/inbound-envelope` | مساعدات مشتركة لتوجيه الوارد + بناء الغلاف |
|
||||
| `plugin-sdk/inbound-envelope` | مساعدات مشتركة لبناء المسار الوارد + الغلاف |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | مساعدات مشتركة لتسجيل الوارد وإرساله |
|
||||
| `plugin-sdk/messaging-targets` | مساعدات تحليل/مطابقة الأهداف |
|
||||
| `plugin-sdk/outbound-media` | مساعدات مشتركة لتحميل الوسائط الصادرة |
|
||||
| `plugin-sdk/outbound-runtime` | مساعدات هوية الإرسال/مفوّض الإرسال الصادر |
|
||||
| `plugin-sdk/outbound-runtime` | مساعدات هوية/إرسال الصادر |
|
||||
| `plugin-sdk/poll-runtime` | مساعدات ضيقة لتطبيع الاستطلاعات |
|
||||
| `plugin-sdk/thread-bindings-runtime` | دورة حياة ربط الخيوط ومساعدات المهايئ |
|
||||
| `plugin-sdk/agent-media-payload` | بانٍ قديم لحمولة وسائط الوكيل |
|
||||
| `plugin-sdk/conversation-runtime` | مساعدات ربط المحادثة/الخيط، والاقتران، والربط المهيأ |
|
||||
| `plugin-sdk/runtime-config-snapshot` | مساعد لقطة تهيئة وقت التشغيل |
|
||||
| `plugin-sdk/runtime-group-policy` | مساعدات حل سياسة المجموعة في وقت التشغيل |
|
||||
| `plugin-sdk/channel-status` | مساعدات مشتركة للقطات/ملخصات حالة القناة |
|
||||
| `plugin-sdk/channel-config-primitives` | أوليات ضيقة لمخطط تهيئة القناة |
|
||||
| `plugin-sdk/channel-config-writes` | مساعدات تفويض كتابة تهيئة القناة |
|
||||
| `plugin-sdk/channel-plugin-common` | تصديرات تمهيدية مشتركة للمكونات الإضافية للقنوات |
|
||||
| `plugin-sdk/allowlist-config-edit` | مساعدات قراءة/تحرير تهيئة قائمة السماح |
|
||||
| `plugin-sdk/group-access` | مساعدات مشتركة لقرارات الوصول إلى المجموعات |
|
||||
| `plugin-sdk/direct-dm` | مساعدات مشتركة للمصادقة/الحماية الخاصة بالرسائل المباشرة |
|
||||
| `plugin-sdk/agent-media-payload` | منشئ حمولة وسائط الوكيل القديم |
|
||||
| `plugin-sdk/conversation-runtime` | مساعدات المحادثة/ربط الخيوط، والاقتران، والربط المهيأ |
|
||||
| `plugin-sdk/runtime-config-snapshot` | مساعد لقطة إعدادات وقت التشغيل |
|
||||
| `plugin-sdk/runtime-group-policy` | مساعدات حل سياسة المجموعات في وقت التشغيل |
|
||||
| `plugin-sdk/channel-status` | مساعدات مشتركة لملخص/لقطة حالة القناة |
|
||||
| `plugin-sdk/channel-config-primitives` | العناصر الأولية الضيقة لمخطط إعدادات القناة |
|
||||
| `plugin-sdk/channel-config-writes` | مساعدات تفويض كتابة إعدادات القناة |
|
||||
| `plugin-sdk/channel-plugin-common` | تصديرات تمهيد Plugin القناة المشتركة |
|
||||
| `plugin-sdk/allowlist-config-edit` | مساعدات قراءة/تعديل إعدادات قائمة السماح |
|
||||
| `plugin-sdk/group-access` | مساعدات مشتركة لقرارات وصول المجموعات |
|
||||
| `plugin-sdk/direct-dm` | مساعدات مشتركة لمصادقة/حماية الرسائل المباشرة |
|
||||
| `plugin-sdk/interactive-runtime` | مساعدات تطبيع/اختزال حمولة الرد التفاعلي |
|
||||
| `plugin-sdk/channel-inbound` | مساعدات إلغاء الارتداد للوارد، ومطابقة الإشارات، وسياسات الإشارة، ومساعدات الغلاف |
|
||||
| `plugin-sdk/channel-send-result` | أنواع نتائج الرد |
|
||||
| `plugin-sdk/channel-inbound` | حاوية توافق لمساعدات إزالة ارتداد الوارد، ومطابقة الإشارة، ومساعدات سياسة الإشارة، ومساعدات الغلاف |
|
||||
| `plugin-sdk/channel-mention-gating` | مساعدات ضيقة لسياسة الإشارة من دون سطح وقت التشغيل الوارد الأوسع |
|
||||
| `plugin-sdk/channel-location` | سياق موقع القناة ومساعدات التنسيق |
|
||||
| `plugin-sdk/channel-logging` | مساعدات تسجيل القناة لحالات إسقاط الوارد وإخفاقات الكتابة/التأكيد |
|
||||
| `plugin-sdk/channel-send-result` | أنواع نتيجة الرد |
|
||||
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
|
||||
| `plugin-sdk/channel-targets` | مساعدات تحليل/مطابقة الأهداف |
|
||||
| `plugin-sdk/channel-contract` | أنواع عقد القناة |
|
||||
| `plugin-sdk/channel-feedback` | ربط الملاحظات/التفاعلات |
|
||||
| `plugin-sdk/channel-feedback` | توصيل التغذية الراجعة/التفاعلات |
|
||||
| `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لعقد الأسرار مثل `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`، وأنواع أهداف الأسرار |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="المسارات الفرعية للموفّر">
|
||||
| المسار الفرعي | أهم التصديرات |
|
||||
<Accordion title="المسارات الفرعية للموفّرين">
|
||||
| Subpath | Key exports |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/provider-setup` | مساعدات إعداد منسّقة للموفّرين المحليين/المستضافين ذاتيًا |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | مساعدات إعداد مركزة للموفّر المستضاف ذاتيًا والمتوافق مع OpenAI |
|
||||
| `plugin-sdk/cli-backend` | إعدادات CLI الخلفية الافتراضية + ثوابت المراقبة |
|
||||
| `plugin-sdk/provider-auth-runtime` | مساعدات حل مفتاح API وقت التشغيل للمكونات الإضافية للموفّرين |
|
||||
| `plugin-sdk/provider-auth-api-key` | مساعدات إعداد/كتابة ملف تعريف مفتاح API مثل `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | بانٍ قياسي لنتائج مصادقة OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | مساعدات تسجيل الدخول التفاعلي المشتركة للمكونات الإضافية للموفّرين |
|
||||
| `plugin-sdk/provider-setup` | مساعدات منسقة لإعداد الموفّرين المحليين/المستضافين ذاتيًا |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | مساعدات مركزة لإعداد موفّرين مستضافين ذاتيًا متوافقين مع OpenAI |
|
||||
| `plugin-sdk/cli-backend` | افتراضيات CLI backend + ثوابت watchdog |
|
||||
| `plugin-sdk/provider-auth-runtime` | مساعدات وقت التشغيل لحل مفاتيح API في Plugins الموفّرين |
|
||||
| `plugin-sdk/provider-auth-api-key` | مساعدات إعداد/كتابة ملفات تعريف مفاتيح API مثل `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | منشئ موحد لنتيجة مصادقة OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | مساعدات تسجيل الدخول التفاعلي المشتركة لـ Plugins الموفّرين |
|
||||
| `plugin-sdk/provider-env-vars` | مساعدات البحث عن متغيرات البيئة لمصادقة الموفّر |
|
||||
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`، وبناة سياسات إعادة التشغيل المشتركة، ومساعدات نقاط نهاية الموفّر، ومساعدات تطبيع معرّف النموذج مثل `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`، ومنشئات سياسة الإعادة المشتركة، ومساعدات نقاط نهاية الموفّر، ومساعدات تطبيع معرّفات النماذج مثل `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-http` | مساعدات عامة لإمكانات HTTP/نقاط نهاية الموفّر |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | مساعدات ضيقة لعقد تهيئة/اختيار الجلب عبر الويب مثل `enablePluginInConfig` و`WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-web-fetch` | مساعدات تسجيل/تخزين مؤقت لموفّر الجلب عبر الويب |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | مساعدات ضيقة لتهيئة/اعتماد البحث عبر الويب للموفّرين الذين لا يحتاجون إلى ربط تمكين المكوّن الإضافي |
|
||||
| `plugin-sdk/provider-web-search-contract` | مساعدات ضيقة لعقد تهيئة/اعتماد البحث عبر الويب مثل `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`، وضبط/جلب بيانات الاعتماد ضمن النطاق |
|
||||
| `plugin-sdk/provider-web-search` | مساعدات وقت التشغيل/التخزين المؤقت/التسجيل لموفّر البحث عبر الويب |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`، وتنظيف مخطط Gemini + التشخيصات، ومساعدات التوافق الخاصة بـ xAI مثل `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-http` | مساعدات عامة لقدرات HTTP/نقطة النهاية الخاصة بالموفّر |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | مساعدات ضيقة لعقد إعدادات/اختيار web-fetch مثل `enablePluginInConfig` و `WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-web-fetch` | مساعدات تسجيل/تخزين مؤقت لموفّر web-fetch |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | مساعدات ضيقة لإعدادات/بيانات اعتماد web-search للموفّرين الذين لا يحتاجون إلى توصيل تمكين Plugin |
|
||||
| `plugin-sdk/provider-web-search-contract` | مساعدات ضيقة لعقد إعدادات/بيانات اعتماد web-search مثل `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`، وواضعات/قارئات بيانات اعتماد ذات نطاق محدد |
|
||||
| `plugin-sdk/provider-web-search` | مساعدات وقت التشغيل/التسجيل/التخزين المؤقت لموفّر web-search |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`، وتنظيف مخطط Gemini + التشخيصات، ومساعدات توافق xAI مثل `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` وما شابه |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`، وأنواع مغلفات التدفق، ومساعدات المغلفات المشتركة لـ Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-onboard` | مساعدات تصحيح تهيئة الإعداد الأولي |
|
||||
| `plugin-sdk/global-singleton` | مساعدات العملية المحلية للمفردات/الخرائط/التخزين المؤقت |
|
||||
| `plugin-sdk/provider-onboard` | مساعدات تصحيح إعدادات الإعداد الأولي |
|
||||
| `plugin-sdk/global-singleton` | مساعدات singleton/map/cache محلية على مستوى العملية |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="المسارات الفرعية للمصادقة والأمان">
|
||||
| المسار الفرعي | أهم التصديرات |
|
||||
| Subpath | Key exports |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`، ومساعدات سجل الأوامر، ومساعدات تفويض المرسل |
|
||||
| `plugin-sdk/command-status` | بُناة رسائل الأوامر/المساعدة مثل `buildCommandsMessagePaginated` و`buildHelpMessage` |
|
||||
| `plugin-sdk/approval-auth-runtime` | مساعدات حلّ المعتمِد ومصادقة الإجراءات داخل نفس الدردشة |
|
||||
| `plugin-sdk/approval-client-runtime` | مساعدات ملف التعريف/المرشّح للموافقة على التنفيذ الأصلي |
|
||||
| `plugin-sdk/approval-delivery-runtime` | مهايئات إمكانات/تسليم الموافقة الأصلية |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`، ومساعدات سجل الأوامر، ومساعدات تفويض المُرسِل |
|
||||
| `plugin-sdk/command-status` | منشئات رسائل الأوامر/المساعدة مثل `buildCommandsMessagePaginated` و `buildHelpMessage` |
|
||||
| `plugin-sdk/approval-auth-runtime` | مساعدات حل الموافقين ومصادقة الإجراءات داخل الدردشة نفسها |
|
||||
| `plugin-sdk/approval-client-runtime` | مساعدات ملفات تعريف/تصفية موافقات التنفيذ الأصلية |
|
||||
| `plugin-sdk/approval-delivery-runtime` | مهايئات قدرات/تسليم الموافقات الأصلية |
|
||||
| `plugin-sdk/approval-gateway-runtime` | مساعد مشترك لحل Gateway الخاص بالموافقات |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | مساعدات خفيفة لتحميل مهايئ الموافقة الأصلية لنقاط إدخال القنوات السريعة |
|
||||
| `plugin-sdk/approval-handler-runtime` | مساعدات أشمل لوقت تشغيل معالج الموافقة؛ يُفضَّل استخدام مسارات المهايئ/Gateway الأضيق عندما تكون كافية |
|
||||
| `plugin-sdk/approval-native-runtime` | مساعدات الهدف الأصلي للموافقة + ربط الحساب |
|
||||
| `plugin-sdk/approval-reply-runtime` | مساعدات حمولة الرد الخاصة بموافقات التنفيذ/Plugin |
|
||||
| `plugin-sdk/command-auth-native` | مساعدات المصادقة الأصلية للأوامر + هدف الجلسة الأصلي |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | مساعدات خفيفة لتحميل مهايئات الموافقات الأصلية لنقاط إدخال القنوات السريعة |
|
||||
| `plugin-sdk/approval-handler-runtime` | مساعدات أوسع لوقت تشغيل معالج الموافقات؛ فضّل طبقات المهايئ/Gateway الأضيق عندما تكون كافية |
|
||||
| `plugin-sdk/approval-native-runtime` | مساعدات الهدف الأصلي للموافقات + ربط الحساب |
|
||||
| `plugin-sdk/approval-reply-runtime` | مساعدات حمولة رد موافقات التنفيذ/Plugin |
|
||||
| `plugin-sdk/command-auth-native` | مساعدات مصادقة الأوامر الأصلية + هدف الجلسة الأصلي |
|
||||
| `plugin-sdk/command-detection` | مساعدات مشتركة لاكتشاف الأوامر |
|
||||
| `plugin-sdk/command-surface` | مساعدات تطبيع جسم الأمر وسطح الأمر |
|
||||
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لتجميع عقود الأسرار لأسطح أسرار القنوات/Plugin |
|
||||
| `plugin-sdk/secret-ref-runtime` | `coerceSecretRef` الضيق ومساعدات كتابة SecretRef لتحليل عقود الأسرار/التهيئة |
|
||||
| `plugin-sdk/security-runtime` | مساعدات مشتركة للثقة، وتقييد الرسائل المباشرة، والمحتوى الخارجي، وتجميع الأسرار |
|
||||
| `plugin-sdk/ssrf-policy` | مساعدات سياسة SSRF لقائمة السماح بالمضيفين والشبكات الخاصة |
|
||||
| `plugin-sdk/ssrf-runtime` | مساعدات المرسِل المثبّت، وfetch المحمي من SSRF، وسياسات SSRF |
|
||||
| `plugin-sdk/secret-input` | مساعدات تحليل إدخال الأسرار |
|
||||
| `plugin-sdk/webhook-ingress` | مساعدات الطلب/الهدف الخاصة بـ Webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | مساعدات حجم جسم الطلب/المهلة الزمنية |
|
||||
| `plugin-sdk/channel-secret-runtime` | مساعدات ضيقة لتجميع عقود الأسرار لأسطح أسرار القنوات/Plugins |
|
||||
| `plugin-sdk/secret-ref-runtime` | مساعدات ضيقة لـ `coerceSecretRef` وأنواع SecretRef لتحليل عقود الأسرار/الإعدادات |
|
||||
| `plugin-sdk/security-runtime` | مساعدات مشتركة للثقة، وبوابة الرسائل المباشرة، والمحتوى الخارجي، وتجميع الأسرار |
|
||||
| `plugin-sdk/ssrf-policy` | مساعدات سياسة SSRF الخاصة بقائمة سماح المضيف والشبكة الخاصة |
|
||||
| `plugin-sdk/ssrf-dispatcher` | مساعدات ضيقة لـ pinned-dispatcher من دون سطح وقت تشغيل البنية الأوسع |
|
||||
| `plugin-sdk/ssrf-runtime` | مساعدات pinned-dispatcher وfetch المحمي بـ SSRF وسياسة SSRF |
|
||||
| `plugin-sdk/secret-input` | مساعدات تحليل مدخلات الأسرار |
|
||||
| `plugin-sdk/webhook-ingress` | مساعدات طلب/هدف Webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | مساعدات حجم جسم الطلب/المهلة |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="المسارات الفرعية لوقت التشغيل والتخزين">
|
||||
| المسار الفرعي | أهم التصديرات |
|
||||
| Subpath | Key exports |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/runtime` | مساعدات عامة لوقت التشغيل/التسجيل/النسخ الاحتياطي/تثبيت المكونات الإضافية |
|
||||
| `plugin-sdk/runtime-env` | مساعدات ضيقة لبيئة وقت التشغيل، والمسجل، والمهلة الزمنية، وإعادة المحاولة، والتراجع التدريجي |
|
||||
| `plugin-sdk/runtime` | مساعدات واسعة لوقت التشغيل/التسجيل/النسخ الاحتياطي/تثبيت Plugins |
|
||||
| `plugin-sdk/runtime-env` | مساعدات ضيقة لبيئة وقت التشغيل، والمسجل، والمهلة، وإعادة المحاولة، والتراجع التدريجي |
|
||||
| `plugin-sdk/channel-runtime-context` | مساعدات عامة لتسجيل سياق وقت تشغيل القناة والبحث عنه |
|
||||
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/plugin-runtime` | مساعدات مشتركة للأوامر/الخطافات/HTTP/التفاعل الخاصة بـ Plugin |
|
||||
| `plugin-sdk/hook-runtime` | مساعدات مشتركة لخط أنابيب Webhook/الخطافات الداخلية |
|
||||
| `plugin-sdk/lazy-runtime` | مساعدات الاستيراد/الربط الكسول لوقت التشغيل مثل `createLazyRuntimeModule` و`createLazyRuntimeMethod` و`createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/plugin-runtime` | مساعدات مشتركة للأوامر/الخطافات/HTTP/التفاعل الخاصة بالـ Plugin |
|
||||
| `plugin-sdk/hook-runtime` | مساعدات مشتركة لخطافات Webhook/الخطافات الداخلية |
|
||||
| `plugin-sdk/lazy-runtime` | مساعدات الاستيراد/الربط الكسول لوقت التشغيل مثل `createLazyRuntimeModule` و `createLazyRuntimeMethod` و `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | مساعدات تنفيذ العمليات |
|
||||
| `plugin-sdk/cli-runtime` | مساعدات تنسيق CLI والانتظار والإصدار |
|
||||
| `plugin-sdk/gateway-runtime` | مساعدات عميل Gateway وتصحيح حالة القناة |
|
||||
| `plugin-sdk/config-runtime` | مساعدات تحميل/كتابة التهيئة |
|
||||
| `plugin-sdk/telegram-command-config` | تطبيع اسم/وصف أوامر Telegram وفحوصات التكرار/التعارض، حتى عندما لا يكون سطح عقد Telegram المضمّن متاحًا |
|
||||
| `plugin-sdk/approval-runtime` | مساعدات موافقات التنفيذ/Plugin، وبناة إمكانات الموافقة، ومساعدات المصادقة/الملف التعريفي، ومساعدات التوجيه/وقت التشغيل الأصلية |
|
||||
| `plugin-sdk/reply-runtime` | مساعدات مشتركة لوقت تشغيل الوارد/الرد، والتجزئة، والإرسال، وHeartbeat، ومخطط الرد |
|
||||
| `plugin-sdk/config-runtime` | مساعدات تحميل/كتابة الإعدادات |
|
||||
| `plugin-sdk/telegram-command-config` | تطبيع اسم/وصف أوامر Telegram والتحقق من التكرار/التعارض، حتى عندما لا يكون سطح عقد Telegram المجمّع متاحًا |
|
||||
| `plugin-sdk/text-autolink-runtime` | اكتشاف الروابط التلقائية لمراجع الملفات من دون حاوية text-runtime الأوسع |
|
||||
| `plugin-sdk/approval-runtime` | مساعدات موافقات التنفيذ/Plugin، ومنشئات قدرات الموافقة، ومساعدات المصادقة/الملف التعريفي، ومساعدات التوجيه/وقت التشغيل الأصلية |
|
||||
| `plugin-sdk/reply-runtime` | مساعدات مشتركة لوقت تشغيل الوارد/الرد، والتقسيم، والإرسال، وHeartbeat، ومخطط الرد |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | مساعدات ضيقة لإرسال/إنهاء الرد |
|
||||
| `plugin-sdk/reply-history` | مساعدات مشتركة لسجل الرد ضمن نافذة قصيرة مثل `buildHistoryContext` و`recordPendingHistoryEntry` و`clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-history` | مساعدات مشتركة لسجل الردود ضمن نافذة قصيرة مثل `buildHistoryContext` و `recordPendingHistoryEntry` و `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | مساعدات ضيقة لتجزئة النص/Markdown |
|
||||
| `plugin-sdk/reply-chunking` | مساعدات ضيقة لتقسيم النص/Markdown |
|
||||
| `plugin-sdk/session-store-runtime` | مساعدات مسار مخزن الجلسة + `updated-at` |
|
||||
| `plugin-sdk/state-paths` | مساعدات مسارات دليل الحالة/OAuth |
|
||||
| `plugin-sdk/routing` | مساعدات التوجيه/مفتاح الجلسة/ربط الحساب مثل `resolveAgentRoute` و`buildAgentSessionKey` و`resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | مساعدات مشتركة لملخص حالة القناة/الحساب، والقيم الافتراضية لحالة وقت التشغيل، ومساعدات بيانات التعريف الخاصة بالمشكلات |
|
||||
| `plugin-sdk/target-resolver-runtime` | مساعدات مشتركة لحلّ الأهداف |
|
||||
| `plugin-sdk/string-normalization-runtime` | مساعدات تطبيع slug/السلاسل النصية |
|
||||
| `plugin-sdk/state-paths` | مساعدات مسارات الحالة/دليل OAuth |
|
||||
| `plugin-sdk/routing` | مساعدات ربط المسار/مفتاح الجلسة/الحساب مثل `resolveAgentRoute` و `buildAgentSessionKey` و `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | مساعدات مشتركة لملخص حالة القناة/الحساب، وافتراضيات حالة وقت التشغيل، ومساعدات بيانات تعريف المشكلات |
|
||||
| `plugin-sdk/target-resolver-runtime` | مساعدات مشتركة لحل الأهداف |
|
||||
| `plugin-sdk/string-normalization-runtime` | مساعدات تطبيع slug/السلاسل |
|
||||
| `plugin-sdk/request-url` | استخراج عناوين URL النصية من مدخلات شبيهة بـ fetch/request |
|
||||
| `plugin-sdk/run-command` | مشغّل أوامر مؤقّت بنتائج `stdout`/`stderr` مطبّعة |
|
||||
| `plugin-sdk/param-readers` | قارئات معلمات شائعة للأدوات/CLI |
|
||||
| `plugin-sdk/run-command` | مشغّل أوامر موقّت مع نتائج stdout/stderr مطبّعة |
|
||||
| `plugin-sdk/param-readers` | قارئات المعلمات الشائعة للأدوات/CLI |
|
||||
| `plugin-sdk/tool-payload` | استخراج الحمولات المطبّعة من كائنات نتائج الأدوات |
|
||||
| `plugin-sdk/tool-send` | استخراج حقول هدف الإرسال القياسية من وسائط الأدوات |
|
||||
| `plugin-sdk/tool-send` | استخراج حقول هدف الإرسال القياسية من وسائط الأداة |
|
||||
| `plugin-sdk/temp-path` | مساعدات مشتركة لمسارات التنزيل المؤقت |
|
||||
| `plugin-sdk/logging-core` | مساعدات مسجل النظام الفرعي والتنقيح |
|
||||
| `plugin-sdk/logging-core` | مساعدات مسجل النظام الفرعي وإخفاء البيانات الحساسة |
|
||||
| `plugin-sdk/markdown-table-runtime` | مساعدات أوضاع جداول Markdown |
|
||||
| `plugin-sdk/json-store` | مساعدات صغيرة لقراءة/كتابة حالة JSON |
|
||||
| `plugin-sdk/file-lock` | مساعدات إعادة الدخول لقفل الملفات |
|
||||
| `plugin-sdk/persistent-dedupe` | مساعدات ذاكرة التخزين المؤقت لإزالة التكرار المدعومة بالقرص |
|
||||
| `plugin-sdk/acp-runtime` | مساعدات وقت تشغيل ACP/الجلسة وإرسال الرد |
|
||||
| `plugin-sdk/agent-config-primitives` | أوليات ضيقة لمخطط تهيئة وقت تشغيل الوكيل |
|
||||
| `plugin-sdk/file-lock` | مساعدات قفل الملفات القابلة لإعادة الدخول |
|
||||
| `plugin-sdk/persistent-dedupe` | مساعدات ذاكرة التخزين المؤقت لإزالة التكرار المعتمدة على القرص |
|
||||
| `plugin-sdk/acp-runtime` | مساعدات ACP لوقت التشغيل/الجلسة وإرسال الردود |
|
||||
| `plugin-sdk/acp-binding-resolve-runtime` | حل ربط ACP للقراءة فقط من دون استيرادات بدء دورة الحياة |
|
||||
| `plugin-sdk/agent-config-primitives` | عناصر أولية ضيقة لمخطط إعدادات وقت تشغيل الوكيل |
|
||||
| `plugin-sdk/boolean-param` | قارئ مرن لمعلمات boolean |
|
||||
| `plugin-sdk/dangerous-name-runtime` | مساعدات حل مطابقة الأسماء الخطرة |
|
||||
| `plugin-sdk/device-bootstrap` | مساعدات تهيئة الجهاز ورمز الاقتران |
|
||||
| `plugin-sdk/extension-shared` | أوليات مساعدة مشتركة للقناة السلبية، والحالة، والوكيل المحيطي |
|
||||
| `plugin-sdk/models-provider-runtime` | مساعدات الرد الخاصة بأمر `/models`/الموفّر |
|
||||
| `plugin-sdk/skill-commands-runtime` | مساعدات عرض أوامر Skills |
|
||||
| `plugin-sdk/native-command-registry` | مساعدات السجل/البناء/التسلسل للأوامر الأصلية |
|
||||
| `plugin-sdk/agent-harness` | سطح تجريبي موثوق لـ Plugin لأحزمة الوكيل منخفضة المستوى: أنواع الحزام، ومساعدات التوجيه/الإيقاف للتشغيل النشط، وجسر أدوات OpenClaw، وأدوات نتائج المحاولات |
|
||||
| `plugin-sdk/dangerous-name-runtime` | مساعدات حل مطابقة الأسماء الخطِرة |
|
||||
| `plugin-sdk/device-bootstrap` | مساعدات التمهيد للجهاز ورمز الاقتران |
|
||||
| `plugin-sdk/extension-shared` | عناصر أولية مشتركة لمساعدات القنوات السلبية والحالة والوكيل المحيط |
|
||||
| `plugin-sdk/models-provider-runtime` | مساعدات الرد الخاصة بالأمر `/models`/الموفّر |
|
||||
| `plugin-sdk/skill-commands-runtime` | مساعدات سرد أوامر Skills |
|
||||
| `plugin-sdk/native-command-registry` | مساعدات بناء/تسلسل/سجل الأوامر الأصلية |
|
||||
| `plugin-sdk/agent-harness` | سطح تجريبي لـ Plugin موثوق للحزم منخفضة المستوى الخاصة بالوكيل: أنواع الحزم، ومساعدات توجيه/إيقاف التشغيل النشط، ومساعدات جسر أدوات OpenClaw، وأدوات نتائج المحاولات |
|
||||
| `plugin-sdk/provider-zai-endpoint` | مساعدات اكتشاف نقاط نهاية Z.A.I |
|
||||
| `plugin-sdk/infra-runtime` | مساعدات أحداث النظام/Heartbeat |
|
||||
| `plugin-sdk/collection-runtime` | مساعدات صغيرة لذاكرة تخزين مؤقت محدودة |
|
||||
| `plugin-sdk/diagnostic-runtime` | مساعدات الأعلام والأحداث التشخيصية |
|
||||
| `plugin-sdk/error-runtime` | مساعدات رسم الأخطاء، والتنسيق، وتصنيف الأخطاء المشتركة، و`isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | مساعدات fetch المغلف، والوكيل، والبحث المثبّت |
|
||||
| `plugin-sdk/diagnostic-runtime` | مساعدات العلامات والأحداث التشخيصية |
|
||||
| `plugin-sdk/error-runtime` | مساعدات مخطط الأخطاء والتنسيق وتصنيف الأخطاء المشتركة، و `isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | مساعدات fetch الملتفة والوكيل والبحث المثبّت |
|
||||
| `plugin-sdk/runtime-fetch` | fetch خاص بوقت التشغيل ومدرك للـ dispatcher من دون استيرادات proxy/guarded-fetch |
|
||||
| `plugin-sdk/response-limit-runtime` | قارئ محدود لجسم الاستجابة من دون سطح وقت تشغيل الوسائط الأوسع |
|
||||
| `plugin-sdk/session-binding-runtime` | حالة ربط المحادثة الحالية من دون توجيه الربط المهيأ أو مخازن الاقتران |
|
||||
| `plugin-sdk/session-store-runtime` | مساعدات قراءة مخزن الجلسة من دون استيرادات واسعة لكتابة/صيانة الإعدادات |
|
||||
| `plugin-sdk/context-visibility-runtime` | حل رؤية السياق وتصفية السياق الإضافي من دون استيرادات إعدادات/أمان واسعة |
|
||||
| `plugin-sdk/string-coerce-runtime` | مساعدات ضيقة لإجبار/تطبيع السجلات البدائية والسلاسل من دون استيرادات Markdown/التسجيل |
|
||||
| `plugin-sdk/host-runtime` | مساعدات تطبيع اسم المضيف ومضيف SCP |
|
||||
| `plugin-sdk/retry-runtime` | مساعدات تهيئة إعادة المحاولة ومشغّل إعادة المحاولة |
|
||||
| `plugin-sdk/agent-runtime` | مساعدات دليل الوكيل/الهوية/مساحة العمل |
|
||||
| `plugin-sdk/directory-runtime` | الاستعلام عن الدليل المعتمد على التهيئة/إزالة التكرار |
|
||||
| `plugin-sdk/retry-runtime` | مساعدات إعدادات إعادة المحاولة ومشغّل إعادة المحاولة |
|
||||
| `plugin-sdk/agent-runtime` | مساعدات دليل/هوية/مساحة عمل الوكيل |
|
||||
| `plugin-sdk/directory-runtime` | استعلام/إزالة تكرار الأدلة المعتمد على الإعدادات |
|
||||
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="المسارات الفرعية للقدرات والاختبار">
|
||||
| المسار الفرعي | أهم التصديرات |
|
||||
| Subpath | Key exports |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/media-runtime` | مساعدات مشتركة لجلب/تحويل/تخزين الوسائط بالإضافة إلى بُناة حمولات الوسائط |
|
||||
| `plugin-sdk/media-generation-runtime` | مساعدات مشتركة للتجاوز عند الفشل في توليد الوسائط، واختيار المرشحين، ورسائل النماذج المفقودة |
|
||||
| `plugin-sdk/media-understanding` | أنواع موفّر فهم الوسائط بالإضافة إلى تصديرات المساعدات الخاصة بالصور/الصوت الموجّهة للموفّرين |
|
||||
| `plugin-sdk/text-runtime` | مساعدات مشتركة للنص/Markdown/التسجيل مثل إزالة النص المرئي للمساعد، ومساعدات العرض/التجزئة/الجداول في Markdown، ومساعدات التنقيح، ومساعدات وسم التوجيهات، وأدوات النص الآمن |
|
||||
| `plugin-sdk/text-chunking` | مساعد تجزئة النص الصادر |
|
||||
| `plugin-sdk/speech` | أنواع موفّر الكلام بالإضافة إلى التوجيهات، والسجل، ومساعدات التحقق الموجّهة للموفّرين |
|
||||
| `plugin-sdk/speech-core` | أنواع موفّر الكلام المشتركة، والسجل، والتوجيهات، ومساعدات التطبيع |
|
||||
| `plugin-sdk/realtime-transcription` | أنواع موفّر النسخ الفوري ومساعدات السجل |
|
||||
| `plugin-sdk/realtime-voice` | أنواع موفّر الصوت الفوري ومساعدات السجل |
|
||||
| `plugin-sdk/image-generation` | أنواع موفّر توليد الصور |
|
||||
| `plugin-sdk/image-generation-core` | الأنواع المشتركة لتوليد الصور، ومساعدات التجاوز عند الفشل، والمصادقة، والسجل |
|
||||
| `plugin-sdk/media-runtime` | مساعدات مشتركة لجلب/تحويل/تخزين الوسائط بالإضافة إلى منشئات حمولة الوسائط |
|
||||
| `plugin-sdk/media-generation-runtime` | مساعدات مشتركة للتعامل مع الإخفاق البديل في توليد الوسائط، واختيار المرشحين، ورسائل النماذج المفقودة |
|
||||
| `plugin-sdk/media-understanding` | أنواع موفّري فهم الوسائط بالإضافة إلى تصديرات المساعدات الخاصة بالصور/الصوت للموجّهة إلى الموفّرين |
|
||||
| `plugin-sdk/text-runtime` | مساعدات مشتركة للنص/Markdown/التسجيل مثل إزالة النص المرئي للمساعد، ومساعدات عرض/تقسيم/جداول Markdown، ومساعدات إخفاء البيانات الحساسة، ومساعدات وسوم التوجيه، وأدوات النص الآمن |
|
||||
| `plugin-sdk/text-chunking` | مساعد تقسيم النص الصادر |
|
||||
| `plugin-sdk/speech` | أنواع موفّري الكلام بالإضافة إلى المساعدات الخاصة بالموجّهة إلى الموفّرين للتوجيه والسجل والتحقق |
|
||||
| `plugin-sdk/speech-core` | مساعدات مشتركة لأنواع موفّري الكلام والسجل والتوجيه والتطبيع |
|
||||
| `plugin-sdk/realtime-transcription` | أنواع موفّري النسخ الفوري ومساعدات السجل |
|
||||
| `plugin-sdk/realtime-voice` | أنواع موفّري الصوت الفوري ومساعدات السجل |
|
||||
| `plugin-sdk/image-generation` | أنواع موفّري توليد الصور |
|
||||
| `plugin-sdk/image-generation-core` | مساعدات مشتركة لأنواع توليد الصور، والإخفاق البديل، والمصادقة، والسجل |
|
||||
| `plugin-sdk/music-generation` | أنواع موفّر/طلب/نتيجة توليد الموسيقى |
|
||||
| `plugin-sdk/music-generation-core` | الأنواع المشتركة لتوليد الموسيقى، ومساعدات التجاوز عند الفشل، والبحث عن الموفّر، وتحليل مرجع النموذج |
|
||||
| `plugin-sdk/music-generation-core` | مساعدات مشتركة لأنواع توليد الموسيقى، والإخفاق البديل، والبحث عن الموفّر، وتحليل مرجع النموذج |
|
||||
| `plugin-sdk/video-generation` | أنواع موفّر/طلب/نتيجة توليد الفيديو |
|
||||
| `plugin-sdk/video-generation-core` | الأنواع المشتركة لتوليد الفيديو، ومساعدات التجاوز عند الفشل، والبحث عن الموفّر، وتحليل مرجع النموذج |
|
||||
| `plugin-sdk/webhook-targets` | سجل أهداف Webhook ومساعدات تثبيت المسارات |
|
||||
| `plugin-sdk/video-generation-core` | مساعدات مشتركة لأنواع توليد الفيديو، والإخفاق البديل، والبحث عن الموفّر، وتحليل مرجع النموذج |
|
||||
| `plugin-sdk/webhook-targets` | مساعدات سجل أهداف Webhook وتثبيت المسارات |
|
||||
| `plugin-sdk/webhook-path` | مساعدات تطبيع مسار Webhook |
|
||||
| `plugin-sdk/web-media` | مساعدات مشتركة لتحميل الوسائط البعيدة/المحلية |
|
||||
| `plugin-sdk/zod` | إعادة تصدير `zod` لمستهلكي Plugin SDK |
|
||||
@ -266,102 +280,101 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="المسارات الفرعية للذاكرة">
|
||||
| المسار الفرعي | أهم التصديرات |
|
||||
| Subpath | Key exports |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/memory-core` | سطح مساعد memory-core المضمّن لمساعدات المدير/التهيئة/الملف/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | واجهة وقت تشغيل لفهرسة/بحث الذاكرة |
|
||||
| `plugin-sdk/memory-core` | سطح مساعد memory-core المجمّع لمساعدات المدير/الإعدادات/الملفات/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | واجهة وقت التشغيل لفهرسة/بحث الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | تصديرات محرك الأساس لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | عقود تضمينات مضيف الذاكرة، والوصول إلى السجل، والموفّر المحلي، ومساعدات الدفعات/المهام البعيدة العامة |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | عقود تضمين مضيف الذاكرة، والوصول إلى السجل، والموفّر المحلي، والمساعدات العامة للدُفعات/البعيد |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | تصديرات محرك QMD لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | تصديرات محرك التخزين لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | مساعدات متعددة الوسائط لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | مساعدات الوسائط المتعددة لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-query` | مساعدات الاستعلام لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-secret` | مساعدات الأسرار لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-events` | مساعدات دفتر يوميات الأحداث لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-events` | مساعدات سجل أحداث مضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-status` | مساعدات حالة مضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | مساعدات وقت تشغيل CLI لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | مساعدات وقت التشغيل الأساسية لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | مساعدات الملفات/وقت التشغيل لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-host-core` | اسم بديل محايد تجاه المورّد لمساعدات وقت التشغيل الأساسية لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-host-events` | اسم بديل محايد تجاه المورّد لمساعدات دفتر يوميات الأحداث لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-host-files` | اسم بديل محايد تجاه المورّد لمساعدات الملفات/وقت التشغيل لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-host-markdown` | مساعدات Markdown المُدار المشتركة للمكونات الإضافية المرتبطة بالذاكرة |
|
||||
| `plugin-sdk/memory-host-search` | واجهة Active Memory لوقت التشغيل للوصول إلى مدير البحث |
|
||||
| `plugin-sdk/memory-host-status` | اسم بديل محايد تجاه المورّد لمساعدات حالة مضيف الذاكرة |
|
||||
| `plugin-sdk/memory-lancedb` | سطح مساعد memory-lancedb المضمّن |
|
||||
| `plugin-sdk/memory-host-core` | اسم بديل مستقل عن المورّد لمساعدات وقت التشغيل الأساسية لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-host-events` | اسم بديل مستقل عن المورّد لمساعدات سجل أحداث مضيف الذاكرة |
|
||||
| `plugin-sdk/memory-host-files` | اسم بديل مستقل عن المورّد لمساعدات الملفات/وقت التشغيل لمضيف الذاكرة |
|
||||
| `plugin-sdk/memory-host-markdown` | مساعدات managed-markdown المشتركة للـ Plugins المجاورة للذاكرة |
|
||||
| `plugin-sdk/memory-host-search` | واجهة وقت تشغيل Active Memory للوصول إلى مدير البحث |
|
||||
| `plugin-sdk/memory-host-status` | اسم بديل مستقل عن المورّد لمساعدات حالة مضيف الذاكرة |
|
||||
| `plugin-sdk/memory-lancedb` | سطح مساعد memory-lancedb المجمّع |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="المسارات الفرعية المحجوزة للمساعدات المضمّنة">
|
||||
| العائلة | المسارات الفرعية الحالية | الاستخدام المقصود |
|
||||
<Accordion title="المسارات الفرعية المحجوزة للمساعدات المجمّعة">
|
||||
| Family | Current subpaths | Intended use |
|
||||
| --- | --- | --- |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | مساعدات دعم Plugin المضمّن للمتصفح (`browser-support` يبقى حزمة التوافق) |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | سطح المساعدة/وقت التشغيل المضمّن لـ Matrix |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | سطح المساعدة/وقت التشغيل المضمّن لـ LINE |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | سطح المساعدة المضمّن لـ IRC |
|
||||
| مساعدات خاصة بالقنوات | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | مسارات توافق/مساعدة مضمّنة للقنوات |
|
||||
| مساعدات خاصة بالمصادقة/Plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | مسارات مساعدة مضمّنة للميزات/Plugin؛ يصدّر `plugin-sdk/github-copilot-token` حاليًا `DEFAULT_COPILOT_API_BASE_URL` و`deriveCopilotApiBaseUrlFromToken` و`resolveCopilotApiToken` |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | مساعدات دعم Plugin Browser المجمّع (`browser-support` تبقى حاوية التوافق) |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | سطح المساعد/وقت التشغيل المجمّع لـ Matrix |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | سطح المساعد/وقت التشغيل المجمّع لـ LINE |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | سطح المساعد المجمّع لـ IRC |
|
||||
| مساعدات خاصة بالقنوات | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | طبقات توافق/مساعدة القنوات المجمّعة |
|
||||
| مساعدات خاصة بالمصادقة/Plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | طبقات مساعدات الميزات/Plugins المجمّعة؛ يصدّر `plugin-sdk/github-copilot-token` حاليًا `DEFAULT_COPILOT_API_BASE_URL` و `deriveCopilotApiBaseUrlFromToken` و `resolveCopilotApiToken` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## API التسجيل
|
||||
## واجهة برمجة تطبيقات التسجيل
|
||||
|
||||
يتلقى رد النداء `register(api)` كائن `OpenClawPluginApi` بهذه
|
||||
الأساليب:
|
||||
|
||||
### تسجيل القدرات
|
||||
|
||||
| الأسلوب | ما الذي يسجله |
|
||||
| ------------------------------------------------ | -------------------------------- |
|
||||
| `api.registerProvider(...)` | استدلال النص (LLM) |
|
||||
| `api.registerAgentHarness(...)` | منفّذ وكيل منخفض المستوى تجريبي |
|
||||
| `api.registerCliBackend(...)` | واجهة CLI خلفية محلية للاستدلال |
|
||||
| `api.registerChannel(...)` | قناة مراسلة |
|
||||
| `api.registerSpeechProvider(...)` | تحويل النص إلى كلام / توليف STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | نسخ فوري متدفق |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | جلسات صوت فوري ثنائية الاتجاه |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | تحليل الصور/الصوت/الفيديو |
|
||||
| Method | What it registers |
|
||||
| ------------------------------------------------ | ------------------------------------- |
|
||||
| `api.registerProvider(...)` | الاستدلال النصي (LLM) |
|
||||
| `api.registerAgentHarness(...)` | مُنفّذ وكيل منخفض المستوى تجريبي |
|
||||
| `api.registerCliBackend(...)` | CLI backend محلي للاستدلال |
|
||||
| `api.registerChannel(...)` | قناة مراسلة |
|
||||
| `api.registerSpeechProvider(...)` | تحويل النص إلى كلام / تركيب STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | النسخ الفوري المتدفق |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | جلسات الصوت الفوري ثنائية الاتجاه |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | تحليل الصور/الصوت/الفيديو |
|
||||
| `api.registerImageGenerationProvider(...)` | توليد الصور |
|
||||
| `api.registerMusicGenerationProvider(...)` | توليد الموسيقى |
|
||||
| `api.registerVideoGenerationProvider(...)` | توليد الفيديو |
|
||||
| `api.registerWebFetchProvider(...)` | موفّر جلب / كشط الويب |
|
||||
| `api.registerWebSearchProvider(...)` | البحث على الويب |
|
||||
| `api.registerMusicGenerationProvider(...)` | توليد الموسيقى |
|
||||
| `api.registerVideoGenerationProvider(...)` | توليد الفيديو |
|
||||
| `api.registerWebFetchProvider(...)` | موفّر جلب / كشط الويب |
|
||||
| `api.registerWebSearchProvider(...)` | بحث الويب |
|
||||
|
||||
### الأدوات والأوامر
|
||||
|
||||
| الأسلوب | ما الذي يسجله |
|
||||
| Method | What it registers |
|
||||
| ------------------------------- | --------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | أداة وكيل (مطلوبة أو `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | أمر مخصص (يتجاوز LLM) |
|
||||
| `api.registerTool(tool, opts?)` | أداة وكيل (مطلوبة أو `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | أمر مخصص (يتجاوز LLM) |
|
||||
|
||||
### البنية التحتية
|
||||
|
||||
| الأسلوب | ما الذي يسجله |
|
||||
| ---------------------------------------------- | ----------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | خطاف أحداث |
|
||||
| `api.registerHttpRoute(params)` | نقطة نهاية HTTP لـ Gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | أسلوب RPC لـ Gateway |
|
||||
| `api.registerCli(registrar, opts?)` | أمر فرعي في CLI |
|
||||
| `api.registerService(service)` | خدمة في الخلفية |
|
||||
| `api.registerInteractiveHandler(registration)` | معالج تفاعلي |
|
||||
| Method | What it registers |
|
||||
| ---------------------------------------------- | --------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | خطاف أحداث |
|
||||
| `api.registerHttpRoute(params)` | نقطة نهاية HTTP لـ Gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | أسلوب Gateway RPC |
|
||||
| `api.registerCli(registrar, opts?)` | أمر فرعي في CLI |
|
||||
| `api.registerService(service)` | خدمة في الخلفية |
|
||||
| `api.registerInteractiveHandler(registration)` | معالج تفاعلي |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | قسم إضافي في المطالبة مجاور للذاكرة |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | متن إضافي للبحث/القراءة في الذاكرة |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Corpus إضافي لبحث/قراءة الذاكرة |
|
||||
|
||||
تظل مساحات أسماء الإدارة الأساسية المحجوزة (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) دائمًا `operator.admin` حتى إذا حاول Plugin تعيين نطاق أضيق
|
||||
لأسلوب Gateway. استخدم بادئات خاصة بـ Plugin
|
||||
للأساليب التي يملكها Plugin.
|
||||
`update.*`) دائمًا `operator.admin`، حتى إذا حاول Plugin تعيين
|
||||
نطاق أضيق لأسلوب Gateway. ويفضَّل استخدام بادئات خاصة بالـ Plugin من أجل
|
||||
الأساليب المملوكة للـ Plugin.
|
||||
|
||||
### بيانات تعريف تسجيل CLI
|
||||
|
||||
يقبل `api.registerCli(registrar, opts?)` نوعين من بيانات التعريف عالية المستوى:
|
||||
يقبل `api.registerCli(registrar, opts?)` نوعين من بيانات التعريف العليا:
|
||||
|
||||
- `commands`: جذور أوامر صريحة يملكها المسجِّل
|
||||
- `descriptors`: واصفات أوامر وقت التحليل المستخدمة لمساعدة CLI الجذرية،
|
||||
والتوجيه، وتسجيل CLI الكسول للمكوّنات الإضافية
|
||||
- `commands`: جذور أوامر صريحة يملكها المسجل
|
||||
- `descriptors`: واصفات أوامر وقت التحليل المستخدمة في مساعدة CLI الجذرية،
|
||||
والتوجيه، وتسجيل CLI الكسول للـ Plugin
|
||||
|
||||
إذا كنت تريد أن يبقى أمر Plugin محمّلًا بكسل في مسار CLI الجذري العادي،
|
||||
فقدّم `descriptors` تغطي كل جذر أمر عالي المستوى يكشفه
|
||||
ذلك المسجِّل.
|
||||
إذا كنت تريد أن يظل أمر Plugin محمّلًا بشكل كسول في مسار CLI الجذري العادي،
|
||||
فقدّم `descriptors` تغطي كل جذر أمر علوي يعرّضه ذلك المسجل.
|
||||
|
||||
```typescript
|
||||
api.registerCli(
|
||||
@ -373,7 +386,7 @@ api.registerCli(
|
||||
descriptors: [
|
||||
{
|
||||
name: "matrix",
|
||||
description: "إدارة حسابات Matrix، والتحقق، والأجهزة، وحالة الملف الشخصي",
|
||||
description: "إدارة حسابات Matrix والتحقق والأجهزة وحالة الملف التعريفي",
|
||||
hasSubcommands: true,
|
||||
},
|
||||
],
|
||||
@ -382,136 +395,133 @@ api.registerCli(
|
||||
```
|
||||
|
||||
استخدم `commands` بمفرده فقط عندما لا تحتاج إلى تسجيل CLI جذري كسول.
|
||||
لا يزال مسار التوافق المتعجل هذا مدعومًا، لكنه لا يثبت
|
||||
عناصر نائبة مدعومة بواصفات للتحميل الكسول في وقت التحليل.
|
||||
لا يزال مسار التوافق eager هذا مدعومًا، لكنه لا يثبت
|
||||
عناصر نائبة مدعومة بالواصفات للتحميل الكسول في وقت التحليل.
|
||||
|
||||
### تسجيل الواجهة الخلفية لـ CLI
|
||||
### تسجيل CLI backend
|
||||
|
||||
يتيح `api.registerCliBackend(...)` لـ Plugin امتلاك التهيئة الافتراضية
|
||||
لواجهة CLI خلفية محلية للذكاء الاصطناعي مثل `codex-cli`.
|
||||
يتيح `api.registerCliBackend(...)` لـ Plugin امتلاك الإعداد الافتراضي
|
||||
لـ CLI backend محلي للذكاء الاصطناعي مثل `codex-cli`.
|
||||
|
||||
- يصبح `id` الخاص بالواجهة الخلفية بادئة الموفّر في مراجع النماذج مثل `codex-cli/gpt-5`.
|
||||
- تستخدم `config` الخاصة بالواجهة الخلفية البنية نفسها مثل `agents.defaults.cliBackends.<id>`.
|
||||
- تظل تهيئة المستخدم لها الأولوية. يدمج OpenClaw `agents.defaults.cliBackends.<id>` فوق
|
||||
القيمة الافتراضية الخاصة بـ Plugin قبل تشغيل CLI.
|
||||
- استخدم `normalizeConfig` عندما تحتاج واجهة خلفية إلى إعادة كتابة توافقية بعد الدمج
|
||||
(على سبيل المثال تطبيع الأشكال القديمة للأعلام).
|
||||
- يصبح `id` الخاص بالـ backend هو بادئة الموفّر في مراجع النماذج مثل `codex-cli/gpt-5`.
|
||||
- يستخدم `config` الخاص بالـ backend البنية نفسها الموجودة في `agents.defaults.cliBackends.<id>`.
|
||||
- يظل إعداد المستخدم هو الغالب. يدمج OpenClaw القيمة `agents.defaults.cliBackends.<id>` فوق
|
||||
الإعداد الافتراضي للـ Plugin قبل تشغيل CLI.
|
||||
- استخدم `normalizeConfig` عندما يحتاج backend إلى إعادة كتابة للتوافق بعد الدمج
|
||||
(على سبيل المثال تطبيع أشكال العلامات القديمة).
|
||||
|
||||
### الخانات الحصرية
|
||||
### الفتحات الحصرية
|
||||
|
||||
| الأسلوب | ما الذي يسجله |
|
||||
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | محرك السياق (واحد فقط نشط في كل مرة). يتلقى رد النداء `assemble()` القيمتين `availableTools` و`citationsMode` حتى يتمكن المحرك من تكييف إضافات المطالبة. |
|
||||
| `api.registerMemoryCapability(capability)` | قدرة ذاكرة موحّدة |
|
||||
| `api.registerMemoryPromptSection(builder)` | بانٍ لقسم مطالبة الذاكرة |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | محلّل خطة تفريغ الذاكرة |
|
||||
| `api.registerMemoryRuntime(runtime)` | مهايئ وقت تشغيل الذاكرة |
|
||||
| Method | What it registers |
|
||||
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | محرك السياق (واحد فقط يكون نشطًا في كل مرة). تتلقى دالة `assemble()` الراجعة `availableTools` و `citationsMode` حتى يتمكن المحرك من تفصيل الإضافات إلى المطالبة. |
|
||||
| `api.registerMemoryCapability(capability)` | قدرة الذاكرة الموحدة |
|
||||
| `api.registerMemoryPromptSection(builder)` | منشئ قسم مطالبة الذاكرة |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | محلّل خطة تفريغ الذاكرة |
|
||||
| `api.registerMemoryRuntime(runtime)` | مهايئ وقت تشغيل الذاكرة |
|
||||
|
||||
### مهايئات تضمين الذاكرة
|
||||
|
||||
| الأسلوب | ما الذي يسجله |
|
||||
| ---------------------------------------------- | --------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | مهايئ تضمين الذاكرة الخاص بـ Plugin النشط |
|
||||
| Method | What it registers |
|
||||
| ---------------------------------------------- | ---------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | مهايئ تضمين الذاكرة للـ Plugin النشط |
|
||||
|
||||
- `registerMemoryCapability` هو API الذاكرة الحصري المفضّل لـ Plugin.
|
||||
- قد يكشف `registerMemoryCapability` أيضًا `publicArtifacts.listArtifacts(...)`
|
||||
بحيث يمكن للمكونات الإضافية المصاحبة استهلاك عناصر الذاكرة المُصدّرة عبر
|
||||
`openclaw/plugin-sdk/memory-host-core` بدلًا من الوصول إلى التخطيط الخاص
|
||||
الداخلي لمكوّن ذاكرة إضافي محدد.
|
||||
- إن `registerMemoryPromptSection` و`registerMemoryFlushPlan` و
|
||||
`registerMemoryRuntime` هي واجهات API حصرية للمكوّنات الإضافية الخاصة بالذاكرة
|
||||
ومتوافقة مع الأنظمة القديمة.
|
||||
- يتيح `registerMemoryEmbeddingProvider` لمكوّن الذاكرة الإضافي النشط تسجيل
|
||||
معرّف مهايئ تضمين واحد أو أكثر (مثل `openai` أو `gemini` أو معرّف
|
||||
مخصص يعرّفه Plugin).
|
||||
- تُعد `registerMemoryCapability` واجهة Plugin الذاكرة الحصرية المفضلة.
|
||||
- يمكن أيضًا لـ `registerMemoryCapability` كشف `publicArtifacts.listArtifacts(...)`
|
||||
حتى تتمكن Plugins المصاحبة من استهلاك عناصر الذاكرة المصدّرة عبر
|
||||
`openclaw/plugin-sdk/memory-host-core` بدلًا من الوصول إلى تخطيط خاص
|
||||
لـ Plugin ذاكرة محدد.
|
||||
- تُعد `registerMemoryPromptSection` و `registerMemoryFlushPlan` و
|
||||
`registerMemoryRuntime` واجهات Plugin ذاكرة حصرية متوافقة مع الإصدارات القديمة.
|
||||
- تتيح `registerMemoryEmbeddingProvider` للـ Plugin النشط للذاكرة تسجيل
|
||||
معرّف مهايئ تضمين واحد أو أكثر (مثل `openai` أو `gemini` أو معرّف مخصص
|
||||
يعرّفه Plugin).
|
||||
- تُحل إعدادات المستخدم مثل `agents.defaults.memorySearch.provider` و
|
||||
`agents.defaults.memorySearch.fallback` في مقابل معرّفات المهايئات
|
||||
المسجّلة تلك.
|
||||
`agents.defaults.memorySearch.fallback` وفقًا لمعرّفات المهايئات المسجلة هذه.
|
||||
|
||||
### الأحداث ودورة الحياة
|
||||
|
||||
| الأسلوب | ما الذي يفعله |
|
||||
| -------------------------------------------- | ------------------------ |
|
||||
| `api.on(hookName, handler, opts?)` | خطاف دورة حياة مضبوط الأنواع |
|
||||
| `api.onConversationBindingResolved(handler)` | رد نداء ربط المحادثة |
|
||||
| Method | What it does |
|
||||
| -------------------------------------------- | ----------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | خطاف دورة حياة مطبوع |
|
||||
| `api.onConversationBindingResolved(handler)` | رد نداء ربط المحادثة |
|
||||
|
||||
### دلالات قرار الخطاف
|
||||
|
||||
- `before_tool_call`: إن إرجاع `{ block: true }` نهائي. بمجرد أن يضبط أي معالج هذه القيمة، يتم تخطي المعالجات ذات الأولوية الأقل.
|
||||
- `before_tool_call`: إن إرجاع `{ block: false }` يُعامل على أنه بلا قرار (مثل حذف `block`)، وليس كتجاوز.
|
||||
- `before_install`: إن إرجاع `{ block: true }` نهائي. بمجرد أن يضبط أي معالج هذه القيمة، يتم تخطي المعالجات ذات الأولوية الأقل.
|
||||
- `before_install`: إن إرجاع `{ block: false }` يُعامل على أنه بلا قرار (مثل حذف `block`)، وليس كتجاوز.
|
||||
- `reply_dispatch`: إن إرجاع `{ handled: true, ... }` نهائي. بمجرد أن يعلن أي معالج أنه تولى الإرسال، يتم تخطي المعالجات ذات الأولوية الأقل ومسار إرسال النموذج الافتراضي.
|
||||
- `message_sending`: إن إرجاع `{ cancel: true }` نهائي. بمجرد أن يضبط أي معالج هذه القيمة، يتم تخطي المعالجات ذات الأولوية الأقل.
|
||||
- `message_sending`: إن إرجاع `{ cancel: false }` يُعامل على أنه بلا قرار (مثل حذف `cancel`)، وليس كتجاوز.
|
||||
- `before_tool_call`: تؤدي إعادة `{ block: true }` إلى إنهاء المعالجة. وبمجرد أن يضبط أي معالج هذه القيمة، يتم تخطي المعالجات ذات الأولوية الأدنى.
|
||||
- `before_tool_call`: تُعامل إعادة `{ block: false }` على أنها عدم اتخاذ قرار (مثل حذف `block`)، وليس كتجاوز.
|
||||
- `before_install`: تؤدي إعادة `{ block: true }` إلى إنهاء المعالجة. وبمجرد أن يضبط أي معالج هذه القيمة، يتم تخطي المعالجات ذات الأولوية الأدنى.
|
||||
- `before_install`: تُعامل إعادة `{ block: false }` على أنها عدم اتخاذ قرار (مثل حذف `block`)، وليس كتجاوز.
|
||||
- `reply_dispatch`: تؤدي إعادة `{ handled: true, ... }` إلى إنهاء المعالجة. وبمجرد أن يطالب أي معالج بعملية الإرسال، يتم تخطي المعالجات ذات الأولوية الأدنى ومسار إرسال النموذج الافتراضي.
|
||||
- `message_sending`: تؤدي إعادة `{ cancel: true }` إلى إنهاء المعالجة. وبمجرد أن يضبط أي معالج هذه القيمة، يتم تخطي المعالجات ذات الأولوية الأدنى.
|
||||
- `message_sending`: تُعامل إعادة `{ cancel: false }` على أنها عدم اتخاذ قرار (مثل حذف `cancel`)، وليس كتجاوز.
|
||||
|
||||
### حقول كائن API
|
||||
|
||||
| الحقل | النوع | الوصف |
|
||||
| ------------------------ | ------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | معرّف Plugin |
|
||||
| `api.name` | `string` | اسم العرض |
|
||||
| `api.version` | `string?` | إصدار Plugin (اختياري) |
|
||||
| `api.description` | `string?` | وصف Plugin (اختياري) |
|
||||
| Field | Type | Description |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | معرّف Plugin |
|
||||
| `api.name` | `string` | اسم العرض |
|
||||
| `api.version` | `string?` | إصدار Plugin (اختياري) |
|
||||
| `api.description` | `string?` | وصف Plugin (اختياري) |
|
||||
| `api.source` | `string` | مسار مصدر Plugin |
|
||||
| `api.rootDir` | `string?` | الدليل الجذري لـ Plugin (اختياري) |
|
||||
| `api.config` | `OpenClawConfig` | لقطة التهيئة الحالية (لقطة وقت التشغيل النشطة داخل الذاكرة عند توفرها) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | تهيئة خاصة بـ Plugin من `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [مساعدات وقت التشغيل](/ar/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | مسجل ضمن النطاق (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | وضع التحميل الحالي؛ تشير `"setup-runtime"` إلى نافذة البدء/الإعداد الخفيفة قبل الإدخال الكامل |
|
||||
| `api.resolvePath(input)` | `(string) => string` | حل المسار بالنسبة إلى جذر Plugin |
|
||||
| `api.rootDir` | `string?` | الدليل الجذري للـ Plugin (اختياري) |
|
||||
| `api.config` | `OpenClawConfig` | لقطة الإعدادات الحالية (لقطة وقت التشغيل النشطة داخل الذاكرة عند توفرها) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | إعدادات خاصة بالـ Plugin من `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [مساعدات وقت التشغيل](/ar/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | مسجل ذو نطاق محدد (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | وضع التحميل الحالي؛ `"setup-runtime"` هي نافذة البدء/الإعداد الخفيفة قبل الإدخال الكامل |
|
||||
| `api.resolvePath(input)` | `(string) => string` | حل المسار نسبةً إلى جذر Plugin |
|
||||
|
||||
## اصطلاح الوحدات الداخلية
|
||||
## اصطلاح الوحدة الداخلية
|
||||
|
||||
داخل Plugin الخاص بك، استخدم ملفات barrel محلية للاستيراد الداخلي:
|
||||
داخل Plugin الخاص بك، استخدم ملفات barrel محلية للاستيرادات الداخلية:
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
api.ts # تصديرات عامة للمستهلكين الخارجيين
|
||||
api.ts # التصديرات العامة للمستهلكين الخارجيين
|
||||
runtime-api.ts # تصديرات داخلية فقط لوقت التشغيل
|
||||
index.ts # نقطة إدخال Plugin
|
||||
setup-entry.ts # إدخال خفيف للإعداد فقط (اختياري)
|
||||
```
|
||||
|
||||
<Warning>
|
||||
لا تستورد Plugin الخاص بك أبدًا عبر `openclaw/plugin-sdk/<your-plugin>`
|
||||
لا تستورد Plugin الخاص بك عبر `openclaw/plugin-sdk/<your-plugin>`
|
||||
من كود الإنتاج. وجّه الاستيرادات الداخلية عبر `./api.ts` أو
|
||||
`./runtime-api.ts`. مسار SDK هو العقد الخارجي فقط.
|
||||
</Warning>
|
||||
|
||||
تفضّل الآن الأسطح العامة للمكونات الإضافية المضمّنة المحمّلة عبر الواجهة (`api.ts` و`runtime-api.ts`
|
||||
و`index.ts` و`setup-entry.ts` وملفات الإدخال العامة المشابهة)
|
||||
لقطة تهيئة وقت التشغيل النشطة عندما يكون OpenClaw قيد التشغيل بالفعل. وإذا لم تكن
|
||||
لقطة وقت التشغيل موجودة بعد، فإنها ترجع إلى ملف التهيئة المحلول على القرص.
|
||||
تفضّل الآن الأسطح العامة لPlugin المجمّع المحمّلة عبر Facade (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts`، وملفات الإدخال العامة المماثلة)
|
||||
لقطة إعدادات وقت التشغيل النشطة عندما يكون OpenClaw قيد التشغيل بالفعل. وإذا لم تكن هناك
|
||||
لقطة وقت تشغيل بعد، فإنها تعود إلى ملف الإعدادات المحلول على القرص.
|
||||
|
||||
يمكن لمكونات الموفّر الإضافية أيضًا كشف حزمة عقد محلية ضيقة خاصة بـ Plugin عندما
|
||||
يكون أحد المساعدات خاصًا بالموفّر عمدًا ولا ينتمي بعد إلى مسار فرعي عام في SDK.
|
||||
المثال المضمّن الحالي: يحتفظ موفّر Anthropic بمساعدات تدفق Claude
|
||||
في مساره العام الخاص `api.ts` / `contract-api.ts` بدلًا من
|
||||
ترقية منطق رأس Anthropic التجريبي و`service_tier` إلى عقد عام
|
||||
يمكن Plugins الموفّرين أيضًا كشف ملف contract barrel محلي ضيق خاص بالـ Plugin عندما تكون
|
||||
إحدى المساعدات خاصة بالموفّر عمدًا ولا تنتمي بعد إلى مسار فرعي عام
|
||||
في SDK. المثال المجمّع الحالي: يحتفظ موفّر Anthropic بمساعدات تدفق Claude
|
||||
داخل الطبقة العامة الخاصة به `api.ts` / `contract-api.ts` بدلًا من
|
||||
ترقية منطق ترويسة Anthropic التجريبية و`service_tier` إلى عقد عام
|
||||
`plugin-sdk/*`.
|
||||
|
||||
أمثلة مضمّنة حالية أخرى:
|
||||
أمثلة مجمّعة حالية أخرى:
|
||||
|
||||
- `@openclaw/openai-provider`: يصدّر `api.ts` بُناة الموفّر،
|
||||
ومساعدات النموذج الافتراضي، وبُناة الموفّر الفوري
|
||||
- `@openclaw/openrouter-provider`: يصدّر `api.ts` باني الموفّر بالإضافة إلى
|
||||
مساعدات الإعداد الأولي/التهيئة
|
||||
- `@openclaw/openai-provider`: يصدّر `api.ts` أدوات بناء الموفّر،
|
||||
ومساعدات النموذج الافتراضي، وأدوات بناء الموفّر الفوري
|
||||
- `@openclaw/openrouter-provider`: يصدّر `api.ts` أداة بناء الموفّر بالإضافة إلى
|
||||
مساعدات الإعداد الأولي/الإعدادات
|
||||
|
||||
<Warning>
|
||||
يجب على كود الإنتاج الخاص بالامتدادات أيضًا تجنّب استيرادات
|
||||
`openclaw/plugin-sdk/<other-plugin>`.
|
||||
إذا كان أحد المساعدات مشتركًا فعلًا، فارفعه إلى مسار فرعي محايد في SDK
|
||||
مثل `openclaw/plugin-sdk/speech` أو `.../provider-model-shared` أو سطح آخر
|
||||
موجّه حسب القدرة بدلًا من ربط مكوّنين إضافيين معًا.
|
||||
يجب أن يتجنب كود الإنتاج الخاص بالامتداد أيضًا استيراد `openclaw/plugin-sdk/<other-plugin>`.
|
||||
إذا كانت إحدى المساعدات مشتركة فعلًا، فقم بترقيتها إلى مسار فرعي محايد في SDK
|
||||
مثل `openclaw/plugin-sdk/speech` أو `.../provider-model-shared` أو أي سطح آخر
|
||||
موجّه إلى القدرات بدلًا من ربط Pluginين معًا.
|
||||
</Warning>
|
||||
|
||||
## ذو صلة
|
||||
|
||||
- [نقاط الإدخال](/ar/plugins/sdk-entrypoints) — خيارات `definePluginEntry` و`defineChannelPluginEntry`
|
||||
- [نقاط الإدخال](/ar/plugins/sdk-entrypoints) — خيارات `definePluginEntry` و `defineChannelPluginEntry`
|
||||
- [مساعدات وقت التشغيل](/ar/plugins/sdk-runtime) — المرجع الكامل لمساحة الأسماء `api.runtime`
|
||||
- [الإعداد والتهيئة](/ar/plugins/sdk-setup) — التغليف، والبيانات الوصفية، ومخططات التهيئة
|
||||
- [الإعداد والإعدادات](/ar/plugins/sdk-setup) — التحزيم، وmanifestات، ومخططات الإعدادات
|
||||
- [الاختبار](/ar/plugins/sdk-testing) — أدوات الاختبار وقواعد lint
|
||||
- [ترحيل SDK](/ar/plugins/sdk-migration) — الترحيل من الأسطح المهجورة
|
||||
- [الخصائص الداخلية لـ Plugin](/ar/plugins/architecture) — البنية العميقة ونموذج القدرات
|
||||
- [البنية الداخلية للـ Plugin](/ar/plugins/architecture) — البنية العميقة ونموذج القدرات
|
||||
|
||||
@ -1,168 +1,168 @@
|
||||
---
|
||||
x-i18n:
|
||||
generated_at: "2026-04-08T06:02:17Z"
|
||||
generated_at: "2026-04-18T07:15:28Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 4a9066b2a939c5a9ba69141d75405f0e8097997b523164340e2f0e9a0d5060dd
|
||||
source_hash: dbb2c70c82da7f6f12d90e25666635ff4147c52e8a94135e902d1de4f5cbccca
|
||||
source_path: refactor/qa.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# إعادة هيكلة QA
|
||||
|
||||
الحالة: تم إرساء الترحيل التأسيسي.
|
||||
الحالة: تم إنجاز الترحيل التأسيسي.
|
||||
|
||||
## الهدف
|
||||
|
||||
نقل QA في OpenClaw من نموذج تعريف منقسم إلى مصدر حقيقة واحد:
|
||||
نقل QA في OpenClaw من نموذج تعريف منقسم إلى مصدر وحيد للحقيقة:
|
||||
|
||||
- بيانات تعريف السيناريو
|
||||
- بيانات وصفية للسيناريو
|
||||
- المطالبات المرسلة إلى النموذج
|
||||
- الإعداد والتنظيف
|
||||
- منطق الـ harness
|
||||
- الإعداد والإنهاء
|
||||
- منطق الحزام
|
||||
- التأكيدات ومعايير النجاح
|
||||
- العناصر الناتجة وتلميحات التقرير
|
||||
- الآثار وتلميحات التقرير
|
||||
|
||||
الحالة النهائية المطلوبة هي harness عام لـ QA يحمّل ملفات تعريف سيناريوهات قوية بدلًا من ترميز معظم السلوك بشكل ثابت في TypeScript.
|
||||
الحالة النهائية المطلوبة هي حزام QA عام يحمّل ملفات تعريف سيناريوهات قوية بدلًا من ترميز معظم السلوك بشكل ثابت في TypeScript.
|
||||
|
||||
## الحالة الحالية
|
||||
|
||||
يوجد مصدر الحقيقة الأساسي الآن في `qa/scenarios/index.md` بالإضافة إلى ملف واحد لكل
|
||||
سيناريو ضمن `qa/scenarios/*.md`.
|
||||
المصدر الأساسي للحقيقة موجود الآن في `qa/scenarios/index.md` بالإضافة إلى ملف واحد لكل
|
||||
سيناريو ضمن `qa/scenarios/<theme>/*.md`.
|
||||
|
||||
ما تم تنفيذه:
|
||||
تم تنفيذ ما يلي:
|
||||
|
||||
- `qa/scenarios/index.md`
|
||||
- بيانات تعريف حزمة QA القياسية
|
||||
- بيانات وصفية قانونية لحزمة QA
|
||||
- هوية المشغّل
|
||||
- مهمة الانطلاق
|
||||
- `qa/scenarios/*.md`
|
||||
- `qa/scenarios/<theme>/*.md`
|
||||
- ملف Markdown واحد لكل سيناريو
|
||||
- بيانات تعريف السيناريو
|
||||
- ربط المعالجات
|
||||
- إعدادات التنفيذ الخاصة بالسيناريو
|
||||
- بيانات وصفية للسيناريو
|
||||
- ارتباطات المعالِجات
|
||||
- ضبط تنفيذ خاص بالسيناريو
|
||||
- `extensions/qa-lab/src/scenario-catalog.ts`
|
||||
- محلل حزمة Markdown + تحقق `zod`
|
||||
- `extensions/qa-lab/src/qa-agent-bootstrap.ts`
|
||||
- تصيير الخطة من حزمة Markdown
|
||||
- `extensions/qa-lab/src/qa-agent-workspace.ts`
|
||||
- يهيئ ملفات توافق مولدة بالإضافة إلى `QA_SCENARIOS.md`
|
||||
- يزرع ملفات توافق مولدة بالإضافة إلى `QA_SCENARIOS.md`
|
||||
- `extensions/qa-lab/src/suite.ts`
|
||||
- يحدد السيناريوهات القابلة للتنفيذ عبر روابط معالجات معرّفة في Markdown
|
||||
- بروتوكول حافلة QA + واجهة المستخدم
|
||||
- يختار السيناريوهات القابلة للتنفيذ عبر ارتباطات معالِجات معرّفة في Markdown
|
||||
- بروتوكول ناقل QA + واجهة المستخدم
|
||||
- مرفقات مضمنة عامة لعرض الصور/الفيديو/الصوت/الملفات
|
||||
|
||||
الأسطح المنقسمة المتبقية:
|
||||
|
||||
- `extensions/qa-lab/src/suite.ts`
|
||||
- لا يزال يملك معظم منطق المعالجات المخصصة القابلة للتنفيذ
|
||||
- لا يزال يملك معظم منطق المعالِجات المخصصة القابلة للتنفيذ
|
||||
- `extensions/qa-lab/src/report.ts`
|
||||
- لا يزال يستمد بنية التقرير من مخرجات وقت التشغيل
|
||||
- لا يزال يشتق بنية التقرير من مخرجات وقت التشغيل
|
||||
|
||||
لذا تم إصلاح انقسام مصدر الحقيقة، لكن التنفيذ لا يزال في الغالب معتمدًا على المعالجات بدلًا من أن يكون تصريحيًا بالكامل.
|
||||
لذا فقد تم إصلاح انقسام مصدر الحقيقة، لكن التنفيذ لا يزال في معظمه مدعومًا بالمعالِجات بدلًا من أن يكون تصريحيًا بالكامل.
|
||||
|
||||
## كيف يبدو سطح السيناريو الحقيقي
|
||||
|
||||
تُظهر قراءة الحزمة الحالية عدة فئات مميزة من السيناريوهات.
|
||||
تُظهر قراءة المجموعة الحالية عدة فئات مميزة من السيناريوهات.
|
||||
|
||||
### تفاعل بسيط
|
||||
|
||||
- خط أساس القناة
|
||||
- خط أساس الرسائل الخاصة
|
||||
- متابعة ضمن خيط
|
||||
- خط أساس DM
|
||||
- متابعة ضمن سلسلة
|
||||
- تبديل النموذج
|
||||
- استكمال الموافقة
|
||||
- التفاعل/التعديل/الحذف
|
||||
- متابعة الموافقة
|
||||
- التفاعل/التحرير/الحذف
|
||||
|
||||
### تعديل الإعدادات ووقت التشغيل
|
||||
### تعديل الإعداد ووقت التشغيل
|
||||
|
||||
- تعطيل skill عبر ترقيع الإعدادات
|
||||
- إيقاظ إعادة تشغيل تطبيق الإعدادات
|
||||
- قلب قدرة إعادة تشغيل الإعدادات
|
||||
- تعطيل مهارة تصحيح الإعداد
|
||||
- تطبيق الإعداد وإعادة التشغيل والاستيقاظ
|
||||
- قلب قدرة إعادة تشغيل الإعداد
|
||||
- فحص انجراف مخزون وقت التشغيل
|
||||
|
||||
### تأكيدات نظام الملفات والمستودع
|
||||
|
||||
- تقرير اكتشاف المصدر/الوثائق
|
||||
- بناء Lobster Invaders
|
||||
- البحث عن عنصر صورة مولد
|
||||
- البحث عن أثر صورة مولدة
|
||||
|
||||
### تنسيق الذاكرة
|
||||
|
||||
- استدعاء الذاكرة
|
||||
- أدوات الذاكرة في سياق القناة
|
||||
- احتياط فشل الذاكرة
|
||||
- الرجوع الاحتياطي عند فشل الذاكرة
|
||||
- ترتيب ذاكرة الجلسة
|
||||
- عزل ذاكرة الخيط
|
||||
- اجتياح حلم الذاكرة
|
||||
- عزل ذاكرة السلسلة
|
||||
- مسح Dreaming للذاكرة
|
||||
|
||||
### تكامل الأدوات والـ plugin
|
||||
### تكامل الأدوات وPlugin
|
||||
|
||||
- استدعاء MCP plugin-tools
|
||||
- ظهور Skills
|
||||
- التثبيت السريع للـ skill
|
||||
- استدعاء أدوات MCP Plugin
|
||||
- رؤية المهارات
|
||||
- تثبيت المهارة السريع
|
||||
- توليد الصور الأصلي
|
||||
- رحلة الصورة الكاملة
|
||||
- فهم الصورة من مرفق
|
||||
- دورة ذهاب وإياب للصورة
|
||||
- فهم الصورة من المرفق
|
||||
|
||||
### تعدد الأدوار وتعدد الأدوار الفاعلة
|
||||
### متعدد الأدوار ومتعدد المنعطفات
|
||||
|
||||
- تسليم العمل إلى وكيل فرعي
|
||||
- تركيب التوزيع المتوازي لوكلاء فرعيين
|
||||
- تسليم وكيل فرعي
|
||||
- تجميع مخرجات الوكلاء الفرعيين
|
||||
- تدفقات بأسلوب التعافي بعد إعادة التشغيل
|
||||
|
||||
هذه الفئات مهمة لأنها تحدد متطلبات DSL. فقائمة مسطحة من المطالبات + النص المتوقع ليست كافية.
|
||||
هذه الفئات مهمة لأنها تحدد متطلبات DSL. فالقائمة المسطحة التي تحتوي على مطالبة + نص متوقع لا تكفي.
|
||||
|
||||
## الاتجاه
|
||||
|
||||
### مصدر حقيقة واحد
|
||||
### مصدر وحيد للحقيقة
|
||||
|
||||
استخدم `qa/scenarios/index.md` بالإضافة إلى `qa/scenarios/*.md` كمصدر
|
||||
الحقيقة المؤلف.
|
||||
استخدم `qa/scenarios/index.md` بالإضافة إلى `qa/scenarios/<theme>/*.md` بوصفها
|
||||
المصدر المؤلف للحقيقة.
|
||||
|
||||
يجب أن تظل الحزمة:
|
||||
ينبغي أن تظل الحزمة:
|
||||
|
||||
- قابلة للقراءة البشرية أثناء المراجعة
|
||||
- قابلة للتحليل آليًا
|
||||
- غنية بما يكفي لتشغيل:
|
||||
- تنفيذ الحزمة
|
||||
- تهيئة مساحة عمل QA
|
||||
- بيانات تعريف واجهة مستخدم QA Lab
|
||||
- غنية بما يكفي لقيادة:
|
||||
- تنفيذ المجموعة
|
||||
- تمهيد مساحة عمل QA
|
||||
- بيانات وصفية لواجهة QA Lab
|
||||
- مطالبات الوثائق/الاكتشاف
|
||||
- توليد التقارير
|
||||
|
||||
### تنسيق التأليف المفضل
|
||||
### صيغة التأليف المفضلة
|
||||
|
||||
استخدم Markdown كتنسيق علوي، مع YAML منظّم بداخله.
|
||||
استخدم Markdown كصيغة عليا، مع YAML منظَّم داخله.
|
||||
|
||||
الشكل الموصى به:
|
||||
البنية الموصى بها:
|
||||
|
||||
- YAML frontmatter
|
||||
- id
|
||||
- title
|
||||
- surface
|
||||
- tags
|
||||
- docs refs
|
||||
- code refs
|
||||
- تجاوزات النموذج/الموفر
|
||||
- prerequisites
|
||||
- مراجع الوثائق
|
||||
- مراجع الشيفرة
|
||||
- تجاوزات النموذج/المزوّد
|
||||
- المتطلبات المسبقة
|
||||
- أقسام نثرية
|
||||
- objective
|
||||
- notes
|
||||
- debugging hints
|
||||
- الهدف
|
||||
- ملاحظات
|
||||
- تلميحات تصحيح
|
||||
- كتل YAML مسيجة
|
||||
- setup
|
||||
- steps
|
||||
- assertions
|
||||
- cleanup
|
||||
- الإعداد
|
||||
- الخطوات
|
||||
- التأكيدات
|
||||
- التنظيف
|
||||
|
||||
وهذا يوفّر:
|
||||
يوفر هذا:
|
||||
|
||||
- قابلية قراءة أفضل في طلبات السحب من JSON ضخم
|
||||
- سياقًا أغنى من YAML الخالص
|
||||
- قابلية قراءة أفضل في طلبات السحب من JSON الضخم
|
||||
- سياقًا أغنى من YAML الصرف
|
||||
- تحليلًا صارمًا وتحقق `zod`
|
||||
|
||||
يُقبل JSON الخام فقط كصيغة وسيطة مولدة.
|
||||
يُقبل JSON الخام فقط بوصفه صيغة وسيطة مولدة.
|
||||
|
||||
## الشكل المقترح لملف السيناريو
|
||||
|
||||
@ -189,7 +189,7 @@ codeRefs:
|
||||
|
||||
# الهدف
|
||||
|
||||
تحقق من إعادة إرفاق الوسائط المولدة في الدور اللاحق.
|
||||
تحقق من إعادة إرفاق الوسائط المولدة في المنعطف التالي.
|
||||
|
||||
# الإعداد
|
||||
|
||||
@ -223,7 +223,7 @@ codeRefs:
|
||||
- fromArtifact: lighthouseImage
|
||||
```
|
||||
|
||||
# التوقع
|
||||
# المتوقع
|
||||
|
||||
```yaml scenario.expect
|
||||
- assert: outbound.textIncludes
|
||||
@ -237,9 +237,9 @@ codeRefs:
|
||||
```
|
||||
````
|
||||
|
||||
## قدرات المشغّل التي يجب أن يغطيها DSL
|
||||
## قدرات المشغل التي يجب أن تغطيها DSL
|
||||
|
||||
استنادًا إلى الحزمة الحالية، يحتاج المشغّل العام إلى أكثر من مجرد تنفيذ المطالبات.
|
||||
استنادًا إلى المجموعة الحالية، يحتاج المشغل العام إلى أكثر من مجرد تنفيذ المطالبات.
|
||||
|
||||
### إجراءات البيئة والإعداد
|
||||
|
||||
@ -250,7 +250,7 @@ codeRefs:
|
||||
- `thread.create`
|
||||
- `workspace.writeSkill`
|
||||
|
||||
### إجراءات دور الوكيل
|
||||
### إجراءات منعطفات الوكيل
|
||||
|
||||
- `agent.send`
|
||||
- `agent.wait`
|
||||
@ -266,7 +266,7 @@ codeRefs:
|
||||
- `tools.effective`
|
||||
- `skills.status`
|
||||
|
||||
### إجراءات الملفات والعناصر الناتجة
|
||||
### إجراءات الملفات والآثار
|
||||
|
||||
- `file.write`
|
||||
- `file.read`
|
||||
@ -275,7 +275,7 @@ codeRefs:
|
||||
- `artifact.captureGeneratedImage`
|
||||
- `artifact.capturePath`
|
||||
|
||||
### إجراءات الذاكرة وcron
|
||||
### إجراءات الذاكرة وCron
|
||||
|
||||
- `memory.indexForce`
|
||||
- `memory.searchCli`
|
||||
@ -305,76 +305,76 @@ codeRefs:
|
||||
- `cron.managedPresent`
|
||||
- `artifact.exists`
|
||||
|
||||
## المتغيرات ومراجع العناصر الناتجة
|
||||
## المتغيرات ومراجع الآثار
|
||||
|
||||
يجب أن يدعم DSL المخرجات المحفوظة والمراجع اللاحقة إليها.
|
||||
يجب أن تدعم DSL المخرجات المحفوظة والمراجع اللاحقة إليها.
|
||||
|
||||
أمثلة من الحزمة الحالية:
|
||||
أمثلة من المجموعة الحالية:
|
||||
|
||||
- إنشاء خيط، ثم إعادة استخدام `threadId`
|
||||
- إنشاء سلسلة، ثم إعادة استخدام `threadId`
|
||||
- إنشاء جلسة، ثم إعادة استخدام `sessionKey`
|
||||
- توليد صورة، ثم إرفاق الملف في الدور التالي
|
||||
- توليد سلسلة وسم إيقاظ، ثم التأكد من ظهورها لاحقًا
|
||||
- توليد صورة، ثم إرفاق الملف في المنعطف التالي
|
||||
- توليد سلسلة علامة استيقاظ، ثم التأكد من ظهورها لاحقًا
|
||||
|
||||
القدرات المطلوبة:
|
||||
|
||||
- `saveAs`
|
||||
- `${vars.name}`
|
||||
- `${artifacts.name}`
|
||||
- مراجع typed للمسارات، ومفاتيح الجلسات، ومعرّفات الخيوط، والواسمات، ومخرجات الأدوات
|
||||
- مراجع مكتوبة للأنواع للمسارات، ومفاتيح الجلسات، ومعرفات السلاسل، والعلامات، ومخرجات الأدوات
|
||||
|
||||
من دون دعم المتغيرات، سيستمر الـ harness في تسريب منطق السيناريو مرة أخرى إلى TypeScript.
|
||||
من دون دعم المتغيرات، سيظل الحزام يعيد تسريب منطق السيناريو إلى TypeScript.
|
||||
|
||||
## ما الذي يجب أن يبقى كمخارج طوارئ
|
||||
## ما الذي ينبغي أن يبقى كمنافذ هروب
|
||||
|
||||
المشغّل التصريحي الخالص بالكامل غير واقعي في المرحلة 1.
|
||||
المشغل التصريحي النقي بالكامل غير واقعي في المرحلة 1.
|
||||
|
||||
بعض السيناريوهات بطبيعتها كثيفة التنسيق:
|
||||
|
||||
- اجتياح حلم الذاكرة
|
||||
- إيقاظ إعادة تشغيل تطبيق الإعدادات
|
||||
- قلب قدرة إعادة تشغيل الإعدادات
|
||||
- حل عنصر الصورة المولد حسب الطابع الزمني/المسار
|
||||
- مسح Dreaming للذاكرة
|
||||
- تطبيق الإعداد وإعادة التشغيل والاستيقاظ
|
||||
- قلب قدرة إعادة تشغيل الإعداد
|
||||
- حل أثر الصورة المولدة حسب الطابع الزمني/المسار
|
||||
- تقييم تقرير الاكتشاف
|
||||
|
||||
ينبغي أن تستخدم هذه السيناريوهات معالجات مخصصة صريحة في الوقت الحالي.
|
||||
ينبغي أن تستخدم هذه السيناريوهات معالِجات مخصصة صريحة في الوقت الحالي.
|
||||
|
||||
القاعدة الموصى بها:
|
||||
|
||||
- 85-90% تصريحي
|
||||
- خطوات `customHandler` صريحة للباقي الصعب
|
||||
- معالجات مخصصة مسماة وموثقة فقط
|
||||
- لا يوجد كود مضمن مجهول داخل ملف السيناريو
|
||||
- معالِجات مخصصة مسماة وموثقة فقط
|
||||
- لا شيفرة مضمنة مجهولة داخل ملف السيناريو
|
||||
|
||||
يحافظ ذلك على نظافة المحرك العام مع السماح بإحراز التقدم.
|
||||
هذا يُبقي المحرك العام نظيفًا مع السماح بإحراز تقدم.
|
||||
|
||||
## التغيير المعماري
|
||||
|
||||
### الحالي
|
||||
|
||||
أصبح Markdown الخاص بالسيناريو الآن مصدر الحقيقة لكل من:
|
||||
أصبح Markdown الخاص بالسيناريو الآن هو مصدر الحقيقة من أجل:
|
||||
|
||||
- تنفيذ الحزمة
|
||||
- ملفات تهيئة مساحة العمل
|
||||
- فهرس سيناريوهات واجهة مستخدم QA Lab
|
||||
- بيانات تعريف التقرير
|
||||
- تنفيذ المجموعة
|
||||
- ملفات تمهيد مساحة العمل
|
||||
- فهرس سيناريوهات واجهة QA Lab
|
||||
- بيانات التقرير الوصفية
|
||||
- مطالبات الاكتشاف
|
||||
|
||||
التوافق المولد:
|
||||
|
||||
- لا تزال مساحة العمل المهيأة تتضمن `QA_KICKOFF_TASK.md`
|
||||
- لا تزال مساحة العمل المهيأة تتضمن `QA_SCENARIO_PLAN.md`
|
||||
- تتضمن مساحة العمل المهيأة الآن أيضًا `QA_SCENARIOS.md`
|
||||
- لا تزال مساحة العمل المزروعة تتضمن `QA_KICKOFF_TASK.md`
|
||||
- لا تزال مساحة العمل المزروعة تتضمن `QA_SCENARIO_PLAN.md`
|
||||
- كما أصبحت مساحة العمل المزروعة تتضمن أيضًا `QA_SCENARIOS.md`
|
||||
|
||||
## خطة إعادة الهيكلة
|
||||
|
||||
### المرحلة 1: المُحمّل والمخطط
|
||||
### المرحلة 1: المُحمِّل والمخطط
|
||||
|
||||
تمت.
|
||||
|
||||
- تمت إضافة `qa/scenarios/index.md`
|
||||
- تم تقسيم السيناريوهات إلى `qa/scenarios/*.md`
|
||||
- تمت إضافة محلل لمحتوى حزمة YAML المسمى في Markdown
|
||||
- تم تقسيم السيناريوهات إلى `qa/scenarios/<theme>/*.md`
|
||||
- تمت إضافة محلل لمحتوى حزمة Markdown YAML المسمّى
|
||||
- تم التحقق باستخدام `zod`
|
||||
- تم تحويل المستهلكين إلى الحزمة المحللة
|
||||
- تمت إزالة `qa/seed-scenarios.json` و`qa/QA_KICKOFF_TASK.md` على مستوى المستودع
|
||||
@ -382,60 +382,60 @@ codeRefs:
|
||||
### المرحلة 2: المحرك العام
|
||||
|
||||
- تقسيم `extensions/qa-lab/src/suite.ts` إلى:
|
||||
- loader
|
||||
- engine
|
||||
- action registry
|
||||
- assertion registry
|
||||
- custom handlers
|
||||
- مُحمِّل
|
||||
- محرك
|
||||
- سجل إجراءات
|
||||
- سجل تأكيدات
|
||||
- معالِجات مخصصة
|
||||
- الإبقاء على دوال المساعدة الحالية كعمليات للمحرك
|
||||
|
||||
الناتج القابل للتسليم:
|
||||
الناتج المطلوب:
|
||||
|
||||
- ينفذ المحرك سيناريوهات تصريحية بسيطة
|
||||
- ينفّذ المحرك سيناريوهات تصريحية بسيطة
|
||||
|
||||
ابدأ بالسيناريوهات التي تكون في الغالب مطالبة + انتظار + تأكيد:
|
||||
ابدأ بالسيناريوهات التي هي غالبًا مطالبة + انتظار + تأكيد:
|
||||
|
||||
- متابعة ضمن خيط
|
||||
- فهم الصورة من مرفق
|
||||
- ظهور الـ skill واستدعاؤه
|
||||
- متابعة ضمن سلسلة
|
||||
- فهم الصورة من المرفق
|
||||
- رؤية المهارة واستدعاؤها
|
||||
- خط أساس القناة
|
||||
|
||||
الناتج القابل للتسليم:
|
||||
الناتج المطلوب:
|
||||
|
||||
- أول سيناريوهات حقيقية معرّفة في Markdown تُشحن عبر المحرك العام
|
||||
|
||||
### المرحلة 4: ترحيل السيناريوهات المتوسطة
|
||||
|
||||
- رحلة توليد الصورة الكاملة
|
||||
- دورة ذهاب وإياب لتوليد الصور
|
||||
- أدوات الذاكرة في سياق القناة
|
||||
- ترتيب ذاكرة الجلسة
|
||||
- تسليم العمل إلى وكيل فرعي
|
||||
- تركيب التوزيع المتوازي لوكلاء فرعيين
|
||||
- تسليم وكيل فرعي
|
||||
- تجميع مخرجات الوكلاء الفرعيين
|
||||
|
||||
الناتج القابل للتسليم:
|
||||
الناتج المطلوب:
|
||||
|
||||
- إثبات المتغيرات والعناصر الناتجة وتأكيدات الأدوات وتأكيدات سجل الطلبات
|
||||
- إثبات المتغيرات، والآثار، وتأكّدات الأدوات، وتأكّدات سجل الطلبات
|
||||
|
||||
### المرحلة 5: إبقاء السيناريوهات الصعبة على المعالجات المخصصة
|
||||
### المرحلة 5: إبقاء السيناريوهات الصعبة على المعالِجات المخصصة
|
||||
|
||||
- اجتياح حلم الذاكرة
|
||||
- إيقاظ إعادة تشغيل تطبيق الإعدادات
|
||||
- قلب قدرة إعادة تشغيل الإعدادات
|
||||
- مسح Dreaming للذاكرة
|
||||
- تطبيق الإعداد وإعادة التشغيل والاستيقاظ
|
||||
- قلب قدرة إعادة تشغيل الإعداد
|
||||
- انجراف مخزون وقت التشغيل
|
||||
|
||||
الناتج القابل للتسليم:
|
||||
الناتج المطلوب:
|
||||
|
||||
- نفس تنسيق التأليف، ولكن مع كتل خطوات مخصصة صريحة عند الحاجة
|
||||
- نفس صيغة التأليف، ولكن مع كتل خطوات مخصصة صريحة عند الحاجة
|
||||
|
||||
### المرحلة 6: حذف خريطة السيناريوهات المرمزة بشكل ثابت
|
||||
### المرحلة 6: حذف خريطة السيناريوهات المرمزة
|
||||
|
||||
بمجرد أن تصبح تغطية الحزمة جيدة بما يكفي:
|
||||
|
||||
- أزل معظم التفرعات الخاصة بالسيناريو في TypeScript من `extensions/qa-lab/src/suite.ts`
|
||||
- إزالة معظم التفرعات الخاصة بكل سيناريو في TypeScript من `extensions/qa-lab/src/suite.ts`
|
||||
|
||||
## دعم Slack المزيف / الوسائط الغنية
|
||||
|
||||
حافلة QA الحالية تعتمد النص أولًا.
|
||||
ناقل QA الحالي يركّز على النص أولًا.
|
||||
|
||||
الملفات ذات الصلة:
|
||||
|
||||
@ -445,17 +445,17 @@ codeRefs:
|
||||
- `extensions/qa-lab/src/bus-server.ts`
|
||||
- `extensions/qa-lab/web/src/ui-render.ts`
|
||||
|
||||
اليوم تدعم حافلة QA:
|
||||
اليوم يدعم ناقل QA ما يلي:
|
||||
|
||||
- النص
|
||||
- التفاعلات
|
||||
- الخيوط
|
||||
- السلاسل
|
||||
|
||||
وهي لا تصمم بعد مرفقات وسائط مضمنة.
|
||||
لكنه لا يصمّم بعد مرفقات الوسائط المضمنة.
|
||||
|
||||
### عقد النقل المطلوب
|
||||
|
||||
أضف نموذج مرفقات عام لحافلة QA:
|
||||
أضف نموذج مرفقات عام لناقل QA:
|
||||
|
||||
```ts
|
||||
type QaBusAttachment = {
|
||||
@ -480,61 +480,61 @@ type QaBusAttachment = {
|
||||
- `QaBusInboundMessageInput`
|
||||
- `QaBusOutboundMessageInput`
|
||||
|
||||
### لماذا البدء بشكل عام أولًا
|
||||
### لماذا العام أولًا
|
||||
|
||||
لا تبنِ نموذج وسائط خاصًا بـ Slack فقط.
|
||||
|
||||
بدلًا من ذلك:
|
||||
|
||||
- نموذج نقل QA عام واحد
|
||||
- عدة مصيّرات فوقه
|
||||
- عدة مُصيّرات فوقه
|
||||
- دردشة QA Lab الحالية
|
||||
- واجهة Slack ويب مزيفة مستقبلية
|
||||
- ويب Slack مزيف مستقبلًا
|
||||
- أي عروض نقل مزيفة أخرى
|
||||
|
||||
هذا يمنع تكرار المنطق ويجعل سيناريوهات الوسائط غير مرتبطة بوسيلة نقل محددة.
|
||||
هذا يمنع تكرار المنطق ويجعل سيناريوهات الوسائط مستقلة عن وسيلة النقل.
|
||||
|
||||
### أعمال واجهة المستخدم المطلوبة
|
||||
|
||||
حدّث واجهة مستخدم QA لتصيير:
|
||||
حدّث واجهة QA لعرض:
|
||||
|
||||
- معاينة صورة مضمنة
|
||||
- مشغل صوت مضمن
|
||||
- مشغل فيديو مضمن
|
||||
- شارة مرفق ملف
|
||||
|
||||
يمكن لواجهة المستخدم الحالية بالفعل تصيير الخيوط والتفاعلات، لذا يجب أن يُضاف تصيير المرفقات فوق نموذج بطاقة الرسالة نفسه.
|
||||
يمكن للواجهة الحالية بالفعل عرض السلاسل والتفاعلات، لذا ينبغي أن يندمج عرض المرفقات فوق نموذج بطاقة الرسالة نفسه.
|
||||
|
||||
### أعمال السيناريو التي يتيحها نقل الوسائط
|
||||
|
||||
بمجرد أن تمر المرفقات عبر حافلة QA، يمكننا إضافة سيناريوهات دردشة مزيفة أكثر غنى:
|
||||
بمجرد أن تتدفق المرفقات عبر ناقل QA، يمكننا إضافة سيناريوهات دردشة مزيفة أغنى:
|
||||
|
||||
- رد بصورة مضمنة في Slack المزيف
|
||||
- رد صورة مضمنة في Slack مزيف
|
||||
- فهم مرفق صوتي
|
||||
- فهم مرفق فيديو
|
||||
- ترتيب مختلط للمرفقات
|
||||
- رد ضمن خيط مع الاحتفاظ بالوسائط
|
||||
- رد ضمن سلسلة مع الاحتفاظ بالوسائط
|
||||
|
||||
## التوصية
|
||||
|
||||
يجب أن تكون الدفعة التالية من التنفيذ كما يلي:
|
||||
|
||||
1. إضافة مُحمّل سيناريو Markdown + مخطط `zod`
|
||||
1. إضافة مُحمِّل سيناريو Markdown + مخطط `zod`
|
||||
2. توليد الفهرس الحالي من Markdown
|
||||
3. ترحيل بعض السيناريوهات البسيطة أولًا
|
||||
4. إضافة دعم مرفقات حافلة QA العامة
|
||||
5. تصيير صورة مضمنة في واجهة مستخدم QA
|
||||
4. إضافة دعم مرفقات ناقل QA عام
|
||||
5. تصيير صورة مضمنة في واجهة QA
|
||||
6. ثم التوسع إلى الصوت والفيديو
|
||||
|
||||
هذا هو أصغر مسار يثبت كلا الهدفين:
|
||||
|
||||
- QA عام معرّف عبر Markdown
|
||||
- أسطح مراسلة مزيفة أكثر غنى
|
||||
- QA عام معرّف في Markdown
|
||||
- أسطح مراسلة مزيفة أغنى
|
||||
|
||||
## أسئلة مفتوحة
|
||||
|
||||
- ما إذا كان ينبغي أن تسمح ملفات السيناريو بقوالب مطالبات Markdown مضمنة مع استيفاء المتغيرات
|
||||
- ما إذا كان ينبغي أن تسمح ملفات السيناريو بقوالب مطالبات Markdown مضمنة مع إقحام المتغيرات
|
||||
- ما إذا كان ينبغي أن يكون الإعداد/التنظيف أقسامًا مسماة أو مجرد قوائم إجراءات مرتبة
|
||||
- ما إذا كان ينبغي أن تكون مراجع العناصر الناتجة typed بقوة في المخطط أو معتمدة على السلاسل
|
||||
- ما إذا كان ينبغي أن تعيش المعالجات المخصصة في سجل واحد أو في سجلات حسب السطح
|
||||
- ما إذا كان ينبغي أن يظل ملف التوافق JSON المولد محفوظًا في git أثناء الترحيل
|
||||
- ما إذا كان ينبغي أن تكون مراجع الآثار مكتوبة بقوة في المخطط أو معتمدة على سلاسل نصية
|
||||
- ما إذا كان ينبغي أن تعيش المعالِجات المخصصة في سجل واحد أو في سجلات لكل سطح
|
||||
- ما إذا كان ينبغي أن يظل ملف توافق JSON المولَّد محفوظًا في المستودع أثناء الترحيل
|
||||
|
||||
Loading…
Reference in New Issue
Block a user