---
read_when:
    - تريد أن تلاحظ الوكلاء عندما يغيّر البشر أو وكلاء آخرون جلسةً من دون علمهم
    - أنت تصحّح أخطاء إشعارات تغيّر الحالة أو مؤشرات المراقبة أو تغييرات `changesSince` في `session_status`
    - تريد فهم كيفية بقاء الوكلاء الآباء متزامنين مع الجلسات الفرعية
sidebarTitle: Session state awareness
summary: 'سجل إشارات حالة الجلسة الدائمة: إصدارات الحالة، والمراقبون، وإشعارات الحالة القديمة، والتسوية'
title: الوعي بحالة الجلسة
x-i18n:
    generated_at: "2026-07-16T14:00:11Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: bb4126a0802e1ca4418f225c792490493a78886089b81c3b4567f72090ce34f4
    source_path: concepts/session-state.md
    workflow: 16
---

عندما تعمل عدة جلسات على المشكلة نفسها — مدير يفوّض المهام إلى جلسات فرعية، أو إنسان ينتقل مباشرةً إلى جلسة عامل، أو وكيلان ينسّقان عبر [`sessions_send`](/ar/concepts/session-tool) — تبني كل جلسة افتراضات عن الجلسات الأخرى. تصبح تلك الافتراضات قديمة بمجرد تدخل طرف آخر. الوعي بحالة الجلسة هو الآلية التي تكتشف التدخل، وتُخطر الجلسة المتأثرة مرة واحدة، وتمنحها وسيلة منخفضة التكلفة للاطلاع على المستجدات قبل التصرف.

تعمل ثلاثة مكونات معًا:

1. يسجّل **سجل إشارات دائم** تغييرات محددة في الحالة لكل جلسة.
2. تحتفظ **المراقِبات** بمؤشرات لكل هدف وتتلقى إشعارًا واحدًا مدمجًا بتقادم الحالة.
3. تجلب **المزامنة** الفرق الدقيق عبر `session_status` باستخدام `changesSince`.

## سجل الإشارات

يضيف OpenClaw حدثًا ذا نوع محدد إلى قاعدة بيانات الحالة المشتركة (`session_state_events`) عندما تتغير جلسة مراقَبة تغييرًا جوهريًا. تحمل الأحداث بيانات وصفية وملخصًا من سطر واحد — ولا تحمل محتوى الرسائل أبدًا.

| النوع                   | وقت التسجيل                                            | هل يُخطر المراقِبات؟ |
| ---------------------- | -------------------------------------------------------- | ----------------- |
| `human_direct_message` | عندما يرسل إنسان دورًا مباشرةً إلى جلسة مراقَبة       | نعم               |
| `upstream_missing`     | عندما يختفي المصدر الرئيسي لجلسة متبنّاة          | نعم               |
| `goal_changed`         | عندما تُنشأ حالة هدف الجلسة أو تُحدّث أو تُمسح | نعم               |
| `child_spawned`        | عندما تُنشأ جلسة وكيل فرعي أو جلسة فرعية لـ ACP              | لا (يهيئ المؤشر) |
| `run_completed`        | عندما ينتهي تشغيل جلسة فرعية بنجاح                            | لا (تسجيل فقط)     |
| `run_failed`           | عندما يفشل تشغيل جلسة فرعية أو تنتهي مهلته أو يُلغى            | لا (تسجيل فقط)     |
| `compacted`            | عندما يُضغط سجل الجلسة                       | لا (تسجيل فقط)     |
| `adopted`              | عندما تُتبنى جلسة من الفهرس في OpenClaw               | لا (تسجيل فقط)     |

يحدد كل حدث الطرف الذي نفّذه (`human` أو `agent` أو `system`). تُسجّل عمليات الجلسات الفرعية الملغاة والمنتهية مهلتها كحالات فشل، مع الاحتفاظ بالنتيجة الدقيقة (`cancelled` أو `timeout` أو `error`) في حمولة الحدث.

**إصدار الحالة** للجلسة هو ببساطة أعلى رقم تسلسلي في سجلها، ويُتتبع في رأس دائم خاص بكل جلسة يبقى محفوظًا بعد التنقية. تتضمن صفوف `sessions_list` القيمة `stateVersion` عندما تكون الجلسة قد سجلت تغييرات؛ ويُبلغ عنها `session_status` دائمًا.

