مدونة Maguyva

السياق الذي يسافر معك

Mon, 07 Sep 2026 00:00:00 GMT

فهرسة Cursor ممتازة داخل Cursor. إكمال التبويب، والتحرير المضمّن، والمحادثة، والوكيل داخل تلك النافذة يعتمدون جميعًا بالفعل على فهرس المشروع الذي يشغّله Cursor لمساحة العمل المفتوحة. إذا كان Cursor هو السطح الوحيد الذي تكتب فيه، وكان ذلك الفهرس يجد الملفات الصحيحة بالفعل، فابقَ هناك. هذه حالة صادقة من ‘ابقَ حيث أنت’، وتستحق أن تكون الجملة الأولى في هذه الصفحة.

هذا المقال يتناول النصف الآخر من الأسبوع المعتاد. نفس المستودع مفتوح أيضًا في Claude Code، ويُستعلم منه عبر Codex CLI، ويُراجَع على جهاز ثانٍ، أو يُستعلم منه بواسطة وكيل يعمل في CI. السؤال ليس ‘أي فهرس أفضل’. السؤال هو ما إذا كانت الخريطة التي يثق بها الوكيل في نافذة واحدة هي نفس الخريطة التي سيثق بها في النافذة التالية.

Maguyva هي تلك الخريطة التي تسافر معك. إنها طبقة سياق قاعدة كود MCP عن بُعد. يستعلمها الوكيل بنفس الطريقة التي يستعلم بها أي أداة MCP أخرى. تعود النتائج كمسارات مقتبسة مع أرقام الأسطر. يظل Cursor هو المحرر. السياق هو ما يتحرك.

لماذا وُجدت فهرسة Cursor

توجد الفهرسة المدمجة في Cursor حتى تتمكن المحادثة والوكلاء والبحث داخل المحرر من جلب الكود ذي الصلة بدلًا من الاعتماد فقط على ما يناسب نافذة السياق الخام للنموذج. هذا هو التصميم الصحيح لـ IDE. هذا الفهرس أصلي لـ Cursor. إنه ليس خادم MCP ولا يمكن الوصول إليه من عملاء آخرين.

إليك كيف يعمل، كما هو موصوف في وثائق Cursor العامة وشروحات Cursor نفسها وقت كتابة هذا المقال: مسار البحث الأساسي لم يعد فهرس تضمينات سحابي. ذكر فريق Cursor في منتدى مجتمعهم أن البحث الدلالي/القائم على التضمينات المخصص يجري التقليل منه لصالح الاسترجاع القائم على grep، لأن النماذج الحالية أصبحت جيدة بما فيه الكفاية لاستكشاف الشجرة الحية بنفسها. بدلًا من ذلك هناك Instant Grep، وهو فهرس بحث محلي مبني من مقاطع نصية متتالية وقوائم مقلوبة ومرشحات بلوم، مخزّن في جداول بحث مُخطَّطة على الذاكرة، بحيث تُحل الاستعلامات على جهاز المطور نفسه بدلًا من الخادم.

يعيش الفهرس نفسه في دليل .git/cursor/ الخاص بالمستودع نفسه، مُثبَّت على إيداع git محدد؛ التغييرات منذ ذلك الإيداع تُطبَّق فوقه بدلًا من إثارة مسح جديد، ولا يُعاد بناء الفهرس إلا عندما تنحرف الحالة المحلية بشكل كبير عمّا بُني عليه. ولأنه يقع داخل .git، فإنه لا يُتتبَّع أبدًا ولا يُدفَع أبدًا — احذف ذلك المجلد، ويختفي الفهرس. يُحترَم .gitignore في بنائه، لأن المحتوى المُتتبَّع فقط هو المؤهل، ويُطبَّق .cursorignore في مسار القراءة. لم تعد هناك خطوة تضمين من جانب الخادم أو قاعدة بيانات متجهات عن بُعد في ذلك المسار. وصفت الوثائق القديمة تصميمًا بمساعدة السحابة — تشفير القطع، والمزامنة عبر أشجار Merkle، وإعادة استخدام الفهرس بين أعضاء الفريق — وقد قال فريق Cursor نفسه منذ ذلك الحين إن ذلك التصميم يجري التقليل منه، لذا لم يعد هذا المقال يصفه على أنه حالي.

ما يبرز داخل المحرر هو الوكيل الفرعي للاستكشاف Explore الخاص بـ Cursor. يمكنه إطلاق عدة عمليات بحث متوازية في نافذة سياقه الخاصة على نموذج أسرع، وإرجاع النتائج ذات الصلة فقط، حتى لا تنتفخ المحادثة الرئيسية بنتائج البحث. هذه قوة حقيقية داخل المحرر. حافظ عليها.

مساحات العمل متعددة الجذور مدعومة: سياق كل مجلد مفتوح متاح للـ Agent. بعض الميزات المعتمدة على git، مثل أشجار عمل git، مُعطَّلة في إعدادات متعددة الجذور، ولا يدعم Cloud Agents مساحات العمل متعددة الجذور على الإطلاق.

لا شيء من هذا سبب لترك Cursor. إنه وصف دقيق لخريطة جيدة جدًا في المكان الذي تعيش فيه.

ماذا يعني ‘السفر معك’ فعليًا

تسافر الخريطة معك عندما يعيد نفس السؤال نفس نوع الإجابة، مع اقتباسات يمكنك فتحها، من أكثر من عميل واحد.

في Cursor: ‘أين يُعرَّف parseConfig، ومن يستدعيه؟’
في Claude Code، على نفس المستودع: نفس السؤال.
في Codex CLI، على جهاز مراجعة لم يفتح نافذة Cursor قط: نفس السؤال.
في وكيل CI يتحدث MCP: نفس السؤال، مقابل نفس اللقطة المستضافة.

إذا كان كل سطح يبني فهرسه الخاص والمنفصل، فأنت لا تملك خريطة واحدة. لديك عدة ذاكرات مؤقتة تتباعد. قد يكون فهرس المحرر محدّثًا للشجرة الموجودة على القرص. قد تتأخر جلسة CLI بيوم واحد. قد ترى مهمة CI نسخة مسحوبة مختلفة من الشيفرة. وسيظل الوكيل يبدو واثقًا مع ذلك.

لم تُصمَّم فهرسة Cursor لحل ذلك. ولأنها تعيش داخل المحرر، فإن السياق الذي تبنيه مخصص لذلك المحرر. القراء الذين يحتاجون أيضًا إلى CLI أو خط أنابيب CI أو محرر مختلف يحتاجون إلى أداة منفصلة لتلك الأسطح. هذه حقيقة نطاق، وليست عيبًا. Maguyva هي تلك الأداة المنفصلة.

عدد اللغات المنشور لفهرسة Cursor غير مذكور في المحتوى القابل للاستخدام لهذا المقال. تنشر Maguyva دعمًا لأكثر من 279 لغة وتقنية قائمة على النص. لا يُكرَّر تسعير Cursor هنا أيضًا؛ راجع صفحة تسعيرهم. تفرض Maguyva رسومًا لكل مساحة عمل، وليس لكل مقعد، بخطط منشورة عند $0 و$19 و$49 و$149 حسب التغطية المفهرسة وحجم مساحة العمل.

خريطة مستضافة واحدة، لكل عميل MCP

Maguyva هي خادم MCP عن بُعد. تربط GitHub، وتختار مستودعًا، ويبني خط الأنابيب السحابي الرموز، وحواف الرسم البياني، والخريطة المقتبسة. تضيف مفتاح API إلى تكوين MCP للعميل الذي تستخدمه بالفعل. لدى Maguyva أدلة إعداد لـ 24 عميل MCP موثّق — بما في ذلك Cursor — ويمكنها التحدث إلى أي عميل آخر متوافق مع MCP يدعم التكوين القياسي.

صفحة إعداد Cursor هي مسار خاص بالمحرر إذا كان هذا هو مكان عملك. نفس الخادم يستجيب لـ Claude Code وVS Code وWindsurf وCodex CLI والباقي. أنت لا تغيّر المحرر. أنت تمنح كل وكيل نفس سطح الأدوات: 11 أداة MCP موجهة للعملاء عبر البحث والرموز وتحليل التبعيات واسترجاع الملفات وسياق المستودع وسير عمل الأدوات المساعدة الحتمية. يجتمع البحث الدلالي والبنيوي والرسم البياني والنصي في نتيجة واحدة مُصنَّفة.

تلك هي فائدة قابلية النقل. الاقتباس الذي تتحقق منه في Cursor صباح اليوم له نفس الشكل الذي سيعيده Codex CLI الليلة. مسار الملف ورقم السطر. افتحه. إذا كان خاطئًا، سترى ذلك. إذا كان صحيحًا، فإن التغيير التالي لديه مكان يستقر فيه. المُدَّعى هو تغييرات أقل هلوسة، وليس وعدًا بأن كل تغيير سيكون صحيحًا.

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

الوثائق تعطي نفس حلقة التفعيل لكل عميل: فهرس مستودع تعرفه بالفعل، اربط العميل، اطرح سؤالًا واحدًا يمكنك التحقق منه. افعل ذلك مرة واحدة في Cursor. افعله مرة أخرى من CLI الذي تستخدمه فعليًا يوم المراجعة. إذا اقتبست كلتا الإجابتين نفس المعالج، فإن الخريطة قد سافرت معك بالفعل.

كيف تتعايش الخريطتان معًا

استخدم كليهما. هذا ليس بديلًا بمعنى صفحة المقارنة.

اترك فهرسة Cursor مفعّلة للمشروع الموجود على القرص. دع Explore وInstant Grep والوكيل داخل المحرر يستخدمونها. تلك الحلقة أصلية وسريعة.
أضف Maguyva كخادم MCP في Cursor حتى تتمكن نفس الجلسة أيضًا من استعلام خريطة مساحة العمل المستضافة. Cursor عميل Maguyva موثّق. أنت لا تختار فهرسًا واحدًا وتحذف الآخر.
أضف نفس خادم Maguyva إلى Claude Code أو Codex CLI أو أي عميل MCP آخر يلمس المستودع. نموذج مفتاح API واحد. مساحة عمل واحدة.
إذا كان وكيل CI متوافقًا مع MCP، وجّهه إلى نفس الخادم. سيقرأ نفس اللقطة المختومة بالوقت التي يقرأها الحاسوب المحمول.

يظل فهرس المحرر أفضل أداة لـ ‘ما هو موجود على القرص في هذه النافذة، الآن’. الخريطة المستضافة هي أفضل أداة لـ ‘كيف تبدو مساحة العمل هذه لكل وكيل سيلمسها اليوم’. هاتان الجملتان لا تتنافسان.

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

ما لا تدّعيه هذه الصفحة

هي لا تدّعي أن فهرسة Cursor ضعيفة أو غير مكتملة أو سبب لتغيير المحرر. الجملة الأولى من هذا المقال تنص على العكس.

هي لا تدّعي أن Maguyva تحل محل Instant Grep أو الوكيل الفرعي للاستكشاف. تلك ميزات Cursor. تبقى في Cursor.

هي لا تختلق أعداد لغات أو أرقام كمون أو توفير رموز لأي منتج. الأرقام غير المعروفة تبقى غير منشورة.

هي لا تتظاهر بأن العمل المحلي غير المدفوع بعد موجود في الخريطة المستضافة. اللقطة المختومة بالوقت تجعل ذلك القيد مرئيًا. هي لا تلغيه.

الاختبار عادي. فهرس مستودع تعرفه بالفعل. اطرح سؤالًا واحدًا يمكنك التحقق منه، أولًا في Cursor ثم في عميل MCP ثانٍ. السياق الذي يسافر معك هو نفس الاقتباس في كلا المكانين.

// same map, wherever you opened it.

الخريطة أولًا، المراجعة ثانيًا

Mon, 07 Sep 2026 00:00:00 GMT

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

تبدو هاتان المهمتان متشابهتين من بعيد لأن كلتيهما تتضمنان ‘فهم قاعدة الكود’. إنهما ليستا نفس المنتج. واحدة تجيب عن ‘أين ينبغي أن يستقر هذا التغيير؟’. الأخرى تجيب عن ‘ما الذي يكسره هذا التغيير الذي سيفوّته مدقق شيفرة يعمل سطرًا بسطر؟’. خلطهما ينتج مسودة أولى أسوأ ومراجعة أكثر ضجيجًا.

هذا المقال دليل سير عمل مزدوج. Maguyva هي الخريطة التي يستعلمها الوكيل أولًا. Greptile هو وكيل المراجعة الذي يعلّق على طلب السحب بعد ذلك. هذا الزوج متكامل بحكم التصميم: لا تراجع Maguyva طلبات السحب، ولا يحل Greptile محل طبقة السياق التي يستخدمها الوكيل لكتابته.

لماذا هذا التقسيم مفيد

وكيل البرمجة الذي يبدأ بتحيز التدريب بالإضافة إلى بعض الملفات المُلصَقة سيخترع مسارًا معقولًا ويحرّره. هذا فشل من نوع ‘الملف الخاطئ’، وهو مشكلة استرجاع. Maguyva هي طبقة سياق قاعدة كود MCP عن بُعد: يجتمع الاسترجاع الدلالي والبنيوي (AST) والرسم البياني/التبعيات والنصي في نتيجة واحدة مُصنَّفة، بالإضافة إلى البحث عن الرموز واسترجاع الملفات. الإجابات المدعّمة بالأدلة تعود كـ path/file.ext:line، حتى تتمكن من رفض الخطأ قبل أن توجد الرقعة. المُدَّعى بسيط عمدًا: تغييرات أقل هلوسة. لا يزال بإمكان النموذج التخمين. فقط الخطوة الأولى لم تعد تخمينًا.

Greptile هو وكيل مراجعة كود مدعوم بالذكاء الاصطناعي. بكلماتهم، يراجع تلقائيًا كل طلب سحب بفهم كامل لقاعدة الكود، ويضع نفسه مقابل أدوات تدقيق الشيفرة التقليدية التي تفحص الملفات بشكل منفصل بدلًا من النظام بأكمله. يتكون الإعداد من تثبيت تطبيق GitHub أو GitLab واختيار مستودع. لا يوجد فهرس محلي عليك تشغيله. الاستضافة عبر Greptile Cloud (يذكرون امتثال SOC 2 Type II، مع تقرير متاح عند الطلب)، مع خيار استضافة ذاتية معروض للمؤسسات.

تدفقهم المرقّم بأنفسهم هو: الاتصال وبناء رسم بياني للتبعيات لكل دالة وفئة وتبعية؛ عند كل طلب سحب، تحليل التغيير باستخدام ذلك الرسم البياني الكامل للمستودع ونشر النتائج كتعليقات على طلب السحب مع إصلاحات مقترحة، في حوالي ثلاث دقائق؛ يمكن لكل تعليق تسليم المشكلة إلى وكيل البرمجة الذي يستخدمه الفريق بالفعل. يذكرون أيضًا أنهم يقرؤون تعليقات طلبات السحب البشرية السابقة بمرور الوقت لتعلّم معايير كود الفريق وتقليل الاقتراحات المزعجة. نظام التعلم الخاص بهم، بحسبهم، يستغرق 2-3 أسابيع للتكيّف.

هذه مراجعة، وليست صياغة. قوة Greptile هي سياق الرسم البياني الكامل للمستودع مقابل تغيير استقر بالفعل في طلب سحب، متبوعًا بحلقة مغلقة ترسل النتائج إلى Claude Code أو Codex أو Conductor أو Cursor أو Devin. قوة Maguyva هي الخريطة المُصنَّفة التي يستعلمها الوكيل قبل كتابة التغيير. استخدم كليهما. لا تطلب من أحدهما القيام بعمل الآخر.

لا يوجد تكامل منتج من طرف أول بين Maguyva وGreptile مذكور. لست بحاجة إليه أيضًا. تتحدث Maguyva إلى الوكلاء عبر MCP. يتحدث Greptile إلى GitHub أو GitLab عبر تطبيقه الخاص. يلتقيان عند طلب السحب. لا سكريبت لاصق، ولا cron يغذّي أداة إلى أخرى. لا يحتاج هذا الزوج إلى bash لأن كل منتج يجلس بالفعل على السطح الذي يخصه.

ما ليس هذا

هذا ليس تشهيرًا بـ Greptile. هذه ليست صفحة ‘استبدل مراجعك’. أُطلق Greptile على Hacker News في 5 مارس 2024 كشركة Y Combinator W24، وكان ذلك الموضوع طريقة تعرّف بها كثيرون على هذا المنتج لأول مرة. إذا كانت تلك هي الطريقة التي اكتشفتهم بها، استمر باستخدامهم. هذه الصفحة هي النصف الثاني المفقود من تلك الحلقة: تأسيس الوكيل أولًا حتى يكون طلب السحب الذي يراه Greptile مستهدفًا بالفعل للملفات الصحيحة.

تتصدر مواد Greptile التسويقية بادّعاءات سرعة المراجعة واكتشاف الأخطاء. اعتبر ذلك ادّعاء Greptile الخاص، وليس رقمًا مُتحقَّقًا منه بشكل مستقل. لا يكرره هذا المقال كحقيقة.

تغطية اللغات هي نفس النوع من الصدق. يؤطر Greptile الدعم على أنه يغطي جميع لغات البرمجة بدلًا من قائمة مُدرَجة؛ الرقم الدقيق غير مذكور. تنشر Maguyva دعمًا لأكثر من 279 لغة وتقنية قائمة على النص، مع تفصيل تقني (AST مدعوم بواسطة محلل نحوي مقابل نص فقط) على الموقع عندما يكون السؤال تقنيًا. هذان منتجان مختلفان يدّعيان أشياء مختلفة. لا تخلط بينهما.

تسعير Greptile غير مذكور في المحتوى القابل للاستخدام لهذا المقال. الخطط المدفوعة موجودة؛ راجع صفحة تسعيرهم. تفرض Maguyva رسومًا لكل مساحة عمل، وليس لكل مقعد. الخطط تبدأ مجانًا. صفحة التسعير تسرد المستويات المنشورة إذا كنت بحاجة إلى أرقام مساحة العمل.

سير العمل

