Руководство оператора

Управляйте проектами aichat-go целиком из Telegram

15 админ-команд
10 команд лид-группы
Без доступа к серверу
Только Telegram Без CLI Мультитенантность

Для кого это руководство

Вы управляете одним или несколькими проектами продажного бота через Telegram — создаёте новых ботов, обновляете промты, добавляете контент в базу знаний, смотрите статистику чатов. Доступ по SSH и запуск каких-либо бинарников вручную при этом не требуется.

Все операции с проектами доступны через slash-команды в Telegram-группах. Работа идёт в двух типах групп:

  • Админ-группа — одна особая группа, привязанная к админ-проекту. Из неё можно управлять любым проектом (создавать, наполнять, редактировать, выводить список, удалять). Админ-команды начинаются с /project_.
  • Собственная лид-группа проекта — чат, в который этот проект доставляет лидов. Здесь работают короткие команды (/prompt1, /stats, /info...) и относятся только к текущему проекту.
Примечание. Существует продвинутый инструмент командной строки для скриптинга, массового импорта и восстановления после инцидентов. Намеренно не описан в этом руководстве — см. документацию для разработчиков.

Что должно быть готово

Прежде чем какие-либо команды из этого руководства начнут работать, инженер должен один раз настроить платформу. Проверьте три условия:

  1. Сервис aichat-go запущен и доступен Telegram (вебхук зарегистрирован).
  2. В базе данных существует админ-проект со своим Telegram-ботом.
  3. Этот бот добавлен в Telegram-группу и подтвердил «Лид-группа подключена для проекта «admin»!». Именно эта группа — ваша админ-группа, в которой вы будете вводить все команды ниже.

Если что-то из этого отсутствует, попросите инженера выполнить первичную настройку. Дальше мы исходим из того, что рабочая админ-группа уже есть.

Создание нового проекта

Запуск нового продажного бота — это три шага и пара минут времени. Бот делает почти всё за вас — вы только указываете имя, источник контента и токен Telegram-бота.

1

Создайте бота в BotFather

В Telegram откройте @BotFather и выполните /newbot. Задайте отображаемое имя и уникальный username, заканчивающийся на _bot. BotFather пришлёт токен вида 123456:AAH... — скопируйте его.

2

Выполните /project_init в админ-группе

Выберите короткое имя проекта в нижнем регистре (используется внутри системы и в URL). Затем выберите один из трёх способов задать стартовый контент:

Вариант A — URL карты сайта (sitemap), самый частый

Если у сайта клиента есть sitemap.xml — это самый простой путь: бот автоматически обходит все страницы из карты сайта.

Админ-группа
/project_init acme sitemap https://acme.com/sitemap.xml 123456:AAH...token
Project «acme» created (bot: @acme_bot). Seeding started...
Scraping completed: 42 pages
Chunking completed: 156 chunks
Embeddings completed: 156 vectors
Upload completed: 42 pages, 156 chunks indexed
Project «acme» init finished!
Test the bot: https://t.me/acme_bot
Вариант B — список конкретных URL

Для небольших сайтов или когда нужно проиндексировать только несколько страниц — передавайте URL прямо через запятую.

Админ-группа
/project_init acme urls https://acme.com/services,https://acme.com/pricing,https://acme.com/contacts 123456:AAH...token
Project «acme» created (bot: @acme_bot). Seeding started...
Вариант C — вложенный XML-файл sitemap

Если sitemap не выложен публично (например, экспорт от клиента) — приложите его к сообщению как файл. Бот скачает его и использует как источник для обхода.

Админ-группа
/project_init acme 123456:AAH...token
📎 sitemap.xml
Project «acme» created (bot: @acme_bot). Seeding started...
По завершении бот прикрепляет файл debug_info.txt с подробным журналом пайплайна (и при успехе, и при ошибке). Сохраните его, если что-то выглядит подозрительно — в нём полная трассировка обхода сайта.
Если проект уже существует, вы получите «Project «acme» already exists. Use --force to reinit.» Запуск с --force удаляет записи проекта в БД и коллекции в Qdrant перед пересозданием. Это удаляет всю историю чатов этого проекта. Если нужно только обновить базу знаний — используйте /project_seed.
3

Подключите лид-группу проекта по deep-ссылке

После наполнения базы знаний бот пришлёт deep-ссылку вида https://t.me/<bot>?startgroup=connect_<name>. Кликните по ней — Telegram откроет окно «создать / выбрать группу» с уже добавленным ботом. Создайте новую группу (например, «Acme Leads») и нажмите Создать.

Бот автоматически обнаружит группу, привяжет её как лид-группу проекта и подтвердит:

Acme Leads (новая группа)
Лид-группа подключена для проекта «acme»! Лиды будут отправляться сюда.

Используйте /help для просмотра доступных команд.
ID лид-группы вводить не нужно. Бот сам определяет chat ID из сообщения /start connect_<name>, которое Telegram присылает при добавлении бота через deep-ссылку. Если у проекта пока нет лид-группы, доставка лидов приостанавливается с предупреждением.

Проект полностью готов к работе. Клиенты могут писать @acme_bot, а завершённые лиды попадают в группу «Acme Leads».

Повседневные операции

Когда проект уже работает, почти любая задача — это одна команда в админ-группе. В карточках ниже показано, что делает команда и когда её применять. Все админ-команды первым аргументом принимают имя проекта — так из одного места можно управлять несколькими проектами.

15
админ-команд
8
настраиваемых ключей
3
стадии диалога

Промты и цены

Промты задают, что бот говорит на каждой стадии. Настройки цен определяют, как бот отвечает на вопросы о стоимости — либо подтягивая чанки из специальной страницы цен, либо из запасного текстового блока.

/project_prompt1 <name> <text>

Обновить промт 1-й стадии — как бот здоровается, квалифицирует клиента и определяет, какой услугой тот интересуется.

/project_prompt2 <name> <text>

Обновить промт 2-й стадии — как бот отвечает на детальные вопросы по конкретной услуге и собирает контакт.

/project_prompt3 <name> <text>

Обновить промт 3-й стадии (завершение) — финальное сообщение бота перед передачей лида специалисту.

/project_price_url <name> <url>

Отметить URL базы знаний как «страницу цен». Когда бот определил услугу клиента, чанки этой страницы подмешиваются в контекст LLM — чтобы бот мог называть реальные цены.

/project_price_prompt <name> <text>

Запасной текст о ценах — используется, когда price_url не задан или страница цен не описывает запрошенную услугу. Простой текст, бот использует его как есть.

Для повседневного редактирования промтов удобнее использовать собственную лид-группу проекта — короткие команды (/prompt1, /price_url...) не требуют имени проекта и применяются к текущему чату. См. Лид-группа проекта ниже.

База знаний — добавление и удаление URL

База знаний — это то, по чему бот ищет, когда отвечает клиентам. Можно добавлять новые страницы, переиндексировать изменённые и удалять устаревшие — всё без пересоздания проекта.

/project_add_urls <name> <url1,url2,...>

Добавить URL к существующей базе знаний. Бот скачивает каждый, разбивает на чанки, эмбеддит и индексирует поверх уже имеющегося контента.

/project_add_urls --replace-url <name> <url1,url2,...>

То же, но для каждого URL сначала удаляются все существующие чанки этого URL, а потом он переиндексируется. Используйте, когда страница изменилась и нужна свежая копия.

/project_delete_urls <name> <url1,url2,...>

Удалить все чанки указанных URL из базы знаний. Полезно для устаревших услуг или страниц, которые клиент попросил убрать.

Админ-группа — пример
/project_add_urls --replace-url acme https://acme.com/services/audit
Replacing 1 URL(s) for project «acme»...
URLs added to «acme» successfully.

Перезагрузка существующего проекта

Когда сайт клиента поменялся целиком и нужно перезалить базу знаний с нуля — не удаляя сам проект, его историю чатов и промты — используйте /project_seed. Это тот же пайплайн обхода, что и у /project_init, но применённый к уже существующему проекту.

/project_seed <name> sitemap <sitemap-url>

Перезагрузить из свежей карты сайта.

/project_seed <name> urls <url1,url2,...>

Перезагрузить из явного списка URL.

/project_seed <name>

Перезагрузить из вложенного XML-файла sitemap (приложите его к тому же сообщению).

Внимание. /project_seed индексирует новый контент, но не удаляет старые чанки тех URL, которых больше нет в карте сайта. Если нужен жёсткий сброс базы знаний — либо обратитесь к инженеру за продвинутым CLI, либо из Telegram самый простой путь — /project_init --force, который удаляет проект и создаёт заново. (Это также удалит историю чатов.)

Просмотр и статистика

Три команды только-для-чтения, чтобы увидеть, что происходит — как по конкретному проекту, так и по всей платформе.

/projects

Список всех проектов в базе с датой создания. Админ-проект и проекты в состоянии «удалён» помечаются отдельно.

Пример ответа
acme — 2026-02-14
admin — 2026-01-09 [admin]
legacycorp — 2025-11-22 [deleted]
widgets — 2026-03-01
/project_info <name>

Показать UUID проекта, язык, привязку лид-группы и текущие price_url / price_prompt. Полезно убедиться, что проект существует и правильно настроен.

/project_stats <name> [период]

