دورة حياة تراكب الصوت (macOS)

الجمهور: المساهمون في تطبيق macOS. الهدف: الحفاظ على سلوك متوقع لتراكب الصوت عند تداخل كلمة التنبيه مع الضغط للتحدث.

السلوك

• إذا كان التراكب ظاهرًا بالفعل بسبب كلمة التنبيه وضغط المستخدم مفتاح الاختصار، تعتمد جلسة مفتاح الاختصار النص الموجود بدلًا من إعادة تعيينه. يظل التراكب ظاهرًا طوال فترة الضغط على مفتاح الاختصار. عند تحريره: يُرسل النص إذا لم يكن فارغًا بعد إزالة المسافات الزائدة، وإلا يُغلق التراكب.
• تظل كلمة التنبيه وحدها ترسل تلقائيًا عند الصمت؛ بينما يرسل الضغط للتحدث فور تحرير المفتاح.

التنفيذ

• يُعد VoiceSessionCoordinator ‏(apps/macos/Sources/OpenClaw/VoiceSessionCoordinator.swift) المالك الوحيد لجلسة الصوت النشطة. وهو كائن مفرد من النوع @MainActor @Observable، وليس actor. واجهة API:‏ startSession، وupdatePartial، وfinalize، وsendNow، وdismiss، وupdateLevel، وsnapshot. تحمل كل جلسة رمز UUID؛ ويجري تجاهل الاستدعاءات ذات الرمز القديم أو غير المتطابق.
• يعرض VoiceWakeOverlayController ‏(VoiceWakeOverlayController+Session.swift) التراكب ويمرر إجراءات المستخدم (requestSend، وdismiss) مجددًا عبر المنسق باستخدام رمز الجلسة. ولا يمتلك حالة الجلسة نفسها أبدًا.
• يعتمد الضغط للتحدث (VoicePushToTalk.begin()) أي نص ظاهر في التراكب بوصفه adoptedPrefix (عبر VoiceSessionCoordinator.shared.snapshot())، بحيث يؤدي الضغط على مفتاح الاختصار أثناء ظهور تراكب التنبيه إلى الاحتفاظ بالنص وإلحاق الكلام الجديد به. وعند تحرير المفتاح، ينتظر مدة تصل إلى 1.5 ثانية للحصول على نص نهائي قبل الرجوع إلى النص الحالي.
• عند dismiss، يستدعي التراكب VoiceSessionCoordinator.overlayDidDismiss، ما يؤدي إلى تشغيل VoiceWakeRuntime.refresh(state:) لكي تستأنف جميع حالات الإغلاق اليدوي بزر X، والإغلاق عند فراغ النص، والإغلاق بعد الإرسال الاستماع إلى كلمة التنبيه.
• مسار إرسال موحد: إذا كان النص فارغًا بعد إزالة المسافات الزائدة، يُغلق التراكب؛ وإلا يشغّل sendNow نغمة الإرسال مرة واحدة، ويمرر النص عبر VoiceWakeForwarder، ثم يغلق التراكب.

التسجيل

النظام الفرعي للصوت هو ai.openclaw؛ ويسجل كل مكوّن ضمن فئته الخاصة:

قائمة التحقق لتصحيح الأخطاء

• اعرض سجلات البث أثناء إعادة إنتاج مشكلة بقاء التراكب عالقًا:

  sudo log stream --predicate 'subsystem == "ai.openclaw" AND category CONTAINS "voicewake"' --level info --style compact

• تحقق من وجود رمز جلسة نشط واحد فقط؛ إذ يتجاهل المنسق عمليات رد النداء القديمة.

• تأكد من أن تحرير زر الضغط للتحدث يستدعي دائمًا end() باستخدام الرمز النشط؛ وإذا كان النص فارغًا، فتوقّع إغلاق التراكب دون نغمة أو إرسال.

ذو صلة

• تطبيق macOS
• التنبيه الصوتي (macOS)
• وضع التحدث