SoftControl
دليل مستخدم SoftAgent

دليل مستخدم SoftAgent

SoftAgent هو وكيل خفيف الوزن على مستوى المضيف يعمل على أجهزة كمبيوتر Windows المتحكم بها. يستقبل أوامر الشبكة من SoftControl وأنظمة التحكم الأخرى لتنفيذ عمليات على مستوى النظام — الصوت والطاقة وقفل الشاشة ومحاكاة لوحة المفاتيح ومراقبة العمليات — ويُبلّغ بنشاط عن نبضات القلب. يأخذك هذا الدليل من التثبيت إلى التشغيل المستقر.

مواصفات المنتج

منفذ التحكم

UDP 6500 (افتراضي، قابل للتكوين في الإعداد)

المنصة

Windows 10/11 (يتطلب صلاحيات المسؤول للتحكم على مستوى النظام)

الترخيص

مجاني الاستخدام، التسجيل في الحساب مطلوب للتنزيل

البنية

محرّك تنفيذ بحت — بدون نموذج لغوي كبير مدمج، بدون تنسيق ذكاء اصطناعي على الجهاز

استبقاء متبادل بين العمليتين

العملية الرئيسية للتطبيق + المراقب — يحرس كل منهما الآخر ضد الأعطال

البدء التلقائي

يُسجّل مهمة مجدولة للبدء عند تسجيل الدخول بأعلى امتيازات

1. البدء السريع: التثبيت والنشر والتحقق الأول

يوفر SoftAgent مثبّتًا بنقرة واحدة — انقر نقرًا مزدوجًا للتثبيت وتسجيل المهمة المجدولة للبدء التلقائي والبدء الفوري اختياريًا. يساعدك هذا الفصل على إكمال التثبيت والتشغيل الأول والتحقق من عمل الوكيل في غضون 10 دقائق.

1.1 المتطلبات الأساسية

يعمل SoftAgent بأعلى امتيازات لتنفيذ التحكم على مستوى النظام (إيقاف التشغيل، تغيير IP، محاكاة لوحة المفاتيح). يتطلب التثبيت والتشغيل صلاحيات المسؤول.

الهدف

تأكيد أن البيئة تستوفي المتطلبات والاستعداد للتثبيت.

الخطوات
  1. تأكيد أن الكمبيوتر الهدف يعمل بنظام Windows 10/11 x64.
  2. تأكيد امتلاك صلاحيات حساب المسؤول (سيُفعّل المثبّت مطالبة تصعيد UAC).
  3. تأكيد أن جدار الحماية يسمح بحركة UDP الواردة على المنفذ 6500 (منفذ استماع SoftAgent).
  4. حزمة المثبّت مكتفية بذاتها — لا حاجة لتثبيت .NET runtime مسبقًا على الجهاز الهدف.
التحققات
  • القدرة على تشغيل البرامج كمسؤول (قبول تصعيد UAC).
  • منفذ UDP 6500 غير مشغول ببرنامج آخر.
نصائح
  • يمكن لأجهزة الكمبيوتر المتحكم بها المتعددة استخدام نفس المثبّت — يُكوَّن المنفذ وعنوان الإبلاغ بشكل مستقل على كل جهاز.
  • لمشاريع المعارض، يُنصح بضبط جميع أجهزة الكمبيوتر المتحكم بها على تسجيل الدخول التلقائي بحساب مسؤول حتى تعمل مهمة البدء التلقائي بموثوقية.

1.2 التثبيت والتشغيل

استخدم المثبّت الرسمي للتثبيت بنقرة واحدة. بعد التثبيت، يعمل SoftAgent كتطبيق في علبة النظام بدون نافذة رئيسية مرئية.

الهدف

إكمال التثبيت وتأكيد عمل SoftAgent بشكل طبيعي في علبة النظام.

الخطوات
  1. انقر نقرًا مزدوجًا على SoftAgent-Setup-version.exe وانقر نعم في مطالبة UAC للسماح بصلاحيات المسؤول.
  2. اتبع معالج المثبّت لإكمال التثبيت (الافتراضي: C:\Program Files\SoftAgent\).
  3. في صفحة الاكتمال، اختياريًا ضع علامة على 'تشغيل SoftAgent الآن'، أو ابدأ يدويًا بعد ذلك.
  4. بعد التشغيل، يظهر SoftAgent في علبة النظام (لا تفتح نافذة رئيسية).
  5. انقر بزر الماوس الأيمن على أيقونة علبة النظام واختر 'فتح الإعداد' — تأكيد ظهور النافذة الرئيسية بـ 4 تبويبات (الخصائص / البرامج / المراقبة / الإعدادات).
التحققات
  • تظهر أيقونة SoftAgent في علبة النظام.
  • يُظهر مدير المهام عمل عمليتَي SoftAgent.App و SoftAgent.Watchdog.
  • النقر بزر الأيمن على علبة النظام يُظهر: فتح الإعداد / الحالة / إيقاف مؤقت للمراقبة / فتح دليل السجل / حول / إنهاء.
