Recherche dans la base de connaissances locale Skill (kb-retriever)

Description du répertoire de la base de connaissances

• La base de connaissances est stockée dans un répertoire racine et contient divers types de fichiers (tels que .md/.txt、.pdf、.xlsx etc.), généralement répartis en sous-répertoires à plusieurs niveaux selon leur type ou leur utilisation opérationnelle.
• Les fichiers sont indexés selon une structure de répertoires hiérarchique :
  • Le répertoire racine contient un fichier data_structure.mdfichier décrivant les principaux « répertoires thématiques » et leur utilité.
  • Chaque répertoire de domaine peut disposer de son propre data_structure.md, décrivant les sous-répertoires et fichiers qu’il contient, ainsi que leur utilisation respective.
  • Les sous-répertoires situés à un niveau plus profond peuvent également comporter data_structure.md, formant ainsi une arborescence d’index à plusieurs niveaux.
• Convention relative au répertoire racine de la base de connaissances :
  • par défaut, la base de connaissances est située dans le répertoire knowledge/ .
  • Si l’utilisateur a explicitement spécifié un autre chemin d’accès dans la conversation (par exemple « Ma base de connaissances se trouve dans /data/kb » ou « Utilisez le répertoire ./docs comme base de connaissances »), le chemin d’accès spécifié par l’utilisateur est alors considéré comme le répertoire racine.
  • Lorsque le chemin par défaut knowledge/ n’existe pas ou que l’accès échoue, il convient de demander confirmation à l’utilisateur quant à l’emplacement réel du répertoire racine de la base de connaissances, plutôt que de faire des suppositions arbitraires.
• Un fichier métier peut être très volumineux :
  • ne lisez pas directement le fichier entier avec la fonction Read
  • pour les fichiers PDF et Excel, utilisez les Skills correspondants afin de les structurer, puis combinez cette opération avec grep ou une lecture partielle pour effectuer une recherche précise

Localiser knowledge répertoire racine

• Répertoire racine : privilégier les indications de l’utilisateur. Si celui-ci fournit un chemin d’accès (par exemple ./docs、./knowledge-personal), utilisez directement le chemin fourni par l’utilisateur.
• Répertoire racine par défaut : dans le cas contraire, le répertoire racine est par convention défini comme étant knowledge/。
  • Vérifier explicitement l’existence du répertoire à l’aide du shell : privilégier l’utilisation de test -d knowledge, ou à défaut, utiliser ls -d knowledge。
  • Remarque : il est interdit d’utiliser Glob "knowledge" in . ce type de modèle pour déterminer si un répertoire existe,Glob car cela ne renvoie que le chemin d’accès au fichier, et non le répertoire lui-même ; un résultat vide ne permet pas de distinguer si le « répertoire n’existe pas » ou s’il « existe mais est vide ».
• Ce n’est qu’après avoir vérifié l’existence du répertoire racine à l’aide de test -d , n’utilisez Glob pour rechercher du contenu dans ce répertoire et ne traitez le répertoire que comme path, par exemple :
  • fichier d’index :pattern="**/data_structure.md", path="knowledge"
  • Tous les fichiers Markdown :pattern="**/*.md", path="knowledge"
• Si, par défaut, knowledge/ n'existe pas (test -d échec) : ne pas deviner d’autres répertoires, indiquer clairement à l’utilisateur que le répertoire racine par défaut est introuvable et lui demander de spécifier le chemin d’accès réel à la base de connaissances.

Principe clé : apprendre d’abord, traiter ensuite

Liste de contrôle obligatoire en cas de fichiers PDF ou Excel :

• ✅ Avoir lu le document de référence correspondant pour apprendre la méthode de traitement
• ✅ Les outils et commandes recommandés ont été compris
• ✅ Le traitement du fichier (extraction/conversion) est terminé
• ⏭️ Vous pouvez désormais commencer la recherche

Comportements interdits :

