📘 תיעוד 44

משימות רקע וניטור

Grok מריץ תהליכים ארוכי טווח בלי לחסום את השיחה. מסמך זה מכסה פקודות רקע, את פקודת /loop, את הכלי monitor, ואת ה-scheduler.

#פקודות רקע

הגדר background: true בכלי run_terminal_command כדי להריץ פקודה ברקע. הוא מחזיר task ID באופן מיידי; אחזר פלט באמצעות get_command_or_subagent_output.

#כיצד זה עובד

1. הסוכן קורא ל-run_terminal_command עם background: true.
2. הפקודה מתחילה ברקע.
3. הסוכן מקבל task_id להתייחסות מאוחרת יותר.
4. כאשר הפקודה מסתיימת, מופיעה הודעה בשיחה.

#קבלת פלט

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

• get_command_or_subagent_output(task_id): פלט נוכחי ומצב ללא המתנה
• get_command_or_subagent_output(task_id, timeout_ms=30000): המתנה עד למספר אלפיות השנייה הנתון לסיום

#המתנה למספר משימות

השתמש ב-wait_commands_or_subagents כדי להמתין למספר משימות בבת אחת:

• task_ids: רשימת מזהי המשימות להמתנה (לכל היותר 20)
• mode: הערך wait_any חוזר כאשר המשימה הראשונה מסתיימת; wait_all ממתין לכל המשימות
• timeout_ms: זמן ההמתנה המרבי, באלפיות שנייה (ברירת מחדל: 30 שניות)

הכלי מחזיר את המצב והפלט עבור כל משימה שאתה מציין ברשימה.

#עצירת משימות רקע

השתמש ב-kill_command_or_subagent(task_id) כדי לעצור משימת רקע או סוכן משנה שרצים. הכלי שולח SIGTERM, ולאחר מכן SIGKILL, לתהליכי מעטפת (shell), ושולח Cancel ו-Shutdown לסוכני משנה. הוא מדווח על הצלחה אם המשימה נעצרה או שכבר הסתיימה.

#תרחישי שימוש נפוצים

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

#העברת משימה רצה לרקע

ב-TUI האינטראקטיבי, לחץ על Ctrl+B כדי לשלוח את פקודת החזית הרצה לרקע. זהו קיצור הדרך היחיד להעברה לרקע, אם כי שליחת הודעה חדשה באמצע פקודה מעבירה גם היא את אותה פקודה לרקע במקום לעצור אותה. עשה זאת כאשר:

• פקודה נמשכת זמן רב מהמצופה.
• אתה רוצה לשאול את הסוכן משהו אחר בזמן שפקודה רצה.
• אתה מבין שתהליך הוא ארוך טווח לאחר שהוא כבר התחיל.

המשימה ממשיכה לרוץ, ואתה מקבל הודעה כאשר היא מסתיימת.

#הפקודה /loop

הפקודה /loop מריצה הנחיה במרווח זמנים חוזר. היא שימושית למשימות דגימה (polling), בדיקות תקופתיות וניטור מתמשך.

#תחביר

/loop [interval] <prompt>

פורמט המרווח תומך ב:

#דוגמאות

/loop 5m Check if the test suite passes and report any failures
/loop 2h Summarize new commits since the last check
/loop 60s Check if the dev server at localhost:3000 is responding

#התנהגות

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

#הכלי monitor

הכלי monitor מזרים אירועים מסקריפט ארוך טווח. כל שורת פלט הופכת להודעה בשיחה. הכלי monitor הוא המקבילה המוזרמת ל-/loop: השתמש ב-/loop עבור בדיקות תקופתיות, והשתמש ב-monitor עבור זרמי אירועים בזמן אמת.

#כיצד זה עובד

1. אתה מספק פקודת מעטפת (command) ותיאור קצר (description) שמופיע בכל הודעה.
2. Grok ממזג את ה-stdout וה-stderr של הפקודה לקובץ פלט יחיד.
3. כל שורה חדשה בקובץ זה הופכת להודעה שנמסרת לשיחה.
4. ה-monitor רץ עד שהפקודה מסתיימת או שאתה עוצר אותה.

#הנחיות לכתיבת סקריפטים

• השתמש תמיד ב-grep --line-buffered בצינורות (pipes). ללא זה, אגירת צינור גורמת לעיכוב אירועים בדקות.
• טפל בכשלים זמניים בלולאות דגימה (curl ... || true). בקשה בודדת שנכשלה לא אמורה לעצור את ה-monitor.
• השתמש במסננים בררניים. כל שורה הופכת להודעה, לכן לעולם אל תעביר לוגים גולמיים בצינור.
• הגדר מרווחי דגימה שמתאימים למקור. השתמש ב-30 שניות או יותר עבור ממשקי API מרוחקים כדי לכבד מגבלות קצב, וב-0.5 עד 1 שניות לבדיקות מקומיות.
• גם stdout וגם stderr מייצרים אירועים. נתב מחדש פלט שאינך רוצה כאירועים, לדוגמה הוסף 2>/dev/null, או סנן אותו החוצה.

#דוגמאות

# Watch for errors in a log file
tail -f /var/log/app.log | grep --line-buffered "ERROR"

# Monitor file changes in a directory
inotifywait -m --format '%e %f' /watched/dir

# Poll GitHub for new PR comments
last=$(date -u +%Y-%m-%dT%H:%M:%SZ)
while true; do
  now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
  gh api "repos/owner/repo/issues/123/comments?since=$last" \
    --jq '.[] | "\(.user.login): \(.body)"'
  last=$now; sleep 30
done

#מוניטורים קבועים