ملاحظة

يستخدم SoftAgent بنية ذات عمليتين: عملية التطبيق تتعامل مع الوظائف، وعملية المراقبة ترصد وتعيد تشغيل التطبيق تلقائيًا إذا أُصيب بعطل — يحرس كل منهما الآخر.

1.3 التكوين الأولي والتحقق

بعد التشغيل الأول، أكمل التكوين الأساسي (منفذ الاستماع، عنوان الإبلاغ، البدء التلقائي)، ثم تحقق من استجابة الوكيل بشكل صحيح باستخدام أمر ping.

الهدف

إكمال التكوين الأساسي وتأكيد عمل الوكيل عبر ping عبر UDP.

الخطوات
  1. انقر نقرًا مزدوجًا على أيقونة علبة النظام لفتح النافذة الرئيسية، انتقل إلى تبويب الإعدادات.
  2. تأكيد أن منفذ الاستماع هو 6500 (أو غيّره حسب الحاجة)، وضع علامة على 'بدء تلقائي' لتسجيل المهمة المجدولة.
  3. للتكامل مع SoftControl، أدخل IP:port الخاص بجهاز SoftControl في حقل 'عنوان الإبلاغ'.
  4. انقر على 'حفظ وتطبيق' لحفظ التكوين.
  5. افتح PowerShell وأرسل ping للتحقق:
  6. $u = New-Object System.Net.Sockets.UdpClient
  7. $b = [Text.Encoding]::UTF8.GetBytes('ping')
  8. $u.Send($b, $b.Length, '127.0.0.1', 6500)
  9. $r = $u.Receive([ref](New-Object System.Net.IPEndPoint([Net.IPAddress]::Any, 0)))
  10. [Text.Encoding]::UTF8.GetString($r)
  11. استلام ok:pong يؤكد عمل الوكيل بشكل طبيعي.
التحققات
  • إرسال ping يستلم استجابة ok:pong.
  • خانة البدء التلقائي في تبويب الإعدادات محفوظة.
  • تشغيل schtasks /Query /TN SoftAgent يُظهر المهمة المجدولة المسجلة.
الأخطاء الشائعة
  • تغيير المنفذ لكن نسيان النقر على 'حفظ وتطبيق'، فلا يسري التغيير.
  • إدخال منفذ وحدة تحكم إدارة HTTP بدلًا من منفذ استماع UDP.

2. مرجع أوامر القدرات: التحكم في النظام ومراقبة العمليات

يستقبل SoftAgent أوامر نصية عبر UDP بصيغة verb أو verb:arg. يُدرج هذا الفصل جميع الأوامر مُنظَّمة حسب مستوى المخاطر لمساعدتك على فهم غرض كل أمر واعتبارات السلامة.

2.1 صيغة الأمر وقواعد الاستجابة

تتبع جميع الأوامر صيغة موحدة. فهم فئات مستوى المخاطر يساعد على استخدام العمليات على مستوى النظام بأمان.

الهدف

إتقان صيغة الأوامر ومستويات المخاطر للاستخدام الآمن لـ SoftAgent.

الخطوات
  1. صيغة الأمر: verb أو verb:arg (الوسيطة تلي النقطتين الأولى)، مثلاً volume:80 أو ping.
  2. استجابة النجاح: ok:<code>، مثلاً ok:pong أو ok:volume.
  3. استجابة الفشل: err:<code>، مثلاً err:wol.invalidMac.
  4. ثلاثة مستويات مخاطر: آمن (بدون تعطيل، قابل للتكرار) / مُقطِع (يقطع الجلسة/العملية لكن بدون فقدان بيانات) / مدمّر (إيقاف التشغيل/إعادة التشغيل/تسجيل الخروج إلخ).
  5. الأوامر المدمّرة تُظهر مربع حوار تأكيد في واجهة المستخدم. عند التشغيل عن بُعد، يتحمل المُرسِل مسؤولية تأكيد النية.
التحققات
  • إرسال ping يستلم ok:pong، مما يؤكد صحة الاتصال وصيغة الأمر.
  • إرسال describe يستلم قائمة قدرات JSON بجميع الأوامر المدعومة ومستويات مخاطرها.
ملاحظة

يُعيد أمر describe القائمة الكاملة لقدرات هذا المثيل من SoftAgent، بما في ذلك اسم كل أمر ووصفه ومستوى مخاطره وما إذا كان يتطلب تأكيدًا — مفيد لاكتشاف القدرات عند التكامل مع SoftControl أو أنظمة الذكاء الاصطناعي.

2.2 الأوامر الآمنة: التحقق والصوت واسترجاع المعلومات

