141 lines
5.0 KiB
Markdown
141 lines
5.0 KiB
Markdown
# 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
|