ثلاث مراحل مُسمّاة. نفّذها بهذا الترتيب. لا تتخطَّ أيًا منها في أول مرة تجرّب فيها هذا الزوج.

1. سياق Maguyva

فهرس مستودعًا واحدًا تعرفه بالفعل. اربط عميل MCP الذي تكتب فيه بالفعل — Claude Code أو Cursor أو Codex CLI أو VS Code أو Windsurf أو أي عميل آخر متوافق مع MCP. لدى Maguyva أدلة إعداد لـ 24 عميل MCP موثّق ويمكنها التحدث إلى عملاء آخرين يدعمون تكوين MCP القياسي.

اطرح سؤالًا واحدًا يمكنك تقييمه قبل أن يكتب أي أحد سطرًا واحدًا. ‘أين تُعالَج مهلة انتهاء الجلسة، ومن يستدعيها؟’ خطوة أولى أفضل من ‘أصلح المصادقة’. طالب بالاقتباسات. افتح نتيجة file.ext:line. تتبّع الرمز. تحقق من التبعيات التي أنت على وشك لمسها.

تكشف Maguyva عن 11 أداة MCP موجهة للعملاء عبر البحث والرموز وتحليل التبعيات واسترجاع الملفات وسياق المستودع وسير عمل الأدوات المساعدة الحتمية. تجتمع أربعة أنماط استرجاع في نتيجة واحدة مُصنَّفة؛ find_symbol أداة منفصلة عندما تعرف الاسم بالفعل. تصف الوثائق أقصر مسار: ابدأ مجانًا، فهرس مستودعًا تعرفه بالفعل، اربط العميل، ثم اطرح سؤالًا واحدًا يمكنك التحقق منه.

اللقطات مختومة بالوقت، حتى يتمكن الوكيل من معرفة أي نسخة من الشجرة يقرأ. القيد الصادق هو العمل المحلي غير المتزامن. إذا كان التغيير موجودًا فقط في شجرة العمل ولم يُدفَع بعد، فإن الخريطة المستضافة لا تحتوي عليه بعد. لا تزال ملفات التعليمات (CLAUDE.md، AGENTS.md) لها مكان هنا، للأعراف وما ينبغي عدم لمسه. إنها ليست خريطة حية. استخدمها للسلوك. استخدم Maguyva للحقائق.

لا تدع الوكيل يفتح طلب سحب قبل أن يصمد الاقتباس أمام التماس مع المستودع. تلك البوابة هي الغرض الكامل من هذه المرحلة.

2. طلب سحب الوكيل

نفس الوكيل يكتب الآن التغيير في العميل الذي تدفع مقابله بالفعل. Maguyva ليست محررًا ولا مراجعًا. لا يزال الوكيل ينتج التغيير. لا تزال تفتح طلب سحب على GitHub أو GitLab كما كنت تفعل بالفعل.

ما ينبغي أن يختلف هو الملف الأول. يجب أن يسمّي طلب السحب المعالج الفعلي الذي ينفّذ ذلك السلوك، والمستدعين الذين سينكسرون، والاختبارات التي ستفشل إذا كان التغيير خاطئًا. إذا تُخطّيت المرحلة 1، ستهدر المرحلة 3 تعليقها على تغيير استقر في الحزمة الخاطئة. لا يزال بإمكان Greptile العثور على مشاكل منهجية. لا ينبغي أن يضطر أيضًا للتعافي من مسار مُهلوَس.

أبقِ طلب السحب صغيرًا. الملف الأول المدعوم بالأدلة ليس ترخيصًا لإعادة كتابة وحدة. يعمل هذا الزوج المتكامل عندما يقوم الوكيل بعمل واحد مع الخريطة، ثم يطلب من المراجع القيام بعمل آخر على تغيير محدود.

3. مراجعة Greptile

Greptile متصل بالفعل بالمستودع عبر تطبيق GitHub أو GitLab. عند طلب سحب جديد، يحلّل التغيير باستخدام الرسم البياني الكامل للمستودع الذي بناه، وينشر النتائج كتعليقات مع إصلاحات مقترحة. تضع موادهم الخاصة هذه الخطوة عند حوالي ثلاث دقائق.

اقرأ التعليقات كما تقرأ زميل فريق منتبه: افتح الموقع المقتبس، قرر ما إذا كانت النتيجة صحيحة، ثم تصرّف. حيثما يقدّم Greptile ‘Fix with your Agent’، يرسل المشكلة — مسار الملف، رقم السطر، الكود المقترح — إلى Claude Code أو Codex أو Conductor أو Cursor أو Devin. يرسل ‘Fix All’ جميع المشكلات في تلك المراجعة دفعة واحدة. يوفرون أيضًا Greptile MCP وإضافة Claude Code لذلك التسليم. Maguyva غير موجودة في تلك القائمة المستهدفة المُسمّاة؛ هذا الغياب ليس مشكلة. أنجزت Maguyva عملها بالفعل في المرحلة 1. وكيل البرمجة الذي كتب طلب السحب هو الطرف الذي ينبغي أن يحصل على حمولة الإصلاح.

توقّع ضجيجًا في الأسابيع 2-3 الأولى بينما يتكيّف نظام تعلّم Greptile مع التعليقات التي يتركها فريقك فعليًا. هذا هو الجدول الزمني الذي يذكرونه، وليس عيبًا في الزوج. تبقى المراجعة البشرية في تلك الحلقة. Greptile خطوة أولى تلقائية، وليس زر دمج.

إذا أشار تعليق Greptile إلى ملف لم يستعلمه الوكيل قط في المرحلة 1، فهذه إشارة مفيدة. إما أن الخريطة فوّتت مستدعيًا، أو تخطّى الوكيل اقتباسًا. أصلح المسودة وفقًا للتعليق. لا تعطّل المراجع.

كيف تحافظ على صدق هذا التكامل

Maguyva دائمًا أولًا. مراجعة طلب سحب بملف خاطئ لا تزال مراجعة ملف خاطئ.
Greptile دائمًا بعد ذلك. مسودة مُقتبَسة جيدًا لا تزال تحتاج إلى قراءة تغيير على مستوى النظام بأكمله.
لا تطلب من Maguyva نشر تعليقات طلبات السحب. إنها لا تفعل ذلك.
لا تطلب من Greptile أن يكون طبقة الاسترجاع الأولى للوكيل بينما لا يزال يختار المسار. هذا ليس عملًا مصممًا لتطبيق GitHub أو GitLab الخاص بهما.
لا تخترع خط أنابيب bash ‘يزامن’ الاثنين. طلب السحب هو تلك الواجهة.
تحقق من كلا الجانبين بشكل منفصل. فهرس مستودعًا تعرفه بالفعل. اطرح سؤالًا واحدًا يمكنك التحقق منه. ثم افتح طلب سحب صغير واقرأ ما يعلّق عليه Greptile فعليًا.

تصبح هذه الحلقة عادية بمجرد تسميتها. الخريطة أولًا. طلب سحب الوكيل. المراجعة بعد ذلك. يبقى كل منتج على جانب طلب السحب الذي يتخصص فيه.

// map first. review second. in that order.

منح وكلاء الذكاء الاصطناعي سياق مستودع كبير بدون فهرس محلي

Fri, 14 Aug 2026 00:00:00 GMT

المستودعات الكبيرة لا تناسب نافذة السياق، وإذا سبق لك أن وجّهت فهرسًا مبنيًا على الحاسوب المحمول نحو مستودع موحّد حقيقي، فأنت تعرف أنه لا يناسبه بشكل مريح هناك أيضًا — تقفز ذاكرة الوصول العشوائي، ويستغرق الفهرسة الأولى ساعة، ويبدأ وكيلك مع ذلك الجلسة التالية بتخمين الملفات المهمة.

الإجابة المعتادة هي تشغيل فهرس بجانب المحرر، وبالنسبة لمستودع يناسب جهازًا واحدًا بشكل مريح، هذه إجابة جيدة. إذا كان مستودعك الموحّد يُفهرَس بسرعة بالفعل في Cursor وكان ذلك هو المكان الوحيد الذي تحتاج فيه إلى الخريطة، فلا شيء يضيفه هذا المقال — تخطَّه.

هذا المقال يتناول الحالة الأخرى — عندما يحتاج وكيل إلى خريطة قابلة للاقتباس لمستودع كبير، ولا تريد تشغيل فهرس محلي للحصول عليها.

متى يصبح الفهرس المحلي الأداة الخاطئة

يفترض الفهرس المحلي أن الكود يعيش على نفس الجهاز الذي يستعلمه، وعلى نطاق مستودع موحّد حقيقي، يتوتر ذلك الافتراض حتى داخل محرر واحد. المستودع ببساطة أكبر مما تريد إبقاءه ‘ساخنًا’ على الحاسوب المحمول: تعمل في حزمة واحدة بينما يقع نطاق التأثير على بُعد ثلاثة أدلة، والفهرسة الباردة الأولى لشجرة مكوّنة من مليوني سطر ليست شيئًا تريد المرور به مرتين — سواء على جهازك الخاص، أو على عامل CI الذي لم يستنسخ تلك الشجرة من قبل. أو ينبغي أن يتمكن زميل الفريق من استعلام نفس الخريطة التي تستعلمها، دون انتظار جهازه الخاص ليكافح مع نفس الفهرس.

لا شيء من هذا سبب للتخلص من فهرس محرر جيد. إنه سبب لامتلاك خريطة مستضافة أيضًا يمكن لأي من وكلائك استعلامها عبر MCP.

ومشكلة النطاق تلك أعمق من ‘الكثير من الملفات للصق’. على شجرة كبيرة، السؤال المثير للاهتمام نادرًا ما يكون ‘أرني هذا الملف’ — إنه أي ملف، أي رمز، من يستدعي، أي اختبار. الوكيل الذي يبدأ بسرد src/ وقراءة أول ثلاث نتائج سيفوّت بسعادة المعالج في apps/api والعميل المُولَّد في packages/sdk. ما تحتاجه هو استرجاع مبني من الشجرة بأكملها، ثم مُصنَّف، ثم مقتبس.

ماذا يعني ‘سياق مستودع كبير’ فعليًا

إلقاء الملفات في الطلب ليس سياقًا — إنه نسخ أصغر وأسوأ للشجرة. ما يحتاجه وكيلك فعليًا هو طرح سؤال والحصول على إجابة مقتبسة تعود إليه: أين يُعرَّف هذا الرمز ومن يستدعيه، وما الذي يعتمد على الوحدة التي سأغيّرها، وأي ملفات اختبار تغطي هذا السلوك، وكيف تبدو تلك الشجرة الآن، وليس الربع الماضي.

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

شيء آخر لا تستطيع ملفات التعليمات فعله لك: CLAUDE.md وAGENTS.md هما المكانان الصحيحان للأعراف والسلوك، لكنهما ليسا خريطة حية ومُصنَّفة وقابلة للاستعلام لشجرة مكوّنة من مليوني سطر. استخدم القواعد للسلوك؛ استخدم ذكاء المستودع للحقائق.

نبني الخريطة في السحابة، وأنت تستعلمها من أي عميل

Maguyva هي طبقة سياق قاعدة كود MCP عن بُعد. تربط GitHub، وتختار مستودعك، ويمكنك أن تبتعد بينما يحلّل خط الأنابيب السحابي الشجرة، ويبني الرموز وحواف الرسم البياني، ويحافظ على خريطة مُصنَّفة — دون الحاجة أبدًا إلى فهرس محلي.

عندما تدفع كودًا، تُحلَّل الملفات المتغيرة تدريجيًا، وتُعاد بناء طبقات الرسم البياني والتصنيف وفق جدول: يوميًا في الخطة المجانية، وكل ساعة في الخطط المدفوعة. كل لقطة مختومة بالوقت، حتى يتمكن وكيلك من معرفة أي نسخة من الشجرة يقرأ. القيد الصادق هنا هو العمل المحلي غير المتزامن — التغييرات الموجودة فقط في شجرة عملك، والتي لم تُدفَع أبدًا، ليست بعد في الخريطة المستضافة.

ثم تربط أي عميل تستخدمه بالفعل بإضافة مفتاح API إلى تكوين MCP الخاص به. توجد أدلة إعداد لـ 24 عميل MCP موثّق، ويمكن لأي عميل آخر متوافق مع MCP يدعم التكوين القياسي أن يتصل أيضًا. إذا كان Cursor هو المكان الذي تعيش فيه، فإن صفحة Cursor ترسم ذلك المسار؛ نفس الخادم يستجيب لـ Claude Code وVS Code وWindsurf وCodex CLI والباقي.

أنت لا تغيّر المحرر. أنت تمنح وكيلك سطح أدوات — 11 أداة MCP عبر البحث والرموز وتحليل التبعيات واسترجاع الملفات وسياق المستودع — مع تغطية لأكثر من 279 لغة وتقنية قائمة على النص، مما يعني أكثر مما اعتقدت لمستودع موحّد توقف منذ زمن طويل عن كونه لغة واحدة.

تعود الإجابات مدعّمة بالأدلة، كمسارات ملفات مع أرقام أسطر. يجتمع البحث الدلالي والبنيوي والرسم البياني والنصي في نتيجة واحدة مُصنَّفة، حتى لا يعطيك سؤال مثل ‘ما الذي يعتمد على parseConfig’ كومة من grep أو اقتباسًا دلاليًا واحدًا فقط، بل الأماكن القليلة التي تهم فعلًا.

دليل ملموس

لا تبدأ بفهرسة الشركة بأكملها. هذا هو المسار الذي ينجح:

اختر مستودعًا واحدًا تعرفه جيدًا بالفعل — حزمة يمكنك تقييمها يدويًا أكثر قيمة من أكبر شجرة تملكها.
ابدأ مجانًا: 3 مستودعات، و50 ألف سطر مفهرس، وجميع الأدوات الـ11، ودون حصة استعلام شهرية. إذا كان مستودعك التمثيلي أكبر، فإن صفحة التسعير تسرد مستويات مساحة العمل ($0، $19، $49، $149) حسب التغطية المفهرسة — وليس عدد المقاعد.
اربط GitHub وانتظر اكتمال الفهرسة الأولى. أنت لا تُجمّع أي شيء محليًا.
اربط عميل MCP الخاص بك — بضعة أسطر تكوين. Maguyva خادم MCP عن بُعد، لذا لا يوجد إضافة ولا امتداد ولا محرر ثانٍ يجب تبنّيه.
اطرح سؤالًا واحدًا يمكنك التحقق منه. ‘ما الذي يعتمد على parseConfig؟’ أو ‘أين تُعالَج مهلة انتهاء جلسة تسجيل الدخول؟’ ثم افتح نتيجة file.ext:line المقتبسة وتحقق منها مقابل الشجرة أمامك.
فقط بعد أن تصمد الاقتباسات أمام التماس مع تلك الشجرة، تسمح للوكيل بالتحرير.

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

اختبار التفعيل هو نفسه الذي توصي به الوثائق لأي تشغيل أول: فهرس مستودع تعرفه بالفعل، اطرح سؤالًا واحدًا يمكنك التحقق منه. المستودع الكبير لا يغيّر ذلك الاختبار؛ يجعل فقط الملف الأول الخاطئ أكثر تكلفة.

ما تراقبه بعد الاتصال

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

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

// no laptop got hot building this map.

لماذا يهلوس وكلاء البرمجة بالذكاء الاصطناعي بمسارات الملفات

Fri, 14 Aug 2026 00:00:00 GMT

العلامة ليست جسم دالة خاطئ. إنها تغيير واثق على ملف غير موجود، أو على ملف موجود لكنه ليس الملف الذي ينفّذ ذلك السلوك.

طلبت إصلاح انتهاء صلاحية الجلسة. يفتح الوكيل src/auth/session.ts. المسار معقول. إنه خاطئ أيضًا. المعالج الفعلي يعيش في apps/api/src/middleware/expiry.ts، الذي أُعيدت تسميته منذ عمليتي إعادة هيكلة. الوكيل لا يكذب عليك. إنه يكمل سلسلة نصية بشكل مسار بناءً على تحيز التدريب بالإضافة إلى أي شيء موجود بالفعل في نافذة السياق.

هذا نمط فشل شائع على المستودعات الحقيقية. يستطيع النموذج كتابة الكود. خطؤه هو اختيار المكان الخاطئ لكتابته.

لماذا يخترع الوكلاء المسارات

وكلاء البرمجة هم نماذج تنبؤ بالرمز التالي مزودة بأدوات. عندما تقول ‘أصلح انتهاء صلاحية الجلسة’، يجب أن يسمّي ملفًا قبل أن يتمكن من قراءة أو تصحيح أي شيء. إذا لم يكن لديه بعد خريطة مدعومة بالأدلة، فإنه يبني المسار من:

أعراف التسمية التي رآها في مستودعات أخرى. src/auth/session.ts شكل شائع.
الملفات الموجودة بالفعل في المحادثة، والتي قد تكون الملف الذي ألصقته الأسبوع الماضي، وليس الذي يهم الآن.
قائمة دليل شغّلها بالصدفة، غير مكتملة على شجرة كبيرة.
ملفات التعليمات. CLAUDE.md وAGENTS.md تخبر الوكيل كيف يتصرف. إنها ليست فهرسًا حيًا للرموز أو المستدعين أو المسارات الحالية.

ما من مصدر من هذه هو خريطة هذا المستودع، اليوم. يملأ النموذج الفجوة بنفس الطريقة التي يملأ بها أي فجوة: باستمرارية عالية الاحتمال. غالبًا ما تبدو تلك الاستمرارية كمسار حقيقي. أحيانًا يكون الملف موجودًا ويقع في الحي الصحيح. أحيانًا يكون موجودًا على فرع دُمج الشهر الماضي. أحيانًا لم يكن موجودًا أبدًا.

لا ينقذك grep هنا إذا لم يبحث الوكيل عن السلسلة النصية الصحيحة من الأساس. يخمّن الوكيل مسارًا، ثم يقرأ ما يعيده ذلك المسار، ثم يحرّره. الخطوة الخاطئة الأولى هي المسار، وليست الرقعة.

