364 lines
13 KiB
Markdown
364 lines
13 KiB
Markdown
# Telegram CLI Bot
|
||
|
||
Бот для выполнения CLI команд на вашем ПК через Telegram с многоуровневым меню и гибкой настройкой.
|
||
|
||
**Версия:** 0.7.0
|
||
|
||
## Возможности
|
||
|
||
- 🖥️ **Выполнение CLI команд** - запуск любых команд от имени пользователя
|
||
- 📋 **Многоуровневое меню** - навигация через inline-кнопки
|
||
- ⚙️ **Настройка из бота** - изменение имени, описания, иконки прямо в диалоге
|
||
- 🎯 **Предустановленные команды** - готовые команды для файловой системы, поиска, системы и сети
|
||
- 👥 **Управление доступом** - ограничение круга пользователей
|
||
- 🔧 **Легкое добавление команд** - простая регистрация новых команд через код
|
||
- 🧠 **ИИ-агент с памятью** - чат с Qwen Code с контекстом и семантическим поиском
|
||
- 🔍 **Векторная память** - поиск по истории диалогов на ChromaDB (RAG)
|
||
- 📦 **Автоматическая установка** - скрипт install.sh ставит все зависимости
|
||
|
||
---
|
||
|
||
## 🚀 Быстрый старт
|
||
|
||
### 1. Установка (первый запуск)
|
||
|
||
```bash
|
||
cd /path/to/telegram-cli-bot
|
||
./install.sh
|
||
```
|
||
|
||
Скрипт автоматически:
|
||
- Проверит Python, pip, Node.js, npm
|
||
- Установит qwen-code (для ИИ-агента)
|
||
- Создаст виртуальное окружение
|
||
- Установит все зависимости
|
||
- Создаст .env из примера
|
||
|
||
### 2. Настройка
|
||
|
||
Отредактируйте `.env` и укажите токен бота:
|
||
|
||
```bash
|
||
nano .env
|
||
# TELEGRAM_BOT_TOKEN=ваш_токен_от_BotFather
|
||
```
|
||
|
||
### 3. Запуск
|
||
|
||
```bash
|
||
./run.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 Установка как systemd сервис (автозапуск)
|
||
|
||
Для работы бота в фоновом режиме и автоматического запуска после перезагрузки:
|
||
|
||
### 1. Настройка .env
|
||
|
||
Убедитесь что `.env` файл существует и содержит все необходимые переменные:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
nano .env
|
||
```
|
||
|
||
### 2. Установка сервиса
|
||
|
||
```bash
|
||
sudo ./install-systemd-service.sh
|
||
```
|
||
|
||
Скрипт:
|
||
- Создаст systemd сервис в `/etc/systemd/system/telegram-bot.service`
|
||
- Включит автозапуск при загрузке
|
||
- Настроит логирование через journalctl
|
||
|
||
### 3. Управление сервисом
|
||
|
||
```bash
|
||
# Запуск
|
||
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: Клонирование
|
||
|
||
```bash
|
||
cd /home/mirivlad/git
|
||
git clone <repository_url> telegram-cli-bot
|
||
cd telegram-cli-bot
|
||
```
|
||
|
||
### Шаг 2: Запуск установщика
|
||
|
||
```bash
|
||
./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
|
||
|
||
```bash
|
||
# Отредактируйте .env
|
||
nano .env
|
||
```
|
||
|
||
Обязательные параметры:
|
||
```bash
|
||
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
|
||
ALLOWED_USERS=ваш_telegram_id
|
||
```
|
||
|
||
Ваш Telegram ID можно узнать через @userinfobot.
|
||
|
||
### Шаг 4: Запуск
|
||
|
||
```bash
|
||
./run.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 Обновление
|
||
|
||
```bash
|
||
# Просто запустите установщик снова
|
||
./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` и добавьте новую кнопку:
|
||
|
||
```python
|
||
# В нужное меню добавьте:
|
||
MenuItem("🔥 Ваша команда", "cmd_your", command="ваша_команда", icon="🔥"),
|
||
```
|
||
|
||
### Пример добавления команды для git:
|
||
|
||
```python
|
||
# В 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` для сложной логики:
|
||
|
||
```python
|
||
@command_registry.register("my_command")
|
||
async def my_custom_command(update, context):
|
||
# Ваша логика
|
||
pass
|
||
```
|
||
|
||
## Конфигурация
|
||
|
||
Все настройки хранятся в файле `.env`:
|
||
|
||
```bash
|
||
# Токен бота
|
||
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` | Рабочая директория для выполнения команд |
|
||
|
||
⚠️ **Важно:** После изменения `.env` требуется перезапуск бота.
|
||
|
||
## Безопасность
|
||
|
||
⚠️ **Важные предупреждения:**
|
||
|
||
1. Бот выполняет команды от имени запустившего пользователя
|
||
2. Не запускайте бота от root
|
||
3. Ограничьте доступ через `ALLOWED_USERS` в `.env`:
|
||
```bash
|
||
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
|