> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velesagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Инструменты Велеса: подробный справочник

> Подробное описание встроенных инструментов Велес, их внутренних имён, назначения, ограничений и условий доступности.

# Инструменты Велеса: подробный справочник

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

Если вам нужно простое пользовательское объяснение без технических деталей, начните со статьи [Инструменты Велеса: простое объяснение](/basics/tools_ru).

***

## Как устроены инструменты в Велес

Инструмент в Велес — это отдельное действие, которое модель может вызвать во время формирования ответа.

На практике это означает, что Велес может:

* не только генерировать текст;
* но и искать информацию;
* читать и редактировать файлы;
* запускать команды в системе;
* использовать долговременную память;
* создавать фоновые задачи;
* обращаться к внешним интеграциям.

Обычно пользователь описывает задачу обычным языком, а модель сама выбирает необходимые инструменты.

***

## Типовой цикл вызова инструментов

```mermaid theme={null}
sequenceDiagram
    participant U as Пользователь
    participant A as Велес
    participant R as Реестр инструментов
    participant T as Инструмент
    participant C as Канал

    U->>A: Формулирует задачу
    A->>R: Выбирает доступные инструменты
    A->>T: Вызывает инструмент с аргументами
    T-->>A: Возвращает результат или ошибку
    A->>A: Анализирует результат
    A-->>C: Отправляет прогресс или итоговый ответ
```

Один пользовательский запрос может вызвать несколько таких циклов: например, сначала поиск по файлам, затем чтение найденных документов, потом точечное редактирование и финальное объяснение.

***

## Проверка аргументов инструментов

Перед выполнением Велес приводит простые скалярные значения к ожидаемым типам и затем проверяет их по схеме инструмента.

Для строковых полей, например содержимого файла или команды, Велес не превращает списки и объекты в служебное строковое представление. Если модель передала структуру вместо строки, инструмент возвращает ошибку проверки аргументов, чтобы модель повторила вызов с корректно сериализованным текстом.

***

## Базовые встроенные инструменты

Ниже перечислены основные инструменты, которые регистрируются в стандартном цикле работы Велеса.

### Работа с файловой системой

#### `read_file`

Назначение:

* чтение текстовых файлов;
* чтение содержимого изображений как ресурса;
* используется для анализа кода, конфигураций, markdown и других файлов.

Для изображений Велес готовит ограниченную по размеру копию из своей рабочей области. Она попадет в запрос только для модели, где в настройке `modalities` указаны `image` или `vision`; для текстовых моделей Велес оставит текстовое описание файла. Если файл недоступен или слишком велик после подготовки, в контекст добавляется короткое текстовое замечание вместо скрытой потери изображения.

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

Когда особенно полезен:

* разбор структуры проекта;
* чтение документации;
* проверка содержимого конкретного файла.

#### `write_file`

Назначение:

* создание новых файлов;
* полная запись содержимого файла;
* автоматическое создание нужных директорий при сохранении.

Когда особенно полезен:

* генерация новых документов;
* создание исходного кода;
* сохранение результатов работы.

#### `edit_file`

Назначение:

* внесение точечных изменений в существующие файлы;
* удобен для небольших правок без полной перезаписи файла.

Когда особенно полезен:

* исправление ошибок;
* обновление отдельных блоков текста;
* локальные правки конфигураций и кода.

#### `list_dir`

Назначение:

* просмотр содержимого директорий;
* помощь в понимании структуры проекта.

Когда особенно полезен:

* первичное обследование репозитория;
* поиск нужной папки или документа;
* проверка наличия файлов.

***

### Работа с интернетом

#### `web_search`

Назначение:

* поиск информации в глобальной сети;
* возвращает заголовки, URL и краткие фрагменты (сниппеты) текста.

Типичный сценарий:

* поиск актуальной или внешней информации;
* подбор источников перед детальным изучением конкретной страницы.

Замечания:

* использует настроенный провайдер веб-поиска;
* конкретный бэкенд зависит от конфигурации;
* результатом является список ссылок-кандидатов, а не полный текст страниц.

#### `web_fetch`

Назначение:

* загрузка контента по конкретному URL;
* извлечение содержимого страницы, JSON или других поддерживаемых ресурсов.

Типичный сценарий:

* пользователь предоставил прямую ссылку;
* чтение статьи, ответа API или страницы документации.

Замечания:

* внешний контент считается недоверенным;
* инструмент используется для получения данных, а не для прямого исполнения инструкций со страницы;
* если страница длиннее `maxChars`, Велес показывает начало и конец, сохраняет полный очищенный текст в `.veles/web-fetch/` и добавляет путь для `read_file`, чтобы можно было дочитать пропущенную середину.

***

### Работа с системой и исполнение

#### `exec`

Назначение:

* выполнение команд в shell/терминале.

Типичный сценарий:

* запуск тестов;
* сборка проекта;
* установка зависимостей;
* проверка параметров окружения;
* запуск локальных утилит.

Важно:

* инструмент регистрируется, только если `exec` разрешен в конфигурации;
* ограничения зависят от режима безопасности и настроек ограничений рабочей области (workspace restrictions);
* проверка частных сетей и внутренних доменов управляется общим полем `tools.blockPrivateNetworks`; по умолчанию она включена;
* это один из самых мощных инструментов, требующий осторожности при использовании.

***

### Коммуникация и управление Велесом

#### `ask_user`

Назначение:

* задать пользователю уточняющий вопрос;
* предложить варианты ответа, когда задачу нельзя продолжать надёжно без выбора пользователя.

Типичный сценарий:

* нужно выбрать стратегию перед изменением файлов;
* не хватает обязательного параметра;
* несколько вариантов одинаково правдоподобны и ошибка выбора дорого стоит.

#### `message`

Назначение:

* отправка сообщений обратно в канал связи;
* используется для обычных ответов и промежуточных уведомлений.

Типичный сценарий:

* Велес должен ответить в другой канал;
* фоновая задача завершена, и нужно отдельно сообщить о результате.

#### `model`

Назначение:

* отображение информации о текущей модели;
* временное переключение модели без перезапуска процесса.

Типичный сценарий:

* проверка активной модели;
* временная смена модели для текущей сессии.

Важно:

* изменения носят временный характер и сбрасываются после перезапуска Велеса.

#### `spawn`

Назначение:

* создание отдельного фонового помощника;
* перенос длительных или изолированных задач в параллельный процесс.

Типичный сценарий:

* масштабная исследовательская задача;
* длительная обработка данных;
* независимая побочная работа, которую нецелесообразно держать в основном потоке.

***

### Память и история сессий

#### `session_list`

Назначение:

* отображение списка завершенных сессий из `sessions/_sessions.jsonl`;
* помощь в выборе нужного `session_id`.

Когда особенно полезен:

* нужно понять, какие завершенные сессии существуют;
* поиск прошлой сессии по названию (slug), ключу или связанному файлу памяти.

#### `session_history`

Назначение:

* извлечение полной истории текущей или архивной сессии;
* работа по ключу сессии (`session_key`) или её идентификатору (`session_id`).

Когда особенно полезен:

* восстановление точного текста диалога (transcript);
* просмотр результатов работы инструментов в прошлом;
* проверка ранее сказанного.

#### `memory_search`

Назначение:

* поиск по файлам памяти `memory/MEMORY.md` и `memory/*.md`;
* использование гибридного поиска (семантический + по ключевым словам).

Когда особенно полезен:

* восстановление прошлых решений;
* поиск сохраненных предпочтений пользователя;
* поиск заметок по конкретной теме.

Важно:

* инструмент доступен только при включенной векторной памяти (`vector_memory`).

#### `vector_search`

Назначение:

* поиск по проектной документации в `docs/<project>/`;
* использование гибридного поиска.

Когда особенно полезен:

* работа с документацией, уже размещенной в папке `docs/`;
* смысловой поиск по большим объемам текстов проекта.

Важно:

* инструмент также требует включенной настройки `vector_memory`.

***

### Документы и распознавание (OCR)

#### `document_parse`

Назначение:

* извлечение текста из документов и изображений;
* работа в качестве OCR/парсера для PDF, офисных форматов и картинок.

Когда особенно полезен:

* обработка присланных сканов, PDF-файлов или документов;
* получение markdown-версии содержимого;
* последующее сохранение результата в документацию проекта.

Замечания:

* реальная доступность зависит от настроенного бэкенда распознавания (OCR-сервиса);
* служит удобным мостом между внешним файлом и внутренней базой знаний проекта.

***

## Условные встроенные инструменты

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

### `cron`

Назначение:

* создание, просмотр и удаление запланированных задач и напоминаний.

Когда доступен:

* только если у Велеса подключена служба расписаний (`cron_service`).

Когда полезен:

* установка напоминаний;
* выполнение регулярных заданий;
* действия по расписанию.

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

### Инструменты MCP

Назначение:

* это не единичный инструмент, а набор внешних возможностей, подключенных через протокол MCP (Model Context Protocol).

Когда доступны:

* только если настроены и успешно подключены MCP-серверы.

Что это дает:

* расширение возможностей Велеса без изменения его основного кода;
* доступ к внешним системам, сторонним API и специализированным утилитам.

***

## Как инструменты видит пользователь и Велес

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

* «прочитай файл»;
* «исправь ошибку»;
* «найди это в интернете»;
* «поищи в памяти»;
* «покажи прошлую сессию».

С точки зрения Велеса это превращается в цепочку действий:

1. анализ структуры проекта;
2. чтение нескольких файлов;
3. выполнение поиска;
4. редактирование файла;
5. запуск команды;
6. возврат итогового результата.

Именно поэтому одно сообщение пользователя часто запускает серию вызовов инструментов (вызовов инструментов).

***

## В чем различия между похожими инструментами

### `web_search` против `web_fetch`

* `web_search` ищет места, где может быть информация;
* `web_fetch` читает содержимое уже известной страницы или ссылки и при длинном тексте даёт путь к сохранённой полной версии.

### `memory_search` против `session_history`

* `memory_search` ищет по обобщенным файлам памяти и сводкам;
* `session_history` извлекает дословную историю конкретной сессии.

### `vector_search` против `memory_search`

* `vector_search` работает с документацией проекта в папке `docs/`;
* `memory_search` работает с личной памятью Велеса в папке `memory/`.

### `write_file` против `edit_file`

* `write_file` предназначен для создания файла целиком;
* `edit_file` предназначен для точечных правок в существующем файле.

***

## Зависимость от конфигурации

Набор доступных инструментов может варьироваться между разными экземплярами Велес.

Особенно это актуально для:

* системы исполнения команд (`exec`);
* планировщика (`cron`);
* векторного поиска (`vector_search`);
* поиска по памяти (`memory_search`);
* инструментов MCP;
* качества и доступности парсера документов (`document_parse`).

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

***

## Практический вывод

В текущей реализации Велес инструменты можно разделить на пять основных групп:

* файловые;
* сетевые;
* системные;
* инструменты памяти и поиска;
* оркестрация и интеграции.

Обычному пользователю достаточно понимать, что Велес способен совершать практические действия, выходящие за рамки простого общения.

Для продвинутых пользователей и разработчиков важно понимать тонкие различия между инструментами, в частности:

* разницу между поиском в сети и чтением конкретного ресурса;
* разницу между обобщенной памятью и точной историей диалогов;
* разницу между проектной документацией и личной памятью Велеса;
* разницу между редактированием файлов и выполнением системных команд.

***

## Итог

Современный Велес умеет работать с файлами, интернетом, локальным окружением, памятью, историей сессий, документами (через OCR), фоновыми задачами и внешними интеграциями через MCP.

