راهنمای مستندات

این پوشه مسئول نگارش مستندات، قواعد پیوند Mintlify و سیاست بین‌المللی‌سازی مستندات است.

قواعد Mintlify

• مستندات در Mintlify میزبانی می‌شوند (https://docs.openclaw.ai).
• پیوندهای داخلی مستندات در docs/**/*.md باید نسبت به ریشه باقی بمانند و پسوند .md یا .mdx نداشته باشند (مثال: [پیکربندی](/gateway/configuration)).
• ارجاعات متقابل به بخش‌ها باید از لنگرها در مسیرهای نسبت به ریشه استفاده کنند (مثال: [قلاب‌ها](/gateway/configuration-reference#hooks)).
• در عنوان‌های مستندات باید از خط تیره بلند و آپاستروف پرهیز شود، زیرا تولید لنگر در Mintlify برای آن‌ها شکننده است.
• README و سایر مستنداتی که در GitHub رندر می‌شوند باید نشانی‌های مطلق مستندات را حفظ کنند تا پیوندها خارج از 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 پیش‌نمایش مصنوعات را رندر می‌کند و می‌تواند PRهای مستندات تولیدشده را باز کند؛ .github/workflows/openclaw-release-checks.yml آن را برای QA انتشار اجرا می‌کند. داده‌های قطعی qa-evidence.json.scorecard را در مصنوعات GitHub Actions نگه دارید، مگر اینکه یکی از نگه‌دارندگان صراحتاً یک بازنمایی پاک‌سازی‌شده و ثبت‌شده درخواست کند. بازنویسی‌های انسانی باید وضعیت منبع را در یک PR تغییر دهند و دلیل را همراه با شواهد عمومی یا ویرایش‌شده توضیح دهند.

بین‌المللی‌سازی مستندات

• مستندات زبان‌های خارجی در این مخزن نگه‌داری نمی‌شوند. خروجی انتشار تولیدشده در مخزن جداگانه 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 را ببینید.