Skip to main content

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.

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

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

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

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

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

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

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

​
read_file

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

​
write_file

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

​
edit_file

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

​
list_dir

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

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

Назначение:
  • поиск информации в глобальной сети;
  • возвращает заголовки, URL и краткие фрагменты (сниппеты) текста.
Типичный сценарий:
  • поиск актуальной или внешней информации;
  • подбор источников перед детальным изучением конкретной страницы.
Замечания:
  • использует настроенный провайдер веб-поиска;
  • конкретный бэкенд зависит от конфигурации;
  • результатом является список ссылок-кандидатов, а не полный текст страниц.

​
web_fetch

Назначение:
  • загрузка контента по конкретному URL;
  • извлечение содержимого страницы, JSON или других поддерживаемых ресурсов.
Типичный сценарий:
  • пользователь предоставил прямую ссылку;
  • чтение статьи, ответа API или страницы документации.
Замечания:
  • внешний контент считается недоверенным;
  • инструмент используется для получения данных, а не для прямого исполнения инструкций со страницы.

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

​
exec

Назначение:
  • выполнение команд в shell/терминале.
Типичный сценарий:
  • запуск тестов;
  • сборка проекта;
  • установка зависимостей;
  • проверка параметров окружения;
  • запуск локальных утилит.
Важно:
  • инструмент регистрируется, только если exec разрешен в конфигурации;
  • ограничения зависят от режима безопасности и настроек ограничений рабочей области (workspace restrictions);
  • это один из самых мощных инструментов, требующий осторожности при использовании.

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

​
ask_user

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

​
message

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

​
model

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

​
spawn

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

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

​
session_list

Назначение:
  • отображение списка завершенных сессий из sessions/_sessions.jsonl;
  • помощь в выборе нужного session_id.
Когда особенно полезен:
  • нужно понять, какие завершенные сессии существуют;
  • поиск прошлой сессии по названию (slug), ключу или связанному файлу памяти.

​
session_history

Назначение:
  • извлечение полной истории текущей или архивной сессии;
  • работа по ключу сессии (session_key) или её идентификатору (session_id).
Когда особенно полезен:
  • восстановление точного текста диалога (transcript);
  • просмотр результатов работы инструментов в прошлом;
  • проверка ранее сказанного.
Назначение:
  • поиск по файлам памяти memory/MEMORY.md и memory/*.md;
  • использование гибридного поиска (семантический + по ключевым словам).
Когда особенно полезен:
  • восстановление прошлых решений;
  • поиск сохраненных предпочтений пользователя;
  • поиск заметок по конкретной теме.
Важно:
  • инструмент доступен только при включенной векторной памяти (vector_memory).
Назначение:
  • поиск по проектной документации в 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 работает с документацией проекта в папке 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-интеграциями. Это делает инструменты центральной частью практической полезности Велеса: без них он был бы просто генератором текста, а с ними становится Велесом, который может реально выполнять действия.