К содержимому

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

Где отдаётся справочник и как он связан с /docs на сайте.

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

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

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

ПоверхностьТипичный URLКому видноЧто это
Справочник MkDocshttp://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всем, кто достигает APISwagger UI для HTTP-контрактов
ReDoc API{API host}/redocвсем, кто достигает APIReDoc того же 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}/docsAPI /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 с этой настройкой не переезжает.

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

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