• ❌ Tenter de traiter un fichier PDF sans avoir lu au préalable le fichier pdf_reading.md
• ❌ Tenter de traiter directement un fichier Excel sans avoir lu le fichier excel_reading.md
• ❌ Sauter les étapes de traitement des fichiers et effectuer directement la recherche sur les fichiers PDF/Excel d'origine

Processus global

1. Comprendre les besoins de l’utilisateur

   • Lire la question de l’utilisateur et en extraire :
     • les mots-clés relatifs au thème ou au domaine (par exemple « rapports de ventes », « architecture système », « documentation d’interface »)
     • Les contraintes temporelles ou de portée (par exemple « 1er trimestre 2023 », « dernière version »)
     • Type de résultat souhaité (explication, résumé, valeurs spécifiques de champs, etc.)
   • Déterminer le répertoire racine de la base de connaissances :
     • Vérifier en priorité si l’utilisateur a spécifié un chemin d’accès à la base de connaissances dans sa question.
     • Sinon, utiliser le répertoire racine par défaut knowledge/。
     • Si le répertoire racine par défaut n’existe pas ou si la structure du répertoire est anormale, il convient de demander confirmation à l’utilisateur plutôt que de formuler des hypothèses de son propre chef.

2. Parcourir l’index des répertoires de manière hiérarchique data_structure.md

   • Utiliser le concept de « répertoire de travail actuel » :
     • par défaut, à partir du répertoire racine de la base de connaissances spécifié par l’utilisateur ; si l’utilisateur n’en a pas spécifié, utilisez le répertoire courant.
   • Dans le répertoire de travail actuel, si le fichier data_structure.md：
     • Lire les premières lignes du fichier à l’aide de la commande « Read » (par exemple, limit=300) ; si nécessaire, poursuivre la lecture par segments.
     • Objectif :
       • Identifier les sous-répertoires et fichiers présents dans le répertoire courant
       • Comprendre la description de l’utilisation de chaque sous-répertoire/fichier
     • En fonction de la requête de l’utilisateur, sélectionner les sous-répertoires ou fichiers les plus pertinents afin de constituer un ensemble de candidats.
   • Pour chaque sous-répertoire candidat :
     • pénétrer de manière récursive dans ce sous-répertoire, en le considérant comme le nouveau « répertoire de travail actuel », et poursuivre la recherche à l’intérieur de celui-ci data_structure.md et répéter le processus décrit ci-dessus.
     • Au cours de ce processus récursif, éviter d’explorer toutes les branches en même temps ; privilégier l’exploration des chemins les plus pertinents par rapport au problème.
   • Pour les fichiers métier candidats (md/texte, PDF, Excel, etc.) :
     • Une fois l’exploration nécessaire de la structure des répertoires terminée, regroupez ces fichiers pour constituer la liste finale des cibles de recherche.
   • Lors du classement par ordre de priorité :
     • privilégiez les répertoires et fichiers dont la description d’utilisation correspond étroitement au sujet du problème
     • Prenez ensuite en compte les contraintes telles que la date ou la version (si elles sont présentes dans l’index)
     • Les documents de nature générale (tels que README.md ou les documents de conception globale) sont classés à une priorité moindre

3. Apprendre les méthodes de traitement des fichiers (à appliquer systématiquement en cas de fichiers PDF ou Excel)

   • Avant de traiter un fichier PDF :
     • Il faut d’abord lire le fichier references/pdf_reading.md (attention : ce répertoire se trouve dans le répertoire « Skills », et non dans le répertoire « Knowledge ») Apprendre les méthodes d’extraction
     • Points clés à maîtriser : la commande pdftotext, l’utilisation de pdfplumber, les méthodes d’extraction des tableaux
   • Avant de traiter des fichiers Excel :
     • Il faut d’abord lire le fichier references/excel_reading.md pour apprendre les méthodes de lecture
     • Il est indispensable de lire au préalable le fichier references/excel_analysis.md pour apprendre les méthodes d’analyse
     • Points clés à retenir : lecture avec pandas, filtrage des colonnes, filtrage des données
   • Objectif : s'assurer d'utiliser les bons outils et les bonnes méthodes, afin d'éviter toute recherche aveugle

