agent-desktop computer use: إدارة سطح المكتب بوكيل ذكاء اصطناعي

agent-desktop computer use: وكيل ذكاء اصطناعي يدير macOS وWindows وLinux عبر شجرة إمكانية الوصول. التثبيت والأمان والتتبعات والحدود.
agent-desktop computer use : piloter un bureau par agent IA

agent-desktop computer use: يقدّم مستودع vercel-labs/agent-desktop واجهة سطر أوامر تتيح لوكيل ذكاء اصطناعي رؤية تطبيقات سطح المكتب والتحكم بها على macOS وWindows وLinux. لا يعتمد على لقطات الشاشة: يقرأ شجرة إمكانية الوصول (accessibility tree) الخاصة بالنظام ويعيدها بصيغة JSON، مع مرجع («ref») لكل عنصر يستطيع الوكيل التصرف عليه. تنشر Vercel Labs المستودع بترخيص Apache 2.0.

بالنسبة لمهندس SRE، تغيّر هذه الأدوات نطاق المخاطر. فالوكيل الذي ينقر ويكتب نصًا يعمل على جهاز حقيقي بصلاحيات المستخدم. ماذا يقول المستودع، وكيف يُثبَّت، وما الذي يمكن تتبّعه والتحكم فيه عندما يدير وكيل سطح مكتب؟

توضيح للأمانة: لم تثبّت span.observer أداة agent-desktop ولم تشغّلها. الأوامر مأخوذة من ملف README ومن ملفات docs/ ومن CONCEPTS.md ومن وثائق المشروع، وقد قُرئت في 5 نوفمبر 2026. اللقطات أدناه تعيد إنتاج هذه النصوص. لم نتمكن من إعادة قراءة عدد النجوم من المصدر في ذلك اليوم، لذلك لا نذكره.

agent-desktop computer use: ما يقوله المستودع

  • المبدأ: تقرأ الأداة شجرة إمكانية الوصول لتطبيق ما وتطبعها بصيغة JSON. يتصرف الوكيل على ref، ثم يعيد قراءة الواجهة للتحقق من النتيجة، ثم يكرر. وفق README، تعيش الحلقة داخل وكيلك: لا يتضمن agent-desktop أي نموذج.
  • الشكل: واجهة سطر أوامر CLI ومكتبة بلغة C. يؤرخ سجل التغييرات في المستودع الإصدار 1.2.0 في 5 نوفمبر 2026.
  • الترخيص: Apache 2.0 وفق README وملف LICENSE.
  • الأوامر: يحصي README ‏60 اسم أمر، منها 56 عاملة. أربعة منها (key-down وkey-up وmouse-down وmouse-up) ترفض التنفيذ ما دام لا يوجد daemon قادر على تحرير مفتاح أو زر مضغوط.
  • MCP: يضيف الإصدار 1.2.0 الأمر agent-desktop mcp، وهو خادم MCP عبر stdio يعرض كل أمر على أنه أداة.

تنبيه بشأن الاعتماد: ينبع المشروع من مختبر تابع لناشر معروف، لكنه ما زال حديثًا ويتطور بسرعة (تغييرات غير متوافقة في الإصدار 1.1.0 وفق سجل التغييرات). اقرأ السجل قبل كل تحديث.

جولة في الأوامر والمخرجات

تعيد اللقطة الأولى البدء السريع من README ومقتطف snapshot الذي يعرضه. يظهر غلاف JSON: snapshot_id وعدّاد للمراجع والمؤشر complete، ولكل عنصر قابل للتنفيذ ref_id يتضمن معرّف الـsnapshot.

مقتطف من README في vercel-labs/agent-desktop: ثلاثة أوامر هي snapshot ثم click ثم snapshot على Finder، وغلاف JSON للـsnapshot يحوي snapshot_id وref_count وcomplete وعنصر treeitem يحمل ref_id
Source : github.com

لهذا التصميم نتيجة مفيدة للأمان. وفق README، ينتمي الـref إلى الـsnapshot الخاص به: يُرفض ref مجرد مثل @e8 مع الخطأ INVALID_ARGS. وعندما تتغير الواجهة، يعيد الإجراء STALE_REF أو AMBIGUOUS_TARGET. فلا ينقر الوكيل «بشكل أعمى» على موضع قديم، بل عليه إعادة قراءة الشاشة.

