Инструменты¶

Инструменты — это функции, которые модель может вызывать в процессе работы: чтение и изменение файлов, выполнение команд, поиск в интернете, работа с памятью и навыками. Текущий список доступных инструментов можно посмотреть командой /tools.

Часть инструментов только читает данные, часть меняет файлы или выполняет команды — такие требуют подтверждения.

Встроенные инструменты¶

Инструмент	Назначение
`list_directory`	показать содержимое каталога
`read_file`	прочитать один файл
`read_many_files`	массово прочитать файлы по путям и glob-шаблонам
`glob`	найти файлы по шаблону
`search_file_content`	поиск по содержимому файлов
`replace`	заменить фрагмент файла
`write_file`	создать или перезаписать файл
`run_shell_command`	выполнить shell-команду
`web_fetch`	скачать и обработать содержимое URL
`google_web_search`	выполнить поиск в интернете
`docs_search`	найти материалы в документации
`save_memory`	сохранить факт в глобальную память
`activate_skill`	активировать навык
`update_plan`	опубликовать план задачи и обновлять его статусы
`run_subagent`	делегировать фоновое исследование субагенту

Файлы и каталоги¶

`list_directory`¶

Показывает содержимое каталога. Используется для первичной навигации и понимания структуры проекта.

path (обязательный) — абсолютный путь к каталогу;
ignore (необязательный) — список glob-шаблонов для исключения;
respect_ignore_files (необязательный) — учитывать .gitignore и .kodaignore (по умолчанию true).

`read_file`¶

Читает один файл: текстовый файл, изображение или PDF. Поддерживает постраничное чтение больших файлов.

absolute_path (обязательный) — абсолютный путь к файлу;
offset (необязательный) — номер начальной строки (нумерация с нуля);
limit (необязательный) — максимальное число строк для чтения.

`read_many_files`¶

Загружает в контекст набор файлов по glob-шаблонам. Используется CLI напрямую и через @-ссылки на файлы и каталоги.

paths (обязательный) — массив glob-шаблонов или путей, например ["src/**/*.ts"];
include (необязательный) — дополнительные шаблоны для включения;
exclude (необязательный) — шаблоны для исключения;
useDefaultExcludes (необязательный) — применять стандартные исключения (по умолчанию true).

При чтении каталога бинарные и слишком большие файлы пропускаются. Учитываются .gitignore, .kodaignore, настройки fileFiltering и дополнительные каталоги из includeDirectories.

`glob`¶

Ищет файлы по glob-шаблону, например **/*.py или docs/*.md.

pattern (обязательный) — glob-шаблон;
path (необязательный) — каталог для поиска;
case_sensitive (необязательный) — учитывать регистр (по умолчанию false);
respect_git_ignore (необязательный) — учитывать .gitignore (по умолчанию true).

`search_file_content`¶

Ищет текст по содержимому файлов с помощью регулярных выражений. Подходит для поиска функций, команд, переменных окружения и сообщений об ошибках.

pattern (обязательный) — регулярное выражение;
path (необязательный) — каталог для поиска;
include (необязательный) — glob-шаблон для фильтрации файлов, например *.ts.

`replace`¶

Заменяет точный фрагмент текста в файле. Подходит для точечных изменений, когда старый фрагмент можно однозначно найти. Перед применением CLI показывает дифф.

file_path (обязательный) — абсолютный путь к файлу;
old_string (обязательный) — точный заменяемый текст;
new_string (обязательный) — новый текст;
expected_replacements (необязательный) — число ожидаемых замен (по умолчанию 1).

`write_file`¶

Создаёт или перезаписывает файл целиком. Перед записью CLI показывает дифф. Для правок в существующих файлах предпочтительнее replace с маленькими изменениями.

file_path (обязательный) — абсолютный путь к файлу;
content (обязательный) — содержимое файла.

Командная оболочка¶

`run_shell_command`¶

Выполняет команду в shell текущего процесса Koda CLI. Команда выполняется с правами вашего пользователя, поэтому в режиме по умолчанию инструмент требует подтверждения.

command (обязательный) — команда для выполнения;
description (обязательный) — краткое описание команды;
directory (необязательный) — рабочий каталог выполнения.

Если включена песочница, доступ к файловой системе, сети и сокетам зависит от выбранного окружения. Опасные команды можно запретить через ограничение вида run_shell_command(rm -rf) — см. управление доступом.

Веб и поиск¶

`web_fetch`¶

Скачивает содержимое URL и возвращает модели обработанный результат. Полезен для чтения конкретной страницы, changelog, release notes или raw-файла. Для GitHub blob-ссылок инструмент умеет переходить к raw-содержимому, когда это возможно.

url (обязательный) — адрес, начинающийся с http:// или https://.

Страницы с авторизацией, динамическим JavaScript или ограничением частоты запросов могут не прочитаться. Доступ к сети зависит от окружения и песочницы.

`google_web_search`¶

Выполняет поиск в интернете через сервис Koda и возвращает топ результатов с ссылками и описаниями. Используется, когда нужен свежий внешний контекст.

query (обязательный) — поисковый запрос.

`docs_search`¶

Ищет по технической документации, которую индексирует docs-сервис Koda. К результатам добавляются ссылки на найденные страницы документации.

query (обязательный) — поисковый запрос;
language (необязательный) — язык программирования, например python или javascript.

Память и навыки¶

`save_memory`¶

Сохраняет факт в глобальную память ~/.kodacli/KODA.md — в секцию ## Koda Added Memories. Перед сохранением CLI запрашивает подтверждение. Подробнее о проектной и глобальной памяти — в командах /memory.

fact (обязательный) — самодостаточная формулировка факта.

`activate_skill`¶

Активирует навык: его инструкции добавляются в контекст сессии. Перед активацией CLI запрашивает подтверждение.

name (обязательный) — имя навыка.

`update_plan`¶

Публикует план задачи, который отображается в панели плана. Это единственный способ сделать план видимым: шаги, перечисленные в ответе обычным текстом, планом не считаются. Каждый вызов заменяет план целиком.

plan (обязательный) — массив шагов, у каждого шага поля step (текст) и status (pending, in_progress или completed);
explanation (необязательный) — короткое пояснение к плану.

Одновременно не может быть больше одного шага в статусе in_progress. В режиме планирования все шаги должны иметь статус pending до запуска реализации. Подтверждения вызов не требует: инструмент меняет только панель плана, а не файлы.

Субагенты¶

`run_subagent`¶

Делегирует самодостаточную исследовательскую задачу фоновому субагенту — изолированной read-only сессии с собственным контекстом. Результат доставляется агенту автоматически: по умолчанию агент дожидается завершения всех субагентов, а с настройкой allowParentToContinue продолжает работу параллельно.

Что такое субагенты

Общая концепция субагентов описана в статье Субагенты — без привязки к конкретному продукту.

Субагент может читать файлы и искать по кодовой базе, но не может изменять файлы и запускать команды, меняющие состояние. Лимиты работы регулируются настройкой subagents: число одновременных задач, модель, бюджет времени и набор инструментов.

description (обязательный) — короткая метка задачи (3–8 слов);
prompt (обязательный) — полное самодостаточное описание задачи и ожидаемого результата;
agent (необязательный) — имя роли из списка в системном промпте; субагент работает под её инструкциями; без параметра запускается универсальный субагент-исследователь;
task_id (необязательный) — идентификатор существующей задачи для проверки статуса или продолжения;
action (необязательный) — status для снимка состояния или resume для продолжения завершённой задачи.

Состояние и результаты задач можно посмотреть командой /subagents.