Crear una CLI local que busque tus documentos por palabras clave y por significado

## Usar un solo entorno de ejecución y dar a cada grupo de comandos una tarea clara Elija un entorno de ejecución y un gestor de paquetes compatibles como vía de desarrollo canónica. No mezcle entornos alternativos ni comandos de instalación solo porque parezcan compatibles. Mantenga explícitas las responsabilidades de los comandos: - los comandos de colección gestionan las raíces indexadas y su configuración; - los comandos de contexto asocian indicaciones de búsqueda a las rutas; - los comandos de recuperación devuelven documentos conocidos; - los comandos de búsqueda clasifican los documentos candidatos; - los comandos de mantenimiento inspeccionan o actualizan el índice; - los comandos de servicio ofrecen las mismas capacidades a otros procesos. Conserve el contenedor de comandos instalado cuando este ejecute código compilado de la aplicación. Compile el código fuente con el flujo de compilación documentado; no sustituya el contenedor por un único ejecutable compilado cuando las extensiones nativas dependan de la disposición existente. ## Guardar la configuración de cada colección y distinguir excluir de eliminar Represente cada colección mediante un nombre único, una raíz de origen, una máscara de archivos, un estado de inclusión y un hook previo a la actualización opcional. Permita añadir, enumerar, inspeccionar, renombrar, incluir, excluir y eliminar colecciones. Distinga la eliminación de la exclusión: la eliminación borra el registro de la colección, mientras que la exclusión solo la omite en las consultas sin un ámbito explícito. Permita enumerar los archivos de una colección completa o de un prefijo de ruta. Cuando la interfaz lo admita, acepte tanto rutas de colección normales como el URI de colección virtual de la herramienta. Trate las adiciones, eliminaciones, cambios de nombre, cambios en hooks, cambios en la inclusión y actualizaciones del índice como cambios de estado. Cuando se requiera la aprobación del usuario, presente el comando exacto y el efecto previsto antes de ejecutarlo. ## Asociar notas de búsqueda (contexto) a rutas, separadas del texto de los documentos Almacene el contexto redactado por personas separado del contenido de los documentos, de modo que las indicaciones de clasificación puedan evolucionar sin reescribir los archivos de origen. Permita establecer contexto en: - el directorio actual detectado dentro de una colección; - una subruta concreta; - una ruta de colección virtual; - la raíz global, para las indicaciones que se aplican a todas las colecciones. Proporcione comandos para enumerar el contexto, detectar rutas que carezcan de él y retirar el contexto obsoleto. Aplique el contexto pertinente más específico sin perder las indicaciones globales. No confunda los metadatos de contexto con el texto de los documentos indexados. Haga visible el ámbito para que una nota local no influya silenciosamente en colecciones no relacionadas. ## Dar a cada documento un ID corto y limitar cuánto se devuelve Asigne a cada documento un identificador corto derivado de los primeros 6 caracteres del hash de su contenido. Muestre el identificador en los resultados de búsqueda y acéptelo con o sin el marcador inicial. Permita la recuperación por ruta o identificador, una línea inicial y un número de líneas opcionales, y la recuperación por lotes mediante un glob o una lista separada por comas. Acote la recuperación de forma explícita: - establezca un número máximo de líneas por archivo; - establezca un tamaño máximo en bytes y documente el valor predeterminado, como 10 KB; - omita los archivos demasiado grandes en vez de devolver contenido parcial sin avisar; - incluya los números de línea de forma predeterminada y permita que quien realiza la llamada los desactive; - devuelva las rutas completas en disco solo cuando se soliciten. ## Elegir el tipo de búsqueda según la consulta, con la búsqueda híbrida por defecto Ofrezca tres vías de búsqueda diferentes: - búsqueda por palabras clave mediante clasificación de texto completo, como BM25, sin un modelo de lenguaje; - búsqueda por similitud vectorial mediante incrustaciones locales, sin reclasificación; - búsqueda híbrida ampliada mediante expansión de consultas y reclasificación, como opción predeterminada de máxima calidad. Use la fusión por rango recíproco para combinar conjuntos de resultados clasificados de forma independiente. Mantenga suficientemente visibles las puntuaciones originales y el modo para poder diagnosticar ordenaciones inesperadas. Prefiera la vía de consulta híbrida para el uso general. Elija la búsqueda por palabras clave cuando importen los términos exactos, la búsqueda vectorial cuando el objetivo sea la similitud semántica y una opción sin reclasificación cuando la velocidad importe más que la calidad final del orden. ## Permitir elegir colecciones y formatos de salida sin cambiar los resultados Permita que quien realiza la llamada repita filtros de colección para buscar en varias colecciones con nombre y excluir todas las demás. Admita un número de resultados, un modo de todos los resultados, una puntuación mínima, un modo de contenido completo y una descripción de la intención que precise la clasificación. Mantenga separadas la presentación y la transferencia de datos. Proporcione un formato legible para la línea de comandos, además de salidas estructuradas en JSON, CSV, Markdown, XML y listas de archivos. Conserve los indicadores de formato antiguos solo como alias de una única opción de formato canónica. Para la recuperación por lotes, exponga los límites de líneas y bytes, y los controles de numeración de líneas, con independencia de la clasificación de búsqueda. No permita que una opción de presentación cambie qué documentos se seleccionan. ## Crear el índice de búsqueda y dividir los documentos en fragmentos predecibles Use una base de datos local duradera para la indexación de texto completo y una extensión vectorial compatible para la similitud semántica. Ejecute las incrustaciones, la reclasificación y la expansión de consultas mediante modelos locales configurados. Use una segmentación inteligente de documentos con un objetivo de 900 tokens por fragmento y un solapamiento del 15%. Prefiera los encabezados de Markdown como límites cuando sea posible. Proporcione una estrategia que tenga en cuenta el árbol de sintaxis abstracta para los archivos de código compatibles, de forma que los fragmentos coincidan con los límites de funciones, clases e importaciones. Selecciónela mediante una estrategia automática explícita. Mantenga la segmentación por expresiones regulares como opción predeterminada y úsela sistemáticamente para Markdown y los tipos de archivo desconocidos. Mantenga la indexación, la generación de incrustaciones y la clasificación durante la consulta como etapas separadas, para poder diagnosticar errores sin reconstruirlo todo. ## Revisar el estado del índice y de los modelos antes de ajustar la clasificación Proporcione información de estado que muestre la salud de las colecciones y el índice sin cambiar su estado. Añada un comando de diagnóstico para los problemas de configuración, índice, modelo y dispositivo. Mida la calidad de búsqueda con archivos de datos de prueba versionados. Registre la consulta, los documentos pertinentes esperados, el modo, las métricas de clasificación, la configuración del modelo y la versión del índice para que las comparaciones sean reproducibles. Use el diagnóstico antes de cambiar los pesos de clasificación, los modelos o la configuración de los dispositivos. La ausencia de un modelo, un índice desactualizado, una extensión vectorial incompatible o un dispositivo no disponible no demuestran por sí mismos que el algoritmo de clasificación sea incorrecto. ## Ejecutar la herramienta como servicio local o HTTP solo cuando se pida Ofrezca un servicio de entrada y salida estándar para integrar procesos locales y un servicio HTTP opcional para clientes remotos. Use un puerto predeterminado documentado, como el 8181, y permita sustituirlo de forma explícita. Admita la ejecución en primer plano para depurar y un modo de demonio en segundo plano para el uso prolongado. Proporcione un comando de detención correspondiente que actúe únicamente sobre el demonio gestionado. Mantenga separado el transporte del servicio de la semántica de búsqueda. La interfaz de línea de comandos y la interfaz de servicio deben compartir las reglas de colecciones, contexto, recuperación, clasificación y salida. No inicie implícitamente un servicio en segundo plano. Cuando se inicie un servicio, informe del punto de conexión, el modo del proceso, el origen de la configuración y el método para detenerlo. ## Dejar al usuario los cambios del índice y no romper el contenedor de comandos instalado Nunca añada automáticamente una colección, genere incrustaciones ni actualice índices. Nunca modifique directamente la base de datos de búsqueda subyacente. Cuando un flujo de trabajo solicitado necesite uno de estos cambios, muestre el comando exacto para que lo ejecute el usuario y explique los archivos previstos, la duración y el uso de recursos. Mantenga disponibles la búsqueda y la recuperación de solo lectura sin ampliar los permisos. No ejecute un modo de compilación que sobrescriba el contenedor de shell instalado o inutilice las extensiones vectoriales nativas. No sustituya un contenedor que inicia deliberadamente JavaScript compilado desde un directorio de distribución. Trate los hooks previos a la actualización como configuración ejecutable. Muéstrelos durante la inspección y ejecútelos únicamente como parte de una actualización del índice solicitada explícitamente. ## Añadir pruebas de regresión y publicar con un registro de cambios Mantenga las pruebas automatizadas en el árbol de pruebas designado y ejecute las baterías completas documentadas mediante el entorno de ejecución compatible. Añada pruebas de regresión acotadas para el estado de las colecciones, los límites de recuperación, los modos de clasificación, los límites de fragmentos y el ciclo de vida del servicio. Use el flujo de publicación canónico en lugar de preparar una publicación manualmente: 1. añada entradas al registro de cambios en la sección de cambios no publicados conforme se realicen; 2. convierta esa sección en una versión fechada durante la publicación; 3. reconozca las contribuciones externas mediante el formato de referencia exigido por el proyecto; 4. reúna las notas de publicación de toda la serie de versiones prevista; 5. ejecute los hooks de publicación y la verificación antes de publicar. Informe del comportamiento modificado, la compatibilidad del índice o el esquema, las pruebas ejecutadas, el efecto en las mediciones, las necesidades de migración y cualquier comando que cambie el estado y quede pendiente para el usuario.