4. Effectuer le traitement et l’extraction en fonction du type de fichier

   • Traiter les fichiers à l’aide des méthodes que vous venez d’apprendre (extraction, conversion, structuration)
   • Pour chaque catégorie de fichiers candidats, appliquez les stratégies suivantes : « Markdown/texte », « PDF » et « Excel »
   • Principe général :
     • Commencer en priorité par les fichiers les plus pertinents et les plus précis
     • Effectuer une recherche locale progressive au sein de chaque fichier, en évitant de charger l’intégralité du contenu en une seule fois
     • Si le fichier actuel ne fournit pas d’informations satisfaisantes, passer au fichier candidat suivant

5. Recherche itérative

   • Utiliser un « mécanisme de recherche itérative en plusieurs étapes » uniforme pour tous les types de documents (voir les principes généraux de recherche ci-dessus)

6. Organisation et traçabilité des réponses

   • Synthétiser le contexte issu des recherches itératives pour apporter une réponse globale à la question de l’utilisateur.
   • Dans la mesure du possible :
     • de fournir des réponses claires et directes
     • Indiquer les noms des documents utilisés (en précisant, si nécessaire, leur emplacement approximatif, par exemple le chapitre ou le nombre approximatif de lignes/pages)
   • Si la réponse repose sur des déductions ou des informations incomplètes :
     • indiquer clairement les hypothèses et les incertitudes
     • Indiquez à l’utilisateur qu’il peut préciser davantage la portée du document ou ajouter des mots-clés

Principes de recherche publique

Stratégie de sélection des mots-clés

• Extraire 3 à 8 mots-clés de la requête de l'utilisateur (y compris les éventuelles abréviations en anglais, les synonymes, les termes génériques et spécifiques)
• Expressions combinables (par exemple « rapports de ventes », « délai d'expiration de l'API »)
• Inclure, si nécessaire, des termes métier, des termes techniques et des abréviations courantes (par exemple « uv », « pv », « GMV »)

Principes de base de la recherche avec grep

• Spécifier toujours des paramètres « include » et « path » aussi précis que possible, afin d’éviter de parcourir l’intégralité du répertoire
• Pour le `pattern`, privilégier d’abord les noms et termes clés présents dans la question, puis essayer les synonymes
• Pour chaque résultat, ne lire que la zone locale proche de la correspondance (quelques lignes en amont et en aval)
• Enregistrer « nom de fichier + informations de position + extrait de texte »

Mécanisme de recherche itératif (5 itérations au maximum)

Une stratégie itérative uniforme est appliquée à tous les types de fichiers :

1. Contrôle des itérations
   • Tenir à jour le compteur du « nombre de tentatives de recherche », avec un maximum de 5
   • Le compteur est incrémenté après chaque recherche
2. Déroulement de chaque cycle d’itération
   1. Génération/mise à jour des mots-clés de recherche en fonction du problème (pouvant inclure des synonymes et des mots dérivés)
   2. Sélectionner les fichiers ou parties de fichiers qui n’ont pas encore été suffisamment explorés
   3. Effectuer la recherche (grep / lecture locale / appel d’une Skill dédiée)
   4. Analyse des extraits de contexte obtenus
   5. Déterminer si les informations sont suffisantes pour répondre à la question
3. Conditions de sortie
   • Contexte suffisant pour étayer la réponse ; ou
   • 5 tentatives ont été effectuées sans trouver d’informations pertinentes
4. Traitement en cas d’informations insuffisantes
   • Informer clairement l’utilisateur que l’information fait défaut ou qu’elle n’est peut-être pas présente dans la base de connaissances actuelle
   • Fournir l’information la plus proche trouvée, en précisant le degré d’incertitude
   • Indiquer à l’utilisateur comment affiner sa recherche (nom de fichier plus précis, mots-clés, période, etc.)

Points à retenir

