חיפוש קוד עם גרף הקוד

מדריך זה מראה כיצד להכניס מאגר אל גרף הקוד, ואחר כך להיעזר בו כדי לענות על השאלה שבאמת עומדת בפניכם לפני רפקטורינג: מה תלוי בזה?

גרף הקוד הוא מסד נתונים של סמלים וקצוות, שנבנה מניתוח ה-checkout-ים הרשומים שלכם עם 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.

שני דברים נוספים מעצבים את מה שנכנס לאינדוקס:

ב-work tree של git, ספירת הקבצים נשענת על git ls-files --cached --others --exclude-standard, כך שכל .gitignore, קובץ ignore מקונן, .git/info/exclude וקובץ ה-excludes הגלובלי מכובדים. זה מה שמשאיר את node_modules ואת תוצרי הבנייה מחוץ לגרף.
קוד Dart מיוצר נזרק בכל מקרה. קבצים מיוצרים בדרך כלל נשמרים ב-commit, ולכן git לבדו לא היה מחריג אותם, והם משתנים בכל הרצת codegen.

אינדוקס של מאגר

רישום checkout מפעיל RepoAdded, שמתחיל עבורו אוטומטית את הפייפליין index_code. ראו הוספת מאגרים לסביבת עבודה.

לביצוע אינדוקס מחדש ידנית:

פתחו הגדרות → סביבת עבודה → מאגרים.
לחצו על הכפתור אינדוקס קוד בשורה של המאגר.
בזמן שהפעולה רצה מציג הכפתור את מספר הקבצים שהושלמו מתוך הסך הכול, עם פקד ביטול. כשהיא מסתיימת, הוא מתחלף בסימן ביקורת עם מספר הסמלים.

הגרף מחולק למחיצות לפי סביבת עבודה, מאגר ו-checkout: ה-checkout המקושר הוא מחיצה אחת, וכל worktree של מרחב מקבל מחיצה משלו (במפתח לפי המזהה של המאגר המבודד שלו).

שני מגבילי קצב שווה להכיר, כי הם מסבירים המתנה שנראית כמו תקיעה:

מאזין הקבצים מתיר הרצת אינדוקס אחת בלבד בכל רגע במארח — checkout שני ממתין. הפייפליין index_code מוגבל בנפרד להרצה אחת לכל סביבת עבודה, ולכן שני מאגרים באותה סביבת עבודה נכנסים לתור; סביבות עבודה שונות יכולות לבצע אינדוקס במקביל. המאנדקס עצמו מסדר בסדרה שתי הרצות של אותו checkout, כך שתחילת פייפליין וסבב של המאזין לא יגרמו לניתוח כפול שלו.
worktree-ים של מרחבים רדומים (ללא הודעה בשבוע האחרון) אינם נצפים ואינם נכנסים לאינדוקס. checkouts מקושרים ממשיכים להיצפות. החלטת דילוג נבדקת מחדש לאחר חמש דקות, כך שמרחב ששב לפעילות ייקלט.

איתור סמל

בקשו מסוכן לחפש. הכלי הוא search_code והוא זקוק גם לסביבת עבודה וגם למאגר:

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

מזהי מאגר מגיעים מ-list_repos. הארגומנט האופציונלי mode הוא keyword, semantic או hybrid, וברירת המחדל שלו היא hybrid — BM25 על שמות, חתימות והערות תיעוד, מאוחד עם דמיון וקטורי.

כל תוצאה נושאת את ה-id של הסמל, את שמו, את שמו המסווג, את הסוג, את נתיב הקובץ, את שורת ההתחלה והסיום, ואת החתימה שלו כשיש לו כזו. ה-id הוא המזהה שתעבירו לכל כלי אחר בעמוד זה.

כשאתם יודעים את השם המדויק, חפשו אותו ישירות במקום זאת:

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 (imports, mixes-in והפניות גנריות נשמרים בגרף אך אינם נסרקים כאן). depth הוא מספר הקפיצות המרבי, בין 1 ל-6, וברירת המחדל היא 2.

התוצאה היא שלושה שדות:

root — הסמל ששאלתם עליו
impacted — הקבוצה הניתנת להשגה, כולל השורש בעומק 0, כאשר כל אחד מהם נושא את ה-depth שלו מהשורש
edgeCount — כמה קצוות חצה המעבר, כמניין ולא כקצוות עצמם

הריצו אותו לפני שינוי שם או שינוי חתימה, ומסרו לסוכן את רשימת המושפעים כהיקף העבודה.

התוצאות נבדקות מול עותק העבודה של הקורא עצמו

עבור קורא שהוא סוכן, מזהה המרחב מוזרק אוטומטית, והתוצאות נבדקות מול עותק העבודה של אותו מרחב. סמל שהקובץ שלו כבר אינו קיים בעץ של הקורא מושמט, והתשובה נושאת מניין staleOmitted וכן הערה שהאינדקס מיושן עבור אותם סמלים.

זו הסיבה לכך שאתם וסוכן עשויים לקבל תשובות שונות לאותה שאילתה, ולכך שסוכן במרחב אחד עשוי לקבל תשובה שונה מסוכן במרחב אחר. כל שיחה במרחב חולקת את אותו worktree יחיד. האימות נכשל באופן פתוח: תשובה מיושנת עדיפה על תשובה ריקה.

בקשו מסוכן להריץ את code_impact (או review_studio.blastRadius) כשאתם רוצים את רדיוס ההשפעה של שינוי. ראו חישוב סקירה.

חיפוש סמנטי מחייב את מודל ההטמעות

סמלים ועובדות מוטמעים בזמן הכתיבה, ורק כשמודל ההטמעות שעל המכשיר מותקן. עד אז, ל-mode: "semantic" ולחצי הסמנטי של hybrid אין מול מה להתאים, והחיפוש הוא למעשה מבוסס מילות מפתח בלבד.

התקינו את המודל בהגדרות → שרת → אבחון ופרטיות → חיפוש סמנטי לפני האינדוקס. סמלים מקבלים וקטור כשהקובץ שלהם נקלט.

שימו לב גם שכל בנייה מחדש של קובץ השרת מכינה מחדש את קובצי ה-dylib של הדקדוקים ומשנה את ה-mtimes שלהם, מה שמבטל כל נקודת ביקורת של האינדקס ומאלץ סריקה מלאה אחת של כל checkout בהרצה הבאה. הוא מחשב מחדש את ה-hash, אך אינו מחלץ מחדש קבצים שלא השתנו.

מה יש בגרף

סוגי סמלים: function, method, class, field, enum, constructor, getter, setter, typedef, extension, mixin, variable.

סוגי קצוות: calls, imports, extends, implements, mixes in, references.

החתימות הקנוניות של כלים אלה נמצאות בכלי MCP.

מדריכים קשורים

מושגים קשורים

סביבות עבודה ובידוד