البنية الهندسية

أنبوب المستودعات الثلاثة

يمتد نظام التوثيق والحوكمة عبر ثلاثة مستودعات، كل منها بمسؤولية محددة:

المستودع	الدور
docs-control	مركز الحوكمة المركزي — إعدادات المستودع، تكوين حماية الفروع، بيان الملفات المدارة، سير عمل CI القابل لإعادة الاستخدام، سير عمل Antigravity الذكي، قوالب سير العمل المستدعية، مهارات الوكيل، والتوزيع للمستودعات التابعة
docs-builder	صورة بناء Docker — تنسيق بناء Astro + Starlight، تبعيات npm، إنشاء ملفات PDF عبر Puppeteer، والمكونات التفاعلية
docs-theme	إضافة Astro Starlight — العلامة التجارية المشتركة، CSS، الخطوط، الشعارات، مكونات التخطيط، `astro.config.mjs`، و `content.config.ts`

تحتاج مستودعات المحتوى فقط إلى دليل docs/. ويتولى حاوي البناء وسير العمل كل شيء آخر.

تدفق البيانات

عندما يتغير ملف قالب أو سير عمل في docs-control على الفرع main:

يتم تشغيل سير عمل التوزيع ويتسبب في تطبيق القواعد في كل مستودع تابع
يقارن سير عمل الإنفاذ الحالة المطلوبة بالحالة الحالية ويصلح أي انحراف
يكتشف سير عمل مزامنة الملفات الملفات المدارة المنحرفة، وينشئ طلب سحب بمحتوى معتمد، ويدمجه تلقائياً
تُنفَّذ مسارات عمل Antigravity الذكية القابلة لإعادة الاستخدام (antigravity-review.yml و antigravity-translate.yml) على طلبات السحب عبر المستودعات المسجلة

أتمتة Antigravity الذكية

يتضمن الأسطول أتمتة الذكاء الاصطناعي Antigravity (agy) التي تعمل على مشغلي GitHub Actions:

سير العمل	الغرض	المشغل والتنفيذ
مراجعة كود Antigravity (`antigravity-review.yml`)	مراجعة كود طلبات السحب الآلية بواسطة الذكاء الاصطناعي	يعمَل عند إنشاء طلب السحب أو تحديثه. يستخدم Gemini 3.6 Flash (High) لتدقيق الفروق لكشف الثغرات الأمنية، والأسرار المضمنة، وتسريب بيانات PII، وجودة الكود، ونشر الملاحظات عبر تعليقات طلب السحب.
ترجمة اللغات Antigravity (`antigravity-translate.yml`)	ترجمة التوثيق الآلية بواسطة الذكاء الاصطناعي	يعمل على طلبات السحب التي تعدل `docs/en/*/.md[x]`. ينفذ مهارة `.agents/skills/i18n-translate/SKILL.md` لتحديث 12 لغة مستهدفة (`fr` و `es` و `de` و `pt-br` و `ja` و `ko` و `zh-cn` و `zh-tw` و `ar` و `it` و `hi` و `th`)، وتحديث `i18n.sourceHash` والالتزام التلقائي مجدداً بفرع طلب السحب.

نموذج الرموز و أوراق الاعتماد

توفر ثلاث مجموعات من أوراق الاعتماد فصل الحد الأدنى من الصلاحيات:

الرمز / السر	الصلاحيات / النطاق	مستخدم بواسطة
`REPO_SETTINGS_TOKEN`	قراءة/كتابة الإدارة، قراءة/كتابة الصفحات، قراءة المحتويات، قراءة البيانات الوصفية	`enforce-repo-settings.yml` و `dispatch-downstream.yml` و `update-governed-workflow-pins.yml`
`REPO_SYNC_TOKEN`	قراءة/كتابة المحتويات، قراءة/كتابة المشكلات، قراءة/كتابة طلبات السحب، قراءة البيانات الوصفية	`sync-managed-files.yml`
`ANTIGRAVITY_TOKEN` & `GCP_PROJECT_ID`	مصادقة Antigravity AI والوصول إلى مشروع GCP	`antigravity-review.yml` و `antigravity-translate.yml`

يحتاج سير عمل الإنفاذ إلى وصول مسؤول لتعديل حماية الفروع وإعدادات Pages. يحتاج سير عمل المزامنة إلى وصول للمحتويات وطلبات السحب لإنشاء الفروع، والالتزام بالملفات، ودمج طلبات السحب. تستخدم مسارات عمل Antigravity الذكية أوراق اعتماد مشروع مخصصة للمصادقة مع Gemini 3.6 Flash.

الكشف الذاتي

يعتبر docs-control مزوداً ومستهلكاً لتكوين الحوكمة الخاص به. عندما يعمل enforce-repo-settings.yml على docs-control نفسه (عبر مشغل push)، فإنه يكتشف ذلك بمقارنة managed_files.source_repo بـ github.repository. هذا يفعل تجاوز self_contexts في حماية الفروع — يستخدم docs-control مسارات العمل مباشرة (على سبيل المثال، Shell Unit Tests)، بينما تستخدم المستودعات التابعة أغلِفة مستدعية (على سبيل المثال، lint / Shell Unit Tests). راجع صفحة التكوين للحصول على تفاصيل حول contexts مقابل self_contexts.

تخطيط المستودع

الدليل / الملف	الغرض
`.github/config/repo-settings.json`	التكوين المركزي: إعدادات المستودع، حماية الفروع، صلاحيات Actions، تكوين Pages، وبيان الملفات المدارة
`.github/config/downstream-repos.json`	سجل المستودعات التابعة المسجلة
`.github/config/docs-sites.json`	البيانات الوصفية لكل موقع توثيق تابع (التسمية، الرابط، الوصف) المستخدمة في قوالب README
`.github/workflows/`	مسارات العمل القابلة لإعادة الاستخدام: الإنفاذ، مزامنة الملفات، نشر الصفحات، فحص المشكلات المرتبطة، التوزيع، مراجعة Antigravity، وترجمة Antigravity
`.agents/skills/`	حوكمة مهارات الوكيل: `demo-components` و `i18n-translate`
`workflows/`	قوالب المستدعي التي تثبتها المستودعات التابعة في `.github/workflows/`
`docs/`	مصدر التوثيق (المبني والمنشور عبر Astro Starlight)
`CONTRIBUTING.md`	قواعد سير عمل المساهمين (المزامنة مع كافة المستودعات التابعة)
`CLAUDE.md`	تعليمات مساعد الذكاء الاصطناعي (المزامنة مع كافة المستودعات التابعة)
`AGENTS.md`	تعليمات وكيل المستودع وسياسات الحوكمة
`README.md.tpl`	قالب لملفات README الموالية المنشأة ديناميكياً
`.pre-commit-config.yaml`	تكوين خطافات pre-commit (المزامنة مع كافة المستودعات التابعة)
`.markdownlint.json`	قواعد مدقق Markdown
`.yamllint.yaml`	قواعد مدقق YAML