Использование ИИ-ассистента#

Основной сценарий#

  1. Пользователь скачивает из дистрибутива комплект документации в формате HTML.

  2. Пользователь размещает (копирует/распаковывает) документацию в директорию, заданную параметром doc_agent.docs_dir.

  3. Пользователь выполняет команду ingest для создания локального индекса.

  4. Пользователь ожидает успешного завершения индексации.

  5. Пользователь запускает команду ask для начала работы с ИИ-ассистентом.

  6. ИИ-ассистент запускается в режиме CLI-чата.

  7. Пользователь формулирует и отправляет запрос по содержимому документации.

  8. ИИ-ассистент отображает пользователю релевантный ответ.

Альтернативный сценарий#

Альтернативный сценарий не предусмотрен.

Исключительный сценарий: Ошибки в конфигурационных параметрах#

8а. ИИ-ассистент получает ошибку от LLM-провайдера.
9а. ИИ-ассистент отображает пользователю сообщение об ошибке конфигурации на основе ответа от LLM-провайдера.

Исключительный сценарий: LLM-провайдер недоступен#

8b. ИИ-ассистент фиксирует ошибку — LLM-провайдер недоступен (timeout / 5xx).
9b. ИИ-ассистент информирует пользователя о недоступности LLM-провайдера.

Исключительный сценарий: Отсутствие файла конфигурации ai-doc.json#

8c. ИИ-ассистент не находит конфигурационный файл ai-doc.json ни в одном из предопределённых мест.
9c. ИИ-ассистент отображает пользователю сообщение об ошибке и список возможных местоположений.
10c. ИИ-ассистент предлагает пользователю указать путь вручную через флаг --config.

Исключительный сценарий: Отсутствие поддерживаемых файлов документации#

8d. ИИ-ассистент при индексировании не находит файлов с поддерживаемыми расширениями (.md, .txt, .html).
9d. ИИ-ассистент отображает сообщение: No supported files found.
10d. ИИ-ассистент предлагает проверить doc_agent.docs_dir, права доступа и распаковку архива.

Исключительный сценарий: Отсутствие индекса (не выполнена команда ingest)#

8e. Пользователь запускает ask, но локальный векторный индекс отсутствует.
9e. ИИ-ассистент отображает сообщение: Index not found. Run ingest first.
10e. ИИ-ассистент напоминает: индекс создаётся только после команды ingest.

Исключительный сценарий: Несовместимая версия Java#

8f. ИИ-ассистент обнаруживает UnsupportedClassVersionError при запуске.
9f. ИИ-ассистент отображает сообщение о требовании Java ≥17.
10f. ИИ-ассистент предлагает проверить java -version и установить JAVA_HOME.

Исключительный сценарий: Тайм-аут или задержка LLM-провайдера#

8g. ИИ-ассистент получает timeout или 5xx от провайдера (например, GigaChat).
9g. ИИ-ассистент информирует пользователя о задержке и предлагает увеличить timeout_sec.
10g. ИИ-ассистент приводит пример правки конфигурации:

{
  "provider": "gigachat",
  "gigachat": {
    "timeout_sec": 90
  }
}