دليل الوثائق

هذا الدليل مسؤول عن تأليف الوثائق، وقواعد روابط 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.