Локальные базы знаний

Локальная база знаний — это обычная папка с файлами Markdown, которые вы пишете и упорядочиваете в VelaTerm. Заметки и вложения хранятся в этой папке, поэтому их можно по-прежнему редактировать и в других редакторах. В некоторых пунктах меню локальная база знаний называется «блокнотом»; оба слова обозначают одну и ту же папку.

Рядом с локальными базами знаний находится встроенная «База знаний сеансов». В ней хранятся знания, которые агенты собирают из ваших сессий, а статьи, источники и история версий ведутся в ней отдельно; см. База знаний сеансов.

Открытие базы знаний

Щёлкните значок базы знаний в правой панели (подсказка «База знаний»). В центральной области откроется вкладка «База знаний» с главной страницей, на которой находятся:

поле поиска («Поиск по знаниям сеансов и локальным заметкам…», см. раздел «Поиск» ниже);
«База знаний сеансов»;
ваши «Локальные базы знаний»;
кнопки «Открыть базу знаний» и «Создать базу знаний».

В правой панели показано дерево с тремя корневыми разделами: «База знаний сеансов», «Архивные сессии» и «Локальные базы знаний». Щёлкните стрелку, чтобы развернуть папку прямо в дереве; развернуть можно сразу несколько баз знаний. Щёлкните название папки, чтобы показать её содержимое, а щелчок по заметке открывает её. Ссылка «Базы знаний» вверху дерева возвращает на главную страницу, а кнопка «На уровень выше» в заголовке страницы открывает родительскую страницу, не покидая базу знаний.

Заметки открываются в обычных вкладках документов, где доступны те же редактирование, сохранение, поиск и экспорт в PDF, что и для любого другого файла Markdown (см. Вкладки документов и браузера). Вкладка «База знаний» остаётся на панели вкладок, чтобы вы могли вернуться к тому месту, где остановились.

Открытие и создание локальной базы знаний

Открытие: нажмите «Открыть базу знаний» и выберите папку. Настольное приложение показывает системное окно выбора папки, а браузерный клиент — обзор папок подключённого компьютера. Существующее хранилище Obsidian можно открыть напрямую: файлы остаются на своих местах, а скрытые папки, например .obsidian, не индексируются и не изменяются.
Создание: нажмите «Создать базу знаний», введите название в поле «Имя», укажите расположение в поле «Папка» (или нажмите «Обзор»; по умолчанию предлагается ~/Notes) и подтвердите. VelaTerm создаёт папку и открывает её. Родительская папка должна существовать, а папки с таким же именем быть не должно; иначе VelaTerm показывает сообщение «Такой файл или папка уже существует. Выберите другое имя или папку.» Чтобы использовать существующую папку, выберите «Открыть базу знаний».
Переименование: щёлкните базу знаний в дереве правой кнопкой мыши и выберите «Переименовать». При этом переименовывается папка на диске.
Закрытие: нажмите «Закрыть блокнот» на панели инструментов базы знаний или выберите этот пункт в контекстном меню базы знаний в дереве. Закрытие убирает папку из списка, а её файлы остаются на диске. Если снова открыть ту же папку, её корзина и история импорта сохранятся.

«Локальный» здесь означает компьютер, на котором работает сервер VelaTerm, к которому вы подключены. В браузерном клиенте «Открыть базу знаний» показывает папки этого компьютера, а при импорте файлы, выбранные в браузере, загружаются на этот компьютер.

Импорт файлов и папок

Откройте нужную базу знаний и нажмите «Импорт» на её панели инструментов.
Выберите папку назначения в поле «Папка», затем нажмите «Выбрать файлы» или «Выбрать папку» либо перетащите файлы и папки в область импорта.
Проверьте список и подтвердите импорт.

Импорт выполняется в фоне, поэтому во время копирования можно переходить на другие страницы или открывать заметки. Ход импорта отображается на панели инструментов базы знаний и на главной странице, а отменить импорт можно в окне импорта или на странице «История импорта». По завершении баннер показывает число импортированных и пропущенных файлов; если окно не в фокусе, появляется системное уведомление («Импорт завершён» или «Не удалось выполнить импорт»). В одной базе знаний одновременно может выполняться только один импорт.

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