الأوامر الآمنة غير مدمّرة ويمكن تشغيلها بشكل متكرر في أي وقت — مناسبة لمراقبة الحالة الروتينية والتحكم في الصوت.

الهدف

إتقان الأوامر الآمنة للتحكم اليومي في الصوت ومراقبة الحالة.

الخطوات
  1. فحص الاتصال: ping (يستجيب ok:pong، يؤكد أن الوكيل متصل).
  2. الحصول على قائمة القدرات: describe (يُعيد JSON يُدرج جميع الأوامر مع الأوصاف ومستويات المخاطر).
  3. اكتشاف الأجهزة: discover (يُعيد JSON لقطة نبضات القلب مع اسم المضيف وIP وMAC والصوت وحالة المراقبة).
  4. رفع الصوت خطوة: volup (افتراضي +5% لكل استدعاء).
  5. خفض الصوت خطوة: voldown (افتراضي -5% لكل استدعاء).
  6. تبديل الكتم: mute (تبديل بين الكتم وإلغاء الكتم).
  7. الحصول على عنوان MAC لبطاقة الشبكة الأساسية: getmac (يُعيد تنسيق أحرف كبيرة مفصولة بشرطة، مثلاً AA-BB-CC-DD-EE-FF).
  8. إرسال حزمة Wake-on-LAN السحرية: wol:AA-BB-CC-DD-EE-FF (إيقاظ الجهاز بعنوان MAC المحدد).
  9. محاكاة لوحة المفاتيح: key:^s (Ctrl+S)، key:{F5} (مفتاح F5)، key:Hello (كتابة حروف).
التحققات
  • أمر ping يُعيد ok:pong.
  • volup/voldown يغيّر صوت الجهاز المتحكم به.
  • أمر wol يوقظ الجهاز الهدف (يتطلب تفعيل WoL على الهدف).
نصائح
  • استخدم discover للحصول بسرعة على الحالة الحالية للجهاز المتحكم به (IP، الصوت، حالة المراقبة) — مفيد لفحوصات صحة دفعية في SoftControl.
  • تستخدم key: صيغة SendKeys من Microsoft: ^ هي Ctrl، % هي Alt، + هي Shift، المفاتيح الخاصة بين قوسين مثل {ENTER}.

2.3 الأوامر المُقطِعة: قفل الشاشة ومراقبة العمليات والبرامج المُدارة

الأوامر المُقطِعة تقطع الجلسات أو العمليات الحالية لكن لا تسبب فقدان البيانات. تأكد من أنها لن تؤثر على العمل الجاري قبل التنفيذ.

الهدف

إتقان أوامر قفل الشاشة وبدء/إيقاف العمليات وإلغاء إيقاف التشغيل.

الخطوات
  1. قفل الشاشة: lock (يقفل محطة العمل الحالية — يتطلب إعادة تسجيل الدخول للاستعادة).
  2. إلغاء إيقاف تشغيل/إعادة تشغيل مؤجلة: cancelshutdown (استخدم أثناء العد التنازلي لإيقاف التشغيل).
  3. تشغيل عنصر مراقبة بواسطة المعرّف: run:id (مثلاً run:db-player يبدأ العنصر المسمى db-player).
  4. إيقاف عنصر مراقبة بواسطة المعرّف: stop:id (يوقف ويوقف مؤقتًا المراقبة — لن تُعاد العملية تلقائيًا).
  5. تشغيل برنامج مُدار بواسطة الفهرس: startpro:0 (يبدأ البرنامج في الفهرس 0 في قائمة البرامج المُدارة).
  6. إيقاف برنامج مُدار بواسطة الفهرس: killpro:0.
  7. إيقاف جميع البرامج المُدارة: killall.
التحققات
  • بعد lock، تُظهر الجهاز المتحكم به شاشة القفل.
  • بعد run:id، يبدأ عنصر المراقبة المقابل — تتغير الحالة من متوقف إلى يعمل في تبويب المراقبة.
  • cancelshutdown المُرسَل أثناء العد التنازلي لإيقاف التشغيل يلغي إيقاف التشغيل.
نصائح
  • استخدم run/stop مع معرّف المراقبة (معرّف مستقر) بدلًا من startpro/killpro مع الفهرس (الفهرس يتغير عند حذف العناصر أو إعادة ترتيبها).
  • تُكوَّن معرّفات المراقبة في تبويب المراقبة الخاص بـ SoftAgent. حدّث أوامر SoftControl إذا غيّرت معرّفًا.

2.4 الأوامر المدمّرة: إيقاف التشغيل وإعادة التشغيل وتسجيل الخروج

الأوامر المدمّرة خطيرة (إيقاف التشغيل/إعادة التشغيل/تسجيل الخروج إلخ) وتتطلب تأكيدًا. يُنصح باستخدام إيقاف التشغيل المؤجل + cancelshutdown لإمكانية الإلغاء في حالات الطوارئ.

