أتمتة واجهة سطح المكتب¶

يستطيع local-shell-mcp مراقبة تطبيقات سطح المكتب الأصلية والتحكم بها على Linux وWindows وmacOS. وتبقى الواجهة العامة صغيرة عن قصد:

الأداة	الغرض
`gui_list`	يسرد نوافذ التطبيقات المرئية ويعرض الـ backend الأصلي النشط وإمكاناته.
`gui_state`	يراقب نافذة واحدة. يعيد `state_id` قصير العمر وعناصر إمكانية الوصول وهندسة النافذة ولقطة شاشة MCP أصلية اختيارية.
`gui_action`	ينفذ إجراءات دلالية أو معتمدة على الإحداثيات على تلك الملاحظة نفسها.

تقبل الأدوات الثلاث معامل machine الاختياري، لذلك يمكن استخدام التدفق نفسه مع desktop worker متصل.

راقب أولاً ثم نفّذ¶

ابدأ بـ gui_list، واختر window_id، ثم استدعِ gui_state. استخدم element_id الخاص بإمكانية الوصول كلما كان يمثل عنصر التحكم المطلوب:

gui_list
  -> gui_state(window_id)
  -> gui_action(window_id, state_id, [{type: "click", element_id: "e17"}])
  -> gui_state(window_id)

استخدم إحداثيات x/y النسبية للنافذة فقط عندما لا توفر الواجهة عنصر إمكانية وصول مناسباً، مثل canvas أو عنصر مرسوم خصيصاً. تستخدم حدود العناصر ولقطات الشاشة المساحة نفسها من البكسلات المنطقية النسبية للنافذة، بما في ذلك شاشات HiDPI/Retina. تُرفض الإحداثيات الخام خارج النافذة المحددة.

تنتهي صلاحية state_id بعد 30 ثانية ويُستخدم مرة واحدة. تتحقق إجراءات الإحداثيات أيضاً من أن النافذة المستهدفة لم تتحرك ولم يتغير حجمها منذ المراقبة. إذا فشل أي تحقق، استدعِ gui_state من جديد بدلاً من إعادة استخدام إحداثيات قديمة.

الإجراءات المدعومة هي click وdouble_click وright_click وmove وscroll وdrag وtype وkey وset_value وfocus وwait.

التحكم البشري في Native WebUI¶

تتضمن Native WebUI صفحة Desktop للتحكم البشري المباشر في backends GUI الأصلية نفسها. اختر جهازاً ونافذة، ثم تفاعل مع صورة النافذة بالنقر أو النقر المزدوج أو الزر الأيمن أو السحب أو عجلة الفأرة أو اختصارات لوحة المفاتيح أو حقل النص لإدخال IME/CJK.

هذا المسار منفصل عمداً عن دلالة state_id الخاصة بالنموذج. تحمل كل لقطة معروضة هندسة النافذة التي تمت ملاحظتها؛ ويتحقق كل طلب إدخال بشري من بقاء الهندسة مطابقة تماماً قبل حقن الإدخال. إذا تحركت النافذة أو تغير حجمها أو اختفت، يُرفض الإجراء وتحدّث WebUI الملاحظة. تظل الإحداثيات الخام محصورة داخل النافذة المحددة.

تضع إجراءات لوحة المفاتيح والنص التركيز صراحة على النافذة الأصلية المحددة قبل الحقن. تستخدم WebUI polling خفيفاً للقطات الشاشة بدلاً من بث فيديو VNC/WebRTC؛ أما RPC البعيد gui_human_action فهو عملية داخلية بين controller وworker وليس أداة MCP معروضة للنماذج.

الـ backends الأصلية¶

المنصة	إمكانية الوصول / التحكم الدلالي	الالتقاط والإدخال الخام
Windows	Microsoft UI Automation	التقاط النافذة وإدخال الفأرة ولوحة المفاتيح الأصلي في Windows
macOS	Accessibility (`AXUIElement`)	`screencapture` للنافذة المحددة وإدخال Quartz `CGEvent`
Linux	AT-SPI	إدخال/التقاط X11 الأصلي؛ يستخدم Wayland التقاط سطح المكتب الأصلي وXDG Desktop Portal RemoteDesktop/ScreenCast

