TKBK Studio
TKBK Studio
Отвечает клиентам по вашим документам через Claude, а сложные вопросы передаёт операторам в Telegram
Бот первой линии поддержки для интернет-магазинов, сервисов и онлайн-школ. Вы кладёте в папку knowledge/ обычные текстовые файлы — условия доставки, оплаты, возврата, FAQ, — а бот отвечает клиентам по ним с помощью Claude через TKBK API.
Бот отвечает строго по базе: если ответа нет, модель не уверена или клиент просит живого человека, вопрос уходит в чат операторов с кнопками «Ответить» и «Закрыть». Оператор отвечает реплаем — клиент получает ответ в том же чате с ботом. Журнал /unanswered показывает, чего не хватает в базе знаний.
Поиск по базе — BM25 на чистом Python, без векторных баз и тяжёлых библиотек; данные — в SQLite на вашем сервере. Защита бюджета: лимит вопросов на клиента, приветствия без запроса к ИИ, повторы при сбоях API.
Для кого: Интернет-магазины, сервисы, онлайн-школы, служба поддержки
Ключи и токены не вводятся на сайте — их кладут в файл .env на своём сервере.
BOT_TOKENТокен бота — @BotFather → /newbotADMIN_CHAT_IDЧат операторов — Добавьте бота в группу и отправьте /id; для проверки — ваш ID у @userinfobotTKBK_API_KEYКлюч TKBK API — Личный кабинет tkbk.onlineTKBK_MODELМодель (переопределить) — claude-haiku-4-5 или claude-sonnet-5RATE_LIMIT_PER_HOURЛимит вопросов к ИИ в час на клиента — По умолчанию 30# {{BRAND}} — AI-бот поддержки в Telegram
Бот отвечает клиентам по вашей базе знаний (файлы в папке `knowledge/`) с помощью нейросети Claude через TKBK API.
Если ответа в базе нет, бот не уверен или клиент просит живого человека — вопрос уходит в чат операторов,
а оператор отвечает обычным реплаем. Все вопросы без ответа попадают в журнал `/unanswered` — по нему удобно дополнять базу.
## Что умеет
- **Ответы строго по базе знаний**: бот находит подходящие фрагменты (поиск BM25 на чистом Python, понимает формы слов)
и просит модель отвечать только по ним — без выдуманных цен и сроков.
- **Передача оператору**: по кнопке «👤 Позвать человека», по фразам «позовите оператора», когда модель не уверена
или в базе нет ответа. Режим из мастера: передавать сразу (`auto`) или спрашивать клиента (`ask`).
- **Чат операторов**: обращение приходит с кнопками «✍️ Ответить» и «✅ Закрыть»; ответ реплаем на любое сообщение
обращения уходит клиенту (текст, фото, файлы). Пока обращение открыто, сообщения клиента идут операторам.
- **Журнал вопросов без ответа** — `/unanswered`, открытые обращения — `/tickets`, перечитать базу без перезапуска — `/reload`.
- **Память диалога** (3 последних вопроса) — понимает уточнения вроде «а сколько это стоит?».
- **Защита бюджета**: не больше 30 вопросов к ИИ в час от одного клиента, приветствия и «спасибо» — без запроса к ИИ,
повторы при сбоях API с паузами.
## Запуск за 5 минут
### 1. Получите токены
| Что | Где взять |
|---|---|
| `BOT_TOKEN` | [@BotFather](https://t.me/BotFather) → `/newbot` → имя и юзернейм → скопируйте токен |
| `ADMIN_CHAT_ID` | Чат операторов: создайте группу, добавьте бота, отправьте в группе `/id`. Для проверки подойдёт ваш личный ID от [@userinfobot](https://t.me/userinfobot) |
| `TKBK_API_KEY` | Ключ TKBK API в личном кабинете [tkbk.online](https://tkbk.online) |
Скопируйте `.env.example` в `.env` и впишите значения.
### 2а. Запуск в Docker
```bash
docker compose up -d --build
docker compose logs -f # смотреть логи
```
Папка `knowledge/` подключена с диска: поправьте файлы и отправьте боту `/reload` в чате операторов.
### 2б. Запуск без Docker (Python 3.12+)
```bash
python -m venv .venv
# Windows: .venv\Scripts\activate Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python -m app
```
## База знаний
Положите в `knowledge/` файлы `.md` или `.txt` (можно в подпапках). В шаблоне лежат примеры — замените их своими.
- Делите текст заголовками `# …` — каждый раздел становится отдельным фрагментом.
- Пишите короткими абзацами: один вопрос — один абзац. Указывайте точные цифры, сроки, адреса.
- Названия разделов делайте похожими на вопросы клиентов: «Доставка в регионы», «Возврат денег».
- После правок — `/reload` в чате операторов (или перезапуск бота). Смотрите `/unanswered` и дописывайте недостающее.
## Команды
| Команда | Где | Что делает |
|---|---|---|
| `/start`, `/human` | у клиента | приветствие, позвать человека |
| `/tickets` | чат операторов | открытые обращения |
| `/close 12` | чат операторов | закрыть обращение |
| `/unanswered` | чат операторов | вопросы без ответа за 30 дней |
| `/reload` | чат операторов | перечитать папку `knowledge/` |
| `/id` | везде | ID текущего чата |
## Проверка
```bash
pip install -r requirements.txt pytest==9.1.1
pytest
```
Тесты проверяют поиск по базе, нарезку файлов, промпт, разбор ответа модели, повторы, лимиты и распознавание
просьбы позвать человека.
## Структура
```
app/
__main__.py запуск бота
config.py настройки: .env + значения из мастера (модель, тексты, правила для ИИ)
search.py токены, стемминг, BM25 (чистая логика)
knowledge.py чтение knowledge/, нарезка на фрагменты, поиск
llm.py TKBK API (Anthropic Messages API), промпт, память диалога, лимиты
db.py SQLite: обращения и вопросы без ответа
support.py вопросы клиентов: ответ ИИ или передача оператору
operators.py чат операторов: ответы реплаем, /tickets, /unanswered, /reload
tickets.py создание обращений и пересылка сообщений
keyboards.py кнопки
knowledge/ база знаний (.md, .txt)
```
## FAQ
**Бот не видит ответы операторов в группе.** Отвечайте именно реплаем на сообщение бота (или нажмите «✍️ Ответить»).
Если не помогает — сделайте бота администратором группы или отключите Group Privacy в @BotFather → Bot Settings.
**Команды в группе не срабатывают.** Пишите их с именем бота: `/tickets@имя_бота`.
**Бот слишком часто зовёт оператора.** Дополните базу по журналу `/unanswered`, разбейте длинные тексты на разделы
с понятными заголовками. Модель Sonnet отвечает точнее, чем Haiku.
**Ошибка «TKBK API отклонил запрос (HTTP 401)».** Проверьте `TKBK_API_KEY` и баланс в личном кабинете.
**Сколько это стоит?** Каждый ответ — один запрос к модели с найденными фрагментами базы. Приветствия, «спасибо»
и вопросы без совпадений в базе нейросеть не тратят.
**Где хранятся данные?** В SQLite: `data/support.db` (в Docker — том `support-data`). История диалога хранится
в памяти и сбрасывается при перезапуске.
Услуги, мастера, свободные окна на 14 дней, напоминания за сутки и за 2 часа, предоплата и отзывы
Оценка 0–10 после заказа: довольных — на Яндекс Карты, 2ГИС и WB, недовольных — сразу к менеджеру
Оплата звёздами или картой, одноразовые ссылки, напоминания о продлении и автоисключение по окончании