الهدف

تنفيذ العمليات المدمّرة بأمان مثل إيقاف التشغيل وإعادة التشغيل وتسجيل الخروج.

الخطوات
  1. إيقاف تشغيل مؤجل (موصى به): shutdown:60 (إيقاف تشغيل بعد 60 ثانية، cancelshutdown يمكنه الإلغاء أثناء العد التنازلي).
  2. إيقاف تشغيل فوري (استخدم بحذر): shutdown (بدون تأخير، لا يمكن الإلغاء).
  3. إعادة تشغيل مؤجلة (موصى به): reboot:60 (إعادة تشغيل بعد 60 ثانية).
  4. إعادة التشغيل إلى BIOS/UEFI: reboot:firmware (يتطلب دعم UEFI firmware).
  5. تسجيل خروج المستخدم الحالي: logoff (تأكيد عدم وجود بيانات غير محفوظة قبل التنفيذ).
  6. تفعيل/تعطيل UAC: uac:off / uac:on (تغيير سجل، يتطلب إعادة تشغيل للتطبيق، يتطلب مسؤول).
  7. تفعيل/تعطيل إيماءات حافة شاشة اللمس: edgeswipe:off / edgeswipe:on.
  8. تفعيل/تعطيل إصلاح بدء التشغيل التلقائي لـ Windows: autorepair:off / autorepair:on.
التحققات
  • بعد shutdown:60، يُظهر النظام إشعار العد التنازلي 'سيتم إيقاف التشغيل خلال 60 ثانية'.
  • cancelshutdown المُرسَل أثناء العد التنازلي يلغي إيقاف التشغيل.
الأخطاء الشائعة
  • إرسال shutdown بدون تأخير، مما يجعل الإلغاء مستحيلًا — يتوقف الجهاز المتحكم به فورًا.
  • بعد uac:off، عدم إعادة التشغيل والافتراض بأن UAC معطّل بالفعل (يتطلب إعادة تشغيل للتطبيق).
ملاحظة

تتطلب أوامر إيقاف التشغيل صلاحيات المسؤول. في حالة عدم كفاية الأذونات، يُعاد رمز خطأ واضح مثل err:power.denied — لا فشل صامت.

3. التكوين والشبكة: المنفذ وIP والبدء التلقائي

يُخزَّن تكوين SoftAgent في %ProgramData%\SoftAgent\config.json (على مستوى الجهاز، مشترك بين جميع المستخدمين). عدّل التكوين من خلال تبويب الإعدادات في النافذة الرئيسية — تسري التغييرات فورًا (إعادة تحميل ساخنة)، باستثناء تغييرات المنفذ التي تتطلب إعادة تشغيل.

3.1 إعدادات التكوين الأساسية

منفذ الاستماع وعنوان الإبلاغ وفاصل نبضات القلب هي الإعدادات الثلاثة الأكثر استخدامًا. البقية تكوين متقدم.

الهدف

إكمال التكوين الأساسي حتى يتمكن SoftAgent من الاكتشاف الصحيح والتحكم بواسطة SoftControl.

الخطوات
  1. افتح النافذة الرئيسية لـ SoftAgent وانتقل إلى تبويب الإعدادات.
  2. منفذ الاستماع (افتراضي 6500): يُرسل SoftControl والمتحكمون الآخرون أوامر UDP إلى هذا المنفذ.
  3. عنوان الإبلاغ (صيغة IP:port): يُرسل SoftAgent نبضات قلب JSON دورية إلى هذا العنوان؛ أدخل IP ومنفذ استماع SoftControl.
  4. فاصل نبضات القلب (بالثواني): افتراضي 10 ثوانٍ؛ تحتوي نبضات القلب على اسم المضيف وIP وMAC والصوت وحالة المراقبة إلخ.
  5. تأخير البدء التلقائي (بالثواني): تأخير بعد تسجيل الدخول قبل بدء SoftAgent (مفيد للانتظار حتى استعداد الشبكة).
  6. انقر على 'حفظ وتطبيق' بعد التغييرات — تغييرات المنفذ تُظهر إشعار 'يلزم إعادة التشغيل' دائمًا؛ التغييرات الأخرى تسري فورًا.
التحققات
  • يسري التكوين فورًا بعد الحفظ (تغييرات المنفذ تتطلب إعادة تشغيل).
  • إذا كان عنوان الإبلاغ مكوَّنًا، يجب أن يبدأ SoftControl في استلام نبضات قلب JSON دورية من هذا SoftAgent.
نصائح
  • لأجهزة الكمبيوتر المتحكم بها المتعددة، يُنصح باستخدام نفس المنفذ (6500) عبر الجميع لتبسيط إدخال الأوامر الدفعية في SoftControl.
  • ترك عنوان الإبلاغ فارغًا يعني أن SoftAgent لن يُرسل نبضات القلب بشكل استباقي لكنه سيستجيب لأوامر UDP.