За один импорт можно передать до 5000 файлов (пропущенные скрытые файлы тоже учитываются в этом ограничении) общим объёмом до 1 ГиБ и не более 100 МиБ на файл. Сначала файлы помещаются в промежуточную область и появляются в папке назначения только после получения всего пакета, поэтому прерванная загрузка никогда не оставляет недописанную заметку.

На странице «История импорта» перечислены все операции импорта: время, место назначения («Корень базы знаний» для верхней папки), статус («Импорт», «Завершён», «Ошибка», «Отменён» или «Прерван»), число импортированных и пропущенных файлов, объём и длительность. Нажмите «Файлы (N)», чтобы увидеть каждый файл и причину его пропуска. «Удалить запись» удаляет запись из истории, но не удаляет импортированные файлы. Импорт, ход которого не менялся более двух минут (например, из-за неожиданного завершения приложения), помечается как «Прерван»; удаление его записи удаляет и файлы, подготовленные для этого импорта.

Создание и упорядочивание заметок

На странице базы знаний есть разделы «Недавние заметки», «Корзина» и «История импорта», кнопка «Новая заметка», а на панели инструментов — кнопки «Новая папка», «Импорт» и «Закрыть блокнот». Список заметок можно отфильтровать по тегу («Все метки») и отсортировать по признаку «Недавно обновлённые» или «По заголовку».

Когда открыта страница базы знаний, ⌘N / Ctrl+N создаёт заметку («Новая заметка»), ⌘O / Ctrl+O открывает «Быстрое открытие» (поиск заметки по пути), а ⌘⇧F / Ctrl+Shift+F переводит фокус в поле «Поиск заметок…».
Чтобы переименовать заметку, щёлкните её в дереве правой кнопкой мыши и выберите «Переименовать». Чтобы переместить заметку, перетащите её в другую папку той же базы знаний. «Удалить» перемещает заметку в корзину базы знаний.
Когда открыта папка, «Переименовать или переместить» перемещает её по указанному пути относительно корня базы знаний; родительская папка должна уже существовать. При перемещении заметки или папки ссылки в других заметках той же базы знаний обновляются: текст ссылок сохраняется, а код не затрагивается.
Удалённые элементы попадают в папку .vkb-trash внутри базы знаний. Чтобы вернуть элемент, откройте раздел «Корзина» и нажмите «Восстановить»; существующий файл с тем же именем никогда не перезаписывается.
Теги берутся из #tag в тексте, а также из списка или массива tags в YAML.
Изображения, вставленные в заметку, сохраняются в папку assets рядом с заметкой.

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

Страницы базы знаний, диалоговые окна, история импорта, поисковые запросы, область поиска, теги, сортировка и быстрое открытие отражаются в URL, поэтому страницу можно обновить, а также пользоваться кнопками «Назад» и «Вперёд» в браузере. Несохранённый текст и данные, введённые в формы, в URL не входят.

Поиск

Главная страница: поиск выполняется одновременно по базе знаний сеансов и всем локальным базам знаний, а результаты группируются по источнику. Архивные сессии в поиск не входят.
Правая панель: поле «Поиск заметок…» над деревом ищет по всем локальным базам знаний.
Страница базы знаний: поле «Поиск заметок…» ищет по именам, путям и тексту заметок. «Область поиска» переключает режим между «Эта база знаний» и «Все базы знаний».

Если введено несколько слов, совпасть должны все. Для каждого результата показаны база знаний или группа сессий, фрагмент текста, номер строки, число совпадений и «Связанные заметки», на которые ссылается заметка; щёлкните любой из этих элементов, чтобы открыть его. Клавиши ↑ и ↓ выбирают результат, Enter открывает его, а Esc очищает поиск. Сначала идут результаты с совпадениями в имени или пути, затем результаты упорядочиваются по числу совпадений и по времени последнего изменения. Выводится не более 100 результатов; если их больше, в конце списка появляется сообщение «Показаны только первые результаты. Уточните запрос, чтобы увидеть остальные.»

