Búsqueda en la base de conocimientos local (kb-retriever)

Descripción del directorio de la base de conocimientos

• La base de conocimientos se almacena en un directorio raíz y contiene diversos tipos de archivos (como .md/.txt、.pdf、.xlsx , etc.), y suele dividirse en subdirectorios de varios niveles según el tipo o la finalidad operativa.
• Se utiliza un sistema de directorios jerárquico para indexar los archivos:
  • En el directorio raíz hay un archivo data_structure.mdque describe los principales «directorios temáticos» y su finalidad.
  • Cada directorio de área puede tener su propio data_structure.md, que describe qué subdirectorios o archivos contiene dicho directorio, así como su finalidad respectiva.
  • Los subdirectorios de niveles inferiores también pueden contener data_structure.md, formando así un árbol de índices de varios niveles.
• Convención para el directorio raíz de la base de conocimientos:
  • Por defecto, se considera que la base de conocimientos se encuentra en el directorio knowledge/ .
  • Si el usuario especifica explícitamente otra ruta en el diálogo (por ejemplo, «Mi base de conocimientos está en /data/kb» o «Utilizar el directorio ./docs como base de conocimientos»), se utilizará la ruta especificada por el usuario como directorio raíz.
  • Cuando la ruta predeterminada knowledge/ no existe o no se puede acceder a ella, se debe confirmar con el usuario la ubicación real del directorio raíz de la base de conocimientos, en lugar de hacer conjeturas al azar.
• Un único archivo de negocio puede ser muy grande:
  • no leas el archivo completo directamente con Read
  • Para archivos PDF y Excel, utilice la Skill correspondiente para procesarlos de forma estructurada y, a continuación, combine el uso de grep o la lectura parcial para realizar búsquedas precisas

Localizar knowledge del directorio raíz

• En el directorio raíz, dar prioridad a la indicación del usuario: si el usuario proporciona una ruta (por ejemplo, ./docs、./knowledge-personal), utilice directamente la ruta proporcionada por el usuario.
• Directorio raíz por defecto: en caso contrario, se establece como directorio raíz el directorio knowledge/。
  • Comprobar explícitamente con el shell si el directorio existe: dar prioridad a test -d knowledge, o, en su defecto, utilizar ls -d knowledge。
  • Nota: Queda prohibido utilizar Glob "knowledge" in . este tipo de patrones para determinar si un directorio existe,Glob ya que solo devuelve la ruta del archivo, no el propio directorio; un resultado vacío no permite distinguir entre «el directorio no existe» y «el directorio existe pero está vacío».
• Solo cuando se haya comprobado que el directorio raíz existe mediante test -d , se utilizará Glob para buscar contenido en dicho directorio, y se utilizará el directorio como path, por ejemplo:
  • archivo de índice:pattern="**/data_structure.md", path="knowledge"
  • Todos los archivos Markdown:pattern="**/*.md", path="knowledge"
• Si por defecto knowledge/ no existe (test -d error): no especules sobre otros directorios, indica claramente al usuario que no se ha encontrado el directorio raíz predeterminado y pídele que especifique la ruta real de la base de conocimientos.

Principio clave: primero aprender, luego procesar

Lista de comprobación obligatoria al encontrarse con archivos PDF o Excel:

• ✅ Se han consultado los documentos de referencia correspondientes para aprender el método de procesamiento
• ✅ Se han comprendido las herramientas y los comandos recomendados
• ✅ Se ha completado el procesamiento del archivo (extracción/conversión)
• ⏭️ Ahora ya puedes comenzar la recuperación

Conductas prohibidas:

• ❌ Intentar procesar un PDF directamente sin haber leído primero el archivo pdf_reading.md
• ❌ Intentar procesar archivos Excel directamente sin haber leído primero el archivo excel_reading.md
• ❌ Saltarse los pasos de procesamiento de archivos y realizar la extracción directamente sobre los archivos PDF/Excel originales

Proceso general

1. Comprender las necesidades del usuario

   • Leer la consulta del usuario y extraer:
     • palabras clave del tema o ámbito (por ejemplo, «informes de ventas», «arquitectura del sistema», «documentación de interfaces»)
     • Limitaciones temporales o de alcance (por ejemplo, «primer trimestre de 2023», «última versión»)
     • Tipo de resultado requerido (explicación, resumen, valores concretos de campos, etc.)
   • Determinar el directorio raíz de la base de conocimientos:
     • Comprueba en primer lugar si el usuario ha especificado una ruta a la base de conocimientos en la pregunta.
     • De lo contrario, utilice el directorio raíz por defecto knowledge/。
     • Si el directorio raíz predeterminado no existe o la estructura de directorios es anómala, se debe solicitar confirmación al usuario, en lugar de hacer suposiciones por cuenta propia.

