Skip to main content

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

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

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

Инструмент в Велес — это отдельное действие, которое модель может вызвать во время формирования ответа. На практике это означает, что Велес может:
  • не только генерировать текст;
  • но и искать информацию;
  • читать и редактировать файлы;
  • запускать команды в системе;
  • использовать долговременную память;
  • создавать фоновые задачи;
  • обращаться к внешним интеграциям.
Обычно пользователь описывает задачу обычным языком, а модель сама выбирает необходимые инструменты.

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

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

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

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

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

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

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

​
read_file

Назначение:
  • чтение текстовых файлов;
  • чтение содержимого изображений как ресурса;
  • используется для анализа кода, конфигураций, markdown и других файлов.
Для изображений Велес готовит ограниченную по размеру копию из своей рабочей области. Она попадет в запрос только для модели, где в настройке modalities указаны image или vision; для текстовых моделей Велес оставит текстовое описание файла. Если файл недоступен или слишком велик после подготовки, в контекст добавляется короткое текстовое замечание вместо скрытой потери изображения. Для текстовых файлов действует защитный предел размера. Одна порция содержит не более примерно 12 тысяч символов, после чего результат указывает следующую строку. Такой предел оставляет текст и указание продолжения непосредственно в контексте модели, не заменяя обычное чтение ссылкой на отдельно сохранённый большой вывод. Очень длинная строка в постраничном чтении обрезается в конце возвращаемого фрагмента, а следующий вызов продолжает чтение со следующей строки, чтобы модель не застревала на одном и том же начале файла. Когда особенно полезен:
  • разбор структуры проекта;
  • чтение документации;
  • проверка содержимого конкретного файла.

​
write_file

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

​
edit_file

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

​
list_dir

Назначение:
  • просмотр содержимого директорий;
  • помощь в понимании структуры проекта.
Когда особенно полезен:
  • первичное обследование репозитория;
  • поиск нужной папки или документа;
  • проверка наличия файлов.

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

Назначение:
  • поиск информации в глобальной сети;
  • возвращает заголовки, 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.md в корне рабочей области, если он есть, и по memory/**/*.md, кроме сырых аварийных архивов memory/*-raw-archive.md;
  • использование гибридного поиска (семантический + по ключевым словам).
Когда особенно полезен:
  • восстановление прошлых решений;
  • поиск сохраненных предпочтений пользователя;
  • поиск заметок по конкретной теме.
Важно:
  • инструмент доступен только при включённой настройке tools.vectorMemory.enabled.
  • файлы крупнее tools.vectorMemory.maxFileBytes и сырые аварийные архивы остаются на диске, но в результаты не попадают.
Назначение:
  • поиск по проектной документации в docs/<project>/;
  • использование гибридного поиска.
Когда особенно полезен:
  • работа с документацией, уже размещенной в папке docs/;
  • смысловой поиск по большим объемам текстов проекта.
Важно:
  • инструмент также требует включённой настройки tools.vectorMemory.enabled.
  • один индексируемый файл по умолчанию ограничен 8 МиБ; предел меняется через tools.vectorMemory.maxFileBytes.

​
Документы и распознавание (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 работает с документацией проекта в папке 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 работает по проектной документации в 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-интеграциями. Это делает инструменты центральной частью практической полезности Велеса: без них он был бы просто генератором текста, а с ними становится Велесом, который может реально выполнять действия.