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-кодировкой. Если модель не поддерживает модальность, возвращает сообщение об ошибке с рекомендациями (например, предлагает навыки или внешние инструменты).
  • Для других двоичных файлов: пытается определить и пропустить их, возвращая сообщение о том, что это универсальный двоичный файл.
• Вывод: (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.
• Подтверждение: Нет.

Чтение Jupyter notebook

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

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

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

3. notebook_edit (NotebookEdit)

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

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

Примеры 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. Для редактирования ячеек .ipynb используйте notebook_edit.
  • Создаёт родительские каталоги, если их нет.
• Вывод (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-ноутбуков. Для редактирования ячеек .ipynb используйте notebook_edit.
  • Если 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 отключается — это предусмотренный запасной вариант для репозиториев или инструментов, которые не принимают BOM.

Summary

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