💬 NLP

CodeScout: Contextual Problem Statement Enhancement for Software Agents

تقدم الورقة البحثية CodeScout، وهو إطار عمل يعزز أداء وكلاء البرمجيات من خلال إجراء استكشاف مسبق خفيف الوزن لقواعد الأكواد لتحويل طلبات المستخدمين غير المحددة بدقة إلى بيانات مشكلات شاملة وقابلة للتنفيذ، مما أدى إلى تحسن بنسبة 20% في معدلات الحل في اختبار SWEBench-Verified.

المؤلفون الأصليون: Manan Suri, Xiangci Li, Mehdi Shojaie, Songyang Han, Chao-Chun Hsu, Shweta Garg, Aniket Anand Deshmukh, Varun Kumar

نُشر 2026-03-09

📖 3 دقيقة قراءة☕ قراءة في استراحة قهوة

CC BY 4.0

المؤلفون الأصليون: Manan Suri, Xiangci Li, Mehdi Shojaie, Songyang Han, Chao-Chun Hsu, Shweta Garg, Aniket Anand Deshmukh, Varun Kumar

البحث الأصلي مرخَّص بموجب CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ هذا شرح مولَّده بالذكاء الاصطناعي للبحث أدناه. لم يكتبه المؤلفون ولم يصادقوا عليه. وللتحقق من الدقة التقنية، يرجى الرجوع إلى البحث الأصلي. اقرأ إخلاء المسؤولية الكامل

تخيل أنك تحاول توظيف مساعد آلي (روبوت) ذكي للغاية ولكنه حرفي التفكير جداً لإصلاح آلة معطلة في مصنعك.

المشكلة: الملحوظة الغامضة

كتبت ملحوظة صغيرة للروبوت: "الآلة تصدر ضجيجاً غريباً. أصلحها."

سلمت هذه الملحوظة للروبوت. ولأن الروبوت ذكي ولكنه يفتقر إلى السياق، بدأ يشعر بالذعر. فهو لا يعرف أي آلة، ولا نوع الضجيج، ولا أين يبحث. لذا، قام الروبوت بما يلي:

ركض في أرجاء المصنع بأكمله لفحص كل آلة (الإفراط في الاستكشاف).
حاول شد برغي، فشل، ثم شدّه مرة أخرى، ومرة أخرى (محاولات متكررة وعنيدة).
في النهاية استسلم أو كسر شيئاً آخر لأنه لم يفهم أبداً السبب الجذري.

في عالم البرمجيات، هذا هو بالضبط ما يحدث عندما يطلب المطورون من وكلاء برمجة الذكاء الاصطناعي إصلاح الأخطاء (bugs) باستخدام أوصاف قصيرة وغامضة. حيث يتوه الذكاء الاصطناعي، ويضيع الوقت، وغالباً ما يفشل.

الحل: CodeScout (المحقق "ما قبل الطيران")

قدم مؤلفو هذه الورقة البحثية CodeScvoid. فكر في CodeScout ليس كميكانيكي يصلح الآلة، بل كمحقق ذكي للغاية يصل قبل الميكانيكي.

إليك كيف يعمل CodeScout، باستخدام تشبيه بسيط:

1. فحص "ما قبل الطيران" (تحديد نطاق السياق)

قبل أن يلمس ميكانيكي الروبوت مسماراً واحداً، يقوم CodeScout بفحص مخططات المصنع (قاعدة الكود/codebase). هو لا يكتفي بقراءة الملحوظة فحسب؛ بل يستقصي عن الآلة.

الطريقة القديمة: الميكانيكي يخمن من أين يأتي الضجيج.
طريقة CodeScout: يقول CodeScout: "لقد فحصت المخططات. الضجيج يأتي بالتأكيد من ترس 'التوثيق' (Authentication) في محرك 'تسجيل الدخول' (Login). هناك مسمار أمان مفقود."

2. "الدليل المُعزز" (صياغة بيان المشكلة)

يأخذ CodeScout ملحوقتك الغامضة ويعيد كتابتها على شكل دليل تعليمات شامل وخطوة بخوة.

