فخ الحصص الصفرية في Antigravity: كيف طوّرت مهارة مفتوحة للتدوير الذاتي التام بين الحسابات؟

أثناء العمل البرمجي المكثف مع وكلاء الذكاء الاصطناعي في بيئة Google Antigravity، لا شيء يقطع تدفق التركيز (Flow State) مثل التوقف المفاجئ أمام رسالة خطأ: HTTP 429 Resource Exhausted / Quota Exceeded.

لحل هذه المعضلة، يمتلك الكثير من المطورين عدة حسابات Google AI (سواء Pro أو Starter)، ويستخدمون أدوات وسيطة (Proxies) لمحاولة توزيع الطلبات. لكن في التطبيق العملي الميداني، يكتشف المطور فجأة أن كل وعود «الأتمتة الكاملة» تنهار في لحظة حرجة، ويضطر لترك الكود، وفتح لوحات الإدارة، والبحث يدوياً عن حساب يمتلك رصيداً، ثم التبديل وإعادة تشغيل المحرر.

هذا ما دفعني لتشريح المشكلة من جذورها البرمجية، واكتشاف فخ الحصص الخفي، وبناء مهارة مفتوحة المصدر باسم Antigravity Autopilot للتدوير الذاتي الكامل وبلا أدنى تدخل بشري.

المهارة متاحة ومفتوحة المصدر بالكامل على GitHub بترخيص MIT، ومتوافقة مع معايير Agent Skills المفتوحة.

---

تشريح المشكلة: ما الذي يفشل في الحلول المعتادة؟

عندما قمت بتحليل سلوك الأدوات الوسيطة ونظام إدارة الحسابات في Antigravity، ظهرت فجوتان جوهريتان تفسران سبب فشل التدوير التلقائي:

1. فخ حصة الـ 5 ساعات مقابل الحصة الأسبوعية (The Quota Blindspot)

تعتمد جوجل لحسابات الذكاء الاصطناعي على نافذتين متوازيتين للحدود:

• نافذة الـ 5 ساعات المتجددة (Rolling 5-Hour Window): تتجدد تلقائياً كل 5 ساعات من الاستهلاك.
• الحصة الأسبوعية الصلبة (Weekly Quota Bucket): حد أقصى أسبوعي شامل لكل عائلة نماذج.

الكارثة تكمن في طريقة حساب النسبة المئوية المجمعة؛ فأغلب أدوات الوكيل تقرأ حصة نافذة الـ 5 ساعات فقط. فإذا استنفدت الحصة الأسبوعية بالكامل حتى أصبحت 0%، ولكن نافذة الـ 5 ساعات انتهى وقتها وتجددت، ستُظهر واجهة الإدارة أن رصيد النماذج 100%!

النتيجة: يوجّه النظام الطلبات إلى حساب ميت أسبوعياً فيتلقى فوراً رفض 429، ولا يتم تفعيل آليات حماية الحساب (Protected Models) لأن الخوارزمية تظن أن الحساب يمتلك 100%!

2. قيد الجلسة النشطة في بيئة التطوير (IDE Credential Lock)

تخزن بيئة التطوير Antigravity IDE (المبنية على إلكترون وVS Code) مفاتيح الدخول النشطة في مستودع المفاتيح للنظام:

• macOS Keychain: الخدمة gemini والحساب antigravity.
• قاعدة بيانات SQLite الداخلية: state.vscdb.

الأدوات الوسيطة تتعامل مع واجهة API على المنفذ المحلي فقط، ولا تمتلك أي تحكم بالتبديل الذاتي للحساب النشط داخل المحرر نفسه. فعندما ينفد الحساب النشط داخل المحادثة، يتجمد المحرر ويتوقف العمل تماماً.

---

الحل: هيكلية القيادة الذاتية ثلاثية الطبقات

بنيت مهارة Antigravity Autopilot كمنظومة مستقلة تعمل في خلفية النظام على مدار الساعة وتتألف من ثلاث طبقات متناغمة:

┌────────────────────────────────────────────────────────────────────────┐
│             المراقب الذاتي الدائم كل 60 ثانية (LaunchAgent)            │
├────────────────────────────────────────────────────────────────────────┤
│ 1. تحديث الحصص الحقيقية مباشرة من واجهة جوجل الرسمية                   │
│ 2. حساب الحصة الفعلية: دالة القيمة الدنيا min(5h, weekly)              │
│ 3. فحص الحساب النشط في بيئة Antigravity IDE                            │
│ 4. عند هبوط الحساب إلى <= 2%، اختيار أفضل حساب Pro يمتلك رصيداً        │
│ 5. تنفيذ التبديل البرمجي النظيف وحقن المفاتيح في Keychain و SQLite     │
│ 6. إعادة تشغيل المحرر وإرسال إشعار فوري صوتي على سطح المكتب            │
└────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                   الحارس الرقابي كل 5 دقائق (Watchdog)                 │
├────────────────────────────────────────────────────────────────────────┤
│ • إنعاش العمليات المعلقة وضمان استقرار خوادم الخدمة                    │
│ • إطلاق التسخين الاستباقي للنماذج لتجديد نافذة الـ 5 ساعات دورياً      │
│ • النسخ الاحتياطي التلقائي لإعدادات التهيئة                            │
└────────────────────────────────────────────────────────────────────────┘

