Skip to content

companion-bot-setup.md

Latest commit

 

History

History
112 lines (90 loc) · 8.62 KB

companion-bot-setup.md

File metadata and controls

112 lines (90 loc) · 8.62 KB
Raw

Настройка companion-бота

setup создаёт локально управляемого companion-бота и минимальное рабочее пространство Telegram. Это привилегированная операция, доступная только в «Сохранённых сообщениях» авторизованного аккаунта. В другом диалоге команда не запускается. Во время активной настройки ответы BotFather и ввод в «Сохранённых сообщениях» обрабатываются как часть настройки, а не как обычные команды.

Во всех примерах <prefix> означает текущий префикс Lavis (по умолчанию ,).

Формы команды

<prefix>setup
<prefix>setup <username_bot>
<prefix>setup auto
<prefix>setup status
<prefix>setup repair
<prefix>setup cancel
  • <prefix>setup запрашивает имя пользователя бота; следующим сообщением в «Сохранённых сообщениях» укажите имя, оканчивающееся на _bot.
  • <prefix>setup <username_bot> показывает план и ждёт точного ответа confirm либо cancel.
  • <prefix>setup auto генерирует имя вида lavis_<16-шестнадцатеричных-символов>_bot и начинает настройку. Если BotFather сообщает, что имя занято, Lavis пробует новые автоматически сгенерированные имена, не более десяти попыток всего.
  • <prefix>setup status показывает сохранённый статус и имя бота, но не токен.
  • <prefix>setup repair продолжает создание ресурсов по сохранённому состоянию.
  • <prefix>setup cancel отменяет текущую локальную интерактивную настройку; он не удаляет уже созданного бота или ресурсы Telegram.

Имя должно состоять из 5–32 ASCII-букв, цифр или _ и оканчиваться на _bot. Команда принимает ровно один аргумент: например, setup start — это попытка использовать имя start, а не отдельная форма запуска.

BotFather и токен

Lavis ведёт последовательный диалог с официальным @BotFather: сначала отменяет его незавершённый диалог, затем создаёт нового бота, передаёт фиксированное отображаемое имя и выбранное имя пользователя. Следующий шаг отправляется только после ответа BotFather. Полученный токен проверяется запросом Bot API getMe; проверенное имя должно совпасть с запрошенным.

Токен — секрет. Не пересылайте ответ BotFather, не публикуйте его в чатах, скриншотах, журналах или Git. Lavis не показывает токен в статусе и использует редактированные диагностические данные; URL Bot API с токеном не попадает в сообщения об ошибках. Токен хранится отдельно от состояния в $XDG_CONFIG_HOME/lavis/companion-bot.token (или $HOME/.config/lavis/companion-bot.token) с правами 0600. Не открывайте этот файл другим пользователям и не добавляйте его в резервные копии общего доступа.

Состояние прогресса находится в $XDG_STATE_HOME/lavis/setup.json (или $HOME/.local/state/lavis/setup.json). Оно не содержит токен; каталог и файлы проверяются как приватные (0700 для каталога, 0600 для файлов).

Создаваемые ресурсы

После проверки токена Lavis создаёт или дополняет следующие ресурсы:

  • forum-супергруппу Lavis с описанием Lavis companion workspace;
  • темы General, Logs и Backups в этой группе;
  • аватар группы из bundled-ассетов Lavis; фото накладывается при каждом provision, включая восстановление через setup repair;
  • приглашение companion-бота в группу;
  • права администратора бота только для управления темами, удаления и закрепления сообщений;
  • папку диалогов Lavis ровно с ботом и companion-группой; флаги автоматического включения групп и ботов отключены.

Lavis использует лимит папок, объявленный Telegram для текущего типа аккаунта, и выбирает свободный безопасный идентификатор, не предполагая фиксированного диапазона. Одноимённая папка, которая не записана как созданная Lavis, считается конфликтом и никогда не заменяется. Порядок всех уже существующих пользовательских и chatlist-папок сохраняется.

Ёмкость папок, продолжение и частичные ошибки

Если Telegram не разрешает ещё одну папку или нет безопасного идентификатора, создание папки не завершается. Уже созданные бот, группа, темы и права не удаляются. Освободите папку в Telegram и выполните <prefix>setup repair в «Сохранённых сообщениях».

Прогресс записывается после каждого успешного удалённого шага. Поэтому сбой сети, перезапуск Lavis или частичная ошибка не должны создавать заново уже записанные ресурсы: после устранения причины используйте <prefix>setup repair. Команда восстанавливает только сохранённое рабочее пространство; без безопасно читаемого состояния или имени бота она не может продолжить работу. Если токен не прошёл проверку или настройка BotFather не завершилась, токен не сохраняется.

Диагностическое примечание

Конструктор 0x7f5defa6 — это messages.invitedUsers, возвращаемый при channels.inviteToChannel; он наблюдался как проблема десериализации во время работы.

Отложенная область

В текущую реализацию намеренно не входят:

  • обработчики команд или сообщений companion-бота;
  • отправка логов, резервных копий или иных данных в темы Logs и Backups;
  • настройка webhook, polling, Bot API updates или внешнего сервиса для бота;
  • изменение профиля бота, команд BotFather, меню, privacy mode или команд бота;
  • управление участниками группы сверх первоначального приглашения и минимальных прав бота;
  • удаление, очистка, переименование или откат созданных бота, группы, тем и папки;
  • отзыв или ротация токена, а также настройка нескольких companion-ботов;
  • автоматическое возобновление после перезапуска без явной команды <prefix>setup repair.