Telegram CLI Bot

Бот для выполнения CLI команд на вашем ПК через Telegram с многоуровневым меню и гибкой настройкой.

Версия: 0.8.0

Возможности

• 🖥️ Выполнение CLI команд - запуск любых команд от имени пользователя
• 📋 Многоуровневое меню - навигация через inline-кнопки
• ⚙️ Настройка из бота - изменение имени, описания, иконки прямо в диалоге
• 🎯 Предустановленные команды - готовые команды для файловой системы, поиска, системы и сети
• 👥 Управление доступом - ограничение круга пользователей
• 🔧 Легкое добавление команд - простая регистрация новых команд через код
• 🧠 ИИ-агент с памятью - чат с Qwen Code с контекстом и семантическим поиском
• 🔍 Векторная память - поиск по истории диалогов на ChromaDB (RAG)
• 📦 Автоматическая установка - скрипт install.sh ставит все зависимости

---

🚀 Быстрый старт

1. Установка (первый запуск)

cd /path/to/telegram-cli-bot
./install.sh

Скрипт автоматически:

• Проверит Python, pip, Node.js, npm
• Установит qwen-code (для ИИ-агента)
• Создаст виртуальное окружение
• Установит все зависимости
• Создаст .env из примера

2. Настройка

Отредактируйте .env и укажите токен бота:

nano .env
# TELEGRAM_BOT_TOKEN=ваш_токен_от_BotFather

3. Запуск

./run.sh

---

🔧 Установка как systemd сервис (автозапуск)

Для работы бота в фоновом режиме и автоматического запуска после перезагрузки:

1. Настройка .env

Убедитесь что .env файл существует и содержит все необходимые переменные:

cp .env.example .env
nano .env

2. Установка сервиса

sudo ./install-systemd-service.sh

Скрипт:

• Создаст systemd сервис в /etc/systemd/system/telegram-bot.service
• Включит автозапуск при загрузке
• Настроит логирование через journalctl

3. Управление сервисом

# Запуск
sudo systemctl start telegram-bot

# Остановка
sudo systemctl stop telegram-bot

# Перезапуск
sudo systemctl restart telegram-bot

# Статус
sudo systemctl status telegram-bot

# Автозапуск при загрузке
sudo systemctl enable telegram-bot

# Просмотр логов
sudo journalctl -u telegram-bot -f

---

📦 Подробная установка

Требования

• Python 3.10+
• pip (менеджер пакетов Python)
• Node.js 18+ (для qwen-code, опционально)
• npm (менеджер пакетов Node.js)

Шаг 1: Клонирование

cd /home/mirivlad/git
git clone <repository_url> telegram-cli-bot
cd telegram-cli-bot

Шаг 2: Запуск установщика

./install.sh

Что делает install.sh:

Шаг	Действие
1	Проверяет Python, pip
2	Проверяет Node.js, npm (предлагает установить если нет)
3	Устанавливает qwen-code через npm install -g
4	Создаёт/обновляет venv
5	Устанавливает pip зависимости из requirements.txt
6	Создаёт .env из .env.example (если нет)
7	Сохраняет версию в .installed

Шаг 3: Настройка .env

# Отредактируйте .env
nano .env

Обязательные параметры:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
ALLOWED_USERS=ваш_telegram_id

Ваш Telegram ID можно узнать через @userinfobot.

Шаг 4: Запуск

./run.sh

---

🔄 Обновление

# Просто запустите установщик снова
./install.sh

Скрипт определит что это обновление и:

• Обновит qwen-code
• Обновит pip зависимости
• Сохранит новую версию

---

Команды бота

Команда	Описание
/start	Запустить бота, показать главное меню
/help	Показать справку
/settings	Открыть настройки бота

Главное меню

• 🖥️ Выполнить команду - ввод произвольной CLI команды
• 📋 Предустановленные команды - меню с готовыми командами
• ⚙️ Настройки бота - конфигурация бота
• ℹ️ О боте - информация о боте

Предустановленные команды

Файловая система

• ls -la - список файлов
• pwd - текущая директория
• df -h - свободное место
• du -sh * - размер папок

Поиск

• find . -name - поиск файлов
• grep пример - поиск по содержимому
• which command - путь к командам

Система

• top -n 1 - процессы
• ps aux - список процессов
• free -h - использование памяти
• uname -a - информация о системе
• uptime - время работы

Сеть

• ip addr - сетевые интерфейсы
• ping google - проверка связи
• netstat - сетевые подключения
• curl ifconfig.me - внешний IP

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

Через меню ⚙️ Настройки бота:

1. 📝 Изменить имя бота - новое отображаемое имя
2. 📄 Изменить описание - описание бота
3. 🎨 Изменить иконку - emoji для бота
4. 👥 Управление доступом - whitelist пользователей

Добавление новых команд

Быстрое добавление через меню

Найдите функцию init_menus() в bot.py и добавьте новую кнопку:

# В нужное меню добавьте:
MenuItem("🔥 Ваша команда", "cmd_your", command="ваша_команда", icon="🔥"),

Пример добавления команды для git:

# В init_menus() добавьте новое меню:
git_menu = [
    MenuItem("git status", "cmd_git_status", command="git status", icon="📊"),
    MenuItem("git log", "cmd_git_log", command="git log --oneline -10", icon="📜"),
    MenuItem("⬅️ Назад", "preset", icon="⬅️"),
]
menu_builder.add_menu("git", git_menu)

