Граф кода и база знаний

Граф кода — экспериментальная функция. Его интерфейс, формат данных и поведение индексации могут измениться в следующих версиях.

Граф кода использует CodeGraph для анализа символов проекта и связей между ними. Проектные решения, ограничения и накопленный опыт хранятся в разделе База знаний сеансов. Ссылки на код соединяют одно с другим, поэтому вы видите и текущую структуру кода, и причины, по которым она устроена именно так.

Страницы

Граф кода открывается в диалоговом окне с вкладками «Обзор», «Символы», «Исследование кода» и «Файлы». Кнопка «База знаний» в этом окне открывает базу знаний.

Обзор: число файлов, символов и связей, распределение по языкам и видам символов, а также состояние синхронизации («Автосинхронизация включена» или «Синхронизация перед запросами»). Щёлкните элемент распределения, чтобы увидеть соответствующие результаты.
Символы: поиск по имени или пути к файлу («Поиск символов или путей к файлам…»). На странице символа показаны его исходный код с подсветкой синтаксиса, а также «Входящие связи» и «Исходящие связи», сгруппированные по типу связи и файлу. Связи, выведенные анализом, помечены как «Предполагаемая связь», а номера строк ведут к месту вызова.
Исследование кода: опишите функциональность или сценарий работы либо укажите файл или символ, чтобы увидеть относящийся к ним исходный код и связи. Этот запрос выполняется локально и не использует модель ИИ.
Файлы: просмотр проиндексированных файлов; щёлкните файл, чтобы увидеть список его символов.
Вызывающие символы и Вызываемые символы: на странице символа показывают несколько уровней вызовов. «Глубина обхода» по умолчанию равна 3, максимум — 6. Показывается до 500 результатов; если их больше, выводятся общее число и уведомление.
Анализ влияния: на странице символа показывает символы и файлы, которые может затронуть изменение, до выбранной глубины (по умолчанию 3, максимум 6). Показывается до 500 символов и 2000 связей; если результат усечён, выводятся общее число и уведомление.
Путь вызовов: на странице символа найдите целевой символ («Найти целевой символ…»), чтобы увидеть кратчайший путь по связям вызовов. Сообщение «В индексе не найден направленный путь вызовов.» означает лишь, что в индексе такого пути нет.

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

Включение индекса проекта

Щёлкните проект или коллекцию в боковой панели правой кнопкой мыши и выберите «Экспериментальная функция» → «Граф кода».
При первом использовании нажмите «Скачать CodeGraph». Сервер VelaTerm, к которому вы подключены, загружает с GitHub фиксированный выпуск CodeGraph 1.6.0 и сверяет его со встроенной контрольной суммой SHA-256 (сообщение «Контрольная сумма загрузки не совпала. Среда выполнения не установлена.» означает, что проверка не пройдена). Отдельно устанавливать Node.js не нужно.
Выберите каталог в поле «Рабочий каталог» и нажмите «Включить индексацию». Каталог проекта и другие рабочие каталоги, которые используют его сессии и группы, перечислены отдельно; у каждого рабочего дерева Git собственный индекс. В коллекции должна быть хотя бы одна сессия с действительным рабочим каталогом.
Дождитесь статуса «Готово», затем ищите символы или пути к файлам. Индексация выполняется в фоне («Выполняется индексация. Можно закрыть эту страницу или отключить индексацию, чтобы остановить задачу.»), и закрытие страницы её не отменяет.

«Синхронизировать» обновляет индекс вручную или повторяет попытку после сбоя. Кроме того, перед каждым запросом к коду VelaTerm сам приводит индекс в актуальное состояние. Для одного и того же сервера и рабочего каталога используется один процесс запросов, который во время работы сразу учитывает изменения файлов. Он завершается после пяти минут без запросов; следующий запрос снова открывает индекс и учитывает накопившиеся изменения. Вкладка «Обзор» обновляет состояние синхронизации каждые 30 секунд; если автоматическая синхронизация недоступна, VelaTerm всё равно синхронизирует индекс перед каждым запросом и никогда не выдаёт устаревший результат за актуальный.

«Отключить индексацию» останавливает выполняемую задачу индексации, но сохраняет файлы индекса и связи со статьями базы знаний, поэтому позже индексацию можно включить снова. Если задача прервана, примерно через две минуты она переходит в состояние ошибки, после чего её можно повторить («Предыдущая задача была прервана. Запустите синхронизацию для повторной попытки.»). Одна задача индексации может выполняться не более 30 минут.

Индексы хранятся в папке .codegraph/ в каждом рабочем каталоге, и ими управляет CodeGraph. VelaTerm выполняет индексацию сам; он не запускает установщик агентов CodeGraph и не устанавливает хуки Git. Если каталог проекта — это подпапка репозитория, индексируется только эта папка.

Просмотр связей в коде

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

