@besales/mcp 0.1.0 → 0.12.0

package/dist/resources/concepts/feedback-sheets.md

@@ -0,0 +1,77 @@
+# Google Sheets Feedback Integration
+
+Владелец платформы может привязать к промпту агента Google Sheets-таблицу, в которой
+тестировщики оставляют замечания о работе агента. Ты читаешь эти замечания и предлагаешь
+правки промпта.
+
+## Инструменты
+
+- `besales_feedback_sheet_link` — привязать таблицу к промпту агента по ссылке.
+- `besales_feedback_sheet_list` — список таблиц, привязанных к агенту.
+- `besales_feedback_sheet_read` — прочитать строки замечаний.
+- `besales_feedback_sheet_unlink` — отвязать таблицу от агента.
+- `besales_feedback_sheet_row_update` — отметить статус строк в таблице (editable).
+
+## Когда привязывать
+
+Если пользователь прислал ссылку на Google Sheet (`docs.google.com/spreadsheets/...`) с
+замечаниями и хочет, чтобы они учитывались в промпте — вызови `besales_feedback_sheet_link`
+с `agent_id` нужного агента и `source_url`. Один файл можно привязать к нескольким промптам:
+повторный вызов с другим `agent_id` создаёт ещё одну привязку, дубликата файла не возникает.
+
+В ответе придёт `serviceAccountEmail` — попроси пользователя расшарить таблицу на этот email
+(Viewer достаточно для чтения). Без расшаривания чтение вернёт ошибку доступа.
+
+Поддерживаются только нативные Google Sheets. Ссылка на `.xlsx`/`.csv` в Google Drive вернёт
+ошибку — попроси пользователя открыть файл как Google Sheet.
+
+## Когда читать
+
+Перед тем как улучшать промпт по замечаниям тестировщиков, вызови
+`besales_feedback_sheet_list` для агента — узнать, есть ли привязанные таблицы. Затем для
+каждой таблицы вызови `besales_feedback_sheet_read` по её `feedbackSheet.id`. Tool вернёт
+распарсенные строки (`headers` + `rows` с `rowNumber`, `rowHash`, `cells`). Не проси
+содержимое таблицы у пользователя вручную — оно уже доступно через эти tools.
+
+## Режимы — различай по `accessMode`
+
+**`READ_ONLY`** — у тебя нет прав на запись в файл. Воркфлоу:
+1. `besales_feedback_sheet_read` → проанализируй замечания, сгруппируй по смыслу.
+2. Сформулируй конкретные правки промпта.
+3. `besales_prompt_iterate_get_instructions` — замечания тестировщиков положи в
+   `feedback.general_comments` и `feedback.selections`.
+4. Локально выполни stages → `besales_prompt_iterate_submit` → покажи пользователю preview.
+5. **Дождись подтверждения пользователя** → `besales_prompt_finalize`.
+
+Никогда не финализируй промпт без явного согласия пользователя. В файл при `READ_ONLY`
+ничего не пиши — доступа нет.
+
+**`EDITABLE`** — у тебя есть права на запись. Воркфлоу тот же по части правки промпта, плюс
+после обработки замечаний отметь их статус прямо в таблице через
+`besales_feedback_sheet_row_update`:
+
+1. Для каждой обработанной строки передай `row_number`, `row_hash` (из последнего
+   `besales_feedback_sheet_read`), `status` (`done` / `in_progress` / `wont_fix` /
+   `needs_clarification`) и при необходимости `comment` («что сделано / что не хватает»).
+2. Backend запишет статус и комментарий в служебные колонки и подсветит строку светлой
+   заливкой (зелёная — done, жёлтая — needs_clarification, голубая — in_progress, серая —
+   wont_fix).
+3. Если строки таблицы сдвинулись между чтением и записью — придёт ошибка `409`. Перечитай
+   таблицу через `besales_feedback_sheet_read` и повтори с актуальными `row_hash`.
+
+Если запись недоступна (service account не настроен) — `besales_feedback_sheet_row_update`
+вернёт понятную ошибку «запись недоступна, доступно только чтение». В этом случае работай в
+read-only режиме: читай замечания и предлагай правки промпта, статусы в файл не пиши.
+
+## Безопасность
+
+- Не вписывай в комментарии к таблице секреты, токены или ключи.
+- Не меняй ячейки с исходными замечаниями тестировщиков — пиши только в служебные колонки
+  статуса/комментария.
+- Если `besales_feedback_sheet_read` вернул ошибку доступа — таблица не расшарена на service
+  account. Сообщи пользователю email из ответа `link` и попроси выдать доступ.
+
+## Отвязка
+
+Если пользователь просит перестать учитывать таблицу для промпта — `besales_feedback_sheet_unlink`.
+Это убирает только привязку к этому агенту; для других промптов таблица продолжит работать.

