أدوات MCP

الأدوات التي يمنحها ScreenPilot لتطبيق الذكاء الاصطناعي، مجمّعة حسب المهمة: التسجيل والمقاطع وstoryboard والتصيير ودمج التسجيلات والتحكم بسطح المكتب والتشخيص.

يعمل ScreenPilot كخادم MCP. يرى تطبيق الذكاء الاصطناعي الأدوات أدناه ويستدعيها عنك، فتطلب الفيديو بكلمات عادية ويختار التطبيق الأدوات. هذه الصفحة للمطورين الذين يريدون معرفة ما تفعله كل أداة بالضبط. ويرسل الخادم سير العمل إلى كل عميل عند الاتصال، فتعرف حتى التطبيقات التي بلا skill الدورة كاملة.

الأزمنة في أدوات الـ storyboard بثواني المصدر (التسجيل الخام). المواضع مُطبَّعة بين 0 و1، حيث x من اليسار وy من الأعلى. الأداة check_output وحدها تستخدم ثواني الخرج.

التسجيل#

الأداة	وظيفتها	أهم المدخلات
`record_start`	تبدأ تسجيل سطح المكتب بالمسجّل المدمج (بدون OBS)، مع أحداث المؤشر والنقرات والنافذة النشطة. تسجيل واحد فقط في كل مرة. اطلب من الشخص تنفيذ العرض ثم استدعِ `record_stop`.	`dir`, `screens` (`"all"` أو أسماء شاشات), `screen`, `fitWindow`, `recorder` (`native` أو `obs`), `input`, `obsUrl`, `obsPassword`, `map`
`record_stop`	توقف التسجيل الجاري. تعيد مجلد الجلسة ومسار الفيديو ومسار `events.jsonl` والمدة والتحذيرات.	لا شيء
`remap`	تعيد ربط أحداث المؤشر في جلسة بشاشة أخرى، عندما ينبّه `record_stop` إلى أنه خمّن الشاشة التي يسجّلها OBS.	`dir`, `screen`

إذا أُغلق العميل أثناء التسجيل، يوقف الخادم التسجيل ويحفظه.

معاينة المقاطع#

الأداة	وظيفتها	أهم المدخلات
`analyze`	تحلّل التسجيل: المدة وفترات الخمول والنقرات وsegments وzooms المقترحة. وتعيد أيضًا صورة contact sheet فيها مصغّرات مرقّمة بالزمن. انظر إلى الصورة أولًا.	`target` (مجلد جلسة أو فيديو)
`get_frames`	تستخرج لقطات من التسجيل المصدر عند ثواني المصدر المحددة وتعيدها صورًا، بحد أقصى 12 في الاستدعاء. وتُحفظ اللقطات أيضًا في مجلد `frames/` بجوار الفيديو. مع تفعيل `grid` تقرأ من الشبكة (0..1) مواضع zoom وhighlight وcallout مباشرة من الصورة.	`video`, `times`, `grid`, `width` (من 160 إلى 3840، الافتراضي 1280)

Storyboard#

الأداة	وظيفتها	أهم المدخلات
`storyboard_schema`	تعيد JSON Schema الخاص بـ `storyboard.json`. اقرأه قبل أن تكتب storyboard.	لا شيء
`storyboard_init`	تكتب `storyboard.json` مبدئيًا لتسجيل أو جلسة. مع `suggest` تملأ segments (بقصّ وقت الخمول) وzooms (من النقرات) مسبقًا. الوسيط `provider` هو `edge` (افتراضي) أو `local` أو `command`، والوسيط `voice` هو اسم الصوت لهذا المزوّد، مثل `voicetut:Sarah`.	`target`, `suggest`, `out`, `voice`, `provider`, `force`
`storyboard_validate`	تتحقق من الـ storyboard مقابل الـ schema والفيديو المصدر. تعيد `valid` مع التحذيرات، أو مشكلات الـ schema. لا ترمي خطأ أبدًا. نفّذها قبل كل تصيير.	`path`
`voices`	تعرض الأصوات. مع `provider` قيمته `edge` (افتراضي) تعرض أصوات Edge وتحتاج إلى اتصال بالشبكة؛ صفِّ حسب اللغة، مثل `ar-EG` أو `en-US`. ومع `local` تعرض النماذج المحلية المثبّتة. ومع `command` تعرض الأصوات المعرّفة في `voices.json`. لا توجد أداة لتثبيت نموذج محلي: نفّذ `screenpilot voice-setup` في الطرفية.	`lang`, `provider`

