ذكاء برمجي دون هلوسة: كيف تتفوق الرسوم البيانية القطعية على استرجاع المتجهات

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

مع إطلاق الإصدار 0.9.55 في 5 سبتمبر 2026، تقدم أداة Graphify (المطورة من فريق Graphify-Labs برخصة Apache 2.0 والتي تجاوزت 115 ألف نجمة على GitHub) بديلاً هندسياً متيناً. فبدلاً من تحويل الشيفرة البرمجية إلى متجهات تقريبية، تفحص Graphify المستودعات وتبني رسماً بيانياً معرفياً قطعياً معتمداً على أشجار البنية المجردة (AST)، وتربط العلاقات النحوية في فهرس موحد يستعلم عنه وكلاء الذكاء الاصطناعي مباشرة عبر بروتوكول سياق النموذج (MCP).

لماذا يتعثر استرجاع المتجهات في هندسة البرمجيات؟

يعود إخفاق تقنيات RAG المتجهية في بيئات تطوير البرمجيات المعقدة إلى ثلاثة عيوب معمارية:

1. الدقة النحوية مقابل التقارب اللفظي: تقيس متجهات التضمين التشابه المعنوي في اللغات الطبيعية، بينما تتطلب البرمجة مطابقة حرفية قاطعة للرموز والواجهات البرمجية. فوجود دالة باسم handleAuth في وحدة الفواتير يحمل تشابهاً متجهياً كبيراً مع handleAuth في بوابة إدارة المشرفين، مما يدفع قواعد بيانات المتجهات لإعادة الكود الخطأ إلى سياق النموذج.
2. عجز تتبع السلاسل المتعددة (Multi-Hop): تتطلب الإجابة عن سؤال مثل “إذا غيرت هذا الحقل في قاعدة البيانات، ما هي نقاط API التي ستتعطل؟” تتبع مسار تسلسلي حتمي: بنية الجدول -> نموذج ORM -> طبقة المستودع -> المتحكم -> مسار الويب. تعيد محركات المتجهات قطعاً مبعثرة وتترك للنموذج مهمة تخمين الروابط المفقودة داخل نافذة السياق.
3. تضخم استهلاك نافذة السياق: يملأ نظام RAG التقليدي نافذة النموذج بمقاطع نصية كاملة غير لازمة، مما يرفع تكلفة الرموز ويشتت انتباه النموذج وقدرته على الاستدلال أثناء جلسات تصحيح الأخطاء الطويلة.

استرجاع المتجهات التقليدي (Vector RAG):
الكود المصدري ---> تقطيع عشوائي ---> تضمين لغوي ---> قاعدة بيانات متجهات ---> نتائج تقريبية
                                                                            |
                                                                    إهدار كبير للرموز
                                                                    ضياع سلاسل الاستدعاء

معمارية Graphify:
الكود المصدري ---> تحليل Tree-Sitter ---> استخراج الرموز ---> رسم بياني حتمي ---> أدوات MCP
                                                                            |
                                                                    أرقام أسطر حتمية
                                                                    تتبع علاقات قطعي

كيف تعمل أداة Graphify؟

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

1. استخراج حتمي متعدد اللغات للبنية المجردة (AST)

تستخدم Graphify محللات Tree-Sitter لفحص المشاريع المكتوبة بلغات TypeScript وJavaScript وPython وGo وRust وJava وC++ ومخططات SQL. ويولد المحلل نوعين رئيسيين من البيانات:

• عقد معرفة النوع (Typed Nodes): تشمل الملفات، الدوال، التوابع، الفئات، الواجهات البرمجية، الثوابت، مخططات قواعد البيانات، ونقاط اتصال API.
• روابط موجهة حتمية (Typed Directed Edges): مثل calls (تستدعي)، وinherits (ترث)، وimplements (تطبق واجهة)، وimports (تستورد)، وdefines (تعرف)، وmutates (تعدل بيانات).

يحفظ كل رابط المسار الدقيق في ملف الكود وموقع السطر ورقم البايت بدقة متناهية. وإذا كانت الدالة processInvoice تستدعي الدالة chargeCard في السطر 142 من ملف billing.ts، فإن الرابط بينهما يكون مؤشراً حسابياً ثابتاً لا علاقة له باحتمالات المتجهات اللغوية.

2. الربط الدلالي للوثائق والمواصفات

إلى جانب الأكواد، تفحص Graphify ملفات التوثيق بتنسيق Markdown ومواصفات OpenAPI وملفات ترحيل قواعد البيانات. وعندما يشير ملف التوثيق إلى ميزة أو كيان معين، تربط Graphify عقدة التوثيق برمز الكود البرمجي المقابل مع ضمانات تحقق مشددة، ليتصل التوثيق مباشرة بالكود المنفذ.

