@besales/mcp 0.48.0 → 1.0.0-beta.2

package/dist/resources/concepts/triggers.md

@@ -18,3 +18,11 @@ Trigger — это событие или условие, которое запу
 
 Практическое правило: проектируй и записывай конфигурацию только объявленными MCP tools;
 не обещай немедленный side effect, если инструмент лишь меняет правило на будущее.
+
+## Типизированные аргументы
+
+Объявления аргументов принадлежат действию, значения извлекаются сервером из разговора при
+вызове моделью. В инструменте запуска значения не задаются. Настройка `arguments` необязательна;
+пустой массив снимает объявления, отсутствие поля сохраняет. Подробности и маркеры —
+`besales://docs/trigger-actions`. Карточка клиента — общие поля пространства на переменных;
+служебное действие `client__card` записывает только явно названное и не стирает прежнее пустотой.

package/dist/resources/concepts/workbook-classification.md

@@ -1,4 +1,4 @@
-# Workbook Ingestion & Classification (v1.5)
+# Workbook Ingestion & Classification
 
 Заказчик присылает многотабличный xlsx или Google Sheets — например, файл
 «Сухбатлар тахлили 100+100» от компании ASLZAR с 7 вкладками: индекс диалогов
@@ -15,9 +15,9 @@ KnowledgeDocument / ICP samples). Структура файла у разных
 
 | Слой | Где хранится | Что туда кладётся | Когда применяется |
 |---|---|---|---|
-| **A. Поведение** | `AgentChat.baseSystemPrompt` | компактные правила (1–5k chars) | каждый запрос |
-| **B. Активные факты** | `AgentChat.factualContext` (≤2K токенов) | компактное продуктовое знание | каждый запрос |
-| **C. Сырое знание** | `KnowledgeDocument` + chunks + Pinecone | бульк-знание (>8k) | через RAG, когда namespace привязан к агенту |
+| **A. Поведение** | системный промпт агента | компактные правила (1–5k chars) | каждый запрос |
+| **B. Активные факты** | факты агента (≤2K токенов) | компактное продуктовое знание | каждый запрос |
+| **C. Сырое знание** | `KnowledgeDocument` + chunks + векторный индекс | бульк-знание (>8k) | через RAG, когда namespace привязан к агенту |
 | **D. Provenance** | `SourceWorkbook` | исходный xlsx/GS + классификация | metadata, audit |
 
 Цель: **A и B** — компактные, разумные по размеру; **C** — куда уезжает всё
@@ -29,7 +29,7 @@ KnowledgeDocument / ICP samples). Структура файла у разных
 Для Google Sheets — сразу шаг 2 с URL.
 
 Для xlsx:
-1. Вызови `besales_file_upload_request` и передай человеку полученный browser upload URL.
+1. Вызови `besales_file_upload_request` и передай человеку browser upload URL.
 2. После загрузки проверь `besales_file_upload_status`; из результата возьми `storedFileId`.
 
 Сам workbook MCP **не** загружает файлы — он только инспектирует уже
