--- read_when: - أنت تتحقق من التحويل إلى تخزين SQLite في المسار 3 باستخدام Gateway فعلي - تحتاج إلى التمييز بين انحراف JSONL القديم المتوقع وإخفاقات وقت التشغيل - أنت تبني أو تراجع بيئة اختبار E2E المباشرة لـ SQLite والمدفوعة بالوكيل summary: تصميم لإثبات Gateway المباشر لتحويل الجلسة/النص المفرّغ في SQLite للمسار 3 title: مسار 3 لأداة اختبار SQLite الشاملة الحية x-i18n: generated_at: "2026-07-16T15:00:26Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: 2749bf47cb4967bc80a5ed37a12f2a553f3b388ed8cd90cfb3217e1b5e8afae9 source_path: reference/path3-live-sqlite-e2e-harness.md workflow: 16 --- تُثبت أداة اختبار E2E المباشر لـ SQLite في المسار 3 أن Gateway يستخدم SQLite بوصفه المخزن الأساسي للجلسات والنصوص المنسوخة، بينما تظل ملفات JSONL القديمة مدخلات للترحيل أو مواد للأرشفة. وهي أداة إثبات للمشرفين، وليست أداة تشخيص عادية للمستخدمين. بعد أن يعالج Gateway حركة مرور لاحقة للترحيل، لا يعود التكافؤ مع ملفات JSONL القديمة إشارة صالحة إلى سلامة وقت التشغيل. فقد يحتوي Gateway سليم جرى ترحيله على صفوف نصوص منسوخة في SQLite تختلف عن أعداد JSONL القديمة، لأن التفاعلات الجديدة يجب أن تُحدّث SQLite وحده. لذلك يجب على أداة الاختبار المباشر قياس سلوك Gateway وحركة صفوف SQLite وخمول الملفات القديمة وسلامة السجلات في كل خطوة. ## صيغة الأمر الأمر المباشر المقصود هو: ```bash node scripts/path3-live-sqlite-e2e.mjs \ --url http://127.0.0.1:18789 \ --agent main \ --session-key agent:main:path3-live-e2e: \ --json ``` يتصل الأمر بـ Gateway قيد التشغيل بالفعل. ولا يبدأ الترحيل أو يوقفه أو يستورده أو يعيد تشغيله، ما لم يُضف وضع ترحيل صريح لاحقًا. يمكن لمتغير CI أو المتغير المحلي المعزول استخدام `test/helpers/openclaw-test-instance.ts`، لكن مسار الإثبات المباشر يجب أن يفحص Gateway الفعلي للمشغّل وقاعدة بيانات SQLite الحقيقية الخاصة بكل وكيل. ## إثبات CLI المبني المعزول يملأ مشغّل إثبات CLI المبني مخزن جلسات قديمًا معزولًا، ويبدأ Gateway المعاد بناؤه، ويثبت أن بدء التشغيل يستورد الجلسات القديمة النشطة إلى SQLite قبل بدء قراءات وقت التشغيل. ويجب ألا يشغّل `openclaw doctor --fix` قبل أول تشغيل لـ Gateway، لأن ذلك سيثبت مسار الترحيل اليدوي بدلًا من مسار الترقية الذي يتلقاه المستخدمون عند أول إقلاع بعد التحويل. بعد الاستيراد عند بدء التشغيل، يجوز للإثبات المعزول تشغيل `openclaw doctor --session-sqlite inspect` و `openclaw doctor --session-sqlite validate` بوصفهما أدلة تشخيصية. أوامر doctor هذه ليست محرّك الترحيل لإثبات الترقية عند بدء التشغيل. يجب أن تملأ سيناريوهات استيراد doctor المنفصلة ملفات النصوص المنسوخة القديمة، إضافة إلى الملفات الجانبية للمسار، وأن تتحقق من أن doctor يؤرشف تلك العناصر بينما يظل SQLite هو المخزن الأساسي. ## الفحص المسبق يجمع الفحص المسبق خط أساس ويفشل قبل إرسال تفاعل الإثبات إذا لم يكن Gateway قابلًا للاستخدام: - `GET /health` والحالة المعمقة لـ Gateway يجب أن يبلّغا عن Gateway قيد التشغيل ويمكن الوصول إليه. - يجب أن تتطابق إصدارات CLI وGateway مع الفرع الجاري اختباره. - تسجل أداة الاختبار مؤشر سجل لسجل الملف النشط الخاص بـ Gateway. - تسجل أداة الاختبار أعداد جداول SQLite الخاصة بكل وكيل لـ `sessions`، و`session_entries`، و`transcript_events`، و`transcript_event_identities`، و `session_routes`. - تسجل أداة الاختبار `mtime`، و`size`، وحالة الوجود لملف `sessions.json` القديم، وملفات JSONL المشار إليها، ومسارات JSONL المحتملة لجلسة الإثبات. - يجب أن يعرض `lsof -p ` مقابض SQLite DB/WAL/SHM وألا يعرض أي مقابض نشطة لـ `.jsonl` أو `sessions.json`. يُعد `openclaw doctor --session-sqlite validate` معلوماتيًا فقط في الوضع المباشر. بعد حركة المرور اللاحقة للتحويل، قد يبلّغ عن انحراف متوقع عن الملفات القديمة. يجب أن تستخدم أداة الاختبار مخرجات doctor للتصنيف وجرد الترحيل، لا بوصفها مرجع النجاح أو الفشل في وقت التشغيل. ## سيناريو يقوده الوكيل يستخدم السيناريو المباشر مفتاح جلسة مخصصًا للإثبات ويقود Gateway عبر مسارات RPC العامة حيثما أمكن. ينبغي أن يكون تفاعل وكيل واحد كافيًا لممارسة الاستمرارية العادية، لكن يجب أن يغطي الإثبات الكامل نقاط التكامل 3.1b التي كانت تتطلب سابقًا فحوصًا مباشرة منفردة: - تفاعل دردشة عادي: أنشئ جلسة الإثبات أو أعد استخدامها، وأرسل مطالبة حقيقية إلى الوكيل، وانتظر نتيجة المساعد النهائية، وتحقق من `chat.history` أو إسقاط Gateway المكافئ. - هوية النص المنسوخ: تحقق من ظهور العلامة نفسها في سجل Gateway وفي صفوف النصوص المنسوخة في SQLite، بما في ذلك صفوف هوية الأحداث الثابتة عند وجودها. - موصّلات بيانات الجلسة الوصفية: اقرأ جلسة الإثبات وبعض الجلسات المباشرة الحالية المحددة من خلال موصّلات Gateway/الجلسة وقارنها بصفوف SQLite. - إسقاط تصحيح الجلسة: طبّق تغييرًا قابلًا للعكس في بيانات النموذج/الجلسة الوصفية على جلسة الإثبات، ثم تحقق من تطابق الصف المُسقط واستجابة Gateway. - دورة حياة نقطة تحقق Compaction: اسرد نقطة تحقق وفرّعها واستعدها فقط في جلسة الإثبات أو جلسة تجهيز اصطناعية تنشئها أداة الاختبار. - الاستعادة بعد إعادة التشغيل: شغّل مسار علامة الاستعادة الآمن على جلسة إثبات مضبوطة أو مثيل اختبار معزول؛ لا يجوز للوضع المباشر تشغيل هذه الخطوة إلا عندما تكون مجموعة الجلسات المستهدفة صريحة وقابلة للعكس. - دورة حياة التنظيف: احذف جلسة الإثبات أو أعد ضبطها، ثم تحقق من صفوف دورة الحياة في SQLite وحالة النص المنسوخ المؤرشف. يجب أن تستخدم نقاط التكامل الخاصة بوسائل النقل، التي لا يمكن ممارستها بأمان على Gateway المباشر للمشغّل، مثل دخول WhatsApp أو المكالمات الصوتية، مجسّات وقت تشغيل على مستوى المالك مقابل عقد SQLite نفسه بدلًا من تزييف وسيلة نقل خارجية. ## تأكيدات كل خطوة تلتقط كل خطوة حالة ما قبل التنفيذ وما بعده وتكتب سجل تأكيد منظمًا: - تزداد أعداد صفوف SQLite فقط حيثما هو متوقع. - تتقدم صفوف وقت تشغيل المسار لجلسات الإثبات المدعومة بعلامات والتي تسجل أحداث وقت التشغيل. - يحتوي صف جلسة الإثبات على `session_id` والحالة والطوابع الزمنية والبيانات الوصفية وصفوف التوجيه المتوقعة. - يتطابق إسقاط سجل/جلسة Gateway مع ذيل النص المنسوخ في SQLite. - لا يُنشأ أو يُعدّل أي ملف JSONL لجلسة الإثبات. - لا يُنشأ أي ملف جانبي لجلسة الإثبات من نوع `.trajectory.jsonl` أو `.trajectory-path.json` أو `trajectory/.jsonl` مشتق من العلامة. - تظل ملفات JSONL القديمة الحالية و`sessions.json` دون تغيير، ما لم تكن الخطوة صراحةً عملية ترحيل أو أرشفة دون اتصال. - لا تفتح عملية Gateway مقابض `.jsonl` أو `sessions.json`. - لا تحتوي السجلات منذ المؤشر السابق على `ERROR` أو `FATAL` أو `SQLITE_`، أو `no such column`، أو عدم توفر مخزن الجلسات، أو فشل الاستعادة بعد إعادة التشغيل، أو تحذير تسوية النصوص المنسوخة، إلا إذا سمح به السيناريو صراحةً في قائمة السماح. يُعد فحص السجل جزءًا من عقد النجاح والفشل. ولا يُعد Gateway الذي يستجيب لفحوص السلامة لكنه يصدر أخطاء مخطط SQLite أو حالات فشل متكررة في تسوية النصوص المنسوخة سليمًا للمسار 3. ## عنصر الدليل يجب أن تكتب أداة الاختبار الأدلة ضمن `.artifacts/path3-live-e2e//` وتُبقيها خارج git: - `summary.json`: وسائط الأمر، وإصدار Gateway، والنتيجة، والتأكيد الفاشل، ومسارات العناصر. - `sqlite-before.json` و`sqlite-after.json`: أعداد الصفوف وصفوف الإثبات المحددة. - `legacy-files.json`: حالة وجود الملف القديم، و`mtime`، والحجم، وما إذا كان كل ملف قد تغير. - `gateway-log-scan.json`: نطاق المؤشر، وأسطر السجل المتطابقة، وقرارات قائمة السماح. - `events.jsonl`: ملاحظات مرتبة لكل خطوة صالحة لتعليقات إثبات PR. يجب أن يلخّص إثبات PR هذه العناصر بدلًا من لصق النصوص المنسوخة الكاملة أو محتوى الرسائل الخاصة. ## قواعد السلامة - يجب ألا يعيد الوضع المباشر مطلقًا استيراد JSONL القديم أثناء تشغيل Gateway. - يجب ألا يعدّل الوضع المباشر الجلسات غير المخصصة للإثبات، باستثناء مجسّات الإصلاح القابلة للعكس والمحددة صراحةً. - تتطلب أي خطوة ترحيل تدميرية أو واسعة نسخة احتياطية حديثة من قاعدة بيانات SQLite المتأثرة ودليل الجلسات القديم. - يجب أن تقتصر النسخ الاحتياطية على قاعدة بيانات الوكيل/دليل الجلسة المتأثر، وأن يعاد استخدامها خلال تشغيل إثبات واحد لتجنب نمو القرص بلا حدود. - يجب ألا تترك خطوة التنظيف وراءها أي جلسة إثبات أو ملف JSONL للإثبات أو ملف قديم معدّل، ما لم يمرر المستدعي `--keep-artifacts`. ## نتيجة النجاح يعني نجاح التشغيل المباشر أن Gateway قبل تدفق جلسة حقيقيًا يقوده الوكيل، وأن كل الحالة الأساسية المرصودة كانت في SQLite، وأن ملفات وقت التشغيل القديمة ظلت خاملة، وأن سلامة السجل ظلت نظيفة خلال النافذة المقاسة. ولا يعني ذلك أن التكافؤ مع JSONL القديم يظل سليمًا بعد حركة المرور المباشرة؛ فالانحراف المباشر متوقع بمجرد أن يصبح SQLite هو المخزن الأساسي.