---
x-i18n:
    generated_at: "2026-06-27T17:08:29Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: a0c67d049eb1d0f1d4e675a71e69b2d34d3ce5c733ca9582bf08ac717c233644
    source_path: AGENTS.md
    workflow: 16
---

# دليل الوثائق

هذا الدليل مسؤول عن تأليف الوثائق، وقواعد روابط Mintlify، وسياسة i18n للوثائق.

## قواعد Mintlify

- تُستضاف الوثائق على Mintlify (`https://docs.openclaw.ai`).
- يجب أن تبقى روابط الوثائق الداخلية في `docs/**/*.md` نسبية إلى الجذر من دون لاحقة `.md` أو `.mdx` (مثال: `[Config](/gateway/configuration)`).
- يجب أن تستخدم الإحالات المتقاطعة للأقسام المراسي على المسارات النسبية إلى الجذر (مثال: `[Hooks](/gateway/configuration-reference#hooks)`).
- يجب أن تتجنب عناوين الوثائق الشرطات الطويلة والفواصل العليا لأن توليد المراسي في Mintlify هش معها.
- يجب أن تحتفظ README وغيرها من الوثائق المعروضة في GitHub بعناوين URL مطلقة للوثائق حتى تعمل الروابط خارج Mintlify.
- يجب أن يبقى محتوى الوثائق عامًا: لا أسماء أجهزة شخصية، أو أسماء مضيفين، أو مسارات محلية؛ استخدم عناصر نائبة مثل `user@gateway-host`.

## قواعد محتوى الوثائق

- بالنسبة إلى الوثائق، ونصوص الواجهة، وقوائم الاختيار، رتّب الخدمات/المزوّدين أبجديًا ما لم يكن القسم يصف صراحةً ترتيب وقت التشغيل أو ترتيب الاكتشاف التلقائي.
- حافظ على اتساق تسمية Plugin المضمّن مع قواعد مصطلحات Plugin على مستوى المستودع في ملف `AGENTS.md` الجذري.

## الوثائق الداخلية

- تنتمي وثائق المشغّل الخاصة طويلة الأجل إلى `~/Projects/manager/docs/`.
- يمكن أن تكون وثائق المسودات/المرايا الداخلية المحلية للمستودع تحت `docs/internal/` المتجاهَل.
- لا تضف أبدًا صفحات `docs/internal/**` إلى تنقّل `docs/docs.json` أو تربطها من الوثائق العامة.
- يستثني `scripts/docs-sync-publish.mjs` ويزيل `docs/internal/**` من مستودع النشر العام `openclaw/docs` إذا أُضيفت صفحة قسرًا لاحقًا.
- يمكن أن تذكر الوثائق الداخلية مسارات المستودع، وأسماء التطبيقات الخاصة، وأسماء عناصر 1Password، وأدلة التشغيل، لكن لا تُدرج أبدًا قيمًا سرية.

## تحرير بطاقة درجات النضج

`taxonomy.yaml` و`qa/maturity-scores.yaml` هما مدخلات المصدر؛ وثائق النضج المولّدة تحت `docs/maturity/` هي إسقاطات ويجب عدم تحريرها يدويًا للدرجات، أو LTS، أو التصنيف، أو ملف QA، أو جداول الأدلة.
يتولى `scripts/qa/render-maturity-docs.ts` التوليد؛ استخدم `pnpm maturity:render` لتحديث الوثائق الملتزم بها و`pnpm maturity:check` للتحقق منها.
يعرض `.github/workflows/maturity-scorecard.yml` معاينات المصنوعات ويمكنه فتح PRs للوثائق المولّدة؛ ويستدعيه `.github/workflows/openclaw-release-checks.yml` من أجل QA للإصدار.
احتفظ ببيانات `qa-evidence.json.scorecard` الحتمية في مصنوعات GitHub Actions ما لم يطلب مشرف صراحةً إسقاطًا ملتزمًا به ومنقّحًا.
يجب أن تغيّر التجاوزات البشرية حالة المصدر في PR وأن تشرح السبب مع دليل عام أو منقّح.

## i18n للوثائق

- لا تُصان الوثائق باللغات الأجنبية في هذا المستودع. يعيش خرج النشر المولّد في مستودع `openclaw/docs` المنفصل (غالبًا ما يُنسخ محليًا باسم `../openclaw-docs`).
- لا تضف أو تحرر وثائق مترجمة تحت `docs/<locale>/**` هنا.
- تعامل مع الوثائق الإنجليزية في هذا المستودع إضافةً إلى ملفات المسرد كمصدر الحقيقة.
- مسار العمل: حدّث الوثائق الإنجليزية هنا، وحدّث `docs/.i18n/glossary.<locale>.json` حسب الحاجة، ثم دع مزامنة مستودع النشر و`scripts/docs-i18n` يعملان في `openclaw/docs`.
- قبل إعادة تشغيل `scripts/docs-i18n`، أضف إدخالات مسرد لأي مصطلحات تقنية جديدة، أو عناوين صفحات، أو تسميات تنقّل قصيرة يجب أن تبقى بالإنجليزية أو تستخدم ترجمة ثابتة.
- `pnpm docs:check-i18n-glossary` هو الحارس لعناوين الوثائق الإنجليزية المتغيرة وتسميات الوثائق الداخلية القصيرة.
- تعيش ذاكرة الترجمة في ملفات `docs/.i18n/*.tm.jsonl` المولّدة في مستودع النشر.
- راجع `docs/.i18n/README.md`.