توجد الأنواع المخصصة للتسجيل فقط من أجل سجل المزامنة، لا الإشعارات: يظل التسليم المعتاد لإكمال تشغيل الجلسات الفرعية ضمن مسؤولية [إعلانات الوكلاء الفرعيين](/ar/tools/subagents)، ولا يكرره سجل الإشارات أبدًا.

## المراقِبات

المراقِب هو جلسة تحتفظ بمؤشر (`session_watch_cursors`) على هدف. تأتي المؤشرات من مصدرين:

- **ضمنية (حواف الإنشاء).** عندما تنشئ جلسة وكيلًا فرعيًا أو جلسة فرعية لـ ACP، يُهيأ مؤشر الجلسة الأصل تلقائيًا عند إصدار إنشاء الجلسة الفرعية. لا تشترك الجلسات الأصل يدويًا أبدًا.
- **صريحة (`sessions_send watch: true`).** يمكن لأي منسّق مراقبة هدف لم ينشئه: مرّر `watch: true` إلى `sessions_send`، وبعد إرسال الرسالة بنجاح يُسجّل المرسل كمراقِب للجلسة التي استلمت الرسالة فعليًا. يبدأ التسجيل عند إصدار الحالة الحالي للهدف — ولا ينتج السجل السابق إشعارات أبدًا. تعرض نتيجة الأداة `watched: true|false` عند ضبط المعامل.

يجب أن تكون هوية المراقِب مفتاح جلسة مؤهلًا باسم الوكيل. تحت `session.scope="global"`، يكون المفتاح المشترك `global` ملتبسًا بين الوكلاء، لذا تحصل هذه الجلسات على السجل الدائم و`changesSince`، لكن دون إشعارات استباقية.

تنظف المراقبات نفسها تلقائيًا: تنتهي صلاحية صفوف المؤشرات وفق مدة الاحتفاظ بسجل الإشارات، وتُزال عند إعادة ضبط جلسة المراقِب، وتُحذف مع حذف أي من الجلستين. لا يوجد إجراء لإلغاء المراقبة في الإصدار v1.

تُفحص الجلسات المراقَبة والمتبنّاة من فهرس الجلسات وفق وتيرة ثابتة لرصد النشاط البشري المباشر في المصدر الرئيسي. يدخل النشاط المكتشف في سجل الإشارات ومسار المراقِبات نفسيهما، مثل سائر الأدوار البشرية المباشرة.

إذا حُذف المصدر الرئيسي لجلسة متبنّاة خارجيًا، فإن ثلاث عمليات تحقق متتالية لا تجده فيها (نحو ثلاث دورات للمراقبة) تنتج إشارة `upstream_missing` واحدة لمراقِبيها وتزيل رابط المصدر الرئيسي. تؤدي متابعة جلسة الفهرس مرة أخرى إلى إنشاء رابط جديد.

## الإشعارات: واحد، لا عدة إشعارات

عندما يصل حدث يستوجب الإخطار ويكون مؤشر المراقِب متأخرًا، يتلقى المراقِب إشعارًا واحدًا من النظام في دوره التالي:

```
تغيرت الجلسة "agent:main:subagent:child" (بفعل طرف آخر). زامِن قبل التصرف: session_status sessionKey "agent:main:subagent:child" changesSince 12.
```

كما تُوقظ مراقِبات الجلسات الرئيسية فورًا عبر تنبيه Heartbeat؛ أما مراقِبات الوكلاء الفرعيين المتداخلة فتتلقى الإشعار في دورها التالي.

صُمم البروتوكول عمدًا لمنع الإغراق:

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

## المزامنة

يخبر الإشعار المراقِب بما يجب فعله تحديدًا. يعيد `session_status` مع `changesSince: <version>` الأحداث ذات الأنواع المحددة بعد ذلك الإصدار (حتى 200)، دون تقديم أي مؤشرات:

```json
{
  "stateVersion": 19,
  "stateChanges": {
    "events": [
      {
        "sequence": 14,
        "kind": "human_direct_message",
        "actorType": "human",
        "summary": "رسالة بشرية عبر telegram"
      },
      { "sequence": 19, "kind": "goal_changed", "actorType": "human", "summary": "تم تحديث الهدف" }
    ],
    "historyGap": false
  }
}
```

