Skip to Content
Руководство разработчикаИнструментыФайловая система

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

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

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

1. list_directory (ListFiles)

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

  • Имя инструмента: list_directory
  • Отображаемое имя: ListFiles
  • Файл: ls.ts
  • Параметры:
    • path (строка, обязательный): Абсолютный путь к каталогу для вывода списка.
    • ignore (массив строк, необязательный): Список шаблонов glob, которые следует исключить из списка (например, ["*.log", ".git"]).
    • respect_git_ignore (логическое значение, необязательный): Учитывать ли шаблоны .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 (строка, обязательный): Абсолютный путь к файлу для чтения.
    • offset (число, необязательный): Для текстовых файлов — номер строки (начиная с 0), с которой начинать чтение. Требует установки параметра limit.
    • limit (число, необязательный): Для текстовых файлов — максимальное количество строк для чтения. Если не указано, читается стандартное максимальное значение (например, 2000 строк) или весь файл, если это возможно.
  • Поведение:
    • Для текстовых файлов: Возвращает содержимое. Если используются offset и limit, возвращается только этот фрагмент строк. Указывает, было ли содержимое усечено из-за ограничений по количеству строк или длине строк.
    • Для файлов изображений и PDF: Возвращает содержимое файла в виде структуры данных, закодированной в base64, подходящей для использования моделью.
    • Для других бинарных файлов: Пытается определить и пропустить их, возвращая сообщение о том, что это обычный бинарный файл.
  • Вывод: (llmContent):
    • Для текстовых файлов: Содержимое файла, при необходимости с префиксом сообщения об усечении (например, [Содержимое файла усечено: отображаются строки 1–100 из 500 общего количества строк...]\nФактическое содержимое файла...).
    • Для файлов изображений/PDF: Объект, содержащий inlineData с mimeType и данными в формате base64 (например, { inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }).
    • Для других бинарных файлов: Сообщение вроде Невозможно отобразить содержимое бинарного файла: /path/to/data.bin.
  • Подтверждение: Нет.

3. write_file (WriteFile)

write_file записывает содержимое в указанный файл. Если файл существует, он будет перезаписан. Если файл не существует, он (а также все необходимые родительские директории) будет создан.

  • Имя инструмента: write_file
  • Отображаемое имя: WriteFile
  • Файл: write-file.ts
  • Параметры:
    • file_path (строка, обязательный): Абсолютный путь к файлу для записи.
    • content (строка, обязательный): Содержимое, которое нужно записать в файл.
  • Поведение:
    • Записывает предоставленное 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 (строка, обязательный): Шаблон glob для сопоставления (например, "*.py", "src/**/*.js").
    • path (строка, необязательный): Каталог для поиска. Если не указан, будет использоваться текущий рабочий каталог.
  • Поведение:
    • Ищет файлы, соответствующие шаблону 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

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

  • Параметры:

    • pattern (строка, обязательный): Регулярное выражение для поиска в содержимом файлов (например, "function\\s+myFunction", "log.*Error").
    • path (строка, необязательный): Файл или директория для поиска. По умолчанию используется текущая рабочая директория.
    • glob (строка, необязательный): Шаблон glob для фильтрации файлов (например, "*.js", "src/**/*.{ts,tsx}").
    • limit (число, необязательный): Ограничить вывод первыми 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 (строка, обязательный): Абсолютный путь к файлу для изменения.

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

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

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

    • replace_all (булево, необязательный): Заменить все вхождения 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...).

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

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

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