package/dist/resources/concepts/sandbox.md

@@ -12,6 +12,19 @@ Sandbox в Besales — это контролируемый прогон аген
 4. Локально выполнить stages: сгруппировать проблемы, оценить severity, предложить улучшения.
 5. Отправить результат через `besales_sandbox_findings_submit`.
 
+## Режимы клиента: scripted и simulated
+
+Прогон поддерживает два режима клиента (`options.client_mode`):
+
+- **`scripted`** (по умолчанию) — реплики клиента берутся из заранее записанных `situations` сценария и проигрываются дословно. Детерминировано — годится для regression-проверок «не сломал ли промпт известный кейс».
+- **`simulated`** — backend-LLM отыгрывает персону из ICP: видит ответ агента и генерит следующую реплику клиента вживую. Диалог адаптивный и реалистичный, но **недетерминированный** — для regression-diff не подходит, годится для охвата и проверки отработки возражений.
+
+Один прогон = один режим. «Прогнать оба режима» = два вызова `besales_sandbox_run_start`.
+
+**Правило для Claude:** когда пользователь просит «запусти sandbox / прогон», сначала **уточни режим** — scripted, simulated или оба (по умолчанию предлагай оба). Молча режим не выбирай. Заодно уместно уточнить охват сценариев (все или часть).
+
+В findings: если симулированный клиент ушёл с `outcome: refused` или `endReason: gave_up` — это не автоматически провал агента; оценивай по тексту диалога.
+
 Sandbox не должен обращаться к реальным channel adapters и не должен создавать внешние side effects. Если сценарий требует проверки CRM или отправки сообщений, backend должен использовать sandbox adapters/ports или mock behavior.
 
 Практическое правило: sandbox — это безопасная проверка качества агента. Claude должен использовать его перед финализацией рискованных prompt changes, особенно если ICP содержит несколько сегментов или есть новые handoff/routing правила.

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

