# لماذا تُدرج الأدوات أولاً؟

في لوحة السياق بـ cc-viewer، **تظهر Tools قبل System Prompt والMessages**. يعكس هذا الترتيب بدقة **تسلسل بادئة KV-Cache في Anthropic API**.

## تسلسل بادئة KV-Cache

عندما تبني Anthropic API الـ KV-Cache، تقوم بتسلسل السياق في بادئة وفق هذا **الترتيب الثابت**:

```
┌─────────────────────────────────────────────────┐
│ 1. Tools (JSON Schema definitions)               │  ← Start of cache prefix
│ 2. System Prompt                                 │
│ 3. Messages (conversation history + current turn)│  ← End of cache prefix
└─────────────────────────────────────────────────┘
```

هذا يعني أن **Tools تأتي قبل System Prompt في بداية بادئة الـ cache تماماً**.

## لماذا تمتلك Tools وزناً أعلى في الـ Cache من System؟

في مطابقة بادئة KV-Cache، **المحتوى الأسبق أكثر أهمية** — أي تغيير يُبطل كل ما يليه:

1. **مطابقة البادئة تبدأ من البداية**: يقارن KV-Cache الطلب الحالي بالبادئة المخزنة token بـ token من البداية. فور اكتشاف عدم تطابق، يُبطَل كل المحتوى اللاحق.

2. **تغيير Tools = إبطال كامل للـ cache**: بما أن Tools تأتي أولاً، فأي تغيير في تعريفات الأدوات (حتى إضافة أو حذف MCP tool واحدة) **يكسر البادئة من البداية تماماً**، مما يُبطل كل الـ System Prompt والMessages المخزنة.

3. **تغيير System = إبطال cache الـ Messages**: يقع System Prompt في المنتصف، لذا تؤثر تغييراته فقط على جزء الـ Messages الذي يليه.

4. **تغيير Messages = يؤثر فقط على الذيل**: Messages تأتي في النهاية، لذا إضافة رسائل جديدة تُبطل فقط جزءاً صغيراً في النهاية — يبقى cache الـ Tools والـ System سليماً.

## التأثير العملي

| نوع التغيير | تأثير الـ Cache | السيناريو النموذجي |
|-------------|----------------|---------------------|
| إضافة/حذف Tool | **إبطال كامل** | اتصال/انقطاع MCP server، تفعيل/تعطيل إضافة IDE |
| تغيير System Prompt | فقدان cache الـ Messages | تعديل CLAUDE.md، حقن system reminder |
| إضافة رسالة جديدة | زيادة طرفية فقط | تدفق المحادثة الطبيعي (الأكثر شيوعاً، الأقل تكلفة) |

لهذا السبب يُعد `tools_change` في [CacheRebuild](CacheRebuild.md) أغلى أسباب إعادة البناء في الغالب — لأنه يكسر سلسلة البادئة من الأمام تماماً.

## لماذا توضع تعريفات الأدوات قبل "الدماغ"؟

من منظور التخزين المؤقت، وجود Tools في المقدمة هو حقيقة تقنية. لكن من منظور التصميم المعرفي، هذا الترتيب منطقي بنفس القدر — **الأدوات هي اليدان والقدمان، وSystem Prompt هو الدماغ**.

قبل التصرف، يحتاج الشخص إلى إدراك الأطراف والأدوات المتاحة له. الرضيع لا يفهم أولاً قواعد العالم (System) ثم يتعلم الإمساك — بل يدرك أولاً أن لديه يدين وقدمين، ثم يفهم القواعد تدريجياً من خلال التفاعل مع البيئة. وبالمثل، يحتاج نموذج LLM إلى معرفة الأدوات التي يمكنه استدعاؤها (قراءة الملفات، كتابة الكود، البحث، تنفيذ الأوامر) قبل تلقي تعليمات المهمة (System Prompt)، ليتمكن من تقييم "ماذا يمكنني أن أفعل" و"كيف يجب أن أفعل ذلك" بدقة عند معالجة التعليمات.

لو كان الترتيب معكوساً — إخبار النموذج أولاً "مهمتك إعادة هيكلة هذه الوحدة"، ثم إخباره "لديك أدوات Read وEdit وBash" — سيفتقر النموذج إلى معلومات حاسمة عن حدود قدراته عند فهم المهمة، مما قد ينتج خططاً غير واقعية أو يتجاهل أساليب متاحة.

**اعرف أوراقك قبل أن تقرر كيف تلعبها.** هذا هو المنطق المعرفي وراء وضع Tools قبل System.

## لماذا توجد أدوات MCP أيضاً في هذا الموضع؟

أدوات MCP (Model Context Protocol)، مثل الأدوات المدمجة، توضع في بداية منطقة Tools. فهم موقع MCP في السياق يساعد في تقييم فوائده وتكاليفه الحقيقية.

### مزايا MCP

- **توسيع القدرات**: يتيح MCP للنماذج الوصول إلى خدمات خارجية (استعلامات قواعد البيانات، استدعاءات API، عمليات IDE، التحكم بالمتصفح، إلخ)، متجاوزاً حدود الأدوات المدمجة
- **نظام بيئي مفتوح**: يمكن لأي شخص تنفيذ خادم MCP؛ يكتسب النموذج قدرات جديدة دون إعادة التدريب
- **التحميل عند الطلب**: يمكن توصيل/فصل خوادم MCP بشكل انتقائي حسب السيناريو، مع تركيب مرن لمجموعات الأدوات

### تكاليف MCP

- **قاتل التخزين المؤقت**: يتم ربط تعريف JSON Schema لكل أداة MCP في بداية بادئة KV-Cache. إضافة أو إزالة أداة MCP واحدة = **إبطال التخزين المؤقت بالكامل من البداية**. التوصيل/الفصل المتكرر لخوادم MCP يقلل بشكل كبير من معدل إصابة التخزين المؤقت
- **تضخم البادئة**: مخططات أدوات MCP عادة أكبر من الأدوات المدمجة (أوصاف مفصلة للمعاملات، قيم تعداد، إلخ). العديد من أدوات MCP يزيد بشكل ملحوظ عدد الرموز في منطقة Tools، مما يقلص مساحة السياق المتاحة للرسائل
- **عبء التأخير**: تتطلب استدعاءات أدوات MCP اتصالاً بين العمليات (JSON-RPC عبر stdio/SSE)، وهو أبطأ بمرتبة من استدعاءات الدوال المدمجة
- **مخاطر الاستقرار**: خوادم MCP هي عمليات خارجية قد تتعطل أو تنتهي مهلتها أو تعيد تنسيقات غير متوقعة، مما يتطلب معالجة أخطاء إضافية

### توصيات عملية

| السيناريو | التوصية |
|-----------|---------|
| محادثات طويلة، تفاعل متكرر | تقليل عدد أدوات MCP لحماية استقرار بادئة التخزين المؤقت |
| مهام قصيرة، عمليات لمرة واحدة | استخدام أدوات MCP بحرية؛ التأثير على التخزين المؤقت محدود |
| إضافة/إزالة متكررة لخوادم MCP | كل تغيير يؤدي إلى إعادة بناء كاملة للتخزين المؤقت؛ النظر في تثبيت مجموعة الأدوات |
| مخططات أدوات كبيرة الحجم | تقليص الأوصاف والتعدادات لتقليل استهلاك رموز البادئة |

في لوحة Context في cc-viewer، تُعرض أدوات MCP إلى جانب الأدوات المدمجة في منطقة Tools، مما يوفر رؤية واضحة لحجم مخطط كل أداة ومساهمتها في بادئة التخزين المؤقت.
