Bases de connaissances locales

Une base de connaissances locale est un dossier ordinaire de fichiers Markdown que vous rédigez et organisez dans VelaTerm. Les notes et les pièces jointes restent dans ce dossier ; vous pouvez donc continuer à les modifier avec d’autres éditeurs. Certains éléments de menu appellent une base de connaissances locale un « carnet » ; les deux termes désignent le même dossier.

La « Base de connaissances des sessions » intégrée figure à côté de vos bases de connaissances locales. Elle contient les connaissances que les agents organisent à partir de vos sessions et conserve ses propres articles, sources et historique des révisions ; voir Base de connaissances des sessions.

Ouverture de la base de connaissances

Cliquez sur l’icône de connaissances dans le panneau de droite (info-bulle « Base de connaissances »). Un onglet « Base de connaissances » s’ouvre au centre et affiche la page d’accueil :

un champ de recherche (« Rechercher dans les connaissances des sessions et les notes locales… », voir la section Recherche ci-dessous) ;
la « Base de connaissances des sessions » ;
vos « Bases de connaissances locales » ;
les boutons « Ouvrir une base de connaissances » et « Créer une base de connaissances ».

Le panneau de droite affiche une arborescence à trois racines : « Base de connaissances des sessions », « Sessions archivées » et « Bases de connaissances locales ». Cliquez sur une flèche pour déplier un dossier sur place ; plusieurs bases de connaissances peuvent être dépliées en même temps. Cliquez sur le nom d’un dossier pour afficher son contenu, et sur une note pour l’ouvrir. Le lien « Bases de connaissances » en haut de l’arborescence ramène à la page d’accueil, et le bouton « Remonter d’un niveau » de l’en-tête d’une page affiche la page parente sans quitter la base de connaissances.

Les notes s’ouvrent dans des onglets de document ordinaires, avec les mêmes fonctions de modification, d’enregistrement, de recherche et d’export PDF que tout autre fichier Markdown (voir Onglets de documents et de navigateur). L’onglet « Base de connaissances » reste dans la barre d’onglets pour que vous puissiez revenir à l’endroit où vous étiez.

Ouverture ou création d’une base de connaissances locale

Ouvrir : cliquez sur « Ouvrir une base de connaissances » et choisissez un dossier. L’application de bureau affiche le sélecteur de dossiers du système ; un client navigateur affiche un explorateur des dossiers de l’ordinateur connecté. Un coffre Obsidian existant peut être ouvert directement : les fichiers restent à leur emplacement, et les dossiers masqués tels que .obsidian ne sont ni indexés ni modifiés.
Créer : cliquez sur « Créer une base de connaissances », saisissez un « Nom », choisissez un « Dossier » (ou « Parcourir » ; l’emplacement proposé est ~/Notes), puis confirmez. VelaTerm crée le dossier et l’ouvre. Le dossier parent doit exister, et aucun dossier du même nom ne doit s’y trouver ; sinon, VelaTerm affiche « La destination existe déjà. Choisissez un autre nom ou dossier. » Pour utiliser un dossier existant, choisissez plutôt « Ouvrir une base de connaissances ».
Renommer : cliquez avec le bouton droit sur une base de connaissances dans l’arborescence et choisissez « Renommer ». Le dossier est alors renommé sur le disque.
Fermer : cliquez sur « Fermer le carnet » dans la barre d’outils de la base de connaissances, ou cliquez avec le bouton droit sur celle-ci dans l’arborescence. La fermeture retire le dossier de la liste ; ses fichiers restent sur le disque. Lorsque vous rouvrez le même dossier, sa corbeille et son historique des importations sont toujours présents.

Le terme « locale » désigne l’ordinateur qui exécute le serveur VelaTerm auquel vous êtes connecté. Dans un client navigateur, « Ouvrir une base de connaissances » parcourt les dossiers de cet ordinateur, et l’importation envoie vers cet ordinateur les fichiers que vous choisissez dans le navigateur.

Importation de fichiers et de dossiers

Ouvrez la base de connaissances cible et cliquez sur « Importer » dans sa barre d’outils.
Choisissez le « Dossier » de destination, puis « Choisir des fichiers » ou « Choisir un dossier », ou faites glisser des fichiers et des dossiers dans la zone d’importation.
Vérifiez la liste et confirmez.

L’importation s’exécute en arrière-plan ; vous pouvez donc changer de page ou ouvrir des notes pendant la copie. Sa progression apparaît dans la barre d’outils de la base de connaissances et sur la page d’accueil, et elle peut être annulée depuis la boîte de dialogue d’importation ou depuis « Historique des importations ». À la fin, un bandeau indique le nombre de fichiers importés et ignorés ; si la fenêtre n’est pas au premier plan, une notification système (« Importation terminée » ou « Échec de l’importation ») s’affiche. Une seule importation peut s’exécuter à la fois dans une base de connaissances.