تعني `historyGap: true` أن الإصدار المطلوب يسبق السجل المحتفظ به — لذا حدّث حالة الجلسة كاملةً (`sessions_history` و`session_status`) بدلًا من التعامل مع الاستجابة على أنها فرق دقيق. إشارة الفجوة دقيقة: فهي تأتي من علامة مائية منقّاة خاصة بكل جلسة، ولا تُستنتج من حساب التسلسلات.

## التخزين والحدود

يُحفظ السجل في قاعدة بيانات الحالة المشتركة، بحد أقصى قدره 30 يومًا و50,000 صف؛ وتظل رؤوس الجلسات رتيبة التصاعد بعد التنقية. التسجيل قائم على بذل أفضل جهد — يُسجّل فشل الإضافة ولا يؤدي أبدًا إلى إفشال الدور الأصلي — لذا فإن `stateVersion` هو رأس سجل إشارات، وليس إصدارًا لالتقاط بيانات التغيير ضمن معاملة.

الحدود الحالية:

- يفترض تسليم الإشعارات أن عملية Gateway واحدة تملك قاعدة بيانات الحالة المشتركة. تشترك بوابات Gateway المتعددة في السجل الدائم و`changesSince`، لكن الإصدار v1 لا يدفع الإشعارات بين العمليات.
- تغطي أحداث Compaction الجهات المالكة للضغط في بيئة التشغيل المضمّنة؛ أما الضغط الذي يقتصر على الحاضنة الأصلية فلا يُسجّل بالكامل.
- تنتج عمليات الجلسات الفرعية لـ ACP حاليًا تفاصيل حمولة نتيجة الإلغاء؛ بينما تظهر عمليات إلغاء الوكلاء الفرعيين الأصلية كحالات فشل عامة.
- تقارن آلية اكتشاف الصدى الذاتي للمصدر الرئيسي نص المستخدم بعد تسويته. تُعامل مطالبة خارجية تطابق إحدى أحدث 10 رسائل مستخدم من جهة OpenClaw في الجلسة على أنها صدى ذاتي.
- يؤدي صف محلي واحد من Claude بصيغة JSONL يتجاوز سقف الفحص البالغ 1 MiB لكل دورة إلى حظر مؤشر تلك الجلسة في الإصدار v1؛ ولا يجري تخطي البايتات غير المصنفة أبدًا.
- تصنّف عمليات تحقق Claude على العقد المقترنة أحدث 50 عنصرًا من النص المنسوخ في كل دورة. قد تقع الدفعات الأكبر خارج نافذة الفحص في الإصدار v1.
- لا تعرض قراءات سجل Claude على العقد المقترنة نتيجة قاطعة تفيد بعدم العثور على سلسلة المحادثة، لذا لا تُصنّف عمليات حذف Claude البعيدة على أنها `upstream_missing` في الإصدار v1.
- تظل جلسات الفهرس التي لم تُتبنَّ خارج طبقة الوعي في الإصدار v1.
- لا تحمل الجلسات المتبنّاة قبل هذه الميزة أي رابط للمصدر الرئيسي؛ تابعها مرة واحدة من الفهرس لبدء مراقبة المصدر الرئيسي.
- تفترض روابط المصدر الرئيسي أن كل مفتاح جلسة متبنّاة يرتبط بوكيل مالك واحد (يستخدم التبنّي وكيل المخزن الافتراضي). لا تُراقَب في الإصدار v1 حالة تبنّي عدة وكلاء لسلسلة المحادثة الخارجية نفسها.

## ذو صلة

- [أدوات الجلسات](/ar/concepts/session-tool) — `sessions_send` و`session_status` و`sessions_list`
- [الوكلاء الفرعيون](/ar/tools/subagents) — حواف الإنشاء وإعلانات الإكمال
- [Heartbeat](/ar/gateway/heartbeat) — كيفية إيقاظ الإشعارات المدرجة في قائمة الانتظار للجلسات الرئيسية
- [إدارة الجلسات](/ar/concepts/session) — مفاتيح الجلسات ونطاقاتها ودورة حياتها