Инструменты файловой системы Qwen Code
Qwen Code предоставляет комплексный набор инструментов для взаимодействия с локальной файловой системой. Эти инструменты позволяют модели читать, записывать, перечислять, искать и изменять файлы и директории, всё под вашим контролем и, как правило, с подтверждением для чувствительных операций.
Примечание: Все инструменты файловой системы работают в пределах rootDirectory (обычно это текущая рабочая директория, из которой вы запустили CLI) в целях безопасности. Пути, которые вы указываете этим инструментам, как правило, должны быть абсолютными или будут разрешены относительно этой корневой директории.
1. list_directory (ReadFolder)
list_directory выводит список имен файлов и подкаталогов, находящихся непосредственно в указанном пути к каталогу. При необходимости можно игнорировать записи, соответствующие заданным glob-паттернам.
- Имя инструмента:
list_directory - Отображаемое имя: ReadFolder
- Файл:
ls.ts - Параметры:
path(string, обязательный): Абсолютный путь к каталогу для вывода списка.ignore(массив строк, необязательный): Список glob-паттернов, которые нужно исключить из списка (например,["*.log", ".git"]).respect_git_ignore(boolean, необязательный): Учитывать ли паттерны из.gitignoreпри выводе списка файлов. По умолчаниюtrue.
- Поведение:
- Возвращает список имен файлов и каталогов.
- Показывает, является ли каждая запись каталогом.
- Сортирует записи: сначала каталоги, затем в алфавитном порядке.
- Вывод (
llmContent): Строка вида:Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png - Подтверждение: Нет.
2. read_file (ReadFile)
read_file читает и возвращает содержимое указанного файла. Этот инструмент работает с текстовыми файлами, изображениями (PNG, JPG, GIF, WEBP, SVG, BMP) и PDF-файлами. Для текстовых файлов можно читать определённые диапазоны строк. Другие бинарные файлы, как правило, пропускаются.
- Название инструмента:
read_file - Отображаемое имя: ReadFile
- Файл:
read-file.ts - Параметры:
path(string, обязательный): Абсолютный путь к файлу для чтения.offset(number, опциональный): Для текстовых файлов — номер строки (с 0), с которой начинать чтение. Требует установкиlimit.limit(number, опциональный): Для текстовых файлов — максимальное количество строк для чтения. Если не указан, читается стандартное максимальное количество (например, 2000 строк) или весь файл, если это возможно.
- Поведение:
- Для текстовых файлов: Возвращает содержимое. Если используются
offsetиlimit, возвращает только указанный диапазон строк. Указывает, если содержимое было обрезано из-за ограничений по количеству или длине строк. - Для изображений и PDF-файлов: Возвращает содержимое файла в виде base64-закодированной структуры данных, подходящей для обработки моделью.
- Для других бинарных файлов: Пытается определить и пропустить их, возвращая сообщение о том, что это обычный бинарный файл.
- Для текстовых файлов: Возвращает содержимое. Если используются
- Вывод: (
llmContent):- Для текстовых файлов: Содержимое файла, возможно, с префиксом сообщения об обрезке (например,
[File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...). - Для изображений/PDF-файлов: Объект, содержащий
inlineDataсmimeTypeи base64-кодированнымиdata(например,{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }). - Для других бинарных файлов: Сообщение вроде
Cannot display content of binary file: /path/to/data.bin.
- Для текстовых файлов: Содержимое файла, возможно, с префиксом сообщения об обрезке (например,
- Подтверждение: Нет.
3. write_file (WriteFile)
write_file записывает контент в указанный файл. Если файл существует, он будет перезаписан. Если файл не существует, он (и все необходимые родительские директории) будет создан.
- Название инструмента:
write_file - Отображаемое имя: WriteFile
- Файл:
write-file.ts - Параметры:
file_path(string, обязательный): Абсолютный путь к файлу для записи.content(string, обязательный): Контент, который нужно записать в файл.
- Поведение:
- Записывает переданный
contentпо указанномуfile_path. - Создает родительские директории, если они не существуют.
- Записывает переданный
- Вывод (
llmContent): Сообщение об успешной операции, например:Successfully overwrote file: /path/to/your/file.txtилиSuccessfully created and wrote to new file: /path/to/new/file.txt. - Подтверждение: Да. Показывает diff изменений и запрашивает подтверждение пользователя перед записью.
4. glob (FindFiles)
glob находит файлы, соответствующие определенным glob-паттернам (например, src/**/*.ts, *.md), и возвращает абсолютные пути, отсортированные по времени модификации (новые файлы первыми).
- Название инструмента:
glob - Отображаемое имя: FindFiles
- Файл:
glob.ts - Параметры:
pattern(string, обязательный): glob-паттерн для поиска (например,"*.py","src/**/*.js").path(string, опциональный): Абсолютный путь к директории, в которой нужно искать. Если не указан, поиск осуществляется в корневой директории инструмента.case_sensitive(boolean, опциональный): Учитывать ли регистр при поиске. По умолчаниюfalse.respect_git_ignore(boolean, опциональный): Следует ли учитывать паттерны из .gitignore при поиске файлов. По умолчаниюtrue.
- Поведение:
- Ищет файлы, соответствующие glob-паттерну в указанной директории.
- Возвращает список абсолютных путей, отсортированных по времени модификации (новые файлы первыми).
- По умолчанию игнорирует стандартные служебные директории, такие как
node_modulesи.git.
- Вывод (
llmContent): Сообщение вида:Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):\nsrc/file1.ts\nsrc/subdir/file2.ts... - Подтверждение: Нет.
5. search_file_content (SearchText)
search_file_content ищет регулярное выражение (regex) в содержимом файлов указанной директории. Может фильтровать файлы по glob-паттерну. Возвращает строки с совпадениями, а также пути к файлам и номера строк.
-
Имя инструмента:
search_file_content -
Отображаемое имя: SearchText
-
Файл:
grep.ts -
Параметры:
pattern(string, обязательный): Регулярное выражение для поиска (например,"function\s+myFunction").path(string, опциональный): Абсолютный путь к директории, в которой нужно искать. По умолчанию — текущая рабочая директория.include(string, опциональный): Glob-паттерн для фильтрации файлов (например,"*.js","src/**/*.{ts,tsx}"). Если не указан, поиск осуществляется по большинству файлов (с учетом стандартных игнор-файлов).maxResults(number, опциональный): Максимальное количество совпадений, которое будет возвращено, чтобы избежать переполнения контекста (по умолчанию: 20, максимум: 100). Используйте меньшие значения для широких поисков, большие — для точных.
-
Поведение:
- Использует
git grep, если доступен в Git-репозитории, для повышения скорости; иначе использует системныйgrepили поиск на JavaScript. - Возвращает список строк с совпадениями, каждая из которых снабжена путем к файлу (относительно директории поиска) и номером строки.
- По умолчанию ограничивает количество результатов 20 совпадениями, чтобы избежать переполнения контекста. При обрезке результатов выводится предупреждение с рекомендациями по уточнению запроса.
- Использует
-
Вывод (
llmContent): Отформатированная строка с совпадениями, например:Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"): --- File: src/utils.ts L15: export function myFunction() { L22: myFunction.call(); --- File: src/index.ts L5: import { myFunction } from './utils'; --- WARNING: Results truncated to prevent context overflow. To see more results: - Use a more specific pattern to reduce matches - Add file filters with the 'include' parameter (e.g., "*.js", "src/**") - Specify a narrower 'path' to search in a subdirectory - Increase 'maxResults' parameter if you need more matches (current: 20) -
Подтверждение: Нет.
Примеры использования search_file_content
Поиск по паттерну с ограничением результатов по умолчанию:
search_file_content(pattern="function\s+myFunction", path="src")Поиск по паттерну с пользовательским ограничением результатов:
search_file_content(pattern="function", path="src", maxResults=50)Поиск по паттерну с фильтрацией файлов и пользовательским ограничением результатов:
search_file_content(pattern="function", include="*.js", maxResults=10)6. edit (Редактирование)
edit заменяет текст в файле. По умолчанию заменяется одно вхождение, но можно заменить несколько вхождений, если указать expected_replacements. Этот инструмент предназначен для точных, целевых изменений и требует значительного контекста вокруг old_string, чтобы убедиться, что он изменяет правильное место.
-
Название инструмента:
edit -
Отображаемое имя: Редактирование
-
Файл:
edit.ts -
Параметры:
-
file_path(string, обязательный): Абсолютный путь к файлу, который нужно изменить. -
old_string(string, обязательный): Точный буквальный текст для замены.ВАЖНО: Эта строка должна однозначно идентифицировать единственный экземпляр для изменения. Она должна включать как минимум 3 строки контекста до и после целевого текста, точно соответствующего пробелам и отступам. Если
old_stringпустая, инструмент пытается создать новый файл по путиfile_pathс содержимымnew_string. -
new_string(string, обязательный): Точный буквальный текст, на который нужно заменитьold_string. -
expected_replacements(number, опциональный): Количество вхождений для замены. По умолчанию —1.
-
-
Поведение:
- Если
old_stringпустая иfile_pathне существует, создается новый файл с содержимымnew_string. - Если
old_stringзадана, инструмент читаетfile_pathи пытается найти ровно одно вхождениеold_string. - Если одно вхождение найдено, оно заменяется на
new_string. - Повышенная надежность (многоэтапная коррекция редактирования): Чтобы значительно повысить вероятность успешного редактирования, особенно когда предоставленная моделью
old_stringможет быть не совсем точной, инструмент использует механизм многоэтапной коррекции редактирования.- Если исходная
old_stringне найдена или совпадает с несколькими местами, инструмент может использовать модель Qwen для итеративного уточненияold_string(и, возможно,new_string). - Этот процесс самокоррекции пытается определить уникальный сегмент, который модель хотела изменить, делая операцию
editболее надежной даже при немного неточном начальном контексте.
- Если исходная
- Если
-
Условия сбоя: Несмотря на механизм коррекции, инструмент завершится ошибкой, если:
file_pathне является абсолютным или находится вне корневой директории.old_stringне пустая, ноfile_pathне существует.old_stringпустая, ноfile_pathуже существует.old_stringне найдена в файле после попыток её корректировки.old_stringвстречается несколько раз, и механизм самокоррекции не может определить однозначное совпадение.
-
Вывод (
llmContent):- При успехе:
Successfully modified file: /path/to/file.txt (1 replacements).илиCreated new file: /path/to/new_file.txt with provided content. - При ошибке: Сообщение об ошибке с объяснением причины (например,
Failed to edit, 0 occurrences found...,Failed to edit, expected 1 occurrences but found 2...).
- При успехе:
-
Подтверждение: Да. Показывает diff предложенных изменений и запрашивает подтверждение пользователя перед записью в файл.
Эти инструменты файловой системы предоставляют основу для того, чтобы Qwen Code мог понимать и взаимодействовать с локальным контекстом вашего проекта.