الانتقال إلى المحتوى الرئيسي
تُشغّل مسار Matrix QA الـ Plugin المضمّن @openclaw/matrix مقابل خادم Tuwunel homeserver مؤقت في Docker، مع حسابات مؤقتة للسائق وSUT والمراقب، إضافةً إلى غرف مُهيأة مسبقاً. وهو تغطية النقل الحية والواقعية لـ Matrix. هذه أدوات خاصة بالمشرفين فقط. إصدارات OpenClaw المعبأة تتعمد حذف qa-lab، لذلك لا يتوفر openclaw qa إلا من checkout للمصدر. تقوم checkouts المصدر بتحميل المشغّل المضمّن مباشرةً - ولا حاجة إلى خطوة تثبيت Plugin. للحصول على سياق أوسع حول إطار QA، راجع نظرة عامة على QA.

​
البدء السريع

pnpm openclaw qa matrix --profile fast --fail-fast
يشغّل الأمر العادي pnpm openclaw qa matrix الخيار --profile all ولا يتوقف عند أول فشل. استخدم --profile fast --fail-fast كبوابة إصدار؛ وقسّم الفهرس باستخدام --profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli عند تشغيل المخزون الكامل بالتوازي.

​
ما يفعله المسار

  1. يوفّر خادم Tuwunel homeserver مؤقتاً في Docker (الصورة الافتراضية ghcr.io/matrix-construct/tuwunel:v1.5.1، اسم الخادم matrix-qa.test، المنفذ 28008) خلف مسجّل محدود يحجب البيانات الحساسة للطلبات/الاستجابات.
  2. يسجّل ثلاثة مستخدمين مؤقتين - driver (يرسل حركة المرور الواردة)، وsut (حساب OpenClaw Matrix قيد الاختبار)، وobserver (التقاط حركة مرور من طرف ثالث).
  3. يهيئ الغرف المطلوبة من السيناريوهات المحددة (الرئيسية، threading، الوسائط، إعادة التشغيل، الثانوية، قائمة السماح، E2EE، رسالة التحقق المباشرة، وما إلى ذلك).
  4. يشغّل مجس بروتوكول matrix-qa-v1 المحايد للركيزة مقابل حد Tuwunel المسجّل. تثبت اختبارات الوحدة عقد المجس مع مُثبّت بروتوكول Matrix؛ ويمتلك مضيف محوّل نقل QA المعياري في #99707 توصيلات هدف Crabline الحقيقية.
  5. يبدأ Gateway فرعياً من OpenClaw مع Plugin Matrix الحقيقي المقيّد بحساب SUT؛ ولا يتم تحميل qa-channel في الفرع.
  6. يشغّل السيناريوهات بالتتابع، مع مراقبة الأحداث عبر عملاء Matrix للسائق/المراقب واشتقاق توقعات التوجيه/الحالة من حركة المرور المسجّلة.
  7. يفكك خادم homeserver، ويكتب التقرير ومخرجات الأدلة، ثم يخرج.

​
CLI

pnpm openclaw qa matrix [options]

​
العلامات الشائعة

العلامةالافتراضيالوصف
--profile <profile>allملف تعريف السيناريو. راجع ملفات التعريف.
--fail-fastمتوقفالتوقف بعد أول فحص أو سيناريو فاشل.
--scenario <id>-تشغيل هذا السيناريو فقط. قابل للتكرار. راجع السيناريوهات.
--output-dir <path><repo>/.artifacts/qa-e2e/matrix-<timestamp>مكان كتابة التقارير والملخص ومخزون التوجيه/الحالة والأحداث المرصودة وسجل الإخراج. تُحل المسارات النسبية مقابل --repo-root.
--repo-root <path>process.cwd()جذر المستودع عند الاستدعاء من دليل عمل محايد.
--sut-account <id>sutمعرّف حساب Matrix داخل إعدادات Gateway الخاصة بـ QA.

​
علامات المزوّد

يستخدم المسار نقل Matrix حقيقياً، لكن مزوّد النموذج قابل للتكوين:
العلامةالافتراضيالوصف
--provider-mode <mode>live-frontiermock-openai للإرسال الوهمي الحتمي أو live-frontier لمزوّدي frontier الحيين. لا يزال الاسم المستعار القديم live-openai يعمل.
--model <ref>افتراضي المزوّدمرجع provider/model الأساسي.
--alt-model <ref>افتراضي المزوّدمرجع provider/model بديل عند تبديل السيناريوهات في منتصف التشغيل.
--fastمتوقفتفعيل الوضع السريع للمزوّد حيث يكون مدعوماً.
لا يقبل Matrix QA الخيارين --credential-source أو --credential-role. يوفّر المسار مستخدمين مؤقتين محلياً؛ ولا توجد مجموعة بيانات اعتماد مشتركة للاستئجار منها.

