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، ينتمي الـref إلى الـsnapshot الخاص به: يُرفض ref مجرد مثل @e8 مع الخطأ INVALID_ARGS. وعندما تتغير الواجهة، يعيد الإجراء STALE_REF أو AMBIGUOUS_TARGET. فلا ينقر الوكيل «بشكل أعمى» على موضع قديم، بل عليه إعادة قراءة الشاشة.
تعرض اللقطة الثانية عقد الأخطاء الموصوف في docs/json-output.md. يحمل كل خطأ الحقل disposition: يبيّن delivery ما إذا كان الإجراء قد أُرسل، ويبيّن retry ما إذا كان يمكن إعادته. تنص الوثائق على الإعادة التلقائية فقط عندما تكون قيمة retry هي safe، وعلى اعتبار unknown غير آمن.

التثبيت خطوة بخطوة
الأوامر التالية مأخوذة من README. المتطلبات وفق جدول المنصات: macOS 13 أو أحدث، أو Windows 10 الإصدار 1809 أو أحدث، أو Ubuntu 24.04 أو أحدث (X11 أو Wayland).
- ثبّت حزمة npm التي تتضمن الملفات التنفيذية الأصلية x64 وARM64:
npm install -g agent-desktop - على macOS وLinux يعمل Homebrew أيضًا:
brew install agent-desktop. يوضح README أنه لا توجد حزمة Scoop رسمية. - تحقق من المنصة والأذونات والأسطح المدعومة:
agent-desktop status agent-desktop permissions --guide # macOS : guide pour l'autorisation Accessibilité - شغّل حلقة الملاحظة ثم التنفيذ ثم التحقق:
agent-desktop snapshot --app Finder -i agent-desktop click @s8f3k2p9:e8 agent-desktop snapshot --app Finder -i - لعميل 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، ملف لكل عملية.

- الخط الزمني: يعيد
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. العلامات المذكورة تعود إلى مالكيها. الأدوات تتطور بسرعة: تحقق دائمًا من الأوامر والخيارات في وثائقها الرسمية.