تعرض اللقطة الثانية عقد الأخطاء الموصوف في docs/json-output.md. يحمل كل خطأ الحقل disposition: يبيّن delivery ما إذا كان الإجراء قد أُرسل، ويبيّن retry ما إذا كان يمكن إعادته. تنص الوثائق على الإعادة التلقائية فقط عندما تكون قيمة retry هي safe، وعلى اعتبار unknown غير آمن.

مقتطف من docs/json-output.md: غلاف JSON لخطأ STALE_REF في الأمر click، مع recovery (refresh_snapshot_then_retry_original) وdisposition بقيمة not_delivered وretry بقيمة safe
Source : github.com

التثبيت خطوة بخطوة

الأوامر التالية مأخوذة من README. المتطلبات وفق جدول المنصات: macOS 13 أو أحدث، أو Windows 10 الإصدار 1809 أو أحدث، أو Ubuntu 24.04 أو أحدث (X11 أو Wayland).

  1. ثبّت حزمة npm التي تتضمن الملفات التنفيذية الأصلية x64 وARM64:
    npm install -g agent-desktop
  2. على macOS وLinux يعمل Homebrew أيضًا: brew install agent-desktop. يوضح README أنه لا توجد حزمة Scoop رسمية.
  3. تحقق من المنصة والأذونات والأسطح المدعومة:
    agent-desktop status
    agent-desktop permissions --guide   # macOS : guide pour l'autorisation Accessibilité
  4. شغّل حلقة الملاحظة ثم التنفيذ ثم التحقق:
    agent-desktop snapshot --app Finder -i
    agent-desktop click @s8f3k2p9:e8
    agent-desktop snapshot --app Finder -i
  5. لعميل MCP، صرّح بالخادم (مقتطف من README):
    { "mcpServers": { "agent-desktop": { "command": "agent-desktop", "args": ["mcp"] } } }

في PowerShell يطلب README وضع كل ref بين علامتي اقتباس مفردتين، لأن @token المجرد هو عامل splatting.

الأمان: ما هو موثّق وما يبقى على عاتقك

  • البيانات الخاصة: يحذر README من أن الـsnapshots وقراءات الحافظة ولقطات الشاشة ومخرجات الأوامر قد تحتوي محتوى خاصًا من سطح المكتب. ويطلب إبعادها عن السجلات العامة.
  • وضع بلا واجهة افتراضيًا (headless): تمر الإجراءات على ref عبر واجهة إمكانية الوصول، دون تحريك المؤشر ودون أخذ التركيز. الخيار العام --headed يسمح بالإدخال الفعلي.
  • الأسرار: تقبل الأوامر type وset-value وclipboard-set الخيار --stdin لإبقاء النص خارج وسائط العملية. ينصح README بتنفيذ خطوات الأسرار في أوامر منفصلة، لأن نص دفعة JSON يظهر في الوسائط.
  • الأذونات: على macOS يحتاج البرنامج الذي يشغّل agent-desktop إلى إذن Accessibility. ومنح هذا الحق لوكيل يعادل ائتمانه على الجهاز.
  • حد وظيفي: لا ترى الأداة إلا ما ينشره التطبيق في شجرة إمكانية الوصول. تقول الأسئلة الشائعة في المستودع ذلك: التطبيق الذي بلا شجرة غير مرئي.

هذه الضمانات في الأداة لا تغني عن ضمانات الوكيل. راجع ضوابط وكلاء الذكاء الاصطناعي في الإنتاج لمعرفة حدود الإجراءات التي ينبغي وضعها من جهة الإنتاج، واكتشاف تسميم أدوات MCP إذا ربطت الخادم agent-desktop mcp بعميل يحمّل أدوات أخرى.

مراقبة وكيل يدير سطح مكتب

يوثّق المستودع آلية جلسات وتتبعات، لا قياسًا عن بُعد عبر OpenTelemetry: لا تجد عمليات البحث في ملفات Markdown بالمستودع أي ذكر لـOpenTelemetry أو OTLP أو Prometheus. لذلك لا ينبغي افتراض وجوده.

تعيد اللقطة الثالثة قسم «Sessions and traces» من مرجع الأوامر. الجلسة مجلد تحت ~/.agent-desktop/sessions/<id>/ يحوي ملف بيان (manifest) ومجلد trace/ افتراضيًا. مقاطع التتبع ملفات JSONL، ملف لكل عملية.

