📘 תיעוד 44

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

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

#פקודות רקע

הגדירו את block_until_ms ל-0 בכלי run_terminal_command כדי להריץ פקודה ברקע. הוא מחזיר מזהה משימה מיד. אחזרו פלט עם get_command_or_subagent_output.

#איך זה עובד

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

#קבלת פלט

השתמשו ב-get_command_or_subagent_output כדי לבדוק פקודת רקע או תת-סוכן. העבירו את task_ids כרשימה (מזהה אחד הוא מערך בן איבר אחד, מקסימום 20):

• השמיטו את timeout_ms, או העבירו 0, לתצלום מצב לא חוסם.
• timeout_ms חיובי ממתין להשלמה. כמה מזהים ממתינים עד שכולם מסתיימים.

timeout_ms חיובי מוגבל לשעה אחת (3600000 ms). מארחים עם דדליין תעבורה קצר יותר מגדירים את GROK_MAX_WAIT_BLOCK_MS (מילישניות רגילות. ערכים שלא ניתן לפרש שומרים על ברירת המחדל).

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

#הריגת משימות רקע

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

#מקרי שימוש נפוצים

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

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

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

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

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

#הפקודה /loop

/loop מריץ הנחיה במרווח חוזר. היא שימושית לסקר משימות, לבדיקות תקופתיות, ולניטור רציף.

#תחביר

/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. אתם מספקים פקודת shell (command) ו-description קצר שמופיע בכל התראה.
2. גרוק ממזג את stdout ואת stderr של הפקודה לקובץ פלט אחד.
3. כל שורה חדשה בקובץ הזה הופכת להתראה שנמסרת לשיחה.
4. המוניטור רץ עד שהפקודה יוצאת או שאתם עוצרים אותו.

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

• תמיד השתמשו ב-grep --line-buffered בצינורות. בלעדיו, אגירת הצינור מעכבת אירועים בדקות.
• טפלו בכשלים חולפים בלולאות סקר (curl ... || true). בקשה כושלת אחת לא אמורה לעצור את המוניטור.
• השתמשו במסננים בררניים. כל שורה הופכת להודעה, אז אל תעבירו בצינור יומנים גולמיים.
• הגדירו מרווחי סקר שתואמים למקור. השתמשו ב-30 שניות או יותר עבור ממשקי API מרוחקים כדי לכבד מגבלות קצב, וב-0.5 עד שנייה אחת עבור בדיקות מקומיות.
• גם 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 למוניטורים שצריכים לרוץ לכל משך ההפעלה:

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

עצרו מוניטורים מתמידים עם kill_command_or_subagent(task_id).

#בקרת נפח

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

#המתזמן

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

#scheduler_create

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

כל ירייה רצה בתת-סוכן רקע מנותק. אין אפשרות להריץ אחת כתור בשיחה.

#scheduler_list

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

#scheduler_delete

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

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

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

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

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

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

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

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

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

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

◎  1 command still running · send a message to interrupt

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

#מקרי שימוש ודפוסים

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

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

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

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

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

/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.

#שיטות עבודה מומלצות

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