قراءة الملفات أيضًا ليست نفس الشيء مثل العثور على الملف الصحيح. يمكن لـ Claude Code وCursor وCodex وأدوات مماثلة فتح أي شيء تشير إليه. السؤال هو ما إذا كانت تجد بشكل موثوق الملف الصحيح، والرمز المهم، والتبعيات، والاختبارات، ونطاق التأثير قبل التحرير. الوصول إلى الملفات دون خريطة لا يزال يبدأ بالتخمين.

تحرير الملف الخاطئ مشكلة استرجاع

فكّر في المسار المُخترَع كخطأ استرجاع، وليس عيبًا في الشخصية.

إذا كان على الوكيل إعادة path/file.ext:line قبل السماح له بالتحرير، سيحدث شيئان. أولًا، يمكنك فتح الاقتباس ورفض العمل في عشر ثوانٍ. ثانيًا، يجب على الوكيل أن يستعلم شيئًا يعرف تلك الشجرة فعليًا.

هذا هو عمل طبقة سياق قاعدة الكود. البحث الدلالي وحده غير كافٍ. اقتباس ‘يبدو كانتهاء صلاحية الجلسة’ لا يزال يمكن أن يستقر في حزمة مهجورة. تحتاج أيضًا إلى النص الدقيق عندما تعرف السلسلة النصية، والبحث عن الرموز عندما تعرف الاسم، والبحث البنيوي عندما تعرف الشكل، والرسم البياني للتبعيات عندما تحتاج إلى المستدعين ونطاق التأثير.

Maguyva هي تلك الطبقة لوكلاء البرمجة المتوافقين مع MCP. إنها ليست محررًا. تبقى Claude Code وCursor وCodex CLI وVS Code وWindsurf وعملاء MCP الآخرون في مكانهم. يستعلم الوكيل الخريطة المُصنَّفة قبل لمس سطر واحد.

المُدَّعى بسيط عمدًا: تغييرات أقل هلوسة. لا تنزع Maguyva قدرة التخمين من النموذج. إنها تحوّل الخطوة الأولى الافتراضية من ‘اخترع مسارًا معقولًا’ إلى ‘اطلب موقعًا مُصنَّفًا ومقتبسًا’.

كيف تبدو الإجابة المدعومة بالأدلة

الإجابة المفيدة على ‘أين تُعالَج مهلة انتهاء الجلسة’ ليست فقرة واحدة. إنها قائمة مواقع قصيرة:

apps/api/src/middleware/expiry.ts:48 - المعالج
apps/web/src/lib/auth-client.ts:112 - المستدعي
apps/api/tests/expiry.test.ts:20 - الاختبار الذي سيفشل إذا كان التغيير خاطئًا

يمكنك فتح هذه الأسطر. إذا كانت خاطئة، تتوقف. إذا كانت صحيحة، يمكن للوكيل التحرير. التحقق هو صلب الأمر، وليس شعارًا.

تكشف Maguyva عن 11 أداة MCP موجهة للعملاء عبر البحث والرموز وتحليل التبعيات واسترجاع الملفات وسياق المستودع وسير عمل الأدوات المساعدة الحتمية. تجتمع أربعة أنماط استرجاع (دلالي، وبنيوي، ورسم بياني/تبعيات، ونصي) في نتيجة واحدة مُصنَّفة؛ البحث عن الرموز أداة MCP منفصلة (find_symbol). تعود الإجابات المدعومة بالأدلة بمسارات ملفات وأرقام أسطر، حتى تتمكن من تقييمها مقابل الشجرة أمامك.

الوثائق تصف أقصر مسار: ابدأ مجانًا، فهرس مستودعًا تعرفه بالفعل، اربط العميل، ثم اطرح سؤالًا واحدًا يمكنك التحقق منه.

الحلقة التي تغيّر التغيير الأول

لست بحاجة إلى دين سير عمل جديد. تحتاج إلى خطوة إضافية واحدة قبل الكتابة الأولى.

اطرح سؤالًا واحدًا يمكنك تقييمه بالفعل. ‘أي كود يعالج تسجيل الدخول وانتهاء صلاحية الجلسة؟’ أفضل من ‘أصلح المصادقة’.
طالب بالاقتباسات. مسار الملف ورقم السطر، وليس ملخصًا لـ ‘وحدة المصادقة’.
افتح الملف المقتبس. تتبّع الرمز. تحقق من التبعيات التي أنت على وشك لمسها.
لا تدع الوكيل يصحّح إلا بعد ذلك.

إذا لم تُعد الخطوة 2 أي شيء مفيد، فليس للوكيل الحق في الارتجال على المسار. يبحث مرة أخرى، أو تُريه أنت. تلك البوابة الواحدة هي ما ينتج تغييرات أقل هلوسة. النموذج هو نفس النموذج. الخريطة هي ما يتغير.

لا تزال ملفات التعليمات مهمة. حافظ عليها. استخدمها للأعراف وقواعد المراجعة وما ينبغي عدم لمسه. لا تطلب منها أن تكون فهرسًا. CLAUDE.md الذي يسرد ثلاثة أدلة مهمة سيصبح قديمًا بعد أسبوع من تقسيم حزمة. الخريطة القابلة للاستعلام تُحدَّث عند تحديث المستودع.

فشل ذو صلة هو الملف شبه الصحيح: يفتح الوكيل auth.ts بينما يعيش السلوك في auth-client.ts، أو يصحّح ملفًا مُولَّدًا بدلًا من المصدر، أو يحرّر نسخة في packages/legacy لأن الاسم يتطابق. لا تجعل الاقتباسات هذه الأخطاء مستحيلة. إنها تجعلها مرئية قبل استقرار التغيير.

ما لن تُصلحه الخريطة لك

كن صادقًا حول ما تحصل عليه. لن تجعل خريطة مدعومة بالأدلة كل تغيير صحيحًا — لا يزال بإمكان وكيلك كتابة رقعة سيئة على الملف الصحيح تمامًا. إذا كانت قاعدة الكود الخاصة بك تعتمد على التوجيه الديناميكي للاستدعاءات، أو الانعكاس، أو الترقيع أثناء التشغيل، فسيعيد بعض البحث عن الرموز نتائج أقل مما تريد، لأن هذا ما تفعله عدم المباشرة في وقت التشغيل بأي فهرس ثابت. وإذا كنت تتوقع نسبة مئوية — ‘انخفضت المسارات المُهلوَسة بنسبة X%’ — فلن تجدها هنا، لأنه لا يمكن لأحد قياس هذا الرقم بصدق لمستودعك سواك أنت.

ما يمكنك توقعه أضيق وأكثر فائدة: يتوقف الوكيل عن بدء تغييره بمسار مُخمَّن. تلك الخطوة الأولى تصبح مدعومة بالأدلة في خريطة حقيقية، ومن هناك تأتي التغييرات الأقل هلوسة. كل شيء بعد الاقتباس — قراءة التغيير، تقييم الرقعة — لا يزال عملك، كما كان دائمًا.

هذا الاختبار لا يكاد يكلفك شيئًا: فهرس مستودعًا تعرفه بالفعل واطرح سؤالًا واحدًا يمكنك التحقق منه. ابدأ بالمسار الذي أحرقك سابقًا. إذا كان الاقتباس خاطئًا، سترى ذلك فورًا. إذا كان صحيحًا، فإن تغيير وكيلك التالي لديه مكان أفضل للاستقرار فيه.

// it doesn't know the file. it knows how to find it.

لماذا رقّينا بحث الكود إلى voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

تعكس أرقام المعايير القياسية في هذا المنشور لوحات صدارة RTEB وقت النشر (يونيو 2026). تتحرك لوحات الصدارة؛ تعامل مع الترتيب كلقطة آنية، لا حقيقة دائمة.

جودة البحث الدلالي لا تتجاوز جودة التضمينات التي تحته.

عندما يسأل وكيل Maguyva “أين نتعامل مع إعادة المحاولة”، فهو لا يبحث حرفيًا (grep) عن كلمة “retry”. إنه يطلب المعنى — حلقة التراجع (backoff)، وقاطع الدارة (circuit breaker)، والشيء الذي يُغلِّف استدعاءً غير مستقر. يجيب عن هذا السؤال نموذج متجهي يحوِّل الكود إلى نقطة في الفضاء ويجد الجيران. اختر نموذجًا أفضل، ويصبح كل استعلام دلالي في المنتج أكثر دقة بصمت.

لذا غيَّرنا نموذجنا. اعتبارًا من يونيو 2026، تعمل تضمينات كود Maguyva على voyage-4-large، لتحل محل voyage-code-3.

المعيار القياسي

لم نتخذ هذا القرار بالحدس. يُرتِّب معيار تضمين الاسترجاع العام (RTEB) نماذج التضمين وفق مهام استرجاع حقيقية، وفي لوحة صدارة الكود الخاصة به يحتل voyage-4-large المرتبة الأولى إجمالًا (90.86) — متقدمًا على gemini-embedding-2-preview (90.26)، والأهم، متقدمًا على النموذج الذي كنا نستخدمه بالفعل، voyage-code-3 (89.73، المرتبة الثالثة).

تلك فجوة مطلقة صغيرة. لكنها فجوة في الاتجاه الصحيح، على معيار قياسي عام، في المهمة الدقيقة التي تهمنا: استرجاع الكود بالمعنى.

المقايضة التي نقبلها: التكميم الثنائي (Binary Quantization)

إليك الجزء الذي تُغفِله معظم منشورات “رقَّينا نموذجنا”.

لا يخزِّن Maguyva متجهات كاملة الدقة. نخزِّن تضمينات مُكمَّمة ثنائيًا: يُختزَل كل متجه بـ2048 بُعدًا إلى توقيع بـ2048 بت — 256 بايت لكل متجه. يُجرى البحث في تلك التواقيع بمسافة هامينغ (Hamming)، وتُفهرَس وتُقسَّم لكل مستأجر.

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

يتناسب voyage-4-large مع هذا التصميم دون فرض ترحيل لطبقة التخزين: إنه يُنتج مخرَجًا بـ2048 بُعدًا، مثل voyage-code-3 تمامًا، لذا لم تتغير أعمدة bit(2048) لدينا ومسار بحث هامينغ. تحسَّن النموذج؛ وبقي المخطط (schema) في مكانه.

الكود كان مجرد البداية

Maguyva أداة ذكاء كود. لكننا أيضًا أول مستخدميه، ونوجِّهه نحو شيء آخر: ملفات markdown التي تعيش في مستودعاتنا جنبًا إلى جنب مع الكود. سجلات القرارات المعمارية، وأدلة التشغيل، والعقود، ووثائق المالية والسياسات — كلها تحت التحكم في الإصدار في Git، وكلها خلف خادم MCP نفسه، فهرس دلالي فوق الوثائق، لا المصدر فقط.

هذا بالضبط سبب أهمية اتساع voyage-4-large. في العائلة نفسها من لوحات صدارة RTEB، إنه الأول في المالية، والأول في الرعاية الصحية، والأول في استرجاع النصوص إجمالًا — متقدمًا على Gemini Embedding من Google، وEmbed v4 من Cohere، وtext-embedding-3-large من OpenAI. (Voyage شريك مؤسِّس لـRTEB، لذا نقرأ هذا كإشارة عامة قوية أكثر من كونه حكمًا محايدًا تمامًا — لكنه يُقاس رأسًا لرأس مقابل كل نموذج تجاري رئيسي، على مجموعات اختبار خاصة محجوبة.) الفهرس نفسه الذي يجد الدالة الصحيحة لوكيل يجد البند الصحيح في عقد أو السطر الصحيح في سياسة — وفي تلك المجالات، voyage-4-large ليس حلًا وسطًا، إنه الرائد.

لماذا ندفع مقابل تضمينات متميزة

توجد طريقة أرخص للبحث، والكثير منها مجاني. البحث المعجمي — BM25 وأقرانه — يطابق الكلمات المفتاحية، ويعمل محليًا، ولا يكلِّف شيئًا. تمنح نماذج التضمين مفتوحة المصدر مثل BGE وNomic وembeddinggemma استرجاعًا دلاليًا لائقًا فعلًا، ويمكنك استضافتها ذاتيًا بثمن وحدة معالجة رسومية (GPU). يستخدم Maguyva الجانب المجاني أيضًا: يدمج كل استعلام البحث النصي، وAST، والرسم البياني، والدلالي. ما لا نُقصِّر فيه هو الطبقة الدلالية.

ندفع لكل رمز مقابل تضمينات متميزة — voyage-4-large — بدلًا من استضافة نموذج مجاني ذاتيًا، لسببين. أولًا، لا يستطيع البحث بالكلمات المفتاحية وحده الإجابة عن “أين نتعامل مع إعادة المحاولة” عندما يقول الكود backoff وcircuit breaker ولا يذكر كلمة “retry” أبدًا — المعنى هو بيت القصيد من التضمين، وفي المجالات التي نخدمها تتخلَّف النماذج المفتوحة عن المتميزة: بفارق نحو نقطتين في النصوص العامة، وأبعد من ذلك في مجالات متخصصة مثل الكود والعقود والمالية. ثانيًا، في تجربتنا تُشكِّل جودة الاسترجاع الإجابة النهائية أكثر مما يفعله النموذج في الطرف الآخر — وكيل قوي يُعطى سياقًا خاطئًا لا يزال يجيب خطأً، ولا يرى أبدًا الوثيقة التي لم تُمنَح له قط.

إذًا التضمينات المتميزة فاتورة لكل رمز تتوسَّع مع كل مستودع ووثيقة نُفهرِسها — وندفعها عن قصد. مقابل النتيجة التي يحصل عليها مستخدمونا، الدالة الصحيحة أو البند الصحيح، نعتقد أن تلك المقايضة تستحق العناء.

الجزء الصادق

لا يزال توثيق Voyage نفسه يصف voyage-code-3 بأنه النموذج المُحسَّن للكود. فلماذا الانتقال إذًا؟

لأننا قرأنا المعيار القياسي العام، لا جدول نماذج البائع فقط، ووضع المعيار voyage-4-large في القمة لاسترجاع الكود. كان هذا قرارًا استشرافيًا: أخذ النموذج الأحدث والأقوى عمومًا والتحقق منه مقابل لوحة صدارة عامة على المهام التي تهم. نحن مرتاحون لاتخاذ ذلك الرهان لأن الأدلة واسعة — voyage-4-large لا يفوز على الكود فقط، بل يتصدر في المالية، والرعاية الصحية، والاسترجاع الإجمالي أيضًا.

الأرضية الصامتة

كل أداة نعرضها — البحث الدلالي، وجمع سياق المهام، والأسئلة والأجوبة المرتكزة على الأدلة — تنتهي عند الاسترجاع. عندما يتحسَّن المسترجِع، يحصل الوكيل في الطرف الآخر على أدلة أفضل، ويسلك مسارات خاطئة أقل، ويُرسِّخ إجاباته في الكود الصحيح — أو البند الصحيح، أو السياسة الصحيحة. نموذج تضمين أكثر دقة ليس ميزة برَّاقة. إنه الأرضية تحت كل شيء آخر، وقد رفعناها للتو. لن تلاحظ. تلك هي الفكرة.

التحسين الذاتي المتكرر للغات: صقل ذكاء الكود عبر نحو 280 لغة

Tue, 26 May 2026 00:00:00 GMT

تعكس الأرقام في هذا المنشور حالة النظام وقت النشر (مايو 2026). راجع صفحة فريقنا للأرقام الحالية.

يستخلص Maguyva الرموز، والمراجع، ورسمًا بيانيًا للتبعيات من كود المصدر في نحو 280 لغة. كل لغة هي معالِج tree-sitter مخصَّص — استعلامات، وأساليب استدلال، وحالات حدّية — ويمكن أن يكون كل معالِج خاطئًا بطريقة دقيقة خاصة به. استدعاء دالة يُصدَر كقراءة. دالة تُنسَب إلى النطاق المحيط الخطأ. علاقة غير موجودة أصلًا.

لا يمكنك تدقيق ذلك يدويًا. لا يستطيع أي فريق قراءة مخرَجات الاستخلاص عبر 280 مجموعة من القواعد النحوية واكتشاف الحواف السيئة. لذا فإن السؤال المثير للاهتمام ليس “هل استخلاصنا صحيح” — إنه “كيف تكتشف أنه خاطئ، بهذا الاتساع، دون إنسان في كل حلقة”. إجابتنا هي التحسين الذاتي المتكرر للغات: حلقة جودة يقودها وكلاء اللغات، وLLM يعمل حكَمًا، وقاعدة واحدة نستمر في إعادة تعلّمها: الأخضر (green) ليس مرادفًا للصحيح.

الأخضر ليس صحيحًا

لكل لغة مجموعة تجهيزات اختبار (fixtures)، وتُقيِّمها بوابة إصدار عبر خمسة أبعاد — الدقة، والسلامة البنيوية، والاكتمال، والجودة، والأداء. لا تصبح اللغة خضراء (GREEN) إلا عندما تكون الدقة (precision) ≥ 0.95، والاستدعاء (recall) ≥ 0.99، وF1 ≥ 0.97 على تجهيزاتها، مع 20 حافة (edge) متوقَّعة على الأقل للثقة الإحصائية. دون ذلك تكون صفراء (YELLOW) أو حمراء (RED)، ولا تُطلَق.

تلك البوابة ضرورية لكنها غير كافية. يستند التحقق إلى تجهيزات كتبناها نحن. إنها تُرمِّز الحالات التي فكرنا فيها بالفعل. يمكن لمعالِج أن يكون مثاليًا على تجهيزاته ومع ذلك يُشوِّه نمطًا لا يظهر إلا في كود حقيقي — اصطلاح ماكرو، أو دالة مقيَّدة بنوع عام، أو ميزة لغة لم يكتب أحد لها تجهيزة. الأخضر يعني أن التجهيزات نجحت. لا يعني أن مستودعًا حقيقيًا يُستخلَص بنظافة. لذا يجب أن تترك الحلقة التجهيزات وراءها وتفحص الكود المستخدم فعليًا.

الحلقة الداخلية: فحص عيّني، حكم، إصلاح، إثبات

تُشغَّل الحلقة الأساسية للغة واحدة في كل مرة:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

بضعة أشياء تجعل هذا ينجح بدلًا من أن يتخبط.

