@besales/mcp 0.48.0 → 1.0.0-beta.4

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

@@ -1,398 +1,67 @@
-# 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.
+`besales_behavior_update` принимает прежние имена полей поведения и переводит их в секции API v2:
+`bot_greeting` → `greeting.text`, `ai_error_custom_message` → `errorHandling.custom_message`,
+`message_filters` списком → `messageFilters.rules`. Прежние `fake_delay` и `message_open_delay`
+задаются **в секундах**; мост умножает их на 1000 и отправляет поля `*_ms`. Если используешь
+новые имена `*_ms`, передавай миллисекунды. Одновременная передача прежнего и нового имени одного
+поля отклоняется с адресом поля. `go_offline` принимается, но не исполнялось и в прежней системе:
+мост отбрасывает его и сообщает об этом в ответе.
 
-## 1. Назначение
+Поведение в Besales не хранится одним глобальным объектом. Оно складывается из конфигурации
+агента, его привязки к конкретному каналу и `channel_behavior_configs`. Это важно для
+multi-instance: два канала одного типа могут иметь разные режимы работы.
 
-`AgentBehavior` — это контейнер настроек, которые применяются **на уровне платформы** и влияют на всех её агентов. Он управляет:
-- Задержками перед ответом (имитация естественной коммуникации).
-- Скоростью «набора» сообщения.
-- Стратегией обработки медиа (картинки, видео, документы, аудио, ссылки).
-- Расписанием доступности оператора.
-- Фильтрами текста и приветственными кнопками.
-- Поведением при ошибках LLM.
+## Уровень агента
 
-Один `AgentBehavior` на `(workspaceId, platformId)`. AI-сервис создаёт его при настройке платформы.
+На агенте живут базовый промпт, режим завершения хода, опубликованная версия, навыки, действия и
+привязки к CRM-воронкам. Изменение агента не должно незаметно менять все каналы workspace.
 
-## 2. JSON-схема (полная)
+## Уровень привязки агент × канал
 
