دليل التوثيق

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

قواعد Mintlify

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

قواعد محتوى التوثيق

• في التوثيق، ونصوص واجهة المستخدم، وقوائم الاختيار، رتّب الخدمات/المزوّدين أبجديًا ما لم يكن القسم يصف صراحةً ترتيب وقت التشغيل أو ترتيب الاكتشاف التلقائي.
• حافظ على اتساق تسمية Plugin المضمّنة مع قواعد مصطلحات Plugin المطبّقة على مستوى المستودع في ملف AGENTS.md الجذري.
• التوثيق المُنشأ آليًا، لا تعدّله يدويًا مطلقًا: تُنشأ docs/plugins/reference/** وdocs/plugins/reference.md وdocs/plugins/plugin-inventory.md بواسطة pnpm plugins:inventory:gen؛ ويُنشأ docs/docs_map.md بواسطة pnpm docs:map:gen؛ وتُنشأ docs/maturity/** بواسطة pnpm maturity:render.

التوثيق الداخلي

• يجب وضع توثيق المشغّلين الخاص طويل الأجل في ~/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 معاينات للنتائج ويمكنه فتح طلبات سحب للمستندات المُنشأة؛ ويستدعيه .github/workflows/openclaw-release-checks.yml لإجراء QA للإصدار. احتفظ ببيانات qa-evidence.json.scorecard الحتمية في مخرجات GitHub Actions، ما لم يطلب أحد المشرفين صراحةً إسقاطًا منقّحًا وملتزمًا به. يجب أن تغيّر التجاوزات البشرية حالة المصدر في طلب سحب، وأن توضّح السبب مع أدلة عامة أو منقّحة.

تدويل التوثيق

• لا تُصان مستندات اللغات الأجنبية في هذا المستودع. يوجد ناتج النشر المُنشأ في مستودع 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.