5.0 KiB

Raw Permalink Blame History

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')

Прямой вызов

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

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

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

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

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

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

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

bot/tools/file_system_tool.py

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

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

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

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

5.0 KiB Raw Permalink Blame History Unescape Escape