שאלות נפוצות

התקנה

מהן דרישות המערכת?

Triggerfish רץ על macOS (Intel ו-Apple Silicon), Linux (x64 ו-arm64) ו-Windows (x64). מתקין הבינארי מטפל בהכל. אם בונים מקוד מקור, נדרש Deno 2.x.

לפריסות Docker, כל מערכת שמריצה Docker או Podman מתאימה. תמונת הקונטיינר מבוססת על distroless Debian 12.

היכן Triggerfish מאחסן את הנתונים שלו?

הכל נמצא תחת ~/.triggerfish/ כברירת מחדל:

~/.triggerfish/
  triggerfish.yaml          # תצורה
  SPINE.md                  # זהות הסוכן
  TRIGGER.md                # הגדרת התנהגות יזומה
  logs/                     # קבצי לוג (מסובבים ב-1 MB, 10 גיבויים)
  data/triggerfish.db       # מסד נתונים SQLite (סשנים, זיכרון, מצב)
  skills/                   # מיומנויות מותקנות
  backups/                  # גיבויי תצורה עם חותמת זמן

פריסות Docker משתמשות ב-/data במקום. ניתן לדרוס את ספריית הבסיס עם משתנה הסביבה TRIGGERFISH_DATA_DIR.

האם ניתן להעביר את ספריית הנתונים?

כן. הגדירו את משתנה הסביבה TRIGGERFISH_DATA_DIR לנתיב הרצוי לפני הפעלת ה-daemon. אם אתם משתמשים ב-systemd או launchd, תצטרכו לעדכן את הגדרת השירות (ראו הערות פלטפורמה).

המתקין אומר שהוא לא יכול לכתוב ל-/usr/local/bin

המתקין מנסה קודם /usr/local/bin. אם זה דורש גישת root, הוא חוזר ל-~/.local/bin. אם אתם רוצים את המיקום ברמת המערכת, הריצו שוב עם sudo:

curl -sSL https://raw.githubusercontent.com/greghavens/triggerfish/master/scripts/install.sh | sudo bash

כיצד להסיר את Triggerfish?

# Linux / macOS
curl -sSL https://raw.githubusercontent.com/greghavens/triggerfish/master/scripts/uninstall.sh | bash

זה עוצר את ה-daemon, מסיר את הגדרת השירות (יחידת systemd או plist של launchd), מוחק את הבינארי ומסיר את כל ספריית ~/.triggerfish/ כולל כל הנתונים.

---

תצורה

כיצד לשנות את ספק ה-LLM?

ערכו את triggerfish.yaml או השתמשו ב-CLI:

triggerfish config set models.primary.provider anthropic
triggerfish config set models.primary.model claude-sonnet-4-20250514

ה-daemon מתאתחל אוטומטית לאחר שינויי תצורה.

היכן שמים מפתחות API?

מפתחות API מאוחסנים ב-keychain של מערכת ההפעלה שלכם (macOS Keychain, Linux Secret Service, או אחסון קובץ מוצפן ב-Windows/Docker). לעולם אל תשימו מפתחות API גולמיים ב-triggerfish.yaml. השתמשו בתחביר הפניה secret::

models:
  providers:
    anthropic:
      model: claude-sonnet-4-20250514
      apiKey: "secret:provider:anthropic:apiKey"

אחסנו את המפתח בפועל:

triggerfish config set-secret provider:anthropic:apiKey sk-ant-...

מה המשמעות של secret: בתצורה שלי?

ערכים עם קידומת secret: הם הפניות ל-keychain של מערכת ההפעלה. בעת ההפעלה, Triggerfish מפענח כל הפניה ומחליף אותה בערך הסוד הממשי בזיכרון. הסוד הגולמי לעולם אינו מופיע ב-triggerfish.yaml על הדיסק. ראו סודות ואישורים לפרטי backend לפי פלטפורמה.

מהו SPINE.md?

SPINE.md הוא קובץ הזהות של הסוכן שלכם. הוא מגדיר את שם הסוכן, המשימה, האישיות וקווי ההנחיה ההתנהגותיים. חשבו על זה כבסיס ל-system prompt. אשף ההגדרה (triggerfish dive) מייצר אחד עבורכם, אבל ניתן לערוך אותו בחופשיות.

