---
read_when:
    - ضبط سلوك التراكب الصوتي
summary: دورة حياة تراكب الصوت عند تداخل كلمة التنبيه مع الضغط للتحدث
title: تراكب صوتي
x-i18n:
    generated_at: "2026-05-06T08:05:00Z"
    model: gpt-5.5
    provider: openai
    source_hash: 5b30f50512e557bd5a50f0e4e8b7955a847b3b554694347d56638581fcda9514
    source_path: platforms/mac/voice-overlay.md
    workflow: 16
---

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

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

## النية الحالية

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

## تم التنفيذ (9 ديسمبر 2025)

- تحمل جلسات التراكب الآن رمزًا مميزًا لكل التقاط (كلمة تنبيه أو اضغط للتحدث). يتم إسقاط تحديثات الجزئي/النهائي/الإرسال/الإخفاء/المستوى عندما لا يطابق الرمز المميز، مما يتجنب ردود النداء القديمة.
- يتبنى اضغط للتحدث أي نص تراكب ظاهر كبادئة (لذلك فإن الضغط على مفتاح الاختصار أثناء ظهور تراكب التنبيه يُبقي النص ويضيف الكلام الجديد). ينتظر حتى 1.5 ثانية للحصول على نسخة نهائية قبل الرجوع إلى النص الحالي.
- يتم إصدار سجلات الرنين/التراكب عند `info` في الفئات `voicewake.overlay` و`voicewake.ptt` و`voicewake.chime` (بدء الجلسة، جزئي، نهائي، إرسال، إخفاء، سبب الرنين).

## الخطوات التالية

1. **`VoiceSessionCoordinator` (ممثل)**
   - يمتلك `VoiceSession` واحدة بالضبط في كل مرة.
   - API (مستند إلى الرمز المميز): `beginWakeCapture` و`beginPushToTalk` و`updatePartial` و`endCapture` و`cancel` و`applyCooldown`.
   - يسقط ردود النداء التي تحمل رموزًا مميزة قديمة (يمنع أدوات التعرف القديمة من إعادة فتح التراكب).
2. **`VoiceSession` (نموذج)**
   - الحقول: `token` و`source` (`wakeWord|pushToTalk`) والنص المثبت/المتقلب، وأعلام الرنين، والمؤقتات (الإرسال التلقائي، الخمول)، و`overlayMode` (`display|editing|sending`) وموعد انتهاء فترة التهدئة.
3. **ربط التراكب**
   - يعكس `VoiceSessionPublisher` (`ObservableObject`) الجلسة النشطة إلى SwiftUI.
   - يعرض `VoiceWakeOverlayView` عبر الناشر فقط؛ ولا يغيّر الكائنات المفردة العامة مباشرة أبدًا.
   - تستدعي إجراءات مستخدم التراكب (`sendNow` و`dismiss` و`edit`) المنسق مع الرمز المميز للجلسة.
4. **مسار إرسال موحد**
   - عند `endCapture`: إذا كان النص بعد إزالة المسافات الطرفية فارغًا ← إخفاء؛ وإلا `performSend(session:)` (يشغل رنين الإرسال مرة واحدة، ويمرر، ثم يخفي).
   - اضغط للتحدث: بلا تأخير؛ كلمة التنبيه: تأخير اختياري للإرسال التلقائي.
   - طبّق فترة تهدئة قصيرة على وقت تشغيل التنبيه بعد انتهاء اضغط للتحدث حتى لا تعيد كلمة التنبيه التشغيل فورًا.
5. **التسجيل**
   - يصدر المنسق سجلات `.info` في النظام الفرعي `ai.openclaw`، ضمن الفئتين `voicewake.overlay` و`voicewake.chime`.
   - الأحداث الرئيسية: `session_started` و`adopted_by_push_to_talk` و`partial` و`finalized` و`send` و`dismiss` و`cancel` و`cooldown`.

## قائمة التحقق للتصحيح

- دفق السجلات أثناء إعادة إنتاج تراكب عالق:

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

- تحقق من وجود رمز مميز واحد فقط لجلسة نشطة؛ يجب أن يسقط المنسق ردود النداء القديمة.
- تأكد من أن إفلات اضغط للتحدث يستدعي دائمًا `endCapture` مع الرمز المميز النشط؛ إذا كان النص فارغًا، فتوقع `dismiss` بدون رنين أو إرسال.

## خطوات الترحيل (مقترحة)

1. أضف `VoiceSessionCoordinator` و`VoiceSession` و`VoiceSessionPublisher`.
2. أعد هيكلة `VoiceWakeRuntime` لإنشاء الجلسات/تحديثها/إنهائها بدلًا من لمس `VoiceWakeOverlayController` مباشرة.
3. أعد هيكلة `VoicePushToTalk` لتبني الجلسات الموجودة واستدعاء `endCapture` عند الإفلات؛ وطبّق فترة تهدئة وقت التشغيل.
4. اربط `VoiceWakeOverlayController` بالناشر؛ وأزل الاستدعاءات المباشرة من وقت التشغيل/اضغط للتحدث.
5. أضف اختبارات تكامل لتبني الجلسات، وفترة التهدئة، وإخفاء النص الفارغ.

## ذو صلة

- [تطبيق macOS](/ar/platforms/macos)
- [التنبيه الصوتي (macOS)](/ar/platforms/mac/voicewake)
- [وضع التحدث](/ar/nodes/talk)