@besales/mcp 0.1.0 → 0.11.1

package/dist/resources/docs/knowledge-base.md

@@ -0,0 +1,521 @@
+# 07. База знаний и RAG
+
+> **Источник правды:** `ai-aniomaly/docs/ai-prompt-builder/07-knowledge-base.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. Назначение
+
+База знаний нужна агенту, чтобы отвечать **по реальной информации** компании-клиента: документы, FAQ, прайсы, статьи, инструкции. Animaly использует Pinecone (vector DB) + локальную БД для хранения. Агент получает релевантные фрагменты во время каждого запроса (RAG — Retrieval Augmented Generation).
+
+## 2. Архитектура
+
+```
+Workspace
+└── Namespace (cleanNamespace + scopeType)
+    ├── KnowledgeDocument[] → KnowledgeChunk[] (Pinecone: pineconeDoc)
+    ├── Qa[] → QaAnswerChunk[]                  (Pinecone: pineconeQa)
+    ├── WebsiteKnowledge[]                      (Pinecone: pineconeWeb)
+    └── KnowledgeTable[]                        (Pinecone: pineconeTable)
+
+AgentChat
+└── knowledgeNamespaces: string[] — массив cleanNamespace
+```
+
+При каждом запросе агента система:
+1. Берёт `query` (сообщение пользователя или его переписанная версия из QUERY_REWRITE).
+2. Делает vector-поиск в каждом из подключённых namespaces (по типам данных).
+3. Объединяет результаты, отсекает по `ragMinScore`/`qaMinScore`, берёт top-K (`ragTopK`).
+4. Подкладывает в промпт как `{knowledgeContext}`.
+
+Для QA после поиска может запускаться `RERANKER` (`AgentSpecialized.RERANKER`), чтобы выбрать лучший QA-кандидат.
+
+## 3. Namespace — JSON-схема
+
+```json
+{
+  "id": "uuid",
+  "cleanNamespace": "main_qa",
+  "displayName": "Main Q&A",
+  "scopeType": "PLATFORM",
+  "workspaceId": "<workspaceId>",
+  "platformId": "<platformId>",
+
+  "hasQa": true,
+  "hasDocuments": true,
+  "hasWebsites": false,
+  "hasTables": false,
+
+  "accessMode": "AUTO_QUERY",
+
+  "pineconeQa": "qa_main_qa_<workspaceId>_<platformId>",
+  "pineconeDoc": "doc_main_qa_<workspaceId>_<platformId>",
+  "pineconeWeb": null,
+  "pineconeTable": null
+}
+```
+
+| Поле | Описание |
+|---|---|
+| `cleanNamespace` | Человеко-читаемое имя (например, `general`, `support`). Уникально в рамках платформы (или workspace для `WORKSPACE` scope). |
+| `displayName` | Имя для UI. |
+| `scopeType` | `GLOBAL` (системный) / `WORKSPACE` (общий для workspace) / `PLATFORM` (только для одной платформы). |
+| `workspaceId`, `platformId` | Привязка по scope. |
+| `hasQa`, `hasDocuments`, `hasWebsites`, `hasTables` | Флаги активных типов данных. |
+| `accessMode` | `AUTO_QUERY` (поиск автоматически на каждом сообщении) или `TOOL_ONLY` (поиск только по явному вызову `read_namespaces`). |
+| `pineconeQa/Doc/Web/Table` | Реальные имена namespace-ов в Pinecone (генерируются системой при создании). |
+
+### `WORKSPACE` scope: привязка к нескольким платформам
+
+`Namespace` с `scopeType=WORKSPACE` может быть привязан к нескольким `Platform` через `PlatformNamespace`:
+
+```json
+{
+  "id": "uuid",
+  "platformId": "<platformId>",
+  "namespaceId": "<namespaceId>"
+}
+```
+
+Так одну общую базу знаний (например, общий FAQ) можно подключить к 3 разным каналам.
+
+## 4. Назначение namespace агенту
+
+Через `AgentChat.knowledgeNamespaces` (массив строк):
+
+```json
+{
+  "name": "main",
+  "knowledgeNamespaces": ["main_qa", "main_doc", "general_faq"]
+}
+```
+
+Имена в массиве — это `Namespace.cleanNamespace`. Агент получит данные из всех типов (qa/doc/web/table), доступных в этих namespaces.
+
+## 5. KnowledgeDocument — документы
+
+```json
+{
+  "id": "uuid",
+  "filename": "price-list-2026.pdf",
+  "filepath": "s3://animaly/knowledge/price-list-2026.pdf",
+  "namespace": "doc_main_qa_<wsId>_<platformId>",
+  "namespaceRecordId": "<Namespace.id>",
+  "platformId": "<platformId>",
+  "workspaceId": "<workspaceId>",
+
+  "splitMode": "recursive",
+  "separator": null,
+  "chunkSize": 1000,
+  "chunkOverlap": 200,
+  "maxChunkSize": 2000,
+
+  "embeddingModel": "text-embedding-3-small",
+  "storageType": "s3",
+  "status": "COMPLETED"
+}
+```
+
+| Поле | Описание |
+|---|---|
+| `splitMode` | Стратегия разбиения текста (`recursive`, `paragraph`, и т.п.). |
+| `chunkSize`, `chunkOverlap`, `maxChunkSize` | Параметры разбиения. |
+| `embeddingModel` | Модель эмбеддингов (по умолчанию OpenAI). |
+| `status` | enum `DocumentStatus`: `LOADED` → `TEXT_EXTRACTED` → `SPLIT` → `EMBEDDINGS_GENERATED` → `VECTOR_DB_UPLOADED` → `COMPLETED`. |
+
+Чанки хранятся в `KnowledgeChunk` (`text`, `embedding`, `chunkIndex`).
+
+### 5.1. Заголовок документа НЕ попадает в эмбеддинг (contextual retrieval)
+
+Эмбеддится **только сырой текст чанка**. `filename`/заголовок документа хранится в метаданных Pinecone, но **в вектор не входит** — чанк находится поиском только по словам, которые есть в нём самом. Чанк «Модуль 6. Колени» не содержит названия курса/темы, поэтому по запросу «какой курс от боли в коленях» матчится слабее, а в смешанном namespace путается с похожими темами других продуктов.
+
+Приёмы:
+- **Контекстный заголовок внутри чанка.** Начинай каждый смысловой блок строкой-контекстом, которая попадёт в эмбеддинг: `[Курс ДБО — суставы, позвоночник, боли] Модуль 6. Колени…`. Так вектор кодирует и тему, и принадлежность; LLM тоже видит, к чему относится фрагмент.
+- **Контроль границ через `split_override`.** Чтобы «один смысловой юнит = один чанк» (и заголовок не отклеился), грузи документ с `split_mode=separator` + явным `separator` между юнитами (+ `max_chunk_size` с запасом). Иначе recursive-резка по `chunkSize` разорвёт блок, и второй кусок останется без заголовка.
+
+## 6. Qa — пары «вопрос-ответ»
+
+```json
+{
+  "id": "uuid",
+  "question": "Какая стоимость доставки по Москве?",
+  "answer": "Доставка по Москве — 500 руб. в пределах МКАД. ...",
+  "alias": "delivery_moscow",
+  "namespace": "qa_main_qa_<wsId>_<platformId>",
+  "namespaceRecordId": "<Namespace.id>",
+  "platformId": "<platformId>",
+  "workspaceId": "<workspaceId>",
+
+  "mode": "SIMPLE",
+  "callOperator": false,
+  "chunkDelaySeconds": 10,
+  "isCallQaOnly": false,
+
+  "embeddingModel": "text-embedding-3-small",
+  "status": "COMPLETED",
+
+  "answerChunks": [
+    { "orderIndex": 0, "text": "Доставка по Москве — 500 руб. ...", "buttons": [], "storedFileId": null },
+    { "orderIndex": 1, "text": null, "buttons": [], "storedFileId": "<StoredFile.id>" }
+  ]
+}
+```
+
+| Поле | Описание |
+|---|---|
+| `question`, `answer` | Текст. `answer` используется как контекст; реально в чат уходит `answerChunks[]`. |
+| `alias` | Уникальный псевдоним в `(workspaceId)`. Используется для `call_qa(alias_name)`. Опциональный, но обязательный, если `isCallQaOnly=true`. |
+| `mode` | `SIMPLE` (RAG + QA), `STRICT` (только QA, дословно), `ONCE_STRICT` (первый раз STRICT, потом как контекст). |
+| `callOperator` | Если `true` — после QA автоматически вызывается оператор. |
+| `chunkDelaySeconds` | Задержка между отправкой чанков ответа (если их несколько). |
+| `isCallQaOnly` | Если `true` — QA не векторизуется, доступна только через `call_qa(alias)`. |
+
+### `QaAnswerChunk` — фрагменты ответа
+
+```json
+{
+  "orderIndex": 0,
+  "text": "Текст чанка",
+  "buttons": [
+    { "name": "Подробнее", "url": "https://example.com/delivery" }
+  ],
+  "storedFileId": "<StoredFile.id>"
+}
+```
+
+Чанк может быть текстовым (`text`), медийным (`storedFileId`) или иметь кнопки (`buttons`). Несколько чанков отправляются последовательно с задержкой `chunkDelaySeconds`.
+
+> ⚠️ **Ссылки — в текст, не в кнопки (по умолчанию).** URL клади в `text` чанка/ответа, а НЕ в `buttons`. В режиме `SIMPLE` агент перегенерирует ответ из текста контекста, и URL, лежащий только в `buttons`, клиенту не доходит (агент его «не видит» и отвечает «не вижу ссылку»). Кнопки (`buttons`) добавляй ТОЛЬКО если пользователь явно попросил кнопку. То же при `besales_knowledge_qa_create` / `besales_knowledge_qa_patch`.
+
+## 7. WebsiteKnowledge — скрапленные сайты
+
+```json
+{
+  "id": "uuid",
+  "url": "https://example.com",
+  "domain": "example.com",
+  "title": "Главная",
+  "description": "...",
+  "namespace": "web_main_qa_<wsId>_<platformId>",
+  "namespaceRecordId": "<Namespace.id>",
+  "status": "COMPLETED",
+  "totalPages": 142,
+  "totalChunks": 1530,
+  "chunkSize": 1000,
+  "chunkOverlap": 200,
+  "embeddingModel": "text-embedding-3-small",
+  "lastCrawledAt": "2026-04-25T10:00:00Z"
+}
+```
+
+Краулинг управляется отдельным сервисом (BullMQ-job). AI-сервис обычно не создаёт WebsiteKnowledge напрямую — это делает админ через UI.
+
+## 8. KnowledgeTable — таблицы (Google Sheets / Notion / Airtable)
+
+```json
+{
+  "id": "uuid",
+  "name": "Прайс на услуги",
+  "type": "GOOGLE_SHEETS",
+  "url": "https://docs.google.com/spreadsheets/d/...",
+  "access": "PUBLIC",
+  "namespace": "table_main_qa_<wsId>_<platformId>",
+  "namespaceRecordId": "<Namespace.id>",
+
+  "headerRowIndex": 0,
+  "useVectorIndex": true,
+  "vectorEmbedMaxChars": 1000,
+  "vectorTopK": 5,
+
+  "isActive": true,
+  "errorCount": 0,
+  "lastSuccessAt": "2026-04-30T08:00:00Z"
+}
+```
+
+| Поле | Описание |
+|---|---|
+| `type` | enum `KnowledgeSourceType`: `GOOGLE_SHEETS`, `NOTION`, `AIRTABLE`. |
+| `access` | `PUBLIC` / `PRIVATE`. |
+| `useVectorIndex` | Индексировать содержимое таблицы для vector-поиска. Если `false` — таблица читается «сырой» при каждом запросе (медленнее, но всегда актуально). |
+| `vectorTopK` | Лимит результатов из таблицы. |
+
+## 9. Параметры RAG на уровне агента
+
+В `AgentChat`:
+
+| Поле | Дефолт | Описание |
+|---|---|---|
+| `ragTopK` | 3 | Сколько top-K результатов брать из vector-поиска документов. |
+| `ragMinScore` | 0.5 | Минимальная релевантность RAG-результата (0.0–1.0). |
+| `qaMinScore` | 0.45 | Минимальная релевантность QA-совпадения (широкий recall; точность даёт LLM-reranker). |
+| `qaContextLimit` | 3 | Лимит QA-кандидатов для контекста (1–6). |
+
+> ⚠️ Значения в таблице — дефолты колонок `AgentChat` (что получает новый агент), они и действуют в рантайме. В коде есть вторичные fallback-константы (`DEFAULT_RAG_TOP_K=5`, `DEFAULT_RAG_MIN_SCORE=0.4`), которые срабатывают только если значение агента не задано — не путай их с дефолтом агента.
+
+## 10. Поток обработки RAG
+
+```
+Сообщение пользователя
+    ↓
+QUERY_REWRITE (через AiUsageOperationKind=KNOWLEDGE_QUERY_REWRITE)
+    Опционально: LLM переписывает запрос для лучшего поиска (учитывая историю).
+    ↓
+Vector-поиск по namespaces агента
+    Параллельно во всех типах: qa, doc, web, table.
+    ↓
+Фильтрация по min-score
+    QA: qaMinScore (0.45)
+    Doc/Web/Table: ragMinScore (0.5)
+    ↓
+Reranker (AgentSpecialized.RERANKER)
+    Опционально: для QA выбирает лучший из top-K (если включён).
+    ↓
+Top-K результатов
+    ragTopK для doc/web, qaContextLimit для QA.
+    ↓
+Формирование {knowledgeContext} в промпте
+```
+
+**Приоритет QA над документами.** Поиск по типам идёт параллельно, но сборка ответа — QA-first: если найдена релевантная QA-пара (≥ `qaMinScore`, прошла reranker) — ответ строится в QA-режиме (QA + документный RAG как дополнение); если подходящей QA нет — чистый документный RAG (`llm-main.service.ts`, ветка «Если НЕ НАШЛИ QA → RAG»). Практический вывод: слишком «широкая» QA перехватывает запросы, которые ты хотел увести в документный RAG. Держи QA-вопросы конкретными (цена, программа, противопоказания), а свободные «симптомные» запросы оставляй документам.
+
+## 11. Inline-пример: namespace для интернет-магазина
+
+### Конфигурация
+
+```json
+{
+  "namespace": {
+    "cleanNamespace": "shop_main",
+    "displayName": "Интернет-магазин",
+    "scopeType": "PLATFORM",
+    "platformId": "<platformId>",
+    "workspaceId": "<workspaceId>",
+    "hasQa": true,
+    "hasDocuments": true,
+    "hasWebsites": true,
+    "hasTables": true,
+    "accessMode": "AUTO_QUERY"
+  },
+  "qaSamples": [
+    {
+      "question": "Какая стоимость доставки?",
+      "answer": "По Москве — 500 руб. в пределах МКАД. ...",
+      "alias": "delivery",
+      "mode": "SIMPLE"
+    },
+    {
+      "question": "Как работает гарантия?",
+      "answer": "Гарантия 1 год на все товары. ...",
+      "alias": "warranty",
+      "mode": "SIMPLE"
+    }
+  ],
+  "documents": [
+    { "filename": "price-list-2026.pdf", "splitMode": "recursive", "chunkSize": 1000 }
+  ],
+  "websites": [
+    { "url": "https://shop.example.com", "chunkSize": 1000 }
+  ],
+  "tables": [
+    {
+      "name": "Каталог товаров",
+      "type": "GOOGLE_SHEETS",
+      "url": "https://docs.google.com/spreadsheets/d/...",
+      "useVectorIndex": true,
+      "vectorTopK": 5
+    }
+  ],
+  "agent": {
+    "name": "main",
+    "knowledgeNamespaces": ["shop_main"],
+    "ragTopK": 3,
+    "ragMinScore": 0.5,
+    "qaMinScore": 0.78
+  }
+}
+```
+
+## 12. Inline-пример: TOOL_ONLY namespace для бронирования услуг
+
+Иногда не нужно искать в базе знаний на каждом сообщении — только когда AI явно решил уточнить (например, услуги/расписание):
+
+```json
+{
+  "namespace": {
+    "cleanNamespace": "services_catalog",
+    "scopeType": "PLATFORM",
+    "accessMode": "TOOL_ONLY",
+    "hasQa": false,
+    "hasTables": true
+  },
+  "agent": {
+    "knowledgeNamespaces": ["services_catalog"],
+    "tools": ["builtin-read_namespaces"]
+  }
+}
+```
+
+Агент получит инструмент `read_namespaces` и будет вызывать его осознанно.
+
+## 13. Граничные случаи и валидация
+
+| Правило | Что AI-сервису помнить |
+|---|---|
+| `cleanNamespace` уникален в `(workspaceId, ?platformId)` | Зависит от `scopeType`. |
+| Pinecone-имена (`pineconeQa/Doc/...`) генерируются системой | Не пытаться задавать вручную. |
+| Документы загружаются асинхронно | `status` пройдёт через несколько стадий, прежде чем `COMPLETED`. До этого RAG может не работать. |
+| QA с `isCallQaOnly=true` не векторизуется | Доступна только через `call_qa(alias)`. Хорошо для готовых медиа-ответов. |
+| `mode=STRICT` отдаёт answer дословно | LLM не перефразирует. Подходит для legal/юридических текстов. |
+| QA `alias` уникален в `(workspaceId)` | Не дублировать. |
+| `ragTopK` слишком большой → шум | Реалистично 3–5. |
+| `qaMinScore` — баланс recall/точности | Дефолт **0.45** = широкий recall, точность даёт LLM-reranker. Без reranker (мало QA) держи выше (0.6–0.8), иначе ложные срабатывания. |
+| `RERANKER` агент опционален | Если в namespace мало QA — можно без него. Если QA много (200+) — желательно. |
+| `accessMode=TOOL_ONLY` без инструмента `read_namespaces` | Бесполезно — агент не сможет искать. |
+| WebsiteKnowledge — отдельный воркфлоу | Краулинг через очередь, AI-сервис обычно не задаёт его — даёт URL администратору. |
+| `KnowledgeTable.useVectorIndex=false` | Каждый запрос ходит во внешнюю Google Sheets API — медленно. Включать только для маленьких таблиц. |
+| Cross-platform namespace | Workspace-namespace + `PlatformNamespace` для каждой платформы, которая должна видеть. |
+
+## 14. Workbook ingestion — загрузка из xlsx/Google Sheets
+
+Помимо обычной загрузки документов через UI (multipart upload), Animaly умеет автоматически препарировать **рабочие книги** (xlsx-файлы или Google Sheets с несколькими листами) в `KnowledgeDocument`/`Qa`/`KnowledgeTable` через workbook-adapter. Этот flow задумывался для AI-ассистента типа Claude Code: пользователь даёт ссылку на табличку, AI-ассистент классифицирует каждый лист и решает, что куда отправить.
+
+### 14.1. Модель `SourceWorkbook`
+
+```json
+{
+  "id": "uuid",
+  "workspaceId": "<workspaceId>",
+  "kind": "XLSX_UPLOAD",                       // или "GOOGLE_SHEETS"
+  "storedFileId": "<StoredFile.id>",           // для XLSX_UPLOAD
+  "googleSpreadsheetId": null,                  // для GOOGLE_SHEETS
+  "canonicalUrl": "https://docs.google.com/...",
+  "originalTitle": "Каталог 2026.xlsx",
+  "classification": [
+    {
+      "sheetTitle": "Prices",
+      "sheetGid": 0,
+      "detectedKind": "price_table",
+      "destination": "knowledge_table",
+      "mappedEntityId": "<KnowledgeTable.id>",
+      "notes": "Прайс на основные позиции — индексировать через vector"
+    },
+    {
+      "sheetTitle": "FAQ",
+      "sheetGid": 12345,
+      "detectedKind": "qa_pairs",
+      "destination": "qa",
+      "mappedEntityId": null,
+      "notes": "Q&A для импорта через besales_knowledge_qa_create"
+    }
+  ],
+  "importedBy": "<userId or null>",            // null если impersonated MCP key
+  "importedBySource": "MCP_KEY",                // "USER" / "MCP_KEY"
+  "importedAt": "2026-05-27T10:00:00Z",
+  "archivedAt": null                            // soft delete
+}
+```
+
+| Поле | Описание |
+|---|---|
+| `kind` | enum `SourceWorkbookKind`: `XLSX_UPLOAD` (multipart файл) или `GOOGLE_SHEETS` (по URL) |
+| `classification` | Json-массив с per-sheet решениями AI-ассистента. Формат: `{sheetTitle, sheetGid, detectedKind, destination, mappedEntityId?, notes?}` |
+| `importedBySource` | enum `ImportedBySource`: `USER` (через UI/auth user) или `MCP_KEY` (через impersonated MCP key — `importedBy` может быть `null`) |
+| `archivedAt` | Soft delete. Записи остаются в БД для аудита |
+
+### 14.2. Новые поля `KnowledgeDocument`
+
+```json
+{
+  "id": "uuid",
+  "filename": "FAQ_Prices.md",
+  "source": "AI_INGESTED",                     // или "USER_UPLOAD" (default)
+  "sourceWorkbookId": "<SourceWorkbook.id>",   // null для USER_UPLOAD
+  "sourceSheetTitle": "Prices",                // какой лист породил
+  ...
+}
+```
+
+| Поле | Тип | Дефолт | Описание |
+|---|---|---|---|
+| `source` | enum `DocumentSource` | `USER_UPLOAD` | `USER_UPLOAD` — обычный multipart upload через UI; `AI_INGESTED` — создан workbook-adapter'ом из листа `SourceWorkbook` |
+| `sourceWorkbookId` | uuid? | `null` | FK на `SourceWorkbook.id` (`onDelete: SetNull`). Заполнено для `AI_INGESTED`-документов |
+| `sourceSheetTitle` | string? | `null` | Имя листа, из которого извлечён документ. Partial unique index по `(workspaceId, sourceWorkbookId, sourceSheetTitle) WHERE source = 'AI_INGESTED'` — гарантирует идемпотентный re-ingest одного и того же листа |
+
+### 14.3. Flow workbook ingestion
+
+```
+1. UI/CLI/MCP: upload xlsx → /api/v2/files → storedFileId
+   (или: pass Google Sheets URL целиком)
+   ↓
+2. POST /api/v2/workspaces/:wsId/workbooks/inspect
+   { storedFileId? | googleSheetsUrl? }
+   → server читает структуру всех листов (sample max 50 rows + hyperlink stats)
+   → upsert SourceWorkbook (workspaceId, kind, …)
+   ↓
+3. AI-ассистент (Claude Code / GPT) локально классифицирует листы:
+   - price_table → knowledge_table
+   - qa_pairs → qa
+   - product_descriptions → knowledge_document
+   - amocrm_leads_export → POST /workbooks/:id/extract-amocrm-leads (вернёт массив leadId)
+   - dialogue_corpus → ICP analysis (см. spec icp)
+   - feedback_sheet → FeedbackSheet (см. 31-google-sheets-feedback.md)
+   ↓
+4. PATCH /workbooks/:id/classification { classification: [...] }
+   → server сохраняет решение в SourceWorkbook.classification
+   ↓
+5. Per-sheet actions (по решению AI):
+   - POST /workbooks/:id/knowledge-document
+     → создаёт KnowledgeDocument с source=AI_INGESTED + auto-detect splitMode
+   - besales_knowledge_qa_create (для qa-пар из листа)
+   - besales_knowledge_table_link (для таблиц)
+   ↓
+6. POST /workbooks/:id/archive — soft delete после полной обработки
+```
+
+### 14.4. Auto-detect splitMode при `POST /workbooks/:id/knowledge-document`
+
+Workbook-adapter использует heuristic для выбора `splitMode` нового документа на основе структуры листа:
+
+| Heuristic | splitMode выбирается |
+|---|---|
+| 2 колонки, первая короткая, вторая длинная | `qa` (Q&A pairs) |
+| Заголовки строк `## ...` или `=== ...` | `heading` (по заголовкам) |
+| Абзацы разделены пустыми строками | `paragraph` |
+| Нумерованные пункты `1.`, `2.`, ... | `numbered` |
+| Fallback (структура не распознана) | `fixed-size` (с дефолтным `chunkSize`) |
+
+### 14.5. MCP tools для workbook ingestion
+
+| Tool | Endpoint | Назначение |
+|---|---|---|
+| `besales_workbook_inspect` | POST `/workbooks/inspect` | Загрузить структуру + создать SourceWorkbook |
+| `besales_workbook_extract_amocrm_leads` | POST `/workbooks/:id/extract-amocrm-leads` | Извлечь все leadId (regex `.amocrm.ru/leads/` + `/api/v4/`) — hard cap 10000 строк |
+| `besales_workbook_to_knowledge_document` | POST `/workbooks/:id/knowledge-document` | Создать KnowledgeDocument из листа |
+
+### 14.6. Ограничения
+
+| Лимит | Значение |
+|---|---|
+| Sample строк при `inspect` | 50 |
+| Hard cap строк при `extract-amocrm-leads` | 10 000 |
+| Cross-tenant защита | `SourceWorkbook.workspaceId` фиксирован owner-ом; повторный ingest того же файла в другой workspace создаёт новую запись |
+| Идемпотентность re-ingest | Partial unique index гарантирует, что повторный `to-knowledge-document` для того же `(workspaceId, sourceWorkbookId, sourceSheetTitle)` обновит существующий документ, а не создаст дубль |
+
+### 14.7. Когда AI-сервис использует workbook ingestion
+
+- Клиент даёт большую табличку с прайсом, FAQ, описаниями товаров — AI-сервис не пытается распарсить вручную, а вызывает `inspect` → классифицирует → `to-knowledge-document`.
+- Клиент даёт Google Sheets с выгрузкой лидов AmoCRM (например, для прогрева через ICP-анализ) — AI вызывает `extract-amocrm-leads`, затем `besales_icp_import_dialogues` с полученными leadId.
+- Клиент даёт лист с testing feedback — AI вызывает `besales_feedback_sheet_link` (см. [`31-google-sheets-feedback.md`](31-google-sheets-feedback.md)).
+
+## 15. Связь с другими подсистемами
+
+| Подсистема | Связь |
+|---|---|
+| **Агенты** ([`01-agents.md`](01-agents.md)) | `knowledgeNamespaces[]`, `ragTopK`, `ragMinScore`, `qaMinScore`. |
+| **Промпт** ([`02-prompt-anatomy.md`](02-prompt-anatomy.md)) | `{knowledgeContext}`, `{knowledgeInstructions}`. |
+| **Инструменты** ([`03-tools-catalog.md`](03-tools-catalog.md)) | `builtin-read_namespaces` для `TOOL_ONLY`, `builtin-call_qa` для QA-aliases. |
+| **Триггеры** ([`04-triggers-and-actions.md`](04-triggers-and-actions.md)) | `READ_NAMESPACES` action — RAG-поиск через триггер. |
+| **AgentSpecialized** ([`01-agents.md`](01-agents.md)) | `RERANKER` для QA, опционально. |
+| **Файлы** ([`17-files-and-uploads.md`](17-files-and-uploads.md)) | `SourceWorkbook.storedFileId` указывает на `StoredFile` (xlsx upload). |
+| **Google Sheets feedback** ([`31-google-sheets-feedback.md`](31-google-sheets-feedback.md)) | Workbook с тестировщиками может быть размечен как feedback-sheet для linker'а |