# Руководство пользователя LLM Kanban

---

## Аннотация

Настоящий документ является руководством пользователя информационной системы **LLM Kanban** — веб-приложения для управления задачами, выполняемыми большими языковыми моделями (LLM), по принципу канбан-доски.

Документ предназначен для операторов, ревьюеров и администраторов системы, использующих её для постановки задач LLM-агентам, контроля их выполнения, ревью результатов и учёта стоимости вычислений.

В руководстве описаны область применения, условия эксплуатации, порядок установки и запуска клиентской части, основные пользовательские операции, типовые аварийные ситуации и способы их устранения.

---

# Содержание

- [Руководство пользователя LLM Kanban](#руководство-пользователя-llm-kanban)
  - [Аннотация](#аннотация)
- [Содержание](#содержание)
- [1 Введение](#1-введение)
  - [1.1 Область применения](#11-область-применения)
  - [1.2 Краткое описание возможностей](#12-краткое-описание-возможностей)
  - [1.3 Уровень подготовки пользователя](#13-уровень-подготовки-пользователя)
  - [1.4 Перечень эксплуатационной документации](#14-перечень-эксплуатационной-документации)
- [2 Назначение и условия применения](#2-назначение-и-условия-применения)
  - [2.1 Назначение системы](#21-назначение-системы)
  - [2.2 Условия применения](#22-условия-применения)
  - [2.3 Минимальные требования](#23-минимальные-требования)
- [3 Подготовка к работе](#3-подготовка-к-работе)
  - [3.1 Состав и содержание дистрибутива](#31-состав-и-содержание-дистрибутива)
  - [3.2 Запуск программы](#32-запуск-программы)
  - [3.3 Проверка работоспособности](#33-проверка-работоспособности)
- [4 Описание операций](#4-описание-операций)
  - [4.1 Авторизация пользователя](#41-авторизация-пользователя)
  - [4.2 Просмотр канбан-доски](#42-просмотр-канбан-доски)
  - [4.3 Создание задачи](#43-создание-задачи)
  - [4.4 Назначение LLM-агента](#44-назначение-llm-агента)
  - [4.5 Запуск задачи на выполнение](#45-запуск-задачи-на-выполнение)
  - [4.6 Перемещение задачи между колонками](#46-перемещение-задачи-между-колонками)
  - [4.7 Ревью результата](#47-ревью-результата)
  - [4.8 Просмотр истории выполнения](#48-просмотр-истории-выполнения)
  - [4.9 Управление LLM-агентами](#49-управление-llm-агентами)
  - [4.10 Управление пользователями](#410-управление-пользователями)
  - [4.11 Просмотр учёта стоимости](#411-просмотр-учёта-стоимости)
  - [4.12 Выход из системы](#412-выход-из-системы)
- [5 Аварийные ситуации](#5-аварийные-ситуации)
- [6 Рекомендации по освоению](#6-рекомендации-по-освоению)
- [7 Термины и сокращения](#7-термины-и-сокращения)
- [8 Контакты](#8-контакты)
- [Лист регистрации изменений](#лист-регистрации-изменений)

---

# 1 Введение

## 1.1 Область применения

Система **LLM Kanban** применяется в организациях, использующих большие языковые модели (LLM) от внешних провайдеров (Anthropic, OpenAI, Google) для автоматизации интеллектуальной обработки текстовых задач: подготовки документов, анализа данных, генерации кода, перевода, реферирования и других подобных операций.

Система обеспечивает:

- централизованную постановку задач LLM-агентам;
- визуальное отслеживание состояния задач на канбан-доске;
- управление учётными записями LLM-провайдеров;
- ревью полученных результатов с возможностью повторного запуска;
- ведение журнала аудита всех действий пользователей;
- учёт стоимости выполненных запросов.

Типичные сценарии использования:

- постановка оператором задачи на генерацию текста, переводимая агентом Claude или GPT-5;
- ревью полученного ответа специалистом-ревьюером;
- администрирование набора подключённых моделей и их тарифов;
- анализ совокупных расходов на LLM за отчётный период.

## 1.2 Краткое описание возможностей

Система LLM Kanban предоставляет следующие возможности:

- создание, редактирование и удаление задач;
- визуальное представление задач в виде канбан-доски с колонками `Backlog`, `In Prompt`, `Processing`, `Review`, `Done`, `Failed`;
- перемещение задач между колонками методом drag-and-drop;
- выбор LLM-агента из списка подключённых;
- автоматическая постановка задачи в очередь выполнения через брокер Redis;
- получение и сохранение ответа LLM-провайдера;
- ревью и утверждение или отклонение результата;
- автоматический возврат задачи в `Backlog` при отклонении;
- ведение журнала аудита (`audit_log`) с фиксацией каждого изменения;
- учёт стоимости каждого запроса в журнале `cost_ledger`;
- управление пользователями и их ролями (доступно администратору);
- управление LLM-агентами: добавление, отключение, изменение тарифа (доступно администратору);
- разграничение доступа к данным средствами Row Level Security (RLS) PostgreSQL.

## 1.3 Уровень подготовки пользователя

Пользователь должен обладать:

- базовыми навыками работы с персональным компьютером;
- базовыми навыками работы с веб-браузером;
- общим пониманием принципов работы канбан-методологии;
- общим пониманием принципов работы LLM (формулирование промптов, ограничения по числу токенов).

Для администраторов дополнительно требуется:

- понимание разграничения ролей в информационных системах;
- знание принципов учёта стоимости вычислений на основе токенов.

## 1.4 Перечень эксплуатационной документации

При эксплуатации системы рекомендуется использовать документы, перечисленные в таблице 1.

Таблица 1 – Перечень эксплуатационной документации

| Документ | Назначение |
|:---------|:-----------|
| Руководство пользователя | Полное описание работы с системой LLM Kanban (настоящий документ) |
| Руководство администратора | Описание установки и конфигурирования серверной части |
| Руководство программиста | Описание GraphQL-схемы API и интеграции внешних сервисов |
| Описание архитектуры | Описание программно-аппаратной архитектуры по ГОСТ Р 57100-2025 |

---

# 2 Назначение и условия применения

## 2.1 Назначение системы

Система LLM Kanban предназначена для автоматизации процессов оркестрации задач, выполняемых большими языковыми моделями, и для контроля их выполнения по принципу канбан-доски.

Основные задачи системы:

- централизованная постановка и хранение задач LLM;
- автоматический подбор и вызов LLM-агента по заданным критериям;
- визуальный контроль состояния задач;
- ревью и утверждение результатов уполномоченным сотрудником;
- ведение полного журнала аудита;
- учёт стоимости в разрезе пользователя, агента, отчётного периода.

## 2.2 Условия применения

Система предназначена для работы в режиме многопользовательского доступа через локальную сеть или сеть Интернет. Серверная часть размещается в защищённой подсети и доступна клиентам по протоколу HTTPS.

Для работы с системой пользователю необходимо:

- наличие учётной записи в системе с присвоенной ролью;
- стабильное подключение к сети с пропускной способностью не ниже 1 Мбит/с;
- современный веб-браузер, поддерживающий стандарт ECMAScript 2022 и протокол WebSocket.

## 2.3 Минимальные требования

Минимальные требования к рабочему месту пользователя приведены в таблице 2.

Таблица 2 – Минимальные требования к рабочему месту пользователя

| Компонент | Требования |
|:----------|:-----------|
| Операционная система | Windows 10, macOS 12, Ubuntu 22.04 и выше |
| Оперативная память | От 4 ГБ |
| Свободное место на диске | От 200 МБ |
| Браузер | Chrome 120+, Firefox 120+, Edge 120+, Safari 17+ |
| Разрешение экрана | От 1366×768 пикселей |
| Подключение к сети | От 1 Мбит/с |

Минимальные требования к серверной части приведены в руководстве администратора.

---

# 3 Подготовка к работе

## 3.1 Состав и содержание дистрибутива

Клиентская часть системы является веб-приложением и не требует установки на рабочее место пользователя. Доступ осуществляется через веб-браузер по адресу, предоставленному администратором (например, `https://llm-kanban.example.org`).

Серверная часть распространяется в виде Docker-контейнеров и устанавливается администратором согласно руководству администратора.

## 3.2 Запуск программы

Для запуска клиентской части пользователю необходимо:

1. Открыть веб-браузер.
2. В адресной строке ввести URL системы, предоставленный администратором.
3. Дождаться загрузки экрана авторизации.

После загрузки на экране отображается форма входа, как показано на рисунке 1.

*Рисунок 1 – Экран авторизации*

## 3.3 Проверка работоспособности

Для проверки корректной работы системы необходимо последовательно выполнить операции, приведённые в таблице 3.

Таблица 3 – Проверка работоспособности

| № | Действие | Ожидаемый результат |
|:-:|:---------|:--------------------|
| 1 | Открыть URL системы | Отображается экран авторизации |
| 2 | Ввести корректные учётные данные и нажать «Войти» | Выполняется переход на канбан-доску |
| 3 | Открыть колонку `Backlog` | Список задач загружается без ошибок |
| 4 | Открыть раздел «Агенты» | Отображается список подключённых LLM-агентов |
| 5 | Выйти из системы | Выполняется возврат на экран авторизации |

Если на любом из шагов возникла ошибка, следует обратиться к разделу [5 Аварийные ситуации](#5-аварийные-ситуации).

---

# 4 Описание операций

## 4.1 Авторизация пользователя

При обращении к системе отображается экран авторизации.

Для входа в систему необходимо:

1. Ввести адрес электронной почты в поле «Email».
2. Ввести пароль в поле «Пароль».
3. Нажать кнопку **«Войти»**.

При успешной авторизации выполняется следующее:

- система генерирует JWT-токен доступа сроком действия 1 час;
- токен сохраняется в защищённом хранилище браузера;
- одновременно создаётся сессия в Redis с ключом вида `session:{token}` и временем жизни 3600 секунд;
- выполняется переход на канбан-доску;
- в журнал `audit_log` записывается событие входа.

Если данные введены неверно, отображается сообщение:

> Неверный email или пароль

При повторном открытии системы в том же браузере вход выполняется автоматически, пока действителен сохранённый токен.

Внешний вид экрана авторизации представлен на рисунке 1.

*Рисунок 1 – Экран авторизации*

## 4.2 Просмотр канбан-доски

После авторизации пользователь попадает на главный экран — канбан-доску.

Доска содержит шесть колонок:

а) `Backlog` — новые и отклонённые задачи, ожидающие назначения;

б) `In Prompt` — задачи с назначенным агентом, ожидающие запуска;

в) `Processing` — задачи, обрабатываемые LLM-агентом в настоящий момент;

г) `Review` — задачи с полученным ответом, ожидающие ревью;

д) `Done` — задачи, ревью которых завершено успешно;

е) `Failed` — задачи, выполнение которых завершилось ошибкой.

Каждая задача представлена карточкой с краткой информацией:

- идентификатор задачи;
- заголовок промпта (первые 80 символов);
- приоритет (`low`, `medium`, `high`);
- имя назначенного агента (если назначен);
- автор задачи.

Состав отображаемых задач зависит от роли пользователя и определяется политикой Row Level Security:

- оператор видит только свои задачи;
- ревьюер дополнительно видит задачи в статусе `Review`;
- администратор видит все задачи.

Общий вид канбан-доски представлен на рисунке 2.

*Рисунок 2 – Главный экран. Канбан-доска*

## 4.3 Создание задачи

Для создания новой задачи необходимо нажать кнопку **«Создать задачу»** в верхней части канбан-доски. После нажатия открывается форма создания задачи.

Пользователь должен заполнить поля, перечисленные в таблице 4.

Таблица 4 – Поля формы создания задачи

| Поле | Обязательность | Описание |
|:-----|:---------------|:---------|
| Промпт | Обязательное | Текст задачи для LLM-агента, до 16 000 символов |
| Приоритет | Обязательное | Одно из значений: `low`, `medium`, `high` |
| Агент | Необязательное | LLM-агент из списка подключённых |
| Контекстные файлы | Необязательное | Прикрепляемые файлы формата PDF, TXT, MD общим объёмом до 10 МБ |

После заполнения формы необходимо нажать кнопку **«Сохранить»**. Для отмены операции используется кнопка **«Отмена»**.

При успешном сохранении выполняется следующее:

- в таблицу `tasks` PostgreSQL вставляется новая запись со статусом `backlog`;
- в журнал `audit_log` записывается событие создания;
- прикреплённые файлы сохраняются в MongoDB-коллекции `task_artifacts`;
- карточка задачи появляется в колонке `Backlog`.

Если агент при создании не выбран, задача остаётся в `Backlog` до его назначения. Если агент выбран, задача автоматически переводится в колонку `In Prompt`.

## 4.4 Назначение LLM-агента

Для назначения агента задаче в колонке `Backlog` необходимо:

1. Открыть карточку задачи нажатием на неё.
2. В поле «Агент» выбрать одно из значений выпадающего списка.
3. Нажать кнопку **«Сохранить»**.

При выборе агента отображается информация:

- название модели;
- лимит токенов на запрос;
- стоимость 1000 входных и 1000 выходных токенов;
- провайдер (Anthropic, OpenAI или Google).

После сохранения задача автоматически перемещается в колонку `In Prompt`.

## 4.5 Запуск задачи на выполнение

Для запуска задачи на выполнение LLM-агентом необходимо:

1. Открыть карточку задачи в колонке `In Prompt`.
2. Нажать кнопку **«Запустить»**.

После нажатия выполняется следующая последовательность действий:

1. Карточка задачи перемещается в колонку `Processing`.
2. В очередь Redis `queue:llm-calls` добавляется команда на вызов LLM-провайдера.
3. Worker-процесс извлекает команду из очереди и обращается к API провайдера.
4. По завершении запроса ответ сохраняется в `task_artifacts` MongoDB.
5. В журнал `cost_ledger` записывается стоимость, рассчитанная по числу входных и выходных токенов.
6. Карточка автоматически перемещается в колонку `Review`.

В случае ошибки выполнения карточка перемещается в колонку `Failed`, а в журнал `audit_log` записывается причина отказа.

Прогресс выполнения отображается в реальном времени средствами GraphQL Subscriptions через канал `events:tasks`.

## 4.6 Перемещение задачи между колонками

Перемещение задач между колонками выполняется методом drag-and-drop. Допустимые переходы между статусами определяются конечным автоматом, представленным на рисунке 3.

*Рисунок 3 – Диаграмма состояний задачи*

Допустимые ручные переходы приведены в таблице 5.

Таблица 5 – Допустимые ручные переходы между колонками

| Из колонки | В колонку | Условие | Доступно роли |
|:-----------|:----------|:--------|:--------------|
| Backlog | In Prompt | Назначен агент | Оператор, Администратор |
| In Prompt | Backlog | — | Оператор, Администратор |
| Review | Done | Ответ утверждён | Ревьюер, Администратор |
| Review | Backlog | Ответ отклонён | Ревьюер, Администратор |
| Failed | Backlog | Повторная попытка | Оператор, Администратор |

Прочие переходы выполняются автоматически и через интерфейс drag-and-drop недоступны.

## 4.7 Ревью результата

Задачи в колонке `Review` доступны для проверки пользователям с ролью «ревьюер» или «администратор».

Для проведения ревью необходимо:

1. Открыть карточку задачи в колонке `Review`.
2. Ознакомиться с исходным промптом, контекстными файлами и ответом LLM-агента.
3. Нажать кнопку **«Утвердить»** или **«Отклонить»**.

При нажатии **«Утвердить»**:

- статус задачи изменяется на `done`;
- карточка перемещается в колонку `Done`;
- в журнал `audit_log` записывается событие утверждения.

При нажатии **«Отклонить»**:

- открывается диалоговое окно с полем «Причина отклонения»;
- после ввода причины и подтверждения статус задачи изменяется на `backlog`;
- карточка перемещается в колонку `Backlog`;
- значение поля `retry_count` задачи увеличивается на единицу;
- в журнал `audit_log` записывается событие отклонения с указанной причиной.

## 4.8 Просмотр истории выполнения

Для просмотра истории действий по задаче необходимо:

1. Открыть карточку задачи.
2. Перейти на вкладку **«История»**.

На вкладке отображается хронологический список событий из коллекции `task_events` MongoDB. Для каждого события указаны:

- дата и время;
- тип события (`created`, `assigned`, `started`, `completed`, `approved`, `rejected`, `failed`);
- автор события;
- дополнительные данные в формате JSON.

История доступна для просмотра в рамках прав, определённых политикой RLS.

## 4.9 Управление LLM-агентами

Раздел **«Агенты»** доступен только пользователям с ролью «администратор».

В разделе отображается список подключённых LLM-агентов. Для каждого агента указаны:

- провайдер;
- название модели;
- лимит токенов;
- стоимость 1000 входных и 1000 выходных токенов;
- статус активности.

Доступные операции:

а) **Добавление агента** — нажатием кнопки **«Добавить агент»** открывается форма ввода параметров нового агента, включая API-ключ. Ключ сохраняется в зашифрованном виде в поле `encrypted_api_key`;

б) **Редактирование агента** — нажатием на строку агента открывается форма редактирования параметров;

в) **Отключение агента** — переключателем «Активен» агент переводится в неактивное состояние. Неактивные агенты недоступны для выбора при создании задач, но связанные с ними записи `cost_ledger` сохраняются;

г) **Удаление агента** — недоступно из соображений целостности учётных данных. Используется отключение.

## 4.10 Управление пользователями

Раздел **«Пользователи»** доступен только пользователям с ролью «администратор».

В разделе отображается список зарегистрированных пользователей. Для каждого указаны:

- идентификатор;
- email;
- ФИО;
- роль (`operator`, `reviewer`, `admin`);
- статус активности.

Доступные операции:

а) **Добавление пользователя** — заполнение формы с указанием email, ФИО, роли и начального пароля. Пароль сохраняется в виде хеша Argon2;

б) **Изменение роли** — выбор нового значения роли из выпадающего списка;

в) **Блокировка пользователя** — переключение поля `is_active` в значение «ложь». Заблокированный пользователь не может авторизоваться, но его задачи и записи `audit_log` сохраняются;

г) **Сброс пароля** — генерация нового временного пароля, отображаемого администратору один раз.

## 4.11 Просмотр учёта стоимости

Раздел **«Учёт стоимости»** доступен пользователям с ролью «ревьюер» или «администратор».

В разделе отображается таблица записей `cost_ledger`. Для каждой записи указаны:

- идентификатор задачи;
- агент;
- число входных и выходных токенов;
- стоимость в условных единицах;
- отчётный период.

Доступные операции:

а) фильтрация по агенту, пользователю, периоду;

б) группировка по агенту, пользователю или периоду с подсчётом суммы;

в) экспорт результатов в формат CSV.

## 4.12 Выход из системы

Для выхода из системы необходимо:

1. Нажать на имя пользователя в правом верхнем углу.
2. В открывшемся меню выбрать пункт **«Выйти»**.

При выходе выполняется следующее:

- JWT-токен удаляется из хранилища браузера;
- ключ `session:{token}` удаляется из Redis;
- в журнал `audit_log` записывается событие выхода;
- выполняется переход на экран авторизации.

---

# 5 Аварийные ситуации

Типовые аварийные ситуации и рекомендации по их устранению приведены в таблице 6.

Таблица 6 – Аварийные ситуации

| Сообщение или симптом | Возможная причина | Рекомендация |
|:----------------------|:------------------|:-------------|
| «Неверный email или пароль» | Опечатка во вводе либо учётная запись заблокирована | Проверить раскладку клавиатуры, обратиться к администратору |
| «Срок действия сессии истёк» | Истёк срок действия JWT-токена (1 ч) | Повторно выполнить вход в систему |
| «Доступ запрещён» | У роли нет прав на запрошенное действие | Обратиться к администратору для уточнения прав |
| «Превышен лимит запросов» | Превышен лимит rate-limit для пользователя или агента | Подождать восстановления квоты согласно политике (60/120/300 запросов в минуту) |
| «Ошибка обращения к LLM-провайдеру» | Внешний API недоступен или ключ недействителен | Сообщить администратору; задача переводится в `Failed` |
| «Задача превысила лимит токенов» | Размер промпта или ожидаемого ответа превышает `token_limit` агента | Уменьшить размер промпта или выбрать агента с большим лимитом |
| Канбан-доска не загружается | Отсутствует подключение к серверу | Проверить соединение с сетью; обновить страницу |
| Карточка не перемещается между колонками | Запрещённый переход согласно конечному автомату | См. таблицу 5 |
| Файл не загружается | Превышен размер 10 МБ либо неподдерживаемый формат | Использовать форматы PDF, TXT, MD; уменьшить размер |

При возникновении нештатной ситуации, не описанной в таблице 6, необходимо обратиться в службу технической поддержки (см. раздел [8 Контакты](#8-контакты)).

---

# 6 Рекомендации по освоению

Для эффективного освоения системы LLM Kanban рекомендуется:

- начать работу с тестовых задач с агентом наименьшей стоимости;
- формулировать промпты максимально конкретно, указывая желаемый формат ответа;
- использовать поле «Приоритет» для упорядочивания работы команды;
- регулярно отклонять некорректные результаты для повышения качества возможных доработок промпта;
- использовать раздел «Учёт стоимости» для контроля расходов;
- администраторам — отключать неиспользуемые агенты, чтобы не загромождать выпадающий список выбора;
- обращать внимание на значение `retry_count`: его рост может означать, что промпт сформулирован неудачно.

---

# 7 Термины и сокращения

Перечень применяемых терминов и сокращений приведён в таблице 7.

Таблица 7 – Термины и сокращения

| Термин | Значение |
|:-------|:---------|
| LLM | Large Language Model — большая языковая модель |
| API | Application Programming Interface — программный интерфейс приложения |
| JWT | JSON Web Token — стандарт защищённой передачи утверждений |
| RLS | Row Level Security — построчное разграничение доступа в PostgreSQL |
| CRUD | Create, Read, Update, Delete — операции создания, чтения, изменения и удаления |
| Worker | Серверный процесс, обрабатывающий очередь задач |
| Промпт | Текстовое задание, передаваемое LLM-агенту на вход |
| Токен | Минимальная единица обработки текста LLM, используемая для тарификации |
| Канбан | Метод визуального управления задачами с использованием доски и карточек |
| Drag-and-drop | Способ перемещения объекта интерфейса путём захвата мышью |
| Ревью | Проверка результата выполнения задачи уполномоченным пользователем |
| Backlog | Колонка канбан-доски с задачами, ожидающими назначения |

---

# 8 Контакты

Служба технической поддержки системы:

- электронная почта: `support@llm-kanban.example.org`;
- Telegram: `@llm_kanban_support`;
- репозиторий проекта: `https://gogs.itiscaf.ru/romanov_da/llm-kanban`.

Часы работы службы поддержки: с 09:00 до 18:00 по московскому времени, в рабочие дни.

---

# Лист регистрации изменений

| № | Дата | Раздел | Изменение | Автор |
|:-:|:-----|:-------|:----------|:------|
| 1 | 22.05.2026 | Все разделы | Создание документа | Романов Д. А. |