Une importation copie les fichiers tels quels, y compris les noms de fichiers non ASCII, l’arborescence relative des dossiers et les pièces jointes, et ne modifie jamais les originaux. L’importation d’un dossier inclut le dossier lui-même. Si un seul fichier devait en écraser un autre, l’ensemble du lot est refusé. Les fichiers masqués et les dossiers de configuration masqués sont ignorés. Les sélecteurs de fichiers des navigateurs ne transmettent pas les dossiers vides ; ceux-ci ne sont donc pas importés.

Une importation peut contenir jusqu’à 5 000 fichiers (les fichiers masqués ignorés sont comptés dans cette limite) et jusqu’à 1 Gio au total, avec au plus 100 Mio par fichier. Les fichiers sont d’abord placés dans une zone de transit et n’apparaissent dans la destination qu’une fois le lot complet reçu ; un envoi interrompu n’apparaît donc jamais sous la forme d’une note à moitié écrite.

« Historique des importations » répertorie chaque importation avec son heure, sa destination (« Racine de la base de connaissances » pour le dossier de premier niveau), son état (« Importation en cours », « Terminée », « Échouée », « Annulée » ou « Interrompue »), le nombre de fichiers importés et ignorés, la taille et la durée. Cliquez sur « Fichiers (N) » pour afficher chaque fichier et la raison pour laquelle il a été ignoré. « Supprimer l’entrée » retire l’entrée de l’historique ; les fichiers importés ne sont pas supprimés. Une importation dont la progression est arrêtée depuis plus de deux minutes, par exemple parce que l’application s’est fermée de manière inattendue, est marquée « Interrompue » ; la suppression de son entrée supprime aussi les fichiers placés en transit pour elle.

Rédaction et organisation des notes

Une page de base de connaissances propose les vues « Notes récentes », « Corbeille » et « Historique des importations », un bouton « Nouvelle note » et, dans la barre d’outils, les boutons « Nouveau dossier », « Importer » et « Fermer le carnet ». La liste des notes peut être filtrée par étiquette (« Toutes les étiquettes ») et triée par « Mise à jour récente » ou « Titre ».

Lorsqu’une page de base de connaissances est affichée, ⌘N / Ctrl+N crée une « Nouvelle note », ⌘O / Ctrl+O ouvre « Ouverture rapide » (recherche d’une note par son chemin), et ⌘⇧F / Ctrl+Maj+F place le curseur dans le champ « Rechercher des notes… ».
Pour renommer une note, cliquez dessus avec le bouton droit dans l’arborescence et choisissez « Renommer ». Pour la déplacer, faites-la glisser sur un autre dossier de la même base de connaissances. « Supprimer » la place dans la corbeille de la base de connaissances.
Lorsqu’un dossier est ouvert, « Renommer ou déplacer » déplace le dossier vers un chemin relatif à la racine de la base de connaissances ; le dossier parent doit déjà exister. Lorsqu’une note ou un dossier est déplacé, les liens des autres notes de la même base de connaissances sont mis à jour : le texte des liens est conservé et le code n’est pas modifié.
Les éléments supprimés sont placés dans un dossier .vkb-trash à l’intérieur de la base de connaissances. Ouvrez « Corbeille » et cliquez sur « Restaurer » pour récupérer un élément ; un fichier existant portant le même nom n’est jamais écrasé.
Les étiquettes proviennent des #tag présents dans le texte et d’une liste ou d’un tableau YAML tags.
Les images collées dans une note sont enregistrées dans un dossier assets situé à côté de la note.

L’arborescence et les listes s’actualisent environ toutes les cinq secondes tant que la page est visible, ainsi que lorsque la fenêtre redevient active. Un onglet de document ouvert détecte les modifications effectuées par d’autres programmes et propose de recharger le fichier.

Les pages de base de connaissances, les boîtes de dialogue, l’historique des importations, les recherches, la portée de recherche, les étiquettes, le tri et l’ouverture rapide disposent tous de leur propre URL ; vous pouvez donc actualiser la page ou utiliser les boutons Précédent et Suivant du navigateur. Le texte non enregistré et les saisies de formulaire ne font pas partie de l’URL.

Recherche

Page d’accueil : recherche en une seule fois dans la base de connaissances des sessions et dans toutes les bases de connaissances locales, et regroupe les résultats par source. Les sessions archivées ne sont pas incluses.
Panneau de droite : le champ « Rechercher des notes… » situé au-dessus de l’arborescence porte sur toutes les bases de connaissances locales.
Page d’une base de connaissances : « Rechercher des notes… » porte sur les noms, les chemins et le texte des notes. « Portée de la recherche » permet de choisir entre « Cette base de connaissances » et « Toutes les bases de connaissances ».

Lorsque vous saisissez plusieurs mots, tous doivent correspondre. Chaque résultat indique sa base de connaissances ou son groupe de sessions, un extrait, le numéro de ligne, le nombre de correspondances et les « Notes liées » vers lesquelles pointe la note ; cliquez sur l’un de ces éléments pour l’ouvrir. Utilisez Haut et Bas pour sélectionner un résultat, Entrée pour l’ouvrir et Échap pour effacer la recherche. Les résultats sont classés d’abord selon les correspondances dans le nom ou le chemin, puis selon le nombre de correspondances, puis selon la date de mise à jour la plus récente. Jusqu’à 100 résultats sont affichés ; s’il y en a davantage, la liste se termine par « Seuls les premiers résultats sont listés. Affinez la recherche pour voir les suivants. »