מהו TRIGGER.md?

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

כיצד להוסיף ערוץ חדש?

triggerfish config add-channel telegram

זה מתחיל prompt אינטראקטיבי שמוביל אתכם דרך השדות הנדרשים (טוקן בוט, מזהה בעלים, רמת סיווג). ניתן גם לערוך ישירות את triggerfish.yaml תחת חלק channels:.

שיניתי את התצורה אבל שום דבר לא קרה

ה-daemon חייב להתאתחל כדי לקלוט שינויים. אם השתמשתם ב-triggerfish config set, הוא מציע להתאתחל אוטומטית. אם ערכתם את קובץ ה-YAML ידנית, אתחלו מחדש עם:

triggerfish stop && triggerfish start

---

ערוצים

למה הבוט שלי לא מגיב להודעות?

התחילו בבדיקת:

1. האם ה-daemon רץ? הריצו triggerfish status
2. האם הערוץ מחובר? בדקו את הלוגים: triggerfish logs
3. האם טוקן הבוט תקף? רוב הערוצים נכשלים בשקט עם טוקנים לא תקפים
4. האם מזהה הבעלים נכון? אם אתם לא מזוהים כבעלים, הבוט עשוי להגביל תגובות

ראו את מדריך פתרון בעיות ערוצים לרשימות בדיקה ספציפיות לערוץ.

מהו מזהה הבעלים ולמה הוא חשוב?

מזהה הבעלים אומר ל-Triggerfish איזה משתמש בערוץ נתון הוא אתם (המפעיל). משתמשים שאינם בעלים מקבלים גישה מוגבלת לכלים ועשויים להיות כפופים למגבלות סיווג. אם תשאירו את מזהה הבעלים ריק, ההתנהגות משתנה לפי ערוץ. ערוצים מסוימים (כמו WhatsApp) יתייחסו לכולם כבעלים, מה שמהווה סיכון אבטחה.

האם ניתן להשתמש במספר ערוצים בו-זמנית?

כן. הגדירו כמה ערוצים שרוצים ב-triggerfish.yaml. כל ערוץ מתחזק סשנים ורמת סיווג משלו. הנתב מטפל במסירת הודעות בכל הערוצים המחוברים.

מהן מגבלות גודל ההודעה?

ערוץ	מגבלה	התנהגות
Telegram	4,096 תווים	חלוקה אוטומטית
Discord	2,000 תווים	חלוקה אוטומטית
Slack	40,000 תווים	חיתוך (לא חלוקה)
WhatsApp	4,096 תווים	חיתוך
Email	ללא מגבלה קשיחה	הודעה מלאה נשלחת
WebChat	ללא מגבלה קשיחה	הודעה מלאה נשלחת

למה הודעות Slack נחתכות?

ל-Slack יש מגבלה של 40,000 תווים. בניגוד ל-Telegram ו-Discord, Triggerfish חותך הודעות Slack במקום לפצל אותן למספר הודעות. תגובות ארוכות מאוד (כמו פלטי קוד גדולים) עשויות לאבד תוכן בסוף.

---

אבטחה וסיווג

מהן רמות הסיווג?

ארבע רמות, מהפחות לרגישה ביותר:

1. PUBLIC - ללא הגבלות על זרימת נתונים
2. INTERNAL - נתונים תפעוליים סטנדרטיים
3. CONFIDENTIAL - נתונים רגישים (אישורים, מידע אישי, רשומות פיננסיות)
4. RESTRICTED - רגישות גבוהה ביותר (נתונים מפוקחים, קריטיים לציות)

נתונים יכולים לזרום רק מרמות נמוכות לרמות שוות או גבוהות. נתוני CONFIDENTIAL לעולם לא יכולים להגיע לערוץ PUBLIC. זהו כלל "אין כתיבה-למטה" ולא ניתן לדרוס אותו.

מה המשמעות של "זיהום סשן"?