Сводная статистика чатов проекта за период: всего чатов, завершённых, незавершённых (старше 24 часов), среднее число сообщений.

Формат периода — интервал PostgreSQL: 1 month (по умолчанию), 1 week, 3 days, 6 months. Пробел обязателен — 1month не сработает.

Пример ответа на /project_stats acme 1 week
Stats for «acme» (1 week):
Total chats: 87
Finished: 23
Unfinished (>24h): 41
Unfinished total: 64
Avg messages (all): 6.3
Avg messages (finished): 11.8
Avg messages (unfinished): 4.4

Удаление и восстановление проекта

Удаление и восстановление обратимы. Они переключают флаг проекта — данные, история чатов и база знаний остаются в базе. Чтобы изменения стали видны клиентам, инженер перезапускает сервис бота.

/project_delete <name>

Пометить проект как удалённый. После следующего перезапуска бот перестаёт обрабатывать сообщения для бота этого проекта. Сам админ-проект удалить нельзя.

/project_restore <name>

Снять флаг удаления. После перезапуска (или после повторной регистрации проекта инженером) бот снова отвечает на сообщения.

Это не жёсткое удаление. Если нужно полностью вычистить проект — вместе с записями в базе, коллекциями Qdrant и историей чатов — обратитесь к инженеру. Из Telegram доступно только мягкое удаление.

Прочие настройки — /project_set

Одна универсальная команда обновляет любую настройку проекта, у которой нет отдельной команды. Используйте её для приветственного сообщения, языка и смены токена бота.

/project_set <name> <key> <value>

Обновляет одну настройку проекта. Поддерживаемые ключи:

КлючЧто делаетНужен перезапуск?
prompt1 Промт 1-й стадии (синоним /project_prompt1) Нет
prompt2 Промт 2-й стадии Нет
prompt3 Промт 3-й стадии (завершение) Нет
price_url URL, чанки которого подмешиваются в контекст как информация о ценах Нет
price_prompt Запасной текст о ценах, когда нет price_url Нет
start-reply Приветственное сообщение, которое бот возвращает клиенту на /start Нет
tg_api_key Сменить токен Telegram-бота для проекта Да
language Язык проекта — ru или en Да
Админ-группа — примеры
/project_set acme start-reply Здравствуйте! Чем мы можем вам помочь?
Set start-reply for project «acme» (44 chars).
/project_set acme language en
Set language for project «acme» (2 chars). Restart the bot for tg_api_key/language changes to take effect.
Ключи, требующие перезапуска. tg_api_key и language вступают в силу только после перезапуска сервиса — живой бот кэширует эти значения при старте. Попросите инженера перезапустить сервис или дождитесь следующего деплоя.

Команды лид-группы проекта

Внутри собственной лид-группы любого проекта (не админ-группы) доступен сокращённый набор команд. Они всегда применяются к проекту, который владеет этим чатом — имя проекта вводить не нужно.

КомандаЧто делает
/help Показать все команды, доступные в этой группе (а в админ-группе — ещё и админ-команды)
/prompt Показать текущие промты 1, 2 и 3 стадии
/prompt1 [текст] Показать или обновить промт 1-й стадии этого проекта
/prompt2 [текст] Показать или обновить промт 2-й стадии
/prompt3 [текст] Показать или обновить промт 3-й стадии (завершение)
/price_prompt [текст] Показать или установить запасной текст о ценах
/price_url [url] Показать или установить URL страницы цен
/stats [период] Статистика чатов этого проекта (по умолчанию 1 month)
/info Показать UUID проекта, язык, лид-группу, настройки цен
/settings Открыть встроенное меню настроек (кнопки на те же команды)
Если вызвать команду-сеттер без аргументов, она покажет текущее значение. Например, /prompt1 без текста распечатает действующий промт 1-й стадии — удобно посмотреть перед редактированием.
Админ-группа — это тоже лид-группа проекта. Внутри админ-группы работают оба набора команд: короткие управляют самим админ-проектом, а /project_* — всеми остальными.

Что видят клиенты

Для контекста — у клиентов, которые пишут боту, есть всего две команды. Вы их не запускаете — просто чтобы вы понимали, что это такое в логах.

/start

Сбрасывает диалог: очищает текущую историю и состояние чата, после чего возвращает приветственное сообщение проекта (start-reply). Настраивается командой /project_set <name> start-reply ....

/debug

Переключает режим отладки для конкретного чата клиента. В режиме отладки к каждому ответу бота добавляется короткая трассировка (текущая стадия, найденные результаты, оценки) — так видно, почему бот ответил именно так. Состояние сохраняется в чате клиента.

Решение проблем