@@ -49,17 +49,24 @@ besales_workbook_inspect({
 
 В ответе:
 - `workbook` — создан `SourceWorkbook` record;
-- `sheets[]` — для каждой вкладки: `sheetTitle`, `rowCount`, `columnCount`,
-  `sampleRows[][]` (per-cell `value` + `hyperlink` + `formula`),
-  `hyperlinkStats[]` (per-column число amoCRM lead/contact ссылок),
-  `truncated` (применён ли лимит).
-
-`inspect` — только инвентаризация и sample. Для Google Sheets точный total может быть
-неизвестен (`rowCount`/`columnCount = null`, `dimensionsKnown=false`). `readError` означает
-ошибку чтения конкретного листа, а не пустой лист. Дочитывай нужные страницы через
+- `sheets[]` — для каждой вкладки: `title`, `sheetGid`, `rowCount`, `columnCount`,
+  `totalColumnCount`, `headers[]`, `sampleRows[][]`, `columnStats[]`,
+  `truncated`, `rowsTruncated`, `columnsTruncated`, `readError?`.
+
+⚠️ **`sampleRows` — массив строк текста, а не ячеек-объектов.** Каждая ячейка приходит
+только своим текстом; полей вида `value` / `hyperlink` / `formula` в сэмпле НЕТ. Гиперссылки
+переживают чтение лишь в агрегате: `columnStats[]` = `{ columnIndex, header, linkCount }`,
+то есть СКОЛЬКО ячеек колонки несут ссылку — но не какие именно.
+
+⚠️ `truncated` и `columnsTruncated` — разные вещи: первое означает, что бюджет ячеек обрезал
+строки, второе — что колонки за пределом лимита отброшены и лист прочитан НЕ полностью.
+
+`inspect` — инвентаризация и sample. Для полного чтения вызови
 `besales_workbook_sheet_read`: для каждого `columnOffset` пройди строки до
-`scanUpperBoundRowCount`, затем сбрось `rowOffset` в 0 и перейди к `nextColumnOffset` до
-`scanUpperBoundColumnCount`. Пустая страница внутри этой области не означает конец листа.
+`scanUpperBoundRowCount`, затем сбрось `rowOffset` в 0 и перейди к следующему
+`nextColumnOffset`. Пустая страница не завершает обход. `sourceTruncated=true` означает, что
+часть xlsx лежит за parser cap и полную вычитку этим источником доказать нельзя.
+`readError` означает ошибку чтения конкретной вкладки, а не пустой лист.
 
 **Если Google Sheets вернул 403 (`error: google_sheets_not_shared`)** — покажи
 пользователю `serviceAccountEmail` из response и попроси расшарить таблицу
@@ -73,12 +80,12 @@ besales_workbook_inspect({
 
 | `detectedKind` | Когда подходит | → Назначение |
 |---|---|---|
-| `dialogue_corpus_with_amocrm_links` | колонка содержит много amoCRM URL'ов (см. `hyperlinkStats`), есть метки оператора/статуса/оценки | regex'ом извлеки `leadId`'ы → `besales_icp_import_dialogues mode=audio audio_source_type=amocrm_leads` |
-| `dialogue_corpus_text_only` | список диалогов без аудио-ссылок (например, готовые транскрипты) | `besales_icp_import_dialogues mode=text` (если CRM подключён) или ручная подготовка IcpDialogueSample'ов |
+| `dialogue_corpus_with_amocrm_links` | колонка содержит много amoCRM URL'ов (см. `columnStats[].linkCount`), есть метки оператора/статуса/оценки | отложенный аудио-конвейер; текущий импорт по CRM не принимает lead-ID |
+| `dialogue_corpus_text_only` | список диалогов без аудио-ссылок (например, готовые транскрипты) | не направлять в `besales_icp_import_dialogues`: он читает только сохранённую историю рабочего пространства |
 | `behavior_rules` | правила, критерии общения, скрипты, чек-листы | секция системного промпта через `besales_prompt_generate_get_instructions` (передай содержимое в `businessContext`) |
 | `product_knowledge_compact` | компактное (≤8k chars) знание о продукте, политике | **ты сам делаешь LLM-выжимку в markdown** → `besales_agent_facts_set` (существующий tool, НЕ workbook-tool) |
 | `product_knowledge_bulk` | объёмное (>8k) знание (история, описания товаров, регламенты) | `besales_workbook_to_knowledge_document` |
-| `qa_pairs` | строки в формате «Вопрос → Ответ» | `besales_workbook_to_knowledge_document` (heuristic сам выберет Q&A split) |
+| `qa_pairs` | строки в формате «Вопрос → Ответ» | `besales_workbook_to_knowledge_document` (чанкинг — из профиля пространства, не подбирается) |
 | `followup_sequence` | последовательность сообщений с тайм-задержками | `besales_followup_sequence_upsert` |
 | `tester_feedback` | построчные замечания тестировщиков к промпту | `besales_feedback_sheet_link` (привязка конкретной вкладки) |
 | `metadata_summary` | сводка/dashboard со статистикой | игнор, пометить в `classification` |
@@ -108,18 +115,25 @@ besales_workbook_inspect({
 
 ## Шаг 5 — Извлечение lead_ids из диалог-индекса
 
-Для `dialogue_corpus_with_amocrm_links` вызови
-`besales_workbook_extract_amocrm_leads`: он читает вкладку целиком до явного hard cap и
-возвращает координаты найденных ссылок. Не извлекай полный набор из `inspect.sampleRows`.
+Для `dialogue_corpus_with_amocrm_links` зови **`besales_workbook_extract_amocrm_leads`**.
+Своими руками по сэмплу это не делается: сэмпл отдаёт только текст ячеек, а ссылка живёт в
+гиперссылке, которой там нет — по сэмплу вы нашли бы лишь те идентификаторы, что вписаны в
+текст, и молча потеряли остальные.
 
 ```
-/https?:\/\/[\w-]+\.amocrm\.ru\/leads\/detail\/(\d+)/   → leadId
-/https?:\/\/[\w-]+\.amocrm\.ru\/contacts\/detail\/(\d+)/ → contactId
+besales_workbook_extract_amocrm_leads({
+  workbook_id: <uuid>,
+  sheet_title?: "Все разговоры",   // либо sheet_gid (GS), либо sheet_index (xlsx)
+})
 ```
 
-Поддерживается любой amoCRM поддомен (`aslzar`, `acme-crm`, и т.д.). Если
-`truncated=true`, сообщи о hard cap и не называй результат полным. Для иных правил и ссылок
-используй общее постраничное чтение `besales_workbook_sheet_read`.
+Инструмент читает вкладку целиком (потолок 10 000 строк) и возвращает ссылки как
+`{ kind: 'lead' | 'contact', id, subdomain, row, col }`. Поддерживается любой поддомен
+amoCRM. При достижении потолка ответ несёт признак усечения — не считайте усечённый
+результат полным списком.
+
+`columnStats[].linkCount` из `inspect` служит только сигналом «в этой колонке есть ссылки»
+и подсказывает, какую вкладку отдавать в извлечение.
 
 ## Шаг 6 — `besales_workbook_to_knowledge_document` (bulk knowledge)
 
@@ -128,29 +142,67 @@ besales_workbook_to_knowledge_document({
   workbook_id: <uuid>,
   sheet_title?: "Регламенты продаж",
   // или sheet_gid (для GS), или sheet_index (для xlsx)
-  namespace?: "aslzar-product-knowledge",
-  split_override?: { ... },  // опционально, иначе heuristic
-  replace_existing?: true,   // по умолчанию true (idempotency)
+  knowledge_space_id?: <uuid>,  // либо namespace: "Имя пространства"
+  target_knowledge_source_id?: <uuid>,  // явная преемственность: что именно заменяем
+  replace_existing?: true,      // по умолчанию true
 })
 ```
 
+`knowledge_space_id` — **UUID**, а не человеческое имя пространства. Взять его можно из
+`besales_knowledge_space_list`. Вместо него можно передать `namespace` — точное имя
+существующего пространства. Без обоих полей используется пространство с именем `general`.
+Имя не нормализуется и пространство по имени не создаётся: если его нет, вызов получает отказ.
+
 Sheet identifier (`sheet_title` / `sheet_gid` / `sheet_index`) — **в body, не в
 path** (потому что названия вкладок содержат кириллицу и пробелы).
 
-Сервер сам выбирает `splitMode` через эвристику:
-1. Q&A структура (≥3 пар Q:/A:) → separator `\n\n`, maxChunkSize 800
-2. Markdown headers (≥2 строк `^## `) → separator `\n## `, maxChunkSize 1500
-3. `===` / `---` разделители → separator, maxChunkSize 1500
-4. Параграфы (≥3 блоков `\n\n` avg ≥200 chars) → separator `\n\n`, maxChunkSize 1200
-5. Пронумерованные секции (≥3 строк `^\d+[.)]`) → separator `\n\n`, maxChunkSize 1200
-6. Fallback → fixed_size, chunkSize 1000, overlap 200
-
-В ответе `splitDecision.reason` — почему выбран этот режим (для отладки).
-Если знаешь лучше — передай `split_override`.
-
-**Idempotency**: повторный вызов для того же `(workbook, sheet)` заменяет
-существующий AI_INGESTED документ (удаляет старые chunks + Pinecone vectors).
-По умолчанию `replace_existing: true` — отключи только если знаешь зачем.
+⚠️ **Правила разбиения задаются вызовом.** `split_override` (`size` — по размеру куска, `separator` — по
+разделителю, раздел длиннее `max_chunk_size` дорезается) действует и на новый документ, и на замену содержимого;
+ответ `splitDecision` называет применённые правила (`OVERRIDE` либо `GLOBAL_DEFAULT`). Без поля — правила по
+умолчанию, памяти прошлых правил у документа нет. Эвристики выбора разделителя по содержимому вкладки нет, у профилей
+пространства правил разбиения нет.
+
+### Повторный импорт: маршрут НИЧЕГО НЕ УДАЛЯЕТ
+
+Он либо создаёт новый документ, либо заменяет **содержимое** существующего. Прежние чанки
+подменяются атомарно уже при индексации, поэтому поиск всё это время отвечает прежним знанием,
+а имя документа и пространство, куда его перенёс оператор, сохраняются.
+
+Документ-цель выбирается по убыванию уверенности:
+
+1. **`target_knowledge_source_id`**, если передан, — никакого угадывания.
+2. **Доказуемое тождество.** Признак зависит от рода книги: у **Google Sheets** — только
+   стабильный `gid` (заголовок вкладки мутабелен и в поиске цели не участвует), у
+   **загруженного xlsx** — книга и заголовок вкладки; у Google без доступного `gid` цель не
+   ищется вовсе. Ровно одно совпадение — оно и цель; ноль — новый документ; **несколько —
+   отказ 409 со списком `knowledgeSourceIds`, документ НЕ создаётся** (удали лишние либо назови
+   нужный в `target_knowledge_source_id`).
+3. Иначе — **новый документ**, а в ответе `possibleDuplicates` со списком похожих.
+
+⚠️ **Перезалитый xlsx автоматически не опознаётся как «та же книга»** — и это свойство задачи,
+а не недоделка: контрольная сумма бессмысленна при перезаливе отредактированного файла, имя
+файла идентичностью не является. Чтобы обновить прежний документ, возьми его `knowledgeSourceId`
+из `possibleDuplicates` (или из `besales_knowledge_document_list`) и передай в
+`target_knowledge_source_id`. **Удалять прежний документ руками не нужно.**
+
+⚠️ **Сверяй `sheetTitle` у кандидата перед тем, как передать его в `target_knowledge_source_id`.**
+Кандидаты берутся из линии происхождения ЭТОЙ книги (та же Google-таблица либо файл с тем же
+именем), поэтому документов чужих книг там нет — но документы ДРУГИХ вкладок этой книги есть, и
+они там не по ошибке, а на случай переименованной вкладки. Маршрут вкладку цели не проверяет:
+раз ты назвал документ явно, он тебе верит. Указав кандидата с чужой вкладкой, ты перезапишешь
+её содержимое.
+
+Google-таблицы этой проблемы не имеют: `spreadsheetId` и `gid` стабильны, повторный
+`besales_workbook_inspect` той же ссылки приводит к тому же документу автоматически.
+
+Ответ несёт `outcome` (`CREATED` либо `CONTENT_REPLACED`) и `indexingStatus: QUEUED` —
+индексация асинхронна, ответ **не** обещает, что новые чанки уже активны.
+`possibleDuplicates` — только подсказка, она ничего не изменяет; при
+`possibleDuplicatesTruncated: true` кандидатов больше, чем поместилось в список.
+
+`replace_existing: false` отключает шаг 2 — цель не ищется вовсе и всегда создаётся новый
+документ. Сочетать с `target_knowledge_source_id` нельзя: это противоречивые инструкции, маршрут
+их отвергает.
 
 После создания документа — **привяжи knowledge_space к агенту** через
 `besales_agent_update` (поле `knowledge_space_ids` — массив UUID, полученных из
@@ -162,7 +214,7 @@ path** (потому что названия вкладок содержат к
 Для `product_knowledge_compact` НЕ зови `besales_workbook_to_knowledge_document`.
 Вместо этого:
 
-1. Дочитай вкладку через `besales_workbook_sheet_read`; sample из inspect недостаточен.
+1. Дочитай доступные страницы вкладки через `besales_workbook_sheet_read`; sample недостаточен.
 2. Сам сделай LLM-выжимку: возьми ключевые факты, сожми в markdown ≤8k chars.
    Формат:
    ```
@@ -215,7 +267,7 @@ provenance не должна теряться.
    - `workbook.id = wb-1` создан
    - 7 вкладок: Свод (6 строк), Все разговоры (435 строк), Плохие (101),
      Хорошие (130), Критерии (68), Регламенты (420), Задачи (8)
-   - hyperlinkStats для «Все разговоры» колонка C: 124 amocrmLeads
+   - columnStats для «Все разговоры» колонка C: linkCount 124 — сигнал, что вкладку надо отдать в besales_workbook_extract_amocrm_leads
 3. Локальная классификация в твоей голове:
    - Свод → `metadata_summary` (ignore)
    - Все разговоры → `dialogue_corpus_with_amocrm_links`
@@ -223,15 +275,17 @@ provenance не должна теряться.
    - Критерии → `behavior_rules` (2 параллельные колонки!)
    - Регламенты → `product_knowledge_bulk` (53k chars)
    - Задачи → `tasks_log` (ignore)
-4. `besales_workbook_extract_amocrm_leads` по вкладке «Все разговоры» → 124 leadId.
-5. `besales_icp_import_dialogues mode=audio audio_source_type=amocrm_leads` с
-   этими leadId.
+4. `besales_workbook_extract_amocrm_leads({workbook_id: "wb-1", sheet_title: "Все разговоры"})`
+   → 124 leadId (по сэмплу их не собрать — там только текст ячеек); сохранить как
+   классификацию для отложенного аудио-конвейера.
+5. Если нужна текущая текстовая ветка, вызвать `besales_icp_import_dialogues`
+   отдельно по CRM-подключению: она прочитает сохранённые беседы, а не lead-ID из файла.
 6. `AskUserQuestion`: «В Критериях вижу 2 параллельных набора правил (звонок 1
    vs повторный звонок). Хочешь 1 агента или 2 + router?» → ждём ответ.
 7. По ответу: `besales_agent_create` (+роутер если 2), `besales_prompt_generate_*`
    с `businessContext = текст Критериев`.
 8. `besales_workbook_to_knowledge_document({workbook_id: "wb-1",
-   sheet_title: "Регламенты продаж", namespace: "aslzar-product-knowledge"})`.
+   sheet_title: "Регламенты продаж", knowledge_space_id: "<uuid пространства>"})`.
 9. `besales_agent_update` — добавить knowledge_space_id в `knowledge_space_ids` агента (UUID, не cleanNamespace).
 10. `besales_workbook_classification_update` — зафиксировать решения.
 
@@ -242,5 +296,5 @@ provenance не должна теряться.
   каждый запрос инференса. Большие материалы → в KnowledgeDocument.
 - ❌ Не создавай агентов / промпты / документы без подтверждения user'а для
   high-impact операций (новый агент, router rule).
-- ❌ Для записи compact facts нет отдельного workbook-tool. Используй
+- ❌ Для записи compact facts нет отдельного workbook-tool. Compact
   knowledge ты сам сжимаешь LLM-вызовом и кладёшь через `besales_agent_facts_set`.