gccli: دليل الاستعلام عن بيانات Garmin Connect من سطر الأوامر وعبر الوكيل

لمن هذا الأداة

gccli أداة سطر أوامر لخدمة Garmin Connect، ويصفها المشروع رسميًا بأنها «واجهة سطر أوامر سريعة ومناسبة للبرامج النصية»، وتتيح الوصول إلى الأنشطة والبيانات الصحية وتكوين الجسم والتمارين والمسارات والأجهزة والمعدات والأهداف والشارات. تناسب هؤلاء:

• من يريد الاستعلام عن بياناته في Garmin مباشرة من الطرفية وتمرير النتائج إلى البرامج النصية: يوفر المشروع الرسمي نمطي مخارج قابلين للتحليل هما JSON وplain/TSV، وهما موجّهان صراحةً للبرامج النصية والأتمتة.
• من يعمل داخل عميل وكيل ويريد أن يستعلم الوكيل عن البيانات نيابة عنه: يأتي gccli مع مهارة وكيل (agent skill) جاهزة للاستخدام، ويوضح الطرح الرسمي أنها موجهة إلى عملاء وكلاء الذكاء الاصطناعي مثل Claude Code وCodex وHermes وOpenClaw.
• المطورون الذين يحتاجون إلى دمج بيانات التمارين والصحة في تدفقات مؤتمتة.

الحالات غير المناسبة أو التي تستلزم التحقق أولًا:

• لا يمكن استخدامه دون حساب Garmin Connect: تتم المصادقة عبر Garmin SSO، وهذا شرط إلزامي.
• البيئات التي لا تريد فيها Homebrew: أمر التثبيت الوحيد الجاهز للنسخ الذي توفره الوثائق الرسمية هو أمر Homebrew؛ ويشترط البناء من الشيفرة المصدرية وجود Go 1.26 أو أحدث، بينما لا تذكر الوثائق الرسمية خطوات البناء الكاملة.
• قائمة العملاء أمثلة رسمية لا حصر لها؛ ولم يُذكر هل يوجد توافق خارج هذه القائمة، فارجع إلى وثائق المستودع قبل الربط.

أول تجربة خلال 3 دقائق

المسار الرئيسي الموصى به واحد فقط: ثبّت عبر Homebrew، وأكمل مصادقة Garmin SSO، ثم اطلب من الوكيل تنفيذ استعلام.

المتطلبات المسبقة: لديك حساب Garmin Connect؛ وHomebrew مثبّت على جهازك؛ وتعلم أن المصادقة الأولى ستكتب بيانات الاعتماد في keyring النظام (راجع الآثار الجانبية في قسم «حدود الاستخدام»).

الخطوة 1، التثبيت:

brew install bpauli/tap/gccli

الخطوة 2، المصادقة. تتم المصادقة عبر Garmin SSO، وتُحفظ بيانات الاعتماد في keyring النظام. تفصيلة يجب معرفتها مسبقًا: تذكر الوثائق الرسمية بوضوح أن gccli يشفّر كل ملف رموز بعبارة مرور ثابتة مدمجة في الشيفرة المصدرية — أي ملف الرموز البديل المستخدم عندما لا يتوفر keyring، وعبارة المرور هذه ليست سرًّا خاصًا بك وحدك. فقرر بنفسك، قبل المصادقة الأولى، هل تقبل هذا الأسلوب في التخزين. الوثائق الرسمية لا تقدم أمر تسجيل دخول محددًا؛ بعد التثبيت اتبع المساعدة المدمجة في gccli لإكمال تسجيل الدخول.

الخطوة 3، ربط الوكيل بالمهارة. مهارة الوكيل المرفقة مع gccli موجودة في skills/gccli/SKILL.md ويصفها المشروع الرسمي بالجاهزة للاستخدام؛ أما خطوات ربطها بعميلك فلم تقدمها الوثائق الرسمية، فاتبع وثائق كل عميل.

