الرسائل والتسليم

قائمة انتظار الأوامر

نقوم بتسلسل تشغيلات الرد التلقائي الواردة (جميع القنوات) من خلال قائمة انتظار صغيرة داخلية لمنع تصادم تشغيلات وكلاء متعددة، مع السماح بالتوازي الآمن عبر الجلسات.

لماذا

  • يمكن أن تكون تشغيلات الرد التلقائي مكلفة (مكالمات LLM) وقد تتصادم عند وصول رسائل واردة متعددة في وقت متقارب.
  • التسلسل يتجنب التنافس على الموارد المشتركة (ملفات الجلسة، السجلات، CLI stdin) ويقلل من فرص تجاوز حدود المعدل (rate limits) من المصادر العلوية.

كيف تعمل

  • تقوم قائمة انتظار FIFO الواعية بالمسارات بتفريغ كل مسار بسقف تزامن قابل للتكوين (الافتراضي 1 للمسارات غير المكونة؛ المسار الرئيسي main يبدأ بـ 4، والوكيل الفرعي subagent بـ 8).
  • تقوم runEmbeddedPiAgent بإدراج الأوامر في قائمة الانتظار حسب مفتاح الجلسة (مسار session:<key>) لضمان تشغيل واحد نشط فقط لكل جلسة.
  • يتم بعد ذلك إدراج كل تشغيل جلسة في مسار عام (main افتراضيًا) بحيث يكون التوازي العام محدودًا بـ agents.defaults.maxConcurrent.
  • عند تمكين التسجيل التفصيلي، تصدر عمليات التشغيل المدرجة في قائمة الانتظار إشعارًا قصيرًا إذا انتظرت أكثر من ~2 ثانية قبل البدء.
  • لا تزال مؤشرات الكتابة تظهر فورًا عند الإدراج في قائمة الانتظار (عندما تدعمها القناة) بحيث تظل تجربة المستخدم كما هي أثناء انتظار الدور.

أوضاع قائمة الانتظار (لكل قناة)

يمكن للرسائل الواردة توجيه التشغيل الحالي، أو الانتظار لدور متابعة، أو القيام بكليهما:

  • steer: حقن فوري في التشغيل الحالي (يلغي استدعاءات الأدوات المعلقة بعد حد الأداة التالي). إذا لم يكن هناك تدفق (streaming)، يتراجع إلى وضع المتابعة (followup).
  • followup: إدراج في قائمة الانتظار لدور الوكيل التالي بعد انتهاء التشغيل الحالي.
  • collect: دمج جميع الرسائل المدرجة في قائمة الانتظار في دور متابعة واحد (الافتراضي). إذا كانت الرسائل تستهدف قنوات/خيوطًا مختلفة، يتم تفريغها بشكل فردي للحفاظ على التوجيه.
  • steer-backlog (المعروف أيضًا بـ steer+backlog): توجيه فوري و الاحتفاظ بالرسالة لدور متابعة.
  • interrupt (قديم): إيقاف التشغيل النشط لتلك الجلسة، ثم تشغيل أحدث رسالة.
  • queue (اسم قديم): نفس steer.

يعني steer-backlog أنه يمكنك الحصول على رد متابعة بعد التشغيل الموجه، لذا قد تبدو واجهات التدفق (streaming surfaces) وكأنها مكررة. يُفضل استخدام collect/steer إذا كنت تريد ردًا واحدًا لكل رسالة واردة. أرسل /queue collect كأمر منفرد (لكل جلسة) أو عيّن messages.queue.byChannel.discord: "collect". القيم الافتراضية (عند عدم التحديد في التكوين):

  • جميع الواجهات → collect

قم بالتكوين عالميًا أو لكل قناة عبر messages.queue:

{
  messages: {
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
      byChannel: { discord: "collect" },
    },
  },
}

خيارات قائمة الانتظار

تنطبق الخيارات على followup، وcollect، وsteer-backlog (وعلى steer عندما يتراجع إلى وضع المتابعة):

  • debounceMs: الانتظار لهدوء قبل بدء دور متابعة (يمنع "استمر، استمر").
  • cap: الحد الأقصى للرسائل المدرجة في قائمة الانتظار لكل جلسة.
  • drop: سياسة الفائض (old، new، summarize).

يحتفظ summarize بقائمة مختصرة من النقاط للرسائل التي تم تجاهلها ويحقنها كموجه متابعة اصطناعي. القيم الافتراضية: debounceMs: 1000، cap: 20، drop: summarize.

التجاوزات لكل جلسة

  • أرسل /queue <mode> كأمر منفرد لتخزين الوضع للجلسة الحالية.
  • يمكن دمج الخيارات: /queue collect debounce:2s cap:25 drop:summarize
  • /queue default أو /queue reset يزيل التجاوز المخصص للجلسة.

النطاق والضمانات

  • ينطبق على تشغيلات وكيل الرد التلقائي عبر جميع القنوات الواردة التي تستخدم خط أنابيب رد البوابة (WhatsApp web، Telegram، Slack، Discord، Signal، iMessage، الدردشة عبر الويب، إلخ.).
  • المسار الافتراضي (main) هو على مستوى العملية للرسائل الواردة + نبضات القلب الرئيسية؛ عيّن agents.defaults.maxConcurrent للسماح بتشغيل جلسات متعددة بالتوازي.
  • قد توجد مسارات إضافية (مثل cron، subagent) بحيث يمكن للمهام الخلفية التشغيل بالتوازي دون حجب الردود الواردة.
  • تضمن المسارات لكل جلسة أن يلمس تشغيل وكيل واحد فقط جلسة معينة في كل مرة.
  • لا توجد تبعيات خارجية أو خيوط عمل خلفية؛ TypeScript خالص + وعود (promises).

استكشاف الأخطاء وإصلاحها

  • إذا بدا أن الأوامر عالقة، فعِّل السجلات التفصيلية وابحث عن سطور "queued for …ms" لتأكيد تفريغ قائمة الانتظار.
  • إذا كنت بحاجة إلى معرفة عمق قائمة الانتظار، فعِّل السجلات التفصيلية وراقب سطور توقيت قائمة الانتظار.

سياسة إعادة المحاولة