@besales/mcp 0.1.0 → 0.12.0

package/dist/resources/docs/agent-behavior.md

@@ -0,0 +1,393 @@
+# 10. Поведение агента (`AgentBehavior`)
+
+> **Источник правды:** `ai-aniomaly/docs/ai-prompt-builder/10-agent-behavior.md` — копия для MCP doc-bridge (v1.5 Increment 6b). Синкать при изменении оригинала.
+>
+> ⚠️ **MCP-контекст:** это доменная справка, написанная для людей/админ-UI. В MCP-сессии ты выполняешь те же операции **через besales_* tools**, а не через UI (drag-n-drop, клики в админке). Где текст ниже говорит «клиент/админ делает X через UI» — это «что должно получиться»; механику бери из tool (напр. загрузка файла → `besales_file_upload_request`; документ в knowledge → `besales_knowledge_document_upload`; сайт → `besales_knowledge_website_add`) + из workflow-ресурсов. Внутренние ссылки `[NN-name.md]` — относительные пути исходной доки, через MCP НЕ резолвятся: ищи `besales://docs/<slug>` или concept-resource.
+
+## 1. Назначение
+
+`AgentBehavior` — это контейнер настроек, которые применяются **на уровне платформы** и влияют на всех её агентов. Он управляет:
+- Задержками перед ответом (имитация естественной коммуникации).
+- Скоростью «набора» сообщения.
+- Стратегией обработки медиа (картинки, видео, документы, аудио, ссылки).
+- Расписанием доступности оператора.
+- Фильтрами текста и приветственными кнопками.
+- Поведением при ошибках LLM.
+
+Один `AgentBehavior` на `(workspaceId, platformId)`. AI-сервис создаёт его при настройке платформы.
+
+## 2. JSON-схема (полная)
+
+```json
+{
+  "id": "uuid",
+  "platformId": "<platformId>",
+  "workspaceId": "<workspaceId>",
+
+  "waitingAnswerTime": 10,
+  "messageOpenDelay": 0,
+  "fakeDelay": 0,
+  "typingSpeed": "fast",
+
+  "canInterrupt": false,
+  "messageDevide": false,
+  "messageChunkSeparator": "",
+
+  "botGreeting": "Привет! Чем могу помочь?",
+  "greetingFileId": null,
+  "greetingButtons": [],
+  "greetingButtonsKeyboardType": "INLINE",
+
+  "popupDelaySeconds": 0,
+
+  "messageFilters": [],
+
+  "operatorSchedule": null,
+  "operatorUnavailableMessage": null,
+  "botWaitingReturn": 3,
+  "followUpWaitingReturn": -1,
+
+  "imageHandlingBehavior": "SILENT",
+  "imageFixedResponseText": null,
+  "shouldCallOperatorWithImage": true,
+  "imageOperatorComment": null,
+
+  "videoHandlingBehavior": "SILENT",
+  "videoFixedResponseText": null,
+  "shouldCallOperatorWithVideo": true,
+  "videoOperatorComment": null,
+
+  "documentHandlingBehavior": "SILENT",
+  "documentFixedResponseText": null,
+  "shouldCallOperatorWithDocument": true,
+  "documentOperatorComment": null,
+
+  "audioHandlingBehavior": "SILENT",
+  "audioFixedResponseText": null,
+  "shouldCallOperatorWithAudio": true,
+  "audioOperatorComment": null,
+
+  "urlHandlingBehavior": "PASS_THROUGH",
+  "urlFixedResponseText": null,
+  "shouldCallOperatorWithUrl": false,
+  "urlOperatorComment": null,
+
+  "aiErrorHandlingBehavior": "SILENT",
+  "aiErrorCustomMessage": null,
+  "shouldCallOperatorWithError": false,
+  "aiErrorTargetStageId": null,
+
+  "skipTaskCreationOnCallOperator": false,
+  "anonymizationEnabled": false,
+  "anonymizationDisabledTypes": [],
+
+  "goOffline": "0"
+}
+```
+
+## 3. Задержки и скорость
+
+| Поле | Единицы | Дефолт | Описание |
+|---|---|---|---|
+| `waitingAnswerTime` | секунды | 10 | Сколько ждать перед запуском LLM. Помогает дождаться нескольких сообщений подряд (если пользователь пишет очередью). 0–300. |
+| `messageOpenDelay` | секунды | 0 | Только для **Telegram Personal**: пауза после отметки «прочитано» до начала имитации набора. 0–60. |
+| `fakeDelay` | секунды | 0 | Дополнительная задержка-обманка перед отправкой ответа. 0–60. |
+| `typingSpeed` | enum | `fast` | Скорость имитации набора: `fast` / `middle` / `slow`. |
+| `canInterrupt` | bool | false | Можно ли прерывать генерацию при новом сообщении пользователя. |
+
+### Эффективная задержка ответа
+
+Для Telegram Personal: `waitingAnswerTime` + `messageOpenDelay` + (время LLM-генерации) + `fakeDelay` + (имитация набора по `typingSpeed`).
+
+Для остальных платформ: `waitingAnswerTime` + (время LLM-генерации) + `fakeDelay`.
+
+## 4. Разделение и форматирование сообщения
+
+| Поле | Дефолт | Описание |
+|---|---|---|
+| `messageDevide` | false | Если `true` — длинный ответ агента разделяется на чанки по `messageChunkSeparator`. |
+| `messageChunkSeparator` | `""` | Разделитель чанков (например, `%%%`). LLM кладёт его в ответ, бэк разбивает по нему. |
+
+### Пример
+
+`messageDevide=true`, `messageChunkSeparator="%%%"`. LLM сгенерировал:
+
+```
+Здравствуйте, Иван!%%%Конечно, помогу с заказом.%%%Какой товар вас интересует?
+```
+
+Будет отправлено 3 отдельных сообщения.
+
+## 5. Фильтры текста (`messageFilters`)
+
+Замены, применяемые к **исходящим сообщениям** перед отправкой:
+
+```json
+"messageFilters": [
+  {
+    "id": "uuid",
+    "source": "магазин",
+    "target": "наш магазин",
+    "enabled": true,
+    "order": 1
+  },
+  {
+    "id": "uuid",
+    "source": "https://(.+)\\.example\\.com",
+    "target": "https://$1.example.ru",
+    "enabled": true,
+    "order": 2
+  }
+]
+```
+
+| Поле | Описание |
+|---|---|
+| `source` | Текст или регэксп для поиска. |
+| `target` | На что заменить (можно использовать `$1`, `$2` для regex-групп). |
+| `enabled` | Можно отключить без удаления. |
+| `order` | Порядок применения. |
+
+**Лимит:** до **20** правил.
+
+**Зачем:** убрать упоминания внутренней терминологии, заменить домены, нормализовать тон.
+
+## 6. Приветственные кнопки (`greetingButtons`)
+
+> **MCP-операторам:** по умолчанию приветствие — **без кнопок** (живой текст `botGreeting`). `greetingButtons` — opt-in: добавляй ТОЛЬКО по явному запросу пользователя (кнопки дают menu-feel, противоречат принципу «звучит как человек»). На создании агента ставится только `bot_greeting`; остальной behavior — позже.
+
+Кнопки, которые отправляются **с приветственным сообщением** (`botGreeting` или `greetingFileId`):
+
+```json
+"greetingButtons": [
+  { "id": "uuid", "label": "Каталог", "text": "Покажи каталог", "order": 1 },
+  { "id": "uuid", "label": "Доставка", "text": "Расскажи о доставке", "order": 2 },
+  { "id": "uuid", "label": "Оператор", "text": "Хочу оператора", "order": 3 }
+]
+```
+
+| Поле | Описание |
+|---|---|
+| `label` | Текст на кнопке (≤20 символов). |
+| `text` | Что отправляется при нажатии (для `REPLY` keyboard) или `callback_data` (для `INLINE`). |
+| `order` | Порядок. |
+
+**Лимит:** до **10** кнопок.
+
+`greetingButtonsKeyboardType` — `INLINE` (под сообщением) или `REPLY` (вместо клавиатуры). Поддерживается на: Telegram Bot, VK, Salebot, Wazzup, Instagram, WebWidget.
+
+`greetingFileId` — `StoredFile.id` для приветственного аудио/картинки/видео.
+
+`popupDelaySeconds` — для **Web Widget**: задержка показа popup-сообщения в свёрнутом виджете (0 = отключено).
+
+## 7. Расписание оператора
+
+```json
+"operatorSchedule": {
+  "enabled": true,
+  "availability": {
+    "monday":    { "active": true,  "startTime": "09:00", "endTime": "19:00" },
+    "tuesday":   { "active": true,  "startTime": "09:00", "endTime": "19:00" },
+    "wednesday": { "active": true,  "startTime": "09:00", "endTime": "19:00" },
+    "thursday":  { "active": true,  "startTime": "09:00", "endTime": "19:00" },
+    "friday":    { "active": true,  "startTime": "09:00", "endTime": "19:00" },
+    "saturday":  { "active": false, "startTime": null,    "endTime": null },
+    "sunday":    { "active": false, "startTime": null,    "endTime": null }
+  }
+},
+"operatorUnavailableMessage": "Сейчас оператор недоступен. Мы работаем по будням с {startTime} до {endTime}."
+```
+
+Если `enabled=true` и текущее время вне расписания — `call_operator` будет отвечать `operatorUnavailableMessage` (с подстановкой `{startTime}`/`{endTime}` из текущего дня).
+
+## 8. Возврат бота после оператора
+
+| Поле | Дефолт | Описание |
+|---|---|---|
+| `botWaitingReturn` | 3 | Сколько часов бот молчит после сообщения оператора. Допустимые: `0`, `1`, `3`, `6`, `12`, `24`. `0` = до команды `/start`. |
+| `followUpWaitingReturn` | -1 | На сколько часов отключить follow-up после оператора. `-1` = не отключать, `0` = навсегда, `1`–`24` — часы. |
+| `skipTaskCreationOnCallOperator` | false | Если `true` — при `call_operator` система **только** меняет ответственного на оператора, без постановки задачи в CRM. Полезно, когда workflow в CRM ведётся через статусы воронки, а не через task'ы, и лишние «висящие» задачи на оператора засоряют его список дел. |
+| `anonymizationEnabled` | false | Обратимая PII-анонимизация LLM-пайплайна (per-platform). Если `true` — реальные имя/телефон/email клиента вырезаются из сообщений перед отправкой в LLM (заменяются токенами) и подставляются обратно в ответе и в аргументах tool-call (например, поля CRM). Ставится через секцию `privacy: { anonymization_enabled }` в `besales_behavior_update`. |
+| `anonymizationDisabledTypes` | `[]` | Типы PII, выключенные из анонимизации (при `anonymizationEnabled=true` отдаются в LLM **реальными**). OFF-список: пусто = скрывать всё. Имя дробится на части — исключив `FIRST_NAME`, отдаёшь реальное имя в LLM, и модель склоняет его в нужный падеж сама. Значения: `FIRST_NAME`/`LAST_NAME`/`PATRONYMIC`/`PERSON`/`PHONE`/`EMAIL`/`INN`/`PASSPORT`/`CARD`/`DATE_OF_BIRTH`/`ACCOUNT`/`SNILS`/`OGRN`/`OGRNIP`/`SOCIAL_ID` (СНИЛС/ОГРН/ОГРНИП — по контрольной сумме; SOCIAL_ID — VK/Telegram/Max @-хэндлы и ссылки на профиль). Ставится через `privacy: { anonymization_disabled_types }`. ⚠️ Выключение типа — осознанная передача данных провайдеру модели. |
+
+## 9. Обработка медиа от пользователя
+
+Для каждого типа медиа задаётся:
+- **`*HandlingBehavior`** — что делать с медиа.
+- **`*FixedResponseText`** — текст для `FIXED_RESPONSE` режима.
+- **`shouldCallOperatorWith*`** — вызывать ли оператора при получении.
+- **`*OperatorComment`** — комментарий для оператора.
+
+### Изображения (`ImageHandlingBehavior`)
+
+```json
+{
+  "imageHandlingBehavior": "PROCESS_WITH_LLM",
+  "imageFixedResponseText": null,
+  "shouldCallOperatorWithImage": false,
+  "imageOperatorComment": null
+}
+```
+
+| Значение | Что делает |
+|---|---|
+| `SILENT` | Промолчать (default). |
+| `PROCESS_WITH_LLM` | Запустить vision-модель (gpt-4.1-mini) и интерпретировать изображение в текст для LLM. |
+| `FIXED_RESPONSE` | Отправить фиксированный текст из `imageFixedResponseText`. |
+
+`PROCESS_WITH_LLM` доступен **только** для изображений. Для видео/документов/аудио — только `SILENT` или `FIXED_RESPONSE`.
+
+### Видео / Документы / Аудио (`VideoHandlingBehavior`, `DocumentHandlingBehavior`, `AudioHandlingBehavior`)
+
+Все три enum'а имеют одинаковый набор значений:
+
+| Значение | Что делает |
+|---|---|
+| `SILENT` | Промолчать (default). |
+| `FIXED_RESPONSE` | Отправить фиксированный текст из соответствующего `*FixedResponseText`. |
+
+```json
+{
+  "videoHandlingBehavior": "FIXED_RESPONSE",
+  "videoFixedResponseText": "Извините, я пока не умею смотреть видео. Опишите, пожалуйста, словами.",
+  "shouldCallOperatorWithVideo": true,
+  "videoOperatorComment": "Клиент прислал видео — нужно посмотреть."
+}
+```
+
+### Голосовые сообщения (Whisper-транскрипция)
+
+⚠️ **Голос ≠ аудиофайл.** `AudioHandlingBehavior` (выше) применяется только к **аудиофайлам** (`.mp3 / .m4a / .wav / .aac / ...`). **Голосовые сообщения** (Telegram `voice` / `video_note`; на остальных платформах — медиа с расширением `.opus / .oga / .ogg / .webm`) обрабатываются отдельно: они **автоматически транскрибируются** через OpenAI Whisper, и распознанный текст уходит в LLM как обычное сообщение.
+
+- **Включено по умолчанию, без отдельного тумблера** в `AgentBehavior` — транскрипция голоса работает на всех **9 платформах** (Telegram, TelegramPersonal, Instagram, Avito, VKon, Wazzup, Salebot, Bitrix24Bot, GetCourse). Разделение voice/audio — по расширению файла (утилита `inferAudioKindFromUrl`).
+- **Лимит размера — 20 MB** (`MAX_TRANSCRIBE_FILE_SIZE_BYTES`, с запасом ниже 25 MB-лимита Whisper). Файл больше → транскрипция не делается, в LLM уходит плейсхолдер `[Файл слишком большой для транскрибации (XMB > 20MB)]`.
+- Если речь не распознана → `[Речь не распознана]`. Стоимость расшифровки пишется в AI-леджер как операция `WHISPER_TRANSCRIPTION` (модель `whisper-1`).
+- Язык можно подсказать Whisper (ISO 639-1) — обычно совпадает с языком агента.
+
+> То есть `audioHandlingBehavior: SILENT` заглушит только присланные **аудиофайлы**; голосовые всё равно будут расшифрованы и обработаны LLM. Полное описание пайплайна — в [`docs/modules/transcription.md`](../modules/transcription.md).
+
+### Ссылки
+
+```json
+{
+  "urlHandlingBehavior": "PROCESS_WITH_CRAWLER",
+  "urlFixedResponseText": null,
+  "shouldCallOperatorWithUrl": false,
+  "urlOperatorComment": null
+}
+```
+
+| `urlHandlingBehavior` | Что делает |
+|---|---|
+| `PASS_THROUGH` | Передать ссылку как есть в LLM (default). |
+| `SILENT` | Игнорировать. |
+| `FIXED_RESPONSE` | Отправить фиксированный текст. |
+| `PROCESS_WITH_CRAWLER` | Скачать страницу через web-crawler и положить контент в контекст LLM. |
+
+## 10. Обработка ошибок LLM
+
+```json
+{
+  "aiErrorHandlingBehavior": "SEND_ERROR_MESSAGE",
+  "aiErrorCustomMessage": "Прошу прощения, у меня сейчас технические сложности. Передаю вас оператору.",
+  "shouldCallOperatorWithError": true,
+  "aiErrorTargetStageId": 999
+}
+```
+
+| Поле | Описание |
+|---|---|
+| `aiErrorHandlingBehavior` | `SILENT` (default) или `SEND_ERROR_MESSAGE`. |
+| `aiErrorCustomMessage` | Текст для `SEND_ERROR_MESSAGE`. |
+| `shouldCallOperatorWithError` | Если `true` — автоматически вызывать оператора. |
+| `aiErrorTargetStageId` | Куда перевести лид при ошибке (`null` = на первый этап текущей воронки). |
+
+## 11. Inline-пример: типичная конфигурация для Telegram-бота
+
+```json
+{
+  "platformId": "<platformId>",
+  "workspaceId": "<workspaceId>",
+
+  "waitingAnswerTime": 15,
+  "fakeDelay": 3,
+  "typingSpeed": "middle",
+
+  "messageDevide": true,
+  "messageChunkSeparator": "%%%",
+
+  "botGreeting": "Здравствуйте! Я Анна, помогу с выбором цветов и оформлением заказа.",
+  "greetingButtons": [
+    { "label": "Каталог", "text": "Покажи каталог букетов", "order": 1 },
+    { "label": "Доставка", "text": "Расскажи про доставку", "order": 2 },
+    { "label": "Связаться с менеджером", "text": "Хочу с менеджером", "order": 3 }
+  ],
+  "greetingButtonsKeyboardType": "INLINE",
+
+  "messageFilters": [
+    { "source": "ChatGPT", "target": "наш ассистент", "enabled": true, "order": 1 }
+  ],
+
+  "operatorSchedule": {
+    "enabled": true,
+    "availability": {
+      "monday":    { "active": true, "startTime": "09:00", "endTime": "19:00" },
+      "tuesday":   { "active": true, "startTime": "09:00", "endTime": "19:00" },
+      "wednesday": { "active": true, "startTime": "09:00", "endTime": "19:00" },
+      "thursday":  { "active": true, "startTime": "09:00", "endTime": "19:00" },
+      "friday":    { "active": true, "startTime": "09:00", "endTime": "19:00" },
+      "saturday":  { "active": true, "startTime": "10:00", "endTime": "18:00" },
+      "sunday":    { "active": false, "startTime": null, "endTime": null }
+    }
+  },
+  "operatorUnavailableMessage": "Сейчас оператор отдыхает 🌙. Я отвечу или передам ему сообщение, как только он подключится.",
+
+  "botWaitingReturn": 3,
+  "followUpWaitingReturn": 12,
+
+  "imageHandlingBehavior": "PROCESS_WITH_LLM",
+  "shouldCallOperatorWithImage": false,
+
+  "videoHandlingBehavior": "FIXED_RESPONSE",
+  "videoFixedResponseText": "К сожалению, я пока не работаю с видео. Опишите словами или пришлите фото.",
+  "shouldCallOperatorWithVideo": true,
+
+  "documentHandlingBehavior": "FIXED_RESPONSE",
+  "documentFixedResponseText": "Спасибо за документ! Передаю менеджеру для проверки.",
+  "shouldCallOperatorWithDocument": true,
+
+  "urlHandlingBehavior": "PROCESS_WITH_CRAWLER",
+
+  "aiErrorHandlingBehavior": "SEND_ERROR_MESSAGE",
+  "aiErrorCustomMessage": "Прошу прощения, минутка технических сложностей. Сейчас приглашу менеджера.",
+  "shouldCallOperatorWithError": true
+}
+```
+
+## 12. Граничные случаи и валидация
+
+| Правило | Что AI-сервису помнить |
+|---|---|
+| Один `AgentBehavior` на платформу | Не пытаться создать два — конфликт по `(workspaceId, platformId)`. |
+| `waitingAnswerTime` 0–300 сек | Большее значение = пользователь дольше ждёт ответа. |
+| `messageOpenDelay` только для Telegram Personal | На обычных Telegram Bot ничего не даёт. |
+| `messageDevide=true` без `messageChunkSeparator` | Не работает — нужен явный разделитель. |
+| LLM должен знать про `messageChunkSeparator` | Если включаете `messageDevide`, добавьте в `baseSystemPrompt` инструкцию: «Когда нужно разделить ответ на части, ставь между частями `%%%`». |
+| `imageHandlingBehavior=PROCESS_WITH_LLM` | Только для изображений (vision). Для видео/доков/аудио — `SILENT` или `FIXED_RESPONSE`. |
+| `urlHandlingBehavior=PROCESS_WITH_CRAWLER` | Может тормозить (внешний запрос). Не включать массово. |
+| `messageFilters` — до 20 правил | Применяются по `order`. |
+| `greetingButtons` — до 10 кнопок | Платформенный лимит. |
+| `botWaitingReturn=0` | Бот не вернётся автоматически — нужно явное `/start` от оператора. |
+| `operatorSchedule.enabled=false` | Оператор «всегда доступен» — не блокировать `call_operator`. |
+| `aiErrorTargetStageId=null` | Не критично — система переведёт на первый этап. |
+| `skipTaskCreationOnCallOperator=true` | Только смена ответственного, без постановки задачи в CRM (для AmoCRM/Bitrix24). |
+
+## 13. Связь с другими подсистемами
+
+| Подсистема | Связь |
+|---|---|
+| **Агенты** ([`01-agents.md`](01-agents.md)) | `AgentBehavior` влияет на всех агентов платформы. |
+| **Платформа** ([`11-platforms.md`](11-platforms.md)) | Один `AgentBehavior` на платформу. |
+| **Триггеры** ([`04-triggers-and-actions.md`](04-triggers-and-actions.md)) | `CALL_OPERATOR` использует `operatorSchedule`. |
+| **Follow-up** ([`08-follow-up.md`](08-follow-up.md)) | `followUpWaitingReturn` отключает follow-up после оператора. |
+| **Файлы** | `greetingFileId` — `StoredFile`. |