الحكَم هو الوكيل، لا استدعاء واجهة برمجية (API). عندما نقول “LLM كحكَم”، نعني أن وكيل اللغة نفسه يقرأ كل حافة (edge) مأخوذة كعيّنة مقابل المصدر الحقيقي ويصنِّفها وفق معيار ثابت من خمس فئات: هل هذه الحافة صحيحة، أم إيجابية كاذبة، أم العلاقة الصحيحة بنوع خاطئ، أم مرتبطة بنطاق خاطئ، أم تحمل بيانات وصفية خاطئة؟ ذلك المعيار هو اللعبة كلها — “معدل خطأ 23%” لا معنى له حتى تعرف ما إذا كانت تلك عيوبًا حقيقية أم سوء عدّ من الحكَم.

أصلِح شيئًا واحدًا، ثم أثبِته. كل تكرار يغيِّر أصلًا واحدًا قابلًا للتحرير بالضبط، ثم يُعاد تشغيله مقابل منظومة اختبار ثابتة، ويُحتفَظ بالتغيير فقط إذا تحسَّن F1 وبدت نتائج إعادة التصنيف أفضل. إن لم يفعل، يتم التراجع عنه. لا دفعة من التعديلات التخمينية، ولا “من المفترض أن يكون أفضل”. يكسب التغيير مكانه أو يزول. وعندما يثبت إصلاح، يُرقَّى إلى مجموعة التجهيزات — كي لا تستطيع العلة التي أصلحها العودة بصمت أبدًا. خطوة الترقية تلك هي ما يجعل الحلقة تُحسّن نفسها اعتمادًا على نتائجها السابقة، لا مجرد تكرار للعمل ذاته: كل تمريرة تُصلِّب المرجع الذي تتحقق مقابله التمريرة التالية.

الدرس الذي نستمر في إعادة تعلّمه: المقاييس تُبالغ في الإبلاغ

إليك الفخ، وقد وقعنا فيه مباشرة. المقاييس الثانوية لمجموعة الكود — عدد المرات التي لا يكون فيها لهدف مستخلَص رمز قابل للحل، وعدد الرموز التي تبدو “يتيمة”، وما شابه — تُبالغ بشدة في الإبلاغ عن المشكلات. إنها في الغالب نتائج طبيعية لأنماط البرمجة، لا أخطاء.

أوضح مثال: أظهرت llvm ذات مرة معدل “مصدر بلا رمز” بنسبة 73% ووُصِمت بالكارثية. تعمّقنا في الأمر. كانت الدقة الحقيقية 98.5%. كانت “الرموز المفقودة” في معظمها مراجع خارجية مشروعة — استدعاءات إلى المكتبة القياسية، وإلى الأطر، وإلى كود يعيش خارج المستودع. كان المقياس يقيس خاصية للغة، لا عيبًا في المعالِج. لغات مثل Zig وCOBOL وOdin تُظهر معدلات “يُتم” بنسبة 65–70% وهي صحيحة تمامًا؛ لم يكن لدى COBOL أي أخطاء حقيقية.

لو تركنا تلك الأرقام تقود العمل، لكنا أمضينا أسابيع في “إصلاح” معالِجات كانت صحيحة بالفعل، وتجاهلنا اللغات ذات الأخطاء الحقيقية الهادئة. الخلاصة صريحة: المقاييس الإجمالية إشارة فرز أولي تقريبية في أفضل الأحوال. الإشارة الحقيقية للجودة هي الفحص العيّني مع تصنيف الحواف — النظر في حواف فعلية في مستودعات فعلية والحكم عليها واحدة تلو الأخرى. البيانات فوق الحدس، لكن فقط بمجرد أن تعرف أي البيانات يقول الحقيقة.

الحلقة الخارجية: أسطول، لا ماراثون

لغة واحدة في كل مرة ستستغرق وقتًا لا نهائيًا عبر 280 لغة، لذا تُغلَّف الحلقة الداخلية بحلقة خارجية تُشغِّل عددًا كبيرًا بالتوازي.

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

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

ما لا يزال غير كامل

يمكن أن يكون الحكَم مخطئًا، وللخطأ اتجاه: وكيل يعمل بسياق قليل جدًا يُبالغ في الإبلاغ. في دفعة واحدة، صُنِّفت ثماني لغات بخطأ 5–20%؛ وعند الفحص، كانت واحدة فقط علة حقيقية خاصة باللغة — البقية كانت أخطاء حكَم ناتجة عن إغفال دلالات اللغة نفسها (سطر مصدر واحد يُصدر شرعيًا عدة حواف، وربط معاملات نُمذِج كإسنادات، ولغات مرجع-لكل-معرِّف). لهذا نأخذ عينات ببذرتين (seeds) ونقارن نتائج الفحص، ولهذا يُعامَل الاختلاف بين الحكَم والتجهيزات كأكثر إشارة مثيرة للاهتمام، لا حكمًا نهائيًا — أحيانًا تكون التجهيزة نفسها هي المخطئة.

نحن صادقون أيضًا بشأن الهدف. الهدف هو صفر أخطاء حقيقية، تمامًا — لكن “الصفر” اتجاه نصقل نحوه، لغةً تلو أخرى، لا مربعًا يُعلَّم عليه. يوجد دائمًا مستودع آخر باصطلاح آخر.

مُكتسَب، لا مُدَّعى

كل ما يفعله Maguyva من أجل وكيل — إيجاد رمز، وتتبّع تبعية، والإجابة عن سؤال بكود مُستشهَد به — يرتكز على صحة الاستخلاص الذي تحته. عبر 280 لغة، لا يمكن أن يُدَّعى “الصحيح”؛ يجب أن يُكتسَب باستمرار مقابل كود حقيقي. الحلقة هي كيف نكتسبه: دورة مستقلة من الفحص العيّني والإصلاح تعامل مقاييسها الخاصة بريبة، وتُثبِت كل تغيير، وتحوِّل كل إصلاح إلى حارس ضد الانحدار التالي. إنه ليس عملًا برّاقًا. إنه العمل الذي يتيح لنا أن نقول “ندعم لغتك” ونعنيه فعلًا. الأخضر سهل. الصحيح مُكتسَب.

البحث المدمَج متعدد الأنماط: اختيار المسترجِع الصحيح لكل استعلام

Wed, 15 Apr 2026 00:00:00 GMT

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

استعلام البحث ليس شيئًا واحدًا.

“أين يُعرَّف parseConfig” يريد رمزًا دقيقًا — موقعًا واحدًا محدَّدًا، بسرعة. “كيف تعمل المصادقة” يريد المعنى — مجموعة أجزاء الكود ذات الصلة التي تشرح مفهومًا. “ما الذي ينكسر إذا غيّرت هذه الدالة” يريد الرسم البياني للتبعيات. “ابحث عن السلسلة ECONNREFUSED” يريد مطابقة حرفية، لا شيء ذكيًا.

grep ممتاز للمطابقات الحرفية ومفيد لبعض عمليات البحث عن المراجع، لكنه ليس رسمًا بيانيًا للتبعيات ولا يفهم المعنى. تُغطِّي التضمينات الجانب الدلالي، لكنها الأداة الخطأ للسلاسل الدقيقة وتحليل التأثير. تختار معظم أدوات بحث الكود محركًا واحدًا وتُلزم كل استعلام بذلك الاختيار. Maguyva لا يختار. إنه يستنتج نوع السؤال الذي طرحته، ثم يمزج أربعة مسترجِعات بالنسبة التي يستحقها ذلك السؤال.

أربعة أنماط

تحت الغطاء، توجد أربع طرق مستقلة لإيجاد الكود:

الدلالي (semantic) — بحث متجهي عبر تضمينات Voyage الثنائية (binary)؛ يجد الكود بالمعنى.
النصي (text) — مطابقة المقاطع الثلاثية (trigram)؛ يجد السلاسل الحرفية، وسلاسل الأخطاء، والمعرِّفات الدقيقة.
البنيوي (structural) — استعلامات AST؛ يجد التعريفات، والتوقيعات، وبُنى اللغة.
الرسم البياني (graph) — رسم بياني للتبعيات؛ يجد الدوال المُستدعِية، والدوال المُستدعاة، ونطاق التأثير.

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

تصنيف النية

قبل تشغيل أي استرجاع، يُصنِّف مُصنِّف خفيف الوزن الاستعلام إلى واحدة من ست نوايا، بدرجة ثقة. إنه قليل التكلفة عمدًا — أساليب استدلال مرتَّبة، وتفوز أول مطابقة — لأنه يعمل على المسار الساخن ولا يضيف سوى ميلي ثانية أو اثنتين:

يبدأ بـdef ، class ، func ، import … → find_definition (ثقة 0.95)
“who calls” (من يستدعي)، “usages of” (استخدامات لـ)، “references to” (مراجع إلى) → find_references (0.90)
“impact” (التأثير)، “blast radius” (نطاق التأثير)، “what depends on” (ما الذي يعتمد على) → impact_analysis (0.90)
"string" مقتبَس أو رمز خطأ مثل traceback → exact_match (0.85–0.90)
معرِّف CamelCase أو snake_case → find_definition (0.60–0.80)
“how” (كيف)، “why” (لماذا)، “explain” (اشرح)، “architecture” (البنية المعمارية) → understand_code (0.75)
لا شيء يطابق → understand_code، ثقة منخفضة (0.40)

تحمل كل نية مجموعة أوزان عبر الأنماط الأربعة. هذه هي الأرقام الحقيقية:

النية	الدلالي	النصي	البنيوي (AST)	الرسم البياني
find_definition	0.2	0.1	0.6	0.1
find_references	0.1	0.2	0.2	0.5
understand_code	0.5	0.2	0.2	0.1
find_similar	0.4	0.3	0.2	0.1
impact_analysis	0.1	0.1	0.1	0.7
exact_match	0.0	0.9	0.1	0.0

إذًا “أين يُعرَّف parseConfig” يعتمد بشدة على AST (0.6). “كيف تعمل المصادقة” يعتمد على المتجهات الدلالية (0.5). “ما الذي يعتمد على هذا” هو تقريبًا كله رسم بياني (0.7). “ابحث عن ECONNREFUSED” هو تقريبًا كله مطابقة المقاطع الثلاثية (0.9)، مع إيقاف نموذج التضمين تمامًا — لأن التشابه الدلالي هو بالضبط الأداة الخطأ لسلسلة حرفية دقيقة.

المسار السريع، والمسار المدمَج

عندما يكون المصنِّف واثقًا — درجة ≥ 0.85 — ويكون الاستعلام عاديًا، يتخطى Maguyva الدمج تمامًا ويوجِّه مباشرة إلى النمط المهيمِن الواحد. “أين يُعرَّف X” لا يحتاج إلى أربعة مسترجِعات؛ إنه يحتاج إلى فهرس AST، الآن. يُبلَّغ عن هذا المسار المباشر باسم fusion_strategy: "direct".

يمر كل ما هو غامض عبر الدمج. تعمل الأنماط الأربعة (أو الثلاثة، في الإعداد الافتراضي) بالتوازي، ويُعيد كل واحد قائمته المُرتَّبة الخاصة، وندمجها معًا.

دمج الرتب التبادلي الموزون (Weighted Reciprocal Rank Fusion)

دمج مسترجِعات متغايرة أصعب مما يبدو: تشابه جيب تمام بقيمة 0.82، ودرجة مطابقة مقاطع ثلاثية بقيمة 137، ومركزية رسم بياني بقيمة 0.004 ليست على المقياس نفسه، لذا لا يمكنك ببساطة جمعها. يتفادى دمج الرتب التبادلي (RRF) المشكلة بتجاهل الدرجات الخام والاحتفاظ فقط بـالرتبة التي منحها كل محرك. مساهمة نتيجة من نمط واحد هي:

contribution = weight × 1 / (k + rank + 1)

حيث rank هي موضعها في قائمة ذلك النمط وk ثابت تنعيم. تُجمَع المساهمات عبر الأنماط لأي نتيجة وجدها أكثر من محرك — يطفو الاتفاق بين المسترجِعات طبيعيًا إلى القمة. نستخدم k = 40 في الإعداد الافتراضي و60 في thorough (quick يعمل دلاليًا فقط، لذا لا يتدخل الدمج هناك أبدًا). استقر عمل RRF الأصلي على k = 60 للاسترجاع العام؛ نحن نفترض قيمة افتراضية تمنح الرتب الأولى أفضلية أكبر قليلًا، مما يمنح الاتفاق الأعلى رتبة بين الأنماط وزنًا أكبر قليلًا — ولا نوصي بضبطها يدويًا.

فوق ذلك، تحمل النتائج تعزيزًا لأهمية الرسم البياني. يجب أن تتفوق عقدة محورية — دالة تعتمد عليها قاعدة الكود بأكملها — على عقدة طرفية قليلة الاستخدام حتى عند التساوي في الأهمية النصية، لذا نضرب كل مساهمة في:

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

تأتي المركزية من مقاييس PageRank/الدرجة المحسوبة مسبقًا لخط الأنابيب، ويُقيَّد التعزيز عند 1.5× كي لا تستطيع دالة شائعة أن تدفن تمامًا دالة غامضة أكثر صلة. أخيرًا، نُخفِّض رتبة النتائج من مسارات مكتبات الأطراف الخارجية (vendor)، والبناء (build)، والأرشيف، ونزيل التكرار مع الاحتفاظ بأفضل جزء لكل ملف.

ما لا يزال غير كامل

مصنّف النوايا مجموعة من التعبيرات النمطية، وليس نموذجًا مدرّبًا. يعالج أنماط الاستعلام الشائعة بقواعد استدلالية، ويعود الاستعلام الملتبس إلى understand_code ومزيج يميل إلى البحث الدلالي. وصفت نسخة سابقة من هذه المقالة انخفاض معدل الاستعلامات بلا نتائج من نحو 15% إلى أقل من 5% بأنه تحقق بالفعل. لكن مقترح ديسمبر 2025 كان يسرد في الواقع خط أساس تقديريًا وهدفًا؛ ولم تُقدّم مجموعة استعلامات أو سجل قياس يدعمان ذلك. نسحب الادعاء بتحقيق هذا التحسن؛ راجع أدلة المصدر والتصحيح. لم نستبدل المصنّف بنموذج مدرّب لأن النسخة قليلة التكلفة سريعة وكافية لدورها المقصود في التوجيه، ولأن مصنّفًا مخطئًا وواثقًا أسوأ من رجوع صريح إلى الخيار الافتراضي. الأوزان نفسها افتراضات أولية اختيرت يدويًا، وليست متعلَّمة من بيانات نقرات لا نجمعها.

اطرح سؤالك ودع النظام يختار الأداة

لا ينبغي أن يحتاج الوكيل إلى معرفة ما إذا كان يلجأ إلى grep أو التضمينات أو رسم الاستدعاء البياني — بل ينبغي أن يطرح سؤاله بعبارات بسيطة ويحصل على الإجابة الصحيحة. الدمج متعدد الأنماط هو ما يتيح لـfind_symbol، والبحث الدلالي، وتحليل التبعيات أن تتاح عبر واجهة استعلام واحدة: يقرأ النظام شكل السؤال ويُجمِّع بصمت المسترجِع الصحيح له. النموذج الذي يُقيِّم التضمينات مهم، لكن معرفة متى لا تُستخدَم مهمة أيضًا. اختيار الأداة الصحيحة لكل استعلام نوع خاص به من الجودة، وهو نوع نُفضِّل تولّيه بأنفسنا بدلًا من تحميله على المُستدعِي.

// you bring the question. it brings the tools.

مراقبة الوكلاء (Observability): الخطافات (Hooks) وAlloy وGrafana

Tue, 24 Mar 2026 00:00:00 GMT

تفشل أنظمة الوكلاء بطرق غريبة.

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

إذا لم تستطع رؤية الفرق، فأنت لا تُشغِّل نظام وكلاء فعليًا. أنت تخمِّن.

لذا بنينا مكدس مراقبة (observability) لسير عملنا الخاص: Claude Code وCodex وأحداث خطافات (hooks) Claude وأحداث إشعارات (notify) Codex وOpenTelemetry الأصلي وGrafana Alloy وGrafana Cloud في الطرف الآخر.

الجزء المثير للاهتمام ليس “لقد صنعنا لوحة معلومات (dashboard)”. الجزء المثير للاهتمام هو أننا اضطررنا إلى تقسيم القياس عن بُعد إلى تدفقين مختلفين لأن أي مصدر منفرد لم يعطنا الصورة الكاملة.

المشكلة: بيانات القياس عن بُعد للوكلاء مجزَّأة

يُصدر وكلاء البرمجة الحديثون بالفعل بعض بيانات القياس عن بُعد. هذا يساعد، لكنه غير كافٍ.

يُجيد OTEL الأصلي الإجابة عن أسئلة مثل:

كم عدد الطلبات التي أرسلناها؟
كم كلفت الجلسة؟
أين توجد مقاطع التتبع (spans) والتتبعات (traces)؟
هل ارتفع الكمون؟

لكنه أسوأ بكثير في الإجابة عن أسئلة مثل:

أي خادم MCP اعتمد عليه الوكيل؟
هل حدث هذا الفشل في Bash، أم في أداة ملفات مدمجة، أم في استدعاء MCP؟
أي مهارة (skill) فُعِّلت فعليًا؟
أي نوع من الوكلاء الفرعيين أُرسِل؟
هل كانت الجلسة تقوم بعمل مفيد، أم مجرد تخبط؟

هذا الصنف الثاني من الأسئلة أقرب إلى الخطافات (hooks) منه إلى التتبعات (traces).

لكن العكس صحيح أيضًا: بعض أهم أسئلة الأداء أقرب إلى التتبعات منها إلى الخطافات.

إذا أردت معرفة أين تراكم الكمون فعليًا، وأي مقاطع التتبع كانت بطيئة، أو ما إذا كانت الجلسة قد استهلكت الوقت في استدعاءات النموذج مقابل تنفيذ الأدوات، فأنت بحاجة إلى بيانات التتبع بقدر حاجتك إلى الأحداث الدلالية.

البنية التي انتهينا إليها

نُشغِّل مسارَي قياس عن بُعد جنبًا إلى جنب.

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

هذا الانقسام مقصود.

