# Cache Rebuild (إعادة بناء الذاكرة المؤقتة)

## الخلفية

تقوم آلية prompt caching من Anthropic بتجميع system → tools → messages (حتى نقطة توقف الذاكرة المؤقتة) بالترتيب كمفتاح للذاكرة المؤقتة. عندما يتطابق مفتاح الذاكرة المؤقتة تماماً مع الطلب السابق، تُرجع الـ API قيمة `cache_read_input_tokens` (إصابة الذاكرة المؤقتة)؛ وعندما يتغير المفتاح، تُعيد الـ API إنشاء الذاكرة المؤقتة وتُرجع كمية كبيرة من `cache_creation_input_tokens`، أي إعادة بناء الذاكرة المؤقتة.

إعادة بناء الذاكرة المؤقتة تعني رسوم tokens إضافية (سعر cache creation أعلى من cache read)، لذا فإن تحديد سبب إعادة البناء له قيمة مباشرة في تحسين التكاليف.

## تصنيف أسباب إعادة بناء الذاكرة المؤقتة

يحدد cc-viewer بدقة سبب إعادة بناء الذاكرة المؤقتة من خلال مقارنة body طلبي MainAgent المتتاليين:

| reason | المعنى | طريقة التحديد |
|--------|--------|---------------|
| `ttl` | انتهاء صلاحية الذاكرة المؤقتة | مرور أكثر من 5 دقائق منذ آخر طلب MainAgent |
| `system_change` | تغيير system prompt | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
| `tools_change` | تغيير تعريفات الأدوات | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
| `model_change` | تبديل النموذج | `prev.model !== curr.model` |
| `msg_truncated` | اقتطاع مكدس الرسائل | عدد رسائل الطلب الحالي أقل من السابق، عادة بسبب تجاوز نافذة السياق |
| `msg_modified` | تعديل الرسائل التاريخية | عدم تطابق محتوى الرسائل السابقة (في الإلحاق العادي يجب أن تكون البادئة متطابقة تماماً) |
| `key_change` | تغيير مفتاح غير معروف | احتياطي عندما لا تتطابق أي من الشروط أعلاه |

## أولوية التحديد

1. فحص الفاصل الزمني أولاً — إذا تجاوز 5 دقائق يُحدد مباشرة كـ `ttl` دون مقارنة body
2. ثم فحص model وsystem وtools وmessages بالترتيب
3. قد يتطابق طلب واحد مع أسباب متعددة (مثل تبديل النموذج + تغيير system prompt)، وفي هذه الحالة تحتوي مصفوفة `reasons` على جميع العناصر المتطابقة ويُعرض tooltip بأسطر متعددة

## السيناريوهات الشائعة

- **`ttl`**: توقف المستخدم عن العمل لأكثر من 5 دقائق ثم استأنف، وانتهت صلاحية الذاكرة المؤقتة طبيعياً
- **`system_change`**: قام Claude Code بتحديث system prompt (مثل تحميل CLAUDE.md جديد أو تغيير تعليمات المشروع)
- **`tools_change`**: اتصال/انقطاع خادم MCP أدى إلى تغيير قائمة الأدوات المتاحة
- **`model_change`**: قام المستخدم بتبديل النموذج عبر أمر `/model`
- **`msg_truncated`**: محادثة طويلة أدت إلى تفعيل إدارة نافذة السياق، وقام Claude Code باقتطاع الرسائل المبكرة
- **`msg_modified`**: قام Claude Code بتعديل الرسائل التاريخية (مثل استبدال `/compact` للملخص المضغوط بالرسائل الأصلية)