تُجرّب الإجراءات الدلالية أولاً متى أمكن. لذلك يمكن تفعيل زر يملك إجراء invoke/press أصلياً دون تخمين إحداثيات البكسل. تبقى الإحداثيات المرئية fallback للمحتوى غير المتاح أو المرسوم خصيصاً.

إعداد المنصة¶

Windows¶

شغّل LSM في جلسة سطح المكتب التفاعلية نفسها التي تعمل فيها التطبيقات المطلوب التحكم بها. يبقى تثبيت local-shell-mcp الأساسي آمناً في وضع headless ولا يفرض adapter Windows UI Automation؛ ثبّت extra الاختياري local-shell-mcp[gui] عند الحاجة إلى تحكم GUI محلي في Windows.

macOS¶

امنح عملية LSM المضيفة:

إذن إمكانية الوصول للتحكم الدلالي والإدخال.
إذن تسجيل الشاشة للقطات الشاشة.

لا تتطلب الحزمة الأساسية PyObjC. ثبّت extra الاختياري local-shell-mcp[gui] عند الحاجة إلى تحكم GUI محلي في macOS؛ الأجهزة التي لا تستخدم أدوات GUI لا تحتاج هذه الـ frameworks.

Linux¶

يجب أن تعرض جلسة سطح المكتب AT-SPI. في Debian/Ubuntu تتوفر binding النظام المطلوبة عادة عبر:

sudo apt install python3-gi gir1.2-atspi-2.0

لا تتطلب الحزمة الأساسية adapters Python X11 أو D-Bus. يثبت extra الاختياري local-shell-mcp[gui] ما يلزم للاستخدام المحلي. يكتشف الـ worker البعيد جلسة Linux النشطة قبل أي bootstrap لاعتماديات GUI: يحتاج X11 إلى adapter X11 فقط، ويحتاج Wayland إلى adapter D-Bus فقط، ولا يثبت worker في وضع headless أياً منهما. في Wayland يستخدم fallback للمؤشر/لوحة المفاتيح الخام API الخاصة بـ XDG Desktop Portal RemoteDesktop، لذلك قد يعرض سطح المكتب منتقي إذن/جلسة مرة واحدة. تطبيقات portal في KDE وGNOME مدعومة. تستخدم لقطات النافذة مسار الالتقاط الأصلي المتاح وتعود إلى Screenshot portal عند الحاجة.

غالباً ما يبدأ worker الخاص بـ LSM خارج بيئة تسجيل الدخول الرسومية. يستعيد backend Linux المتغيرات DISPLAY وWAYLAND_DISPLAY وXDG_SESSION_TYPE والمتغيرات المرتبطة من بيئة systemd للمستخدم عندما لا تكون موروثة مباشرة.

أسطح المكتب البعيدة¶

تعمل أدوات GUI على الجهاز المحدد وليس على controller. يجب أن ينتمي worker البعيد إلى المستخدم/الجلسة المالكة لسطح المكتب الهدف. تُحمّل adapters GUI بشكل lazy وتقتصر على استدعاءات GUI؛ لا يثبت بدء worker العادي ولا استخدام shell/files/browser هذه adapters ولا يستوردها. على Linux يعيد worker في وضع headless عدم توفر GUI قبل أي GUI pip bootstrap، بينما يتحقق worker الرسومي من adapter المطلوب لجلسة X11 أو Wayland النشطة أو يثبته فقط.

تُنقل لقطات الشاشة التي يعيدها gui_state البعيد عبر مسار نقل الملفات في LSM وتُعرض للنموذج كمحتوى صورة MCP أصلي؛ ولا تُضمّن في استجابة JSON الخاصة بالـ worker.