2. Revisar el índice de directorios por niveles data_structure.md

   • Utilizar el concepto de «directorio de trabajo actual»:
     • por defecto, se parte del directorio raíz de la base de conocimientos especificado por el usuario; si el usuario no lo ha especificado, se utiliza el directorio actual.
   • En el directorio de trabajo actual, si existe data_structure.md：
     • utilizar la función «Read» para leer las primeras líneas del archivo (por ejemplo, limit=300) y, si es necesario, continuar la lectura por tramos.
     • Objetivo:
       • Conocer qué subdirectorios y archivos hay en el directorio actual
       • Comprender la descripción del uso de cada subdirectorio o archivo
     • En función de la consulta del usuario, seleccionar los subdirectorios o archivos más relevantes para formar un conjunto de candidatos.
   • Para los subdirectorios candidatos:
     • entrar de forma recursiva en dicho subdirectorio, tomándolo como nuevo «directorio de trabajo actual», y continuar buscando en su interior data_structure.md y repetir el proceso anterior.
     • Durante el proceso recursivo, se debe evitar profundizar en todas las ramas a la vez, dando prioridad a la exploración de las rutas más relevantes para la incidencia.
   • En cuanto a los archivos de trabajo candidatos (md/texto, PDF, Excel, etc.):
     • Una vez completada la exploración necesaria de los niveles de directorios, recopilar estos archivos para formar la lista definitiva de objetivos de búsqueda.
   • A la hora de ordenarlos por prioridad:
     • Da prioridad a los directorios y archivos de ámbito específico cuya descripción de uso coincida en gran medida con el tema del problema.
     • En segundo lugar, se deben tener en cuenta las restricciones de tiempo o versión (si están reflejadas en el índice).
     • Los documentos de carácter general (como README.md o documentos de diseño general) se sitúan en una prioridad inferior.

3. Aprender los métodos de procesamiento de archivos (aplicar de forma obligatoria en el caso de archivos PDF o Excel).

   • Antes de procesar archivos PDF:
     • Es imprescindible leer primero el archivo references/pdf_reading.md (ten en cuenta que este directorio se encuentra en el directorio «Skills», no en el directorio «Knowledge») y aprender los métodos de extracción
     • Es fundamental conocer: el comando pdftotext, el uso de pdfplumber y los métodos de extracción de tablas
   • Antes de procesar archivos Excel:
     • Es imprescindible leer primero el archivo references/excel_reading.md para aprender los métodos de lectura
     • Es imprescindible leer primero el archivo references/excel_analysis.md para aprender los métodos de análisis
     • Puntos clave: lectura con pandas, selección de columnas y filtrado de datos
   • Objetivo: garantizar el uso de las herramientas y métodos correctos para evitar búsquedas a ciegas

4. Realizar el procesamiento y la recuperación según el tipo de archivo

   • Procesar los archivos utilizando los métodos que acabas de aprender (extracción, conversión y estructuración)
   • Para cada tipo de archivo candidato, seguir las estrategias que se indican a continuación: «Markdown/texto», «PDF» y «Excel»
   • Principio general:
     • Dar prioridad a los archivos más relevantes y precisos
     • Realizar búsquedas parciales y progresivas dentro de cada archivo, evitando cargar todo el contenido de una sola vez
     • Si no se obtiene información satisfactoria del archivo actual, pasar al siguiente archivo candidato

5. Búsqueda iterativa

   • Se utiliza un «mecanismo de búsqueda iterativa en varias rondas» uniforme para todos los tipos de documentos (véanse los principios generales de búsqueda más arriba)

6. Organización de las respuestas y referencia a las fuentes

   • Se recopila el contexto obtenido tras varias rondas de búsqueda y se responde de forma integral a la pregunta del usuario.
   • En la medida de lo posible:
     • dar respuestas claras y directas
     • Se indiquen los nombres de los documentos utilizados (incluyendo, cuando sea necesario, la ubicación aproximada, como el capítulo o el número aproximado de líneas o páginas)
   • Si la respuesta se basa en deducciones o en información incompleta:
     • Señalará claramente las suposiciones y las incertidumbres
     • Indique al usuario que puede añadir un rango de documentos más concreto o palabras clave

Principios de búsqueda pública

Estrategia de selección de palabras clave

• Extraer entre 3 y 8 palabras clave de la consulta del usuario (incluidas posibles abreviaturas en inglés, sinónimos y términos genéricos o específicos)
• Frases combinables (por ejemplo, «informes de ventas», «tiempo de espera de la interfaz API»)
• Incluir, cuando sea necesario, términos de negocio, jerga técnica y abreviaturas comunes (como «uv», «pv» o «GMV»)

