# 🛠️ Инструменты Telegram CLI Bot

Инструменты — это capabilities, которые бот может использовать **автономно** для выполнения задач пользователя (Agentic AI подход).

## 📋 Архитектура

```
bot/
├── tools/
│   ├── __init__.py       # Реестр инструментов (ToolsRegistry)
│   ├── ddgs_tool.py      # Поиск в интернете через DuckDuckGo
│   ├── rss_tool.py       # Чтение RSS/Atom лент
│   ├── ssh_tool.py       # Выполнение команд по SSH
│   └── cron_tool.py      # Управление задачами по расписанию
└── ai_agent.py           # AI агент для принятия решений
```

## 🏗️ Как это работает

### 1. Реестр инструментов

`ToolsRegistry` — синглтон, который хранит все доступные инструменты:

```python
from bot.tools import tools_registry

# Получить инструмент
tool = tools_registry.get('ddgs_tool')

# Выполнить инструмент
result = await tools_registry.execute_tool('ddgs_tool', query='python tutorial', max_results=5)
```

### 2. AI Агент

`AIAgent` анализирует сообщение пользователя и решает, какой инструмент использовать:

```python
from bot.ai_agent import ai_agent

# Принять решение
decision = await ai_agent.decide("Найди информацию про Python 3.12")

if decision.should_use_tool:
    result = await ai_agent.execute_tool(decision.tool_name, **decision.tool_args)
```

### 3. Автономное использование

Бот **автоматически** проверяет решение агента при обработке сообщений в AI-режиме:

1. Пользователь пишет сообщение в AI-режиме
2. Бот проверяет триггеры (ключевые слова)
3. Если найден триггер → выполняет инструмент
4. Возвращает результат пользователю

## 📦 Доступные инструменты

### 🔍 DDGS Search (`ddgs_tool`)

Поиск информации в интернете через DuckDuckGo.

**Использование:**
```python
result = await tools_registry.execute_tool(
    'ddgs_tool',
    query='python async await',
    max_results=10
)
```

**Триггеры для авто-использования:**
- "найди", "поиск", "погугли", "узнай"
- "что нового", "последние новости"
- "как сделать", "руководство", "tutorial"
- "что такое", "как работает", "где найти"

**Примеры:**
```
Пользователь: Найди информацию про Rust programming
Бот: 🔍 **Результаты поиска:**
     1. **Rust - Official Website**
        https://www.rust-lang.org
        Rust is a programming language ...
```

### 📰 RSS Reader (`rss_tool`)

Чтение RSS/Atom новостных лент.

**Действия:**

| Действие | Описание | Параметры |
|----------|----------|-----------|
| `fetch` | Получить свежие новости | - |
| `list` | Показать новости | `limit`, `feed_id`, `search`, `undigested_only` |
| `add_feed` | Добавить ленту | `url`, `title` |
| `list_feeds` | Список лент | - |
| `mark_digest` | Отметить как прочитанное | `news_id` |

**Использование:**
```python
# Получить новости
result = await tools_registry.execute_tool(
    'rss_tool',
    action='list',
    limit=10,
    undigested_only=True
)

# Добавить ленту
result = await tools_registry.execute_tool(
    'rss_tool',
    action='add_feed',
    url='https://lwn.net/headlines/newrss',
    title='LWN.net'
)
```

**Триггеры для авто-использования:**
- "новости", "rss", "лента", "feed"
- "дайджест", "что нового в linux"
- "новости it", "tech news"
- "почитай новости", "свежие статьи"

**Примеры:**
```
Пользователь: Почитай новости
Бот: 📰 **Последние новости:**
     1. Linux Kernel 6.8 Released
        📅 2024-03-10 14:30:00
        🔗 https://...
```

### 🖥️ SSH Executor (`ssh_tool`)

Выполнение команд на удалённых серверах по SSH.

**Использование:**
```python
result = await tools_registry.execute_tool(
    'ssh_tool',
    command='uptime',
    server='home',
    timeout=30
)
```

**Конфигурация серверов:**
```python
# Серверы настраиваются в ssh_tool.py
servers = {
    'home': {
        'host': '192.168.1.54',
        'port': 22,
        'username': 'mirivlad',
        'password': '***'
    }
}
```

**Триггеры для авто-использования:**
- "выполни команду", "ssh", "запусти на сервере"
- "проверь сервер", "посмотри логи"
- "покажи процесс", "сколько места", "df", "top"
- "systemctl", "journalctl", "uptime"

