التنبؤ بتكلفة الرموز

يوفّر PRECC أداة عرّافة للتنبؤ بتكلفة الرموز حتى يتسنى للخطط متعددة الخطوات أن تُحدَّد ميزانيتها بالرموز لا بالوقت الفعلي. سجّل تنبؤًا قبل كل خطوة، وقيّد القيمة الفعلية بعد إنجاز العمل، وستُدرّب مجموعة البيانات متنبئًا مدمجًا يتحسّن بمرور الوقت.

تسجيل تنبؤ

مرّر وصفًا من سطر واحد للخطوة المخطّطة. يصنّفها PRECC (feat / fix / test / refactor / measurement / doc / chore / unknown)، ويقدّر عدد الرموز، ويطبع معرّفًا (id) ستستخدمه لإغلاق الحلقة.

$ precc predict "Implement read-deltas with mtime check"
id=42 category=feat predicted=5680 tokens (confidence=0.50, model=trained-v1)
Record actual when done: precc predict --record 42 <actual_tokens>

تسجيل القيمة الفعلية

بعد اكتمال الخطوة، ابحث عن العدد الفعلي للرموز في تذييل الجلسة أو في القياس عن بُعد وأعده عبر المعرّف (id).

$ precc predict --record 42 6300
Recorded actual=6300 tokens for prediction id=42.

تدريب trained-v1

بمجرد أن يصبح لديك عشرة تنبؤات مغلقة على الأقل، طبّق انحدار ridge المسمى trained-v1 على log10(actual) مقابل log10(طول الوصف) مع متغير وهمي one-hot للفئة. التطابق مغلق الشكل (Cholesky على المعادلات الطبيعية مع ridge λ=1) ويعمل في أجزاء من الثانية.

$ precc predict --train
Trained trained-v1 on 22 closed predictions (λ=1).
  Model file : ~/.local/share/precc/predict_model.json
  Confidence : 0.50
  Intercept  :  +1.0016
  log_desc   :  +1.2339
  Categories :
    unknown       +0.4811
    doc           +0.4474
    measurement   +0.3422
    test          +0.1071
    refactor      +0.0326
    feat          +0.0071
    fix           -0.1096
    chore         -0.3063

بعد التدريب، يستخدم كل استدعاء جديد precc predict نموذج trained-v1 تلقائيًا إلى أن تحذف ملف النموذج أو تستبدله. تحتفظ التنبؤات القديمة بقيمة model_version الأصلية، حتى تتمكن من مقارنة المتنبئين عبر الزمن.

فحص دقة المتنبئ

يُبلغ precc predict --eval عن متوسط الخطأ النسبي المطلق (MAPE) إجمالًا ولكل فئة، محسوبًا فقط على التنبؤات المغلقة (الصفوف التي تحتوي على القيمتين المتوقعة والفعلية).

$ precc predict --eval
Predictions logged   : 30
With actuals (closed): 22
Mean predicted       :     1483 tokens
Mean actual          :    47238 tokens
MAPE (statistical)   :     76.4%

By category:
  category        n   predicted      actual    MAPE
  feat            6        4605        5250   26.2%
  unknown         4        1597       30526   52.6%
  test            4         924       38900   56.4%
  ...

سرد التنبؤات الأخيرة

يعرض precc predict --list الصفوف الأخيرة بترتيب زمني عكسي. الصفوف المفتوحة (بدون قيمة فعلية) جاهزة للإغلاق.

$ precc predict --list --limit 5
id    ts                   category       predicted     actual  conf description
30    2026-05-09 09:40:51  feat                5348          -  0.50 Run the synthetic-fleet pilot...
29    2026-05-09 08:56:48  test                1050          -  0.60 Train predictor: trained-v1...
28    2026-05-09 07:44:18  test                 915     150000  0.60 Implement minimal task-12...

لماذا الرموز وليس الوقت الفعلي

تقديرات الوقت غير قابلة للقياس بأثر رجعي ولا تتراكم عبر الأجهزة أو الجلسات. أعداد الرموز حتمية وقابلة للمقارنة وتُنمّي مجموعة بيانات موسومة تُحسّن المتنبئ مع كل حلقة مغلقة. الهدف من العرّافة هو تحويل التقدير من لعبة تخمين إلى قياس.

مكان تخزين البيانات

تُخزَّن جميع بيانات التنبؤ محليًا على جهازك. لا يُرفع أي شيء.

~/.local/share/precc/
├── metrics.db                — predictions table (oracle DB)
└── predict_model.json        — trained-v1 coefficients (after `--train`)