VelaTerm recherche d’abord des correspondances exactes et ne se rabat sur des correspondances approximatives qu’en l’absence de correspondance exacte ; il affiche alors « Aucune correspondance exacte. Voici des résultats approximatifs. » La correspondance approximative s’applique aux mots composés de lettres latines et de chiffres : lettres dans l’ordre (knwl trouve knowledge), initiales (kb trouve knowledge base) et petites fautes de frappe (une erreur dans les mots de quatre caractères ou plus, deux dans les mots de huit caractères ou plus ; knoledge trouve knowledge). Pour le chinois et les autres écritures non latines, seules les correspondances exactes sont prises en compte.

Liens et compatibilité avec les fichiers existants

VelaTerm reconnaît les formes courantes [[note]], [[folder/note|label]] et [[note#heading]], les liens Markdown relatifs standard et ![[image.png]]. Il les utilise pour mettre à jour les liens lors du déplacement de notes, pour afficher les « Notes liées » dans les résultats de recherche et pour les commandes vkb décrites ci-dessous. Dans l’éditeur, les liens [[…]] s’affichent sous forme de texte brut. Lorsque plusieurs fichiers portent le même nom, un lien court n’est résolu que si la cible est unique ; sinon, indiquez le chemin du dossier.

Les fichiers restent au format Markdown brut, et l’en-tête YAML (front matter) reste dans le fichier ; le mode « Code source » de l’éditeur l’affiche tel quel. Les fichiers Markdown qui ne sont pas encodés en UTF-8 ou qui dépassent 5 Mio ne sont pas répertoriés comme notes et sont comptés parmi les « Ignorés ». Une base de connaissances peut contenir jusqu’à 50 000 fichiers et dossiers ; un dossier plus volumineux ne peut pas être ouvert et affiche « Le fichier ou la sélection dépasse les limites du carnet. » Les liens symboliques ne sont pas suivis.

Ces fonctions couvrent le travail quotidien avec des fichiers, des dossiers, du Markdown, des liens et la recherche en local. Les modules complémentaires, les thèmes, Canvas, les références de blocs, les notes intégrées et les alias YAML d’Obsidian ne sont pas pris en charge ; les fichiers correspondants restent inchangés. Pour le modèle de fichiers et la syntaxe des liens, consultez la documentation d’Obsidian sur les coffres, les liens internes et les pièces jointes.

Copie depuis la base de connaissances des sessions et requêtes des agents

Ouvrez un article de la base de connaissances des sessions, choisissez « Copier dans un carnet local », puis sélectionnez la base de connaissances cible et le nom du fichier. La copie est une note Markdown indépendante ; l’article d’origine, ses instantanés source et son historique des révisions restent en place.

Dans une session VelaTerm, vous-même ou un agent pouvez lire les bases de connaissances locales enregistrées avec vkb :

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

notes recherche dans toutes les bases de connaissances locales enregistrées sur le serveur actuel. Chaque résultat comprend vaultId, vaultName, path, absolutePath, line, matches, score, matched (le texte qui a effectivement correspondu), related (les notes vers lesquelles pointe cette note) et summary (le texte autour de la correspondance). La réponse indique aussi total, hasMore, unavailable (les bases de connaissances qui n’ont pas pu être lues) et fuzzy (si les résultats sont approximatifs). Jusqu’à 100 résultats sont renvoyés.
note renvoie le texte, le plan, les liens, les rétroliens et les étiquettes d’une note.
search renvoie les correspondances issues de la base de connaissances des sessions, des notes locales et, lorsqu’un index du code existe, du graphe du code (voir Graphe du code et base de connaissances).

Ces commandes fonctionnent en lecture seule. Elles ne modifient jamais les notes, et VelaTerm n’ajoute pas automatiquement le contenu des bases de connaissances aux sessions.

Stockage et journaux

Les fichiers sur le disque constituent la copie de référence de vos notes et pièces jointes. La base de données de l’application (tables kb_*) ne stocke que la liste des bases de connaissances enregistrées, les enregistrements de la corbeille, l’historique des importations et un cache de recherche qui peut être reconstruit. La base de connaissances des sessions utilise ses propres tables memory_*.

L’ouverture, l’écriture, le déplacement, la suppression, la restauration et l’importation sont consignés dans le journal d’exécution avec un identifiant d’opération, des compteurs et la durée, jamais avec le contenu des notes. Ces lignes utilisent l’événement knowledge ; lorsque VLX_LOG_DIR n’est pas défini, VLX_KNOWLEDGE_LOG_DIR définit leur répertoire. L’historique des importations est stocké dans la base de données et affiché sur la page « Historique des importations ». Pour sauvegarder complètement une base de connaissances, conservez à la fois son dossier et les données de l’application, qui contiennent sa corbeille et ses enregistrements d’importation.