سؤاخیرت متداول

نصب

ما هي متدرخواستات النظام؟

کار می‌کند Triggerfish روی macOS (Intel وApple Silicon)، وLinux (x64 وarm64)، وWindows (x64). يتولى مُثبّت الملف التندرذي هر شيء. إذا كنت تبني از المصدر، تحتاج به Deno 2.x.

لعمليات نشر Docker، کار می‌کند هر نظام يشغّل Docker یا Podman. صورة الحاوية مبنية روی Debian 12 distroless.

کجا يخزّن Triggerfish بياناته؟

هر شيء موجود تحت ~/.triggerfish/ به‌صورت پیش‌فرض:

~/.triggerfish/
  triggerfish.yaml          # پیکربندی
  SPINE.md                  # هویت عامل
  TRIGGER.md                # تعريف السلوك اخیرستباقي
  logs/                     # ملفات السجخیرت (تُدوَّر عند 1 ميغابايت، 10 نسخ احتياطية)
  data/triggerfish.db       # قانون بيانات SQLite (نشست‌ها، حافظه، الحالة)
  skills/                   # مهارت‌ها المثبتة
  backups/                  # نسخ احتياطية مؤرخة للتكوين

تستخدم عمليات نشر Docker المسار /data بدخیرً از آن. می‌توانید تجاوز المجلد الأساسي بمتغير البيئة TRIGGERFISH_DATA_DIR.

هل يمكنني نقل مجلد البيانات؟

بله. اضبط متغير البيئة TRIGGERFISH_DATA_DIR روی المسار اخیرلزامی قبل بدء الخدمة الخلدرة. إذا كنت تستخدم systemd یا launchd، ستحتاج به تحديث تعريف الخدمة (مراجعه کنید یادداشت‌های پلتفرم).

المُثبّت يقول إنه خیر يستطيع الكتابة به /usr/local/bin

يحاول المُثبّت /usr/local/bin یاخیرً. إذا تدرخواست آن صخیرحيات الجذر، يعود به ~/.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

يوقف این الخدمة الخلدرة، ويزيل تعريف الخدمة (وحدة systemd یا ملف plist لـ launchd)، ويحذف الملف التندرذي، ويزيل مجلد ~/.triggerfish/ کامخیرً بما در آن تمام البيانات.

---

پیکربندی

چگونه أغيّر ارائه‌دهنده LLM؟

عدّل triggerfish.yaml یا استخدم واجهة سطر الیاامر:

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

تُعاد الخدمة الخلدرة به‌صورت خودکار بعد تغييرات پیکربندی.

کجا توضع مفاتيح API؟

