قاعدة المعرفة: المشكلات المعروفة

المشكلات المعروفة الحالية وحلولها البديلة. تُحدَّث هذه الصفحة كلما اكتُشفت مشكلات وحُلّت.

---

Email: لا يوجد إعادة اتصال IMAP

الحالة: مفتوح

يستطلع محول قناة البريد الإلكتروني الرسائل الجديدة كل 30 ثانية عبر IMAP. إذا انقطع اتصال IMAP (انقطاع شبكة، إعادة تشغيل خادم، مهلة خمول)، تفشل حلقة الاستطلاع بصمت ولا تحاول إعادة الاتصال.

الأعراض:

• قناة البريد الإلكتروني تتوقف عن استقبال رسائل جديدة
• يظهر IMAP unseen email poll failed في السجلات
• لا يوجد استرداد تلقائي

الحل البديل: أعد تشغيل الخدمة الخلفية:

triggerfish stop && triggerfish start

السبب الجذري: حلقة استطلاع IMAP لا تحتوي على منطق إعادة اتصال. يستمر setInterval في العمل لكن كل استطلاع يفشل لأن الاتصال ميت.

---

Slack/Discord SDK: تسريب عمليات غير متزامنة

الحالة: مشكلة معروفة في المصدر الأصلي

يُسرّب SDK الخاص بـ Slack (@slack/bolt) وDiscord (discord.js) عمليات غير متزامنة عند الاستيراد. يؤثر هذا على الاختبارات (يتطلب sanitizeOps: false) لكنه لا يؤثر على الاستخدام الإنتاجي.

الأعراض:

• فشل الاختبارات بـ "leaking async ops" عند اختبار محولات القنوات
• لا يوجد تأثير إنتاجي

الحل البديل: ملفات الاختبار التي تستورد محولات Slack أو Discord يجب أن تضبط:

Deno.test({
  name: "test name",
  sanitizeOps: false,
  sanitizeResources: false,
  fn: async () => { ... }
});

---

Slack: اقتطاع الرسائل بدلاً من التقسيم

الحالة: بالتصميم

تُقتطع رسائل Slack عند 40,000 حرف بدلاً من تقسيمها إلى رسائل متعددة (كما يفعل Telegram وDiscord). استجابات الوكيل الطويلة جداً تفقد محتواها في النهاية.

الحل البديل: اطلب من الوكيل إنتاج استجابات أقصر، أو استخدم قناة مختلفة للمهام التي تُنتج مخرجات كبيرة.

---

WhatsApp: جميع المستخدمين يُعامَلون كمالك عند فقدان ownerPhone

الحالة: بالتصميم (مع تحذير)

إذا لم يُكوَّن حقل ownerPhone لقناة WhatsApp، يُعامَل جميع مرسلي الرسائل كمالك، مما يمنحهم وصولاً كاملاً للأدوات.

الأعراض:

• WhatsApp ownerPhone not configured, defaulting to non-owner (تحذير السجل مُضلّل في الواقع؛ السلوك يمنح وصول المالك)
• أي مستخدم WhatsApp يمكنه الوصول لجميع الأدوات

الحل البديل: اضبط ownerPhone دائماً:

channels:
  whatsapp:
    ownerPhone: "+1234567890"

---

systemd: لا يُحدَّث PATH بعد تثبيت الأدوات

الحالة: بالتصميم

يلتقط ملف وحدة systemd PATH لـ shell الخاص بك وقت تثبيت الخدمة الخلفية. إذا ثبّتت أدوات جديدة (ملفات تنفيذ خادم MCP، npx، إلخ) بعد تثبيت الخدمة الخلفية، لن تجدها الخدمة الخلفية.

الأعراض:

• فشل إنشاء خوادم MCP
• الملفات التنفيذية للأدوات "غير موجودة" رغم أنها تعمل في طرفيتك

الحل البديل: أعد تثبيت الخدمة الخلفية لتحديث PATH الملتقط:

triggerfish stop
triggerfish dive --install-daemon

ينطبق هذا على launchd (macOS) أيضاً.

---

المتصفح: قيود CDP في Flatpak Chrome

الحالة: قيد منصة

بعض بناءات Flatpak لـ Chrome أو Chromium تقيّد علامة --remote-debugging-port، مما يمنع Triggerfish من الاتصال عبر Chrome DevTools Protocol.

الأعراض:

• CDP endpoint on port X not ready after Yms
• المتصفح يُشغَّل لكن Triggerfish لا يستطيع التحكم فيه

الحل البديل: ثبّت Chrome أو Chromium كحزمة أصلية بدلاً من Flatpak:

