כלי סוכן מובנים
אלה הכלים המקושרים לשרת שמנגנון ההרצה המובנה של הסוכן רושם ישירות — שרת שפה, חיפוש מבני, מנפה, קרנלים, שאלות ושליטה בעובדים — להבדיל מכלי MCP שהוא מגשר פנימה, ומכלי הקבצים, החיפוש והמעטפת הגנריים של מנגנון ההרצה. הם אינם נמצאים במרשם MCP: לקוח MCP חיצוני לא יראה אותם, מפני שכל אחד מהם קשור למשאב חי בצד השרת — תהליך שרת שפה, מתאם ניפוי, מפרש — ששייך להרצה אחת.
כל כלי כאן נרשם רק כשהמשאב שעומד מאחוריו מחובר להרצה — מפקח שרת שפה או ניפוי, מנתח tree-sitter, מפעל קרנלים, יציאת שאלות, רשימת עובדי vibe. זיהוי של שרת שפה או מתאם ניפוי עבור ה־checkout הזה הוא בדיקה נפרדת ומאוחרת יותר (status / adapters): הכלים האלה נשארים על המשטח כדי שהסוכן יוכל לשאול מדוע שום דבר אינו שמיש, במקום לנחש.
דרגות אישור
קטע בשם “דרגות אישור”כל כלי מצהיר על דרגה, והדרגה מכריעה אילו משטחים רואים אותו — לא רק אם הוא מבקש אישור. מצב תוכנית וסוכני משנה לקריאה בלבד מוגבלים ל־read, כך שכלי בדרגת write או exec נעדר מהסכימה שלהם לחלוטין.
| דרגה | משמעות | כלים כאן |
|---|---|---|
read |
ללא תופעות לוואי | lsp, ast_grep, ask_user, חמשת ה־vibe_* |
write |
משנה קבצים | lsp_rename, ast_edit, resolve |
exec |
מפעיל תהליך או שולט בו | debug, eval |
lsp — שאילתות שרת שפה
קטע בשם “lsp — שאילתות שרת שפה”נרשם כאשר להרצה יש מפקח שרת שפה ותיקיית עבודה. אם שרת באמת יכול לענות מתגלה בזמן הקריאה, כחיתוך: סמן שורש חייב להתקיים וגם קובץ ההרצה של השרת חייב להיפתר. כל אחד מהם לבדו משמעו שאף שרת לא עולה — status אומר זאת — במקום ניחוש שקט.
מיקומים ממוענים לפי line בתוספת מחרוזת חלקית של symbol, ולעולם לא לפי עמודה. מודל שמתבקש לציין עמודה מנחש, וניחוש שגוי נפתר לסמל אחר באותה שורה — תשובה שנראית נכונה ועוסקת במשהו אחר. השמטת symbol בפעולת ניווט היא שגיאה, ולא ניחוש של העמודה הראשונה.
| פעולה | ארגומנטים | מחזיר |
|---|---|---|
diagnostics |
file (או "*") |
שגיאות ואזהרות; "*" מפעיל במקום זאת את בודק הפרויקט |
definition |
file, line, symbol |
היכן שהסמל מוצהר |
type_definition |
file, line, symbol |
היכן שהטיפוס שלו מוצהר |
implementation |
file, line, symbol |
מימושים קונקרטיים |
references |
file, line, symbol |
כל שימוש, עד 50 |
hover |
file, line, symbol |
חתימה והערת תיעוד |
symbols |
query או file |
חיפוש בסביבת העבודה עם query (עד 100); סמלי מסמך עם file (עד 200) |
code_actions |
file, line, symbol |
תיקונים מהירים שהשרת מציע |
status |
— | אילו שרתים פועלים, ועבור אילו שורשים |
reload |
— | מפעיל מחדש את השרת עבור השורש הזה |
אבחון בכתיבה
קטע בשם “אבחון בכתיבה”הרווח אינו הכלי עצמו. write, edit ו־apply_patch עטופים: אחרי הכתיבה הקובץ מסונכרן ונשמר דרך שרת השפה, ורק אבחונים שהופיעו זה עתה מקופלים אל תוך תוצאת הכלי. הסוכן לומד שהוא שבר את הבנייה ברגע ששבר אותה, בלי שהיה עליו לזכור לשאול.
אבחונים שכבר דווחו מושתקים על ידי יומן לכל הרצה שממופתח לפי חומרה, קוד והודעה — המיקום הוחרג במכוון, כך שאבחון שפשוט ירד ארבע שורות למטה אינו מדווח מחדש כחדש.
lsp_rename — שינוי שם בכל הפרויקט
קטע בשם “lsp_rename — שינוי שם בכל הפרויקט”כלי נפרד בדרגת write, מסיבה אחת בדיוק: הדרגה מכריעה את הנראות. קיפול של שינוי השם אל תוך lsp היה או נותן לחוקר לקריאה בלבד את היכולת לשכתב את המאגר, או שם כל hover מאחורי בקשת אישור.
| ארגומנט | משמעות |
|---|---|
file |
היכן שהסמל נמצא |
line |
שורה באינדוקס 1 |
symbol |
מחרוזת חלקית שמזהה אותו באותה שורה |
new_name |
איך לקרוא לו |
ast_grep — חיפוש מבני
קטע בשם “ast_grep — חיפוש מבני”מוצא קוד לפי צורה ולא לפי טקסט. $NAME מתאים לכל צומת, $$$NAME מתאים לרצף של אחים, ו־$_ הוא תו כללי שאינו לוכד דבר.
התכונה שהופכת אותו למתאים ולא לביטוי רגולרי עם כמה שלבים נוספים: מטא-משתנה שחוזר בתבנית אחת חייב ללכוד את אותו טקסט.
ast_grep(pattern: "if ($X != null) $X.dispose()", language: "dart")מתאים לשומר שמשחרר את מה שבדק, ואינו מתאים לכזה שמשחרר משהו אחר.
| ארגומנט | משמעות |
|---|---|
pattern |
קטע קוד עם מטא-משתנים |
path |
קובץ או תיקייה לחיפוש; ברירת המחדל היא כל סביבת העבודה |
language |
מזהה דקדוק שסופק (dart, python, rust, c, …). נגזר כאשר path מציין קובץ |
max_results |
ברירת מחדל 50 |
ast_edit — שכתוב מבני, בהכנה
קטע בשם “ast_edit — שכתוב מבני, בהכנה”אותו מיתוג, בתוספת תבנית rewrite שאליה מוחזרים המטא-משתנים. דבר אינו נכתב. השינוי עובר הכנה, והתוצאה מציינת edit_id.
ast_edit(pattern: "dispose($X)", rewrite: "$X.dispose()", language: "dart")→ (proposed) 12 replacements in 4 files … call resolve with edit_id "edit_1"| ארגומנט | משמעות |
|---|---|
pattern |
מה להתאים |
rewrite |
מה לשים שם, עם $NAME מוחלף |
path |
היקף; ברירת המחדל היא כל סביבת העבודה |
language |
מזהה שפה |
resolve — החלה או ביטול של שינוי שהוכן
קטע בשם “resolve — החלה או ביטול של שינוי שהוכן”| ארגומנט | משמעות |
|---|---|
edit_id |
מהתוצאה (proposed) |
action |
accept או discard |
כל קובץ מושווה מול התוכן שנלכד בזמן ההכנה, וכל אי-התאמה דוחה את השינוי כולו. שכתוב מבני שהוחל חלקית משאיר עץ שאינו מתקמפל לפי אף אחת מהצורות — לא הישנה ולא החדשה.
debug — הפעלת מנפה
קטע בשם “debug — הפעלת מנפה”נרשם כאשר להרצה יש מפקח סשן ניפוי, תיקיית עבודה ומזהה שיחה. אם מתאם באמת יכול לעלות מתגלה בזמן הקריאה, לפי אותו כלל חיתוך של שרת השפה (סמן שורש וגם קובץ הרצה). דרגת exec; אינו בטוח להרצה מקבילה (סשן הוא מצב שנמשך בין קריאות, ולכן continue שעוקף את stack יקרא מסגרת שכבר זזה).
סשן אחד לכל שיחה, עם TTL קשוח (30 דקות). launch שני נדחה במקום להחליף בשקט את הראשון.
| פעולה | ארגומנטים | הערות |
|---|---|---|
adapters |
— | אילו מתאמים שמישים כאן, ומדוע לא |
status |
— | אם סשן פועל, והיכן הוא נעצר |
breakpoints |
file, lines[] |
lines ריק מנקה את הקובץ. אפשר להציב לפני ההפעלה |
launch |
program, args[] |
מפעיל את התוכנית כשהיא עצורה בנקודות העצירה שלכם |
attach |
port |
מתחבר לתוכנית מנופה שכבר רצה |
continue |
thread_id? |
רץ עד לעצירה הבאה |
pause |
thread_id? |
עוצר אותו במקום שבו הוא נמצא |
step_over / step_in / step_out |
thread_id? |
מתקדם צעד אחד |
threads |
— | מזהי תהליכונים ושמותיהם |
stack |
thread_id? |
מסגרות, עד 30 |
scopes |
frame_id |
תחומים במסגרת, לכל אחד reference |
variables |
reference |
ילדים, עד 50, ערכים עד 400 תווים |
evaluate |
expression, frame_id? |
מחושב בתחום של המסגרת עצמה |
output |
— | ה־stdout/stderr של התוכנית המנופה, חסום |
terminate |
— | מסיים את הסשן והורג את המתאם |
מתאמים
קטע בשם “מתאמים”| מזהה | פקודה | סמני שורש |
|---|---|---|
dart |
dart debug_adapter |
pubspec.yaml |
debugpy |
python3 -m debugpy.adapter |
pyproject.toml, setup.py, requirements.txt |
lldb |
lldb-dap |
Cargo.toml, CMakeLists.txt |
delve |
dlv dap |
go.mod |
debugpy מעדיף .venv/bin או venv/bin מקומיים לפרויקט על פני $PATH: מפרש python מ־$PATH הוא סביבה אחרת, והתחברות מהלא נכון נכשלת באופן שנראה כמו קוד שבור.
eval — מפרשים מתמשכים
קטע בשם “eval — מפרשים מתמשכים”תא Python או JavaScript שהמשתנים, הייבואים והנתונים שנטענו בו ממשיכים להתקיים בין קריאה לקריאה. דרגת exec; אינו בטוח להרצה מקבילה.
| ארגומנט | משמעות |
|---|---|
code |
התא |
description |
חובה. 5–10 מילים לתווית בתמלול |
language |
python (ברירת מחדל) או javascript |
reset |
משליך את המפרש ומתחיל נקי מלכתחילה |
- הביטוי האחרון מוצג חזרה כפי שמחברת עושה.
display()עובד, DataFrame של pandas מרונדר כטבלה, ואיור של matplotlib חוזר כתמונה שהתמלול מציג.- הקיצורים של IPython שאנשים מקלידים מתוך הרגל —
%pip,%cd,!cmd,%%bash,%%timeit— נכתבים מחדש כקוד רגיל.%pipגם מפנה אתsys.modules, כך שה־importהבא רואה את מה שזה עתה הותקן.
קריאה לכלים שלכם מתוך תא
קטע בשם “קריאה לכלים שלכם מתוך תא”contents = tool("read", {"path": "lib/auth.dart"})הגשר נכנס מחדש למרשם הכלים של מנגנון ההרצה, כך שמעקות בטיחות, אישור וכל עטיפה חלים בדיוק כפי שהם חלים על קריאה ששלח המודל. הוא נוסע על הצינור של הקרנל עצמו ולא על סוקט לולאה: בלי פורט, בלי סוד, בלי כלל יציאה.
הזמן הקצוב של התא הוא תקציב אי-פעילות (ברירת מחדל 5 דקות), והוא מושהה בזמן שקריאה דרך הגשר מתבצעת, כך שתא שמסתעף לסוכני משנה אינו נהרג באמצע ההסתעפות.
ask_user — לשאול את האדם שאלה
קטע בשם “ask_user — לשאול את האדם שאלה”דרגת read. הדרך היחידה שבה הרצה שואלת את המפעיל משהו. הוא מרנדר כרטיס ממוספר בשיחה וחוסם עד שמישהו עונה, מדלג, או שתפוג תקופת ההמתנה של השאלה. לעולם אל תכתבו את השאלה כהודעת צ’אט — זה מסיים את התור.
| ארגומנט | משמעות |
|---|---|
question |
מה לשאול |
context |
אופציונלי: מדוע אתם שואלים ומה תלוי בתשובה |
options[] |
אפשרויות, כל אחת {label, description?} |
allow_free_text |
אם תשובה מוקלדת מתקבלת |
multi_select |
אם אפשר לבחור כמה אפשרויות |
דילוג הוא הצלחה: המשיכו על בסיס הנחה מוצהרת ואל תשאלו שוב. פג־זמן הוא שגיאה עם אותה הנחיה. בקשות אישור (“האם מותר לי לעשות את זה?”) הן שער נפרד ומרונדרות כאותו כרטיס בשיחה.
נרשם רק כאשר קיימים גם יציאת שאלות וגם מרחב יעד. בלי אדם מחובר הקריאה נכשלת במקום להיחסם לנצח — אותה תנוחת כשל־סגור שנוקטת הכרעת prompt של מעקה בטיחות כשאין מאשר מחובר.
vibe_* — הכוונת עובדי רקע
קטע בשם “vibe_* — הכוונת עובדי רקע”נרשמים רק כשמצב vibe פעיל. כל החמישה בדרגת read: השער שייך לכלים של העובד, שם העריכה באמת קורית.
| כלי | ארגומנטים | הערות |
|---|---|---|
vibe_spawn |
brief, label, tier? |
חוזר מיד; העובד ממשיך לרוץ |
vibe_send |
worker_id, message |
מוסיף לתדרוך ומריץ מחדש |
vibe_wait |
worker_id, timeout_seconds? |
חוסם עד שהוא מגיע למצב סופי |
vibe_kill |
worker_id |
עוצר אותו |
vibe_list |
— | דרגה, מצב, זמן שחלף ותוצאה אחרונה |
tier הוא fast (עבודה מכנית עם מפרט ברור) או good (עיצוב, שיקול דעת, או סקירה של הפלט של עובד fast).