دع الوكيل ينفّذ العرض بنفسه

الوكيل ينفّذ العرض على سطح المكتب الحقيقي: يكتب take.json، يجرّبه، ينفّذه أثناء التسجيل، ثم تُحرَّر النتيجة وتُصدَّر.

بدل أن تنفّذ أنت العرض أمام الكاميرا، يستطيع الوكيل أن ينفّذه بنفسه. ينظر إلى شاشتك، ويحرّك الماوس الحقيقي، وينقر ويكتب ويمرّر الصفحة، بينما يسجّل ScreenPilot كل شيء. النتيجة تسجيل مع ملف storyboard.json مبدئي، وتدخل بعدها في دورة التحرير والتصدير المعتادة.

هذه الصفحة موجّهة للمطوّرين ولكل من يريد قراءة الملف الذي يكتبه الوكيل أو تعديله. اسم الملف take، ويُكتب take.json.

الدورة#

كل عرض ينفّذه الوكيل يمرّ بخمس خطوات. يشغّلها الوكيل، ويمكنك تشغيلها بنفسك من سطر الأوامر.

1. الاستكشاف. انظر قبل أن تتصرف: screenshot (مع شبكة إحداثيات من 0 إلى 1)، وwindows، وbrowser_open لتطبيقات الويب. نفّذ الإجراءات بأدوات التحكم مثل click وtype_text، والتقط لقطة شاشة جديدة بعد كل إجراء للتأكد من نجاحه.
2. كتابة take.json. اقرأ المخطط أولاً: take_schema (MCP) أو screenpilot take-schema.
3. التجربة. شغّل perform مع dryRun (في سطر الأوامر: screenpilot perform take.json --dry-run). ينفّذ الإجراءات نفسها على سطح المكتب لكن دون تسجيل. إذا فشلت خطوة فالخطأ يذكر رقمها. أصلحها وأعد التشغيل حتى يمرّ كل شيء.
4. التنفيذ. شغّل perform دون dryRun. يسجّل ScreenPilot وينفّذ الخطوات، ثم يكتب مجلد جلسة فيه الفيديو وevents.jsonl وstoryboard.json مبدئي.
5. المراجعة والتصدير. افحص النتيجة بـ analyze وget_frames، وعدّل الـ storyboard، وتحقّق منه، وصدّر مسودة، وراجعها، ثم صدّر بجودة delivery. راجع مرجع الـ Storyboard.

الأوامر#

screenpilot screenshot [--screen eDP-1] [--grid]   # what each monitor shows
screenpilot windows                                # open windows and their geometry
screenpilot browser --screen HDMI-A-1 --url https://example.com
screenpilot drive move eDP-1,0.5,0.5               # also: drive click, type, key, scroll
screenpilot take-schema                            # print the take.json schema
screenpilot perform take.json --dry-run            # rehearse: same actions, no recording
screenpilot perform take.json                      # record and drive; writes the session folder

داخل تطبيق الذكاء الاصطناعي تكون هذه الخطوات أدوات MCP. القائمة الكاملة في صفحة الأدوات.

شكل الـ take#

الـ take ملف JSON واحد. الحقل الوحيد المطلوب هو steps.

المسارات داخل الـ take (رابط browser أو goto إذا كان ملفاً) نسبية إلى ملف الـ take نفسه. اكتب site/index.html ولا تكتب مساراً مطلقاً من جهازك.

الأهداف#

الخطوات التي تشير إلى شيء على الشاشة (click وmove وdrag وscroll) تأخذ هدفاً. للهدف ثلاث صيغ.

كل الخطوات#

كل خطوة كائن له مفتاح رئيسي واحد. المفاتيح غير المعروفة تُرفض، فيظهر الخطأ المطبعي عند التحقق بدل أن يُتجاهل.

الخطوات say وcaption وview لا تلمس سطح المكتب. تُكتب في الـ storyboard المبدئي كتعليق صوتي وعناوين وتبديل للكاميرا، في لحظة حدوثها. وداخل setup لا تفعل شيئاً.

take كامل#

يملأ هذا الـ take نموذجاً على الويب، ثم ينزّل ملفاً ويفتحه في تطبيق أصلي على شاشة اللابتوب ويمرّر صفحاته. السطر الصوتي الأخير يغيّر الصوت. أسماء الشاشات (HDMI-A-1 وeDP-1) أمثلة فقط: استخدم الأسماء التي يعرضها screenshot أو doctor على جهازك.

