---
read_when:
    - تحتاج إلى فهم سبب تشغيل مهمة CI أو عدم تشغيلها
    - أنت تقوم بتصحيح أخطاء فحوصات GitHub Actions الفاشلة
summary: رسم مهام CI البياني، وبوابات النطاق، ومكافئات الأوامر المحلية
title: مسار CI
x-i18n:
    generated_at: "2026-04-23T14:55:11Z"
    model: gpt-5.4
    provider: openai
    source_hash: e9a03440ae28a15167fc08d9c66bb1fd719ddfa1517aaecb119c80f2ad826c0d
    source_path: ci.md
    workflow: 15
---

# مسار CI

يعمل CI عند كل دفع إلى `main` وكل طلب سحب. ويستخدم تحديد نطاق ذكيًا لتخطي المهام المكلفة عندما تكون التغييرات مقتصرة على مناطق غير ذات صلة.

لدى QA Lab مسارات CI مخصصة خارج سير العمل الرئيسي ذي النطاق الذكي. يعمل
سير العمل `Parity gate` على تغييرات طلبات السحب المطابقة وعند التشغيل اليدوي؛ وهو
يبني بيئة تشغيل QA الخاصة ويقارن حزم الوكلاء agentic الوهمية لـ GPT-5.4 وOpus 4.6.
ويعمل سير العمل `QA-Lab - All Lanes` ليلاً على `main` وعند
التشغيل اليدوي؛ ويقوم بتفريع مسار parity gate الوهمي، ومسار Matrix الحي، ومسار
Telegram الحي كمهام متوازية. تستخدم المهام الحية بيئة `qa-live-shared`،
ويستخدم مسار Telegram حجوزات Convex. كما يشغّل `OpenClaw Release
Checks` مسارات QA Lab نفسها قبل الموافقة على الإصدار.

## نظرة عامة على المهام

| المهمة                            | الغرض                                                                                        | وقت التشغيل                          |
| --------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ |
| `preflight`                       | اكتشاف تغييرات الوثائق فقط، والنطاقات المتغيرة، والامتدادات المتغيرة، وبناء بيان CI         | دائمًا في عمليات الدفع وطلبات السحب غير المسودة |
| `security-scm-fast`               | اكتشاف المفاتيح الخاصة وتدقيق سير العمل عبر `zizmor`                                        | دائمًا في عمليات الدفع وطلبات السحب غير المسودة |
| `security-dependency-audit`       | تدقيق lockfile الإنتاجي دون تبعيات مقابل تنبيهات npm                                        | دائمًا في عمليات الدفع وطلبات السحب غير المسودة |
| `security-fast`                   | مجمّع مطلوب لمهام الأمان السريعة                                                             | دائمًا في عمليات الدفع وطلبات السحب غير المسودة |
| `build-artifacts`                 | بناء `dist/` وواجهة Control UI وفحوصات مخرجات البناء والقطع الأثرية القابلة لإعادة الاستخدام للمراحل اللاحقة | تغييرات ذات صلة بـ Node              |
| `checks-fast-core`                | مسارات صحة Linux السريعة مثل فحوصات bundled/plugin-contract/protocol                        | تغييرات ذات صلة بـ Node              |
| `checks-fast-contracts-channels`  | فحوصات عقود القنوات المجزأة مع نتيجة فحص مجمعة مستقرة                                        | تغييرات ذات صلة بـ Node              |
| `checks-node-extensions`          | أجزاء اختبارات Plugin المجمعة الكاملة عبر مجموعة الامتدادات                                 | تغييرات ذات صلة بـ Node              |
| `checks-node-core-test`           | أجزاء اختبارات Node الأساسية، باستثناء مسارات القنوات والمجمعة والعقود والامتدادات          | تغييرات ذات صلة بـ Node              |
| `extension-fast`                  | اختبارات مركزة لـ Plugin المجمعة المتغيرة فقط                                               | طلبات السحب التي تحتوي على تغييرات في الامتدادات |
| `check`                           | المكافئ المحلي الرئيسي المجزأ: أنواع الإنتاج، وlint، والحواجز، وأنواع الاختبارات، واختبار smoke الصارم | تغييرات ذات صلة بـ Node              |
| `check-additional`                | حواجز البنية، والحدود، وأسـطح الامتدادات، وحدود الحزم، وأجزاء gateway-watch                 | تغييرات ذات صلة بـ Node              |
| `build-smoke`                     | اختبارات smoke للـ CLI المبني واختبار smoke لذاكرة الإقلاع                                  | تغييرات ذات صلة بـ Node              |
| `checks`                          | متحقق لاختبارات القنوات على مخرجات البناء بالإضافة إلى توافق Node 22 في الدفع فقط           | تغييرات ذات صلة بـ Node              |
| `check-docs`                      | تنسيق الوثائق وlint وفحوصات الروابط المعطلة                                                 | عند تغيّر الوثائق                    |
| `skills-python`                   | Ruff + pytest للـ Skills المعتمدة على Python                                                | تغييرات ذات صلة بـ Skills في Python  |
| `checks-windows`                  | مسارات اختبارات خاصة بـ Windows                                                              | تغييرات ذات صلة بـ Windows           |
| `macos-node`                      | مسار اختبارات TypeScript على macOS باستخدام مخرجات البناء المشتركة                          | تغييرات ذات صلة بـ macOS             |
| `macos-swift`                     | lint وbuild واختبارات Swift لتطبيق macOS                                                    | تغييرات ذات صلة بـ macOS             |
| `android`                         | اختبارات وحدات Android لكلا النكهتين بالإضافة إلى بناء APK واحد للتصحيح                     | تغييرات ذات صلة بـ Android           |

