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

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

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

• В документации, тексте интерфейса и списках выбора располагайте сервисы и провайдеров в алфавитном порядке, если раздел явно не описывает порядок выполнения или автоматического обнаружения.
• Именование встроенных плагинов должно соответствовать общим для репозитория правилам терминологии плагинов в корневом файле 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.