Criar uma CLI local que busca seus documentos por palavra-chave e por significado

## Use um único ambiente de execução e dê a cada grupo de comandos uma função clara Escolha um ambiente de execução compatível e um gerenciador de pacotes como caminho canônico de desenvolvimento. Não misture ambientes de execução substitutos nem comandos de instalação apenas porque parecem compatíveis. Mantenha explícitas as responsabilidades dos comandos: - comandos de coleção gerenciam as raízes indexadas e suas configurações; - comandos de contexto associam orientações de busca a caminhos; - comandos de recuperação retornam documentos conhecidos; - comandos de busca ranqueiam documentos candidatos; - comandos de manutenção inspecionam ou atualizam o índice; - comandos de serviço expõem os mesmos recursos a outros processos. Preserve o invólucro de comando instalado quando ele encaminhar a execução para o código compilado do aplicativo. Compile o código-fonte com o fluxo de compilação documentado; não substitua o invólucro por um único executável compilado quando extensões nativas dependerem da estrutura existente. ## Registre as configurações de cada coleção e diferencie excluir de remover Represente cada coleção com um nome exclusivo, uma raiz de origem, uma máscara de arquivos, um estado de inclusão e um gancho opcional anterior à atualização. Ofereça operações para adicionar, listar, inspecionar, renomear, incluir, excluir e remover coleções. Diferencie remoção de exclusão: a remoção apaga o registro da coleção, enquanto a exclusão apenas a omite de consultas sem escopo definido. Permita listar arquivos de uma coleção inteira ou de um prefixo de caminho. Aceite tanto caminhos simples da coleção quanto o URI virtual de coleção da ferramenta quando a interface oferecer suporte. Trate adição, remoção, renomeação, alterações de ganchos, alterações de inclusão e atualizações do índice como modificações de estado. Quando for necessária a aprovação do usuário, apresente o comando exato e o efeito esperado antes da execução. ## Associe notas de busca (contexto) a caminhos, separadas do texto dos documentos Armazene o contexto escrito por pessoas separadamente do conteúdo dos documentos, para que as orientações de ranqueamento possam evoluir sem reescrever os arquivos de origem. Permita contexto em: - o diretório atual detectado dentro de uma coleção; - um subcaminho específico; - um caminho virtual da coleção; - a raiz global, para orientações que se aplicam a todas as coleções. Forneça comandos para listar o contexto, detectar caminhos sem contexto e remover contexto obsoleto. Aplique o contexto pertinente mais específico, preservando as orientações globais. Não confunda metadados contextuais com o texto indexado dos documentos. Torne o escopo visível para que uma nota local não influencie silenciosamente coleções sem relação. ## Dê a cada documento um ID curto e limite quanto é retornado Atribua a cada documento um identificador curto derivado dos primeiros 6 caracteres do hash de seu conteúdo. Mostre o identificador nos resultados da busca e aceite-o com ou sem o marcador inicial. Ofereça recuperação por caminho ou identificador, com linha inicial e número de linhas opcionais, além de recuperação em lote a partir de um padrão glob ou de uma lista separada por vírgulas. Limite a recuperação de forma explícita: - defina um número máximo de linhas por arquivo; - defina um tamanho máximo em bytes e documente o padrão, como 10 KB; - ignore arquivos grandes demais, em vez de retornar conteúdo parcial sem aviso; - inclua números de linha por padrão e permita que o solicitante os desative; - retorne caminhos completos no disco somente quando solicitado. ## Escolha o tipo de busca conforme a consulta, com a busca híbrida como padrão Disponibilize três caminhos de busca distintos: - busca por palavras-chave com ranqueamento de texto completo, como BM25, sem modelo de linguagem; - busca por similaridade vetorial com embeddings locais, sem reranqueamento; - busca híbrida expandida com expansão de consulta e reranqueamento como padrão de maior qualidade. Use fusão por classificação recíproca para combinar conjuntos de resultados ranqueados de forma independente. Mantenha as pontuações originais e o modo visíveis o suficiente para diagnosticar uma ordenação inesperada. Prefira o caminho de consulta híbrida para uso geral. Escolha a busca por palavras-chave quando termos exatos forem importantes, a busca vetorial quando a similaridade semântica for o objetivo e uma opção sem reranqueamento quando a velocidade for mais importante do que a qualidade da ordenação final. ## Permita escolher coleções e formatos de saída sem mudar os resultados Permita que o solicitante repita filtros de coleção para pesquisar várias coleções nomeadas, excluindo todas as demais. Ofereça contagem de resultados, modo de todos os resultados, pontuação mínima, modo de conteúdo completo e uma descrição da intenção que refine o ranqueamento. Separe a exibição do transporte de dados. Forneça um formato legível na linha de comandos, além de saídas estruturadas em JSON, CSV, Markdown, XML e lista de arquivos. Preserve opções de formato antigas apenas como aliases de uma única opção de formato canônica. Para recuperação em lote, exponha limites de linhas, limites de bytes e controles de números de linha de forma independente do ranqueamento da busca. Não permita que uma opção de apresentação altere quais documentos foram selecionados. ## Crie o índice de busca e divida os documentos em partes previsíveis Use um banco de dados local durável para indexação de texto completo e uma extensão vetorial compatível para similaridade semântica. Execute embeddings, reranqueamento e expansão de consultas por meio de modelos locais configurados. Use divisão inteligente de documentos com alvo de 900 tokens por segmento e sobreposição de 15%. Sempre que possível, prefira títulos Markdown como limites. Ofereça uma estratégia ciente da árvore de sintaxe abstrata para arquivos de código compatíveis, para que os segmentos se alinhem a funções, classes e importações. Selecione-a por meio de uma estratégia automática explícita. Mantenha a divisão por expressões regulares como padrão e use-a de forma consistente para Markdown e tipos de arquivo desconhecidos. Mantenha a indexação, a geração de embeddings e o ranqueamento durante a consulta como etapas separadas, para que seja possível diagnosticar falhas sem reconstruir tudo. ## Verifique o estado do índice e dos modelos antes de ajustar o ranqueamento Forneça uma saída de estado que mostre a integridade das coleções e do índice sem alterar o estado. Acrescente um comando de diagnóstico para problemas de configuração, índice, modelo e dispositivo. Compare a qualidade da busca com arquivos de fixture versionados. Registre a consulta, os documentos relevantes esperados, o modo, as métricas de ranqueamento, a configuração do modelo e a versão do índice, para que as comparações permaneçam reproduzíveis. Use diagnósticos antes de alterar pesos de ranqueamento, modelos ou configurações de dispositivo. Um modelo ausente, um índice desatualizado, uma extensão vetorial incompatível ou um dispositivo indisponível não são evidência de que o próprio algoritmo de ranqueamento esteja errado. ## Execute a ferramenta como serviço local ou HTTP só quando for pedido Ofereça um serviço de entrada e saída padrão para integração com processos locais e um serviço HTTP opcional para clientes remotos. Use uma porta padrão documentada, como 8181, e permita uma substituição explícita. Ofereça operação em primeiro plano para depuração e um modo de daemon em segundo plano para uso prolongado. Forneça um comando de parada correspondente que atinja somente o daemon gerenciado. Mantenha o transporte do serviço separado da semântica da busca. A interface de linha de comandos e a interface de serviço devem compartilhar as regras de coleção, contexto, recuperação, ranqueamento e saída. Não inicie implicitamente um serviço em segundo plano. Ao iniciar um serviço, informe o endpoint, o modo do processo, a origem da configuração e o método de encerramento. ## Deixe as alterações do índice para o usuário e não danifique o invólucro de comando instalado Nunca adicione uma coleção, gere embeddings ou atualize índices automaticamente. Nunca modifique diretamente o banco de dados de busca subjacente. Quando um fluxo de trabalho solicitado precisar de uma dessas modificações, mostre o comando exato para o usuário executar e explique os arquivos esperados, a duração e o uso de recursos. Mantenha a busca e a recuperação somente para leitura disponíveis sem ampliar as permissões. Não execute um modo de compilação que sobrescreva o invólucro de shell instalado ou danifique extensões vetoriais nativas. Não substitua um invólucro que inicia intencionalmente JavaScript compilado a partir de um diretório de distribuição. Trate os ganchos anteriores à atualização como configuração executável. Mostre-os durante a inspeção e execute-os apenas como parte de uma atualização do índice solicitada explicitamente. ## Adicione testes de regressão e publique com um registro de alterações Mantenha os testes automatizados na árvore de testes designada e execute as suítes completas documentadas usando o ambiente de execução compatível. Acrescente testes de regressão específicos para estado das coleções, limites de recuperação, modos de ranqueamento, limites de segmentos e ciclo de vida do serviço. Use o fluxo de publicação canônico em vez de montar uma publicação manualmente: 1. acrescente entradas ao registro de alterações na seção de itens ainda não publicados à medida que as mudanças forem feitas; 2. converta essa seção em uma versão datada durante a publicação; 3. atribua crédito a contribuições externas usando o formato de referência exigido pelo projeto; 4. agregue as notas de publicação para a série de versões pretendida; 5. execute os ganchos e a verificação da publicação antes de publicar. Informe o comportamento alterado, a compatibilidade do índice ou esquema, os testes executados, o impacto nos benchmarks, as necessidades de migração e qualquer comando que altere o estado e tenha ficado para o usuário executar.