Сначала VelaTerm ищет точные совпадения и переходит к приблизительным, только если точных нет; в этом случае показывается сообщение «Точных совпадений нет. Показаны приблизительные результаты.» Приблизительный поиск применяется к словам из латинских букв и цифр: учитываются буквы по порядку (knwl находит knowledge), первые буквы слов (kb находит knowledge base) и небольшие опечатки (одна ошибка в словах из четырёх и более символов, две — в словах из восьми и более; knoledge находит knowledge). Китайский и любой другой текст не на латинице ищется только по точному совпадению.

Ссылки и совместимость с существующими файлами

VelaTerm распознаёт распространённые формы [[note]], [[folder/note|label]] и [[note#heading]], стандартные относительные ссылки Markdown и ![[image.png]]. Они используются для обновления ссылок при перемещении заметок, для списка «Связанные заметки» в результатах поиска и для описанных ниже команд vkb. В редакторе ссылки [[…]] отображаются как обычный текст. Если у нескольких файлов одинаковое имя, короткая ссылка разрешается, только когда цель однозначна; в противном случае укажите в ссылке путь к папке.

Файлы остаются обычными файлами Markdown, а YAML front matter сохраняется в файле; режим «Исходный код» в редакторе показывает его без изменений. Файлы Markdown не в кодировке UTF-8 или размером более 5 МиБ не отображаются как заметки и учитываются как «Пропущено». База знаний может содержать до 50 000 файлов и папок; папку большего размера открыть нельзя, и в этом случае показывается сообщение «Файл или выбранные данные превышают ограничения блокнота.» Символические ссылки не отслеживаются.

Эти возможности охватывают повседневную работу с локальными файлами, папками, Markdown, ссылками и поиском. Плагины, темы, Canvas, ссылки на блоки, встраивание заметок и псевдонимы YAML из Obsidian не поддерживаются; соответствующие файлы остаются без изменений. Модель файлов и синтаксис ссылок описаны в документации Obsidian: хранилища, внутренние ссылки и вложения.

Копирование из базы знаний сеансов и запросы агентов

Откройте статью в базе знаний сеансов, выберите «Копировать в локальный блокнот», затем укажите целевую базу знаний и имя файла. Копия — это самостоятельная заметка Markdown; исходная статья, её снимки источников и история версий остаются на месте.

В сессии VelaTerm вы или агент можете читать зарегистрированные локальные базы знаний с помощью vkb:

vkb notes "reading notes"
vkb note <knowledge-base-ID> "reading/how-to-take-notes.md"
vkb search "architecture decision"

notes ищет по всем локальным базам знаний, зарегистрированным на текущем сервере. Каждый результат содержит vaultId, vaultName, path, absolutePath, line, matches, score, matched (фактически совпавший текст), related (заметки, на которые ссылается эта заметка) и summary (текст вокруг совпадения). В ответе также есть поля total, hasMore, unavailable (базы знаний, которые не удалось прочитать) и fuzzy (являются ли результаты приблизительными). Возвращается не более 100 результатов.
note возвращает текст заметки, её структуру, ссылки, обратные ссылки и теги.
search возвращает совпадения из базы знаний сеансов, локальных заметок и, если есть индекс кода, из графа кода (см. Граф кода и база знаний).

Эти команды работают только на чтение. Они никогда не изменяют заметки, а VelaTerm не добавляет содержимое баз знаний в сессии автоматически.

Хранение данных и журналы

Основной копией заметок и вложений служат файлы на диске. База данных приложения (таблицы kb_*) хранит только список зарегистрированных баз знаний, записи корзины, историю импорта и поисковый кэш, который можно построить заново. База знаний сеансов использует собственные таблицы memory_*.

Открытие, запись, перемещение, удаление, восстановление и импорт регистрируются в журнале выполнения с идентификатором операции, количественными показателями и затраченным временем, но без содержимого заметок. Эти строки относятся к событию knowledge; если переменная VLX_LOG_DIR не задана, их каталог задаёт VLX_KNOWLEDGE_LOG_DIR. История импорта хранится в базе данных и отображается на странице «История импорта». Для полного резервного копирования базы знаний сохраните и её папку, и данные приложения, где хранятся её корзина и записи об импорте.