ضبط سياق أدوات وكيل
يتناول هذا الدليل ما تفعله على السطح ذي الطبقتين: ترى ما يرسله التشغيل، وتغيّره، وتشخّص وكيلًا مدّ يده إلى الأداة الخطأ. لمعرفة لماذا يعمل هكذا، اقرأ سياق الأدوات وتخزين المطالبات مؤقتًا.
اطّلع على ما يرسله التشغيل فعلًا
قسم بعنوان “اطّلع على ما يرسله التشغيل فعلًا”افتح محادثة واضغط مؤشر استخدام السياق في ترويسة المحادثة. يعيد بناء السطح عينه الذي كان الإرسال التالي سيرسله، من غير أن يُطلق تشغيلًا. عرض المزيد (أو الأمر /context) يفتح السياق كاملًا، فتفحص فيه كل أداة.
قسمان يهمان هنا:
- تعريفات الأدوات وأدوات MCP والأدوات الديناميكية — المجموعة المقيمة، مع كلفة الرموز الحقيقية لكل أداة.
- أدوات تُحمَّل عند الطلب — فهرس المؤجَّل. لا يُحتسب لكل مدخل إلا اسمه، فالاسم كل ما يحمله الطلب، وفتح أحدها يظل يعرض الوصف والمخطط كاملين، فترى ما كانت ستكلّفه لو جلبها التشغيل.
إن خلا قسم المؤجَّل، فالتأجيل مطفأ على هذا الخادم. راجع --tool-deferral في واجهة سطر أوامر cc_server.
غيّر الأدوات التي تُحمَّل مقدمًا
قسم بعنوان “غيّر الأدوات التي تُحمَّل مقدمًا”المجموعة المقيمة سياسة لا إعداد — موضعها ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) وتنطبق على كل تشغيل:
residentBuiltins— مفردات الملفات والصدفة.residentDiscovery—search_toolsوlist_my_tools. لا تحذفهما، فبهما يبلغ الوكيل كل ما عداهما.residentMcpTools— حفنة من أدوات Control Center يستحق دفع مخططها في كل طلب.- كتلة لكل وضع، للأدوات التي يستخدمها وضع معيّن في جلّ الجولات.
قاعدتان عند تحريرها:
أضف أداة فقط حين تستخدمها معظم التشغيلات. كل اسم يدفع كلفة مخططه في كل طلب من كل تشغيل، دائمًا. الأداة المهمة حين تُستدعى والنادرة في المجمل مكانها النصف المؤجَّل، وسيجدها الوكيل.
استخدم اسم الأداة الحقيقي. الاسم المقيم الذي لا يطابق أي أداة خامل: لا خطأ ولا تحذير، وتُؤجَّل الأداة فحسب. test/tooling/resident_tool_names_test.dart يلتقط ذلك، ويبقي كل وضع دون 40 أداة مقيمة، وهو المقصود من التمرين — بعد هذا النطاق يتدهور اختيار الأدوات بما يظهر في القياس.
تُضاف أفعال الوضع المطلوبة والمثبَّتة تلقائيًا، فلا حاجة إلى إدراج فعل الإخراج الخاص بالوضع.
شخّص اختيار الأداة الخاطئ
قسم بعنوان “شخّص اختيار الأداة الخاطئ”حين يستخدم الوكيل الأداة الخطأ، أو يدّعي أنه لا يستطيع فعل شيء، تبيّن أي الحالات الثلاث وقعت.
1. هل نظر؟
قسم بعنوان “1. هل نظر؟”يسجّل كل تشغيل الأدوات المؤجَّلة التي حمّلها، وما أطلق التحميل: استدعاء مباشر بالاسم، أو استعلام search_tools. افتح تيار أحداث التشغيل (الإعدادات ← مساحة العمل ← الوكلاء ← الوكيل ← السجلات ← عرض) وابحث عن [harness] loaded N deferred tool(s).
- لا شيء في السجل، وقال الوكيل إن القدرة مفقودة — لم ينظر. هذه مشكلة في المطالبة لا في الاسترجاع: فهرس المؤجَّل في موجّه نظامه، ومعه تعليمة ألا يُعلن أن قدرة مفقودة قبل أن يرجع البحث فارغًا.
- سُجّل بحث ولم يُحمَّل شيء — إخفاق استرجاع حقيقي. انتقل إلى الخطوة 2.
- حُمّلت أدوات واستُخدمت الأداة الخطأ — ما وجده متشابه أكثر مما ينبغي. انتقل إلى الخطوة 3.
2. أصلح إخفاق الاسترجاع
قسم بعنوان “2. أصلح إخفاق الاسترجاع”يطابق search_tools الأسماء والأوصاف وأسماء الوسائط. والإخفاق يعني في الأغلب أن الوصف يخلو من الكلمات التي استخدمها الوكيل.
أضفها. الأوصاف هي فهرس الاسترجاع، فـأطلها بدل اختصارها — اكتب المفردات التي يكتبها المشغّل فعلًا («أسند»، «فوّض»، «سلّم»)، لا الاسم الداخلي وحده. اختصار الوصف توفيرًا للرموز يخسرك إصابة البحث ودقة الاختيار معًا، ووفره إلى جوار المخطط لا يُذكر.
إن وُجدت الأداة الصحيحة وجاء ترتيبها متأخرًا، فهذا ما وُضع له وسيط limit، ووصف الأداة نفسه يأمر الوكيل بتوسيع بحث يبدو قريبًا ويخطئ.
3. أصلح الأدوات المتشابهة
قسم بعنوان “3. أصلح الأدوات المتشابهة”إن بدا الوصفان متماثلين لمن لا يعرف الفرق سلفًا، فالنموذج يخمّن. ادمجهما في أداة واحدة بوسيط مميّز.
تسير ticket_relation وticket_pr_link على هذا النمط: كل منهما تربط وتفك الربط بوسيط مميّز. الاختيار الذي يُحسم داخل استدعاء واحد، وسياق الطلب كاملًا أمامه، أوثق من الاختيار بين وصفين متشابهين.
أبقِ الأدوات منفصلة حين تقتضي بوابة موافقة مختلفة، أو تدقيقًا مختلفًا، أو عرضًا مختلفًا في الواجهة، فالدمج عندها يكلّفك شيئًا حقيقيًا.
تحقق أن تخزين المطالبات مؤقتًا يعمل
قسم بعنوان “تحقق أن تخزين المطالبات مؤقتًا يعمل”يظهر معدّل إصابة الذاكرة المؤقتة في قابلية الملاحظة ← الرؤى باسم معدل الذاكرة المؤقتة. المحادثة الطويلة السليمة يبقى معدّلها مرتفعًا، وإن دام منخفضًا فشيء يعيد كتابة البادئة في كل جولة.
الأسباب الشائعة، بحسب الأرجحية:
- أي شيء غير حتمي في صدر المطالبة. طابع زمني، أو معرّف طلب، أو مجموعة تُجتاز بترتيب يتغيّر، يكفي لذلك.
- تغيير النموذج أو جهد الاستدلال في منتصف المحادثة. كلاهما يغيّر البادئة. والوكلاء الفرعيون أسهل موضع يُخطَأ فيه هنا: تشغيل الأبناء بجهد أدنى توفيرًا للمال قد يضيّع من الاشتراك في الذاكرة المؤقتة أكثر مما يوفّر.
- ضغط متكرر. الضغط يعيد كتابة السجل بتصميمه، فكلفنه حقيقية، والعلاج أن تضغط نادرًا وعمقًا لا كثيرًا وسطحًا.
إيقاف التأجيل بـ --tool-deferral=off اختبار A/B صالح لعزل ما إذا صدر تغيّر السلوك عن السطح ذي الطبقتين. يعيد الطلب كما كان قبل التأجيل حرفيًا، فإن بقي السلوك على حاله والتأجيل مطفأ فالسطح ليس السبب.