Créer une CLI locale qui cherche vos documents par mot-clé et par sens

## Utilisez un seul environnement d’exécution et donnez à chaque groupe de commandes un rôle clair Choisissez un environnement d’exécution pris en charge et un gestionnaire de paquets comme voie de développement canonique. Ne mélangez pas des environnements d’exécution de substitution ou des commandes d’installation simplement parce qu’ils semblent compatibles. Explicitez les responsabilités des commandes : - les commandes de collection gèrent les racines indexées et leur configuration ; - les commandes de contexte associent des consignes de recherche aux chemins ; - les commandes de récupération renvoient des documents connus ; - les commandes de recherche classent les documents candidats ; - les commandes de maintenance inspectent ou actualisent l’index ; - les commandes de service exposent les mêmes capacités à d’autres processus. Préservez le script de lancement de la commande installé lorsqu’il délègue l’exécution au code compilé de l’application. Compilez le code source avec le flux de compilation documenté ; ne remplacez pas ce script par un exécutable compilé unique lorsque des extensions natives dépendent de la structure existante. ## Enregistrez les réglages de chaque collection et distinguez l’exclusion du retrait Représentez chaque collection par un nom unique, une racine source, un masque de fichiers, un état d’inclusion et un hook facultatif préalable à la mise à jour. Prenez en charge les opérations d’ajout, de listage, d’inspection, de renommage, d’inclusion, d’exclusion et de retrait des collections. Distinguez le retrait de l’exclusion : le retrait supprime l’enregistrement de la collection, tandis que l’exclusion se contente de l’omettre des requêtes sans portée définie. Permettez de lister les fichiers d’une collection entière ou d’un préfixe de chemin. Acceptez aussi bien les chemins simples de collection que l’URI virtuelle de collection de l’outil lorsque l’interface le permet. Traitez l’ajout, le retrait, le renommage, les changements de hooks, les changements d’inclusion et les actualisations de l’index comme des modifications d’état. Lorsqu’une approbation de l’utilisateur est requise, présentez la commande exacte et l’effet attendu avant l’exécution. ## Associez des notes de recherche (contexte) aux chemins, séparées du texte des documents Stockez le contexte rédigé manuellement séparément du contenu des documents afin que les consignes de classement puissent évoluer sans réécrire les fichiers sources. Autorisez le contexte pour : - le répertoire courant détecté dans une collection ; - un sous-chemin précis ; - un chemin virtuel de collection ; - la racine globale, pour les consignes qui s’appliquent à toutes les collections. Fournissez des commandes pour lister le contexte, détecter les chemins dépourvus de contexte et retirer le contexte obsolète. Appliquez le contexte pertinent le plus précis tout en conservant les consignes globales. Ne confondez pas les métadonnées contextuelles avec le texte indexé des documents. Rendez la portée visible afin qu’une note locale ne puisse pas influencer silencieusement des collections sans rapport. ## Donnez à chaque document un identifiant court et limitez ce qui est renvoyé Attribuez à chaque document un identifiant court dérivé des 6 premiers caractères du hachage de son contenu. Affichez cet identifiant dans les résultats de recherche et acceptez-le avec ou sans le marqueur initial. Prenez en charge la récupération par chemin ou identifiant, avec une ligne de départ et un nombre de lignes facultatifs, ainsi que la récupération par lots à partir d’un motif glob ou d’une liste séparée par des virgules. Bornez explicitement la récupération : - définissez un nombre maximal de lignes par fichier ; - définissez une taille maximale en octets et documentez la valeur par défaut, par exemple 10 KB ; - ignorez les fichiers trop volumineux au lieu de renvoyer un contenu partiel sans avertissement ; - incluez les numéros de ligne par défaut et permettez aux appelants de les désactiver ; - ne renvoyez les chemins complets sur le disque que sur demande. ## Choisissez le type de recherche selon la requête, avec la recherche hybride par défaut Exposez trois voies de recherche distinctes : - la recherche par mots-clés utilisant un classement en texte intégral tel que BM25, sans modèle de langage ; - la recherche par similarité vectorielle utilisant des embeddings locaux, sans reclassement ; - la recherche hybride étendue avec expansion de requête et reclassement comme option par défaut offrant la meilleure qualité. Utilisez la fusion par rang réciproque pour combiner des ensembles de résultats classés indépendamment. Gardez les scores d’origine et le mode suffisamment visibles pour diagnostiquer un ordre inattendu. Préférez la voie de requête hybride pour un usage général. Choisissez la recherche par mots-clés lorsque les termes exacts sont importants, la recherche vectorielle lorsque la similarité sémantique est l’objectif, et une option sans reclassement lorsque la vitesse compte davantage que la qualité de l’ordre final. ## Permettez de choisir les collections et les formats de sortie sans changer les résultats Permettez aux appelants de répéter les filtres de collection afin de rechercher dans plusieurs collections nommées tout en excluant toutes les autres. Prenez en charge le réglage du nombre de résultats, un mode incluant tous les résultats, un score minimal, un mode de contenu intégral et une description de l’intention qui affine le classement. Séparez l’affichage du transport des données. Fournissez un format lisible en ligne de commande ainsi que des sorties structurées en JSON, CSV, Markdown, XML et liste de fichiers. Ne conservez les anciennes options de format que comme alias d’une seule option de format canonique. Pour la récupération par lots, exposez les limites de lignes, les limites en octets et les contrôles des numéros de ligne indépendamment du classement de la recherche. Ne laissez pas une option de présentation modifier les documents sélectionnés. ## Créez l’index de recherche et découpez les documents en segments prévisibles Utilisez une base de données locale durable pour l’indexation en texte intégral et une extension vectorielle compatible pour la similarité sémantique. Exécutez les embeddings, le reclassement et l’expansion de requêtes au moyen de modèles locaux configurés. Utilisez une segmentation intelligente des documents avec un objectif de 900 tokens par segment et un chevauchement de 15%. Privilégiez les titres Markdown comme limites lorsque c’est possible. Fournissez une stratégie tenant compte de l’arbre syntaxique abstrait pour les fichiers de code pris en charge, afin que les segments s’alignent sur les fonctions, les classes et les importations. Sélectionnez-la au moyen d’une stratégie automatique explicite. Conservez la segmentation par expressions régulières comme comportement par défaut et appliquez-la de manière cohérente à Markdown et aux types de fichiers inconnus. Maintenez l’indexation, la génération des embeddings et le classement au moment de la requête comme des étapes séparées, afin de pouvoir diagnostiquer les échecs sans tout reconstruire. ## Vérifiez l’état de l’index et des modèles avant d’ajuster le classement Fournissez une sortie d’état qui indique l’intégrité des collections et de l’index sans modifier l’état. Ajoutez une commande de diagnostic pour les problèmes de configuration, d’index, de modèle et de périphérique. Évaluez la qualité de la recherche avec des fichiers de test de référence versionnés. Consignez la requête, les documents pertinents attendus, le mode, les métriques de classement, la configuration du modèle et la version de l’index afin que les comparaisons restent reproductibles. Utilisez les diagnostics avant de modifier les pondérations de classement, les modèles ou les paramètres du périphérique. Un modèle absent, un index obsolète, une extension vectorielle incompatible ou un périphérique indisponible ne prouve pas que l’algorithme de classement lui-même est incorrect. ## Lancez l’outil comme service local ou HTTP seulement sur demande Proposez un service sur entrée et sortie standard pour l’intégration aux processus locaux, ainsi qu’un service HTTP facultatif pour les clients distants. Utilisez un port par défaut documenté, tel que 8181, tout en permettant un remplacement explicite. Prenez en charge l’exécution au premier plan pour le débogage et un mode daemon en arrière-plan pour un usage prolongé. Fournissez une commande d’arrêt correspondante qui ne cible que le daemon géré. Séparez le transport du service de la sémantique de la recherche. L’interface de ligne de commande et l’interface de service doivent partager les règles de collection, de contexte, de récupération, de classement et de sortie. Ne démarrez pas implicitement un service en arrière-plan. Lorsqu’un service est lancé, indiquez le point de terminaison, le mode du processus, la source de la configuration et la méthode d’arrêt. ## Laissez à l’utilisateur les modifications de l’index et n’abîmez pas le script de lancement installé N’ajoutez jamais automatiquement une collection, ne générez jamais automatiquement d’embeddings et n’actualisez jamais automatiquement les index. Ne modifiez jamais directement la base de données de recherche sous-jacente. Lorsqu’un flux de travail demandé nécessite l’une de ces modifications, affichez la commande exacte que l’utilisateur doit exécuter et expliquez les fichiers attendus, la durée et l’utilisation des ressources. Maintenez la recherche et la récupération en lecture seule disponibles sans élargir les autorisations. N’exécutez pas un mode de compilation qui écrase le script de lancement shell installé ou endommage les extensions vectorielles natives. Ne remplacez pas un script de lancement qui exécute intentionnellement du JavaScript compilé depuis un répertoire de distribution. Traitez les hooks préalables à la mise à jour comme une configuration exécutable. Affichez-les lors de l’inspection et ne les exécutez que dans le cadre d’une mise à jour de l’index explicitement demandée. ## Ajoutez des tests de régression et publiez avec un journal des modifications Conservez les tests automatisés dans l’arborescence de tests prévue et exécutez les suites complètes documentées avec l’environnement d’exécution pris en charge. Ajoutez des tests de régression ciblés pour l’état des collections, les limites de récupération, les modes de classement, les limites des segments et le cycle de vie du service. Utilisez le flux canonique de mise en version au lieu de préparer manuellement une version : 1. ajoutez les entrées du journal des modifications dans la section des éléments non publiés au fur et à mesure que les changements sont effectués ; 2. convertissez cette section en une version datée lors de la mise en version ; 3. créditez les contributions externes en utilisant le format de référence exigé par le projet ; 4. agrégez les notes de version pour la série de versions visée ; 5. exécutez les hooks de mise en version et la vérification avant de publier. Indiquez le comportement modifié, la compatibilité de l’index ou du schéma, les tests exécutés, l’impact sur les benchmarks, les besoins de migration et toute commande modifiant l’état qu’il reste à l’utilisateur à exécuter.