Skip to main content

​
Как устроен Велес

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

​
Общая схема

​
Поток сообщения

  1. Пользователь отправляет сообщение в Велес.
  2. Велес определяет текущую сессию, активную личность и загружает нужный контекст.
  3. Модель анализирует задачу.
  4. Если нужны действия, Велес использует инструменты: читает файлы, ищет информацию, обращается к памяти, создаёт задачу или запускает внешний сервис.
  5. Результаты инструментов возвращаются в модель.
  6. Велес сохраняет историю и показывает ответ пользователю.

​
Основные части

​
Встроенные модули продукта

Задачи, календарь и интерактивная почта подключены к шлюзу через небольшой статический реестр. Это не система установки расширений: Велес не ищет сторонние репозитории и не исполняет добавленный извне код. Реестр только связывает заранее собранный модуль с его жизненным циклом, маршрутами, обработчиками вызовов, средствами агента и, при необходимости, внешним контекстом. При запуске шлюз один раз читает modules.<id>.enabled. Для выключенного модуля не создаётся прикладная служба, не запускается фоновая работа, не регистрируются маршруты и средства агента. Nerve получает тот же снимок состояния от шлюза и скрывает соответствующие представления. Перечитывание секретов обновляет настройки уже включённых модулей, но не включает и не выключает их без перезапуска. Постоянные данные остаются у Велеса и не переносятся в Nerve. Поэтому цикл «выключить — перезапустить — включить — перезапустить» возвращает прежние задачи, календарные источники и почтовый анализ. Код каждого такого модуля собран вертикально в veles/modules/<id>/. Внутри находятся его точка подключения module.py, прикладная служба, типы, маршруты, средства агента и адаптеры внешних систем. Общий реестр и жизненный цикл находятся в veles/modules/manager.py, а нейтральные примитивы проверки HTTP-запросов — в veles/api/http.py. Основной файл veles/api/routes.py содержит только маршруты ядра и не знает о прикладных исключениях задач, почты или календаря. Проверки доменов повторяют ту же структуру в tests/modules/<id>/.
Модули не импортируют реализацию друг друга. Общий код выносится в ядро только тогда, когда он действительно не зависит от предметной области. Почтовый канал агента остаётся в veles/channels: это независимый способ доставки сообщений, а не часть интерактивного почтового модуля.

​
Рабочая область

Рабочая область — это папка, с которой работает Велес. В ней могут находиться:
  • документы;
  • заметки;
  • файлы памяти;
  • результаты работы;
  • инструкции для поведения ассистента;
  • файлы проекта.
Если вы хотите изолировать проекты, используйте разные рабочие области. SOUL.md в корне workspace задаёт личность main; дополнительные личности лежат в personalities/<id>/SOUL.md. У дополнительной личности может быть свой каталог personalities/<id>/skills, который подключается только для активной личности. Файл AGENTS.md остаётся общим проектным контекстом для всех личностей. Подробнее: Личности.

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

История сессии нужна для текущего диалога. Память нужна для сведений, которые должны сохраниться надолго. Не всё из истории должно попадать в память. Хорошая память короткая, проверяемая и полезная в будущем: предпочтения пользователя, правила проекта, постоянные ограничения, важные решения.

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

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

​
Задачи и доска

Доска задач в интерфейсе — это клиент к задачам Велеса. Nerve не хранит состояние процесса самостоятельно: Локальные задачи остаются файлами в рабочей области. Задачи YouTrack и Bitrix24 не копируются туда: Велес получает их по настроенным адресам и недолго хранит последний удачный снимок каждого источника. При первом запросе страницы он объединяет локальные и внешние записи в отдельный краткоживущий снимок всей выдачи не более чем на две минуты; последующие страницы используют его непрозрачный идентификатор и потому не сдвигаются из-за параллельных изменений. Повторная синхронизация не создаёт дубликаты. «Поручить Велесу» — явное исключение: шлюз создаёт один обычный локальный файл задачи со структурированной ссылкой на внешнюю запись и запускает его через стандартный исполнитель. Повторный запрос на ту же внешнюю задачу возвращает существующий локальный файл. Этот путь не вызывает запись в YouTrack или Bitrix24 и никогда автоматически не завершает исходную задачу. Завершение во внешнем источнике остаётся отдельным подтверждаемым действием шлюза; Nerve не получает секреты внешних систем. Новые интеграции должны использовать /api/tasks/*. Старый путь /api/kanban/* оставлен только для совместимости.

​
Секреты

API-ключи, токены и OAuth-подключения не должны попадать в чат. Велес хранит и использует секреты отдельно, а в интерфейсе показывает только состояние: настроен секрет или нет.

​
Что читать дальше