Skip to Content
Коллекция ИнструментовИнструменты Файловой Системы

Инструменты файловой системы 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 мог понимать и взаимодействовать с локальным контекстом вашего проекта.

Last updated on
Обзор ИнструментовИнструменты Чтения Множественных Файлов