Инструменты файловой системы 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 читает и возвращает содержимое указанного файла. Этот инструмент обрабатывает текстовые файлы и медиафайлы (изображения, PDF, аудио, видео), модальность которых поддерживается текущей моделью. Для текстовых файлов может читать определённые диапазоны строк. Медиафайлы, модальность которых не поддерживается текущей моделью, отклоняются с информативным сообщением об ошибке. Другие типы бинарных файлов обычно пропускаются.

• Имя инструмента: read_file
• Отображаемое имя: ReadFile
• Файл: read-file.ts
• Параметры:
  • path (строка, обязательный): Абсолютный путь к файлу для чтения.
  • offset (число, опциональный): Для текстовых файлов — номер строки (начиная с 0), с которой начать чтение. Требует установки limit.
  • limit (число, опциональный): Для текстовых файлов — максимальное количество строк для чтения. Если опущен, читается максимум по умолчанию (например, 2000 строк) или весь файл, если это возможно.
• Поведение:
  • Для текстовых файлов: возвращает содержимое. Если используются offset и limit, возвращается только этот срез строк. Указывает, было ли содержимое усечено из-за ограничений на количество строк или длину строк.
  • Для медиафайлов (изображения, PDF, аудио, видео): если текущая модель поддерживает модальность файла, возвращает содержимое файла в виде объекта inlineData, закодированного в base64. Если модель не поддерживает модальность, возвращает сообщение об ошибке с рекомендациями (например, предлагает навыки или внешние инструменты).
  • Для других бинарных файлов: пытается определить и пропустить их, возвращая сообщение о том, что это обычный бинарный файл.