# Fedora
sudo dnf install chromium

# Ubuntu/Debian
sudo apt install chromium-browser

---

Docker: أذونات وحدات التخزين مع Podman

الحالة: خاص بالمنصة

عند استخدام Podman مع حاويات بدون صلاحيات جذر، قد يمنع تعيين UID الحاوية (التي تعمل كـ UID 65534) من الكتابة في وحدة تخزين البيانات.

الأعراض:

• أخطاء Permission denied عند بدء التشغيل
• لا يمكن إنشاء ملف التكوين أو قاعدة البيانات أو السجلات

الحل البديل: استخدم علامة تركيب وحدة التخزين :Z لإعادة تسمية SELinux، وتأكد من أن مجلد وحدة التخزين قابل للكتابة:

podman run -v triggerfish-data:/data:Z ...

أو أنشئ وحدة التخزين بالملكية الصحيحة. أولاً، اعثر على مسار تركيب وحدة التخزين، ثم غيّر ملكيته:

podman volume create triggerfish-data
podman volume inspect triggerfish-data   # لاحظ مسار "Mountpoint"
podman unshare chown 65534:65534 /path/from/above

---

Windows: .NET Framework csc.exe غير موجود

الحالة: خاص بالمنصة

يُجمّع مُثبّت Windows مُغلّف خدمة C# وقت التثبيت. إذا لم يُعثر على csc.exe (.NET Framework مفقود أو مسار تثبيت غير قياسي)، يفشل تثبيت الخدمة.

الأعراض:

• يكتمل المُثبّت لكن الخدمة غير مُسجَّلة
• triggerfish status يُظهر أن الخدمة غير موجودة

الحل البديل: ثبّت .NET Framework 4.x، أو شغّل Triggerfish في وضع المقدمة:

triggerfish run

أبقِ الطرفية مفتوحة. تعمل الخدمة الخلفية حتى تغلقها.

---

CalDAV: تعارضات ETag مع عملاء متزامنين

الحالة: بالتصميم (مواصفة CalDAV)

عند تحديث أو حذف أحداث التقويم، يستخدم CalDAV علامات ETag للتحكم في التزامن المتفائل. إذا عدّل عميل آخر (تطبيق هاتف، واجهة ويب) الحدث بين قراءتك وكتابتك، تفشل العملية:

ETag mismatch — the event was modified by another client. Fetch the latest version and retry.

الحل البديل: يجب أن يُعيد الوكيل المحاولة تلقائياً بجلب أحدث إصدار من الحدث. إذا لم يفعل، اطلب منه "جلب أحدث إصدار من الحدث والمحاولة مرة أخرى."

---

البديل في الذاكرة: فقدان الأسرار عند إعادة التشغيل

الحالة: بالتصميم

عند استخدام TRIGGERFISH_SECRETS_MEMORY_FALLBACK=true، تُخزَّن الأسرار في الذاكرة فقط وتُفقد عند إعادة تشغيل الخدمة الخلفية. هذا الوضع مخصص فقط للاختبار.

الأعراض:

• الأسرار تعمل حتى إعادة تشغيل الخدمة الخلفية
• بعد إعادة التشغيل: أخطاء Secret not found

الحل البديل: أعدّ واجهة أسرار خلفية مناسبة. على Linux بدون واجهة رسومية، ثبّت gnome-keyring:

sudo apt install gnome-keyring libsecret-tools
eval $(gnome-keyring-daemon --start --components=secrets)

---

Google OAuth: لا يُصدَر رمز التحديث عند إعادة التفويض

الحالة: سلوك Google API

يُصدر Google رمز التحديث فقط عند أول تفويض. إذا سبق أن أذنت للتطبيق وأعدت تشغيل triggerfish connect google، تحصل على رمز وصول لكن بدون رمز تحديث.

الأعراض:

• Google API يعمل مبدئياً لكنه يفشل بعد انتهاء صلاحية رمز الوصول (ساعة واحدة)
• خطأ No refresh token

الحل البديل: ألغِ وصول التطبيق أولاً، ثم أعد التفويض:

1. اذهب إلى أذونات حساب Google
2. اعثر على Triggerfish وانقر "إزالة الوصول"
3. شغّل triggerfish connect google مرة أخرى
4. سيُصدر Google الآن رمز تحديث جديد

---

الإبلاغ عن مشكلات جديدة

إذا واجهت مشكلة غير مدرجة هنا، تحقق من صفحة GitHub Issues. إذا لم تكن مُبلَّغة بالفعل، قدّم بلاغاً جديداً باتباع دليل تقديم البلاغات.