صيغة الملف موجودة في مرجع الـ storyboard. مزوّدو الصوت في الأصوات.

التصيير والفحص#

الأداة	وظيفتها	أهم المدخلات
`render`	تصيّر storyboard إلى MP4. تستغرق دقائق. إذا كان سطر التعليق الصوتي أطول من مكانه يتجمد الفيديو تلقائيًا (انظر `autoHolds` في النتيجة). استخدم `draft` أثناء التكرار، و`looks` للتصيير العادي، و`delivery` للملف النهائي فقط. مرّر `from` و`to` (بثواني الخرج) لتصيّر تلك النافذة فقط للمراجعة السريعة: الملف هو `<storyboard>.part-<from>-<to>.mp4`. ومرّر `formats` لتصيّر ملفًا لكل صيغة، مع توليد الصوت مرة واحدة.	`storyboard`, `output`, `quality` (`draft` أو `looks` أو `delivery`؛ الافتراضي `looks`), `from`, `to`, `formats`
`check_output`	تعيد لقطات من فيديو مصيَّر على شكل صور، بحد أقصى 12 في الاستدعاء. الأزمنة هنا بثواني الخرج. بدون `times` تحصل على 8 لقطات موزعة بالتساوي. ابحث عن تعليقات مقطوعة، وzoom على موضع خاطئ، وتجميد غير مريح.	`video`, `times`
`build`	تولّد الصوت وتقصّ الفيديو وتكتب مشروع HyperFrames بدون تصيير. تعرض مدة الخرج وفترات التجميد التلقائية والتحذيرات.	`storyboard`
`preview`	تبني الـ storyboard وتفتح HyperFrames Studio ليتنقل الشخص داخل الفيديو.	`storyboard`

المدخل formats قائمة نصوص، كل نص هو "16:9" أو "9:16" أو "1:1" أو "WxH" مثل "1280x720". يكتب <storyboard>.<format>.mp4 (الوسوم 16x9 و9x16 و1x1 وWxH)، ويصبح output عندها الاسم الأساسي. والنتيجة عنصر لكل صيغة. التصدير الطولي يقصّ الـ views العرضية التي تؤطر نافذة. انظر عدة صيغ.

دمج التسجيلات#

تجمع هذه الأدوات عدة storyboards، لكل منها تسجيله، في فيديو واحد، مثلًا لإدخال مقطع ميزة في عرض موجود دون إعادة تسجيله. صيغة الملف في صفحة دمج التسجيلات.

الأداة	وظيفتها	أهم المدخلات
`sequence_schema`	تعيد JSON Schema الخاص بـ `sequence.json`. اقرأها قبل أن تكتب sequence.	لا شيء
`sequence_validate`	تتحقق من sequence وكل storyboard يستخدمه. تعيد `valid` مع التحذيرات، أو المشكلات. لا ترمي خطأ أبدًا.	`path`
`sequence_render`	تصيّر كل جزء مثل storyboard (الأجزاء التي لم تتغير يُعاد استخدامها)، كلها بحجم خرج واحد، مع intro الجزء الأول وoutro الجزء الأخير، ثم تجمعها في MP4 واحد. تستغرق دقائق. أتبعها بـ `check_output`.	`sequence`, `output` (الافتراضي `<sequence>.mp4`), `quality`