​
ملفات التعريف

يحدد ملف التعريف المحدد السيناريوهات التي ستعمل.
ملف التعريفاستخدمه من أجل
all (افتراضي)الفهرس الكامل. بطيء لكنه شامل.
fastمجموعة فرعية لبوابة الإصدار تختبر عقد النقل الحي: canary، بوابة الإشارات، حظر قائمة السماح، شكل الرد، استئناف إعادة التشغيل، متابعة threading، عزل threading، مراقبة التفاعلات، وتسليم بيانات اعتماد موافقة exec الوصفية.
transportسيناريوهات threading على مستوى النقل، والرسائل المباشرة، والغرف، والانضمام التلقائي، والإشارة/قائمة السماح، والموافقة، والتفاعل.
mediaتغطية مرفقات الصور والصوت والفيديو وPDF وEPUB.
e2ee-smokeالحد الأدنى من تغطية E2EE - رد مشفّر أساسي، ومتابعة threading، ونجاح bootstrap.
e2ee-deepسيناريوهات شاملة لفقدان حالة E2EE والنسخ الاحتياطي والمفاتيح والاسترداد.
e2ee-cliسيناريوهات CLI للأمرين openclaw matrix encryption setup وverify * التي تُقاد عبر حزمة QA.
توجد المطابقة الدقيقة في extensions/qa-matrix/src/runners/contract/scenario-catalog.ts.

​
السيناريوهات

قائمة معرّفات السيناريو الكاملة هي اتحاد MatrixQaScenarioId في extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15. تشمل الفئات:
  • threading - matrix-thread-*، matrix-subagent-thread-spawn
  • المستوى الأعلى / رسالة مباشرة / غرفة - matrix-top-level-reply-shape، matrix-room-*، matrix-dm-*
  • البث وتقدم الأدوات - matrix-room-partial-streaming-preview، matrix-room-quiet-streaming-preview، matrix-room-tool-progress-*، matrix-room-block-streaming
  • الوسائط - matrix-media-type-coverage، matrix-room-image-understanding-attachment، matrix-attachment-only-ignored، matrix-unsupported-media-safe
  • التوجيه - matrix-room-autojoin-invite، matrix-secondary-room-*
  • التفاعلات - matrix-reaction-*
  • الموافقات - matrix-approval-* (بيانات exec/Plugin الوصفية، fallback المجزأ، تفاعلات الرفض، threading، وتوجيه target: "both")
  • إعادة التشغيل وإعادة التشغيل من السجل - matrix-restart-*، matrix-stale-sync-replay-dedupe، matrix-room-membership-loss، matrix-homeserver-restart-resume، matrix-initial-catchup-then-incremental
  • بوابة الإشارات، وروبوت إلى روبوت، وقوائم السماح - matrix-mention-*، matrix-allowbots-*، matrix-allowlist-*، matrix-multi-actor-ordering، matrix-inbound-edit-*، matrix-mxid-prefixed-command-block، matrix-observer-allowlist-override
  • E2EE - matrix-e2ee-* (رد أساسي، متابعة threading، bootstrap، دورة حياة مفتاح الاسترداد، متغيرات فقدان الحالة، سلوك النسخ الاحتياطي للخادم، نظافة الجهاز، تحقق SAS / QR / DM، إعادة التشغيل، حجب مخرجات الأدلة)
  • E2EE CLI - matrix-e2ee-cli-* (إعداد التشفير، إعداد متكرر آمن، فشل bootstrap، دورة حياة مفتاح الاسترداد، حسابات متعددة، رحلة ذهاب وإياب لرد Gateway، التحقق الذاتي)
مرّر --scenario <id> (قابل للتكرار) لتشغيل مجموعة منتقاة يدوياً؛ واجمعه مع --profile all لتجاهل بوابة ملف التعريف.

​
متغيرات البيئة

