البحث في الشفرة عبر مخطط الشفرة

يبين هذا الدليل كيف تُدخِل مستودعًا إلى مخطط الشفرة، ثم تستخدمه للإجابة عن السؤال الذي يهمك فعلًا قبل إعادة الهيكلة: ما الذي يعتمد على هذا؟

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

قبل أن تبدأ

يفهرس المخطط Dart و JavaScript و TypeScript و TSX و PHP و Python و Rust و Zig و C و C++ و Go و Java و Ruby و C# و Swift و Kotlin و R و Assembly و MATLAB و Ada. أما ملفات أي لغة أخرى فلا تُحلَّل، ولا تظهر في search_code ولا code_symbol ولا code_callers ولا code_callees ولا code_impact.

أمران آخران يشكّلان ما يُفهرَس:

في شجرة عمل Git يُحال تعداد الملفات إلى git ls-files --cached --others --exclude-standard، فيُراعى كل .gitignore وكل ملف تجاهل متداخل و.git/info/exclude وملف الاستبعادات العام. هذا ما يُبقي node_modules ومخرجات البناء خارج المخطط.
يُسقَط Dart المولَّد في كل الأحوال. الملفات المولَّدة تُودَع عادة، فلا يستبعدها Git وحده، وهي تتقلّب مع كل تشغيل لتوليد الشفرة.

فهرسة مستودع

تسجيل نسخة المستودع يطلق RepoAdded، فيبدأ خط أنابيب index_code لها تلقائيًا. انظر إضافة مستودعات إلى مساحة عمل.

لإعادة الفهرسة يدويًا:

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

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

حدّان جديران بالمعرفة، لأنهما يفسران انتظارًا يبدو كأنه تعليق:

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

العثور على رمز

اطلب البحث من وكيل. الأداة هي search_code، وتحتاج إلى مساحة عمل ومستودع معًا:

search_code(workspace_id: "...", repo_id: "...", query: "authentication middleware")

معرّفات المستودعات تأتي من list_repos. وسيط mode الاختياري هو keyword أو semantic أو hybrid، وافتراضه الهجين — BM25 على الأسماء والتوقيعات وتعليقات التوثيق، مدمجًا مع تشابه المتجهات.

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

إذا عرفت الاسم بدقّته، فاطلبه مباشرة:

code_symbol(workspace_id: "...", repo_id: "...", name: "MyClass")

تتبّع الاستدعاءات

كلاهما يأخذ symbol_id من نتيجة بحث، مع limit اختياري (الافتراضي 50):

code_callers(workspace_id: "...", symbol_id: "...")
code_callees(workspace_id: "...", symbol_id: "...")

يعيد code_callers الرموز التي لها حافة واردة إلى هذا الرمز، ويعيد code_callees ما يعتمد عليه هذا الرمز.

ماذا قد يكسره التغيير

هذه هي الأداة التي وُضعت الصفحة كلها من أجلها:

code_impact(workspace_id: "...", symbol_id: "...", depth: 3)

يحسب نصف قطر التبعية العكسية: كل ما يعتمد على الرمز مباشرة أو بالتعدي عبر حواف calls وextends وimplements (الاستيرادات والخلط ومراجع الأنواع المُعمَّمة تُخزَّن في المخطط ولا يُمشى عليها هنا). depth هو أقصى عدد للقفزات، بين 1 و6، وافتراضه 2.

النتيجة ثلاثة حقول:

root — الرمز الذي سألت عنه
impacted — المجموعة التي يمكن بلوغها، ومنها الجذر عند العمق 0، ويحمل كل عنصر depth الخاص به عن الجذر
edgeCount — عدد الحواف التي عبرها المسار، كعدد لا كالحواف نفسها

شغّله قبل إعادة التسمية أو تغيير التوقيع، وأعطِ الوكيل قائمة المتأثرين لتكون نطاق عمله.

تُفحَص النتائج مقابل نسخة عمل المستدعي نفسه

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

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

اطلب من وكيل تشغيل code_impact (أو review_studio.blastRadius) حين تريد نصف قطر تأثير التغيير. انظر حوسبة المراجعة.

البحث الدلالي يحتاج إلى نموذج التضمين

تُضمَّن الرموز والحقائق عند الكتابة، ولا يحدث ذلك إلا بعد تثبيت نموذج التضمين على الجهاز. إلى ذلك الحين لا يجد mode: "semantic" ولا النصف الدلالي من الوضع الهجين ما يطابقه، فيقتصر البحث عمليًا على الكلمات المفتاحية.

ثبّت النموذج من الإعدادات ← الخادم ← التشخيص والخصوصية ← البحث الدلالي قبل الفهرسة. يكتسب الرمز متجهًا حين يُدخَل ملفه إلى الفهرس.

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

ما الذي في المخطط

أنواع الرموز: دالة، دالة عضو، صنف، حقل، تعداد، مُنشئ، دالة جلب، دالة تعيين، تعريف نوع، توسيع، مزيج، متغيّر.

أنواع الحواف: استدعاء، استيراد، وراثة، تنفيذ، خلط، مرجع.

التواقيع المرجعية لهذه الأدوات في أدوات MCP.

أدلة ذات صلة

مفاهيم ذات صلة

مساحات العمل والعزل