وهو أيضًا غير متماثل. يمنحنا Claude Code واجهة لخطافات دورة الحياة أغنى بكثير. يمنحنا Codex OTEL أصليًا بالإضافة إلى واجهة إشعارات (notify)، لذا نُطبِّع أحداث إتمام الأدوار الأقل تفصيلًا في مخطط السجل نفسه بدلًا من التظاهر بأن كلا وقتَي التشغيل يعرضان الضوابط ذاتها.

OTEL الأصلي يمنحنا التدفق الأساسي: السجلات والتتبعات من وقت التشغيل نفسه، بالإضافة إلى المقاييس حيث يُصدرها وقت التشغيل فعليًا.

أحداث الخطافات والإشعارات تمنحنا الطبقة الدلالية: أشياء مثل PreToolUse وPostToolUse وPostToolUseFailure وUserPromptSubmit وSubagentStop وSkillActivated، والبيانات الوصفية المصنَّفة التي نهتم بها فعليًا عند تصحيح سلوك الوكيل. يسهم Claude Code هنا بتدفق الأحداث الأغنى. ويسهم Codex بتدفق مُطبَّع أقل تفصيلًا لكنه لا يزال مفيدًا.

لماذا توجد الخطافات (Hooks) أساسًا

يُثري خط أنابيب الخطافات لدينا الأحداث قبل وصولها إلى Loki.

بدلًا من الاكتفاء بالقول “عملت أداة ما”، نصنِّف الحدث في حقول مثل:

tool_type: مدمجة (builtin)، وMCP، ومهارة (skill)، ووكيل (agent)، وbash
mcp_server: أي خلفية MCP تعاملت مع الاستدعاء
bash_cli: عائلة أوامر مفسّر الأوامر
subagent_type: أي نوع من المتخصصين أُرسِل
agent_tool: ما إذا كان المصدر Claude Code أم Codex

هذا يعني أننا نستطيع طرح أسئلة مهمة تشغيليًا:

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

تلك ليست حقولًا زائدة عن الحاجة. إنها الفرق بين “شعرتُ بأن الوكيل بطيء” و“أمضى الوكيل الدقائق العشر الأخيرة في عمليات git تعتمد بكثافة على مفسّر الأوامر (shell) مع معدل فشل أدوات مرتفع”.

ثمة تفصيل تنفيذي يبدو أغرب مما هو عليه: لا يزال تدفق Loki المشترك يستخدم service_name="claude-code-hooks" كتصنيف حتى عندما يأتي الحدث من Codex. الانقسام الحقيقي بين وقتَي التشغيل يحدث عند agent_tool.

لماذا تقع Alloy في المنتصف

Grafana Alloy ليست مجرد مُعيد توجيه في هذا الإعداد. إنها نقطة تطبيق السياسة.

نوجِّه تدفق OTEL الأصلي من Claude Code وCodex إلى بروكسي محلي لـAlloy عند localhost:4318، ثم نترك Alloy تنظِّف الحمولة (payload) قبل إعادة توجيهها إلى Grafana Cloud.

هذا مهم لأن القياس عن بُعد الخام للوكلاء مليء بحقول كثيرة القيم المتميزة مفيدة للتحليل لكنها فظيعة كتصنيفات مفهرَسة:

session_id
prompt_id
عدد الرموز (tokens)
المدد الزمنية
كتل معاملات الأدوات

إذا فهرست كل شيء، تحصل على انفجار تصنيفات ويوم سيء.

لذا تقوم Alloy بثلاثة أشياء من أجلنا:

تُبقي مجموعة صغيرة جدًا من التصنيفات قليلة القيم المتميزة مفهرَسة.
تنقل الحقول الصاخبة لكن المفيدة إلى بيانات وصفية منظَّمة.
تُسقِط الضجيج الخالص كليًا.

الفكرة المهمة بسيطة: راقِب أكثر، وفهرِس أقل.

لماذا يتجاوز تدفق الخطافات Alloy

تدفق الخطافات مُهيَّأ لـLoki بالفعل.

بحلول الوقت الذي يدفع فيه send_event.py حدثًا، نكون قد قررنا بالفعل أي الحقول تستحق المعاملة كتصنيف وأيها ينتمي إلى جسم JSON المنظَّم. يذهب ذلك التدفق مباشرة إلى بوابة OTLP الخاصة بـGrafana Cloud بدلًا من المرور مجددًا عبر Alloy.

لذا يمتلك النظام تقسيمًا واضحًا للعمل:

Alloy تُروِّض تدفق OTEL الأصلي الخام.
إثراء الخطافات يجعل الأحداث الدلالية قابلة للاستعلام.

هذا يُبقي البنية أبسط من محاولة إجبار كل شيء عبر مسار واحد.

ما تُظهره لوحة المعلومات فعليًا

لقطة الشاشة أدناه من إحدى لوحات معلومات المراقبة خلف سير عمل وكلائنا. إنها ليست معيارًا (benchmark)، والأرقام مجرد شريحة زمنية آنية. الهدف هو شكل البيانات: سجل النشاط، واستدعاءات الأدوات، والإخفاقات، والمطالبات، والتصنيفات حسب الوكيل، والأدوات المدمجة، واستخدام MCP، وأوامر مفسّر الأوامر، والمهارات.

الجزء المفيد هو أن لوحة المعلومات هذه تعيش على مكدس Grafana نفسه مع بقية بيانات القياس عن بُعد للوكلاء. يمكننا التصفية حسب الوكيل المصدر وعائلة الأداة والنظر عبر أوقات التشغيل دون ابتكار قصة مراقبة مختلفة لكل نظام.

إحدى لوحات المعلومات الحية خلف سير عمل وكلائنا. لقطة الشاشة هذه مجرد شريحة واحدة من مكدس Grafana مشترك يتلقى أيضًا قياسًا عن بُعد من أوقات تشغيل وأنظمة وكلائنا الأخرى. انقر على الصورة للحصول على النسخة كاملة الدقة.

لماذا تهم التتبعات (Traces) أكثر مما تبدو للوهلة الأولى

تخبرنا السجلات بفئة العمل الذي حدث. تخبرنا التتبعات بكيفية تكشُّف العمل عبر الزمن.

هذا الفرق مهم في أنظمة الوكلاء لأن “بطيء” وصف عام أكثر من اللازم ليكون مفيدًا.

يمكن للتتبع أن يخبرنا ما إذا كان الألم قادمًا من:

كمون النموذج
زمن تنفيذ الأداة
محاولات إعادة متكررة
تفاعل واحد مكلف بشكل خاص مع MCP
ذيل طويل من عمليات صغيرة بدت غير ضارة عند عزلها

عمليًا نستخدم تدفق الخطافات وتتبعات Tempo معًا.

سجلات الخطافات تجيب: أي نوع من الأشياء حدث؟
التتبعات تجيب: أين ذهب الوقت؟

هذا المزيج هو ما يحوِّل المراقبة من لوحة معلومات إلى تفسير.

أين يقع Codex

Codex جزء من المكدس نفسه، لكنه ليس مطابقًا لـClaude Code.

بالنسبة إلى Codex نربط قطعتين:

OTEL الأصلي من Codex إلى Alloy
خطاف ويب (webhook) إشعارات إلى codex_notify.py، الذي يُحوِّل إتمامات الأدوار إلى مخطط Loki نفسه الذي نستخدمه لأحداث الخطافات

هذا يمنحنا تصفية موحَّدة مثل agent_tool="codex-cli" داخل تدفق السجل نفسه.

التحفظ الصادق: حمولة إشعارات Codex أقل تفصيلًا حاليًا من حمولة خطافات Claude Code لأنها ليست نوع واجهة التكامل نفسه. في إعدادنا اليوم، يمكن تطبيع إتمامات أدوار Codex في المخطط المشترك، لكن الاستخلاص الغني أداةً بأداة لا يزال أفضل في تدفق OTEL الأصلي منه في جسر الإشعارات.

هذا ليس سببًا لتجنّب هذا المنشور. إنه بيت القصيد من المنشور. تُبنى أنظمة المراقبة الحقيقية من إشارات غير مثالية.

Grafana عبر MCP يغيِّر قواعد اللعبة

التحوّل الأكبر هو أن Grafana ليست مجرد مكان يزوره البشر في متصفح.

في هذا المستودع نعرض Grafana أيضًا عبر MCP. هذا يعني أن الوكيل يستطيع الاستعلام عن Loki وPrometheus وTempo مباشرة بدلًا من الانتظار حتى يفحص إنسان لوحات المعلومات يدويًا أولًا.

هذا يحوِّل المراقبة إلى مُدخَل نشِط في سير العمل.

يستطيع الوكيل أن يسأل:

أي عائلات أدوات فشلت أكثر في الساعة الأخيرة؟
أي خادم MCP هيمن على جلسة ما؟
هل قلَّلت التغييرات الأخيرة من إخفاقات الأدوات، أم أنها فقط نقلت العمل إلى مسارات أكثر اعتمادًا على مفسّر الأوامر (shell) بالأخطاء نفسها؟
أي التتبعات تُظهر أعلى كمون أو محاولات إعادة متكررة؟

بمجرد أن يتوفر لك ذلك، تكون قريبًا جدًا من حلقة تحسين ذاتي.

من لوحة المعلومات إلى حلقة التغذية الراجعة

هذا هو الجزء الذي نجده الأكثر إثارة للاهتمام.

بمجرد أن يصبح مكدس المراقبة قابلًا للاستعلام من طبقة الوكيل، يتوقف القياس عن بُعد عن كونه وسيلة سلبية لإعداد التقارير ويصبح إشارة تحكّم.

تبدو الحلقة كما يلي:

يُصدر نشاط الوكيل تتبعات ومقاييس وسجلات خطافات مُثراة.
تخزِّن Grafana الأدلة في Loki وTempo وPrometheus حيث توجد المقاييس.
يستعلم الوكلاء عن تلك الأدلة عبر Grafana MCP.
يحدِّد النظام مزيج الأدوات السيئ، والمهارات الهشة، والتوجيه الضعيف، أو سير العمل كثير الاعتماد على مفسّر الأوامر الذي يستمر في إنتاج أخطاء يمكن تجنّبها.
يُعدِّل الوكلاء أو المشغِّلون المطالبات، أو إعدادات الوكيل، أو أوصاف المهارات، أو قواعد التوجيه، أو صلاحية الوصول إلى الأدوات.
تُنتج الجلسة التالية نمطًا جديدًا من بيانات القياس عن بُعد، وتتكرر الدورة.

هكذا تنتقل من “لوحة معلومات مثيرة للاهتمام” إلى “نظام تحسين قابل للقياس”.

الهدف ليس تعظيم فئة أداة واحدة. الهدف هو الوصول إلى المزيج الصحيح من سطر الأوامر، والأدوات المدمجة، واستدعاءات MCP، والمهارات للعمل الذي يُنجَز فعليًا.

ما الذي يتيح لنا هذا الإجابة عنه

بمجرد أن يستقر وقتا التشغيل كلاهما على مكدس Grafana نفسه، نستطيع الإجابة عن أسئلة تشغيلية أسرع بكثير:

هل تتركّز الإخفاقات في عائلة أداة واحدة؟
هل يخلق سير العمل كثير الاعتماد على مفسّر الأوامر أخطاء يمكن تجنّبها حيث كان ينبغي وجود أداة أعلى مستوى؟
أي خوادم MCP تحمل عبء العمل؟
هل ندفع مقابل نشاط وكيل لا يُنتج تقدمًا ذا معنى؟
هل جلسة ما غير صحية بسبب النموذج، أو الأدوات، أو طبقة التنسيق؟

هذا مفيد بشكل خاص في سير عمل متعدد الوكلاء، حيث لا تخبرك عبارة “كان الوكيل مشغولًا” بأي شيء تقريبًا.

إذا استمر إرسال متخصص واحد وأنتج معدلات فشل مرتفعة، فتلك مشكلة توجيه أو صياغة مطالبة.

إذا هيمن خادم MCP واحد على كل الاستدعاءات، فقد تكون تلك بنية جيدة أو علامة على أن كل شيء آخر عبء ميت.

إذا ارتفعت إخفاقات الأدوات بينما بقيت التكلفة عالية، فلديك مشكلة تشغيلية، لا مشكلة جودة.

إذا استمر العمل عبر مفسّر الأوامر في الفشل بطرق متوقَّعة يمكن تجنّبها حيث كان ينبغي وجود أداة أعلى مستوى، فتلك إشارة منتج.

إذا نشِطت مهارة واحدة باستمرار دون أن تحسِّن النتائج، فتلك إشارة مطالبة أو توجيه.

الدرس الحقيقي

الدرس الأعمق هنا هو أن مراقبة الوكلاء تحتاج إلى قياس عن بُعد لوقت التشغيل وقياس عن بُعد لسير العمل معًا.

تخبرك بيانات القياس عن بُعد لوقت التشغيل بما فعله النظام.

تخبرك بيانات القياس عن بُعد لسير العمل بما ظن الوكيل أنه يفعله.

نحتاج إلى كليهما.

إذا احتفظت فقط بالتتبعات والعدَّادات، تفوتك الطبقة الدلالية. وإذا احتفظت فقط بأحداث الخطافات، يفوتك الكمون، ومقاطع التتبع، والصورة الأوسع لوقت التشغيل.

وإذا احتفظت بكليهما لكن لم تُغذِّهما أبدًا مرة أخرى إلى طبقة الوكيل، فلديك مراقبة، لا تكيّف.

هذا المزيج هو ما يجعل النظام قابلًا للتفسير بما يكفي للتشغيل، وقابلًا للضبط بما يكفي للتحسين.

ما لا يزال غير كامل

لا تزال هناك جوانب تحتاج إلى صقل.

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

تلك النقطة الأخيرة مقصودة. نفضِّل عرض لوحة الأجهزة الحقيقية على التظاهر بأن أنظمة الوكلاء تُفسِّر نفسها بطريقة سحرية.

لماذا يهم هذا بالنسبة إلى Maguyva

Maguyva يدور حول منح الوكلاء ذكاء كود أفضل. لكن بمجرد أن يبدأ الوكلاء فعليًا بأداء عمل مفيد، تظهر حاجة جديدة على الفور: تحتاج إلى رؤية كيف يتصرفون.

تصبح جودة البحث، وجودة التوجيه، واختيار الأدوات، وكفاءة السياق كلها مشكلات قابلة للمراقبة.

لهذا نعتقد أن الأمر يستحق الكتابة عنه. مكدس الوكلاء المستقبلي ليس مجرد مطالبات وأدوات. إنه مطالبات، وأدوات، وطبقة جمع القياسات التي تخبرك ما إذا كان كل شيء يعمل.

إذا كنت تبني سير عمل جاد للوكلاء، فالمراقبة ليست بنية تحتية اختيارية. إنها جزء من المنتج.

تعدين الحلقة: كيف تتحول التغييرات إلى ذاكرة مؤسسية

Tue, 03 Feb 2026 00:00:00 GMT

تعكس الأرقام في هذا المنشور حالة النظام وقت النشر (فبراير 2026). راجع صفحة فريقنا للأرقام الحالية.

يواجه كل فريق هندسي التحدي نفسه: تحدث التغييرات باستمرار، لكن السبب وراء تلك التغييرات يختفي. بعد ستة أشهر، يسأل أحدهم “لماذا اعتمدنا DuckDB لمراحل خط الأنابيب (pipeline)؟” والجواب يعيش فقط في رأس من اتخذ ذلك القرار — إن كان لا يزال موجودًا.

بنينا سير عمل تعدين (mining) يُغلِق هذه الحلقة. تتدفق التغييرات عبر إيداعات (commits) Git، وتُعالَج بخط أنابيب التعدين لدينا، وتصبح مدخلات سجل تغييرات منظَّمة وسجلات قرارات معمارية، ثم تُغذّي وكلاء الذكاء الاصطناعي لدينا مرة أخرى عبر استعلامات سطر الأوامر (CLI). النتيجة: ذاكرة مؤسسية يستطيع كل من البشر والذكاء الاصطناعي الوصول إليها.

المشكلة: القرارات تتبخَّر

تأمَّل سيناريو نموذجيًا. يُنشئ مطوِّر إيداعًا (commit):

feat(canonical): add DuckDB runtime for pipeline stages

يمثِّل هذا الإيداع خيارًا معماريًا مهمًا. قيَّم الفريق الخيارات، ونظر في المقايضات، واستقر على DuckDB لأسباب محدَّدة. لكن كل ذلك السياق يعيش في:

سلسلة محادثات في Slack (على الأرجح مُحذوفة)
ذاكرة أحدهم (تتلاشى بالتأكيد)
تعليق في الكود (ربما، إن كنت محظوظًا)

بعد ثلاثة أشهر، يسأل عضو فريق جديد: “هل ينبغي أن أستخدم DuckDB أم SQLite لهذه المرحلة الجديدة؟” بدون ذاكرة مؤسسية، إما أن يعيد اختراع العجلة أو يتخذ خيارات غير متسقة.

الحلقة: من الإيداعات إلى السياق

يُحوِّل سير عمل التعدين لدينا تاريخ git إلى معرفة قابلة للاستعلام:

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

البصيرة الأساسية: يتدفق كل من سجلات التغييرات والقرارات المعمارية من تاريخ git نفسه، وتُعالَج عبر خط أنابيب موحَّد. هذا يضمن ألا يُغفَل شيء.

كيف يعمل التعدين

الخطوة 1: مزامنة الفهرس

uv run orkestra mine sync

يفحص هذا الأمر تاريخ git ويبني فهرسًا لكل الإيداعات. يستخلص إشارات منظَّمة من كل إيداع:

نوع الإيداع وفق اصطلاح Conventional Commits (feat، fix، chore، docs)
النطاق (أي حزمة أو منطقة)
علامات التغيير الجذري (breaking change)
الملفات المعدَّلة ومقاييس التعقيد

الخطوة 2: فحص حالة التغطية

uv run orkestra mine status

إليك كيف تبدو حالتنا الحالية:

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15,637 إيداعًا (commits) مُعالَجًا. أصبح 476 منها قرارات معمارية. أصبح 6,799 منها مدخلات سجل تغييرات. كل إيداع مُصنَّف.

