telegram-cli-bot/TOOLS.md

🛠️ Инструменты 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 — синглтон, который хранит все доступные инструменты:

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 анализирует сообщение пользователя и решает, какой инструмент использовать:

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.

Использование:

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

Использование:

# Получить новости
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.

Использование:

result = await tools_registry.execute_tool(
    'ssh_tool',
    command='uptime',
    server='home',
    timeout=30
)

Конфигурация серверов:

# Серверы настраиваются в 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 — каждую неделю

Использование:

# Добавить задачу
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:

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:

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:

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

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

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.