3.2 تكوين IP للشبكة

تبويب الخصائص في النافذة الرئيسية لـ SoftAgent يوفر لوحة شبكة لضبط IP ثابت / التبديل إلى DHCP مباشرة — دون استخدام إعدادات Windows أو RDP إلى كل جهاز.

الهدف

تعديل تكوين IP الجهاز المتحكم به من خلال واجهة SoftAgent بدون RDP.

الخطوات
  1. افتح النافذة الرئيسية وانتقل إلى تبويب الخصائص واختر بطاقة الشبكة الهدف في القائمة المنسدلة للوحة الشبكة.
  2. بعد اختيار بطاقة NIC، يُملأ تلقائيًا عنوان IP الحالي وقناع الشبكة الفرعية والبوابة وDNS وعنوان MAC.
  3. تبديل وضع 'IP ثابت / DHCP': الحقول قابلة للتحرير في الوضع الثابت؛ للقراءة فقط في وضع DHCP.
  4. أدخل عنوان IP الهدف وقناع الشبكة الفرعية والبوابة وDNS (الوضع الثابت).
  5. انقر على 'تغيير إعدادات IP' وأكّد في مربع حوار التأكيد.
  6. تغيير IP عملية مدمّرة — ينقطع الاتصال الحالي بعد التغيير. أعد الاتصال بعنوان IP الجديد.
التحققات
  • بعد التغيير، يمكن إرسال ping بنجاح إلى الجهاز المتحكم به على عنوان IP الجديد.
  • يُظهر JSON نبضات قلب SoftAgent عنوان IP المحدَّث.
ملاحظة

تغيير IP عملية مدمّرة. قبل المتابعة، تأكد من إمكانية الوصول إلى عنوان IP الجديد على الشبكة المحلية لتجنب فقدان الوصول عن بُعد إلى الجهاز المتحكم به.

3.3 تكوين البدء التلقائي

ينفّذ SoftAgent البدء التلقائي عبر مهمة مجدولة في Windows، مُفعَّلة عند تسجيل الدخول بأعلى امتيازات — لضمان جاهزية المعرض فور إقلاع الكمبيوتر.

الهدف

تكوين البدء التلقائي حتى يستأنف SoftAgent تشغيله تلقائيًا بعد إعادة تشغيل الكمبيوتر المتحكم به.

الخطوات
  1. في تبويب الإعدادات في النافذة الرئيسية، ضع علامة على 'بدء تلقائي'.
  2. انقر على 'حفظ وتطبيق'.
  3. تحقق باستخدام: schtasks /Query /TN SoftAgent في PowerShell — تأكيد تسجيل المهمة المجدولة.
  4. مُشغِّل المهمة: ONLOGON (يُفعَّل بعد تسجيل دخول المستخدم) بمستوى امتياز HIGHEST.
  5. لضبط تأخير البدء (الانتظار للشبكة أو الخدمات التابعة)، اضبط الثواني في حقل 'تأخير البدء التلقائي'.
  6. لتعطيل البدء التلقائي، أزل علامة 'بدء تلقائي' واحفظ.
التحققات
  • يُظهر schtasks /Query /TN SoftAgent المهمة موجودة ومفعّلة.
  • بعد إعادة تشغيل الكمبيوتر المتحكم به، يظهر SoftAgent تلقائيًا في علبة النظام بعد تسجيل الدخول.

4. التكامل مع SoftControl: وكيل المضيف المتحكم به

SoftAgent هو المكوّن الرفيق للجانب المتحكم به لنظام التحكم في المعارض SoftControl. كوّن أوامر UDP في SoftControl، ويمكن لضغطة زر واحدة التحكم في SoftAgent على أجهزة كمبيوتر متحكم بها متعددة في آنٍ واحد.

4.1 تكوين أوامر SoftAgent في SoftControl

أنشئ أوامر UDP في إدارة أوامر SoftControl لكل جهاز متحكم به، مع ضبط عنوان IP الهدف على IP الجهاز والمنفذ على منفذ استماع SoftAgent (افتراضي 6500).

الهدف

إكمال إعداد أوامر SoftAgent في SoftControl للتحكم القائم على الأزرار في الأجهزة المتحكم بها.

الخطوات
  1. ادخل لوحة إدارة SoftControl وافتح إدارة الأوامر.
  2. أنشئ أمرًا جديدًا، اختر بروتوكول UDP.
  3. اضبط عنوان الهدف على IP الكمبيوتر المتحكم به (مثلاً 192.168.1.101).
  4. اضبط المنفذ على منفذ استماع SoftAgent (افتراضي 6500).
  5. اضبط نص الأمر على الأمر المحدد، مثلاً: volup (رفع الصوت)، mute (تبديل الكتم)، lock (قفل الشاشة)، shutdown:60 (إيقاف التشغيل خلال 60 ثانية).
  6. احفظ واختبر الأمر بشكل فردي — تأكيد استجابة الجهاز المتحكم به بشكل صحيح.
  7. اربط الأمر المتحقق منه بزر في واجهة SoftControl الأمامية.
