Graphe du code et base de connaissances

Le graphe du code est expérimental. Son interface, son format de données et son comportement d’indexation peuvent changer dans les versions ultérieures.

Le graphe du code s’appuie sur CodeGraph pour analyser les symboles d’un projet et les relations entre eux. La Base de connaissances des sessions conserve les décisions de conception, les contraintes et les enseignements. Les références au code relient les deux, afin que vous puissiez voir à la fois la structure actuelle du code et les raisons qui la sous-tendent.

Pages

Le graphe du code s’ouvre dans une boîte de dialogue comportant les onglets « Vue d’ensemble », « Symboles », « Explorer le code » et « Fichiers ». Son bouton « Base de connaissances » ouvre la base de connaissances.

Vue d’ensemble : le nombre de fichiers, de symboles et de relations, la répartition des langages et des types de symboles, et l’état de synchronisation (« Synchronisation automatique active » ou « Synchronisation avant les requêtes »). Cliquez sur un élément de la répartition pour afficher les résultats correspondants.
Symboles : recherche par nom ou par chemin de fichier (« Rechercher un symbole ou un chemin de fichier… »). La page d’un symbole affiche sa source avec coloration syntaxique ainsi que ses « Relations entrantes » et « Relations sortantes », regroupées par type de relation et par fichier. Les relations déduites par l’analyse sont marquées « Relation déduite », et les numéros de ligne mènent à l’emplacement de l’appel.
Explorer le code : décrivez une fonctionnalité ou un enchaînement, ou indiquez un fichier ou un symbole, pour afficher la source et les relations pertinentes. Cette requête s’exécute localement et n’utilise aucun modèle d’IA.
Fichiers : parcourez les fichiers indexés ; cliquez sur un fichier pour afficher la liste de ses symboles.
Appelants et Symboles appelés : sur la page d’un symbole, affichent plusieurs niveaux d’appels. La « Profondeur de parcours » est de 3 par défaut et de 6 au maximum. Jusqu’à 500 résultats sont affichés ; s’il y en a davantage, le total et un avertissement sont affichés.
Analyse des impacts : sur la page d’un symbole, affiche les symboles et les fichiers susceptibles d’être affectés par une modification, jusqu’à la profondeur choisie (3 par défaut, 6 au maximum). Jusqu’à 500 symboles et 2 000 relations sont affichés, avec le total et un avertissement lorsque le résultat est tronqué.
Chemin d’appel : sur la page d’un symbole, recherchez un symbole cible (« Rechercher un symbole cible… ») pour afficher le plus court chemin suivant les relations d’appel. Le message « Aucun chemin d’appel orienté trouvé dans l’index. » signifie uniquement que l’index ne contient pas un tel chemin.

Changez de répertoire de travail depuis le menu des répertoires, qui affiche aussi le chemin complet. La page, la question posée dans Explorer le code, le symbole, la profondeur, la cible et la ligne source font tous partie de l’URL ; vous pouvez donc actualiser la page, l’ouvrir dans un nouvel onglet ou utiliser les boutons Précédent et Suivant du navigateur. Un lien fonctionne sur le même serveur, à condition que vous y soyez connecté.

Activation de l’index d’un projet

Cliquez avec le bouton droit sur un projet ou une collection dans la barre latérale et choisissez « Expérimental » → « Graphe du code ».
La première fois, cliquez sur « Télécharger CodeGraph ». Le serveur auquel vous êtes connecté télécharge depuis GitHub la version 1.6.0 de CodeGraph, fixée à l’avance, et la vérifie à l’aide d’une somme de contrôle SHA-256 intégrée (« La somme de contrôle du téléchargement ne correspond pas. Le moteur n’a pas été installé. » signifie que la vérification a échoué). Aucune installation séparée de Node.js n’est nécessaire.
Choisissez le « Répertoire de travail » et cliquez sur « Activer l’indexation ». Le répertoire du projet et les autres répertoires de travail utilisés par ses sessions et ses groupes sont listés séparément ; chaque worktree Git dispose de son propre index. Une collection doit comporter au moins une session dont le répertoire de travail est valide.
Attendez que l’état soit « Prêt », puis recherchez des symboles ou des chemins de fichiers. L’indexation s’exécute en arrière-plan (« Une tâche d’indexation est en cours. Vous pouvez fermer cette page ou désactiver l’indexation pour arrêter la tâche. »), et la fermeture de la page ne l’annule pas.