الملحوظة الأصلية: "أصلح الضجيج."
ملحوظة CodeScout الجديدة: "مسمار الأمان في محرك 'تسجيل الدخول' مفقود. هذا يتسبب في تجاهل حقل 'اسم المستخدم' لقاعدة 'الحد الأقصى للطول'.
- الخطوة 1: انظر إلى الملف forms.py السطر 200.
- الخطوة 2: سترى أن المسمار مفقود.
- الخطوة 3: أضف هذا الكود المحدد هنا.
- الخطوة 4: اختبر ذلك عن طريق كتابة اسم مستخدم طويل."

3. النتيجة: ميكانيكي سعيد

الآن، عندما يحصل ميكانيكي الروبوت (وكيل الذكاء الاصطناعي) على هذه الملحوظة الجديدة والمفصلة، فإنه لا يحتاج للتخمين. هو يعرف بالضبط أين يذهب وماذا يفعل.

بدون CodeScout: يستغرق الروبوت 21 خطوة، ويصاب بالارتباك، ويفشل.
مع CodeScout: يستغرق الروبوت 6 خطوات، ويصلح الخطأ، ويعود إلى منزله مبكراً.

لماذا هذا مهم (السر الخفي)

تسلط الورقة البحثية الضوء على بعض الرؤى الرئيسية:

الأمر لا يتعلق بجعل الروبوت أكثر ذكاءً؛ بل بإعطائه تعليمات أفضل. أنت لست بحاجة إلى ذكاء اصطناعي أغلى أو أقوى لإصلاح الأخطاء. أنت فقط بحاجة إلى قضاء القليل من الوقت أولاً لشرح المشكلة بوضوح.
إنه يعمل مع أي روبوت. CodeScout يشبه المترجم العالمي. يمكنه أخذ طلب غامض وتحويله إلى دليل تعليمات مثالي لأي أداة برمجة ذكاء اصطناعي، سواء كان روبوتاً صغيراً ورخيصاً أو روبوتاً ضخماً وباهظ الثمن.
خدعة "العقل الصغير، والعقل الكبير": وجدت الورقة أنه يمكنك استخدام ذكاء اصطناعي أصغر وأرخص (المحقق) لكتابة التعليمات، ثم استخدام ذكاء اصطناعي أكبر وأقوى (الميكانيكي) للقيام بالإصلاح. هذا يوفر المال والوقت مع تحقيق نتائج أفضل.

الخلاصة

في الماضي، كنا نعتقد أن الطريقة الوحيدة للحصول على نتائج برمجة أفضل هي بناء نماذج ذكاء اصطناعي أكبر وأذكى. تقول هذه الورقة: "انتظر، توقف! المشكلة ليست في عقل الذكاء الاصطناعي؛ بل في سؤال المستخدم."

من خلال إضافة "مرحلة المحقق" (CodeScout) التي تستقصي الكود وتوضح المشكلة قبل أن يحاول الذكاء الاصطناعي الإصلاح، يمكننا حل 20% أكثر من الأخطاء بنفس القدر من قوة الحوسبة. إنه الفرق بين الصراخ "أصلحه!" في وجه متدرب مرتبك، وبين تسليمه خريطة مفصلة وملونة توضح الموقع الدقيق للجزء المكسور.

إليك ملخص تقني مفصل لورقة البحث بعنوان "CodeScout: تعزيز بيان المشكلة سياقيًا للوكلاء البرمجيين."

1. بيان المشكلة

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

تحدد الورقة نمطي فشل أساسيين للوكلاء الذين يعملون على مثل هذه المدخلات:

الإفراط في الاستكشاف (Over-exploration): يضيع الوكلاء في قاعدة الكود (codebase) بسبب حمل السياق الزائد، ويفشلون في الوصول إلى السبب الجذري.
التكرار العنيد (Stubborn Repetition): يكرر الوكلاء تطبيق نفس الإصلاح أو استكشاف نفس المناطق دون اختبار أو تطور مناسب، مما يؤدي إلى مسارات غير متقاربة نحو الحل.