## ترتيب الإخفاق السريع

تُرتَّب المهام بحيث تفشل الفحوصات الرخيصة قبل تشغيل المهام المكلفة:

1. يقرر `preflight` أي المسارات موجودة أصلًا. ومنطق `docs-scope` و`changed-scope` هما خطوتان داخل هذه المهمة، وليسا مهمتين مستقلتين.
2. تفشل `security-scm-fast` و`security-dependency-audit` و`security-fast` و`check` و`check-additional` و`check-docs` و`skills-python` سريعًا من دون انتظار مهام المخرجات والمنصات الأثقل.
3. يتداخل `build-artifacts` مع مسارات Linux السريعة حتى يتمكن المستهلكون اللاحقون من البدء فور جاهزية البناء المشترك.
4. بعد ذلك تتفرع مسارات المنصة وبيئة التشغيل الأثقل: `checks-fast-core` و`checks-fast-contracts-channels` و`checks-node-extensions` و`checks-node-core-test` و`extension-fast` الخاصة بطلبات السحب فقط و`checks` و`checks-windows` و`macos-node` و`macos-swift` و`android`.

يوجد منطق النطاق في `scripts/ci-changed-scope.mjs` وتغطيه اختبارات وحدات في `src/scripts/ci-changed-scope.test.ts`.
تتحقق تعديلات سير عمل CI من رسم CI البياني الخاص بـ Node بالإضافة إلى lint لسير العمل، لكنها لا تفرض بنفسها عمليات بناء أصلية لـ Windows أو Android أو macOS؛ إذ تبقى مسارات تلك المنصات محددة النطاق بحسب تغييرات مصدر المنصة.
تُحدَّد فحوصات Windows Node ضمن أغلفة العمليات/المسارات الخاصة بـ Windows، ومساعدات تشغيل npm/pnpm/UI، وإعدادات مدير الحزم، وأسـطح سير عمل CI التي تنفذ ذلك المسار؛ أما التغييرات غير المرتبطة في المصدر أو Plugin أو install-smoke أو الاختبارات فقط فتبقى على مسارات Linux Node حتى لا تحجز عامل Windows بـ 16 vCPU لتغطية مماثلة تُختبر بالفعل عبر أجزاء الاختبار العادية.
يعيد سير العمل المنفصل `install-smoke` استخدام نص النطاق نفسه عبر مهمة `preflight` الخاصة به. وهو يحسب `run_install_smoke` من إشارة changed-smoke الأضيق، لذلك تعمل اختبارات smoke الخاصة بـ Docker/install عند تغييرات التثبيت أو التغليف أو ما له صلة بالحاويات أو تغييرات إنتاج الامتدادات المجمعة أو أسطح Plugin/channel/gateway/Plugin SDK الأساسية التي تمارسها مهام Docker smoke. أما تعديلات الاختبارات فقط أو الوثائق فقط فلا تحجز عمال Docker. ويُجبر smoke حزمة QR طبقة Docker الخاصة بـ `pnpm install` على إعادة التشغيل مع الحفاظ على ذاكرة BuildKit المؤقتة الخاصة بـ pnpm store، لذلك يظل يختبر التثبيت من دون إعادة تنزيل التبعيات في كل تشغيل. ويعيد gateway-network e2e استخدام صورة بيئة التشغيل المبنية سابقًا داخل المهمة، وبذلك يضيف تغطية WebSocket فعلية من حاوية إلى حاوية من دون إضافة بناء Docker آخر. يقوم `test:docker:all` المحلي مسبقًا ببناء صورة live-test مشتركة واحدة وصورة built-app مشتركة واحدة من `scripts/e2e/Dockerfile`، ثم يشغّل مسارات smoke الحية/‏E2E بالتوازي مع `OPENCLAW_SKIP_DOCKER_BUILD=1`؛ ويمكن ضبط التوازي الافتراضي البالغ 4 بواسطة `OPENCLAW_DOCKER_ALL_PARALLELISM`. ويتوقف المجمع المحلي افتراضيًا عن جدولة مسارات مجمعة جديدة بعد أول فشل، ولكل مسار مهلة 120 دقيقة يمكن تجاوزها عبر `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. وتعمل المسارات الحساسة للإقلاع أو لمزوّدات الخدمة بشكل حصري بعد المجموعة المتوازية. ويعكس سير العمل الحي/‏E2E القابل لإعادة الاستخدام نمط الصورة المشتركة عبر بناء ودفع صورة Docker E2E واحدة موسومة بـ SHA إلى GHCR قبل مصفوفة Docker، ثم تشغيل المصفوفة مع `OPENCLAW_SKIP_DOCKER_BUILD=1`. ويشغّل سير العمل الحي/‏E2E المجدول مجموعة Docker الكاملة لمسار الإصدار يوميًا. وتحتفظ اختبارات Docker الخاصة بـ QR والمثبتات بملفات Dockerfiles الخاصة بها والمركزة على التثبيت. وتعمل مهمة `docker-e2e-fast` منفصلة على ملف تعريف Docker محدود للـ Plugin المجمعة ضمن مهلة أمر قدرها 120 ثانية: إصلاح تبعيات setup-entry بالإضافة إلى عزل أعطال bundled-loader الاصطناعية. وتبقى مصفوفة التحديث/القنوات المجمعة الكاملة يدوية/للمجموعة الكاملة لأنها تنفذ تمريرات متكررة فعلية لـ npm update وإصلاح doctor.

يوجد منطق المسارات المحلية المتغيرة في `scripts/changed-lanes.mjs` ويُنفَّذ بواسطة `scripts/check-changed.mjs`. وهذه البوابة المحلية أكثر صرامة بشأن حدود البنية من نطاق CI الواسع الخاص بالمنصات: تغييرات الإنتاج الأساسية تشغّل فحص أنواع الإنتاج الأساسي بالإضافة إلى الاختبارات الأساسية، وتغييرات الاختبارات الأساسية فقط تشغّل فحص أنواع الاختبارات الأساسية/اختباراتها فقط، وتغييرات إنتاج الامتدادات تشغّل فحص أنواع إنتاج الامتدادات بالإضافة إلى اختبارات الامتدادات، وتغييرات اختبارات الامتدادات فقط تشغّل فحص أنواع اختبارات الامتدادات/اختباراتها فقط. أما تغييرات Plugin SDK العامة أو plugin-contract فتوسّع التحقق ليشمل الامتدادات لأن الامتدادات تعتمد على تلك العقود الأساسية. وتشغّل زيادات الإصدار التي تخص بيانات الإصدار الوصفية فقط فحوصات مستهدفة للإصدار/الإعدادات/اعتماديات الجذر. أما تغييرات الجذر/الإعدادات غير المعروفة فتعتمد جميع المسارات كخيار آمن.

عند عمليات الدفع، تضيف مصفوفة `checks` المسار الخاص بالدفع فقط `compat-node22`. أما في طلبات السحب، فيُتخطى ذلك المسار وتبقى المصفوفة مركزة على مسارات الاختبارات/القنوات العادية.

تنقسم أو تتوازن أبطأ عائلات اختبارات Node بحيث تبقى كل مهمة صغيرة من دون حجز مفرط للعاملين: تعمل عقود القنوات كثلاثة أجزاء موزونة، وتُوازن اختبارات Plugin المجمعة عبر ستة عمال للامتدادات، وتُقرن مسارات الوحدات الأساسية الصغيرة، ويعمل auto-reply عبر ثلاثة عمال متوازنين بدلًا من ستة عمال صغار، وتُوزّع إعدادات agentic gateway/plugin عبر مهام Node agentic الحالية الخاصة بالمصدر فقط بدلًا من انتظار مخرجات البناء. وتستخدم اختبارات المتصفح الواسعة وQA والوسائط وPlugin المتنوعة إعدادات Vitest المخصصة لها بدلًا من إعداد Plugin المشترك الشامل. ويستخدم مسار agents الواسع مجدول Vitest المشترك للتوازي على مستوى الملفات لأنه يهيمن عليه الاستيراد/الجدولة بدلًا من أن يملكه ملف اختبار بطيء واحد. ويعمل `runtime-config` مع جزء infra core-runtime حتى لا يستأثر جزء بيئة التشغيل المشترك بذيل التنفيذ. ويُبقي `check-additional` أعمال compile/canary الخاصة بحدود الحزم معًا ويفصل بنية topology الخاصة ببيئة التشغيل عن تغطية gateway watch؛ كما يشغّل جزء boundary guard حواجزه الصغيرة المستقلة بالتوازي داخل مهمة واحدة. وتعمل gateway watch واختبارات القنوات وجزء core support-boundary بالتوازي داخل `build-artifacts` بعد بناء `dist/` و`dist-runtime/` مسبقًا، مع الاحتفاظ بأسماء الفحوصات القديمة الخاصة بها كمهام تحقق خفيفة مع تجنب عاملين إضافيين من Blacksmith وطابور مستهلك ثانٍ للمخرجات.
يشغّل Android CI كلًا من `testPlayDebugUnitTest` و`testThirdPartyDebugUnitTest`، ثم يبني Play debug APK. ولا تحتوي نكهة third-party على مجموعة مصادر أو manifest منفصل؛ ومع ذلك ما يزال مسار اختبار الوحدات الخاص بها يترجم تلك النكهة باستخدام علامات BuildConfig الخاصة بـ SMS/call-log، مع تجنب مهمة تغليف debug APK مكررة في كل دفع ذي صلة بـ Android.
يقتصر `extension-fast` على طلبات السحب لأن عمليات الدفع تشغّل بالفعل أجزاء Plugin المجمعة الكاملة. وهذا يُبقي تغذية راجعة Plugin المتغيرة للمراجعات من دون حجز عامل Blacksmith إضافي على `main` لتغطية موجودة أصلًا في `checks-node-extensions`.

قد يضع GitHub علامة `cancelled` على المهام المستبدلة عندما يصل دفع أحدث إلى المرجع نفسه في طلب السحب نفسه أو في `main`. اعتبر ذلك ضوضاء في CI ما لم يكن أحدث تشغيل للمرجع نفسه فاشلًا أيضًا. تستخدم فحوصات الأجزاء المجمعة `!cancelled() && always()` حتى تظل تبلغ عن أعطال الأجزاء العادية، لكنها لا تُدرج في الطابور بعد أن يكون سير العمل بالكامل قد استُبدل بالفعل.
مفتاح التزامن في CI مُرقّم بإصدار (`CI-v7-*`) حتى لا يتمكن كيان GitHub عالق في مجموعة طوابير قديمة من حجب تشغيلات `main` الأحدث إلى أجل غير مسمى.

## المشغّلات

| المشغّل                         | المهام                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04`                   | `preflight`، ومهام الأمان السريعة ومجمّعاتها (`security-scm-fast` و`security-dependency-audit` و`security-fast`)، وفحوصات protocol/contract/bundled السريعة، وفحوصات عقود القنوات المجزأة، وأجزاء `check` باستثناء lint، وأجزاء `check-additional` ومجمّعاتها، ومتحققات تجميع اختبارات Node، وفحوصات الوثائق، وSkills الخاصة بـ Python، وworkflow-sanity، وlabeler، وauto-response؛ كما يستخدم preflight الخاص بـ install-smoke أيضًا Ubuntu المستضاف من GitHub حتى تتمكن مصفوفة Blacksmith من دخول الطابور مبكرًا |
| `blacksmith-8vcpu-ubuntu-2404`   | `build-artifacts`، وbuild-smoke، وأجزاء اختبارات Linux Node، وأجزاء اختبارات Plugin المجمعة، و`android`                                                                                                                                                                                                                                                                                                                                                                     |
| `blacksmith-16vcpu-ubuntu-2404`  | `check-lint`، الذي لا يزال حساسًا بما يكفي للمعالج بحيث إن 8 vCPU كانت تكلف أكثر مما وفّرت؛ وبناءات Docker الخاصة بـ install-smoke، حيث إن زمن انتظار طابور 32 vCPU كان أعلى من الفائدة التي يحققها                                                                                                                                                                                                                                                                   |
| `blacksmith-16vcpu-windows-2025` | `checks-windows`                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `blacksmith-6vcpu-macos-latest`  | `macos-node` على `openclaw/openclaw`؛ أما forks فتعود إلى `macos-latest`                                                                                                                                                                                                                                                                                                                                                                                                   |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` على `openclaw/openclaw`؛ أما forks فتعود إلى `macos-latest`                                                                                                                                                                                                                                                                                                                                                                                                  |

## المكافئات المحلية

```bash
pnpm changed:lanes   # افحص مصنّف المسارات المحلية المتغيرة لـ origin/main...HEAD
pnpm check:changed   # بوابة محلية ذكية: typecheck/lint/tests للتغييرات حسب مسار الحدود
pnpm check          # بوابة محلية سريعة: `tsgo` للإنتاج + lint مجزأ + حواجز سريعة متوازية
pnpm check:test-types
pnpm check:timed    # البوابة نفسها مع أزمنة كل مرحلة
pnpm build:strict-smoke
pnpm check:architecture
pnpm test:gateway:watch-regression
pnpm test           # اختبارات vitest
pnpm test:channels
pnpm test:contracts:channels
pnpm check:docs     # تنسيق الوثائق + lint + الروابط المعطلة
pnpm build          # ابنِ dist عندما تكون مسارات مخرجات CI/‏build-smoke مهمة
node scripts/ci-run-timings.mjs <run-id>      # لخّص وقت التنفيذ الكلي ووقت الانتظار وأبطأ المهام
node scripts/ci-run-timings.mjs --recent 10   # قارن تشغيلات CI الناجحة الأخيرة على main
```