כל סשן מתחיל ב-PUBLIC. כאשר הסוכן ניגש לנתונים מסווגים (קורא קובץ CONFIDENTIAL, שואל מסד נתונים RESTRICTED), זיהום הסשן מסלים בהתאמה. זיהום רק עולה, לעולם לא יורד. סשן שזוהם ל-CONFIDENTIAL אינו יכול לשלוח את הפלט שלו לערוץ PUBLIC.

למה אני מקבל שגיאות "כתיבה-למטה חסומה"?

הסשן שלכם זוהם לרמת סיווג גבוהה מהיעד. לדוגמה, אם ניגשתם לנתוני CONFIDENTIAL ואז ניסיתם לשלוח תוצאות לערוץ PUBLIC של WebChat, מנוע המדיניות חוסם זאת.

זה עובד כמתוכנן. לפתרון, או:

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

האם ניתן לכבות אכיפת סיווג?

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

---

ספקי LLM

אילו ספקים נתמכים?

Anthropic, OpenAI, Google Gemini, Fireworks, OpenRouter, ZenMux, Z.AI ומודלים מקומיים דרך Ollama או LM Studio.

כיצד failover עובד?

הגדירו רשימת failover ב-triggerfish.yaml:

models:
  primary:
    provider: anthropic
    model: claude-sonnet-4-20250514
  failover:
    - openai/gpt-4o
    - google/gemini-2.5-pro

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

הספק שלי מחזיר שגיאות 401 / 403

מפתח ה-API שלכם לא תקף או פג תוקף. אחסנו אותו מחדש:

triggerfish config set-secret provider:<name>:apiKey <your-key>

ואז אתחלו מחדש את ה-daemon. ראו פתרון בעיות ספקי LLM להנחיות ספציפיות לספק.

האם ניתן להשתמש במודלים שונים לרמות סיווג שונות?

כן. השתמשו בתצורת classification_models:

models:
  classification_models:
    RESTRICTED:
      provider: local
      model: llama-3.3-70b
    CONFIDENTIAL:
      provider: anthropic
      model: claude-sonnet-4-20250514

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

---

Docker

כיצד להריץ Triggerfish ב-Docker?

curl -sSL https://raw.githubusercontent.com/greghavens/triggerfish/master/deploy/docker/install.sh | bash

זה מוריד את סקריפט העטיפה של Docker וקובץ compose, מושך את התמונה ומריץ את אשף ההגדרה.

היכן נתונים מאוחסנים ב-Docker?

כל הנתונים העמידים נמצאים ב-Docker named volume (triggerfish-data) שמותקן ב-/data בתוך הקונטיינר. זה כולל תצורה, סודות, מסד הנתונים SQLite, לוגים, מיומנויות ומרחבי עבודה של סוכנים.

כיצד סודות עובדים ב-Docker?

קונטיינרים של Docker אינם יכולים לגשת ל-keychain של מערכת ההפעלה המארחת. Triggerfish משתמש באחסון קובץ מוצפן במקום: secrets.json (ערכים מוצפנים) ו-secrets.key (מפתח הצפנה AES-256), שניהם מאוחסנים ב-volume /data. התייחסו ל-volume כרגיש.

הקונטיינר לא מוצא את קובץ התצורה שלי

ודאו שהרכבתם אותו נכון:

docker run -v ./triggerfish.yaml:/data/triggerfish.yaml ...

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

כיצד לעדכן את תמונת Docker?

triggerfish update    # אם משתמשים בסקריפט העטיפה
# או
docker compose pull && docker compose up -d

---

מיומנויות ו-The Reef

מהי מיומנות?

מיומנות היא תיקייה המכילה קובץ SKILL.md שנותן לסוכן יכולות, הקשר או קווי הנחיה התנהגותיים חדשים. מיומנויות יכולות לכלול הגדרות כלים, קוד, תבניות והוראות.

מהו The Reef?

The Reef הוא שוק המיומנויות של Triggerfish. ניתן לגלות, להתקין ולפרסם מיומנויות דרכו:

triggerfish skill search "web scraping"
triggerfish skill install reef://data-extraction

למה המיומנות שלי נחסמה על ידי סורק האבטחה?

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