يظهر التحليل التجريبي أن تقارير الأخطاء القابلة للحل تمتلك درجات جودة وصف أعلى بكثير من التقارير غير القابلة للحل. العائق الأساسي هو جودة المدخلات، وليس قدرة النموذج. تعتمد الوكلاء الحالية على الاستكشاف التفاعلي (حلقات التنفيذ والملاحظة خطوة بخطوة) بدلاً من التخطيط الاستراتيجي طويل المدى، مما يتسبب في تراكم الانحرافات عن نطاق المشكلة الحقيقي.

2. المنهجية: CodeScout

قدم المؤلفون CodeScout، وهو إطار عمل لتنقية الاستعلام السياقي يعمل كخطوة معالجة مسبقة قبل تنفيذ الوكيل. يقوم بتحويل طلبات المستخدم الغامضة إلى بيانات مشكلة شاملة وقابلة للتنفيذ من خلال مسار ثلاثي المراحل يقوم بـ "استكشاف مسبق" لقاعدة الكود المستهدفة.

من الأهمية بمكان أن CodeScout هو نظام قابل للتركيب والتشغيل (plug-and-play)؛ فهو لا يتطلب أي تعديلات على هياكل الوكيل الأساسية أو حلقات الاستنتاج.

المسار ثلاثي المراحل:

بناء مخطط معرفة المستودع (Repository Knowledge Graph Construction):
- يقوم النظام بتحليل قاعدة الكود لبناء رسم بياني موجه $G(R)$ يمثل كيانات الكود (الأصناف/Classes، الدوال/Functions، المتغيرات/Variables) وعلاقاتها الدلالية (الوراثة، الاستيراد، التبعيات).
- يوفر هذا رؤية هيكلية هرمية للمستودع، مما يتيح البحث الفعال دون الحاجة لمسح كامل الكود المصدري فورًا.
تحديد نطاق السياق عالي المستوى (High-Level Context Scoping):
- يقوم وكيل يعتمد على نموذج لغوي كبير (LLM) بتحليل بيان المشكلة الأصلي ( $P_0$ ) مقابل رسم معرفة المستودع $G(R)$ .
- يحدد مجموعة مقيدة من أهداف الاستكشاف ( $T$ ، عادةً $\le 15$ كيانًا) الأكثر احتمالًا لارتباطها بالمشكلة.
- تعمل هذه المرحلة على تصفية قاعدة الكود الشاسعة إلى ملفات وأصناف ودوال محددة، مما يمنع الوكيل من الشعور بالإرهاق المعلوماتي.
تحليل السياق دقيق التفاصيل وتوليف المشكلة (Fine-Grained Context Analysis & Problem Synthesis):
- التحليل: لكل هدف في $T$ ، يسترجع النظام الكود ويجري تحليلًا مهيكلًا لاستخراج الرؤى: تقييم الدور، تلميحات موقع الإصلاح، الأنماط التقنية، والفرضيات البديلة.
- التصفية: يتم تخصيص درجة صلة لكل رؤية؛ حيث تُستبعد الرؤى منخفضة الصلة لتقليل الضجيج.
- التوليف: يتم دمج بيان المشكلة الأصلي مع الرؤى المصفاة لتوليد بيان مشكلة مُعزز ( $P_{aug}$ ). يتضمن هذا البيان الجديد:
  - أوصافًا محسنة للمشكلة مع الآليات التقنية.
    ical.
  - خطوات إعادة إنتاج مفصلة مع أنماط الخطأ الداخلية.
  - تلميحات الاستكشاف (Exploration Hints): ملفات وأصناف ومناطق اهتمام محددة للفحص.
  - تلميحات الإصلاح (Fix Hints): مواقع عالية الثقة للرقع البرمجية (patches) واقتراحات التنفيذ.

3. المساهمات الرئيسية