-```json
-{
-  "id": "uuid",
-  "platformId": "<platformId>",
-  "workspaceId": "<workspaceId>",
+Привязка определяет, может ли агент обслуживать канал, является ли он default-агентом и какие
+проекции версии доступны этому каналу. Постобработчики также привязываются к паре агент × канал,
+а не включаются одним флагом на агенте.
 
-  "waitingAnswerTime": 10,
-  "messageOpenDelay": 0,
-  "fakeDelay": 0,
-  "typingSpeed": "fast",
+## Уровень канала
 
-  "canInterrupt": false,
-  "messageDevide": false,
-  "messageChunkSeparator": "",
+Канал задаёт транспортные возможности и поведенческие правила: рабочее расписание, политику
+операторской паузы, ограничения проактивных касаний, поддержку кнопок, подписи медиа и способ
+передачи собственного файла. Отсутствующая настройка не должна угадываться по типу канала, если
+контракт требует явного значения.
 
-  "botGreeting": "Привет! Чем могу помочь?",
-  "greetingFileId": null,
-  "greetingButtons": [],
-  "greetingButtonsKeyboardType": "INLINE",
+Исходящая реплика всегда проходит единый шов доставки. Намерение отправки обязательно; гейты
+могут доставить, подавить или вернуть доказанный/неоднозначный отказ. Побочные эффекты отправки
+возникают только после доказанной доставки.
 
-  "popupDelaySeconds": 0,
+## Оператор и эскалация
 
-  "messageFilters": [],
+Передача оператору и реплика оператора — разные события. Доставленная реплика оператора ставит
+агента на паузу по настройке канала; массовая рассылка такой паузы не создаёт. Правила handoff
+задаются условиями общего condition-core, отдельный язык условий заводить нельзя.
 
-  "operatorSchedule": null,
-  "operatorUnavailableMessage": null,
-  "botWaitingReturn": 3,
-  "followUpWaitingReturn": -1,
+В `besales_behavior_update.operator_schedule.bot_waiting_return_hours` значение `-1` отключает
+паузу после оператора, `0` оставляет её до ручного снятия, положительное значение задаёт часы.
+Отсутствие этой паузы само по себе не доказывает, что остальные гейты разрешают ответ.
 
-  "imageHandlingBehavior": "SILENT",
-  "imageFixedResponseText": null,
-  "shouldCallOperatorWithImage": true,
-  "imageOperatorComment": null,
+В `media_handling` режим `PROCESS_WITH_LLM` различается по типу: изображение передаётся модели
+зрения, у видео читается только подпись или текст сообщения, у документа — извлечённый текст,
+а не сам файл. Для `audio` доступны только `SILENT` и `FIXED_RESPONSE`.
+Длинный документ усекается с предупреждением. Если текст извлечь нельзя, модель получает
+причину; оператор вызывается по настройке `call_operator`. Включение разбора изображения или
+документа требует `explicit_confirmation`.
 
-  "videoHandlingBehavior": "SILENT",
-  "videoFixedResponseText": null,
-  "shouldCallOperatorWithVideo": true,
-  "videoOperatorComment": null,
+Неподдержанное содержимое Telegram настраивается через `besales_behavior_update`, секция
+`unsupported_input_handling`: `SILENT`, `AS_TEXT` или `FIXED_RESPONSE`. Вызов оператора — отдельный
+флаг. Комбинация `SILENT + call_operator` сохраняет безопасную заглушку для однократности, зовёт
+оператора и завершает ход до агента, ничего не отправляя клиенту. Секция сливается с текущей;
+первую запись присылай полной, а `schema_version` инструмент добавляет сам.
 
-  "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,
-  "contactNamePersonalizationMode": "OFF",
-  "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 | Сколько часов бот молчит после сообщения оператора. Допустимые: `-1`, `0`, `1`, `3`, `6`, `12`, `24`. `-1` = ответ оператора вообще не отключает бота, `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`. |
-| `contactNamePersonalizationMode` | `OFF` | Режим безопасного обращения по подтверждённому имени: `OFF`, `SHADOW` или `ENABLED`. Реальное имя остаётся скрытым; модель получает только стабильный semantic token. Ставится через `privacy: { contact_name_personalization_mode }`. |
-| `anonymizationDisabledTypes` | `[]` | OFF-список прочих PII, которые при включённой анонимизации осознанно отдаются модели реальными. Имена/фамилии/отчества выключить нельзя. Значения: `PHONE`/`EMAIL`/`INN`/`PASSPORT`/`CARD`/`DATE_OF_BIRTH`/`ACCOUNT`/`SNILS`/`OGRN`/`OGRNIP`/`SOCIAL_ID`. Ставится через `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` есть у трёх типов из четырёх, и механика у каждого СВОЯ: изображение уходит в vision-модель; у **видео** обрабатывается **подпись (caption)** как обычный текст (само видео не отправляется, нет подписи → оператор; Telegram Bot/Personal, Wazzup, VK, Bitrix24Bot, Salebot, GetCourse — на Avito/Instagram видео → оператор); у **документа** обрабатывается **извлечённый текст файла** (сам файл не отправляется). У **аудио** этого значения нет вовсе — только `SILENT` или `FIXED_RESPONSE`.
-
-### Видео / Документы / Аудио (`VideoHandlingBehavior`, `DocumentHandlingBehavior`, `AudioHandlingBehavior`)
-
-`AudioHandlingBehavior` имеет только `SILENT` / `FIXED_RESPONSE`. `VideoHandlingBehavior` и `DocumentHandlingBehavior` дополнительно поддерживают `PROCESS_WITH_LLM`:
-
-| Значение | Что делает |
-|---|---|
-| `SILENT` | Промолчать (default). |
-| `FIXED_RESPONSE` | Отправить фиксированный текст из соответствующего `*FixedResponseText`. |
-| `PROCESS_WITH_LLM` *(video)* | Обработать **подпись** видео как текст через LLM (само видео не отправляется; нет подписи → оператор; Telegram/Wazzup/VK/Bitrix24/Salebot/GetCourse, кроме Avito/Instagram). |
-| `PROCESS_WITH_LLM` *(document)* | Извлечь текст файла (PDF, DOCX, DOC, XLSX, XLS, CSV, TSV, TXT, MD) и обработать как обычное сообщение. Сам файл в модель не отправляется. Длинный документ передаётся не целиком — модель предупреждается об усечении. Скан без текстового слоя, неподдерживаемый формат и файл >20 МБ → оператор. На Avito документ приходит голой ссылкой: без расширения в ней разбор невозможен → оператор. |
-
-```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` инструкцию: «Когда нужно разделить ответ на части, ставь между частями `%%%`». |
-| `audioHandlingBehavior=PROCESS_WITH_LLM` | Такого значения нет — только `SILENT` или `FIXED_RESPONSE`, иначе 400. У image/video/document разбор есть, но механика у каждого своя (vision / подпись / текст файла). |
-| `urlHandlingBehavior=PROCESS_WITH_CRAWLER` | Может тормозить (внешний запрос). Не включать массово. |
-| `messageFilters` — до 20 правил | Применяются по `order`. |
-| `greetingButtons` — до 10 кнопок | Платформенный лимит. |
-| `botWaitingReturn=0` | Бот не вернётся автоматически — нужно явное `/start` от оператора. |
-| `botWaitingReturn=-1` | Бот отвечает поверх оператора — берут в суфлёрских/квалификационных каналах. Стадию CRM «оператор перехватил» настройка НЕ отменяет: если у этой стадии выключен `isBotActive`, бот всё равно замолчит по стадийному гейту. |
-| `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`. |
+- опубликована версия агента;
+- агент привязан к нужному каналу;
+- выбран корректный default там, где он нужен;
+- настроены знания, CRM и действия, на которые ссылается промпт;
+- песочница проходит через те же runtime-гейты, что production;
+- нет секретов, внутренних UUID и противоречащих друг другу инструкций.

package/dist/resources/docs/campaigns.md

@@ -1,20 +1,13 @@
 # Рассылки и кампании
 
-## Подготовка
+Mailing variant хранит текст, schedule — правило отбора и время, launch/run — запуск, cohort —
+снимок аудитории. Фактически доступные операции сверяй с `besales://docs/tools-catalog`.
 