מהי תקרת סיווג על מיומנות?

מיומנויות מצהירות על רמת סיווג מקסימלית שבה מותר להן לפעול. מיומנות עם classification_ceiling: INTERNAL אינה יכולה להיות מופעלת בסשן שזוהם ל-CONFIDENTIAL ומעלה. זה מונע ממיומנויות לגשת לנתונים מעל אישור הגישה שלהן.

---

טריגרים ותזמון

מהם טריגרים?

טריגרים הם התעוררויות סוכן תקופתיות להתנהגות יזומה. אתם מגדירים מה הסוכן צריך לבדוק ב-TRIGGER.md, ו-Triggerfish מעיר אותו לפי לוח זמנים. הסוכן סוקר את ההוראות שלו, נוקט פעולה (בדיקת יומן, ניטור שירות, שליחת תזכורת) וחוזר לישון.

במה טריגרים שונים ממשימות cron?

משימות cron מריצות משימה קבועה לפי לוח זמנים. טריגרים מעירים את הסוכן עם ההקשר המלא שלו (זיכרון, כלים, גישה לערוצים) ומאפשרים לו להחליט מה לעשות בהתבסס על הוראות TRIGGER.md. Cron הוא מכני; טריגרים הם סוכניים.

מהן שעות שקט?

הגדרת quiet_hours ב-scheduler.trigger מונעת מטריגרים להיפעל בשעות מוגדרות:

scheduler:
  trigger:
    interval: "30m"
    quiet_hours: "22:00-07:00"

כיצד webhooks עובדים?

שירותים חיצוניים יכולים לשלוח POST לנקודת הקצה של webhook של Triggerfish כדי להפעיל פעולות סוכן. כל מקור webhook דורש חתימת HMAC לאימות וכולל זיהוי שידור חוזר.

---

צוותי סוכנים

מהם צוותי סוכנים?

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

במה צוותים שונים מתת-סוכנים?

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

האם צוותי סוכנים דורשים תוכנית בתשלום?

צוותי סוכנים דורשים את תוכנית Power ($149/חודש) בעת שימוש ב-Triggerfish Gateway. למשתמשי קוד פתוח שמריצים מפתחות API משלהם יש גישה מלאה -- כל חבר צוות צורך היסק מספק ה-LLM המוגדר שלכם.

למה המוביל של הצוות שלי נכשל מיד?

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

האם חברי צוות יכולים להשתמש במודלים שונים?

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

כמה זמן צוות יכול לרוץ?

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

מה קורה אם חבר צוות קורס?

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

---

שונות

האם Triggerfish הוא קוד פתוח?

כן, ברישיון Apache 2.0. קוד המקור המלא, כולל כל הרכיבים הקריטיים לאבטחה, זמין לביקורת ב-GitHub.

האם Triggerfish פונה הביתה?

לא. Triggerfish אינו יוצר חיבורים יוצאים מלבד לשירותים שהגדרתם במפורש (ספקי LLM, ממשקי API של ערוצים, אינטגרציות). אין טלמטריה, אנליטיקה או בדיקת עדכונים אלא אם מריצים triggerfish update.

האם ניתן להריץ מספר סוכנים?

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

מהו ה-gateway?

ה-gateway הוא מישור הבקרה הפנימי של Triggerfish בפרוטוקול WebSocket. הוא מנהל סשנים, מנתב הודעות בין ערוצים לסוכן, שולח כלים ואוכף מדיניות. ממשק הצ'אט של ה-CLI מתחבר ל-gateway כדי לתקשר עם הסוכן שלכם.

באילו פורטים Triggerfish משתמש?

פורט	מטרה	קישור
18789	Gateway WebSocket	localhost בלבד
18790	Tidepool A2UI	localhost בלבד
8765	WebChat (אם מופעל)	ניתן להגדרה
8443	WhatsApp webhook (אם מופעל)	ניתן להגדרה

כל הפורטים ברירת המחדל מקושרים ל-localhost. אף אחד מהם אינו חשוף לרשת אלא אם הגדרתם אחרת במפורש או שאתם משתמשים ב-reverse proxy.