---

معادلة «الحصة الحقيقية» (True Quota)

الركيزة الرياضية الأساسية في المهارة هي استبدال النسب المضللة بحساب دقيق للاختناق الفعلي:

$$\text{True Quota} = \min(\text{Bucket}{\text{5h}}, \text{Bucket}{\text{weekly}})$$

إذا كان حساب ما يمتلك:

• حصة 5 ساعات: 100%
• حصة أسبوعية: 0.0%

تكون الحصة الحقيقية المحسوبة 0.0%، ويتم استبعاده فوراً من الترشيح وتطبيق الحماية عليه، مما يمنع نهائياً إرسال أي طلب يواجه الرفض 429.

---

دليل التثبيت السريع

المهارة مصممة لتعمل باستقلالية تامة على أنظمة macOS:

1. التثبيت التلقائي بسطر واحد

git clone https://github.com/yasircs4/antigravity-autopilot.git
cd antigravity-autopilot
chmod +x scripts/install.sh
./scripts/install.sh

2. التثبيت كمهارة لوكلاء الذكاء الاصطناعي

يمكن تثبيت المهارة مباشرة داخل مجلد المهارات العام لأي وكيل برمجي (مثل Claude Code أو OpenCode أو Cursor أو Codex):

mkdir -p ~/.agents/skills/antigravity-autopilot
cp -r skills/antigravity-autopilot/* ~/.agents/skills/antigravity-autopilot/

ولمستخدمي بيئة Google Antigravity / Gemini CLI:

mkdir -p ~/.gemini/config/skills/antigravity-autopilot
cp -r skills/antigravity-autopilot/* ~/.gemini/config/skills/antigravity-autopilot/

---

الفحص والتشخيص عبر ميزة Doctor

تتضمن المهارة أداة تشخيص مدمجة لفحص صحة الخدمات وحصص الحسابات النشطة لحظياً:

python3 scripts/doctor.py

نموذج لنتيجة التشخيص الواقعي:

=== 1. Checking LaunchAgents ===
  [PASS] com.antigravity.controller   (PID: 39727, Exit: 0)
  [PASS] com.antigravity.autopilot    (PID: -, Exit: 0)
  [PASS] com.antigravity.notifier     (PID: 67890, Exit: 0)

=== 2. Checking Local Antigravity Tools Proxy (port 8045) ===
  [PASS] Health endpoint reachable: {'status': 'ok', 'version': '4.7.4'}

=== 3. Account True Quotas & Active Selection ===
  account1@gmail.com   | True Gemini:  23.3% | 5h:  99.9% | Weekly:  23.3% | HEALTHY 
  account2@gmail.com   | True Gemini:   0.5% | 5h: 100.0% | Weekly:   0.5% | DEPLETED
  account3@gmail.com   | True Gemini:   0.0% | 5h: 100.0% | Weekly:     0% | DEPLETED
  account4@gmail.com   | True Gemini:  37.4% | 5h:  89.5% | Weekly:  37.4% | HEALTHY  [ACTIVE IDE]

---

إثبات من بيئة التشغيل الحية

في الاختبارات الميدانية أثناء العمل الفعلي، عندما هبط رصيد الحساب النشط najeepyasir إلى 0.2%، التقطت المنظومة الحدث خلال دورة الـ 60 ثانية، واستبعدت الحسابات المستنفدة، ورصدت تعافي الحساب البديل yasir.najeeb.official إلى 70.6%، ونفذت التبديل وحقن المفاتيح وإعادة تشغيل المحرر وإرسال التنبيه في ثوانٍ معدودة:

[INFO] Active account: najeepyasir@gmail.com | True Gemini: 0.2% (5h: 79.9%, Weekly: 0.2%)
[WARN] 🚨 ACTIVE ACCOUNT DEPLETED: najeepyasir@gmail.com is at 0.2% (<= 2.0%)! Triggering rotation...
[INFO] ✅ Selected best replacement account: yasir.najeeb.official@gmail.com (70.6% True Gemini quota)
[INFO] Executing switch via API: accountId=f7e1c14c-0509-4252-bfb7-4558307ed8f1 targetIde=null...
[INFO] 🎉 SUCCESS: Switched active account from najeepyasir@gmail.com to yasir.najeeb.official@gmail.com (70.6% quota)!
[INFO] Active account: yasir.najeeb.official@gmail.com | True Gemini: 68.7% | Threshold: 2.0%

المشروع مفتوح بالكامل لجميع المطورين للمساهمة والتطوير على مستودع GitHub.