الخطوة 3: الحصول على مرشَّحين للمراجعة

uv run orkestra mine candidates --limit 50 --full

هذا يُظهِر الإيداعات التي لم تُعالَج بعد، مع سياق كامل للتصنيف:

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

تساعد الإشارات في توجيه التصنيف: يشير is_releasable_type: true إلى أن هذا ينبغي أن يظهر في سجل التغييرات. عدد الإدراجات الكبير وملفات البنية التحتية تشير إلى أنه قد يكون قرارًا معماريًا أيضًا.

الخطوة 4: تصنيف الإيداعات

يتفرَّع مساران هنا: مدخلات سجل التغييرات والقرارات المعمارية.

لمدخلات سجل التغييرات:

uv run orkestra mine classify abc123 --changelog added

هذا يُسجِّل أن الإيداع abc123 ينبغي أن يظهر في سجل التغييرات تحت فئة “مُضاف” (Added).

للقرارات المعمارية:

أولًا، احصل على معرِّف قرار حقيقي:

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

ثم صنِّف باستخدام معرِّف القرار:

uv run orkestra mine classify abc123 --decision DEC-PL-143

هذا يربط الإيداع بسجل قرار سيُنشَأ أو يُحدَّث.

للمعالجة بالدفعات (وهو ما نفعله فعليًا):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

يدعم تنسيق JSONL كلا المجالين في تمريرة واحدة:

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

الخطوة 5: توليد المخرجات

uv run orkestra registry changelog render --package <pkg>

هذا يُولِّد ملفات CHANGELOG.md لكل حزمة من السجل (ledger). سجلات التغييرات نواتج مُشتقَّة — احذفها وستتولَّد من جديد بشكل مثالي من السجل المصدر.

بنية سجل القرار

تصبح القرارات المُستخلَصة ملفات YAML ببيانات وصفية غنية:

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

يرتبط كل قرار مرة أخرى بإيداعاته المصدر. يحدِّد كل قرار الملفات التي يؤثر فيها. العلاقات بين القرارات صريحة.

تكامل سطر الأوامر: الاستعلام عن الذاكرة المؤسسية

هنا تُغلَق الحلقة. يستطيع الوكلاء الاستعلام عن القرارات عبر سطر الأوامر:

# Search by topic
uv run orkestra registry decisions search --query "retry"

يُعيد قرارات حول منطق إعادة المحاولة، ومعالجة الأخطاء، وأنماط الاستعادة.

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

يُعيد سجل القرار الكامل بسياقه، ومبرِّراته، وأثره.

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

يُظهِر الخيارات المعمارية التي اتُّخذت مؤخرًا.

كيف يستخدم الوكلاء هذا

تتضمن التعليمات الأساسية لمنسِّقنا:

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

عندما يُطلَب من وكيل تنفيذ شيء متعلق بـDuckDB، يمكنه أولًا التحقق من:

uv run orkestra registry decisions search --query "DuckDB"

واكتشاف DEC-PL-142، والتعلُّم:

لماذا اخترنا DuckDB (context)
كيفية استخدامه بشكل صحيح (agent_guidance)
أي الملفات يجب النظر إليها (files)
أي القرارات ذات الصلة موجودة (related)

لا يعيد الوكيل اختراع العجلة. إنه يبني على أنماط راسخة.

اختبار الأسئلة الثلاثة

لا يستحق كل إيداع سجل قرار. نستخدم اختبار الأسئلة الثلاثة للفرز:

هل كان اتخاذه صعبًا؟ هل تطلَّب تحليلًا كبيرًا، أو تقييم مقايضات، أو نقاشًا؟
هل تغييره مكلف؟ هل سيتطلب عكس هذا القرار إعادة عمل كبيرة؟
هل له أثر على مستوى النظام كله؟ هل يؤثر في حزم متعددة أو يُرسي أنماطًا سيتبعها آخرون؟

إذا أجاب إيداع بـ“نعم” على واحد على الأقل من هذه الأسئلة، فهو مرشَّح لاستخلاص قرار. معدلنا المعتاد: 1-4 قرارات لكل 100 إيداع (نحو 1-4%).

بالنسبة إلى مدخلات سجل التغييرات، العتبة أقل: يُسجَّل أي تغيير يراه المستخدم (ميزات، إصلاحات، تحسينات). عادةً ما تُتخطَّى المهام الداخلية، وتحديثات التوثيق، وإعادة الهيكلة. معدلنا المعتاد: 30-50 مدخلة سجل تغييرات لكل 100 إيداع.

تخزين البيانات: سجلات إلحاق فقط (Append-Only)

يستخدم نظام التعدين سجلات JSONL بإلحاق فقط لتشغيل خالٍ من التعارض بين وكلاء متعددين:

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

تنسيق JSONL مع merge=union في .gitattributes يعني أن وكلاء متعددين يستطيعون تصنيف الإيداعات في آنٍ واحد دون تعارضات دمج. كل سطر مستقل.

بوابات التحقق

قبل أي جلسة تعدين، نُشغِّل التحقق:

uv run orkestra mine validate --quick

يفحص هذا:

صحة تنسيق SHA
امتثال تنسيق معرِّف القرار
عدم وجود مدخلات مكرَّرة لنفس SHA
وجود القرارات المُشار إليها فعليًا

بعد التصنيف، نتحقق مجددًا قبل إيداع التغييرات.

لماذا يهم هذا

تحلّ حلقة التغذية الراجعة التي بنيناها عدة مشكلات:

لأعضاء الفريق الجدد: بدلًا من سؤال “لماذا فعلنا X؟”، يستطيعون البحث في سجل القرارات. السياق محفوظ.

لوكلاء الذكاء الاصطناعي: لا يعملون في فراغ. يستطيعون الاستعلام عن المعرفة المؤسسية قبل تقديم التوصيات. عندما يُطلَب منهم إضافة مرحلة خط أنابيب جديدة، يستطيعون اكتشاف نمط DuckDB واتّباعه.

للاتساق المعماري: القرارات صريحة وقابلة للبحث. عندما يقترح أحدهم نهجًا يناقض قرارًا قائمًا، يستطيع النظام إظهار التعارض.

لتوليد سجل التغييرات: ملاحظات الإصدار ليست هرولة في اللحظة الأخيرة. إنها نتاج ثانوي لتصنيف مستمر أثناء التطوير.

للتهيئة: يرث الوكلاء الجدد السياق الكامل لقاعدة الكود. لا يرون الكود فقط — بل يرون القرارات التي شكَّلته.

الحالة الراهنة

اعتبارًا من اليوم:

15,637 إيداعًا عولِجت عبر خط الأنابيب
476 قرارًا معماريًا استُخلِصت ووُثِّقت
6,799 مدخلة سجل تغييرات سُجِّلت
تغطية 100% عبر كلا المجالين

كل إيداع منذ أن بدأنا صُنِّف. الذاكرة المؤسسية كاملة وقابلة للاستعلام.

البدء

إذا أردت تنفيذ شيء مماثل:

ابدأ بإيداعات تتبع اصطلاح conventional commits. يعمل خط أنابيب التعدين بشكل أفضل عندما تحمل الإيداعات بادئات منظَّمة (feat:، fix:، chore:).
حدِّد مجالاتك. نستخدم مجالات مثل pipeline، agent-design، observability، data-modeling. تنظِّم هذه المجالات القرارات حسب التخصص.
ابنِ عادة التصنيف. يعمل التعدين عندما تصنِّف الفرق الإيداعات بانتظام. تساعد المعالجة بالدفعات بمساعدة LLM على التوسّع.
اجعل القرارات قابلة للاستعلام. تتراكم القيمة عندما يستطيع الوكلاء البحث في القرارات عبر سطر الأوامر. صمِّم مخرجك ليكون قابلًا للاستهلاك آليًا.
أغلِق الحلقة. ينبغي أن تؤثر القرارات في العمل المستقبلي. أدرِج مراجع القرارات في تعليمات الوكيل وقوائم مراجعة الكود.

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

سير عمل التعدين جزء من محرك التنسيق لدينا، وتحديدًا وحدة محرك السياق في حزمة التنسيق لدينا.

تعدين المهارات: من 3,500 مرشَّح إلى 466 قدرة

Tue, 27 Jan 2026 00:00:00 GMT

تعكس الأرقام في هذا المنشور حالة النظام وقت النشر (يناير 2026). راجع صفحة فريقنا للأرقام الحالية.

مشكلة الـ3,500 مهارة

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

إجابتنا: حلقة تعدين واستيعاب منهجية.

الأرقام اليوم

بعد نحو ثلاثة أشهر فقط من إطلاق Anthropic لـAgent Skills في 16 أكتوبر 2025، إليك أين كنا عندما نُشِر هذا المنشور في 27 يناير 2026:

المقياس	العدد
المرشَّحون المحدَّدون	أكثر من 3,500
المهارات المُعتمَدة	466
مهارات البائعين	373
المهارات الداخلية	93
البائعون النشِطون	أكثر من 25
متوسط الرموز لكل مهارة	2,834
الأدوات المُشار إليها	89
الوسوم الفريدة	635

راجعنا أكثر من 3,500 مرشَّح للمهارات. اعتمدنا 466 منها. ذلك معدل اعتماد 13% - وتلك الانتقائية مقصودة.

نظام طبقات المعرفة

لم تُخلَق كل المهارات متساوية. ننظِّمها في خمس طبقات معرفة (K0-K4)، تمثِّل كل واحدة نطاق تطبيق مختلفًا:

K0: الأساسيات (عالمية)

مهارات ينبغي أن يمتلكها كل وكيل. تمثِّل هذه قدرات “المفكِّر الجيد” التي تعمل في أي مكان.

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

مهارات K0 قابلة للنقل إلى أي مشروع، أي مجال، أي مكدس تقني. تُرمِّز أنماطًا معرفية عالمية.

K1: الهويات (التخصص)

مهارات “المهندس الجيد” أو “الباحث الجيد” التي تُطبَّق عبر المشاريع ضمن تخصص واحد.

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: المجالات (خبرة الموضوع)

مهارات “خبير قواعد البيانات الجيد” أو “مهندس الأمان الجيد” القابلة للنقل ضمن مجال واحد.

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: المكدسات التقنية (Stacks)

مهارات “مستخدم Supabase الجيد” أو “مطوِّر Cloudflare الجيد” لمكدسات تقنية محدَّدة.

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: المشروع (المؤسسة)

مهارات خاصة بمؤسستنا وسير عملنا.

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

حلقة التعدين

المرحلة 1: الاكتشاف

تأتي المهارات من كل مكان:

مستودعات البائعين: تنشر AWS، وAnthropic، وCloudflare، وSupabase، ومساهمو المجتمع مجموعات مهارات. نتتبَّع أكثر من 25 جذر بائع.

مشاريع المجتمع: GitHub مليء بقوالب Claude Code، وأنماط الوكلاء، وتعريفات سير العمل.

الأنماط الداخلية: بينما يحل فريقنا المشكلات، تظهر أنماط. تُصاغ هذه رسميًا في مهارات.

تعدين التوثيق: غالبًا ما يحتوي التوثيق التقني على مهارات ضمنية - إجراءات، وقوائم مراجعة، وأشجار قرار.

الاكتشاف مستمر. نستخدم قائمة انتظار مهارات لتتبُّع المرشَّحين قبل التقييم الرسمي.

المرحلة 2: التقييم

يمر كل مرشَّح بالمعيار نفسه:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

يجب أن تنجح جميع المعايير الخمسة للمنتج. لهذا يُرفَض 87% من المرشَّحين.

ثم يمر كل مرشَّح بمراجعة ثقة منفصلة. لا نعامل مستودع بائع رسمي، ومشرف مجتمع معروف جيدًا، ومستودع GitHub عشوائي كمصادر حقيقة متكافئة.

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

يحصل البائعون الموثوقون على مراجعة مصدر أخف، لكن دون إعفائهم من التدقيق. المصادر غير الموثوقة أو المجهولة تخضع لتدقيق يدوي أعمق، ولا نُنفِّذ النصوص البرمجية المُجمَّعة معها حتى تُقرَأ، ويُحدَّد نطاقها، وتُصنَّف بأنها آمنة.

تحليل الفجوات: قبل الاعتماد، نبحث في سجلنا:

uv run orkestra skills search "<capability>"

إذا كنا نمتلكها بالفعل، لا نحتاج إليها. إذا كان لدينا شيء قريب، قد ندمج بدلًا من أن نعتمد.

تقييم العمق والمعايير: نُقيِّم أيضًا مدى استفادة المهارة المرشَّحة من جميع إمكانات نموذج مهارات الوكلاء. لا يزال SKILL.md منفردًا مفيدًا، لكن المهارات الأعمق أكثر قيمة عندما تفصل التعليمات عن المراجع، والنصوص البرمجية، والأصول بالطريقة التي يشجِّعها agentskills.io.

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

يمكن أن ترفع نجوم GitHub درجة المصداقية قليلًا، لكنها لا تُنقِذ أبدًا مهارة سطحية أو غير آمنة. مستودع بنجوم كثيرة مع SKILL.md غامض واحد ونصوص برمجية معتمة يحصل على درجة أقل من مستودع أصغر بوصف دقيق، وreferences/ مُنسَّق، وأدوات مساعدة صغيرة تؤدي كل منها مهمة محددة تستفيد فعليًا من كامل قدرة المهارة.

التحليل البنيوي: نفحص جودة المهارة:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

إذا تضمَّن المرشَّح نصوصًا برمجية، تصبح تلك المراجعة أكثر صرامة. المهارة الجيدة ليست مفيدة فقط؛ يجب أن تكون واضحة، ومحدودة، وآمنة لتُسلَّم إلى وكيل. مرشِّح السلامة هذا وحده يستبعد شريحة ذات معنى من مرشَّحين مثيرين للاهتمام لولا ذلك.

المرحلة 3: الاستيعاب

عندما تجتاز مهارة التقييم، تدخل السجل. لكن المهارات لا تُعتمَد أبدًا دون تغيير. تُعدَّل لتناسب نظامنا.

التعديلات عند الاعتماد:

تطبيع البيانات الوصفية: تحصل كل مهارة على مخطط frontmatter الخاص بنا
تعيين طبقة K: تُوضَع المهارات في طبقة المعرفة المناسبة
إثراء الوسوم: تُضاف وسوم للاكتشاف
تصريح الأدوات: يُعلَن عن الأدوات المسموح بها صراحةً
مواءمة الأقسام: تُعاد هيكلة المحتوى ليطابق قالبنا

مهارة YAML نموذجية بعد الاستيعاب:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

المرحلة 4: تعيين النطاق

تُعيَّن المهارات إلى نطاقات - فئات تُحدِّد أي الوكلاء يُحمِّل أي المهارات:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

يُصرِّح الوكلاء عن نطاقاتهم، وتُعيَّن المهارات تلقائيًا:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

المرحلة 5: التجسيد

لا تعيش المهارات كـYAML في الإنتاج. تُصيَّر إلى ملفات SKILL.md التي يستطيع Claude Code تحميلها:

uv run orkestra sync

يقوم هذا الأمر بما يلي:

يقرأ كل تعريفات YAML للمهارات
يُصيِّرها عبر قوالب Jinja
يكتب ملفات SKILL.md إلى .claude/skills/
ينظِّم حسب طبقة K (foundations/، identities/، domains/، stacks/، project/)

بنية المخرَج النهائية:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

نمط النطاق الكامن (Dormant)

أحد أقوى أنماطنا هو مهارات “مُعتمَدة لكن غير محمَّلة”. نسمّي هذه النطاقات الكامنة.

تأمَّل مهارات الحوسبة العلمية من مستودع k-dense-scientific. اعتمدنا أكثر من 120 مهارة تغطي المعلوماتية الحيوية، والكيمياء، والحوسبة الكمومية، والمعلوماتية السريرية. لكن معظم وكلائنا لا يحتاجون إلى الالتحام الجزيئي أو تحليل التعبير الجيني.

بدلًا من تحميل كل الـ120 مهارة في كل وكيل (مما يُضخِّم نوافذ السياق)، نحن:

نعتمد المهارات بنطاق محدَّد (مثل bioinformatics)
نُبقيها كامنة - مُسجَّلة لكن غير محمَّلة
نُفعِّلها فقط عندما يُصرِّح وكيل عن ذلك النطاق

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

يتيح لنا هذا النمط امتلاك 466 مهارة في السجل بينما يُحمِّل الوكلاء عادةً 40-60 مهارة ذات صلة فقط.

أنواع المهارات

تأتي المهارات في ثلاثة أنماط معرفية:

سير عمل (Workflow)

خطوات إجرائية مرتَّبة: “1. افعل X، 2. ثم Y، 3. أخيرًا Z”

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

انضباط (Discipline)

ضوابط سلوكية: “افعل X دائمًا”، “لا تفعل Y أبدًا”، “فضِّل Z”

type: discipline
# Examples: test-first-discipline, evidence-based-completion

قائمة مراجعة (Checklist)

معايير تحقق: “أكِّد X”، “تحقَّق من Y”، “افحص Z”

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

بوابات الجودة

يجب أن تجتاز كل مهارة التحقق قبل إطلاقها:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

يجب أن تكون الأوصاف بين 50-400 حرف مع عبارات تفعيل (“استخدم عندما…”، “عندما تحتاج إلى…”) كي يعرف Claude Code متى يقترحها.

نتحقق باستمرار:

uv run orkestra validate --show-warnings

منظومة المزوِّدين

نحصل على مهارات المزوِّدين البالغ عددها 373 من:

المزوِّد	المهارات	المجال
AWS Agent	19	خدمات سحابية
Anthropic	12	توليد المستندات
Cloudflare	8	الحوسبة الطرفية (edge)
Supabase	5	قواعد البيانات
k-dense	أكثر من 100	الحوسبة العلمية
silvainfm	4	علم البيانات
Java Developer Kit	أكثر من 45	Spring/Java
Vercel	1	أتمتة المتصفح

يُصرَّح كل جذر بائع في metadata.yaml:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

عندما يعمل orkestra sync، تُربَط مهارات البائعين بروابط رمزية إلى .claude/skills/vendor/ بمساحة اسم مزوِّدها.

ما تعلمناه