Это делает инструменты ключевым фактором полезности Велеса: без них он был бы просто генератором текста, а с ними превращается в полноценного Велеса, способного выполнять реальную работу.
ументы и OCR

#### `document_parse`

Назначение:

* извлекает текст из документов и изображений;
* работает как OCR/парсер для PDF, офисных форматов и картинок.

Когда особенно полезен:

* пользователь прислал скан, PDF или документ;
* нужно получить markdown-версию содержимого;
* нужно потом сохранить результат в документацию проекта.

Замечания:

* реальная доступность зависит от настроенного OCR/backend-сервиса;
* удобен как мост между внешним документом и внутренней базой знаний проекта.

***

## Условные встроенные инструменты

Некоторые инструменты регистрируются не всегда.

### `cron`

Назначение:

* создаёт, показывает и удаляет запланированные задачи и напоминания.

Когда доступен:

* только если у Велеса подключён `cron_service`.

Когда полезен:

* напоминания;
* регулярные задания;
* действия по расписанию.

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

### MCP-инструменты

Назначение:

* это не один конкретный tool, а набор внешних tools, подключённых через MCP.

Когда доступны:

* только если настроены MCP-серверы;
* только после успешного подключения этих серверов.

Что это даёт:

* расширение возможностей Велеса без изменения основного кода;
* доступ к внешним системам, API и специализированным инструментам.

***

## Как инструменты видит пользователь, а как Велес

С точки зрения пользователя всё обычно выглядит просто:

* «прочитай файл»;
* «исправь ошибку»;
* «найди это в интернете»;
* «поищи по памяти»;
* «покажи прошлую сессию».

С точки зрения Велеса это может превращаться в цепочку:

1. посмотреть структуру проекта;
2. прочитать несколько файлов;
3. выполнить поиск;
4. отредактировать файл;
5. запустить команду;
6. вернуть результат.

Именно поэтому одно пользовательское сообщение часто приводит к нескольким последовательным вызовов инструментов.

***

## Чем отличаются похожие инструменты

### `web_search` vs `web_fetch`

* `web_search` ищет, где может быть нужная информация;
* `web_fetch` читает уже конкретную страницу или URL и при длинном тексте даёт путь к сохранённой полной версии.

### `memory_search` vs `session_history`

* `memory_search` ищет по сохранённым memory-файлам и summary;
* `session_history` достаёт точный transcript конкретной сессии.

### `vector_search` vs `memory_search`

* `vector_search` работает по проектной документации в `docs/`;
* `memory_search` работает по памяти Велеса в `memory/`.

### `write_file` vs `edit_file`

* `write_file` удобен для создания файла целиком;
* `edit_file` удобен для локальных изменений в существующем файле.

***

## Что реально зависит от конфигурации

Набор инструментов может меняться между разными инстансами Велес.

Особенно это касается:

* `exec`;
* `cron`;
* `vector_search`;
* `memory_search`;
* MCP-инструментов;
* качества и доступности `document_parse`.

Поэтому документацию по tools полезно читать как описание возможных способностей, а не как гарантию, что всё это включено в каждом запуске.

***

## Практический вывод

Если смотреть на текущую реализацию Велес, инструменты можно условно разделить на пять групп:

* файловые;
* сетевые;
* системные;
* память и retrieval;
* оркестрация и интеграции.

Для обычного пользователя достаточно знать, что Велес умеет делать практические действия поверх текста.

Для продвинутого пользователя или разработчика важно понимать точные различия между tools, особенно между:

* поиском в интернете и чтением конкретной ссылки;
* памятью и точной историей сессий;
* документацией проекта и долговременной памятью;
* локальным редактированием файлов и выполнением shell-команд.

***

## Итог

Текущий Велес умеет работать с файлами, интернетом, локальным окружением, памятью, историей сессий, OCR-документами, фоновыми задачами и внешними MCP-интеграциями.

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