Principios básicos de la búsqueda con grep

• Especificar siempre «include» y «path» con la mayor precisión posible, evitando buscar en todo el directorio
• En el patrón, dar prioridad a los sustantivos y términos clave de la consulta, y después probar con sinónimos
• Para cada resultado, lee solo la zona local cercana a la coincidencia (unas cuantas líneas por encima y por debajo)
• Guardar «nombre del archivo + información de ubicación + fragmento de texto»

Mecanismo de búsqueda iterativa en varias rondas (hasta un máximo de 5 veces)

Se aplica una estrategia de iteración unificada a todos los tipos de archivo:

1. Control de iteraciones
   • Se mantiene un recuento de «intentos de búsqueda», con un máximo de 5.
   • El recuento se incrementa tras cada búsqueda
2. Proceso de cada ronda de iteración
   1. Generación o actualización de palabras clave de búsqueda en función de la consulta (pueden incluir sinónimos y términos relacionados)
   2. Seleccionar archivos o partes de archivos que aún no se hayan buscado exhaustivamente
   3. Realizar la búsqueda (grep/lectura parcial/llamada a una habilidad específica)
   4. Analizar los fragmentos de contexto obtenidos
   5. Determinar si es suficiente para responder a la pregunta
3. Condiciones de finalización
   • Se ha encontrado contexto suficiente para respaldar la respuesta; o
   • Se han agotado los 5 intentos sin encontrar información adecuada
4. Procedimiento en caso de información insuficiente
   • Informar claramente al usuario de que falta información o de que es posible que no se encuentre en la base de datos actual
   • Proporcionar la información más cercana que se haya encontrado y explicar la incertidumbre
   • Sugerir al usuario cómo puede acotar la búsqueda (nombres de archivos más concretos, palabras clave, intervalos de tiempo, etc.)

Aspectos a tener en cuenta

• Prohibido llamar directamente desde el primer momento a:Glob "knowledge" in . ni realizar ninguna llamada que intente determinar la existencia de un directorio mediante Glob; la existencia del directorio debe comprobarse mediante comandos de shell (como test -d).
• Al consultar la base de conocimientos con esta Skill, no se permite utilizar otras herramientas, como búsquedas en Internet, para obtener información

Políticas específicas para los distintos tipos de archivo

1. Archivos de tipo Markdown / texto (.md, .txt, .log, etc.)

1. Selección de archivos candidatos

   • En función de data_structure.md el nombre del archivo y la ruta, se determina la relevancia
   • Se da prioridad a la búsqueda de archivos de tipo título e índice (como documentos de resumen o descripciones generales de diseño)

2. Localización con grep y lectura parcial

   • Utilizar la herramienta grep para los archivos candidatos especificados, limitando con «include» a extensiones concretas (por ejemplo, «*.md»)
   • Para los archivos que coincidan, utilizar «Read» para leer únicamente la zona cercana a la coincidencia:
     • Controlar la lectura mediante el desplazamiento de línea y el parámetro «limit» (por ejemplo, leer varias decenas de líneas hacia delante y hacia atrás desde la línea coincidente)
     • Evitar la lectura del archivo completo

3. Tratamiento especial

   • Si el contenido es solo un índice o un título, continuar la localización hacia el contenido más detallado basándose en los enlaces o los nombres de las secciones
   • Aplicar el «mecanismo de búsqueda iterativa en varias rondas» (véanse los principios generales de búsqueda mencionados anteriormente)

2. Estrategia de búsqueda en archivos PDF

Flujo de trabajo:

1. En primer lugar: leer la guía de métodos de procesamiento

   • Antes de procesar cualquier PDF, es imprescindible leer el archivo references/pdf_reading.md (tenga en cuenta que este directorio se encuentra en el directorio «Skills», y no en el directorio «Knowledge»)
   • Puntos clave: el comando pdftotext, el uso de pdfplumber, los métodos de extracción de tablas y la tabla de decisiones rápidas

2. Selección de archivos PDF candidatos

   • Según data_structure.md , selecciona entre 1 y 3 archivos que sean los más relevantes
   • Si el usuario especifica un archivo PDF concreto, se dará prioridad a dicho archivo

3. Aplicar los métodos aprendidos para extraer el texto

   • Utiliza las herramientas recomendadas en pdf_reading.md (preferiblemente pdftotext o pdfplumber)
   • Importante: utiliza pdftotext input.pdf output.txt extraer el texto a un archivo, en lugar de enviarlo directamente a stdout (para evitar el consumo excesivo de tokens)
   • Si se desea extraer tablas, utilizar la función de extracción de tablas de pdfplumber