رؤية سطح المكتب والتحكم فيه#

تتيح هذه الأدوات للوكيل أن ينظر إلى الشاشة ويتصرف عليها. أدوات التحكم تستخدم الفأرة ولوحة المفاتيح الفعليتين. اقرأ تحكّم الوكيل للدورة، والأمان لمعرفة ما يستطيع الوكيل لمسه وكيف تحدّه. يُسجَّل كل إجراء تحكّم في audit.jsonl داخل مجلد الإعدادات. ولا يُسجَّل النص المكتوب أبدًا.

الرؤية#

هذه الأدوات للقراءة فقط.

الأداة	وظيفتها	أهم المدخلات
`screenshot`	تعيد صورة لكل شاشة. مع تفعيل `grid` تظهر شبكة 0..1 تقرأ منها قيم x وy لتمريرها إلى `pointer_move` و`click`. التقط صورة قبل الإجراء وأخرى بعده للتحقق.	`screen`, `grid`, `width`
`windows`	تعرض النوافذ المفتوحة: المعرّف والعنوان والصنف أو التطبيق وpid وهل هي نشطة والأبعاد والشاشة. فارغة على أنظمة سطح المكتب التي لا تتيح التحكم بالنوافذ (GNOME وsway)؛ استخدم أهداف الشاشة هناك.	لا شيء
`browser_open`	تفتح متصفح العرض النظيف (له ملف تعريف خاص) أو تعيد استخدامه، وتضعه على شاشة. الخيار `app` يخفي شريط العنوان والتبويبات فلا يظهر شيء عن الجهاز. بعدها استخدم أهداف `{web: selector}` والأداة `web_locate`.	`screen`, `url`, `app`
`web_locate`	تجد عنصرًا في متصفح العرض بمحدد Playwright (CSS أو `text=...` أو `role=...`) وتعيد مستطيله بإحداثيات الشاشة بالبكسل. استخدمها للتأكد من وجود الهدف قبل النقر.	`selector`
`wait_for`	تنتظر حتى تظهر نافذة أو عنصر في المتصفح، لتتحقق من نجاح إجراء بدون تخمين مدة الانتظار. مرّر واحدًا فقط من `window` أو `web`. تفشل عند انتهاء المهلة.	`window` أو `web`, `timeout` (بالثواني، الافتراضي 15، الأقصى 120)
`page_text`	تقرأ التبويب الحالي في متصفح العرض كبيانات: العنوان URL والعنوان والنص المرئي. استخدمها لتعرف ما تقوله الصفحة بدل قراءة لقطة شاشة.	`maxChars` (الافتراضي 4000)

التنفيذ#

هذه الأدوات تحرّك المؤشر الفعلي وتضغط مفاتيح فعلية.

الأداة	وظيفتها	أهم المدخلات
`focus_window`	ترفع أول نافذة يحتوي صنفها أو عنوانها على `match` وتعطيها التركيز. ويمكنها نقل النافذة إلى شاشة.	`match`, `screen`
`pointer_move`	تنقل المؤشر بحركة سلسة إلى نقطة على شاشة.	`screen`, `x`, `y`, `dur`
`click`	تنقل المؤشر إلى هدف وتنقر.	`target`, `button` (`left` أو `right` أو `middle`), `count` (من 1 إلى 3؛ 2 نقرة مزدوجة)
`drag`	تضغط عند `from` وتنقل إلى `to` ثم تترك.	`from`, `to`
`scroll`	تدير عجلة الفأرة، ويمكنها الانتقال إلى هدف أولًا. القيمة الموجبة تمرّر للأسفل أو لليمين.	`steps`, `at`, `horizontal`
`key`	تضغط تركيبة مفاتيح في النافذة التي عليها التركيز، مثل `ctrl+l` أو `enter` أو `alt+tab`. على macOS استخدم `cmd` لا `ctrl`.	`combo`
`type_text`	تكتب نصًا في الحقل الذي عليه التركيز كما يفعل الإنسان. للأسرار مرّر `{env: NAME}`: تُقرأ القيمة من بيئة الخادم ولا تظهر أبدًا. ولا يُعاد النص المكتوب في النتيجة.	`text` (نص أو `{env: NAME}`)

