📘 תיעוד 43

מצב תכנון

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

#מה מצב תכנון עושה

כשמצב תכנון פעיל, הסוכן:

1. קורא ומחפש בבסיס הקוד כדי להבין דפוסים וארכיטקטורה קיימים
2. מתכנן גישת מימוש וכותב אותה לקובץ התוכנית
3. עשוי להשתמש ב-ask_user_question כדי להבהיר שאלות מסוימות
4. קורא ל-exit_plan_mode כדי להציג את התוכנית לאישור שלכם

עבור הסוכן הראשי, הרצת headless עם --permission-mode plan מחזיקה את מצב התכנון ודוחה כל עריכה מלבד קובץ התוכנית, במסלול ה-native ובמסלול ה-daemon. קריאת הכלי נכשלת עם הודעה קצרה שרק קובץ התוכנית ניתן לעריכה. מסלול ה-native מציין את הנתיב של הקובץ הזה. מצב תכנון אינטראקטיבי (בלי החזקה) עושה אותו דבר על ערכת הכלים grok. על ערכת הכלים של התאימות (כלי ה-write וכלי ה-string-replace שלה) ובמסלול ה-daemon הוא מתיר כל עריכת markdown ודוחה את השאר. זה תקף בכל מצב הרשאה, כולל always-approve. הפרדת התכנון מהמימוש מאפשרת לכם לסקור ולתקן את הגישה לפני שנכתב קוד כלשהו.

במסלול ה-daemon, האופן שבו הרצת headless מתייחסת לתוכנית שנשמרה מתואר בתוכניות שנשמרו במסלול ה-daemon.

#איך נכנסים למצב תכנון

#כניסה ביוזמת הסוכן

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

טריגרים טובים למצב תכנון:

• "Add user authentication to the app": עמימות אמיתית (session מול JWT, אחסון טוקן, מבנה middleware)
• "Redesign the data pipeline": ארגון מחדש גדול שבו גישה שגויה מבזבזת מאמץ משמעותי
• "Add caching to the API": כמה גישות סבירות (Redis מול in-memory מול file-based)
• "Add real-time updates": החלטת ארכיטקטורה (WebSockets מול SSE מול polling)

לא מתאים למצב תכנון:

• "Add a delete button to the user profile": נתיב מימוש ברור
• "Fix the typo in the README": פשוט וישיר
• "Update the error handling in the API": להתחיל לעבוד, לשאול שאלות ספציפיות אם צריך
• "Can we work on the search feature?": המשתמש רוצה להתחיל, לא לתכנן

#כניסה ביוזמת המשתמש

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