التحققات
  • بعد إرسال SoftControl لأمر UDP، ينفّذ SoftAgent الخاص بالجهاز المتحكم به الإجراء.
  • تُظهر سجلات SoftControl إرسال الأمر بنجاح (استجابة OK).
نصائح
  • أنشئ مجموعة أوامر لكل جهاز متحكم به، مستخدمًا اسم الجهاز كبادئة (مثلاً 'Hall-PC-01_Shutdown') لسهولة الصيانة.
  • لعمليات دفعية مثل إغلاق المعرض، استخدم مجموعات الأوامر في SoftControl — أضف أوامر إيقاف التشغيل لأجهزة متعددة إلى مجموعة واحدة وشغّلها مرة واحدة.

4.2 استخدام نبضات القلب والاكتشاف لمعرفة حالة الأجهزة

يدعم SoftAgent الإبلاغ الاستباقي عن نبضات القلب والاستجابة لاستعلامات الاكتشاف. يمكن لـ SoftControl استخدام هذه لمراقبة حالة اتصال الأجهزة المتحكم بها.

الهدف

تكوين الإبلاغ عن نبضات القلب لمراقبة حالة اتصال الأجهزة المتحكم بها من SoftControl.

الخطوات
  1. في إعدادات SoftAgent، كوّن عنوان الإبلاغ على IP:port الخاص بـ SoftControl (واجهة UDP الخارجية لـ SoftControl، افتراضي 8818).
  2. يُرسل SoftAgent نبضة قلب واحدة فورًا عند بدء التشغيل، ثم يستمر بالفاصل الزمني المكوَّن (افتراضي 10 ثوانٍ).
  3. يتضمن JSON نبضات القلب: agentId (معرّف جهاز فريد)، hostname، ip/mac (معلومات الشبكة)، volume/muted (حالة الصوت)، guards (حالات عمليات المراقبة)، uptimeSeconds.
  4. للاستعلام الفعّال عن الحالة الحالية لجهاز متحكم به، أرسل discover من SoftControl — يُعيد SoftAgent لقطة نبضات قلب.
  5. حقل guards في نبضات القلب يشير إلى ما إذا كانت عمليات المراقبة تعمل بشكل طبيعي، مما يكشف الأعطال أو حالات التخلي.
التحققات
  • يستلم SoftControl نبضات قلب JSON دورية من SoftAgent.
  • إرسال discover يستلم استجابة JSON مع اسم المضيف وIP والصوت ومعلومات أخرى.

4.3 مراقبة العمليات: إعادة التشغيل التلقائي لتطبيقات المعارض بعد الأعطال

تراقب مراقبة عمليات SoftAgent أي تطبيق Windows وتعيد تشغيله تلقائيًا بعد الأعطال باستخدام استراتيجية التراجع الأسي — مثالية لمشغلات المعارض وبرامج الكشك التي تعمل دون رقابة.

الهدف

تكوين مراقبة إعادة التشغيل التلقائي بعد الأعطال لتطبيقات المعارض.

الخطوات
  1. افتح النافذة الرئيسية لـ SoftAgent وانتقل إلى تبويب المراقبة.
  2. انقر على 'استعراض...' لاختيار .exe للمراقبة، اختياريًا اضبط اسمًا ومعرّف مراقبة (معرّف مستقر يُستخدم لأوامر run/stop).
  3. انقر على 'إضافة' لوضعه في قائمة المراقبة. مفتاح التبديل الفردي يتحكم في ما إذا كانت مراقبة هذا العنصر مفعّلة.
  4. مفتاح تبديل المراقبة الرئيسي في أعلى التبويب — تعطيله يوقف جميع المراقبة مؤقتًا (متزامن مع قائمة 'إيقاف مؤقت للمراقبة' في علبة النظام).
  5. شارات الحالة تُظهر حالة كل عنصر: يعمل / متوقف / أُصيب بعطل / تخلّى عنه (تخلّت المراقبة بعد أعطال كثيرة في النافذة الزمنية).
  6. بعد العطل، يُعيد SoftAgent التشغيل بتراجع أسي (ابتداءً من 5 ثوانٍ، يتضاعف في كل مرة؛ يُتخلى عنه بعد تجاوز الحد في النافذة الزمنية).
التحققات
  • يُظهر البرنامج المحمي حالة 'يعمل' في قائمة المراقبة.
  • إنهاء العملية المحمية يدويًا ويُعيد SoftAgent تشغيلها تلقائيًا بعد تأخير.
  • حقل guards في JSON نبضات القلب يعكس أحدث حالات المراقبة.