مقتطف من commands-system.md في المستودع: الأمر session start مع اسم، وsession end، وأربعة أسطر عن trace show وtrace export وحجب الحقول الحساسة والخيار screenshots غير المحجوب
Source : github.com
  • الخط الزمني: يعيد trace show الخط الزمني المدمج للأحداث، ويكتب trace export عارض HTML مستقلًا. كلاهما لا يحتاج إلى أذونات النظام.
  • الحجب: تستبدل أسطر التتبع الحقول الحساسة (text وvalue وname وtitle وurl وغيرها) بـ { "redacted": true }. ومع --screenshots لا تُحجب ملفات PNG قبل الإجراء وبعده: تعامل معها كلقطات شاشة حساسة.
  • العزل: لكل جلسة مساحة snapshots خاصة بها. يمكن لعدة وكلاء مشاركة معرّف جلسة واحد، بشرط أن يستخدم كل منهم المراجع المؤهلة الخاصة بـsnapshot الخاص به.
  • المتابعة: يعرض status الحقول session_id وtracing وartifacts.

لربط هذه التتبعات بالمراقبة لديك، يبقى عمل عليك: أرسل بنفسك span واحدًا لكل إجراء من منسّق الوكيل، يتضمن الأمر ورمز الخطأ والمدة، ولا تضع فيه محتوى الحقول أبدًا. يتفق المبدأ مع وكيل يدير Chrome عبر DevTools ومع متصفح headless للوكلاء: الأداة تنفذ، والقياس يوضع حولها. لا يوثّق المشروع أي تكامل مع Dynatrace؛ يبقى ممكنًا تصدير OTLP من منسّقك إلى Dynatrace SaaS، ويرجع إعداده إلى وثائق Dynatrace.

أفضل الممارسات

  • شغّل الوكيل في حساب أو جهاز مخصص، دون جلسة مفتوحة على بيانات حساسة.
  • لا تعد تنفيذ أمر إلا إذا كانت قيمة error.disposition.retry هي safe.
  • أبقِ الوضع بلا واجهة افتراضيًا، ولا تفعّل --headed إلا لخطوة محددة.
  • مرّر الأسرار عبر --stdin في أوامر منفصلة.
  • فعّل الجلسات المسمّاة، واحذف القديمة بالأمر session gc، وأبقِ مجلدات التتبع خاصة.
  • سجّل في قياسك الخاص اسم الأمر ورمز الخطأ والمدة، دون المحتوى المقروء.

الأسئلة الشائعة

هل يحتاج agent-desktop إلى لقطات شاشة؟

لا. وفق الأسئلة الشائعة في المستودع، تجد الأوامر التي تأخذ ref العنصر في شجرة إمكانية الوصول لا بمقارنة البكسلات. الأمر screenshot موجود بشكل منفصل.

هل يدير agent-desktop صفحات الويب أيضًا؟

لا. تشير الوثائق إلى أنه لا يؤتمت صفحات الويب وتحيل إلى agent-browser لذلك.

هل يتلقى نموذج بعيد بياناتي؟

توضح الأسئلة الشائعة أن CLI الأصلية لا تتطلب أي خدمة نموذج بعيدة. أما وكيلك فيرسل ما يقرأه إلى نموذجه الخاص: عليك أنت التحكم في هذا التدفق. مساعد اختياري في المستودع، JEV، يرسل الهدف ووصف الشاشات إلى المزوّد الذي تضبطه.

الخلاصة

يقدّم agent-desktop أسلوب computer use قائمًا على شجرة إمكانية الوصول، بمخرجات JSON صارمة وعقد أخطاء واضح. قوته في التشغيل هي قابلية التتبع: جلسات وتتبعات وحجب افتراضي. وحدوده هي حدود هذا النوع: وكيل يعمل على جهاز حقيقي، وبيانات خاصة في كل مكان، ولا قياس قياسي يمكن ربطه. أعد قراءة الوثائق قبل كل نشر.

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركتي Vercel وagent-desktop ولا لشركة Dynatrace LLC. Dynatrace علامة تجارية لشركة Dynatrace LLC. العلامات المذكورة تعود إلى مالكيها. الأدوات تتطور بسرعة: تحقق دائمًا من الأوامر والخيارات في وثائقها الرسمية.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Worktrunk git worktree : CLI pour agents de code en parallèle

Worktrunk git worktree: أداة CLI لتشغيل وكلاء البرمجة بالتوازي

Next Post
kagent agents IA Kubernetes : le framework en détail

kagent وكلاء الذكاء الاصطناعي Kubernetes: الإطار بالتفصيل

Related Posts