المتغيرالافتراضيالتأثير
OPENCLAW_QA_MATRIX_TIMEOUT_MS1800000 (30 دقيقة)حد أعلى صارم للتشغيل بأكمله.
OPENCLAW_QA_MATRIX_CANARY_TIMEOUT_MS45000حد لرد الاختبار الأولي. يرفع CI للإصدارات هذا الحد على المشغلات المشتركة كي لا تفشل دورة Gateway الأولى البطيئة قبل بدء تغطية السيناريو.
OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS8000نافذة هادئة لتأكيدات عدم الرد السلبية. تُقيَّد إلى ≤ مهلة التشغيل.
OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS90000حد لإزالة Docker. تتضمن أسطح الفشل أمر الاسترداد docker compose ... down --remove-orphans.
OPENCLAW_QA_MATRIX_TUWUNEL_IMAGEghcr.io/matrix-construct/tuwunel:v1.5.1تجاوز صورة الخادم المنزلي عند التحقق باستخدام إصدار Tuwunel مختلف.
OPENCLAW_QA_MATRIX_PROGRESSمفعّلتجعل 0 أسطر تقدم [matrix-qa] ... صامتة على stderr. وتجبرها 1 على الظهور.
OPENCLAW_QA_MATRIX_CAPTURE_CONTENTمنقّحتبقي 1 نص الرسالة وformatted_body في matrix-qa-observed-events.json. ينقّح الافتراضي المحتوى للحفاظ على أمان عناصر CI.
OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXITمعطّلتتخطى 1 استدعاء process.exit الحتمي بعد كتابة العناصر. يفرض الافتراضي الخروج لأن مقابض التشفير الأصلية في matrix-js-sdk يمكن أن تبقي حلقة الأحداث نشطة بعد اكتمال العناصر.
OPENCLAW_RUN_NODE_OUTPUT_LOGغير معيّنعند تعيينه بواسطة مشغّل خارجي (مثل scripts/run-node.mjs)، يعيد QA الخاص بـ Matrix استخدام مسار السجل هذا بدلاً من بدء tee خاص به.

​
عناصر الإخراج

تُكتب إلى --output-dir:
  • matrix-qa-report.md - تقرير بروتوكول Markdown (ما نجح، وما فشل، وما تم تخطيه، والسبب).
  • matrix-qa-summary.json - ملخص منظم مناسب لتحليل CI ولوحات المعلومات.
  • matrix-qa-route-state-manifest.json - قائمة حصر matrix-qa-v1 ديناميكية مفهرسة حسب معرف السيناريو. تسجل أشكال المسارات/الأجسام المنقّحة، وترتيب الطلبات، وإعادات المحاولة المرصودة، والأخطاء، واستمرارية رموز المزامنة، وعائلات حالات الأجهزة/المفاتيح/الوسائط/النسخ الاحتياطي المرصودة أثناء ذلك التشغيل. هذا دليل قابل للتنفيذ، وليس أساساً مرجعياً محفوظاً في المستودع.
  • matrix-qa-observed-events.json - أحداث Matrix المرصودة من عملاء السائق والمراقب. تُنقّح الأجسام ما لم يكن OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1؛ وتُلخّص بيانات موافقة التعريف باستخدام حقول آمنة مختارة ومعاينة أمر مقتطعة.
  • matrix-qa-output.log - مخرجات stdout/stderr المجمعة من التشغيل. إذا كان OPENCLAW_RUN_NODE_OUTPUT_LOG معيّناً، يُعاد استخدام سجل المشغّل الخارجي بدلاً من ذلك.
دليل الإخراج الافتراضي هو <repo>/.artifacts/qa-e2e/matrix-<timestamp> كي لا تستبدل عمليات التشغيل المتعاقبة بعضها بعضاً.

​
نصائح الفرز

  • يتوقف التشغيل قرب النهاية: يمكن أن تبقى مقابض التشفير الأصلية في matrix-js-sdk بعد عمر الحزام الاختباري. يفرض الافتراضي استدعاء process.exit نظيفاً بعد كتابة العناصر؛ إذا كنت قد ألغيت تعيين OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1، فتوقع أن تبقى العملية قيد التشغيل مدة أطول.
  • خطأ تنظيف: ابحث عن أمر الاسترداد المطبوع (استدعاء docker compose ... down --remove-orphans) وشغّله يدوياً لتحرير منفذ الخادم المنزلي.
  • نوافذ التأكيدات السلبية المتذبذبة في CI: خفّض OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS (الافتراضي 8 ثوانٍ) عندما يكون CI سريعاً؛ وارفعه على المشغلات المشتركة البطيئة.
  • تحتاج إلى أجسام منقّحة لتقرير خطأ: أعد التشغيل باستخدام OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1 وأرفق matrix-qa-observed-events.json. تعامل مع العنصر الناتج باعتباره حساساً.
  • إصدار Tuwunel مختلف: وجّه OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE إلى الإصدار قيد الاختبار. يتحقق المسار من الصورة الافتراضية المثبتة فقط.

​
عقد النقل المباشر

Matrix واحد من ثلاثة مسارات نقل مباشرة (Matrix وTelegram وDiscord) تشترك في قائمة تحقق عقد واحدة معرّفة في نظرة عامة على QA → تغطية النقل المباشر. تبقى qa-channel هي الحزمة الاصطناعية الواسعة، وهي ليست جزءاً من تلك المصفوفة عمداً.

​
ذات صلة

  • نظرة عامة على QA - مكدس QA العام وعقد النقل المباشر
  • قناة QA - محوّل قناة اصطناعي للسيناريوهات المدعومة بالمستودع
  • الاختبار - تشغيل الاختبارات وإضافة تغطية QA
  • Matrix - Plugin القناة قيد الاختبار