ملاحظة

لا تغيّر معرّف المراقبة بشكل تعسفي — تعتمد أوامر run/stop في SoftControl عليه. إذا أعدت تسمية معرّف، حدّث أوامر SoftControl المقابلة.

5. استكشاف الأخطاء وإصلاحها: دليل تشخيص المشكلات الشائعة

يغطي هذا الفصل أكثر أنواع مشكلات SoftAgent شيوعًا وخطوات التشخيص. عند حدوث مشكلات، أرسل ping أولًا لتأكيد الاتصال، ثم تحقق من السجلات، ثم اعمل من خلال المنفذ والأذونات والتكوين.

5.1 أوامر UDP لا تستجيب

لا يوجد رد من SoftAgent بعد إرسال الأوامر — أكثر المشكلات شيوعًا. يحدث عادةً بسبب تكوين منفذ غير صحيح أو حجب جدار الحماية أو عدم تشغيل SoftAgent.

الهدف

استعادة قناة التحكم بأوامر UDP.

الخطوات
  1. تأكيد ظهور SoftAgent في علبة النظام (العملية تعمل).
  2. تأكيد أن منفذ الإرسال يتطابق مع منفذ استماع SoftAgent المكوَّن (افتراضي 6500).
  3. تحقق مما إذا كان جدار حماية Windows يسمح بحركة UDP الواردة على المنفذ 6500.
  4. جرّب ping من localhost (127.0.0.1) أولًا لاستبعاد مشكلات الشبكة، ثم جرّب عن بُعد.
  5. تحقق من ملفات السجل في %ProgramData%\SoftAgent\logs\ لسجلات استلام الأوامر.
التحققات
  • إرسال ping إلى 127.0.0.1 يستلم ok:pong، مما يؤكد عمل SoftAgent ومنفذ UDP.
  • إرسال ping من جهاز بعيد يستلم أيضًا استجابة، مما يؤكد وضوح مسار الشبكة.

5.2 أوامر النظام تُعيد أخطاء الأذونات

أوامر إيقاف التشغيل/إعادة التشغيل/تغيير IP/تعديل UAC تُعيد err:xxx.denied — SoftAgent لا يعمل بصلاحيات المسؤول.

الهدف

ضمان عمل SoftAgent بصلاحيات المسؤول لدعم جميع أوامر مستوى النظام.

الخطوات
  1. تأكيد عمل SoftAgent بصلاحيات المسؤول: البدء التلقائي يستخدم مهمة مجدولة بامتياز HIGHEST؛ للبدء اليدوي، انقر بزر الأيمن على exe واختر 'تشغيل كمسؤول'.
  2. إذا كانت الأوامر مُشغَّلة عبر SoftControl، لا يحتاج SoftControl نفسه لصلاحيات مسؤول — تُحدَّد الصلاحيات بواسطة SoftAgent على الجانب المتحكم به.
  3. تحقق من عمود 'مرتفع' لـ SoftAgent.App.exe في تبويب التفاصيل في مدير المهام — يجب أن يُظهر 'نعم'.
  4. إذا لم يعمل كمسؤول، أنهِ SoftAgent وأعد تشغيله كمسؤول.
التحققات
  • تبويب التفاصيل في مدير المهام يُظهر 'نعم' في عمود 'مرتفع' لـ SoftAgent.App.exe.
  • تستجيب أوامر volup/voldown بشكل طبيعي (لا تتطلب مسؤول — مفيد للتحقق الأساسي).
  • أمر lock يقفل شاشة الجهاز المتحكم به (مستوى مُقطِع — يؤكد صحة الامتياز).

5.3 البدء التلقائي لا يعمل

لا يبدأ SoftAgent تلقائيًا بعد إعادة تشغيل الكمبيوتر المتحكم به — لا تظهر أيقونة في علبة النظام.

الهدف

تشخيص وإصلاح حالات فشل البدء التلقائي.

الخطوات
  1. شغّل schtasks /Query /TN SoftAgent في PowerShell للتأكد من وجود المهمة المجدولة.
  2. إذا لم توجد المهمة، افتح تبويب الإعدادات في SoftAgent، أعد تحديد 'بدء تلقائي' واحفظ.
  3. تأكيد أن الكمبيوتر يستخدم تسجيل الدخول التلقائي (شائع في المعارض) بدلًا من انتظار تسجيل دخول يدوي — مُشغِّل المهمة هو ONLOGON، يتطلب تسجيل دخول مستخدم.
  4. إذا تم إعداده لتسجيل الدخول التلقائي، تأكيد أن حساب تسجيل الدخول التلقائي لديه صلاحيات لتشغيل المهمة (يتطلب حساب مسؤول).
  5. تحقق من السجلات الأخيرة في %ProgramData%\SoftAgent\logs\ لأسباب فشل بدء التشغيل.
