---
x-i18n:
    generated_at: "2026-07-27T13:41:59Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: a8712b1aeb2e605055c22cf308049e5e74fdf33061870026be20bd55cb0c3d1d
    source_path: AGENTS.md
    workflow: 16
---

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

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

## قواعد 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` ریشه آمده است، سازگار نگه دارید.
- مستندات تولیدشده را هرگز دستی ویرایش نکنید: `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` مراجعه کنید.