الانتقائية تُؤتي ثمارها. من المُغري اعتماد كل ما يبدو مفيدًا. لكن كل مهارة تكلِّف رموزًا. بمتوسط 2,834 رمزًا لكل مهارة، يضر التضخم بسرعة. معدل اعتمادنا البالغ 13% يُبقي الوكلاء رشيقين.

البنية تُمكِّن الاكتشاف. نظام طبقات K ليس مجرد تنظيم - إنه يتعلق بقابلية النقل. يمكن إعادة استخدام مهارات K0 في أي مكان. مهارات K4 خاصة بالمشروع عمدًا. هذا الوضوح يساعد كلًا من البشر والوكلاء على إيجاد ما يحتاجونه.

النطاقات الكامنة تتوسَّع. يمكنك اعتماد مئات المهارات دون تحميلها كلها. تتيح لك النطاقات بناء سجل شامل مع إبقاء نوافذ سياق الوكيل الفردية قابلة للإدارة.

التعديل عند الاعتماد ضروري. نادرًا ما تناسب مهارات البائعين الخام نظامك. عملية الاستيعاب - إضافة بيانات وصفية، وتعيين طبقات، وإثراء الوسوم - تجعل المهارات الخارجية تعمل داخليًا.

التعدين مستمر. يستمر رقم الـ3,500 في النمو. تظهر مستودعات بائعين جديدة. تنبثق أنماط مجتمعية. تترسخ إجراءات العمل الداخلية. الحلقة لا تتوقف أبدًا.

ما التالي

نعمل على عدة تحسينات:

اكتشاف الفجوات آليًا: تنبيه عندما يمكن معالجة إخفاقات وكيل شائعة بمهارة غير مُعتمَدة
سير عمل تقادم المهارات: عملية رسمية لسحب المهارات التي حلَّت محلها أخرى أو لم تعد تُستخدَم
تبعيات عبر المهارات: تصريح صريح لمتطلبات المهارة المسبقة
تحليلات الاستخدام: تتبُّع أي المهارات يستدعيها الوكلاء فعليًا مقابل مجرد تحميلها

حلقة تعدين المهارات بنية تحتية. إنها ليست برّاقة. لكنها ما يجعل 41 وكيلًا يعمل بتماسك مع 466 قدرة مع البقاء ضمن حدود السياق.

تلك هي قصة كيف يصبح 3,500 هو 466. ليس بتجاهل 3,000 - بل بتقييمها منهجيًا واعتماد ما ينجح فقط.

تريد رؤية نظام المهارات في العمل؟ راجع uv run orkestra skills list لاستكشاف سجلنا الحالي.

الإفصاح التدريجي: نوافذ سطر الأوامر (CLI) إلى أنظمة الوكلاء

Tue, 20 Jan 2026 00:00:00 GMT

تعكس الأرقام في هذا المنشور حالة النظام وقت النشر (يناير 2026). راجع صفحة فريقنا للأرقام الحالية.

أنظمة الوكلاء معتِمة بالتصميم. تتخذ قرارات، وتستدعي أدوات، وتنسِّق العمل عبر عشرات المتخصصين. لكن عندما يسوء شيء ما — أو عندما تريد ببساطة أن تفهم ما يحدث — أين تنظر؟

الجواب هو الإفصاح التدريجي: واجهة متعددة الطبقات تكشف بالضبط عن قدر التعقيد الذي تحتاجه، بالضبط عندما تحتاجه.

مشكلة العتامة

قد يمتلك نظام تنسيق وكلاء حديث:

أكثر من 40 وكيلًا متخصصًا، لكل منهم قدرات مميزة
أكثر من 700 مهارة تمتد عبر الأتمتة الداخلية وتكاملات البائعين
أكثر من 470 قرارًا معماريًا يُشكِّل السلوك
عشرات خوادم أدوات MCP التي توفِّر قدرات خارجية

هذا التعقيد مقصود. يحتاج الوكلاء إلى وصول لسياق غني — معرفة المجال، وذكاء الكود، ومخططات قواعد البيانات — لاتخاذ قرارات جيدة. لكن ذلك الغنى نفسه يخلق مشكلة رؤية.

كيف تعرف أي وكيل يتعامل مع ترحيلات قاعدة البيانات؟ ما القرارات التي شكَّلت سلوك ترتيب نظام البحث؟ أي الأدوات يستطيع مستشار البنية المعمارية الوصول إليها؟

دون وصول منظَّم، يُترَك لك قراءة كود المصدر أو الأمل في أن يكون التوثيق حديثًا.

الإفصاح التدريجي كبنية

الإفصاح التدريجي ليس مجرد نمط واجهة مستخدم. إنه مبدأ معماري: نظِّم المعلومات في طبقات، كل واحدة أعمق من سابقتها، كي يستطيع المستخدمون التوقف عند المستوى الذي يجيب عن سؤالهم.

بالنسبة إلى أنظمة الوكلاء، يُترجَم هذا إلى أوامر سطر أوامر بأعماق متزايدة:

المستوى	الأمر	السؤال المُجاب عنه
1	`orkestra system status`	هل كل شيء سليم؟
2	`orkestra agents list`	من هم الوكلاء المتاحون؟
3	`orkestra agents info <name>`	ماذا يفعل هذا الوكيل؟
4	`orkestra decisions search`	لماذا يعمل بهذه الطريقة؟
5	أدوات Maguyva MCP	أرِني الكود.

يجيب كل مستوى عن سؤال متابعة طبيعي. نادرًا ما تحتاج إلى القفز مباشرة إلى المستوى 5.

المستوى 1: سلامة النظام

السؤال الأول هو دائمًا: هل كل شيء يعمل؟

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

أمر واحد. أربعة أرقام. كافٍ لمعرفة أن النظام مُهيَّأ وأن السجلات تحتوي على بيانات.

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

المستوى 2: جرد الوكلاء

بمجرد أن تعرف أن النظام سليم، السؤال التالي هو: ما المتاح؟

$ orkestra agents list

هذا يُعيد بيانات منظَّمة — أسماء الوكلاء، وأوصافهم، وتفضيلات النموذج، وتغطية المجال. المخرَج JSON افتراضيًا، مما يسهِّل تمريره عبر أنبوب إلى jq للتصفية:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

تريد وكلاء يتعاملون مع عمل قاعدة البيانات؟ أمر البحث يُضيِّق النطاق:

$ orkestra agents search "database"

هذا يفحص الأسماء، والأوصاف، والقدرات. تجد المتخصص الصحيح دون قراءة 40 تعريف وكيل.

المستوى 3: الغوص العميق في الوكيل

وجدت وكيلًا يبدو ذا صلة؟ يكشف أمر info كل شيء:

$ orkestra agents info architecture-advisor

يتضمَّن المخرَج:

البيانات الوصفية: الاسم، والفئة، وتفضيل النموذج، والوصف
المجالات: أي مجالات معرفة يغطيها هذا الوكيل
الهوية: سمات الشخصية (architect، strategist، knowledge-architect)
أدلة الأدوات: أي توثيق أدوات يُحقَن في السياق
الأدوات: القائمة الكاملة لأدوات MCP المتاحة لهذا الوكيل

إليك عيّنة مما تراه:

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

هذا يخبرك بالضبط بما يستطيع الوكيل فعله. لا حاجة إلى كود المصدر.

المستوى 4: علم آثار القرارات

يتصرف الوكلاء وفق قرارات موثَّقة. عندما تحتاج إلى فهم لماذا يعمل شيء ما بطريقة معينة، سجل القرارات هو مصدر الحقيقة.

$ orkestra decisions search "agent"

هذا يُعيد القرارات المعمارية المطابقة:

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

لكل قرار سجل منشأ كامل — متى اتُّخذ، ولماذا، وأي مقايضات جرى النظر فيها، وأي إيداعات (commits) نفَّذته:

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

هذا توثيق معماري يبقى حديثًا لأنه مُعدَّن من الإيداعات، لا مُصانًا يدويًا.

المستوى 5: ذكاء الكود المباشر

عندما تحتاج إلى رؤية التنفيذ الفعلي — لا بيانات وصفية عنه — توفِّر أدوات MCP الخاصة بـMaguyva وصولًا مباشرًا.

من داخل جلسة وكيل:

mcp__maguyva__intelligent_search
  query: "agent context loading"

هذا يوجِّه تلقائيًا عبر البحث الدلالي والنصي وAST لإيجاد الكود ذي الصلة. لرموز محدَّدة:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

لتحليل التبعيات:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

هذه ليست مجرد بدائل لـgrep. إنها واعية بالرسم البياني، ومفهرَسة دلاليًا، ومتكاملة مع ذكاء الكود نفسه الذي يُشغِّل الوكلاء أنفسهم.

بحث موحَّد عبر السجلات

أحيانًا لا تعرف أي سجل يحمل الإجابة. البحث الموحَّد يمتد عبر كل شيء:

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 تطابقًا عبر خمسة سجلات. يخبرك الملخَّص أين تتعمَّق. أزِل --summary للنتائج التفصيلية، أو أضِف --limit 5 لإبقاء المخرَج قابلًا للإدارة.

لماذا يهم هذا

الإفصاح التدريجي لا يتعلق فقط بالراحة. إنه يُغيِّر كيفية تفاعلك مع الأنظمة المعقدة.

يصبح التصحيح ممكنًا عمليًا. عندما يتخذ وكيل قرارًا غير متوقَّع، لا تبحث عبر السجلات بـgrep. تتحقق من الأدوات التي يستطيع الوصول إليها (agents info)، والقرارات التي تُشكِّل سلوكه (decisions search)، وتتبَّع التنفيذ إن لزم (intelligent_search).

تتسارع التهيئة الأولية. لا يحتاج أعضاء الفريق الجدد إلى قراءة قاعدة الكود بأكملها. يبدؤون بـsystem status، ويستكشفون بـagents list، ويتعمَّقون فقط عندما يصادفون شيئًا لا يفهمونه.

يبقى التوثيق حديثًا. لأن سطر الأوامر يقرأ من السجلات نفسها التي تُهيِّئ الوكلاء، المخرَج دقيق دائمًا. لا يوجد انحراف بين ما يقوله التوثيق وما يفعله النظام.

سطر الأوامر كواجهة

كان بإمكاننا بناء لوحة معلومات على الويب. كان بإمكاننا كتابة توثيق مطوَّل. بدلًا من ذلك، بنينا سطر أوامر يقرأ من مصدر الحقيقة.

لسطر الأوامر مزايا:

قابل للتركيب: وجِّه المخرَج عبر jq، وادمجه مع السكربتات
قابل للبرمجة: أتمِت الفحوصات، وولِّد التقارير
سريع: لا تحميل صفحات، ولا تدفقات مصادقة
دقيق: يقرأ الإعداد الفعلي، لا تمثيلًا مُخزَّنًا مؤقتًا

بالنسبة إلى الأنظمة التي تهم فيها الصحة أكثر من الجمالية، يفوز سطر الأوامر.

بناء إفصاحك التدريجي الخاص

إذا كنت تبني أنظمة وكلاء، فكِّر في كيفية فحص المستخدمين لها:

ابدأ بفحوصات السلامة. أمر واحد يخبرك ما إذا كانت الأمور تعمل.
وفِّر طرق عرض الجرد. اسرد ما هو موجود قبل شرح ما يفعله.
مكِّن الاستعلامات الموجَّهة. البحث يتفوق على التصفح على نطاق واسع.
اعرض المصدر. دَع المستخدمين يتتبَّعون القرارات إلى أصولها.
اتصل بذكاء الكود. في النهاية، يحتاج المستخدمون إلى رؤية التنفيذ.

تجيب كل طبقة عن سؤال متابعة. ابنِها وفق مدى تكرار استخدامها — يتوقف معظم المستخدمين عند الطبقة 2 أو 3. المستخدمون المتقدِّمون فقط يصلون إلى الطبقة 5.

الهدف ليس كشف كل شيء. إنه كشف بالضبط ما هو ضروري، بالضبط عندما يكون ضروريًا. هذا هو الإفصاح التدريجي مُطبَّقًا على بنية الوكلاء.

الحقائق الأساسية (Ground Truths): ترسيخ وكلاء الذكاء الاصطناعي في الواقع

Tue, 13 Jan 2026 00:00:00 GMT

تعكس الأرقام في هذا المنشور حالة النظام وقت النشر (يناير 2026). راجع صفحة فريقنا للأرقام الحالية.

وكلاء الذكاء الاصطناعي قادرون بشكل ملحوظ. يستطيعون الاستدلال، والتوليف، والتوليد. لكن لديهم ضعفًا جوهريًا: إنهم يختلقون الأشياء. ليس بخبث، بل بثقة. قد يخترع الوكيل معاملات API غير موجودة، أو يشير إلى إعدادات لم تُعرَّف قط، أو يطبِّق أنماطًا من بيانات تدريبه تناقض بنيتك المعمارية الفعلية.

التخفيف المعتاد هو “امنح الوكيل سياقًا أكثر”. لكن السياق يمكن أن يكون متناقضًا. يبتعد التوثيق عن التنفيذ. التعليقات تكذب. حتى الكود يمكن أن يُضلِّل عندما يُقرَأ دون فهم القصد.

احتجنا إلى شيء أكثر صراحة. شيء لا يمكن تجاهله أو إساءة تفسيره. شيء يُرسِّخ الوكلاء في واقع قابل للتحقّق.

نسمّيها الحقائق الأساسية (Ground Truths).

ما هي الحقيقة الأساسية؟

الحقيقة الأساسية هي عبارة واقعية صريحة وخاضعة لإدارة الإصدارات يجب أن يحترمها الوكلاء. إنها ليست توثيقًا. إنها ليست تعليقًا. إنها كيان من الدرجة الأولى في النظام يحتوي على:

معرِّف فريد (مثل GT-MAG-015 أو GT-MAG-036)
حالة دورة حياة (current، أو tentative، أو deprecated)
نطاق (على مستوى المنصة، أو خاص بالحزمة، أو محصور بمجال)
دليل (مسارات ملفات، أو روابط، أو مراجع تُثبِت العبارة)
توجيه للوكيل (تعليمات صريحة بما يجب فعله وما يجب تجنّبه)

إليك مثالًا من منصة ذكاء الكود Maguyva لدينا:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

هذا ليس نثرًا. إنه عقد. عندما يصادف الوكيل هذه الحقيقة الأساسية، فإنه يعرف:

السلوك الافتراضي حتمي (نتائج فارغة، لا تخمينات قائمة على التشابه)
توجد معاملات محدَّدة (find_similar، exact_match) بسلوكيات مُعرَّفة
الدليل موجود في ملفات محدَّدة يمكن التحقق منها
جرى التحقق من العبارة في تاريخ محدَّد

تشريح سجل الحقائق الأساسية

تعيش الحقائق الأساسية في سجلات YAML تحت ai_assets/reference/ground_truths.yaml. يمكن أن تمتلك كل حزمة أو مجال سجله الخاص. البنية هي:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

يتضمن السجل بيانات وصفية عن المجموعة نفسها، وإعداد العرض لتوليد التوثيق، والعبارات نفسها. تتبع كل عبارة مخططًا صارمًا يُتحقَّق منه بنماذج Pydantic:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

كيف يصل الوكلاء إلى الحقائق الأساسية

تُعرَض الحقائق الأساسية عبر قنوات متعددة:

1. التوثيق المُصيَّر

يحوِّل أمر orkestra sync سجلات YAML إلى markdown قابل للقراءة:

uv run orkestra sync

هذا يُولِّد ملفات GROUND_TRUTHS.md تُدرَج ضمن سياق الوكيل. يُجمِّع المخرَج المُصيَّر العبارات حسب الحالة والفئة:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. بحث سطر الأوامر (CLI)

يستطيع الوكلاء ذوو وصول إلى مفسّر الأوامر (shell) البحث عن الحقائق الأساسية برمجيًا:

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

تُقيِّم دالة البحث التطابقات عبر حقول متعددة بأهمية نسبية موزونة:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. تركيب السياق

عندما تُصيَّر تعريفات الوكلاء من YAML، يمكن لسياقهم أن يشير إلى سجلات الحقائق الأساسية:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

هذا يضمن تحميل الحقائق الأساسية ذات الصلة قبل أن يبدأ الوكيل العمل.

فئات الحقائق الأساسية

عند النظر عبر سجلاتنا، تتجمَّع الحقائق الأساسية في عدة أنماط:

مبادئ المنتج

قيود على ما هو عليه المنتج وما ليس عليه:

“Maguyva is read-only with respect to user repositories; the only non-rebuildable asset is the paid embeddings cache.” (GT-MAG-001)

حدود البنية المعمارية

أين تعيش المسؤوليات ولماذا:

“Pipeline and Maguyva boundaries are intentional: pipeline is reusable, Maguyva holds code-specific logic, and CQRS separates stage writes from server reads.” (GT-MAG-006)

قواعد مكافحة الهلوسة

توجيهات إلزامية صريحة تُبقي عقود الأدوات حتمية بدلًا من مُستنتَجة:

“Fuzzy symbol matching is opt-in via find_similar=true. Default behavior returns empty results for non-existent symbols; exact_match=true enforces strict matching and disables all fuzzy fallbacks.” (GT-MAG-015)

بوابات الجودة

معايير يجب الحفاظ عليها:

“Changes to shared infrastructure (post_filters.py, relationship extractors, shared handlers) MUST be validated against ALL supported languages via full manifest generation before commit. A single-language validation is insufficient for shared code.” (GT-MAG-036)

أنماط الكود

متطلبات التنفيذ:

“Use asyncio.to_thread() for CPU-bound work in async contexts; the deprecated loop.run_in_executor() pattern should not be used in new code.” (GT-MAG-018)

دورة حياة الحقيقة الأساسية

الحقائق الأساسية ليست ثابتة. تتطور عبر دورة حياة مُعرَّفة:

مبدئية (Tentative)

حقيقة مقترَحة قيد التقييم. تُسجَّل العبارة لكنها قد تتغيّر:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

حالية (Current)

حقيقة مُتحقَّق منها يجب أن يحترمها الوكلاء. جرى التحقق من الدليل:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

مُتقادِمة (Deprecated)

