@besales/mcp 0.48.0 → 1.0.0-beta.4

package/dist/resources/docs/files-and-uploads.md

@@ -1,295 +1,32 @@
-# 17. Файлы и медиа: StoredFile + FileSection
+# Файлы и вложения
 
-> **Источник правды:** `ai-aniomaly/docs/ai-prompt-builder/17-files-and-uploads.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 имеет два разных назначения: источник знаний и вложение сообщения. Само тело
+хранится в S3-совместимом хранилище, а БД содержит устойчивый object key, MIME, размер и связи.
+Короткоживущая подписанная ссылка не является идентичностью файла и не сохраняется в истории.
 
-## 1. Назначение
+## Загрузка
 
-В Animaly есть единое хранилище файлов на уровне workspace — `StoredFile`. Сюда загружаются:
-- Картинки/PDF/видео для инструмента `send_pic`.
-- Приветственные медиа агента (`AgentBehavior.greetingFileId`).
-- Аватары `TelegramPersonalAccount`.
-- Картинки для `WarmupImage`.
-- Медиа в `MessageConfig.attachments[]` follow-up.
-- Чанки QA-ответов с медиа (`QaAnswerChunk.storedFileId`).
-- Медиа-блоки в `Template` кампаний.
+Клиент запрашивает загрузку, передаёт тело по выданному безопасному каналу и опрашивает статус.
+Сервер проверяет размер, фактический MIME и принадлежность workspace. Имя файла не используется
+как путь объекта и не даёт права читать чужой объект.
 
-Файлы группируются в разделы (`FileSection`) — это удобство для админа в UI.
+Для базы знаний после загрузки создаётся knowledge source и запускается индексация. Для входящего
+медиа адаптер отдаёт только дескриптор источника; скачивание, SSRF-защита, MIME sniffing и запись
+`message_attachments` выполняются общим media-ingest контуром.
 
-## 2. Архитектура
+## Исходящее медиа
 
-```
-Workspace
-├── FileSection[]              # Разделы (например: «Прайсы», «Сертификаты», «Warmup-мемы»)
-│   └── StoredFile[]           # Файлы в разделе
-└── StoredFile[]               # Файлы без раздела (sectionId=null)
-```
+Собственный файл передаётся через единый шов доставки как object key с признаком `fromStorage`.
+Шов сам выбирает тело или подписанную ссылку по capability канала и строит подпись после плана
+частей. Это сохраняет стабильный отпечаток при повторе и не размножает один текст на два носителя.
 
-Все ссылки на файлы в системе — через `StoredFile.id` (uuid).
+Произвольного LLM-инструмента отправки картинки нет. Медиа отправляет серверное действие с
+разрешённым типом шага и обязательным `OutboundIntent`; модель не выбирает object key или UUID.
 
-## 3. JSON-схема `StoredFile`
+## Безопасность и хранение
 
-```json
-{
-  "id": "uuid",
-  "name": "Прайс-лист 2026",
-  "originalFilename": "price-list-2026.pdf",
-  "mimeType": "application/pdf",
-  "fileType": "DOCUMENT",
-  "storageType": "s3",
-  "url": "s3://animaly/files/<workspaceId>/price-list-2026.pdf",
-  "size": 245678,
-  "workspaceId": "<workspaceId>",
-  "sectionId": "<FileSection.id>",
-  "source": "USER_UPLOAD"
-}
-```
-
-| Поле | Тип | Описание |
-|---|---|---|
-| `name` | string | Имя, заданное при загрузке (для UI). Уникален в `(workspaceId, name)`. |
-| `originalFilename` | string | Реальное имя файла при загрузке. |
-| `mimeType` | string | `application/pdf`, `image/jpeg`, `video/mp4` и т.п. |
-| `fileType` | enum `StoredFileType` | `IMAGE` / `DOCUMENT` / `VIDEO` / `AUDIO` / `VOICE` / `VIDEO_NOTE` / `OTHER`. |
-| `storageType` | string (`local` / `s3`) | Где физически хранится. В проде — `s3`. |
-| `url` | string | Путь/URL к файлу. |
-| `size` | int | Размер в байтах. |
-| `sectionId` | uuid / null | ID `FileSection` (или null — без раздела). |
-| `source` | enum `StoredFileSource` | Категория для UI-фильтра. См. ниже. |
-
-## 4. `StoredFileSource` — откуда взялся файл
-
-| Значение | Когда выставляется |
-|---|---|
-| `USER_UPLOAD` | Загружен админом вручную через UI (default). |
-| `CHAT_MEDIA` | Получен от пользователя в диалоге (картинка/видео/документ от клиента). |
-| `TELEGRAM_AVATAR` | Скачанный аватар Telegram-аккаунта (для UI отображения). |
-| `WARMUP_IMAGE` | Картинка для warmup-сценариев. |
-| `AGENT_GREETING` | Приветственное медиа агента (`AgentBehavior.greetingFileId`). |
-| `CAMPAIGN` | Медиа из шаблона кампании. |
-| `CRM_IMPORT` | Файл, импортированный из CRM (например, документ к сделке). |
-| `OTHER` | Прочее. |
-
-AI-сервис должен задавать корректный `source` при загрузке — это влияет на фильтрацию в админке.
-
-## 5. JSON-схема `FileSection`
-
-```json
-{
-  "id": "uuid",
-  "name": "Прайсы и каталоги",
-  "workspaceId": "<workspaceId>"
-}
-```
-
-`name` уникален в `(workspaceId)`. Раздел — это просто группировка для UI; не влияет на логику работы.
-
-## 6. Использование `StoredFile` в системе
-
-### 6.1. `send_pic` (builtin tool)
-
-```
-LLM решает отправить файл → вызывает send_pic("price-list-2026", "delivery-info") или send_pic(["url-1", "url-2"])
-```
-
-`send_pic` принимает:
-- **Имя файла** (`StoredFile.name` без расширения) — система найдёт по имени в workspace.
-- **URL** — отправит напрямую без сохранения.
-- **Массив** имён/URL — отправит все по очереди.
-
-См. [`03-tools-catalog.md`](03-tools-catalog.md), раздел 2.12.
-
-### 6.2. Приветственное медиа
-
-```json
-{
-  "AgentBehavior": {
-    "botGreeting": "Здравствуйте! Я Анна, помогу с заказом.",
-    "greetingFileId": "<StoredFile.id>",
-    "greetingButtons": [...]
-  }
-}
-```
-
-Файл (картинка / видео / аудио) отправляется вместе с текстом приветствия. `source` рекомендуется `AGENT_GREETING`.
-
-### 6.3. Медиа в follow-up
-
-```json
-{
-  "MessageConfig": {
-    "type": "media",
-    "attachments": [
-      { "storedFileId": "<StoredFile.id>", "caption": "Прайс на этот месяц" }
-    ]
-  }
-}
-```
-
-До 4 вложений в одном шаге. Caption ≤ 1024 символов.
-
-### 6.4. Медиа-блоки в кампаниях
-
-```json
-{
-  "Template.blocks": [
-    { "type": "media", "storedFileId": "<StoredFile.id>", "caption": "..." }
-  ]
-}
-```
-
-См. [`09-campaigns.md`](09-campaigns.md), раздел 3.2.
-
-### 6.5. QA-ответы с медиа
-
-```json
-{
-  "QaAnswerChunk": {
-    "orderIndex": 0,
-    "text": null,
-    "storedFileId": "<StoredFile.id>",
-    "buttons": []
-  }
-}
-```
-
-QA может отдать медиа без текста (только картинку/документ) или текст + медиа в разных чанках. См. [`07-knowledge-base.md`](07-knowledge-base.md), раздел 6.
-
-### 6.6. Warmup
-
-```json
-{
-  "WarmupImage": {
-    "warmupSettingsId": "<warmupSettingsId>",
-    "storedFileId": "<StoredFile.id>"
-  }
-}
-```
-
-См. [`16-warmup-telegram-personal.md`](16-warmup-telegram-personal.md), раздел 7.
-
-## 7. Лимиты и платформенные ограничения
-
-| Платформа | Image | Video | Document | Audio | Caption |
-|---|---|---|---|---|---|
-| Telegram Bot | ≤ 10 MB | ≤ 50 MB | ≤ 50 MB | ≤ 50 MB | ≤ 1024 |
-| Telegram Personal | ≤ 2 GB | ≤ 2 GB | ≤ 2 GB | ≤ 2 GB | ≤ 1024 |
-| Wazzup (WhatsApp) | ≤ 5 MB | ≤ 16 MB | ≤ 100 MB | ≤ 16 MB | ≤ 1024 |
-| Avito | ≤ 10 MB | ✗ | ✗ | ✗ | — |
-| Instagram | ≤ 8 MB | ≤ 100 MB | ✗ | ≤ 8 MB | ≤ 1000 |
-| VK | ≤ 50 MB | ≤ 200 MB | ≤ 200 MB | ≤ 200 MB | — |
-| Web Widget | ≤ 25 MB | ≤ 100 MB | ≤ 100 MB | ≤ 25 MB | — |
-| SMS | ✗ | ✗ | ✗ | ✗ | — |
-
-(Лимиты могут отличаться в реальном времени — указаны типовые значения провайдеров.)
-
-## 8. Inline-пример: organize files for e-commerce bot
-
-```json
-{
-  "fileSections": [
-    { "name": "Прайсы и каталоги" },
-    { "name": "Сертификаты" },
-    { "name": "Welcome-медиа" },
-    { "name": "Карта проезда" }
-  ],
-  "storedFiles": [
-    {
-      "name": "Прайс-лист 2026",
-      "originalFilename": "price-list-2026.pdf",
-      "mimeType": "application/pdf",
-      "fileType": "DOCUMENT",
-      "sectionId": "<id-Прайсы>",
-      "source": "USER_UPLOAD"
-    },
-    {
-      "name": "Каталог товаров (PDF)",
-      "originalFilename": "catalog.pdf",
-      "mimeType": "application/pdf",
-      "fileType": "DOCUMENT",
-      "sectionId": "<id-Прайсы>",
-      "source": "USER_UPLOAD"
-    },
-    {
-      "name": "Welcome video",
-      "originalFilename": "welcome.mp4",
-      "mimeType": "video/mp4",
-      "fileType": "VIDEO",
-      "sectionId": "<id-Welcome>",
-      "source": "AGENT_GREETING"
-    },
-    {
-      "name": "Карта офиса",
-      "originalFilename": "office-map.jpg",
-      "mimeType": "image/jpeg",
-      "fileType": "IMAGE",
-      "sectionId": "<id-Карта>",
-      "source": "USER_UPLOAD"
-    }
-  ]
-}
-```
-
-В `AgentBehavior`:
-```json
-{ "greetingFileId": "<id-Welcome video>" }
-```
-
-В `baseSystemPrompt` агента:
-```
-Если клиент спрашивает прайс-лист — отправляй его инструментом send_pic("Прайс-лист 2026").
-Если клиент спрашивает, как добраться — send_pic("Карта офиса").
-Если клиент просит каталог — send_pic("Каталог товаров (PDF)").
-```
-
-## 9. Что должен сделать клиент в админке
-
-AI-сервис не загружает файлы сам — только описывает структуру. Клиенту нужно:
-
-1. Открыть `Files` (раздел в навигации админки).
-2. Создать `FileSection` (например, «Прайсы»).
-3. Загрузить файлы через UI (drag-n-drop или file picker).
-4. Указать `name` (как агент будет ссылаться) и `description` (опционально).
-5. Получить `StoredFile.id` или `name` и подставить в:
-   - `AgentBehavior.greetingFileId`
-   - `MessageConfig.attachments[].storedFileId`
-   - `Template.blocks[].storedFileId`
-   - `WarmupImage.storedFileId`
-   - `QaAnswerChunk.storedFileId`
-
-## 10. Граничные случаи и валидация
-
-| Правило | Что AI-сервису помнить |
-|---|---|
-| `name` уникален в `(workspaceId)` | Не назначать два файла с именем «Прайс». |
-| `send_pic` ищет по `name` | AI должен использовать тот же `name`, что админ ввёл при загрузке. Чувствителен к точному совпадению. |
-| `mimeType` определяет, как платформа отрендерит | PDF в Telegram пойдёт как document, в Wazzup-WhatsApp — тоже document, на Avito — не пройдёт. |
-| `source=CHAT_MEDIA` файлы | Растут быстро (от пользователей). Имеют свою retention-политику. AI-сервис не должен ссылаться. |
-| `storageType=local` для прода | Не использовать — только для dev. В проде S3. |
-| Удаление `FileSection` | `sectionId` файлов внутри становится `null`, файлы остаются. |
-| Удаление `StoredFile` | Каскадно удалит ссылки в `AgentBehavior.greetingFile`, `WarmupImage`, `QaAnswerChunk`. |
-| Слишком большой файл (>50 MB) | Многие платформы не примут. Для PDF — рекомендовать сжатие. |
-| `send_pic` с массивом >5 файлов | Платформы могут флаговать как спам. Реалистичный лимит — 1–3 за один вызов. |
-| Voice (Telegram OPUS) vs Audio | `VOICE` и `AUDIO` — разные `fileType`. Голосовые (`VOICE`) авто-транскрибируются через Whisper; аудиофайлы (`AUDIO`) — нет (применяется `audioHandlingBehavior`). См. [`10-agent-behavior.md`](10-agent-behavior.md) §9. |
-
-## 11. Что AI-сервис должен спросить у клиента
-
-При сценариях с медиа:
-
-1. «Какие документы/картинки вы хотите, чтобы агент мог отправлять?» (для `send_pic`).
-2. «Нужно ли приветственное видео/картинка вместе с приветствием?» (для `greetingFileId`).
-3. «Есть ли уже подготовленные прайсы / каталоги / сертификаты?» — указать `StoredFile.name` для использования в промпте.
-4. Для warmup: «Загрузите 5–10 нейтральных картинок (мемы, природа) — они нужны для естественной активности warmup-аккаунтов».
-
-## 12. Связь с другими подсистемами
-
-| Подсистема | Связь |
-|---|---|
-| **Инструменты** ([`03-tools-catalog.md`](03-tools-catalog.md)) | `send_pic` — единственный инструмент, который работает с файлами на чтение. |
-| **Поведение** ([`10-agent-behavior.md`](10-agent-behavior.md)) | `greetingFileId` — приветственное медиа. |
-| **Follow-up** ([`08-follow-up.md`](08-follow-up.md)) | `MessageConfig.attachments[].storedFileId`. |
-| **Кампании** ([`09-campaigns.md`](09-campaigns.md)) | `Template.blocks[type=media].storedFileId`. |
-| **База знаний** ([`07-knowledge-base.md`](07-knowledge-base.md)) | `QaAnswerChunk.storedFileId` — медиа в QA-ответах. |
-| **Warmup** ([`16-warmup-telegram-personal.md`](16-warmup-telegram-personal.md)) | `WarmupImage.storedFileId`. |
-| **Платформы** ([`11-platforms.md`](11-platforms.md)) | Каждая платформа имеет свои лимиты по типам и размерам. |
+- публичная выдача тела использует ограниченную capability-ссылку;
+- пользовательские URL проходят SSRF-проверку;
+- PII во вложениях подчиняется ретеншну и GDPR-диспозиции;
+- удаление метаданных и тела согласуется cleanup-процессом;
+- секреты и подписанные URL не попадают в промпт, трассу или долговременную историю.

package/dist/resources/docs/follow-up.md

@@ -1,19 +1,54 @@
 # Follow-up и дожимы
 
-## Чтение
+У календарной цепочки `config.sessionTimeVariable` называет переменную контакта с часом эфира;
+`config.sessionDayOffsets` задаёт непустой список целых дней от 0 до 30 без повторов;
+`config.sessionDurationMinutes` — целые минуты от 1 до 1440. Длительность требует оба соседних поля и не подставляется по умолчанию.
+Поле серии вне календарной цепочки, неизвестное или неоднозначное имя, константа и секрет получают адресный отказ сервера.
+Повтор дня доходит до сервера. Список отдаёт имя и числа; у удалённой переменной выключенной цепочки имя равно `null`.
 
-Начни с `besales_followup_sequence_list`. Для редактирования одной цепочки запроси её полный config;
-список без config — только инвентаризация. Статистика шага — `besales_followup_step_stats`, реакции
-— `besales_followup_reactions`.
+Начни с `besales_followup_sequence_list`. Для редактирования передай `sequence_id` либо
+`include_config: true`: ответ содержит дословные `type`, `trigger`, `config`. Список без этих
+параметров — инвентаризация. Если `config: null`, причина в `configUnavailableReason`; сначала
+сохрани цепочку целиком формой дожимов. Статистика — `besales_followup_step_stats`, реакции —
+`besales_followup_reactions`.
 
-## Изменение
+В реакциях единица счёта — касание, а не человек. Операционная доля `replied / resolvedSent`
+считает только ответы до следующего касания (не более 72 часов); шаги по ней не сравнивай.
+Сравнительная доля `horizonEngaged / comparableSent` объединяет живой ответ ИЛИ настоящий клик
+ссылки касания без двойного счёта. Для всех строк сервер выбирает общий `horizonMinutes`;
+сравнивай только строки с `comparableSent > 0` и `comparableReliable: true`.
+Доля прерванных окон — `maturedCensored / (comparableSent + maturedCensored)`: в знаменатель
+входят только созревшие окна, а не все `censored`. Нулевой пул и причины `noData` или
+`noReliableHorizon` не дают основания для сравнения. Для раскрытия через API используй те же
+горизонт и `calculatedAt` как `asOf`; это граница событий, а не неизменяемый снимок хранения.
+Серверные `totals` и `runs` не пересчитывай из строк. `runs` считает прохождения (`grain: passage`,
+`periodBasis: passageStartedAt`) в отдельном окне `windowDays`; клик сам по себе не означает
+ответ агента, глубокий диалог или оплату. Метки транспорта бери из `dimensions.transports`.
 
-`besales_followup_sequence_upsert` заменяет конфигурацию цепочки целиком. Сохрани все существующие
-шаги, условия и exclusions. Клонирование — `besales_followup_sequence_clone`; наличие отдельной
-правки текста шага проверяй по динамическому каталогу текущей линии.
+`besales_followup_sequence_upsert` заменяет config целиком: сохрани все шаги и exclusions.
+`config.stopOnPayment: true` выключает дожимы у оплатившего (в списке — `triggerConfig.stop_on_payment`);
+при правке такой цепочки передай его снова, иначе стоп выключится.
+Клонирование — `besales_followup_sequence_clone`. Копия дожима сохраняет форму, копия канала
+требует одного полного сохранения формы.
 
-## Безопасная проверка
+Один текст исправляет `besales_followup_step_message_set`: `step_index` — позиция с нуля в
+`config.steps`, `expected_content` — текст свежего чтения. При 409 перечитай цепочку и найди
+шаг заново. Время, условия и соседние сообщения сохраняются. Незаведённый или архивный
+`{{link:слаг}}` даёт отказ. При правке только текстов уже идущие люди получат новый текст со следующего сообщения; начатая отправка завершится прежним текстом без повтора.
+`runs` называет переведённых, уже отправлявших старый текст и оставленных с причиной; перескажи числа и `summary`.
+Изменение расписания, условий, порядка или заметки CRM оставляет идущих на своей версии.
+Текст вместе с настройками цепочки (стоп при оплате, записка в карточку, круги, продолжение, порог молчания, дата календаря)
+идущим не переводится: новые настройки действуют для всех сразу. Повторное сохранение без изменений доставит им текст.
+Это правило применяется и к полной записи формы; `warnings` относится только к оставленным людям.
+UNKNOWN после отправки нельзя повторять без status.
 
-Перед отправкой живому человеку используй funnel-test plan, если его инструменты есть в каталоге,
-покажи transports, тексты, skip reasons и truncated, затем запускай только с явным подтверждением.
-Timeout или UNKNOWN не разрешает повторную отправку без status.
+Тест воронки: `besales_followup_funnel_test_plan` (адрес человека в канале `chat_user_id` —
+`identities[].id` из `besales_contact_get`) строит и замораживает план, ничего не отправляя; покажи
+человеку все тексты и причины пропуска. Запуск —
+`besales_followup_funnel_test_start` с explicit_confirmation и причиной: уходят НАСТОЯЩИЕ сообщения с
+паузой 15 секунд. Дальше — `besales_followup_funnel_test_status`; остановка —
+`besales_followup_funnel_test_cancel` (со следующего касания).
+
+До запуска покажи также `deliveryMode`, `requestedTransports` и `transportObservation`, если
+они есть в плане: наблюдение не является разрешением доставки. Проверь `truncated` и
+`unchecked` — усечённый план или непроверенные условия не доказывают полный охват.