أمر الموقع

ملخص سريع

• location.get هو أمر عقدة (عبر node.invoke).
• معطل افتراضيًا.
• تستخدم الإعدادات مُحددًا: معطل / أثناء الاستخدام / دائمًا.
• تبديل منفصل: الموقع الدقيق.

لماذا مُحدد (وليس مجرد مفتاح تشغيل/إيقاف)

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

• iOS/macOS: يمكن للمستخدم اختيار أثناء الاستخدام أو دائمًا في مطالبات النظام/الإعدادات. يمكن للتطبيق طلب الترقية، لكن النظام قد يتطلب الذهاب إلى الإعدادات.
• Android: إذن الموقع في الخلفية هو إذن منفصل؛ في Android 10+ غالبًا ما يتطلب تدفقًا عبر الإعدادات.
• الموقع الدقيق هو منح منفصل (iOS 14+ "دقيق"، Android "دقيق" مقابل "تقريبي").

المُحدد في واجهة المستخدم يوجه الوضع الذي نطلبه؛ بينما المنح الفعلي موجود في إعدادات نظام التشغيل.

نموذج الإعدادات

لكل جهاز عقدة:

• location.enabledMode: off | whileUsing | always
• location.preciseEnabled: منطقي (bool)

سلوك واجهة المستخدم:

• اختيار whileUsing يطلب إذن المقدمة (foreground).
• اختيار always يضمن أولاً الحصول على whileUsing، ثم يطلب إذن الخلفية (أو يوجه المستخدم إلى الإعدادات إذا لزم الأمر).
• إذا رفض نظام التشغيل المستوى المطلوب، يتم التراجع إلى أعلى مستوى مُمنوح وعرض الحالة.

تعيين الأذونات (node.permissions)

اختياري. قد تبلغ عقدة macOS عن location عبر خريطة الأذونات؛ بينما قد تحذفها عقد iOS/Android.

الأمر: location.get

يتم استدعاؤه عبر node.invoke. المعلمات (مقترحة):

{
  "timeoutMs": 10000,
  "maxAgeMs": 15000,
  "desiredAccuracy": "coarse|balanced|precise"
}

حمولة الاستجابة:

{
  "lat": 48.20849,
  "lon": 16.37208,
  "accuracyMeters": 12.5,
  "altitudeMeters": 182.0,
  "speedMps": 0.0,
  "headingDeg": 270.0,
  "timestamp": "2026-01-03T12:34:56.000Z",
  "isPrecise": true,
  "source": "gps|wifi|cell|unknown"
}

الأخطاء (رموز ثابتة):

• LOCATION_DISABLED: المُحدد معطل.
• LOCATION_PERMISSION_REQUIRED: الإذن مفقود للوضع المطلوب.
• LOCATION_BACKGROUND_UNAVAILABLE: التطبيق يعمل في الخلفية لكن المسموح به هو أثناء الاستخدام فقط.
• LOCATION_TIMEOUT: لم يتم تحديد الموقع في الوقت المحدد.
• LOCATION_UNAVAILABLE: فشل النظام / لا توجد مزودات.

سلوك الخلفية (مستقبلي)

الهدف: يمكن للنموذج طلب الموقع حتى عندما تكون العقدة تعمل في الخلفية، ولكن فقط عندما:

• اختار المستخدم دائمًا.
• يمنح نظام التشغيل إذن الموقع في الخلفية.
• يُسمح للتطبيق بالعمل في الخلفية لأغراض الموقع (وضع الخلفية في iOS / خدمة المقدمة في Android أو إذن خاص).

تدفق مُحفز بدفع إشعار (مستقبلي):

1. يرسل البوابة (Gateway) إشعار دفع إلى العقدة (إشعار صامت أو بيانات FCM).
2. تستيقظ العقدة لفترة وجيزة وتطلب الموقع من الجهاز.
3. تقدم العقدة حمولة البيانات إلى البوابة.

ملاحظات:

• iOS: يتطلب إذن "دائمًا" + وضع موقع الخلفية. قد يتم تقنين الإشعارات الصامتة؛ توقع فشل متقطع.
• Android: قد يتطلب موقع الخلفية خدمة مقدمة (foreground service)؛ وإلا، توقع الرفض.

التكامل مع النموذج والأدوات

• سطح الأداة: تضيف أداة nodes إجراء location_get (مطلوب تحديد العقدة).
• سطر الأوامر (CLI): openclaw nodes location get --node <id>.
• إرشادات الوكيل (Agent): استدع الأمر فقط عندما يكون المستخدم قد مكّن الموقع ويفهم النطاق.

نصوص واجهة المستخدم (مقترحة)

• معطل: "مشاركة الموقع معطلة."
• أثناء الاستخدام: "فقط عندما يكون OpenClaw مفتوحًا."
• دائمًا: "السماح بالموقع في الخلفية. يتطلب إذنًا من النظام."
• دقيق: "استخدام موقع GPS الدقيق. قم بإيقاف التبديل لمشاركة موقع تقريبي."

إيقاظ صوتيتحويل النص إلى كلام