حقيقة لم تعد تنطبق. تُبقى للمرجعية التاريخية مع إشارة إلى ما حلّ محلها:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

لماذا لا يكفي التوثيق فقط؟

يخدم التوثيق غرضًا مختلفًا. إنه يشرح. إنه يعلِّم. يمكن أن يكون غامضًا، ويمكن أن يستخدم مؤهِّلات مثل “عمومًا” أو “عادةً”.

لا يمكن أن تكون الحقائق الأساسية غامضة. إنها تأكيدات. إما أن تنطبق أو لا تنطبق.

تأمَّل الفرق:

التوثيق: “تُعيد الواجهة البرمجية (API) عمومًا نتائج فارغة عندما لا يُعثَر على رمز، رغم أن المطابقة التقريبية قد تكون مُفعَّلة في بعض الإعدادات.”

الحقيقة الأساسية: “السلوك الافتراضي يُعيد نتائج فارغة للرموز غير الموجودة؛ exact_match=true يفرض المطابقة الصارمة ويُعطِّل كل بدائل المطابقة التقريبية.”

الأول مفيد للبشر الذين يتعلمون النظام. الثاني قابل للتنفيذ للوكلاء الذين يتخذون القرارات.

توجيه الوكيل: افعل وتجنّب

تتضمن بعض الحقائق الأساسية توجيهًا صريحًا للوكيل:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

هذا يُزيل الغموض. الوكيل الذي يقرأ هذا يعرف ليس فقط ما هو صحيح، بل الإجراءات التي تستلزمها تلك الحقيقة.

التحقق والصيانة

تتطلب الحقائق الأساسية صيانة. نتتبَّع:

last_verified: متى أكَّد أحدهم أن العبارة لا تزال صحيحة
evidence: الملفات التي تُثبِت العبارة (يمكن التحقق من وجودها)
source: من أين نشأت الحقيقة (فحص سطر الأوامر، مراجعة معمارية، تعلُّم بعد حادثة)

حقيقة أساسية بتواريخ تحقق قديمة أو روابط دليل معطَّلة هي إشارة للتحقيق. إما أن الحقيقة لا تزال صالحة وتحتاج إعادة تحقق، أو أن الواقع تغيَّر وتحتاج الحقيقة إلى تحديث.

أمثلة حقيقية من الإنتاج

حدود الأمان

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

تمنع هذه الحقيقة الأساسية فئة من “تحسينات الأمان” المضلَّلة التي كانت ستُعطِّل المنتج.

دقة وقت الاستخلاص

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

جاء هذا من تجربة مؤلمة. كان الوكلاء يرقِّعون حزم اللغات الفاشلة بإضافة مرشِّحات خاصة بالمُتحقِّق فقط تجعل نتائج منظومة الاختبار تبدو أفضل، بينما لا يزال مُستخلِص Maguyva الحي يُصدر الحواف الخاطئة. تفرض القاعدة إعادة الإصلاحات إلى المسار الحقيقي: إعداد YAML، أو الاستعلامات، أو المعالِجات.

التصفية متعددة الطبقات

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

هذا يمنع الوكلاء من إضافة مرشِّحات في المكان الخطأ، وهو خطأ شائع تسبَّب في تراجعات في الدقة.

التكامل مع نظام التنسيق

الحقائق الأساسية طبقة واحدة من نظام سياق أوسع:

القرارات المعمارية (ADRs) - تُسجِّل لماذا اخترنا النهج A بدلًا من B
الحقائق الأساسية - تنص على ما هو صحيح قطعيًا الآن
أنماط المجال - تصف كيفية فعل الأشياء بشكل صحيح
الأنماط المضادة - تصف ما يجب تجنّبه ولماذا

الوكيل الذي يعمل في النظام لديه وصول إلى الأربعة جميعًا. توفِّر الحقائق الأساسية المرساة الواقعية، بينما تشرح القرارات التاريخ، وتوجِّه الأنماط التنفيذ، وتحذِّر الأنماط المضادة من المزالق.

قياس الأثر

منذ تقديم الحقائق الأساسية، لاحظنا:

دورات أقل من “أصلِح الإصلاح المُهلوَس”
اتخاذ قرارات أكثر ثقة من الوكلاء عندما تكون الوقائع واضحة
مراجعات طلبات سحب (PR) أفضل لأن التوقعات صريحة
وقت تهيئة أقصر للوكلاء الجدد (والبشر أيضًا)

يُؤتي الاستثمار في صيانة الحقائق الأساسية ثماره بتقليل التصحيح وتوضيح حدود النظام.

البدء

لإضافة حقيقة أساسية إلى نظامك:

أنشئ ground_truths.yaml في دليل ai_assets/reference/ الخاص بحزمتك
عرِّف البيانات الوصفية وإعداد العرض
أضِف العبارات وفق المخطط
شغِّل uv run orkestra sync لتوليد التوثيق
أدرِج السجل ضمن تركيب سياق الوكيل

ابدأ بالوقائع التي تسبِّب أكبر قدر من الالتباس، أو القيود التي تُنتهَك أكثر من غيرها. تلك هي حقائقك الأساسية الأعلى قيمة.

الخاتمة

سيهلوس وكلاء الذكاء الاصطناعي. تلك طبيعتهم. لكن يمكننا خلق بيئات تُقيَّد فيها الهلوسة، حيث تكون وقائع معينة غير قابلة للتفاوض، وحيث يستطيع الوكلاء التحقق من افتراضاتهم مقابل واقع مُتحقَّق منه.

الحقائق الأساسية ليست حلًا كاملًا. تتطلب صيانة. يمكن أن تصبح قديمة. تضيف عبئًا إضافيًا إلى عملية التطوير.

لكنها توفِّر شيئًا قيّمًا: مفردات مشتركة من الوقائع يمكن للبشر والوكلاء أن يثقوا بها. في عالم يشارك فيه الوكلاء بشكل متزايد في تطوير البرمجيات، يصبح ذلك الأساس المشترك ضروريًا.

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

وكلاؤك يستحقون معرفة ما هو صحيح. أخبِرهم.

Orkestra: تنسيق وكلاء الذكاء الاصطناعي على نطاق واسع

Tue, 06 Jan 2026 00:00:00 GMT

تعكس الأرقام في هذا المنشور حالة النظام وقت النشر (يناير 2026). راجع صفحة فريقنا للأرقام الحالية.

عندما بدأنا البناء باستخدام Claude Code، واجهنا مشكلة يواجهها في النهاية كل فريق يستخدم مساعدي البرمجة بالذكاء الاصطناعي: لا يستطيع وكيل واحد أن يفعل كل شيء بإتقان.

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

لذا بنينا Orkestra.

ما هو Orkestra؟

Orkestra نظام تنسيق وكلاء لـClaude Code وأدوات البرمجة المماثلة بالذكاء الاصطناعي. ينسِّق وكلاء متخصصين متعددين، لكل منهم خبرة مميزة، تحت منسِّق واحد يوجِّه العمل إلى المتخصص الصحيح.

تخيَّله كوكالة توظيف لوكلاء الذكاء الاصطناعي. يتلقى المنسِّق مهمة، ويحدِّد أي متخصص ينبغي أن يتولاها، ويُفوِّض إليه بالسياق الصحيح. عندما ينتهي العمل، تتدفق النتائج مرة أخرى إلى المنسِّق للتوليف.

تحكي الأرقام القصة:

المكوِّن	العدد
الوكلاء المتخصصون	46
المهارات القابلة لإعادة الاستخدام	466
أنماط الهوية الأصلية	27
العقليات (Mindsets)	11
أساليب التواصل	10
مجالات المعرفة	21

نظام الشخصية: D&D للوكلاء

البصيرة الأساسية وراء Orkestra هي أن سلوك الوكيل ينبثق من ثلاثة عناصر أولية قابلة للتركيب:

الهوية (Identity) تُحدِّد ماهية الوكيل. المعماري (architect) يصمِّم بنى الأنظمة. مصحِّح الأخطاء (debugger) يتتبَّع الإخفاقات إلى أسبابها الجذرية. الحارس (guardian) يفرض الامتثال وحدود الأمان. لدينا 27 نمطًا أصليًا للهوية يمكن مزجها.

العقلية (Mindset) تُحدِّد كيفية تفكير الوكيل. العقلية التحليلية تُرسِّخ التأكيدات في الأدلة وتُقدِّر عدم اليقين كميًا. العقلية المتشكِّكة تُشكِّك في الافتراضات وتبحث عن أدلة نقض. العقلية الاستكشافية تتبنّى الغموض وتُجرِّب مناهج متعددة.

الأسلوب (Style) يُحدِّد كيفية تواصل الوكيل. الأسلوب التقني يتضمَّن قيمًا دقيقة ويشير إلى ملفات محدَّدة. الأسلوب الموجَز يحذف الحشو ويبدأ بالإجابة. الأسلوب الدبلوماسي يوازن بين الصراحة واللباقة.

يجمع الوكيل بين هذه العناصر الأولية:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

هذا التركيب يُنشئ وكيلًا يصمِّم الأنظمة (architect)، ويربط المعرفة عبر المجالات (knowledge-architect)، ويضع التوجه الاستراتيجي (strategist)، ويفكِّر بالأدلة والبيانات (analytical)، ويتواصل دون حشو (concise).

القوة تكمن في الانفجار التوافقي. 27 هوية × 11 عقلية × 10 أساليب يُنتج نحو 3,000 شخصية وكيل ممكنة. لكنك تُعرِّف فقط التوليفات المهمة لعملك.

المهارات: وحدات قدرة قابلة لإعادة الاستخدام

المهارات هي المعرفة وسير العمل التي يستطيع الوكلاء استدعاءها. تتبع نظامًا متدرِّجًا حسب النطاق:

الطبقة	الاسم	النطاق	مثال
K0	الأساسيات	منهجية عالمية	انضباط الاختبار أولًا، الإنجاز القائم على الأدلة
K1	الهويات	سير عمل قائم على الدور	معايير واجهة سطر الأوامر، دليل الأداء
K2	المجالات	معرفة خاصة بالمجال	أنماط ترحيل قواعد البيانات، التحقق من المصادقة
K3	المكدسات (Stacks)	خاص بالتقنية	نشر Cloudflare، عمليات Supabase
K4	المشروع	خاص بقاعدة الكود هذه فقط	سير عمل وأعراف خاصة بالمشروع

تُحمَّل المهارات عند الحاجة. يرى الوكيل أسماء المهارات وأوصافها عند بدء التشغيل، لكن محتوى المهارة الكامل لا يُحمَّل إلا عند تفعيله. هذا يُبقي السياق خفيفًا مع جعل مئات المهارات قابلة للاكتشاف.

تتضمن كل مهارة:

شروط تفعيل واضحة (“استخدم عند ترحيل مخططات قاعدة البيانات”)
توجيهًا خطوة بخطوة
الأدوات المسموح بها لسير العمل
معايير النجاح ومسارات التعافي من الفشل

تُغطِّي الـ466 مهارة في سجلنا كل شيء من عزل شجرة عمل git إلى سير عمل البحث على الويب إلى التحقق من صحة النشر.

لماذا يهم التنسيق

تصطدم بنى الوكيل الواحد بالجدران بسرعة:

تشتت السياق. نافذة سياق بـ200 ألف رمز تبدو كبيرة حتى تُحمِّل مخططات قواعد البيانات، وتوثيق API، وتجهيزات الاختبار، ومعرفة المجال. يستطيع المتخصصون العمل بسياق موجَّه.

تعارضات التعليمات. أن تطلب من وكيل “كن دقيقًا لكن سريعًا” و“تحقق من كل شيء لكن لا تُفرِط في الهندسة” يخلق توترًا. يحلّ المتخصصون هذا بامتلاك نطاق واضح.

عمق الخبرة. يعرف الوكيل العام القليل عن كل شيء. الوكيل المتخصص، المُركَّب بالهوية والمهارات الصحيحة، يعرف مجاله بعمق.

يُنفِّذ Orkestra تنسيقًا مسطَّحًا: منسِّق واحد ينسِّق متخصصين متعددين. لا يستطيع المتخصصون توليد متخصصين فرعيين. هذا يمنع انفجار التعقيد مع تمكين العمل المتوازي.

يمتلك المنسِّق وصولًا إلى سعة فعلية تبلغ 2.2 مليون رمز: نافذته الخاصة البالغة 200 ألف رمز بالإضافة إلى 10 وكلاء فرعيين متزامنين بـ200 ألف رمز لكل منهم. يُنجَز العمل الذي كان سيُنهك وكيلًا واحدًا بسهولة عند توزيعه على الأسطول.

خط أنابيب التصيير

تعيش تعريفات الوكلاء في YAML. يقرأ Claude Code Markdown. يسدّ Orkestra هذه الفجوة بخط أنابيب تصيير حتمي:

YAML Registries → Jinja Templates → .claude/agents/*.md

يحرِّر المشغِّلون مصدر YAML. شغِّل orkestra sync. يظهر Markdown المُصيَّر في .claude/agents/. يلتقط Claude Code التغييرات.

يخدم هذا الفصل جمهورين مختلفين:

مصدر YAML يتضمَّن بيانات وصفية لدورة الحياة، وعلامات، وقواعد تحقق، وملاحظات تقادم للأدوات
Markdown المُصيَّر يتضمَّن فقط ما يحتاجه النموذج: الوصف، والأدوات، والمهارات، والتوجيه السلوكي

يُركِّب خط الأنابيب الهويات، والعقليات، والأساليب، والمهارات في مطالبة واحدة متماسكة. يحصل وكيل architect-analytical-concise على مطالبة نظام مختلفة تمامًا عن وكيل debugger-skeptical-technical، حتى إن تشاركا بعض المهارات الأساسية.

معرفة المجال: نمط الملفات الأربعة

يتبع كل مجال معرفة بنية متسقة:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

تخدم هذه البنية تحميل سياق الوكيل. يُحمِّل وكيل يعمل على المصادقة authentication/patterns.md للتوجيه وauthentication/anti-patterns.md لتجنّب المزالق المعروفة. الملفات مُحجَّمة لتحميل سياق كفء: مركَّزة بما يكفي لتكون مفيدة، وشاملة بما يكفي لتكون موثوقة.

نحافظ على 21 مجالًا رئيسيًا تتضمَّن التحليلات، والمصادقة، وعلوم البيانات، والبنية التحتية، والتعلم الآلي، والأداء، والأمان، وغيرها. يمكن أن يمتلك كل مجال مجالات فرعية لتفصيل أدق.

القيم: نظام التشغيل

يتشارك جميع الوكلاء طبقة أساسية من القيم تُحدِّد كيفية عملهم:

البساطة أولًا. استخدم أبسط حل يعمل. أضِف تعقيدًا فقط عندما يكون مُبرَّرًا.

أصلِح الأسباب الجذرية. لا ترقِّع أبدًا حول الإخفاقات. إذا فشل خط أنابيب، صحِّح خط الأنابيب. إذا فشل اختبار، أصلِح الكود أو الاختبار.

قائم على الأدلة. صنِّف الادعاءات كـ“مُتحقَّق منها” (بمعايير قياسية) أو “مُقدَّرة” (بافتراضات). اكتشاف نمط لا يساوي تأكيد مشكلة.

اقتصاديات السياق. تكلِّف أدوات MCP 0.1% من السياق. تكلِّف قراءات الملفات 2% لكل واحدة. طبِّق خبرة المجال قبل استكشاف الكود.

تنتشر هذه القيم إلى كل متخصص عبر خط أنابيب التصيير. لا يستطيع وكيل تجاوزها بالتركيب.

سطر الأوامر: مستوى التحكّم

يأتي Orkestra مع سطر أوامر لإدارة نظام الوكلاء البيئي:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

سطر الأوامر هو مصدر الحقيقة للوكلاء المتاحين، والمهارات التي يمتلكونها، وما إذا كان النظام سليمًا. يُشغِّل التحقق قبل المزامنة لاكتشاف المشكلات مبكرًا.

اعتبارات المصدر المفتوح

بنينا Orkestra لحل مشكلتنا الخاصة: تنسيق وكلاء الذكاء الاصطناعي على نطاق واسع لقاعدة كود معقدة. الأنماط التي اكتشفناها ليست خاصة بمجالنا.

يُطبَّق نظام تركيب الشخصية (الهوية + العقلية + الأسلوب) على أي فريق يُعرِّف شخصيات الوكلاء.

يوفِّر نظام طبقات المهارات (K0-K4) نموذجًا ذهنيًا لتنظيم القدرات القابلة لإعادة الاستخدام حسب النطاق.

يفصل نمط خط أنابيب التصيير (مصدر YAML + قوالب + نواتج مُولَّدة) الاهتمامات بين الأدوات واستهلاك النموذج.

يتجنب نموذج التنسيق المسطَّح (منسِّق واحد، متخصصون كثيرون) التعقيد مع تمكين التوازي.

ما إذا كان Orkestra سيصبح مفتوح المصدر يعتمد على ما إذا كانت هذه الأنماط ذات قيمة لآخرين يبنون باستخدام Claude Code. إذا كنت تصطدم بالجدران التي وصفناها، فقد تساعدك هذه البنية.

ما تعلمناه

علَّمنا بناء Orkestra أن التنسيق لا يدور حول جعل الوكلاء أذكى. إنه يدور حول جعلهم أكثر تركيزًا.

وكيل واحد بتعليمات مثالية لا يزال ينفد سياقه. وكيل واحد بكل المهارات لا يزال يرتبك بشأن أيها يُطبِّق. وكيل واحد يحاول أن يكون كل شيء يُنتج نتائج متوسطة في كل مكان.

أربعون متخصصًا، كل منهم ممتاز في مجاله، ينسِّقهم منسِّق يعرف متى يُفوِّض: هكذا نُنجز العمل ونُطلقه.

الأرقام أقل أهمية من البنية. قد تحتاج إلى خمسة وكلاء أو خمسين. المبدأ يبقى: التركيب فوق القدرة، والتخصص فوق التعميم، والتنسيق فوق البطولات الفردية.

يُشغِّل Orkestra نظام الوكلاء البيئي خلف Maguyva، منصة ذكاء الكود لدينا. تريد معرفة المزيد؟ تواصل مع الفريق.