الأسئلة الشائعة

التثبيت

ما هي متطلبات النظام؟

يعمل 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. هذه هي قاعدة "عدم الكتابة للأسفل" ولا يمكن تجاوزها.

ماذا يعني "تلوث الجلسة"؟

تبدأ كل جلسة عند PUBLIC. عندما يصل الوكيل إلى بيانات مصنّفة (يقرأ ملفاً سرياً، يستعلم من قاعدة بيانات مقيّدة)، يتصاعد تلوث الجلسة ليطابق. التلوث يرتفع فقط ولا ينخفض أبداً. لا يمكن للجلسة الملوثة بـ CONFIDENTIAL إرسال مخرجاتها إلى قناة PUBLIC.

لماذا أحصل على أخطاء "write-down blocked"؟

تم تلويث جلستك إلى مستوى تصنيف أعلى من الوجهة. على سبيل المثال، إذا وصلت إلى بيانات CONFIDENTIAL ثم حاولت إرسال النتائج إلى قناة WebChat عامة PUBLIC، يحظر محرك السياسات ذلك.

هذا يعمل كما هو مقصود. لحل المشكلة، إما:

• ابدأ جلسة جديدة (محادثة جديدة)
• استخدم قناة مصنّفة عند أو فوق مستوى تلوث جلستك

هل يمكنني تعطيل تطبيق التصنيف؟

لا. نظام التصنيف هو ثابت أمني أساسي. يعمل ككود حتمي أسفل طبقة 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

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

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

ما هو سقف التصنيف على المهارة؟

تُعلن المهارات عن مستوى تصنيف أقصى يُسمح لها بالعمل فيه. لا يمكن تنشيط مهارة بـ 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)؟

البوابة هي مستوى التحكم الداخلي لـ Triggerfish عبر WebSocket. تدير الجلسات وتوجّه الرسائل بين القنوات والوكيل وتوزّع الأدوات وتُنفّذ السياسات. تتصل واجهة سطر الأوامر للمحادثة بالبوابة للتواصل مع وكيلك.

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

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

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