عن المشروع

Vole هو مراقب محلي للاستخدام والتكلفة والحالات الشاذة لوكلاء البرمجة بالذكاء الاصطناعي. يستهدف الحالات التي تعمل فيها عدة وكلاء جنباً إلى جنب، حيث يستهلك كل منهم الرموز بشكل مستقل دون إرسال إشارات عند حدوث خطأ ما — مثل العلوق في حلقة أدوات، أو إعادة المحاولة ضد واجهة برمجة تطبيقات (API) معطلة، أو إعادة قراءة نفس السياق الكبير بشكل متكرر. وبينما تجيب الأدوات الأخرى على سؤال "كم أنفقت؟"، يسأل Vole "هل هناك شيء خاطئ يحدث الآن؟" ويقدم تقارير الإنفاق كأثر جانبي. معالجة البيانات يقرأ Vole ملفات السجلات التي تكتبها الأدوات بالفعل على القرص — على سبيل المثال ~/.claude/projects/**/*.jsonl لـ Claude Code، و ~/.local/share/opencode/opencode.db لـ OpenCode، و ~/.codex/sessions/**/rollout-*.jsonl لـ Codex CLI، و ~/.grok/logs/unified.jsonl لـ Grok CLI، بالإضافة إلى المخازن المحلية لـ Cursor و Devin و Antigravity — ويقوم بتوحيدها في مخطط واحد. كل شيء يعمل محلياً: لا كشط للبيانات، لا واجهات برمجة تطبيقات سحابية، لا تسجيل دخول، ولا يتم تخزين محتوى المطالبات أو الأدوات. الإذن الاختياري الوحيد المطلوب هو الإشعارات، للتنبيه عند وقوع حادث حرج. الأدوات المدعومة وسياسة الدقة تختلف التغطية حسب الأداة: يوفر Claude Code و OpenCode الرموز والتكلفة بدقة؛ ويوفر Codex CLI و Grok CLI الرموز بدقة ولكن ليس لديهما أسعار منشورة؛ أما Cursor و Devin و Antigravity فلا يسجلون الرموز محلياً وبالتالي يتم تغطيتهم كنشاط فقط. ينص المشروع على عدم وجود فئة "تقديرية" وفقاً للسياسة — فإما أن يتم قراءة عدد الرموز حرفياً من سجلات الأداة نفسها أو يكون غائباً تماماً، والصفوف التي لا تحتوي على رموز تظل تُحتسب كاستدعاءات ولكن يتم استبعادها من إجمالي الرموز والتكلفة. وقد تم النظر في تقدير رموز Cursor من أسطر الكود ورفض ذلك صراحةً. التطبيق يعرض عنصر في شريط القوائم الرموز المباشرة، أو التكلفة، أو مجرد الأيقونة، والتي يتغير لونها عند وجود حادث مفتوح. يؤدي النقر عليه إلى فتح لوحة تحتوي على الأرقام الرئيسية، ورسم بياني خطي (sparkline)، وأشرطة لكل أداة؛ وتوفر لوحة التحكم عرضاً كاملاً. العنصر المميز هو الجدول الزمني الملحق بالحوادث الذي يكدس الرموز لكل أداة ويسمي الفئة ورموزها وأي حوادث حدثت هناك عند تمرير الماوس. يدمج التطبيق جامع البيانات الخاص به، ويقوم بتشغيله وتحديثه في مكانه: يوفر الإصدار الذي ينشر أرشيفاً مفحوصاً تثبيتاً بنقرة واحدة يتحقق من SHA-256 المنشور قبل استبدال الحزمة، بينما لا يتم التثبيت الصامت أبداً في الإصدارات التي تفتقر إلى المجموع التدقيقي. سطر الأوامر و MCP إلى جانب التطبيق، يوفر Vole أوامر طرفية على نفس البيانات: pnpm top (الجلسات المباشرة، السياق مقابل النافذة، الرموز في الدقيقة، العد التنازلي للتخزين المؤقت)، pnpm digest (ملخص استخدام الوكيل بتنسيق markdown مع خيارات النطاق و JSON)، pnpm pr (الاستخدام على الفرع الحالي لوصف PR)، pnpm statusline، و pnpm mcp، وهو خادم MCP stdio. يوفر خادم MCP وظائف مثل vole_summary و vole_live_sessions و vole_session و vole_incidents و vole_breakdown و vole_whatif و vole_digest، بحيث يمكن للوكيل أن يسأل عن تكلفة جلسته الخاصة أو ما إذا كان Vole قد أشار إليه. يقرأ الخادم قاعدة البيانات المحلية ويجيب عبر stdout. قواعد الحالات الشاذة يأتي التطبيق بخمس قواعد: billable_burn_spike (نافذة 10 دقائق تكلف أكثر من 3 أضعاف النافذة النموذجية لتلك الجلسة)، repeat_call_loop (أكثر من 45 استدعاء في 5 دقائق بينما تظل المخرجات ثابتة)، error_storm (نسبة خطأ تزيد عن 20% على مدار 15 دقيقة مع وجود 5 أخطاء على الأقل)، rate_limit_pressure (يبلغ Codex عن استهلاك أكثر من 80% من الحصة)، و context_pressure (استدعاء يحمل 80% على الأقل من نافذة سياق النموذج). تعتمد الخطوط الأساسية على مقارنة نافذة ما بمتوسط جميع النوافذ الأخرى، ويتطلب اكتشاف الحلقات إشارتين حتى لا يتم الخلط بين دفعة إنتاجية من الاستدعاءات وبين الحلقة المفرغة. نموذج التكلفة التكلفة هي القيمة المعادلة لواجهة برمجة التطبيقات بالسعر الرسمي — ما كانت ستكلفه الاستخدامات عبر API — وتشير واجهة المستخدم إلى أن خطط الاشتراك لا تُحاسب لكل رمز. توجد الأسعار في packages/core/src/data/pricing.json، مؤرخة بـ effective_from، ويقوم ملف ~/.vole/pricing.json لكل تثبيت بالدمج فوقها بحيث يمكن إضافة نموذج دون الحاجة لإصدار جديد؛ ويتم إعادة تسعير الصفوف المخزنة قبل وجود سعر للنموذج بأثر رجعي. تعيد النماذج غير المعروفة قيمة NULL، وليس 0 أبداً. التحقق والاختبار يوفر المشروع pnpm test لاختبارات الوحدة للقواعد والاستعلامات وثوابت الثقة، و pnpm verify الذي يطابق كل صف مخزن مقابل سجله المصدري باستخدام صيغة تكلفة أعيد تنفيذها بشكل مستقل. يقارن التحقق لكل سجل بدلاً من الإجمالي ويفشل في حالة المخزن الفارغ لمنع حدوث نجاح وهمي. يقوم أمر pnpm seed بكتابة سجل اصطناعي لمدة 30 يوماً موسوم بـ source='seed'، ويتم رسمه بيانياً بشكل منفصل عن البيانات الحية. البناء والقيود يتطلب البناء من المصدر Node 22+ و pnpm و Xcode 26، وتم اختباره على macOS 26 arm64؛ يقوم pnpm app:bundle ببناء وفتح التطبيق، أو يمكن تشغيل الجامع والتطبيق بشكل منفصل. تشمل القيود الموثقة التغطية السطحية للأدوات التي لا تسجل رموزاً محلية، وتغطية is_error لأخطاء API فقط مما قد يؤدي لنقص في حساب error_storm، وكون سرعات التوليد هي الحدود الدنيا لبعض الأدوات، وحل نوافذ السياق لمعرفات النماذج الأساسية فقط، والتوقيت التقريبي لـ Antigravity بناءً على mtimes للملفات. المشروع مرخص بموجب MIT ويرحب بالمساهمات، مع قاعدتين للمراجعة: عدم اختراع أي رقم، وأن يكون كل جامع بيانات idempotent.