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

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

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

1. list_directory (ListFiles)

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

• Имя инструмента: list_directory
• Отображаемое имя: ListFiles
• Файл: ls.ts
• Параметры:
  • path (string, обязательный): Абсолютный путь к директории для вывода списка.
  • ignore (array of strings, опциональный): Список 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 читает и возвращает содержимое указанного файла. Этот инструмент работает с текстовыми файлами и медиафайлами (изображения, PDF, аудио, видео), модальность которых поддерживается текущей моделью. Для текстовых файлов можно указать диапазон строк. Медиафайлы с неподдерживаемой модальностью отклоняются с понятным сообщением об ошибке. Другие типы бинарных файлов обычно пропускаются.

• Имя инструмента: read_file
• Отображаемое имя: ReadFile
• Файл: read-file.ts
• Параметры:
  • path (string, обязательный): Абсолютный путь к файлу для чтения.
  • offset (number, опциональный): Для текстовых файлов — номер строки (с нуля), с которой начать чтение. Требует указания limit.
  • limit (number, опциональный): Для текстовых файлов — максимальное количество строк для чтения. Если не указан, читается лимит по умолчанию (например, 2000 строк) или весь файл, если это возможно.
• Поведение:
  • Для текстовых файлов: возвращает содержимое. Если указаны offset и limit, возвращает только этот фрагмент строк. Указывает, было ли содержимое обрезано из-за лимита строк или длины строки.
  • Для медиафайлов (изображения, PDF, аудио, видео): если текущая модель поддерживает модальность файла, возвращает содержимое в виде объекта inlineData в кодировке base64. Если модальность не поддерживается, возвращает сообщение об ошибке с рекомендациями (например, предлагает использовать skills или внешние инструменты).
  • Для других бинарных файлов: пытается определить тип и пропустить файл, возвращая сообщение о том, что это обычный бинарный файл.
• Вывод (llmContent):
  • Для текстовых файлов: содержимое файла, возможно с префиксом сообщения об обрезке (например, [File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...).
  • Для поддерживаемых медиафайлов: объект, содержащий 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 (Glob)

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

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

5. grep_search (Grep)

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

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

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

• Файл: grep.ts (с ripGrep.ts в качестве fallback)

• Параметры:

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

• Поведение:

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

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

  Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"):
  ---
  src/utils.ts:15:export function myFunction() {
  src/utils.ts:22:  myFunction.call();
  src/index.ts:5:import { myFunction } from './utils';
  ---
  
  [0 lines truncated] ...

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

Примеры использования grep_search

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

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)

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

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

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

• Файл: edit.ts

• Параметры:

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

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

    ВАЖНО: Эта строка должна однозначно идентифицировать единственный экземпляр для изменения. Она должна включать достаточный контекст вокруг целевого текста, точно совпадая с пробелами и отступами. Если 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 определяет кодировку с помощью многоэтапной стратегии:

1. UTF-8 — проверяется первой (большинство современных инструментов выводят UTF-8)
2. chardet — статистическое определение для контента не в UTF-8
3. Системная кодировка — откат к кодовой странице ОС (Windows chcp / Unix LANG)

Инструменты write_file и edit сохраняют исходную кодировку и BOM (byte order mark) существующих файлов. Если файл был прочитан как GBK с UTF-8 BOM, он будет записан обратно точно так же.

Настройка кодировки по умолчанию для новых файлов

Параметр defaultFileEncoding управляет кодировкой для вновь создаваемых файлов (не для правок в существующих):

Установите его в .qwen/settings.json или ~/.qwen/settings.json:

{
  "general": {
    "defaultFileEncoding": "utf-8-bom"
  }
}

Windows: CRLF для пакетных файлов

В Windows файлы .bat и .cmd автоматически записываются с окончаниями строк CRLF (\r\n). Это необходимо, так как cmd.exe использует CRLF в качестве разделителя строк — окончания только с LF могут сломать многострочные конструкции if/else, метки goto и циклы for. Это применяется независимо от настроек кодировки и только в Windows.

Windows: UTF-8 BOM для скриптов PowerShell

В Windows при использовании системной кодовой страницы, отличной от UTF-8 (например, GBK/cp936, Big5/cp950, Shift_JIS/cp932), вновь создаваемые файлы .ps1 автоматически записываются с UTF-8 BOM. Это необходимо, потому что Windows PowerShell 5.1 (версия, встроенная в Windows 10/11) читает скрипты без BOM, используя системную ANSI-кодовую страницу. Без BOM любые не-ASCII символы в скрипте будут интерпретированы неверно.

Этот автоматический BOM применяется только когда:

• Платформа — Windows
• Системная кодовая страница не UTF-8 (не кодовая страница 65001)
• Файл является новым .ps1 (существующие файлы сохраняют исходную кодировку)
• Пользователь не установил явно defaultFileEncoding в настройках

PowerShell 7+ (pwsh) по умолчанию использует UTF-8 и прозрачно обрабатывает BOM, поэтому его наличие там безвредно.

Если вы явно установите defaultFileEncoding в "utf-8", автоматическое добавление BOM отключается — это преднамеренный механизм обхода для репозиториев или инструментов, которые отвергают BOM.

Итог

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