3. واجهة بروتوكول سياق النموذج (MCP)

توفر Graphify واجهة MCP قياسية عبر الإدخال والإخراج القياسي (stdio) وتقنية التدفق المستمر عبر HTTP SSE. وعند اتصال الوكلاء عبر Claude Code أو Cursor أو Codex أو Gemini CLI، تتاح لهم أربع أدوات قطعية:

• graphify_get_callers: جلب كافة الدوال والمكونات التي تستدعي رمزاً معيناً بشكل مباشر أو غير مباشر حتى عمق محدد.
• graphify_trace_flow: تتبع تدفق البيانات من مدخلات الدالة وصولاً إلى نقطة الحفظ النهائي في قاعدة البيانات أو الإرسال عبر الشبكة.
• graphify_impact_analysis: تحليل أثر التعديلات المقترحة وتحديد كافة الوحدات والاختبارات المتأثرة بتغيير واجهة برمجية.
• graphify_explain_edge: إرجاع الأسطر البرمجية المحددة التي تثبت وجود العلاقة البنيوية بين عقدتين.

أبرز ما جاء في تحديث الإصدار v0.9.55

عالج إصدار 5 سبتمبر 2026 مجموعة من الحالات الحرجة في بيئات التطوير الحقيقية:

1. حل إعادة التصدير في ملفات التجميع (#3358)

تعتمد مشاريع JavaScript وTypeScript على ملفات تجميع الصادرات (index.ts) باستخدام أنماط مثل export { Client } from './client'. في السابق، كانت الأداة تنشئ عقداً وسيطة للملف المجمع مما يؤدي أحياناً إلى انقطاع سلاسل التتبع في المشاريع المتشعبة. يحل الإصدار 0.9.55 هذه المشكلة بتتبع الرموز مباشرة إلى تعريفها الأصلي، متجاوزاً حلقات الوساطة دون الإخلال بقطعية التتبع.

2. الحفاظ على الاستيراد الديناميكي في TypeScript (#3210)

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

3. معالجة تضارب المعرفات في بايثون (#3302)

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

4. استقرار قنوات النقل على نظام ويندوز (#3318)

عند تشغيل Graphify كخادم MCP على بيئات ويندوز، كانت بعض الأدوات التي تستدعي سطر أوامر git أو GitHub CLI تسبب تجمد قناة stdio. يعزل التحديث مدخلات العمليات الفرعية مما يضمن تدفق البيانات بسلاسة على بيئات ويندوز.

طريقة التشغيل والدمج مع وكلاء البرمجة

يمكن تثبيت واستخدام Graphify في بيئات التطوير عبر خطوات مباشرة:

1. فهرسة المشروع محلياً

تثبيت الأداة عالمياً أو تشغيلها عبر مدير الحزم:

# تثبيت سطر أوامر Graphify
npm install -g @graphify/cli

# بناء فهرس الرسم البياني في المجلد الحالي
graphify build --include="src/**/*.ts,src/**/*.py,docs/**/*.md"

يفحص الأمر هيكل المشروع ويبني شجرة العلاقات ويحفظ الفهرس في ملف .graphify/graph.json محلياً دون رفع أي كود للخارج.

2. إعداد بروتوكول MCP للمساعدين البرمجيين

إضافة الأداة إلى إعدادات خوادم MCP (في ملف ~/.claude/mcp.json أو ملف المشروع):

{
  "mcpServers": {
    "graphify": {
      "command": "graphify",
      "args": ["mcp", "--project-dir", "."],
      "env": {
        "GRAPHIFY_MAX_DEPTH": "4"
      }
    }
  }
}

عندما يطلب المهندس من الوكيل فحص مسار استدعاء أو إعادة هيكلة كود، يستدعي الوكيل أداة التحليل البنيوي بدلاً من إضاعة الرموز في عمليات البحث النصي المتكررة.

# الاستعلام عن مسار الاستدعاء من الطرفية مباشرة
graphify query "CALLERS of AuthService.verifyToken DEPTH 3"

وتظهر النتيجة كمسار بنيوي قاطع بأرقام الأسطر:

AuthService.verifyToken (src/auth/service.ts:88)
  <-- called by authMiddleware (src/auth/middleware.ts:24)
        <-- called by setupProtectedRoutes (src/routes/api.ts:112)
              <-- called by bootstrapApp (src/index.ts:45)

القيود والمحاذير التقنية

تقتضي الأمانة الهندسية توضيح حدود استخدام الأداة:

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

خلاصة

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

المصادر المعتمدة

• المستودع الرسمي لمشروع Graphify على GitHub
• سجل التغييرات الرسمي للإصدار v0.9.55
• المواصفات القياسية لبروتوكول سياق النموذج (Model Context Protocol)
• المشروع المصدري لمحللات اللغات النحوية Tree-Sitter