Частые проблемы и их значение. Если что-то здесь не совпадает с тем, что вы видите — эскалируйте инженеру с прикреплённым файлом debug_info.txt от последнего запуска /project_init или /project_seed.

«Project «X» already exists. Use --force to reinit.»

Либо имя действительно занято, либо предыдущий /project_init завершился частично. Три варианта:

  • Выберите другое имя.
  • Запустите /project_init --force <имя> ... — это удалит существующий проект (записи в БД, коллекции Qdrant, историю чатов) и создаст заново. Это деструктивно.
  • Если нужно только обновить базу знаний — запустите /project_seed <имя> .... Он сохраняет промты, привязку лид-группы и историю чатов.
Бот создан, но не отвечает на тестовые сообщения

Две самые частые причины:

  1. Лид-группа не подключена. Запустите /project_info <имя> и посмотрите на строку «Lead group: not connected». Если так — кликните deep-ссылку из ответа на исходный /project_init и добавьте бота в новую группу. Без лид-группы бот всё равно общается с клиентами, но доставка лидов отключена.
  2. Вебхук не зарегистрирован в Telegram. Если несколько токенов смотрят на один и тот же бэкенд, выигрывает только последний зарегистрированный. Попросите инженера проверить вебхук вашего бота.
«Лид-группа ещё не подключена» в ответе бота

В сообщении бота есть deep-ссылка — кликните по ней. Telegram откроет окно «создать группу с этим ботом». Создайте новую группу — бот сам её обнаружит. Никакого chat ID копировать не нужно.

/project_stats показывает ноль чатов, хотя бот работает

Проверьте аргумент период. Это должен быть PostgreSQL-интервал с пробелом: 1 month, 2 weeks, 3 days, 6 hours. Без пробела (1month) база считает, что в окно ничего не попадает — и вы получаете нули.

Если период не указан — используется 1 month.

Только что выполнил /project_delete, а бот всё равно отвечает клиентам

Мягкое удаление меняет только флаг в базе. Активные бандлы проектов загружены в память бота при старте, поэтому изменение применится только после перезапуска сервиса. Обратитесь к инженеру. /project_restore + перезапуск отменяет удаление.

Поменял язык через /project_set ... language en, а бот всё равно отвечает по-русски

language и tg_api_key — ключи, требующие перезапуска. Активный агент кэширует язык при старте: значение в базе обновлено сразу, но живой бандл держит старое до следующего рестарта. Об этом явно пишется в ответе — попросите инженера перезапустить сервис.

Проект есть в /projects, но команды говорят «not found»

Имена проектов чувствительны к регистру. Скопируйте точное написание из вывода /projects.

Новый проект не появился в /projects сразу после создания инженером

Проекты, созданные не из Telegram (через продвинутый CLI), требуют отдельного шага регистрации, прежде чем работающий бот их подхватит. /project_init из Telegram делает это автоматически, CLI — нет. Попросите инженера зарегистрировать проект.

Глоссарий

Термины, которые встречаются в этом руководстве и в ответах бота.

Проект
Один продажный бот — один тенант. У каждого проекта свой Telegram-бот, промты, база знаний и лид-группа. Идентифицируется коротким уникальным именем, например acme.
Админ-проект
Особый проект, чья лид-группа разрешает запускать команды /project_* по любому другому проекту. Админ-проект ровно один.
Лид-группа
Telegram-группа, привязанная к проекту, в которую попадают завершённые лиды. В этой же группе вы запускаете команды этого проекта. Подключается один раз через deep-ссылку.
База знаний (БЗ)
Проиндексированные страницы и чанки, по которым бот ищет ответы клиентам. Создаётся при /project_init или /project_seed; меняется командами /project_add_urls и /project_delete_urls.
Стадии 1 / 2 / 3
Три фазы продажного диалога. 1-я стадия — приветствие и определение услуги; 2-я — ответы на вопросы и сбор контакта; 3-я — завершение и передача лида специалисту.
Завершён
Чат считается «завершённым» (finished), когда 3-я стадия сформировала лид и бот перестал отвечать. Завершённые чаты с успешной доставкой в CRM помечаются как «lead-sent».
Мягкое удаление
Обратимый флаг проекта. Запись в базе остаётся; бот перестаёт его обрабатывать после перезапуска. Отменяется командой /project_restore.
price_url / price_prompt
Два способа дать боту контекст о ценах. price_url указывает на страницу БЗ, чанки которой подмешиваются по запросу; price_prompt — запасной текст, используемый, когда URL нет или подходящих чанков не нашлось.
start-reply
Приветственное сообщение, которое бот возвращает клиенту на /start. Настраивается командой /project_set <name> start-reply <text>.

aichat-go · Руководство оператора · нажмите t для смены темы