-Разделяй сущности: mailing variant хранит текст, schedule — правило отбора и время, launch/run —
-конкретный запуск, cohort — снимок аудитории запуска. Доступный набор операций всегда сверяй с
-`besales://docs/tools-catalog`.
+`besales_broadcast_analytics_get` — канонический исходящий отчёт;
+`besales_broadcast_cohorts_list` — запуски. Сохраняй оси cohort/period/entry и зерно
+recipient/channel. Не считай сообщения людьми и не подменяй входящую аналитику исходящей.
 
-## Аналитика
-
-`besales_broadcast_analytics_get` — канонический исходящий отчёт; `besales_broadcast_cohorts_list`
-— перечень запусков. Сохраняй оси cohort/period/entry и зерно recipient/channel. Не считай число
-сообщений числом людей и не выдавай исходящую аналитику за входящую.
-
-## Запись и запуск
-
-Если линия предоставляет mailing/schedule tools, сначала создай выключенную конфигурацию, затем
-получи preview, проверь ограничения, окно, каналы и дедуп, и только после явного подтверждения
-включай или запускай. При pause/timeout/UNKNOWN сначала читай run/status; повтор может написать
-человеку второй раз.
+Через `besales_broadcast_schedule_preview` проверь ограничения, окно, каналы и дедуп, затем
+сохрани расписание выключенным (`besales_broadcast_schedule_upsert`, `is_enabled=false`). Перед
+включением или живым запуском получи явное подтверждение. При pause/timeout/UNKNOWN сначала читай
+run/status: повторная отправка может написать человеку второй раз.