Перейти к содержанию

Работа с файлами

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

Подключение файлов через @

Если вы знаете путь к файлу, укажите его в запросе с символом @. CLI сразу прочитает файл и вставит его содержимое в ваш запрос.

@src/components/UserProfile.tsx объясни, как этот компонент работает с данными пользователя

Модель видит содержимое файла как часть вашего сообщения — ей не нужно отдельно открывать файл инструментом чтения.

Подробное описание синтаксиса — в справочнике команд.

Как это работает

Когда вы пишете @путь в поле ввода, CLI:

  1. находит файл или каталог по указанному пути;
  2. читает содержимое через внутренний инструмент read_many_files;
  3. вставляет текст в запрос перед отправкой модели.

Несколько файлов

Сложные задачи часто затрагивают несколько файлов. Можно перечислить несколько @-ссылок, чтобы дать модели полную картину зависимостей:

@src/components/UserProfile.tsx @src/types/User.ts отрефактори компонент под обновлённый интерфейс User

Каталоги целиком

Для общих вопросов или масштабного рефакторинга можно подключить весь каталог:

@src/utils/ проверь эти утилиты на использование устаревших API

Расход токенов

Большие каталоги заметно увеличивают контекст запроса. Подключайте каталог целиком только тогда, когда это действительно нужно.

Экранирование пробелов

Пробелы в путях экранируются обратной косой чертой:

@My\ Documents/notes.md

Поиск файлов

Если точный путь неизвестен, просто попросите CLI найти файл. Это удобно при знакомстве с новой кодовой базой или поиске конкретной логики:

найди файл, в котором определён компонент UserProfile

CLI использует инструменты glob и list_directory, чтобы обойти структуру проекта, и вернёт конкретный путь — например, src/components/UserProfile.tsx. Этот путь можно сразу использовать с @ в следующем запросе.

Изменение и создание файлов

Когда контекст собран, можно поручить агенту правки — не только точечную замену текста, но и сложный рефакторинг:

обнови @src/components/UserProfile.tsx — покажи спиннер загрузки, если данные пользователя равны null

CLI использует инструмент replace, чтобы предложить целевое изменение кода.

Можно также попросить создать новый файл или целую структуру каталогов:

создай новый файл @src/components/LoadingSpinner.tsx с простым спиннером на Tailwind CSS

Новый файл создаётся с нуля инструментом write_file.

Подтверждение изменений

Прежде чем изменить какой-либо файл, CLI показывает унифицированный дифф (разницу) предлагаемых правок:

- print('hello')
+ print('hello world')
  • красные строки (-) — код, который будет удалён;
  • зелёные строки (+) — код, который будет добавлен.

Подтвердите применение изменения — правка запишется в локальный файл. Если дифф выглядит неправильно, отклоните его и уточните запрос.

Проверка результата

После правки стоит убедиться, что ничего не сломалось. Попросите CLI перечитать файл или запустить тесты проекта:

запусти тесты для компонента UserProfile

CLI выполнит тестовый раннер через инструмент run_shell_command (например, npm test или jest) и покажет результат.

Управление видимостью файлов

По умолчанию CLI учитывает .gitignore: он не читает и не ищет в node_modules, артефактах сборки и других игнорируемых путях.

Если нужно скрыть от модели чувствительные файлы (например, .env) или крупные ресурсы, не убирая их из git, создайте файл .kodaignore в корне проекта:

.kodaignore
.env
local-db-dump.sql
private-notes.md

При чтении каталогов дополнительно применяются настройки фильтрации:

Настройка По умолчанию Что делает
fileFiltering.respectGitIgnore true исключает файлы, игнорируемые git
fileFiltering.respectKodaIgnore true исключает файлы по правилам .kodaignore
fileFiltering.enableRecursiveFileSearch true разрешает рекурсивный поиск в подкаталогах

Настройка фильтрации

Описание каждого параметра — в разделе настроек контекста: respectGitIgnore, respectKodaIgnore и enableRecursiveFileSearch.

Ограничения

  • Чтение предназначено для текстовых файлов. Двоичные файлы (изображения, архивы, скомпилированные бинарники) пропускаются.
  • Очень большие файлы могут быть усечены для производительности.
  • Инструмент read_many_files указывает в выводе, какие файлы были пропущены.

Обработка ошибок

Если путь после @ не найден или недействителен, CLI покажет сообщение об ошибке. Запрос может быть отправлен без содержимого файла или не отправлен вовсе — зависит от контекста.

Если read_many_files сталкивается с ошибкой доступа (например, нет прав на чтение), это также сообщается в выводе. Остальные файлы обрабатываются независимо — ошибка одного файла не прерывает чтение остальных.