# 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` | Рабочая директория для выполнения команд |

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

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

1. Получите credentials в [SberDevices Developer Portal](https://developers.sber.ru/docs/ru/gigachat)
2. Добавьте в `.env`:

```bash
# 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`:

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

Получите credentials в [Yandex Cloud Console](https://cloud.yandex.ru/docs/fundamentals/concepts/infrastructure).

⚠️ **Важно:** После изменения `.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