• Il est interdit d’appeler directement dès la première tentative :Glob "knowledge" in . ou tout appel visant à vérifier l’existence d’un répertoire à l’aide de Glob ; l’existence d’un répertoire doit être vérifiée via une commande shell (par exemple test -d).
• Lors de l’utilisation de cette Skill pour interroger la base de connaissances, il est interdit d’utiliser d’autres outils, tels que les moteurs de recherche sur Internet, pour obtenir des informations

Stratégies spécifiques pour différents types de fichiers

1. Fichiers Markdown / fichiers texte ( .md, .txt, .log, etc.)

1. Sélection des fichiers candidats

   • En fonction data_structure.md du nom et du chemin d’accès du fichier
   • Priorité accordée aux fichiers de type titre et table des matières (tels que les documents récapitulatifs, les aperçus de conception)

2. Localisation et lecture partielle avec grep

   • Utilisation de l’outil grep sur les fichiers candidats spécifiés, avec l’opérateur « include » pour limiter la recherche à des extensions spécifiques (par exemple « *.md »)
   • Pour les fichiers contenant des correspondances, utiliser « Read » pour ne lire que la zone locale proche de la correspondance :
     • Contrôler la lecture à l’aide d’un décalage de ligne et de l’option `limit` (par exemple, lire quelques dizaines de lignes en avant et en arrière de la ligne correspondant à la correspondance)
     • Éviter la lecture intégrale du fichier

3. Traitement particulier

   • Si le contenu se limite à une table des matières ou à des titres, poursuivre le positionnement vers le contenu détaillé en fonction des liens ou des noms de sous-sections
   • Appliquer le « mécanisme de recherche itératif en plusieurs étapes » (voir les principes généraux de recherche ci-dessus)

2. Stratégie de recherche dans les fichiers PDF

Flux de travail :

1. Tout d’abord : lire le guide des méthodes de traitement

   • Avant de traiter tout fichier PDF, il est indispensable de lire le fichier references/pdf_reading.md (notez que ce répertoire se trouve dans le répertoire « Skills » et non dans le répertoire « Knowledge »)
   • Points clés à retenir : la commande pdftotext, l’utilisation de pdfplumber, les méthodes d’extraction de tableaux, le tableau d’aide à la décision rapide

2. Sélection des fichiers PDF candidats

   • En fonction data_structure.md , sélectionnez 1 à 3 fichiers parmi les plus pertinents
   • Si l’utilisateur spécifie un fichier PDF en particulier, privilégiez ce fichier

3. Appliquer les méthodes apprises pour extraire le texte

   • Utilisez les outils recommandés dans le fichier pdf_reading.md (de préférence pdftotext ou pdfplumber)
   • Important : utilisez pdftotext input.pdf output.txt Extrayez le texte vers un fichier, ne l’affichez pas directement sur stdout (pour éviter de consommer trop de tokens)
   • Pour extraire des tableaux, utiliser la fonctionnalité d’extraction de tableaux de pdfplumber

4. Effectuez une recherche sur les résultats de l'extraction

   • Utilisez `grep` pour effectuer une recherche par mots-clés dans le texte extrait
   • Pour chaque occurrence, extraire le contexte autour de celle-ci (les dizaines de lignes au-dessus et en dessous ou les pages adjacentes)
   • Enregistrer « nom de fichier + numéro de page/emplacement approximatif + extrait de texte »
   • Appliquer le « mécanisme de recherche itérative en plusieurs étapes » (voir les principes généraux de recherche ci-dessus)

3. Stratégie de recherche dans les fichiers Excel

Flux de travail :

1. Tout d’abord : lire le guide des méthodes de traitement

   • Avant de traiter tout fichier Excel, il est indispensable de lire :
     • references/excel_reading.md – pour apprendre à lire les feuilles de calcul (attention : ce répertoire se trouve dans le répertoire « Skills », et non dans le répertoire « Knowledge »)
     • references/excel_analysis.md – pour apprendre à analyser les données (attention : ce fichier se trouve dans le répertoire « Skills » et non dans le répertoire « Knowledge »)
   • Points clés à maîtriser : méthodes de lecture avec pandas, filtrage des colonnes, filtrage des données, opérations d’agrégation