التحققات
  • يحتوي ناتج schtasks /Query /TN SoftAgent على مُشغِّل ONLOGON وامتياز HIGHEST.
  • بعد إعادة تشغيل الكمبيوتر المتحكم به وتسجيل الدخول، يظهر SoftAgent تلقائيًا في علبة النظام.

5.4 مراقبة العمليات تتخلى عن عملية (حالة GaveUp)

بعد أعطال متعددة في فترة قصيرة، يتوقف SoftAgent عن محاولة إعادة تشغيل العملية المحمية (حالة GaveUp) لمنع عواصف إعادة تشغيل لا نهائية.

الهدف

فهم سبب تخلي المراقبة واستعادة مراقبة التطبيق الهدف.

الخطوات
  1. في تبويب المراقبة في النافذة الرئيسية لـ SoftAgent، تحقق من شارة الحالة — يؤكد حالة 'GaveUp'.
  2. تحقق من ملفات السجل في %ProgramData%\SoftAgent\logs\ لسبب العطل المحدد (الأخطاء قبل كل عطل).
  3. أصلح السبب الجذري لأعطال التطبيق المحمي (خطأ في التكوين، تبعية مفقودة، تعارض منفذ إلخ).
  4. بعد الإصلاح، أدّر مفتاح تبديل عنصر المراقبة الفردي من إيقاف إلى تشغيل في تبويب المراقبة (أو أرسل run:id من SoftControl) لإعادة تفعيل المراقبة.
  5. تأكيد تغيير حالة عنصر المراقبة إلى 'يعمل' وبقائه مستقرًا بمرور الوقت.
التحققات
  • بعد إصلاح التطبيق المحمي، تتغير حالة المراقبة من 'GaveUp' إلى 'يعمل'.
  • يُظهر JSON نبضات القلب تحديث حالة عنصر المراقبة المقابل إلى يعمل.
ملاحظة

GaveUp سلوك مقصود لمنع عواصف إعادة تشغيل لا نهائية من التأثير على موارد النظام. الحل الحقيقي هو إصلاح السبب الجذري للعطل — وليس إعادة تفعيل المراقبة يدويًا بشكل متكرر.

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

هل SoftAgent مجاني الاستخدام؟

نعم، SoftAgent مجاني. تحتاج إلى تسجيل حساب على الموقع الرسمي لتنزيله. SoftAgent هو المكوّن على جانب الجهاز المتحكم به في منظومة Soft ويعمل بشكل أفضل مقترنًا بـ SoftControl.

هل يُشغّل SoftAgent استدلالًا للذكاء الاصطناعي أو نماذج لغوية كبيرة على الجهاز؟

لا. SoftAgent محرّك تنفيذ بحت — لا يحتوي على نموذج لغوي كبير مدمج ولا يُؤدي تنسيقًا للذكاء الاصطناعي على الجهاز. 'العقل' الذكاء الاصطناعي يقيم في طبقة التحكم العليا (مثل SoftControl أو طبقة تنسيق الذكاء الاصطناعي). ينفّذ SoftAgent فقط تعليمات محددة على مستوى النظام على الكمبيوتر المتحكم به.

هل يمكن لـ SoftAgent و SoftPlayer العمل على نفس الكمبيوتر في آنٍ واحد؟

نعم. يستمع SoftAgent على UDP 6500 ويستمع SoftPlayer على UDP 7600 (افتراضي) — لا تعارض في المنافذ، يمكنهما التعايش على نفس الجهاز. يمكن لـ SoftControl إرسال أوامر تحكم مختلفة إلى كل منفذ بشكل مستقل.

ما الفرق بين معرّف المراقبة والفهرس؟ لماذا أستخدم المعرّف؟

معرّف المراقبة هو معرّف نصي مستقر تُعرّفه أنت (مثلاً db-player) — لا يتغير عند حذف العناصر الأخرى أو إعادة ترتيبها. الفهرس (يبدأ من 0) يتغير مع تغيير القائمة. استخدام المعرّف (run:id/stop:id) يضمن أن أوامر SoftControl لا تزال تشير إلى البرنامج الصحيح بعد إعادة تنظيم القائمة.

أين تُحفظ ملفات سجل SoftAgent؟

تُحفظ السجلات في %ProgramData%\SoftAgent\logs\ (مثلاً C:\ProgramData\SoftAgent\logs\)، بأسماء ملفات بصيغة softagent-date.log. قائمة النقر بزر الأيمن على علبة النظام 'فتح دليل السجل' تنقل مباشرةً إلى هذا المجلد.

هل أنت مستعد لنشر SoftAgent؟

نزّل SoftAgent، ثبّته على كمبيوتر متحكم به وتحقق من استجابة ping، ثم كوّن المنفذ والبدء التلقائي قبل التكامل مع SoftControl لإدارة جميع الأجهزة المتحكم بها في معرضك بشكل مركزي.