Связи определяются статическим анализом и могут быть неполными или неточными (интерфейс сообщает: «Связи получены статическим анализом и могут быть неполными или неточными.»); они не заменяют запуск кода. На странице символа показывается не более 200 связей в каждом направлении и 600 строк исходного кода; если данных больше, выводится уведомление. Исходные файлы размером более 4 МиБ не отображаются. Если файл изменился во время просмотра, VelaTerm предлагает снова выполнить синхронизацию, прежде чем полагаться на номера строк.

Связывание и проверка статей

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

Связь хранит проект, рабочий каталог, путь к файлу, идентификатор символа и дайджест SHA-256 файла на момент проверки. Когда файл изменяется, у связи появляется статус «Требуется проверка»; когда файл больше нельзя прочитать или он удалён — «Недоступно»; в остальных случаях — «Без изменений». Проверка выполняется на уровне файла, поэтому любое изменение в том же файле требует повторной проверки. Открытая страница статьи регулярно проверяет свои ссылки.

Выберите «Проверить код и статью», чтобы увидеть текущий код, и нажмите «Подтвердить проверку», если статья по-прежнему верна. Сервер ещё раз проверяет, что файл и статья за это время не изменились, а если изменились — просит загрузить страницу заново. Подтверждение обновляет только ссылку на код и не изменяет текст статьи. Чтобы изменить вывод, отредактируйте статью обычным образом.

Если символ удалён или переименован, связь не переходит к другому символу с тем же именем. Нажмите «Удалить связь» и свяжите статью с нужным символом. Удаление статьи удаляет её связи; удаление проекта удаляет его записи индекса и связи, но не затрагивает другие статьи и файлы индекса в рабочих каталогах.

Запросы из сессии

Команда vkb доступна в каждой терминальной сессии и сессии агента, которую запускает VelaTerm. Ею могут пользоваться и другие агенты, умеющие выполнять команды терминала. Если после обновления в уже открытой сессии команда vkb не находится, перезапустите сессию.

Если установлены навыки «Vela Skills» (Настройки ▸ Общие), Claude может использовать /vkb, а Codex — $vkb. Навык запускается только по вашему явному запросу; во время другой работы агенты не вызывают его самостоятельно. Если после обновления агент не показывает навык, нажмите «Переустановить» и перезапустите сессию этого агента.

vkb status
vkb explore "how a session is created and its working directory chosen"
vkb search "greet"
vkb node "<symbol ID from a search result>"
vkb callers "<symbol ID>" 2
vkb callees "<symbol ID>" 2
vkb impact "<symbol ID>" 3
vkb path "<start symbol ID>" "<end symbol ID>"
vkb files "src/session"
vkb memories "design decision"
vkb memory "<entry ID from a search result>"
vkb notes "reading notes"
vkb note <knowledge-base-ID> "folder/note.md"

explore возвращает тот же результат, что и вкладка «Исследование кода».
callers, callees и impact принимают необязательный параметр глубины; их результаты содержат relations, total, depth и truncated.
path принимает два точных идентификатора символов из результатов поиска, а files может фильтровать по пути.
search отдельно возвращает результаты по коду (отсортированные по релевантности, с полем hasMore, если есть ещё результаты), статьи базы знаний и локальные заметки.
node возвращает исходный код символа, его связи и связанные статьи.
memories и memory ищут и читают статьи базы знаний сеансов, включая источники, версии и ссылки на код.
notes и note ищут и читают локальные базы знаний (см. Локальные базы знаний).

Запросы к коду используют индекс каталога, в котором выполняется команда. Подпапка использует индекс своего проекта, а вложенное отдельное рабочее дерево никогда не заимствует индекс основной рабочей копии. Если индекс не включён или запрос завершился ошибкой, в результате сообщается, что код недоступен, а запросы к базе знаний по-прежнему работают. Эти команды ничего не устанавливают, не включают индексацию и не изменяют статьи.

Где хранятся данные

Среда выполнения CodeGraph устанавливается в codegraph/1.6.0/ в каталоге данных приложения. Задачи индексации и связи со статьями хранятся в базе данных приложения (таблицы knowledge_*). Индексация выполняется на том сервере, где находится код; браузерные клиенты и SSH-подключения читают результаты через уже установленное соединение, поэтому дополнительный порт не открывается. Каждый сервер хранит собственные настройки индексов и собственную базу знаний.

Телеметрия, проверка обновлений и отдельная фоновая служба CodeGraph отключены. VelaTerm управляет процессом запросов и обменивается с ним данными через закрытый канал стандартного ввода и вывода, не прослушивая порт. Сама индексация не использует ИИ. Код или статьи, которые агент читает через vkb, могут передаваться в сервис модели, настроенный для этого агента, так же как при чтении агентом исходных файлов.

События графа кода записываются в logs/runtime-*.log в каталоге данных приложения. Если переменная VLX_LOG_DIR не задана, их каталог задаёт VLX_KNOWLEDGE_LOG_DIR. VLX_KNOWLEDGE_LOG_LEVEL фильтрует эти события (например, error или off). Журнал не содержит исходного кода, текста запросов, текста статей и учётных данных.

CodeGraph разрабатывается на github.com/colbymchenry/codegraph и распространяется по лицензии MIT.