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): Строка вида: Содержимое каталога /path/to/your/folder:\n[DIR] подкаталог1\nфайл1.txt\nфайл2.png
  • Подтверждение: Нет.

2. read_file (ReadFile)

Функция read_file считывает и возвращает содержимое указанного файла. Этот инструмент поддерживает текстовые файлы и мультимедийные файлы (изображения, PDF, аудио, видео), модальность которых поддерживается текущей моделью. Для текстовых файлов можно указать диапазон строк для чтения. Мультимедийные файлы, чья модальность не поддерживается текущей моделью, отклоняются с понятным сообщением об ошибке. Другие типы двоичных файлов обычно пропускаются.

  • Имя инструмента: read_file
  • Отображаемое имя: ReadFile
  • Файл: read-file.ts
  • Параметры:
    • path (строка, обязательный): Абсолютный путь к файлу для чтения.
    • offset (число, необязательный): Для текстовых файлов — номер строки (отсчёт с нуля), с которой начинать чтение. Требует указания параметра limit.
    • limit (число, необязательный): Для текстовых файлов — максимальное количество строк для чтения. Если опущен, читается значение по умолчанию (например, 2000 строк) или весь файл, если это технически возможно.
  • Поведение:
    • Для текстовых файлов: возвращает содержимое. При использовании offset и limit возвращается только соответствующий фрагмент строк. Указывает, было ли содержимое усечено из-за ограничений на количество строк или длину строки.
    • Для мультимедийных файлов (изображения, PDF, аудио, видео): если текущая модель поддерживает модальность файла, возвращает содержимое в виде объекта inlineData, закодированного в base64. Если модель не поддерживает данную модальность, возвращает сообщение об ошибке с рекомендациями (например, предложение использовать определённые навыки или внешние инструменты).
    • Для других двоичных файлов: пытается их распознать и пропустить, возвращая сообщение о том, что это общий двоичный файл.
  • Вывод: (llmContent):
    • Для текстовых файлов: содержимое файла, потенциально с префиксом, указывающим на усечение (например, [Содержимое файла усечено: показаны строки 1–100 из 500 всего...]\nФактическое содержимое файла...).
    • Для поддерживаемых мультимедийных файлов: объект, содержащий inlineData с полями mimeType и base64-кодированным data (например, { 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): Сообщение об успешном выполнении, например: Файл успешно перезаписан: /path/to/your/file.txt или Файл успешно создан и в него успешно записано: /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):

    • При успехе: Файл успешно изменён: /path/to/file.txt (1 замена). или Создан новый файл: /path/to/new_file.txt с указанным содержимым.
    • При сбое: Сообщение об ошибке с пояснением причины (например, Не удалось выполнить редактирование: найдено 0 вхождений..., Не удалось выполнить редактирование, так как текст совпадает с несколькими местами...).

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

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

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