« Synchroniser » met à jour l’index manuellement ou relance l’opération après un échec. Avant chaque requête sur le code, VelaTerm met également l’index à jour. Pour un même serveur et un même répertoire de travail, un seul processus de requête est réutilisé ; tant qu’il s’exécute, il prend en compte les modifications de fichiers au fur et à mesure. Il se termine après cinq minutes sans requête ; la requête suivante rouvre l’index et rattrape les modifications. La vue d’ensemble actualise son état de synchronisation toutes les 30 secondes ; lorsque la synchronisation automatique n’est pas disponible, VelaTerm synchronise tout de même avant chaque requête et ne présente jamais un résultat périmé comme étant à jour.

« Désactiver l’indexation » arrête une tâche d’indexation en cours et conserve les fichiers d’index ainsi que les associations aux articles de connaissance ; vous pouvez donc réactiver l’indexation plus tard. Lorsqu’une tâche est interrompue, elle passe en l’espace d’environ deux minutes à l’état d’échec, qui peut être relancé (« La tâche précédente a été interrompue. Synchronisez pour réessayer. »). Une tâche d’indexation peut durer au maximum 30 minutes.

Les index sont stockés dans un dossier .codegraph/ de chaque répertoire de travail et sont gérés par CodeGraph. VelaTerm exécute lui-même l’indexation ; il n’exécute pas le programme d’installation pour agents de CodeGraph et n’installe pas de hooks Git. Si le répertoire du projet est un sous-dossier d’un dépôt, seul ce dossier est indexé.

Consultation des relations du code

Les résultats de recherche indiquent le nom, le type et l’emplacement de chaque symbole. La page d’un symbole affiche sa source, ses relations entrantes et sortantes et les articles de connaissance associés ; cliquez sur un symbole voisin pour poursuivre.

Les relations sont issues d’une analyse statique et peuvent être incomplètes ou incertaines, comme l’indique l’interface (« Les relations proviennent d’une analyse statique et peuvent être incomplètes ou incertaines. ») ; elles ne remplacent pas l’exécution du code. La page d’un symbole affiche au plus 200 relations dans chaque sens et 600 lignes de source, avec un avertissement lorsqu’il en existe davantage. Les fichiers source de plus de 4 Mio ne sont pas affichés. Si un fichier change pendant que vous le consultez, VelaTerm vous demande de synchroniser à nouveau avant de vous fier à ses numéros de ligne.

Association et vérification des articles

Sur la page d’un symbole, choisissez « Associer un article », sélectionnez un article existant, comparez son texte avec le code, puis enregistrez. Sur la page de l’article, « Références au code » ramène au code, et les liens vers les articles dans le graphe du code ouvrent l’article complet.

Une association enregistre le projet, le répertoire de travail, le chemin du fichier, l’identité du symbole et l’empreinte SHA-256 du fichier au moment de la vérification. Lorsque le fichier change, l’association affiche « À vérifier » ; lorsque le fichier ne peut plus être lu ou a été supprimé, elle affiche « Indisponible » ; sinon, elle affiche « Inchangé ». La vérification s’effectue au niveau du fichier : toute modification du même fichier déclenche donc une nouvelle vérification. Une page d’article ouverte vérifie régulièrement ses références.

Choisissez « Vérifier le code et l’article » pour afficher le code actuel, puis « Confirmer la vérification » si l’article reste valable. Le serveur vérifie de nouveau que le fichier et l’article n’ont pas changé entre-temps et vous demande de recharger s’ils ont changé. La confirmation ne met à jour que la référence au code ; elle ne modifie pas le texte de l’article. Pour changer la conclusion, modifiez l’article comme d’habitude.