**Примеры:**
```
Пользователь: Проверь нагрузку на сервере
Бот: 🖥️ **SSH: home**
     **Команда:** `uptime`
     
     **Вывод:**
     ```
     14:30:00 up 10 days,  2:30,  1 user,  load average: 0.15, 0.10, 0.05
     ```
     
     ✅ **Успешно**
```

### ⏰ Cron Manager (`cron_tool`)

Управление периодическими задачами пользователя.

**Действия:**

| Действие | Описание | Параметры |
|----------|----------|-----------|
| `list` | Показать все задачи | - |
| `add` | Добавить задачу | `name`, `command`, `schedule` |
| `remove` | Удалить задачу | `job_id` |
| `toggle` | Включить/выключить | `job_id`, `enabled` |
| `run` | Выполнить немедленно | `job_id` |

**Форматы расписаний:**
- `*/5 * * * *` — каждые 5 минут
- `@hourly` — каждый час
- `@daily` — каждый день
- `@weekly` — каждую неделю

**Использование:**
```python
# Добавить задачу
result = await tools_registry.execute_tool(
    'cron_tool',
    action='add',
    name='Daily Backup',
    command='/home/user/backup.sh',
    schedule='@daily'
)
```

**Триггеры для авто-использования:**
- "напомни", "запланируй", "каждый день"
- "периодически", "по расписанию", "автоматически"
- "создай задачу", "добавь в cron"

**Примеры:**
```
Пользователь: Напомни мне каждый день делать бэкап
Бот: ⏰ **Ваши задачи:**

     ✅ **Daily Backup**
        Команда: `/home/user/backup.sh`
        Расписание: @daily
        Следующий запуск: 2024-03-11 00:00:00
```

## ➕ Добавление нового инструмента

1. Создайте файл `bot/tools/your_tool.py`:

```python
from bot.tools import BaseTool, ToolResult, register_tool

@register_tool
class YourTool(BaseTool):
    name = "your_tool"
    description = "Описание инструмента"
    category = "category"

    async def execute(self, **kwargs) -> ToolResult:
        # Логика инструмента
        return ToolResult(success=True, data={'result': 'data'})
```

2. Инструмент автоматически зарегистрируется в реестре

3. Добавьте триггеры в `bot/ai_agent.py`:

```python
YOUR_TRIGGERS = ['триггер1', 'триггер2']

def _should_use_your_tool(self, message: str) -> tuple[bool, float]:
    message_lower = message.lower()
    for trigger in YOUR_TRIGGERS:
        if trigger in message_lower:
            return True, 0.9
    return False, 0.0
```

4. Добавьте форматирование в `bot.py`:

```python
elif tool_name == 'your_tool':
    return f"Результат: {result.data}"
```

## 🔧 Установка зависимостей

```bash
cd ~/git/telegram-cli-bot
pip install -r requirements.txt
```

## 🎯 Приоритеты инструментов

Приоритет проверки (от высшего к низшему):

1. **SSH Executor** — системные задачи
2. **Cron Manager** — планирование задач
3. **DDGS Search** — поиск информации
4. **RSS Reader** — чтение новостей

## 📝 Примеры использования

### Поиск в интернете

```
Пользователь: Найди информацию про Python 3.12
Бот: 🔍 **Результаты поиска:**
     1. **Python 3.12.0 Documentation**
        https://docs.python.org/3.12/
        The official home of the Python Programming Language
```

### Чтение новостей

```
Пользователь: Почитай новости
Бот: 📰 **Последние новости:**
     1. Linux Kernel 6.8 Released
        📅 2024-03-10 14:30:00
        🔗 https://...
```

### SSH команда

```
Пользователь: Проверь нагрузку на сервере
Бот: 🖥️ **SSH: home**
     **Команда:** `uptime`
     
     **Вывод:**
     ```
      14:30:00 up 10 days,  2:30,  1 user,  load average: 0.15, 0.10, 0.05
     ```
     
     ✅ **Успешно**
```

### Управление задачами

```
Пользователь: Напомни мне каждый день делать бэкап
Бот: ⏰ **Ваши задачи:**

     ✅ **Daily Backup**
        Команда: `/home/user/backup.sh`
        Расписание: @daily
        Следующий запуск: 2024-03-11 00:00:00
```

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

Для персонального бота приоритет на **удобстве и функциональности**:
- Инструменты доступны всегда
- Бот использует их без прямой команды
- Agentic AI — бот сам решает когда нужен инструмент

**Важно:** При добавлении новых серверов в SSH не забывайте обновлять конфигурацию в `bot/tools/ssh_tool.py`.