343 lines
11 KiB
Markdown
343 lines
11 KiB
Markdown
# 🛠️ Инструменты 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`.
|