# File System Tool - Документация

## 📋 Описание

Инструмент для работы с файловой системой Linux. Позволяет AI-агенту (Qwen Code или GigaChat) выполнять операции с файлами и директориями.

## 🎯 Доступные операции

| Операция | Описание | Параметры |
|----------|----------|-----------|
| `read` | Чтение файла | `path`, `limit` (макс. строк) |
| `write` | Запись в файл | `path`, `content`, `append` |
| `copy` | Копирование файла/директории | `source`, `destination` |
| `move` | Перемещение/переименование | `source`, `destination` |
| `delete` | Удаление файла/директории | `path`, `recursive` |
| `mkdir` | Создание директории | `path`, `parents` |
| `list` | Список файлов в директории | `path`, `show_hidden` |
| `info` | Информация о файле | `path` |
| `search` | Поиск файлов по паттерну | `path`, `pattern`, `max_results` |
| `shell` | Выполнение shell-команды | `command`, `timeout` |

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

Инструмент имеет систему проверки путей:

### Разрешённые пути (можно читать/записывать):
- Домашняя директория пользователя (`/home/mirivlad`)
- `/tmp`
- `/var/tmp`

### Запрещённые пути (только чтение с ограничениями):
- `/etc`, `/usr`, `/bin`, `/sbin`
- `/boot`, `/dev`, `/proc`, `/sys`
- Корень `/` (кроме разрешённых поддиректорий)

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

### Через AI-агента (автоматически)

```
Пользователь: "прочитай файл /home/mirivlad/test.txt"
AI-агент → file_system_tool(operation='read', path='/home/mirivlad/test.txt')
```

### Прямой вызов

```python
from bot.tools.file_system_tool import FileSystemTool

tool = FileSystemTool()

# Чтение файла
result = await tool.execute(operation='read', path='/path/to/file.txt')

# Запись файла
result = await tool.execute(
    operation='write',
    path='/path/to/file.txt',
    content='Содержимое файла'
)

# Копирование
result = await tool.execute(
    operation='copy',
    source='/source/file.txt',
    destination='/dest/file.txt'
)

# Список директории
result = await tool.execute(
    operation='list',
    path='/home/mirivlad'
)
```

## 🤖 Интеграция с AI-провайдерами

### GigaChat

GigaChat использует текстовый формат для вызова инструментов:

````
```tool
{"name": "file_system_tool", "arguments": {"operation": "read", "path": "/tmp/test.txt"}}
```
````

### Qwen Code

Qwen Code поддерживает нативные tool calls через stream-json.

## 📊 Триггеры для активации

AI-агент автоматически активирует `file_system_tool` при обнаружении триггеров:

### Прямые триггеры:
- "прочитай файл", "покажи файл", "открой файл"
- "создай файл", "запиши в файл", "сохрани"
- "скопируй файл", "перемести файл", "удали файл"
- "создай директорию", "создай папку"
- "список файлов", "что в папке"
- "найди файл", "поиск файла"

### Команды Unix:
- `cat `, `ls `, `mkdir `, `cp `, `mv `, `rm `, `touch `

## ⚠️ Ограничения

1. **Безопасность**: Нельзя записывать/удалять в системных директориях
2. **Размер файлов**: При чтении ограничено 100 строками (настраивается через `limit`)
3. **Shell команды**: Разрешены только безопасные команды (`ls`, `cat`, `cp`, `mv`, `rm`, `mkdir`, `find`, `grep`, etc.)
4. **Таймаут**: Для shell команд таймаут 30 секунд по умолчанию

## 🔄 История операций

Инструмент сохраняет историю последних 100 операций для отладки:

```python
tool._operation_history  # Список последних операций
```

## 📁 Расположение

```
bot/tools/file_system_tool.py
```

## 🔧 Добавление в реестр

Инструмент автоматически регистрируется при импорте:

```python
from bot.tools import file_system_tool  # Авто-регистрация
```

---

**Версия:** 1.0  
**Совместимость:** Telegram CLI Bot 0.7.1+  
**AI-провайдеры:** Qwen Code, GigaChat