إطار عمل CodeScout: نهج منهجي لتعزيز جودة المدخلات من خلال التحليل المدرك للمستودع، مما يثبت أن الاستكشاف المسبق المهيكل يمكن أن يكمل قدرات الوكيل دون تغييرات في البمارة (architecture).
التحقق التجريبي: تقييم واسع النطاق على معيار SWEBench-Verified عبر ثلاثة هياكل مختلفة للوكلاء (SWE-Agent، OpenHands، Mini-SWE-Agent) وثلاث عائلات من النماذج اللغوية الكبيرة (DeepSeek R1، GPT-5-mini، Qwen3 Coder).
رؤى التوليف المتبادل: تكشف الورقة أن النماذج الأقوى يمكنها تعزيز بيانات المشكلة لرفع كفاءة الوكلاء الأضعف. فالنموذج الأرخص والأكثر قدرة يمكنه حساب التعزيزات مسبقًا لتحسين أداء الوكيل التشغيلي الأضعف بشكل كبير، مما يوفر استراتيجية نشر فعالة من حيث التكلفة.
التحليل السلوكي: تحليل مفصل يوضح أن CodeScout يقلل من المسارات غير المتقاربة، وينقل الوكلاء من الاستكشاف التفاعلي إلى التحقيق المستهدف، ويحسن دقة التحديد الموضعي (localization accuracy) (العثور على الملفات/الدوال الصحيحة).

4. النتائج

أظهر التقييم على SWEBench-Verified تحسينات كبيرة:

معدلات الحل: حقق CodeScout تحسنًا بنسبة 20% في معدلات الحل مقارنة بالخط المرجعي الافتراضي.
المكاسب المطلقة: تم حل ما يصل إلى 27 مشكلة إضافية عبر المعيار.
دراسات الاستبعاد (Ablation Studies):
- المسار الكامل مقابل التعزيز الذاتي: عندما طُلب من الوكلاء القيام بالتعزيز الذاتي أثناء التنفيذ، انخفض الأداء بشكل كبير. وهذا يثبت أن مرحلة الاستكشاف المسبق المنظمة والمنفصلة تتفوق على التصحيح الذاتي التفاعلي.
- نطاق LLM مقابل الاسترجاع: تفوق تحديد النطاق المدفوع بالنماذج اللغوية على الاسترجاع المعجمي التقليدي (BM25)، مما يثبت ضرورة الفهم الدلالي لاختيار الأهداف.
- التصفية: كانت تصفية الصلة أمرًا حاسمًا؛ حيث أدى حذفها إلى تقليل المكاسب، مما يسلط الضوء على الحاجة لتجنب إضافة سياق مليء بالضجيج.
كفاءة التكلفة: رغم أن التعزيز يضيف عبئًا (استدعاءات LLM ورموز/tokens)، إلا أن مقياس الرموز لكل مشكلة محلولة (tokens-per-resolved-issue) تحسن لمعظم النماذج. يتم استيعاب هذا العبء من خلال تقليل عدد الخطوات المطلوبة لحل الخطأ.
تغييرات المسار: استخدم الوكلاء الذين يستخدمون CodeScout استدعاءات استكشاف واسعة أقل (مثل find) واستدعاءات أكثر استهدافًا (مثل view و grep) في وقت مبكر من المسار، مما أدى إلى تقارب أسرع.

5. الأهمية

تجادل الورقة بأن الصياغة المنهجية للمشكلة هي شرط مسبق للاعتماد الموثوق للبرمجة المدعومة بالذكاء الاصطناعي.

تحول في النموذج المعرفي: تتحدى الورقة فكرة وجوب قيام الوكلاء بـ "القفز" مباشرة نحو الحل. بدلًا من ذلك، يجب على الوكلاء أولًا "النظر" وبناء فهم شامل لسياق قاعدة الكود.
الفصل (Decoupling): من خلال فصل مرحلة "الفهم" عن مرحلة "التنفيذ"، يسمح CodeScout للمطورين بترقية أداء الوكيل ببساطة عن طريق تحسين سياق المدخلات، دون الحاجة لإعادة تدريب النماذج أو إعادة كتابة حلقات الوكيل.
الاتجاه المستقبلي: تشير النتائج إلى أن الاستثمار في الحوسبة من أجل الفهم المسبق للمشكلة هو مكمل قوي للتقدم في قدرة النماذج، مما يشير نحو مساعدة برمجية بالذكاء الاصطناعي أكثر موثوقية واستراتيجية وكفاءة.

باختًا، يثبت CodeScout أن التعزيز السياقي هو تدخل عالي التأثير يسد الفجوة بين النوايا البشرية الغامضة والمواصفات الصارمة المطلوبة لنجاح الوكلاء البرمجيين المستقلين.