# И добавьте кнопку в preset_menu:
MenuItem("🔗 Git", "git_menu", icon="🔗"),

Продвинутое: регистрация через декоратор

Используйте command_registry для сложной логики:

@command_registry.register("my_command")
async def my_custom_command(update, context):
    # Ваша логика
    pass

Конфигурация

Все настройки хранятся в файле .env:

# Токен бота
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

# Настройки бота
BOT_NAME=CLI Assistant
BOT_DESCRIPTION=Бот для выполнения CLI команд
BOT_ICON_EMOJI=🤖

# Разрешённые пользователи (список ID через запятую)
# Пустой список = доступ открыт для всех
ALLOWED_USERS=123456789,987654321

# Рабочая директория для команд
WORKING_DIRECTORY=/home/user

Параметр	Описание
TELEGRAM_BOT_TOKEN	Токен бота от @BotFather
BOT_NAME	Отображаемое имя бота
BOT_DESCRIPTION	Описание бота
BOT_ICON_EMOJI	Emoji-иконка
ALLOWED_USERS	Список разрешённых user ID через запятую (пусто = все)
WORKING_DIRECTORY	Рабочая директория для выполнения команд

Настройка GigaChat API (Сбер)

Бот поддерживает альтернативный AI-провайдер — GigaChat от Сбера. Для использования:

1. Получите credentials в SberDevices Developer Portal
2. Добавьте в .env:

# GigaChat API (Сбер)
GIGACHAT_CLIENT_ID=ваш-client-id-uuid
GIGACHAT_CLIENT_SECRET=ваш-client-secret
GIGACHAT_SCOPE=GIGACHAT_API_PERS
GIGACHAT_AUTH_URL=https://ngw.devices.sberbank.ru:9443/api/v2/oauth
GIGACHAT_MODEL=GigaChat-Pro

3. Перезапустите бота

Параметры:

Параметр	Описание
GIGACHAT_CLIENT_ID	ID клиента (UUID из SberDevices Portal)
GIGACHAT_CLIENT_SECRET	Секрет клиента
GIGACHAT_SCOPE	Область доступа (обычно GIGACHAT_API_PERS)
GIGACHAT_AUTH_URL	URL авторизации OAuth
GIGACHAT_MODEL	Модель: GigaChat-Pro или GigaChat-Max

Инструмент GigaChat:

• gigachat — генерация ответов через GigaChat API
• Используется как альтернатива Qwen Code
• Поддерживает системные промпты, температуру, лимит токенов

Настройка YandexGPT API (Яндекс)

Для использования YandexGPT добавьте в .env:

# YandexGPT API (Яндекс)
YANDEX_FOLDER_ID=ваш-folder-id
YANDEX_API_KEY=ваш-api-key
YANDEX_MODEL=yandexgpt/latest

Получите credentials в Yandex Cloud Console.

⚠️ Важно: После изменения .env требуется перезапуск бота.

Безопасность

⚠️ Важные предупреждения:

1. Бот выполняет команды от имени запустившего пользователя
2. Не запускайте бота от root
3. Ограничьте доступ через ALLOWED_USERS в .env:

   ALLOWED_USERS=123456789,987654321
   

   Ваш ID можно узнать через @userinfobot
4. Будьте осторожны с деструктивными командами (rm, dd, etc.)
5. Никогда не передавайте файл .env — он содержит токен бота
6. Добавьте .env в .gitignore (уже сделано)

Логи

Логи сохраняются в bot.log в директории бота.

Структура проекта

telegram-cli-bot/
├── bot.py                      # Точка входа (1411 строк)
├── bot/                        # Модульная структура
│   ├── config.py               # Конфигурация и глобальные объекты
│   ├── models/                 # Модели данных
│   │   ├── server.py           # Server, ServerManager
│   │   ├── session.py          # SSH/Local сессии и менеджеры
│   │   └── user_state.py       # UserState, StateManager
│   ├── utils/                  # Утилиты
│   │   ├── cleaners.py         # Очистка ANSI-кодов
│   │   ├── formatters.py       # Форматирование сообщений
│   │   ├── decorators.py       # Декоратор @check_access
│   │   └── ssh_readers.py      # Чтение SSH/PTY вывода
│   ├── keyboards/              # Клавиатуры
│   │   └── menus.py            # MenuItem, MenuBuilder
│   ├── handlers/               # Обработчики событий
│   │   ├── commands.py         # /start, /menu, /help, /settings
│   │   └── callbacks.py        # Callback от меню
│   └── services/               # Бизнес-логика
│       └── command_executor.py # Выполнение CLI команд
├── memory_system.py            # Система памяти (SQLite)
├── vector_memory.py            # Векторная память (ChromaDB + RAG)
├── qwen_integration.py         # Интеграция с Qwen Code
├── install.sh                  # Универсальный установщик
├── run.sh                      # Скрипт запуска
├── requirements.txt            # Зависимости Python
├── .env                        # Конфигурация (не коммитить!)
├── .env.example                # Пример конфигурации
├── bot.log                     # Лог файл
└── README.md                   # Документация

Модульная архитектура:

• models — модели данных и менеджеры
• utils — вспомогательные функции
• handlers — обработчики команд Telegram
• services — бизнес-логика выполнения команд
• keyboards — построение inline-клавиатур

Требования

• Python 3.10+
• Node.js 18+ (опционально, для qwen-code)
• Библиотеки: python-telegram-bot, chromadb, sentence-transformers
• Доступ к Telegram API

Лицензия

MIT