الخطوة 4، إطلاق مهمة استعلام. قل للوكيل مباشرة: «أخرج لي آخر أنشطة الجري وبيانات تكوين الجسم لهذا الأسبوع». هذه المهمة تقع ضمن قدرات الوصول إلى البيانات المدرجة رسميًا؛ أما هل يكتب الاستعلام ملفات محلية فلا تشرحه الوثائق الرسمية ولم يُؤكد، والوحيد المؤكد من آثار الكتابة هو تخزين الرموز (راجع «حدود الاستخدام») — فلا تفترض أنه للقراءة فقط.

الخطوة 5، التحقق من إشارة النجاح: ينبغي أن تكون الاستجابة مخارج قابلة للتحليل بنمط JSON أو plain/TSV، جاهزة للّصق أو للتسليم إلى برنامج نصي؛ وإذا رأيت مخارج مهيكلة فقد نجح المسار.

حالات الاستخدام

الحالة 1: تلخيص بيانات التمارين والجسم.

• السيناريو: تريد رؤية أحدث سجلات التمارين وتغيرات الوزن دفعة واحدة دون تصفح واجهة الويب سجلًا سجلًا.
• الإطلاق: في عميل وكيل موصول بـ gccli قل: «اسرد لي آخر تماريني وسجلات تكوين الجسم».
• سير العمل: يصل الوكيل عبر gccli إلى فئتي البيانات المؤكدتين رسميًا: الأنشطة وتكوين الجسم.
• النتيجة المتوقعة: تحصل على مخارج JSON أو plain/TSV قابلة للتحليل تلصقها في جدول بيانات أو تسلمها إلى برنامج نصي؛ قائمة حقول السجل الواحد غير مدرجة رسميًا، فالاستجابة الفعلية هي المرجع.

الحالة 2: دمج بيانات Garmin في برامج نصية مؤتمتة.

• السيناريو: تريد تلخيص حالة الأجهزة والمعدات والأهداف والشارات أسبوعيًا لبناء أرشيف تدريب خاص بك.
• الإطلاق: استدعِ gccli من برامجك النصية القائمة أو مهام الوكيل المجدولة، وسلّم المخارج إلى الخطوة التالية.
• سير العمل: استعن بتموضع «الملاءمة للبرامج النصية» الرسمي وبنمطي مخارج JSON وplain/TSV للربط بتدفقاتك القائمة.
• النتيجة المتوقعة: مخارج قابلة للقراءة آليًا تدخل بثبات إلى المعالجة التالية؛ قائمة الأوامر الفرعية والمعاملات الدقيقة غير معطاة نصًا في الوثائق الرسمية، فراجع مخرجات مساعدة gccli وشرح المستودع قبل البدء.

حدود الاستخدام

• الشبكة والحساب: البيانات تأتي من سحابة Garmin Connect، وتحتاج المصادقة وكل استعلام إلى اتصال بالإنترنت وحسابك في Garmin؛ لا ذكر رسميًا لقدرات العمل دون اتصال، ولم يُؤكد ذلك.
• بيانات الاعتماد وآثار الكتابة: تتم المصادقة الأولى عبر Garmin SSO وتُكتب بيانات الاعتماد في keyring النظام؛ ويُشفَّر ملف الرموز البديل، المستخدم عندما لا يتوفر keyring، بعبارة مرور ثابتة مدمجة في الشيفرة المصدرية. عدا تخزين الرموز، لا تشرح الوثائق الرسمية هل يكتب الاستعلام ملفات أخرى، ولم يُؤكد ذلك.
• بيئة التشغيل: يشترط البناء من الشيفرة المصدرية وجود Go 1.26 أو أحدث؛ والمسار الرئيسي الموصى به تثبيت عبر Homebrew دون بناء محلي؛ ومتطلبات التشغيل الأخرى غير موثقة.
• شرط العميل: مهارة الوكيل المرفقة موجهة إلى عملاء وكلاء الذكاء الاصطناعي مثل Claude Code وCodex وHermes وOpenClaw؛ أما التوافق خارج هذه القائمة وتطابق خطوات الربط بين العملاء فلم توضحهما الوثائق الرسمية حالةً بحالة، فارجع إلى وثائق كل عميل قبل الربط.
• الحدود الصريحة: لم تُذكر رسميًا حدود المعدل ولا سقوف التصدير ولا قيود شروط الخدمة؛ فراجع المستودع الرسمي قبل الاستخدام المكثف أو عالي التكرار.