Руководство по документации

Этот каталог отвечает за написание документации, правила ссылок 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.

Правила содержимого документации

• В документации, тексте UI и списках выбора упорядочивайте сервисы/провайдеры по алфавиту, если раздел явно не описывает порядок выполнения или порядок автообнаружения.
• Поддерживайте единообразное именование встроенных plugin в соответствии с обще-репозиторными правилами терминологии plugin в корневом AGENTS.md.

Внутренняя документация

• Долгоживущая приватная операторская документация должна находиться в ~/Projects/manager/docs/.
• Локальные для репозитория внутренние черновые/зеркальные документы могут находиться в игнорируемом docs/internal/.
• Никогда не добавляйте страницы docs/internal/** в навигацию docs/docs.json и не ссылайтесь на них из публичной документации.
• scripts/docs-sync-publish.mjs исключает и удаляет docs/internal/** из публичного publish-репозитория openclaw/docs, если страница позже будет принудительно добавлена.
• Внутренняя документация может упоминать пути репозитория, названия приватных приложений, названия элементов 1Password и runbook, но никогда не должна включать секретные значения.

Редактирование карточки оценки зрелости

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, если maintainer явно не попросит о санитаризованной коммитимой проекции. Ручные переопределения должны менять исходное состояние в PR и объяснять причину, а также предоставлять публичные или отредактированные доказательства.

i18n документации

• Документация на иностранных языках не поддерживается в этом репозитории. Сгенерированный publish-вывод находится в отдельном репозитории openclaw/docs (часто локально клонированном как ../openclaw-docs).
• Не добавляйте и не редактируйте локализованную документацию в docs/<locale>/** здесь.
• Считайте английскую документацию в этом репозитории вместе с файлами глоссария источником истины.
• Pipeline: обновите английскую документацию здесь, при необходимости обновите docs/.i18n/glossary.<locale>.json, затем позвольте синхронизации publish-репозитория и scripts/docs-i18n выполниться в openclaw/docs.
• Перед повторным запуском scripts/docs-i18n добавьте записи глоссария для всех новых технических терминов, заголовков страниц или коротких меток навигации, которые должны оставаться на английском или использовать фиксированный перевод.
• pnpm docs:check-i18n-glossary является защитной проверкой для измененных английских заголовков документации и коротких внутренних меток документации.
• Translation memory находится в сгенерированных файлах docs/.i18n/*.tm.jsonl в publish-репозитории.
• См. docs/.i18n/README.md.