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

Инструменты файловой системы Qwen Code

Qwen Code предоставляет комплексный набор инструментов для взаимодействия с локальной файловой системой. Эти инструменты позволяют модели читать, записывать, перечислять, искать и изменять файлы и директории — всё под вашим контролем и, как правило, с подтверждением для чувствительных операций.

Примечание: Все инструменты файловой системы работают в пределах rootDirectory (обычно это текущая рабочая директория, из которой вы запустили CLI) в целях безопасности. Пути, которые вы передаете этим инструментам, как правило, должны быть абсолютными или будут разрешены относительно этой корневой директории.

1. list_directory (ListFiles)

list_directory выводит список имен файлов и подкаталогов, находящихся непосредственно в указанном пути к каталогу. При необходимости можно игнорировать записи, соответствующие заданным glob-паттернам.

  • Имя инструмента: list_directory
  • Отображаемое имя: ListFiles
  • Файл: 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, опционально): Для текстовых файлов — номер строки (с нуля), с которой начинать чтение. Требует установки параметра 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 и data в кодировке base64 (например, { 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 (Glob)

glob находит файлы, соответствующие заданным glob-паттернам (например, src/**/*.ts, *.md), и возвращает абсолютные пути, отсортированные по времени модификации (новые файлы первыми).

  • Название инструмента: glob
  • Отображаемое имя: Glob
  • Файл: glob.ts
  • Параметры:
    • pattern (string, обязательный): glob-паттерн для поиска (например, "*.py", "src/**/*.js").
    • path (string, опциональный): директория для поиска. Если не указана, будет использоваться текущая рабочая директория.
  • Поведение:
    • Ищет файлы, соответствующие glob-паттерну внутри указанной директории.
    • Возвращает список абсолютных путей, отсортированных по времени последней модификации (сначала новые).
    • По умолчанию учитывает паттерны из .gitignore и .qwenignore.
    • Ограничивает результаты 100 файлами, чтобы избежать переполнения контекста.
  • Вывод (llmContent): Сообщение вида: Найдено 5 файл(ов), соответствующих "*.ts" в /path/to/search/dir, отсортировано по времени изменения (новые первыми):\n---\n/path/to/file1.ts\n/path/to/subdir/file2.ts\n---\n[95 файлов пропущено] ...
  • Подтверждение: Нет.

5. grep_search (Grep)

grep_search ищет регулярное выражение в содержимом файлов указанной директории. Может фильтровать файлы по glob-паттерну. Возвращает строки с совпадениями вместе с путями к файлам и номерами строк.

  • Имя инструмента: grep_search

  • Отображаемое имя: Grep

  • Файл: ripGrep.ts (с grep.ts как резервный вариант)

  • Параметры:

    • pattern (string, обязательный): Регулярное выражение для поиска в содержимом файлов (например, "function\\s+myFunction", "log.*Error").
    • path (string, опциональный): Файл или директория для поиска. По умолчанию — текущая рабочая директория.
    • glob (string, опциональный): Glob-паттерн для фильтрации файлов (например, "*.js", "src/**/*.{ts,tsx}").
    • limit (number, опциональный): Ограничить вывод первыми N совпадающими строками. Необязательный параметр — если не указан, показываются все совпадения.

  • Поведение:

    • Использует ripgrep для быстрого поиска, если доступен; иначе применяется реализация на JavaScript.
    • Возвращает строки с совпадениями, включая пути к файлам и номера строк.
    • По умолчанию регистронезависимый поиск.
    • Учитывает паттерны из .gitignore и .qwenignore.
    • Ограничивает объем вывода, чтобы избежать переполнения контекста.

  • Вывод (llmContent): Отформатированная строка с совпадениями, например:

    Найдено 3 совпадения для паттерна "myFunction" в пути "." (фильтр: "*.ts"):
---
src/utils.ts:15:export function myFunction() {
src/utils.ts:22:  myFunction.call();
src/index.ts:5:import { myFunction } from './utils';
---

[0 строк пропущено] ...

  • Подтверждение: Нет.

Поиск по паттерну с ограничением результатов по умолчанию:

grep_search(pattern="function\\s+myFunction", path="src")

Поиск по паттерну с пользовательским ограничением результатов:

grep_search(pattern="function", path="src", limit=50)

Поиск по паттерну с фильтрацией файлов и пользовательским ограничением результатов:

grep_search(pattern="function", glob="*.js", limit=10)

6. edit (Редактирование)

edit заменяет текст в файле. По умолчанию требуется, чтобы old_string точно совпадал с одной уникальной областью; установите replace_all в true, если вы намеренно хотите изменить все вхождения. Этот инструмент предназначен для точных и целевых изменений и требует значительного контекста вокруг old_string, чтобы гарантировать правильное изменение нужного участка.

  • Название инструмента: edit

  • Отображаемое имя: Редактирование

  • Файл: edit.ts

  • Параметры:

    • file_path (string, обязательный): Абсолютный путь к файлу, который нужно изменить.

    • old_string (string, обязательный): Точный текст, который нужно заменить.

      ВАЖНО: Эта строка должна однозначно определять единственное место для изменения. Она должна включать как минимум 3 строки контекста до и после целевого текста, точно соответствующего пробелам и отступам. Если old_string пустая, инструмент попытается создать новый файл по пути file_path с содержимым new_string.

    • new_string (string, обязательный): Точный текст, на который будет заменена old_string.

    • replace_all (boolean, необязательный): Заменить все вхождения old_string. По умолчанию false.

  • Поведение:

    • Если old_string пустая и файл по пути file_path не существует, создаётся новый файл с содержимым new_string.
    • Если old_string задана, инструмент читает файл по пути file_path и пытается найти ровно одно вхождение, если только replace_all не установлено в true.
    • Если совпадение уникально (или replace_all равно true), текст заменяется на 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 встречается несколько раз, replace_all равен false, и механизм самокоррекции не может сузить выбор до одного однозначного совпадения.

  • Вывод (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 because the text matches multiple locations...).

  • Подтверждение: Да. Показывает diff предлагаемых изменений и запрашивает подтверждение пользователя перед записью в файл.

Эти инструменты работы с файловой системой предоставляют основу, позволяющую Qwen Code понимать и взаимодействовать с локальным контекстом вашего проекта.

Last updated on
ВведениеЧтение нескольких файлов