@@ -0,0 +1,241 @@
+# Workbook Ingestion & Classification (v1.5)
+
+Заказчик присылает многотабличный xlsx или Google Sheets — например, файл
+«Сухбатлар тахлили 100+100» от компании ASLZAR с 7 вкладками: индекс диалогов
+с гиперссылками на amoCRM, выборка «Хорошие/Плохие разговоры» с оценками,
+вкладка «Критерии общения» с правилами для оператора, толстая вкладка
+«Регламенты продаж» с описанием товаров, и т.д.
+
+Твоя задача — открыть источник, классифицировать **каждую вкладку** по типу
+содержимого и разложить её в правильный слой системы (промпт / facts /
+KnowledgeDocument / ICP samples). Структура файла у разных заказчиков
+**разная** — не предполагай фиксированный schema, классификируй по содержимому.
+
+## Архитектурные слои
+
+| Слой | Где хранится | Что туда кладётся | Когда применяется |
+|---|---|---|---|
+| **A. Поведение** | `AgentChat.baseSystemPrompt` | компактные правила (1–5k chars) | каждый запрос |
+| **B. Активные факты** | `AgentChat.factualContext` (≤2K токенов) | компактное продуктовое знание | каждый запрос |
+| **C. Сырое знание** | `KnowledgeDocument` + chunks + Pinecone | бульк-знание (>8k) | через RAG, когда namespace привязан к агенту |
+| **D. Provenance** | `SourceWorkbook` | исходный xlsx/GS + классификация | metadata, audit |
+
+Цель: **A и B** — компактные, разумные по размеру; **C** — куда уезжает всё
+большое, чтобы не раздувать каждый запрос. **D** хранит исходник чтобы
+можно было пересмотреть классификацию без повторной загрузки от пользователя.
+
+## Шаг 1 — Загрузка файла (только для xlsx)
+
+Для Google Sheets — сразу шаг 2 с URL.
+
+Для xlsx:
+1. Залей файл через **существующий files endpoint** (`POST /api/v2/files` с
+   multipart) — это **не** workbook MCP tool, это общий files upload.
+2. В ответе получишь `storedFileId`.
+
+Сам workbook MCP **не** загружает файлы — он только инспектирует уже
+загруженные. Это разделение позволяет переиспользовать SourceWorkbook для
+повторных inspect'ов того же файла.
+
+## Шаг 2 — Inspect
+
+```
+besales_workbook_inspect({
+  stored_file_id?: <uuid>,
+  google_sheets_url?: <url>,
+  sample_rows_per_sheet?: 10,
+  max_cells_total?: 500,
+})
+```
+
+В ответе:
+- `workbook` — создан `SourceWorkbook` record;
+- `sheets[]` — для каждой вкладки: `sheetTitle`, `rowCount`, `columnCount`,
+  `sampleRows[][]` (per-cell `value` + `hyperlink` + `formula`),
+  `hyperlinkStats[]` (per-column число amoCRM lead/contact ссылок),
+  `truncated` (применён ли лимит).
+
+**Если Google Sheets вернул 403 (`error: google_sheets_not_shared`)** — покажи
+пользователю `serviceAccountEmail` из response и попроси расшарить таблицу
+на этот email (Viewer достаточно для чтения). Без этого никакие операции не
+будут работать.
+
+## Шаг 3 — Классификация (твоя голова)
+
+Для каждой вкладки определи `detectedKind` по содержимому. Известные типы и
+куда направлять:
+
+| `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'ов |
+| `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) |
+| `followup_sequence` | последовательность сообщений с тайм-задержками | `besales_followup_sequence_upsert` |
+| `tester_feedback` | построчные замечания тестировщиков к промпту | `besales_feedback_sheet_link` (привязка конкретной вкладки) |
+| `metadata_summary` | сводка/dashboard со статистикой | игнор, пометить в `classification` |
+| `tasks_log` | мета-вкладка типа «что нужно подготовить» | игнор |
+| `unknown` | не подходит ни под одну категорию | спроси у пользователя через `AskUserQuestion` с 2-3 вариантами |
+
+**Одна вкладка может попасть в несколько kind'ов одновременно.** Пример:
+«Хорошие разговоры» = `dialogue_corpus_with_amocrm_links` (для audio import) +
+`tester_feedback` (Изох-колонка с комментариями рецензента). Делай обе вещи.
+
+## Шаг 4 — Распознавай параллельные колонки
+
+Если в `behavior_rules` вкладке видишь **2 структурно-параллельные колонки**
+(например, в ASLZAR-файле «Sotuv mezonlari» / «Qayta qo'ng'iroq mezonlari» —
+правила первого звонка vs правила повторного), это **сильный сигнал** что
+нужно сделать:
+
+- 2 агента — по одному на каждую колонку;
+- роутер на trigger:
+  - агент A (Sotuv) → срабатывает на новый лид / inbound;
+  - агент B (Qayta qo'ng'iroq) → срабатывает на noresponse > N дней / outbound.
+
+Перед тем как создавать — спроси пользователя через `AskUserQuestion`:
+«Я вижу 2 параллельных набора правил. Хочешь 1 универсального агента или
+2 + router?». По его ответу — либо `besales_agent_create` + `besales_router_update`
++ `besales_trigger_upsert`, либо склей в один промпт.
+
+## Шаг 5 — Извлечение lead_ids из диалог-индекса (regex локально)
+
+Для `dialogue_corpus_with_amocrm_links` — **не зови отдельный MCP tool**. Данные
+уже в `inspect` response (`sampleRows[][]`). Прогони regex по `cell.value`,
+`cell.hyperlink`, `cell.formula`:
+
+```
+/https?:\/\/[\w-]+\.amocrm\.ru\/leads\/detail\/(\d+)/   → leadId
+/https?:\/\/[\w-]+\.amocrm\.ru\/contacts\/detail\/(\d+)/ → contactId
+```
+
+Поддерживается любой amoCRM поддомен (`aslzar`, `acme-crm`, и т.д.). Если в
+inspect-sample слишком мало строк — попроси `inspect` повторно с большим
+`sample_rows_per_sheet` (до 50). Если и этого мало — обрати внимание что для
+больших таблиц извлечение в полном объёме сейчас не покрыто отдельным
+helper-tool'ом; в Phase 1 это покрывается доступным sample'ом.
+
+## Шаг 6 — `besales_workbook_to_knowledge_document` (bulk knowledge)
+
+```
+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)
+})
+```
+
+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` — отключи только если знаешь зачем.
+
+После создания документа — **привяжи knowledge_space к агенту** через
+`besales_agent_update` (поле `knowledge_space_ids` — массив UUID, полученных из
+`besales_knowledge_space_list` или ответа `besales_workbook_to_knowledge_document`),
+иначе агент не увидит namespace даже когда RAG будет включён.
+
+## Шаг 7 — Compact knowledge → factualContext (твоя голова + facts_set)
+
+Для `product_knowledge_compact` НЕ зови `besales_workbook_to_knowledge_document`.
+Вместо этого:
+
+1. Прочитай sample вкладки из `inspect` response.
+2. Сам сделай LLM-выжимку: возьми ключевые факты, сожми в markdown ≤8k chars.
+   Формат:
+   ```
+   ## Active facts
+   - факт 1
+   - факт 2
+   - ...
+   ```
+3. Вызови существующий `besales_agent_facts_set` с этой выжимкой.
+
+Это **другой** MCP tool, не workbook. Не путай.
+
+## Шаг 8 — Зафиксируй классификацию
+
+После того как все вкладки разобраны:
+
+```
+PATCH /api/v2/workspaces/:wsId/workbooks/:id/classification
+body: {
+  classification: [
+    { sheetTitle: "Свод", detectedKind: "metadata_summary", destination: "ignored" },
+    { sheetTitle: "Все разговоры", detectedKind: "dialogue_corpus_with_amocrm_links",
+      destination: "icp_import", mappedEntityId: "<icp-run-id>", notes: "124 leadId извлечено" },
+    { sheetTitle: "Критерии общения", detectedKind: "behavior_rules",
+      destination: "prompt", notes: "2 параллельные колонки → 2 агента + router" },
+    { sheetTitle: "Регламенты продаж", detectedKind: "product_knowledge_bulk",
+      destination: "knowledge_document", mappedEntityId: "<kd-id>" },
+    { sheetTitle: "Задачи", detectedKind: "tasks_log", destination: "ignored" }
+  ]
+}
+```
+
+Это даёт audit trail («откуда взялся этот факт») и позволяет потом
+переразложить при необходимости.
+
+## Шаг 9 — Архивация (когда больше не нужен)
+
+`POST /api/v2/workspaces/:wsId/workbooks/:id/archive` — soft delete.
+KnowledgeDocument'ы остаются (благодаря `onDelete: SetNull`), просто теряют
+ссылку на workbook. Hard delete для SourceWorkbook не предусмотрен —
+provenance не должна теряться.
+
+## Пример полного flow на файле ASLZAR
+
+> Заказчик прислал `Сухбатлар тахлили 100+100-2.xlsx` (7 вкладок).
+
+1. User загружает xlsx через `/api/v2/files` → `storedFileId = abc123`.
+2. `besales_workbook_inspect({stored_file_id: "abc123"})` →
+   - `workbook.id = wb-1` создан
+   - 7 вкладок: Свод (6 строк), Все разговоры (435 строк), Плохие (101),
+     Хорошие (130), Критерии (68), Регламенты (420), Задачи (8)
+   - hyperlinkStats для «Все разговоры» колонка C: 124 amocrmLeads
+3. Локальная классификация в твоей голове:
+   - Свод → `metadata_summary` (ignore)
+   - Все разговоры → `dialogue_corpus_with_amocrm_links`
+   - Хорошие/Плохие → дополняют как `dialogue_corpus_*` с `defaultOutcome=won/lost`
+   - Критерии → `behavior_rules` (2 параллельные колонки!)
+   - Регламенты → `product_knowledge_bulk` (53k chars)
+   - Задачи → `tasks_log` (ignore)
+4. Regex по sampleRows[Все разговоры].column[2] → 124 leadId.
+5. `besales_icp_import_dialogues mode=audio audio_source_type=amocrm_leads` с
+   этими leadId.
+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"})`.
+9. `besales_agent_update` — добавить knowledge_space_id в `knowledge_space_ids` агента (UUID, не cleanNamespace).
+10. `PATCH /workbooks/wb-1/classification` — зафиксировать решения.
+
+## Что НЕ делать
+
+- ❌ Не пытайся сам парсить xlsx — используй `besales_workbook_inspect`.
+- ❌ Не запихивай **всё** в `factualContext` — 2K токенов лимит, иначе раздуешь
+  каждый запрос инференса. Большие материалы → в KnowledgeDocument.
+- ❌ Не создавай агентов / промпты / документы без подтверждения user'а для
+  high-impact операций (новый агент, router rule).
+- ❌ Не пытайся найти tool типа `besales_workbook_to_facts` — его нет. Compact
+  knowledge ты сам сжимаешь LLM-вызовом и кладёшь через `besales_agent_facts_set`.