الأهداف#

الأدوات click وdrag وscroll تأخذ هدفًا. له ثلاث صيغ:

{web: selector}: عنصر في متصفح العرض بمحدد Playwright. هذه الصيغة الأكثر موثوقية.
{screen, x, y}: نقطة على شاشة، مُطبَّعة بين 0 و1. الحقل screen اختياري.
{window, x, y}: نقطة داخل النافذة التي يحتوي صنفها أو عنوانها على النص، مُطبَّعة بين 0 و1.

على GNOME وغيره من أنظمة Wayland لا يوجد تحكم بالنوافذ. استخدم أهداف {screen, x, y} فقط هناك. نفّذ doctor لترى ما يدعمه سطح المكتب.

الـ takes#

الـ take ملف take.json ينفّذه الوكيل على سطح المكتب الفعلي أثناء التسجيل.

الأداة	وظيفتها	أهم المدخلات
`take_schema`	تعيد JSON Schema الخاص بـ `take.json`: خطوات say وcaption وview وbrowser وgoto وmove وclick وdrag وtype وkey وscroll وwait وwaitFor وwaitForWindow وfocus وopen وrun. اقرأه قبل أن تكتب take.	لا شيء
`perform`	تنفّذ take: تسجّل بالمسجّل المدمج بينما تتحكم بالفأرة ولوحة المفاتيح، وتكتب storyboard مما حدث. الخيار `dryRun` يجرّب الإجراءات نفسها بدون تسجيل؛ جرّب دائمًا أولًا. إذا فشلت خطوة تكون النتيجة خطأ يحمل `failedStep` و`error` و`partial`. يعمل take واحد فقط في كل مرة.	`take`, `dir`, `dryRun`

الإيقاف والاستئناف#

إذا حرّك شخص الفأرة أثناء تحكّم الوكيل، يتوقف الإجراء الجاري مع رسالة. هذا يحمي الشخص الجالس أمام الجهاز. في التشغيل بلا مراقبة، شغّل الخادم مع SCREENPILOT_INTERRUPT=off.

الأداة	وظيفتها	أهم المدخلات
`resume`	تتابع بعد أن توقفت نقرة أو حركة أو كتابة لأن شخصًا آخر حرّك المؤشر. تعتمد موضع المؤشر الحالي وتبقي المشغّل مفتوحًا، فلا يظهر مربع موافقة جديد. التقط لقطة شاشة بعدها، فقد تغيّرت الشاشة.	لا شيء
`abort`	توقف كل ما يتحكم فيه الوكيل الآن: المشغّل الحي و`perform` الجاري. آمنة في أي وقت. أداة التحكم التالية تفتح مشغّلًا جديدًا.	لا شيء

قد يحتاج أول إجراء تحكّم إلى موافقة شخص على مربع حوار التحكم عن بعد (مرة واحدة على Wayland، وتُحفظ الموافقة). على macOS يحتاج تطبيق الذكاء الاصطناعي إلى إذن Accessibility وScreen Recording. ويذكر الخطأ مكان منح الإذن.

التشخيص#

الأداة	وظيفتها	أهم المدخلات
`doctor`	تفحص الجهاز وتعيد `{summary, checks}`: node وffmpeg وسطح المكتب والشاشات والنوافذ وOBS ومتصفح العرض والأصوات، ومنها فحص "local voice" الذي يُتخطّى إذا لم يُعدّ صوت محلي. لا تفشل أبدًا، فاقرأ التقرير. مع تفعيل `input` تختبر حقن الإدخال أيضًا وتحرّك المؤشر الفعلي لحظة.	`input`

نفّذ doctor أولًا على أي جهاز جديد.