• --permission-mode plan: הדגל חל על ה-TUI ועל grok -p. grok agent stdio ו-grok agent serve מתעלמים מ-plan. סשן ה-welcome, /new, worktree חדש, סשן ענן, placeholder ההגדרות, מזהה בעל שם (--session-id, או worktree שנוצר עם מזהה סשן מועדף), resume שנופל חזרה לסשן חדש, ובחירה זרה מתחילים ב-plan רק כשאפשר להתחיל plan (כלי plan מופעלים, לא צ'אט, ולמזהה חדש אין מחשב /remote מחובר), ומתחילים ב-Ask אחרת, עם always-approve ו-auto כבויים. --chat לא יוצר את סשן ה-welcome. מזהה בעל שם נשאר על המכונה הזו. spawn של לוח הבקרה עוקב אחרי שבב המצב שלו. שבב Plan שלא יכול להתחיל הופך ל-Ask, והסוכן הזה מתחיל ב-Ask. resume או fork ב-TUI שומר את המצב השמור. החלפה של סשן שנמצא ב-plan מתחילה ב-plan כשאפשר להתחיל plan, וב-Ask כשאי אפשר. כל החלפה אחרת שומרת את ה-mirror ולא מתחילה ב-plan. סשן שקשור למכונה מרוחקת לא מתחיל במצב תכנון. תחת הדגל, /new בלשונית מרוחקת וסשן שנפתח על המחשב המחובר מתחילים ב-Ask. סשן ריק שנמצא ב-plan נבנה מחדש ב-plan כשאפשר להתחיל plan, וב-Ask כשאי אפשר. רק סשן שאינו ב-plan שומר Always-approve או Auto שנבחרו במפורש. מעבר אל מחשב מתחיל כל סשן ריק אחר ב-Ask, ומעבר חזרה ממנו מתחיל אותו ב-plan כשאפשר להתחיל plan וב-Ask כשאי אפשר. headless מגדיר מצב תכנון על הסשן שהוא פותח כשלריצה יש פרומפט, כולל resume או fork, ו-exit_plan_mode ב-headless לא מאושר, כך שמצב התכנון מוחזק לאורך הריצה. שטיפת זיכרון בלי פרומפט לא שולחת החזקה, ואישור תוכנית שחודש נשאר חונה. ב-daemon, -r <id> --fork-session עושה fork ומצב התכנון מוחזק לאותה ריצה. fork לפי כותרת או --continue נדחה (the daemon forks a session only by session id), ו---session-id יחד עם --fork-session נדחה.
• /plan: כניסה למצב תכנון. כשהסשן במנוחה, מצב התכנון מחכה לפרומפט הבא שלכם. כשתור רץ, מצב התכנון מופעל מיד. הריצו /plan <description> כדי להיכנס למצב תכנון ולהתחיל תור עם התיאור הזה בצעד אחד.
• Shift+Tab: מחזור מצב הסשן: Normal, אחר כך Plan, אחר כך Auto-review, אחר כך Always-approve, אחר כך Normal. המחזור מדלג על Auto-review כששער המצב האוטומטי כבוי. מ-Normal, לחיצה אחת נוחתת על Plan.

אחרי שקיימת תוכנית, הריצו /view-plan (כינויים /show-plan, /plan-view) כדי לפתוח מחדש את התצוגה המקדימה השמורה שלה.

#קובץ התוכנית

התוכנית נכתבת ל-plan.md בתוך תיקיית הסשן (~/.grok/sessions/<cwd>/<session-id>/plan.md, כאשר <cwd> הוא שם תיקייה מקודד, לא הנתיב המילולי).

קובץ התוכנית מכיל:

• מקטע Context שמסביר למה השינוי נעשה
• הגישה המומלצת (לא כל חלופה)
• הנתיבים של קבצים קריטיים לשינוי
• פונקציות וכלי עזר קיימים לשימוש חוזר, עם נתיבי הקבצים שלהם
• מקטע אימות שמתאר איך לבדוק את השינויים מקצה לקצה

#אישור התוכנית

כשהסוכן מסיים לתכנן, הוא קורא לכלי exit_plan_mode. הכלי קורא את קובץ התוכנית מהדיסק, וה-TUI פותח תצוגה מקדימה ניתנת לגלילה של התוכנית עם סרגל פעולות לאורך התחתית.

אם הסוכן יוצא בלי לכתוב תוכנית (plan.md ריק או חסר), אותו משטח אישור עדיין נפתח עם הודעת מצב ריק ברורה, כדי שתוכלו לאשר ולהתחיל לממש, לבקש שינויים (לשלוח את הסוכן חזרה לתכנון), או לצאת. במצב מינימלי הודעת הריק נכתבת ל-scrollback וכותרת רצועת הבקרים נקראת No plan written yet.

#סקירת התוכנית

גללו את התוכנית עם מקשי החצים או j/k. סרגל הפעולות מציג את קיצורי הדרך האלה:

לחצו Tab כדי להעביר מיקוד בין תצוגת התוכנית לפרומפט.

בפרומפט כל אות מוקלדת, כולל a, כך שהערה יכולה להתחיל בכל אות. כדי לאשר מתוך הפרומפט, לחצו Tab כדי לעבור לתצוגה, ואז לחצו a. כשהסקירה נפתחת בזמן שאתם מקלידים ואין פרומפט הרשאה שממתין, המיקוד מתחיל בפרומפט. טופס /feedback פתוח, פרומפט בתור שנערך, או סרגל החיפוש, הסינון או ה-goto של מציג הבלוקים נחשבים להקלדה. בזמן שחלונית המשימות או ה-dock מחזיקים את התצוגה סגורה, המיקוד נשאר איפה שהיה.

הסקירה שאחרי תור ממתינה בזמן ש-/feedback, שאלה, elicitation, או עריכת פרומפט בתור פתוחים. פקודה רצה כמו /compact מחזיקה אותה עד שהפקודה מסתיימת. תור מודל שמתחיל שומר את ההמתנה, והסקירה נפתחת כשהתור הזה מסתיים, על התצוגה אם ה-composer ריק. סגירת /feedback או עריכת פרומפט בתור בזמן שתור רץ עובדת באותו אופן. הסקירה שנפתחת כשהתוכנית נכתבת (exit_plan_mode) אף פעם לא ממתינה. כרטיס הרשאה מחזיק סקירה שכבר המתינה. הוא לא מונע מסקירה להיפתח מתחתיו. פרומפט שהוחזר ל-composer, כי הסוכן אף פעם לא אישר אותו, מחזיק את סקירת התוכנית בזמן שהפרומפט יושב ב-composer, שאלה, elicitation, כרטיס הרשאה, הערה מוטמעת פתוחה, או עריכת פרומפט בתור. ההחזקה מסתיימת ברגע שה-composer וה-stashes האלה ריקים, אחרי שליחה או ניקוי. סקירה שמגיע זמנה בזמן שהפרומפט הזה עדיין שם ממתינה באותו אופן. ניקוי ה-composer נחשב להקלדה, כך שהסקירה נפתחת בהערות. הערת /remember נשארת פתוחה מעל סקירה שהסוכן פתח עם exit_plan_mode, ומעל הסקירה שנפתחת אחרי התור.

בזמן שתצוגת אישור התוכנית פתוחה, Ctrl+P (לוח פקודות → מודל) עדיין עובד להחלפת מודל לפני שלוחצים a לאישור.

#מתן משוב

לתצוגת האישור יש שלושה מצבי מיקוד:

• Preview: גלילה בתוכנית ובחירת שורות להערה.
• Commenting: הוספת הערה מוטמעת לטווח השורות שנבחר (לחצו c, או Enter על שורה).
• Prompt: הקלדת הערות תיקון חופשיות.

לחצו Tab כדי לעבור בין התצוגה לפרומפט. כשאתם שולחים משוב, הערות מוטמעות, הערות חופשיות, או שתיהן, הסוכן מקבל אותו ומתקן את התוכנית. מצב התכנון נשאר פעיל כדי שתוכלו לחזור שוב. פקודת pager מלאה שהוקלדה בפרומפט (לדוגמה /feedback <text> או /compact) רצה כפקודה במקום להישלח כהערות. הסקירה נשארת פתוחה. לחיצה על a בתצוגה בזמן שפקודה כזו יושבת בפרומפט נדחית עד שתריצו אותה עם Enter או תמחקו אותה.

#יציאה מתצוגת האישור

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

#מחזור החיים של מצב תכנון

למכונת המצבים של מצב התכנון יש ארבעה מצבים:

מעברים:

Inactive    --> Active   (enter_plan_mode tool called and approved -- skips Pending)
Inactive    --> Pending  (you toggle plan mode on while the session is idle)
Inactive    --> Active   (you toggle plan mode on while a turn is running)
Pending     --> Active   (your first prompt activates plan mode)
Active      --> Inactive (exit_plan_mode approved, or you toggle plan mode off when idle)
Active      --> ExitPending (you toggle plan mode off while a turn is in-flight)
ExitPending --> Inactive (after the turn completes)

מצב התכנון נשמר לדיסק ושורד הפעלות מחדש של התהליך. מצבים חולפים (Pending, ExitPending) מכווצים ל-Inactive בהפעלה מחדש כי הם תלויים באינטראקציות שעדיין רצות.

#עריכות במהלך מצב תכנון

במהלך מצב תכנון פעיל, עריכות של קובץ התוכנית מאושרות אוטומטית בלי בקשה, כך שהסוכן יכול לחזור על התוכנית בחופשיות. תחת החזקת תוכנית ב-headless, עריכות של הסוכן הראשי לכל קובץ אחר נדחות בשני המסלולים, עם הודעה קצרה שרק קובץ התוכנית ניתן לעריכה. מסלול ה-native מציין את הנתיב של הקובץ הזה. מצב תכנון אינטראקטיבי דוחה עריכות שאינן של קובץ התוכנית בערכת הכלים grok, ודוחה עריכות שאינן markdown בערכת הכלים של התאימות ובמסלול ה-daemon.

האכיפה הזו עצמאית ממצב ההרשאה:

• Always-approve (yolo) נשאר דרוך מתחת למצב תכנון. כלי שאינם עריכה (פקודות bash, קריאות, כלי MCP) עדיין רצים אוטומטית, אבל עריכות הקבצים של הסוכן הראשי חסומות עד שתאשרו יציאה ממצב תכנון. אחרי שהתוכנית מאושרת, always-approve חוזר למימוש.
• פקודות Bash לא נבדקות לכתיבת קבצים. מצב התכנון חוסם את כלי העריכה, לא הפניית shell.
• תת-סוכנים לא מכוסים בשער העריכה של מצב התכנון של סשן ההורה. כל תת-סוכן מתחיל עם עוקב מצב תכנון חדש (Inactive), כך שתת-סוכן general-purpose (או אחר שמסוגל לכתוב) יכול לערוך קבצים בזמן שההורה עדיין במצב תכנון, והוא יורש את מצב ההרשאה של ההורה (כולל always-approve). סוגים לקריאה בלבד כמו explore נשארים מוגבלים על ידי ערכת הכלים שלהם. תת-סוכן שהופעל עם Task עוקב אחרי כללי ה-allow. במסלול ה-native כלי workflow לא נחסם במצב תכנון. מסלול ה-daemon מסרב ל-workflow ב-Plan.

דגל הסטטוס מציג plan בזמן שמצב התכנון פעיל. אם always-approve מופעל מתחת, הדגל שלו חוזר להופיע כשמצב התכנון יוצא.

#מצב תכנון ודחיסה

כש-/compact רץ במהלך סשן עם מצב תכנון פעיל, מצב התכנון נשמר. ההקשר הדחוס כולל תזכורת שמצב התכנון פעיל, כך שהסוכן ממשיך לתכנן אחרי הדחיסה.

#מתי מצב תכנון מתאים

השתמשו במצב תכנון עבור:

• משימות עם עמימות ארכיטקטונית משמעותית (כמה גישות סבירות)
• דרישות לא ברורות שצריכות חקירה לפני מימוש
• ארגון מחדש בעל השפעה גבוהה שבו גישה שגויה מבזבזת מאמץ משמעותי

דלגו על מצב תכנון עבור:

• משימות עם נתיב מימוש ברור
• תיקוני באגים שבהם התיקון ברור אחרי שמבינים את הבאג
• הוספת יכולות שעוקבות אחרי מוסכמות קיימות
• שינויים פשוטים וישירים (שינוי שם, עיצוב, הוספת בדיקות)
• משימות מחקר וחקירה (השתמשו בתת-סוכנים במקום)