• Вывод: (llmContent):
  • Для текстовых файлов: содержимое файла, возможно, с префиксом о усечении (например, [File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...).
  • Для поддерживаемых медиафайлов: объект, содержащий inlineData с mimeType и данными в base64 (например, { inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }).
  • Для неподдерживаемых медиафайлов: строка с сообщением об ошибке, объясняющим, что текущая модель не поддерживает эту модальность, с предложениями альтернатив.
  • Для других бинарных файлов: сообщение вида Cannot display content of binary file: /path/to/data.bin.
• Подтверждение: Нет.

Чтение Jupyter notebook

Для Jupyter notebook (.ipynb) read_file разбирает JSON notebook и возвращает структурированное, читаемое моделью представление notebook вместо сырого JSON. Отображаемый вывод включает язык notebook, упорядоченные ячейки, идентификаторы ячеек, исходный код и сжатые результаты выполнения.

Ячейки notebook затем можно редактировать с помощью notebook_edit. Модель должна использовать идентификаторы ячеек, показанные read_file, при указании целевой ячейки.

offset и limit не поддерживаются для файлов .ipynb. Чтение notebook обрабатывается как структурированное чтение полного файла; если отображаемый вывод notebook внутренне усечён из-за большого размера, notebook_edit отклонит изменения на уровне ячеек и попросит вас уменьшить объём вывода или разделить notebook перед редактированием.

3. notebook_edit (NotebookEdit)

notebook_edit безопасно редактирует файлы Jupyter notebook (.ipynb) на уровне ячеек. Используйте его вместо edit или write_file при изменении ячеек notebook.

• Имя инструмента: notebook_edit
• Отображаемое имя: NotebookEdit
• Файл: notebook-edit.ts
• Параметры:
  • notebook_path (строка, обязательный): Абсолютный путь к файлу .ipynb.
  • cell_id (строка, опциональный): Идентификатор целевой ячейки, показанный read_file. Обязателен для replace и delete. Для insert новая ячейка вставляется после этой ячейки; если опущен, новая ячейка вставляется в начало.
  • new_source (строка, опциональный): Новый исходный код ячейки для replace и insert. Не требуется для delete.
  • cell_type (code или markdown, опциональный): Тип ячейки для вставляемых ячеек или целевой тип при замене ячейки.
  • edit_mode (replace, insert или delete, опциональный): Операция редактирования. По умолчанию replace.
• Поведение:
  • Требует, чтобы notebook был сначала прочитан с помощью read_file в текущем сеансе.
  • Нацеливается на ячейки, используя идентификаторы, отображаемые read_file, включая реальные идентификаторы ячеек notebook и отображаемые запасные идентификаторы cell-N.
  • Отклоняет неоднозначные отображаемые идентификаторы ячеек вместо угадывания.
  • Для ячеек с кодом очищает устаревшие выходные данные и сбрасывает execution_count при изменении исходного кода.
  • Сохраняет форматирование JSON notebook, концы строк, кодировку и BOM, где это возможно.
  • Аннулирует состояние предыдущего чтения после структурных изменений, когда отображаемые запасные идентификаторы могут сместиться, так что следующее редактирование notebook потребует нового read_file.
• Вывод (llmContent): Сообщение об успехе с описанием отредактированной ячейки notebook и, для операций, отличных от delete, обновлённым исходным кодом.
• Подтверждение: Да. Показывает diff JSON notebook и запрашивает одобрение пользователя перед записью, если только текущий режим разрешений или правила не auto-approve инструменты редактирования.

Примеры notebook_edit

Замена ячейки с кодом:

notebook_edit(
  notebook_path="/path/to/analysis.ipynb",
  cell_id="load-data",
  new_source="result = 41 + 1\nprint(result)"
)

Вставка ячейки markdown после существующей ячейки:

notebook_edit(
  notebook_path="/path/to/analysis.ipynb",
  edit_mode="insert",
  cell_id="summary",
  cell_type="markdown",
  new_source="## Findings\n\nThe cleaned data is ready for modeling."
)

Удаление ячейки:

notebook_edit(
  notebook_path="/path/to/analysis.ipynb",
  edit_mode="delete",
  cell_id="old-experiment"
)

4. write_file (WriteFile)

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

• Имя инструмента: write_file
• Отображаемое имя: WriteFile
• Файл: write-file.ts
• Параметры:
  • file_path (строка, обязательный): Абсолютный путь к файлу для записи.
  • content (строка, обязательный): Содержимое для записи в файл.
• Поведение:
  • Записывает указанное content в file_path.
  • Не записывает сырой JSON Jupyter notebook. Используйте notebook_edit для редактирования ячеек .ipynb.
  • Создаёт родительские каталоги, если они не существуют.
• Вывод (llmContent): Сообщение об успехе, например: Successfully overwrote file: /path/to/your/file.txt или Successfully created and wrote to new file: /path/to/new/file.txt.
• Подтверждение: Да. Показывает diff изменений и запрашивает одобрение пользователя перед записью.

5. glob (Glob)

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

• Имя инструмента: glob
• Отображаемое имя: Glob
• Файл: glob.ts
• Параметры:
  • pattern (строка, обязательный): Glob-шаблон для сопоставления (например, "*.py", "src/**/*.js").
  • path (строка, опциональный): Каталог для поиска. Если не указан, используется текущий рабочий каталог.
• Поведение:
  • Ищет файлы, соответствующие glob-шаблону, в указанном каталоге.
  • Возвращает список абсолютных путей, отсортированных по времени последнего изменения (сначала самые новые).
  • По умолчанию учитывает .gitignore, .qwenignore и настроенные пользовательские файлы игнорирования Qwen.
  • Ограничивает результаты 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] ...
• Подтверждение: Нет.

6. 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 и настроенные пользовательские файлы игнорирования Qwen.
  • Ограничивает вывод, чтобы избежать переполнения контекста.

• Вывод (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)

7. edit (Edit)

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

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

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

• Файл: edit.ts

• Параметры:

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

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

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

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

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

• Поведение:

  • Не редактирует сырой JSON Jupyter notebook. Используйте notebook_edit для редактирования ячеек .ipynb.
  • Если 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 (метку порядка байтов) существующих файлов. Если файл был прочитан как 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 прозрачно, поэтому BOM там безвреден.

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

Сводка

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