הגדר persistent: true עבור מוניטורים שאמורים לרוץ לכל אורך זמן ההפעלה (session):

• ניטור PR
• מעקב אחר קובצי יומן (log tailing)
• צפייה במצב CI

עצור מוניטורים קבועים באמצעות kill_command_or_subagent(task_id).

#בקרת נפח

אם מוניטור מייצר יותר מדי אירועים, Grok עוצר אותו אוטומטית. כאשר זה קורה, הפעל מחדש את המוניטור עם מסנן הדוק יותר. העדף grep --line-buffered, awk, או סקריפט מעטפת שפולט רק את האירועים שחשובים לך.

#המתזמן

המתזמן מספק API ברמה נמוכה יותר ליצירת משימות חוזרות. /loop היא מעטפת נוחות סביב המתזמן.

#scheduler_create

צור משימה מתוזמנת:

#scheduler_list

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

#scheduler_delete

בטל משימה מתוזמנת לפי מזהה (ID). מחזיר הצלחה אם המשימה נמצאה והוסרה.

#חלונית המשימות

ב-TUI האינטראקטיבי, לחץ על Ctrl+G כדי להציג או להסתיר את חלונית המשימות. חלונית זו מציגה, בתצוגה אחת:

• סוכני משנה שרצים ואת ההתקדמות שלהם
• משימות רקע פעילות ואת המצב שלהן
• משימות monitor ו-/loop, כל אחת עם תג המציג ספירת שורות חיה
• מזהה המשימה (task ID) עבור כל רשומה

כדי להציג או להסתיר את תור ההנחיות במקום זאת, לחץ על Ctrl+;.

#שורת המצב של מה שעדיין רץ

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

◎ 1 command · 2 monitors · 1 loop · 1 subagent still running

היא סופרת פקודות רקע רצות, מוניטורים, משימות /loop מתוזמנות וסוכני משנה ברקע, ומתעדכנת בשידור חי כאשר כל אחד מהם מסתיים. כל אחד מהם יכול להעיר את הסוכן לתור חדש (פקודות וסוכני משנה עם סיומם, מוניטורים בעת אירועים, לולאות לפי הטיימר שלהן), כך שהחיווי נשאר עד שלא נותר דבר. ספירות הריצה מתקיימות רק בשורת מצב זו: סיומים מופיעים בתמליל כתג בודד של "Task completed", וסמני "Worked for" נשארים פשוטים, שכן התמליל לעולם אינו חוזר או מציין מחדש את ספירות הריצה.

בזמן שתור ממתין לעבודת רקע (חסום בקריאה ל-get_task_output או ל-wait_tasks), שורת המצב מוסיפה רמז לכך שהקלדה מקבלת שליטה באופן מיידי:

◎ 1 command still running · send a message to interrupt

אותו רמז מופיע בתור ◎ waiting · send a message to interrupt כאשר הסוכן ממתין למשהו ללא מונה חי (המתנת sleep, או עבודה שכבר הסתיימה). שליחת הודעה קוטעת את ההמתנה ומריצה את ההודעה שלך מיד. התמליל שומר על המבנה הרגיל שלו לכל האורך: סמן "Worked for" אחד כאשר התור מסתיים. כאשר סיום מעיר את הסוכן והוא משיב, תשובה זו מקבלת סמן "Worked for" משלה; יקיצה שהסוכן עונה עליה בשקט אינה משאירה עקבות בתמליל, אלא אם היא נכשלת, ובמקרה כזה שורת "Turn failed" מופיעה אפילו עבור יקיצה שקטה, כדי שהוראה קבועה לעולם לא תפסיק לפעול באופן בלתי נראה.

#תרחישי שימוש ודפוסים

#שרת פיתוח + כתיבת קוד

הפעל שרת פיתוח ברקע והמשך בכתיבת קוד:

Start the dev server with `npm run dev` in the background, then implement the login form.

הסוכן מריץ את שרת הפיתוח עם background: true וממשיך בכתיבת קוד. כאשר השרת מתחיל לפעול, אתה רואה הודעה.

#ניטור בדיקות רציף

/loop 5m Run the test suite and report any new failures since the last run

בכל 5 דקות, הסוכן מריץ בדיקות ומדווח רק על כשלים חדשים.

#ניטור קובצי יומן

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

Monitor the application log for ERROR and WARN entries. Use:
tail -f /var/log/app.log | grep --line-buffered -E "ERROR|WARN"

כל שגיאה או אזהרה מופיעה כהודעה בשיחה.

#מעקב אחר צינור CI

/loop 2m Check the status of the GitHub Actions run for this PR. Report when it completes.

#שיטות מומלצות

• השתמש ב-background עבור פקודות ארוכות חד פעמיות (בניות, סוויטות בדיקה, הפעלות שרת)
• השתמש ב-/loop עבור בדיקות תקופתיות (מצב CI, הרצות בדיקות, בדיקות תקינות)
• השתמש ב-monitor עבור זרמי אירועים בזמן אמת (מעקב אחר קובצי יומן, מעקב אחר קבצים)
• השתמש ב-scheduler_create עם recurring: false עבור משימות חד פעמיות מושהות
• שמור על מסנני מוניטור הדוקים: העדף grep --line-buffered על פני זרמי יומן גולמיים
• אל תשתמש בלולאות שינה (sleep loops) בפקודות רגילות לצורך דגימה: השתמש במקום זאת ב-get_command_or_subagent_output עם timeout_ms
• הגדר מרווחי דגימה סבירים: 30 שניות ומעלה עבור ממשקי API מרוחקים כדי להימנע ממגבלות קצב, ומרווחים קצרים יותר לבדיקות מקומיות