Lorsqu’un symbole est supprimé ou renommé, l’association n’est pas reportée sur un autre symbole portant le même nom. Utilisez « Supprimer l’association », puis associez le bon symbole. La suppression d’un article supprime ses associations ; la suppression d’un projet supprime ses enregistrements d’index et ses associations, mais pas les autres articles ni les fichiers d’index des répertoires de travail.

Requêtes depuis une session

Chaque session de terminal et d’agent démarrée par VelaTerm dispose de la commande vkb. Les autres agents capables d’exécuter des commandes de terminal peuvent aussi l’utiliser. Si une session existante ne trouve pas vkb après une mise à jour, redémarrez-la.

Lorsque les « Vela Skills » sont installées (Paramètres ▸ Général), Claude peut utiliser /vkb et Codex $vkb. La compétence ne s’exécute que lorsque vous la demandez explicitement ; les agents ne l’appellent pas d’eux-mêmes au cours d’un autre travail. Si un agent n’affiche pas la compétence après une mise à jour, cliquez sur « Reinstall » et redémarrez la session de cet agent.

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 renvoie le même résultat qu’Explorer le code.
callers, callees et impact acceptent une profondeur facultative ; leurs résultats comprennent relations, total, depth et truncated.
path prend deux identifiants de symbole exacts issus des résultats de recherche, et files peut filtrer par chemin.
search renvoie séparément les résultats de code (triés par pertinence, avec hasMore lorsqu’il y en a davantage), les articles de connaissance et les notes locales.
node renvoie la source, les relations et les articles associés d’un symbole.
memories et memory recherchent et lisent les articles de la base de connaissances des sessions, y compris leurs sources, leurs révisions et leurs références au code.
notes et note recherchent et lisent les bases de connaissances locales (voir Bases de connaissances locales).

Les requêtes sur le code utilisent l’index du répertoire dans lequel la commande s’exécute. Un sous-dossier utilise l’index de son projet, et un worktree distinct imbriqué n’emprunte jamais l’index de la copie de travail principale. Lorsqu’aucun index n’est activé ou qu’une requête échoue, le résultat indique que le code n’est pas disponible, et les requêtes sur les connaissances continuent de fonctionner. Ces commandes n’installent rien, n’activent pas l’indexation et ne modifient pas les articles.

Emplacement des données

Le moteur CodeGraph est installé dans codegraph/1.6.0/, dans le répertoire de données de l’application. Les tâches d’indexation et les associations aux articles sont stockées dans la base de données de l’application (tables knowledge_*). L’indexation s’exécute sur le serveur qui héberge le code ; les clients navigateur et les connexions SSH lisent les résultats par leur connexion existante, sans ouvrir de port supplémentaire. Chaque serveur conserve ses propres réglages d’index et sa propre base de connaissances.

La télémétrie, la recherche de mises à jour et le service d’arrière-plan distinct de CodeGraph sont désactivés. VelaTerm gère le processus de requête et communique avec lui par un canal privé d’entrée et de sortie standard, sans écouter sur un port. L’indexation elle-même n’utilise pas d’IA. Le code ou les articles qu’un agent lit avec vkb peuvent être envoyés au service de modèle configuré pour cet agent, de la même manière que lorsque l’agent lit des fichiers source.

Les événements du graphe du code sont écrits dans logs/runtime-*.log, dans le répertoire de données de l’application. Lorsque VLX_LOG_DIR n’est pas défini, VLX_KNOWLEDGE_LOG_DIR définit leur répertoire. VLX_KNOWLEDGE_LOG_LEVEL les filtre (par exemple error ou off). Le journal ne contient ni code source, ni texte de requête, ni texte d’article, ni identifiants de connexion.

CodeGraph est développé sur github.com/colbymchenry/codegraph et publié sous licence MIT.