4. Realizar búsquedas en los resultados extraídos

   • Utiliza `grep` para buscar palabras clave en el texto extraído
   • Para cada coincidencia, extrae el contexto de la zona cercana a la coincidencia (unas decenas de líneas por encima y por debajo o las páginas adyacentes)
   • Guardar «nombre del archivo + número de página/ubicación aproximada + fragmento de texto»
   • Aplicar el «mecanismo de búsqueda iterativa en varias rondas» (véanse los principios generales de búsqueda mencionados anteriormente)

3. Estrategia de búsqueda en archivos de Excel

Flujo de trabajo:

1. En primer lugar: leer la guía de métodos de procesamiento.

   • Antes de procesar cualquier archivo de Excel, es imprescindible leer:
     • references/excel_reading.md: aprende a leer hojas de cálculo (ten en cuenta que este directorio se encuentra en el directorio «Skills», no en el directorio «Knowledge»)
     • references/excel_analysis.md: aprende a analizar datos (ten en cuenta que este archivo se encuentra en el directorio «Skills», no en el de «Knowledge»)
   • Puntos clave: métodos de lectura de pandas, filtrado de columnas, filtrado de datos y operaciones de agregación

2. Seleccionar un archivo Excel candidato

   • Según data_structure.md los nombres de los archivos y hojas de cálculo, selecciona la hoja más relevante
   • Dar prioridad a los libros o hojas de cálculo que contengan palabras clave como «informes», «estadísticas», «registros», «configuración» o «mapeo»
   • Si el usuario especifica un archivo de Excel concreto, se utilizará preferentemente ese archivo

3. Aplicar los métodos aprendidos para explorar la estructura

   • Utilizar pandas para leer las primeras 10-50 filas (utilizando nrows los parámetros de limitación)
   • Aspectos clave: nombres de columnas/campos, tipos de datos (valores numéricos, fechas, texto) y campos clave
   • Comparar los nombres de las columnas con la consulta del usuario para identificar posibles campos clave (como «ingresos», «ventas», «error_code», etc.)

4. Realizar la recuperación y el análisis de datos

   • Utilizar los métodos de pandas aprendidos para filtrar y agrupar (por ejemplo, df[df['column'] == value]）
   • leer solo los datos cercanos a las filas que coincidan, evitando leer toda la tabla de una sola vez
   • Si la pregunta incluye un intervalo de tiempo, añadir un filtro de fecha a la búsqueda
   • Aplicar el «mecanismo de búsqueda iterativa en varias rondas» (véanse los principios generales de búsqueda mencionados anteriormente)

Colaboración con otras herramientas

Procesamiento de PDF

• Antes de procesar un PDF, es imprescindible leer el archivo references/pdf_reading.md para conocer el método de procesamiento
• Utilizar pdfplumber/pypdf para la extracción de texto, la extracción de tablas y la lectura de metadatos
• Dar prioridad a la herramienta de línea de comandos pdftotext para una extracción rápida de texto

Procesamiento de Excel

• Antes de procesar archivos Excel, es imprescindible consultar:
  • references/excel_reading.md: para aprender los métodos de lectura
  • references/excel_analysis.md: para aprender los métodos de análisis
• Utilizar pandas para explorar, previsualizar, filtrar y analizar datos

Principios de uso de las herramientas

• Grep: se utiliza para buscar, en un archivo determinado, los números de línea y los fragmentos que coincidan con una palabra clave; especifica siempre los parámetros «include» y «path» con la mayor precisión posible
• Read: se utiliza únicamente para leer partes de un archivo; establece siempre un «limit» razonable (por ejemplo, entre 200 y 500 líneas) y un desplazamiento adecuado
• Para cualquier archivo que pueda ser muy grande:
  • No se debe leer directamente de principio a fin
  • Reducir siempre primero el alcance mediante índices, directorios o palabras clave antes de leer

Estilo de respuesta y gestión de errores

• Estilo de respuesta
  • Intenta responder utilizando el mismo idioma que el usuario haya empleado en su pregunta (chino/inglés).
  • Empieza por dar la conclusión y, a continuación, expón brevemente los fundamentos.
  • Si es necesario, se pueden indicar al final los archivos consultados y su ubicación aproximada, por ejemplo:
    • Fuente: design/api_gateway.md, cerca de la línea 100
    • Fuente: reports/2023_Q1_sales.xlsx, hoja de cálculo «Summary»
• Cuando falte información o esta sea incierta
  • Indique claramente que no se ha encontrado información que coincida totalmente en la base de conocimientos actual o que solo se puede responder parcialmente.
  • No invente datos.
  • Indicar al usuario cómo puede ayudar a acotar la búsqueda:
    • Especificar un directorio o archivo más concreto
    • Proporcione palabras clave o nombres de campos más precisos
    • Especificar un intervalo de tiempo o una versión