Перейти к содержанию

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

Существуют три разные поверхности /docs. У них нет общего хоста, рендерера и контракта. Смешивать их — обычный способ открыть OpenAPI, когда нужен how-to, или статью справки, когда нужна схема.

URL и кто их видит

Поверхность Типичный URL Кому видно Что это
Справочник MkDocs http://localhost:8011/ (RU), http://localhost:8011/en/ (EN) всем эта документация, собранная из docs-user-facing/docs/
Проекция веба /{locale}/docs и /{locale}/docs/{slug…} всем тот же Markdown внутри сайта
Machine-документация веба /{locale}/ai/docs и /{locale}/ai/docs/{slug…} всем Markdown-проекция этой страницы
OpenAPI API {API host}/docs всем, кто достигает API Swagger UI для HTTP-контрактов
ReDoc API {API host}/redoc всем, кто достигает API ReDoc того же OpenAPI
OpenAPI JSON {API host}/openapi.json всем, кто достигает API машинная схема

В разработке тот же процесс отдаёт обе языковые линии на http://localhost:8011 (AI_STP_USER_DOCS_URL): русский корень / и английский /en/. Это не живой mkdocs serve одной docs_dir — английский на том хосте не 404. Сайт — другой origin. API — третий origin; в разработке обычно http://localhost:8000. В production справочник живёт на своём хосте (AI_STP_DOCS_HOST), а /docs на хосте API остаётся для OpenAPI.

Подпись шапки Документация — внешний docsHref. Он всегда указывает на AI_STP_USER_DOCS_URL, никогда на /{locale}/docs и никогда на API. Переключатель Human / Machine эту ссылку не переписывает: внешние цели остаются внешними.

Справочник может читать кто угодно. Гейта сессии нет. Поиск локален для сборки MkDocs или для поля поиска документации на сайте.

Для чего этот экран

Справочник нужен, чтобы выучить продуктовый путь: установить CLI, прочитать карточку каталога, понять оси доверия, восстановиться после отказа.

/{locale}/docs нужен, когда вы уже на сайте и хотите те же статьи, не покидая origin. Исходные файлы те же. Оболочка — шапка, подвал и переключатель проекций сайта.

{API host}/docs нужен, только когда вы реализуете или отлаживаете HTTP API. Он не написан для человека, выбирающего сетап.

Эта страница не:

  • генерирует OpenAPI;
  • импортирует ADR или specs/active/ в публичное дерево;
  • позволяет править Markdown в браузере;
  • заменяет ai-stp help --agent --json как парсер команд.

Внутренняя инженерная документация остаётся в docs/ репозитория. Публичные страницы ссылаются туда, только когда читателю нужен владелец правила.

Что на сайте MkDocs

Material for MkDocs, две языковые сборки.

Элемент Что делает
Поиск индексирует собранную языковую линию
Левая навигация Обзор, Быстрый старт (человек / ИИ-агент), Харнессы, Понятия, Каталог, CLI, Веб, Компоненты, Сетапы, Публикация, Доверие и безопасность, Диагностика
Языковой alternate Русский на /, English на /en/
Переключатель темы светлая / тёмная из prefers-color-scheme
Ссылка править GitHub edit/main/docs-user-facing/docs/{locale}/…

Русский собирается в корень сайта. Английский — в /en/. Обратный порядок стёр бы английский на каждой русской сборке.

Глава Веб, в которой вы находитесь, — карта сайта, не CLI. Страницы CLI живут в CLI.

Что на /{locale}/docs

Сайт загружает docs-user-facing/docs/**/*.md через Fumadocs. /{locale}/docs — индекс этой locale. Вложенные slug следуют дереву каталогов: /{locale}/docs/web/catalog — страница каталога этой главы.

Элемент Что делает
Поиск по документации фильтрует заголовки в этой locale
Разделы документации вложенное дерево из .pages, та же структура, что у MkDocs
Тело статьи заголовок, описание, отрендеренный Markdown

Отсутствующий slug даёт 404. Флага draft на страницах справки нет: если файл в дереве, он отдаётся. Черновики хаба материалов — другое хранилище; см. Материалы.

Machine /{locale}/ai/docs/… — та же статья как Markdown. Это всё ещё не OpenAPI.

Три /docs рядом

Вопрос MkDocs :8011 Сайт /{locale}/docs API /docs
Источник docs-user-facing/docs/ те же файлы сгенерированный OpenAPI
Locale отдельные сборки префикс [locale] не locale справки
Оболочка Material шапка сайта Swagger / ReDoc
Документация в шапке этот хост не эта цель не эта цель
Human / Machine нет (только тема MkDocs) да нет
Говорит, как установить да да нет
Говорит HTTP-схему нет нет да

Закладку хоста MkDocs — для чтения. Закладку хоста API — для клиентов. Не предполагайте, что reverse proxy их схлопнул: путь API /docs зарезервирован и не является справочником (ADR-0078).

Соответствующие команды CLI

Команды ai-stp docs нет. Повседневное обнаружение:

ai-stp task intents --json

Expert: полный реестр этой установки:

ai-stp help --agent --json

Этот конверт всё равно продолжает на task intents. Флаги, схемы и next_actions не копируются в Markdown. Если страница справки и CLI расходятся, следуйте CLI.

Канонические веб-ссылки из оболочки:

ai-stp link web --json

link web печатает round-trippable URL сайта. Он не открывает MkDocs и не открывает OpenAPI.

Тупики

Что видно Что это значит Что делать
localhost:8011 отказал сервис compose документации не поднят поднимите его или используйте /{locale}/docs на сайте
/{locale}/docs/… 404 нет Markdown по этому slug откройте индекс документации или навигацию MkDocs
Документация в шапке уводит с сайта это внешний docsHref ожидаемо
Swagger UI на /docs хоста API вы открыли OpenAPI идите на :8011 или /{locale}/docs за how-to
Английского нет на :8011/ вы на русском корне откройте :8011/en/
Поиск не находит флаг CLI страницы справки — не парсер запустите ai-stp task intents --json
Правка на GitHub даёт 404 вы не на main или нет доступа читайте собранную страницу; не вставляйте секреты в PR

Self-hosted сайты всё равно компилируют этот Markdown. Они могут направить AI_STP_USER_DOCS_URL на внутренний хост. Путь OpenAPI API с этой настройкой не переезжает.

Связанные страницы

Источник истины

Публичные how-to живут в docs-user-facing/docs/. Архитектура и требования — в docs/ и specs/active/. Бинарник CLI владеет флагами. OpenAPI владеет HTTP. Четыре владельца, четыре места.