{
  "name": "Submit a support ticket",
  "screens": "all",
  "voice": { "name": "en-US-AndrewNeural", "rate": "+0%" },
  "camera": "window",
  "setup": [
    { "browser": { "screen": "HDMI-A-1", "url": "https://app.example.com/support", "app": true } }
  ],
  "steps": [
    { "view": "HDMI-A-1" },
    { "say": "Let's open a support ticket.", "wait": true },
    { "wait": 0.6 },
    { "click": { "web": "input[name=subject]" } },
    { "type": "Cannot export my report" },
    { "click": { "web": "textarea[name=body]" } },
    { "type": "The export button spins forever on large reports." },
    { "caption": "Describe the problem", "dur": 3, "position": "top" },
    { "say": "Then we send it.", "wait": true },
    { "click": { "web": "text=Submit" } },
    { "waitFor": { "web": "text=Download receipt", "timeout": 20 } },
    { "click": { "web": "text=Download receipt" } },
    { "wait": 1.5 },
    { "open": "~/Downloads/receipt.pdf" },
    { "waitForWindow": { "match": "receipt", "timeout": 15 } },
    { "view": "eDP-1" },
    { "focus": { "match": "receipt", "screen": "eDP-1" } },
    { "say": "ورقة التأكيد وصلت وبتتفتح على طول.", "voice": "ar-EG-SalmaNeural", "wait": true },
    { "scroll": 3, "at": { "window": "receipt", "x": 0.5, "y": 0.5 } },
    { "key": "ctrl+w" }
  ],
  "tail": 1.5
}

ما الذي يعطيك إياه perform#

ينتج الـ take المنفَّذ مجلد جلسة فيه الفيديو وevents.jsonl (النقرات فيه مأخوذة مما فعله المشغّل نفسه فهي دقيقة) وstoryboard.json. في هذا الـ storyboard تأتي التكبيرات موضوعة على النقرات، والتعليق الصوتي والعناوين في أوقاتها، وتبديلات الكاميرا. عدّله كأي storyboard آخر.

من سطر الأوامر يكون المجلد sessions/<timestamp> ما لم تمرّر --dir. ومن تطبيق ذكاء اصطناعي يكون مجلداً جديداً داخل مجلد ScreenPilot في مجلد Videos (وفي ماك Movies).

إذا فشلت خطوة يتوقف الـ take، ويحتفظ بما سُجّل حتى تلك اللحظة، ويذكر الخطوة التي فشلت. في تطبيق الذكاء الاصطناعي تحتوي النتيجة على failedStep وerror وpartial. شاهد التسجيل الجزئي لتعرف أين حدث الخطأ.

نصائح#

• قُل ثم انقر. ضع say مع wait: true قبل النقرة المهمة، ليسمع المشاهد ما سيحدث قبل أن يحدث.
• انتظر الشيء نفسه لا الوقت. بعد نقرة تحمّل شيئاً، استخدم waitFor أو waitForWindow بدل wait طويلة. اجعل الانتظار العادي بين 0.3 وثانية واحدة بعد تغيّر الصفحة.
• اجعل الـ take قصيراً. ابقَ تحت 90 ثانية تقريباً. الـ take الأقصر أسرع في التجربة وأسهل في التحرير.
• اجعل الأسطر قصيرة. جملة واحدة وأقل من 12 كلمة تقريباً. التصدير يجمّد الفيديو إذا كان السطر أطول من مكانه، فتزيد الأسطر الطويلة وقتاً ميتاً.
• فضّل أهداف {web} داخل المتصفح التجريبي. تجد العنصر نفسه، فلا تنكسر إذا تغيّر التخطيط.
• الأسرار في البيئة. استخدم { "type": { "env": "NAME" } }. تُقرأ القيمة من متغيرات البيئة عند تنفيذ الخطوة ولا تُسجَّل ولا تُطبع. لا تكتب كلمة مرور داخل take.json أبداً.
• جرّب دائماً بـ dry run. التجربة تكلّف ثوانٍ، أما take حقيقي فاشل فيكلّف تسجيلاً.
• لا تُظهر شيئاً خاصاً. افتح الصفحات مع "app": true حتى لا يظهر شريط العنوان ولا التبويبات ولا مسارات الملفات المحلية.

ما الذي يدعمه كل سطح مكتب#

يعمل التحكم على KDE Plasma وأي سطح مكتب X11 وGNOME على Wayland وWindows وmacOS. ولا يعمل على sway وHyprland، مع أن التسجيل يعمل عليهما.

• KDE Plasma وأسطح مكتب X11 وWindows وmacOS: كل ما في هذه الصفحة يعمل، بما فيه أهداف {web} و{window} والخطوتان focus وwaitForWindow.
• GNOME على Wayland: لا يوجد تحكم بالنوافذ. استخدم أهداف { "screen", "x", "y" } فقط. الخطوتان focus وwaitForWindow وأهداف {window} و{web} تفشل مع رسالة خطأ.
• sway وHyprland: التحكم غير ممكن.

على Wayland يطلب منك النظام الموافقة على نافذة التحكم عن بعد مرة واحدة عند أول استخدام. على macOS يحتاج تطبيق الذكاء الاصطناعي إلى إذن Accessibility. وعلى Windows لا يمكن التحكم بتطبيقات تعمل بصلاحيات المسؤول إلا إذا كان تطبيق الذكاء الاصطناعي يعمل بها أيضاً. الجدول الكامل في صفحة المنصات.