2. Sélection d’un fichier Excel candidat

   • En fonction data_structure.md et des noms des fichiers/feuilles de calcul, sélectionnez la feuille la plus pertinente
   • Privilégiez les classeurs/feuilles de calcul contenant des mots-clés tels que « rapport », « statistiques », « journal », « configuration » ou « mappage »
   • Si l’utilisateur précise un fichier Excel en particulier, privilégiez l’utilisation de ce fichier

3. Appliquer les méthodes apprises pour explorer la structure

   • Utiliser pandas pour lire les 10 à 50 premières lignes (en respectant les nrows )
   • Points clés à maîtriser : noms de colonnes/champs, types de données (nombres, dates, texte), champs clés
   • Comparer les noms de colonnes avec les questions de l’utilisateur afin d’identifier les champs clés potentiels (tels que « revenu », « chiffre d’affaires », « error_code », etc.)

4. Effectuer la recherche et l’analyse des données

   • Utiliser les méthodes pandas apprises pour filtrer et agréger les données (par exemple df[df['column'] == value]）
   • ne lire à chaque fois que les données proches des lignes correspondantes, afin d’éviter de lire l’intégralité du tableau en une seule fois
   • Si la question comporte une plage de dates, ajouter un filtre temporel à la requête
   • Appliquer le « mécanisme de recherche itérative en plusieurs étapes » (voir les principes généraux de recherche ci-dessus)

Interaction avec d’autres outils

Traitement des PDF

• Avant de traiter un PDF, il est indispensable de consulter le fichier references/pdf_reading.md pour prendre connaissance des méthodes de traitement
• Utiliser pdfplumber/pypdf pour l'extraction de texte, l'extraction de tableaux et la lecture des métadonnées
• Privilégier l’utilisation de l’outil en ligne de commande pdftotext pour une extraction rapide du texte

Traitement des fichiers Excel

• Avant de traiter des fichiers Excel, vous devez d'abord consulter :
  • references/excel_reading.md – pour découvrir les méthodes de lecture
  • references/excel_analysis.md - pour découvrir les méthodes d'analyse
• Utiliser pandas pour l'exploration, la prévisualisation, le filtrage et l'analyse des données

Principes d'utilisation des outils

• Grep : sert à rechercher, dans un fichier donné, les numéros de ligne et les extraits correspondant à un mot-clé ; veillez à toujours spécifier des paramètres « include » et « path » aussi précis que possible
• Read : à utiliser uniquement pour la lecture partielle de fichiers ; définissez toujours une limite raisonnable (par exemple, 200 à 500 lignes) et un décalage approprié
• Pour tout fichier susceptible d’être volumineux :
  • il est interdit de lire directement le fichier de bout en bout
  • Commencez toujours par affiner la recherche à l’aide d’index, de répertoires ou de mots-clés avant de procéder à la lecture

Style de réponse et gestion des erreurs

• Style de réponse
  • Répondez autant que possible dans la langue utilisée par l'utilisateur (chinois/anglais).
  • Commencez par présenter la conclusion, puis donnez brièvement les raisons qui la justifient.
  • Si nécessaire, vous pouvez indiquer à la fin les fichiers cités et leur emplacement approximatif, par exemple :
    • Source : design/api_gateway.md, vers la ligne 100
    • Source : reports/2023_Q1_sales.xlsx, feuille de calcul « Summary »
• En cas d’informations manquantes ou incertaines
  • Précisez clairement qu’aucune information correspondant exactement n’a été trouvée dans la base de connaissances actuelle ou que la réponse n’est que partielle.
  • Ne pas inventer de faits.
  • Indiquez à l’utilisateur comment il peut aider à affiner la recherche :
    • en indiquant un répertoire ou un fichier plus précis
    • fournir des mots-clés ou des noms de champs plus précis
    • Spécifier une période ou une version