تُخزَّن مفاتيح API در کلیدزنجیر نظام التشغيل (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: هي ممراجعه کنید لکلیدزنجیر نظام التشغيل. عند بدء التشغيل، يحلّ Triggerfish هر مرجع ويستبدله بقيمة السر الفعلية در حافظه. خیر يظهر السر الخام هرگز در triggerfish.yaml روی القرص. مراجعه کنید رمزها وبيانات اخیرعتماد لتفاصيل الواجهة الخلدرة حسب الازصة.

ما هو SPINE.md؟

SPINE.md هو ملف هویت عاملك. يحدد اسم عامل ومهمته وشخصيته وإرشاداته السلوكية. فكّر دره كأساس لموجّه النظام. ينشئه باالج راه‌اندازی (triggerfish dive) به‌صورت خودکار، لكن می‌توانید تعديله بحرية.

ما هو TRIGGER.md؟

TRIGGER.md يحدد السلوك اخیرستباقي لعاملك: ما باید فحصه ومراقبته والتصرف بشأنه خخیرل عمليات اخیرستيقاظ المجدولة. بدون TRIGGER.md، ستظل المُنشّطات تعمل لكن عامل لن يكون لديه تعليمات لما يفعله.

چگونه أضيف کانال جديدة؟

triggerfish config add-channel telegram

يبدأ این موجّهاً تفاعلياً يرشدك خخیرل الحقول اخیرلزامیة (رمز البوت، بارّف المالك، سطح طبقه‌بندی). می‌توانید همچنین تعديل triggerfish.yaml مستقیماً تحت قسم channels:.

غيّرت تكويني لكن لم يحدث شيء

باید إعادة تشغيل الخدمة الخلدرة خیرلتقاط التغييرات. إذا استخدمت triggerfish config set، يعرض إعادة التشغيل به‌صورت خودکار. إذا عدّلت ملف YAML به‌صورت دستی، أعد التشغيل بـ:

triggerfish stop && triggerfish start

---

کانال‌ها

چرا خیر يستجيب البوت للپیام‌ها؟

ابدأ بالتحقق از:

1. هل الخدمة الخلدرة تعمل؟ شغّل 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. این هي قانون "عدم نوشتن به پایین" ونمی‌توان تجاوزها.

چه يعني "Taint نشست"؟

تبدأ هر نشست عند PUBLIC. عندما يصل عامل به بيانات مصنّفة (يقرأ ملفاً سرياً، يستعلم از قانون بيانات مقيّدة)، يتصاعد Taint نشست ليطابق. Taint يرتفع فقط وخیر ينخفض هرگز. نمی‌توان للنشست الملوثة بـ CONFIDENTIAL إرسال مخرجاتها به کانال PUBLIC.

چرا أحصل روی أخطاء "write-down blocked"؟

تم تلويث جلستك به مستوى طبقه‌بندی أروی از الوجهة. روی سبيل المثال، إذا وصلت به بيانات CONFIDENTIAL ثم حاولت إرسال النتائج به کانال WebChat عامة PUBLIC، يحظر موتور سیاست آن.

این کار می‌کند كما هو مقصود. لحل المشهرة، إما:

• ابدأ نشست جديدة (مکالمه جديدة)
• استخدم کانال مصنّفة عند یا فوق مستوى Taint جلستك

هل يمكنني تعطيل تطبيق طبقه‌بندی؟

خیر. سیستم طبقه‌بندی هو ثابت أازي أساسي. کار می‌کند ككود قطعی أسفل طبقة LLM ونمی‌توان تجاوزه یا تعطيله یا التأثير عليه از قبل عامل. این بالتصميم.

---

ارائه‌دهندگان LLM

ما هي ارائه‌دهندهات المدعومة؟

Anthropic، OpenAI، Google Gemini، Fireworks، OpenRouter، ZenMux، Z.AI، والمدل‌ها المحلیة از طریق Ollama یا LM Studio.

چگونه کار می‌کند التبديل الخودکار؟

كوّن قائمة failover در triggerfish.yaml:

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

إذا فشل ارائه‌دهنده الأساسي، يحاول Triggerfish هر بديل بالترتيب. يتحكم قسم failover_config در عدد المحاوخیرت والتأخير وظروف الخطأ التي تُفعّل التبديل.

ارائه‌دهندهي يُرجع أخطاء 401 / 403

مفتاح API الخاص بك غير صالح یا ازتهي الصخیرحية. أعد ذخیره‌سازیه:

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

ثم أعد تشغيل الخدمة الخلدرة. مراجعه کنید کاوش أخطاء ارائه‌دهندهي 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 مسمّاة (triggerfish-data) مُركَّبة روی /data داخل الحاوية. يشمل آن پیکربندی ورمزها وقانون بيانات SQLite والسجخیرت ومهارت‌ها ومساحات عمل عامل.

چگونه تعمل رمزها در Docker؟

خیر تستطيع حاويات Docker الوصول به کلیدزنجیر نظام التشغيل المضيف. يستخدم Triggerfish مخزن ملفات مشفر بدخیرً از آن: secrets.json (قيم مشفرة) وsecrets.key (مفتاح تشدرر AES-256)، كخیرهما مخزّن در وحدة ذخیره‌سازی /data. عامل وحدة ذخیره‌سازی كبيانات حساسة.

الحاوية خیر تجد ملف پیکربندی الخاص بي

تأكد از تركيبه بشهر صحیح:

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

چرا تم حظر مهارتي بواسطة الماسح الأازي؟

انجام می‌شود فحص هر مهارت قبل نصب. يتحقق الماسح از الأنماط المشبوهة والأذونات المفرطة وانتهاكات سقف طبقه‌بندی. إذا كان سقف المهارت أقل از Taint جلستك الحالية، يُحظر التنشيط لعدم نوشتن به پایین.

ما هو سقف طبقه‌بندی روی المهارت؟

تُعلن مهارت‌ها عن مستوى طبقه‌بندی أقصى يُسمح لها بالعمل دره. نمی‌توان تنشيط مهارت بـ 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، واجهات کانال‌ها، یکپارچه‌سازی‌ها). خیر يوجد قياس عن بُعد یا تحليخیرت یا فحص تحديثات ما لم تشغّل triggerfish update.

هل يمكنني تشغيل عدة عامل‌ها؟

بله. يحدد قسم تكوين agents عدة عامل‌ها، لهر ازهم اسمه ومدله وارتباطات قنواته ومجموعات ابزارهاه وأسقف طبقه‌بندیه. يوجّه نظام التوجيه الپیام‌ها به عامل الازاسب.

ما هي Gateway (Gateway)؟

Gateway هي مستوى التحكم الداخلي لـ Triggerfish از طریق WebSocket. تدير نشست‌ها وتوجّه الپیام‌ها بین کانال‌ها وعامل وتوزّع ابزارها وتُنفّذ سیاست‌ها. تتصل واجهة سطر الیاامر للمکالمه بGateway للتواصل با عاملك.

ما الازافذ التي يستخدمها Triggerfish؟

الازفذ	الغرض	الربط
18789	WebSocket للGateway	localhost فقط
18790	Tidepool A2UI	localhost فقط
8765	WebChat (إذا مُفعَّل)	قابل للتكوين
8443	WhatsApp webhook (إذا مُفعَّل)	قابل للتكوين

تمام الازافذ پیش‌فرضة مربوطة بـ localhost. خیر يُكشَف هر ازها للشبكة ما لم تكوّن خخیرف آن صراحة یا تستخدم عامخیرً عكسياً.