Pesquisa na base de conhecimento local – Skill (kb-retriever)

Descrição do diretório da base de conhecimento

• A base de conhecimento está armazenada em um diretório raiz e contém diversos tipos de arquivos (como .md/.txt、.pdf、.xlsx etc.), geralmente divididos em subdiretórios de vários níveis por tipo ou finalidade comercial.
• Os arquivos são indexados por meio de uma estrutura de diretórios hierárquica:
  • O diretório raiz possui um arquivo data_structure.md, que descreve os principais “diretórios de área” e suas finalidades.
  • Cada diretório de área pode ter seu próprio data_structure.md, que descreve quais subdiretórios/arquivos estão presentes nesse diretório, bem como suas respectivas finalidades.
  • Os subdiretórios de níveis mais profundos também podem conter data_structure.md, formando uma árvore de índice de vários níveis.
• Convenção para o diretório raiz da base de conhecimento:
  • Por padrão, considera-se que a base de conhecimento está localizada no diretório knowledge/ .
  • Se o usuário especificar explicitamente outro caminho durante a interação (por exemplo, “Minha base de conhecimento está em /data/kb” ou “Use o diretório ./docs como base de conhecimento”), o caminho especificado pelo usuário será considerado o diretório raiz.
  • Quando o caminho padrão knowledge/ não existir ou houver falha no acesso, deve-se confirmar com o usuário a localização real do diretório raiz da base de conhecimento, em vez de fazer suposições aleatórias.
• Um único arquivo de negócios pode ser muito grande:
  • não leia o arquivo inteiro diretamente com o comando `Read`
  • Para PDFs e arquivos do Excel, utilize as Skills correspondentes para processá-los de forma estruturada e, em seguida, combine com o grep ou leitura parcial para realizar uma busca refinada

Localizar knowledge diretório raiz

• Priorize o diretório raiz, mas respeite o que o usuário indicar: se o usuário fornecer um caminho (como ./docs、./knowledge-personal), use diretamente o caminho fornecido pelo usuário.
• Diretório raiz padrão: caso contrário, o diretório raiz será, por convenção, o knowledge/。
  • Verificar explicitamente com o shell se o diretório existe: dar prioridade ao uso de test -d knowledge, ou, como alternativa, use ls -d knowledge。
  • Atenção: é proibido usar Glob "knowledge" in . desse tipo de padrão para determinar se o diretório existe,Glob pois ele retorna apenas o caminho do arquivo, e não o próprio diretório; um resultado vazio não permite distinguir entre “o diretório não existe” e “o diretório existe, mas está vazio”.
• Somente quando a existência do diretório raiz já tiver sido confirmada por meio de test -d ou de outra forma, é que se deve usar o Glob para buscar conteúdo nesse diretório, tratando-o como path, por exemplo:
  • arquivo de índice:pattern="**/data_structure.md", path="knowledge"
  • Todos os Markdown:pattern="**/*.md", path="knowledge"
• Se, por padrão, knowledge/ não existir (test -d falha): não adivinhe outros diretórios; informe claramente ao usuário que o diretório raiz padrão não foi encontrado e peça que ele especifique o caminho real da base de conhecimento.

Princípio fundamental: primeiro aprender, depois processar

Lista de verificação obrigatória ao encontrar arquivos PDF ou Excel:

• ✅ Já li a documentação de referências correspondente para aprender os métodos de processamento
• ✅ Já compreendi as ferramentas e comandos recomendados
• ✅ Concluí o processamento do arquivo (extração/conversão)
• ⏭️ Agora é possível iniciar a pesquisa

Ações proibidas:

• ❌ Tentar processar o PDF diretamente sem ter lido o arquivo pdf_reading.md
• ❌ Tentar processar o Excel diretamente sem ter lido o arquivo excel_reading.md
• ❌ Pular as etapas de processamento de arquivos e realizar a pesquisa diretamente no PDF/Excel original

Fluxo geral

1. Compreender as necessidades do usuário

   • Ler a questão do usuário e extrair:
     • palavras-chave do tema/área (como “relatório de vendas”, “arquitetura de sistema”, “documentação de interface”)
     • Limites de tempo ou escopo (por exemplo, “1º trimestre de 2023”, “versão mais recente”)
     • Tipo de resultado desejado (explicação, resumo, valores específicos de campos, etc.)
   • Determinar o diretório raiz da base de conhecimento:
     • Verifique primeiro se o usuário especificou o caminho da base de conhecimento na pergunta.
     • Caso contrário, utilize o diretório raiz padrão knowledge/。
     • Se o diretório raiz padrão não existir ou a estrutura de diretórios estiver incorreta, deve-se solicitar a confirmação do usuário, em vez de fazer suposições por conta própria.

2. Visualizar o índice de diretórios em camadas data_structure.md

   • Utilize o conceito de “diretório de trabalho atual”:
     • por padrão, a partir do diretório raiz da base de conhecimento especificado pelo usuário; se o usuário não tiver especificado, use o diretório atual.
   • No diretório de trabalho atual, se houver data_structure.md：
     • utilize o comando `Read` para ler as primeiras linhas do arquivo (por exemplo, `limit=300`); se necessário, continue a leitura em partes.
     • Objetivo:
       • Identificar quais subdiretórios e arquivos existem no diretório atual
       • Compreender a descrição da finalidade de cada subdiretório/arquivo
     • Com base na questão do usuário, selecionar os subdiretórios ou arquivos mais relevantes para formar um conjunto de candidatos.
   • Para os subdiretórios candidatos:
     • entrar recursivamente nesse subdiretório, considerando-o como o novo “diretório de trabalho atual”, e continuar a busca por data_structure.md e repetir o processo acima.
     • Durante o processo recursivo, evite explorar todas as ramificações de uma só vez; priorize a exploração das caminhos mais relevantes para a questão.
   • Para os arquivos de negócios candidatos (md/texto, PDF, Excel etc.):
     • Após concluir a exploração necessária da hierarquia de diretórios, reúna esses arquivos para formar a lista final de alvos de pesquisa.
   • Ao classificar por prioridade:
     • Dê prioridade a diretórios e arquivos cujas descrições de uso sejam altamente compatíveis com o tema da questão
     • Em segundo lugar, considere restrições como data/versão (se estiverem refletidas no índice)
     • Documentos de instruções gerais (como README.md e documentos de projeto geral) devem ter prioridade mais baixa

3. Aprenda os métodos de processamento de arquivos (aplique-os obrigatoriamente ao encontrar arquivos PDF/Excel)

   • Antes de processar arquivos PDF:
     • é necessário ler primeiro o arquivo references/pdf_reading.md (observe que esse diretório está localizado no diretório Skills, e não no diretório Knowledge) Aprenda os métodos de extração
     • Concentre-se em: o comando pdftotext, o uso do pdfplumber e os métodos de extração de tabelas
   • Antes de processar arquivos Excel:
     • É necessário ler primeiro o arquivo references/excel_reading.md para aprender os métodos de leitura
     • É necessário ler primeiro o arquivo references/excel_analysis.md para aprender os métodos de análise
     • Pontos importantes a serem compreendidos: leitura com pandas, filtragem de colunas e filtragem de dados
   • Objetivo: garantir o uso das ferramentas e métodos corretos, evitando a recuperação aleatória

4. Executar o processamento e a extração de acordo com o tipo de arquivo

   • Processar os arquivos utilizando os métodos recém-aprendidos (extração, conversão, estruturação)
   • Para cada categoria de arquivos candidatos, seguir as estratégias abaixo: “Markdown/texto”, “PDF” e “Excel”
   • Princípio geral:
     • Comece prioritariamente pelos arquivos mais relevantes e precisos
     • Realizar a busca local de forma progressiva dentro de cada arquivo, evitando carregar todo o conteúdo de uma só vez
     • Se o arquivo atual não fornecer informações satisfatórias, passe para o próximo arquivo candidato

5. Pesquisa iterativa

   • Todos os tipos de arquivos utilizam um “mecanismo de pesquisa iterativa em várias rodadas” unificado (ver os princípios gerais de pesquisa acima)

6. Organização e atribuição de fontes das respostas

   • Reúna o contexto obtido nas várias rodadas de pesquisa para responder de forma abrangente à pergunta do usuário.
   • Procure, na medida do possível:
     • Fornecer respostas claras e diretas
     • Indicar os nomes dos documentos utilizados (incluindo, quando necessário, a localização aproximada, como capítulo ou número aproximado de linhas/páginas)
   • Se a resposta for baseada em suposições ou em informações incompletas:
     • Indique claramente as suposições e as incertezas
     • Sugira ao usuário que complemente com um escopo mais específico do documento ou palavras-chave

Princípios de pesquisa pública

Estratégia de seleção de palavras-chave

• Extrair de 3 a 8 palavras-chave da consulta do usuário (incluindo possíveis siglas em inglês, sinônimos, termos de nível superior/inferior)
• Expressões combinadas (como “relatório de vendas”, “tempo limite da interface API”)
• Incluir, quando necessário, termos de negócios, terminologia técnica e abreviações comuns (como “uv”, “pv”, “GMV”)

Princípios básicos da pesquisa com grep

• Sempre especifique `include` e `path` da forma mais precisa possível, evitando pesquisar em todo o diretório
• No padrão, priorize os substantivos e termos centrais da questão e, em seguida, tente sinônimos
• Para cada resultado, leia apenas a área local próxima à correspondência (algumas linhas acima e abaixo)
• Salve “nome do arquivo + informações de localização + trecho de texto”

Mecanismo de pesquisa iterativa em várias rodadas (no máximo 5 vezes)

Todos os tipos de arquivo adotam uma estratégia de iteração unificada:

1. Controle de iteração
   • Manutenção do contador de “número de tentativas de pesquisa”, com limite máximo de 5 vezes
   • O contador é incrementado após cada tentativa de recuperação
2. Fluxo de cada rodada de iteração
   1. Geração/atualização de palavras-chave de pesquisa com base na consulta (podem incluir sinônimos e termos relacionados)
   2. Selecionar arquivos ou partes de arquivos que ainda não foram pesquisados de forma adequada
   3. Executar a busca (grep/leitura local/chamada de Skill específica)
   4. Analisar os trechos de contexto obtidos
   5. Avaliar se são suficientes para responder à pergunta
3. Condições de encerramento
   • Encontrar contexto suficiente para fundamentar a resposta; ou
   • Atingir 5 tentativas sem encontrar informações adequadas
4. Tratamento em caso de informações insuficientes
   • Informar claramente ao usuário que faltam informações ou que elas podem não estar na base de conhecimento atual
   • Fornecer a informação mais próxima encontrada e explicar a incerteza
   • Sugira ao usuário como ele pode restringir a pesquisa (nome de arquivo mais específico, palavras-chave, intervalo de tempo etc.)

Observações

• É proibido chamar diretamente, logo na primeira tentativa:Glob "knowledge" in . ou qualquer chamada que tente determinar a existência de um diretório usando Glob; a existência do diretório deve ser verificada por meio de comandos do shell (como test -d) para verificar a existência de diretórios.
• Ao consultar a base de conhecimento com esta Skill, é proibido utilizar outras ferramentas, como pesquisas na internet, para obter informações

Políticas específicas para diferentes tipos de arquivos

1. Arquivos do tipo Markdown / texto (.md, .txt, .log etc.)

1. Seleção de arquivos candidatos

   • Com base data_structure.md e do nome e caminho do arquivo
   • Priorizar a busca por arquivos do tipo título e índice (como documentos de resumo, visão geral do projeto)

2. Localização com grep e leitura parcial

   • Utilizar a ferramenta grep nos arquivos candidatos especificados, com o parâmetro `include` para restringir a busca a extensões específicas (como "*.md")
   • Para arquivos com correspondência, use o Read para ler apenas a região local próxima à correspondência:
     • Controle a leitura por meio do deslocamento de linha e do parâmetro `limit` (por exemplo, lendo algumas dezenas de linhas antes e depois da linha correspondente)
     • Evite a leitura do arquivo inteiro

3. Tratamento especial

   • Se o conteúdo for apenas um índice/título, continue a localização do conteúdo mais detalhado com base em links ou nomes de seções
   • Aplique o “mecanismo de pesquisa iterativa em várias rodadas” (consulte os princípios gerais de pesquisa acima)

2. Estratégia de pesquisa em arquivos PDF

Fluxo de trabalho:

1. Primeiro: ler o guia de métodos de processamento

   • Antes de processar qualquer PDF, é necessário ler o arquivo references/pdf_reading.md (observe que esse diretório está localizado no diretório Skills, e não no diretório Knowledge)
   • Pontos importantes a serem compreendidos: o comando pdftotext, o uso do pdfplumber, métodos de extração de tabelas e a tabela de decisões rápidas

2. Seleção dos PDFs candidatos

   • De acordo com data_structure.md , selecione de 1 a 3 arquivos mais relevantes
   • Se o usuário indicar um arquivo PDF específico, desse arquivo será dada prioridade

3. Aplique os métodos aprendidos para extrair o texto

   • Utilize as ferramentas recomendadas no arquivo pdf_reading.md (de preferência pdftotext ou pdfplumber)
   • Importante: use pdftotext input.pdf output.txt Extrai o texto para um arquivo; não o envie diretamente para o stdout (para evitar o consumo excessivo de tokens)
   • Para extrair tabelas, use o recurso de extração de tabelas do pdfplumber

4. Execute uma pesquisa nos resultados extraídos

   • Use o grep para realizar uma busca por palavras-chave no texto extraído
   • Para cada ocorrência, extraia o contexto próximo à ocorrência (dezenas de linhas acima e abaixo ou algumas páginas adjacentes)
   • Salve como “nome do arquivo + número da página/localização aproximada + trecho de texto”
   • Aplique o “mecanismo de pesquisa iterativo em várias rodadas” (consulte os princípios gerais de pesquisa acima)

3. Estratégia de pesquisa em arquivos do Excel

Fluxo de trabalho:

1. Primeiro: ler o guia de métodos de processamento

   • Antes de processar qualquer arquivo do Excel, é necessário ler:
     • references/excel_reading.md — aprenda como ler planilhas (observe que esse diretório está localizado no diretório Skills, e não no diretório Knowledge)
     • references/excel_analysis.md — aprenda a analisar dados (observe que esse arquivo está localizado na pasta “Skills”, e não na pasta “Knowledge”)
   • Destaque: métodos de leitura do pandas, filtragem de colunas, filtragem de dados e operações de agregação

2. Selecione um arquivo Excel candidato

   • Com base data_structure.md e à nomenclatura dos arquivos/planilhas, selecione a planilha mais relevante
   • Dê prioridade a pastas de trabalho/planilhas que contenham palavras-chave como “relatório”, “estatística”, “log”, “configuração” e “mapeamento”
   • Se o usuário indicar um arquivo do Excel específico, use esse arquivo prioritariamente

3. Aplicar os métodos aprendidos para explorar a estrutura

   • Use o pandas para ler as primeiras 10 a 50 linhas (utilizando nrows limites de parâmetros)
   • Foco: nomes de colunas/campos, tipos de dados (numéricos, datas, texto), campos-chave
   • Comparar os nomes das colunas com a questão do usuário para identificar possíveis campos-chave (como “renda”, “vendas”, “error_code”, etc.)

4. Executar a recuperação e a análise de dados

   • Utilizar os métodos do pandas aprendidos para filtrar e agregar (por exemplo, df[df['column'] == value]）
   • ler apenas os dados próximos às linhas correspondentes de cada vez, evitando a leitura da tabela inteira de uma só vez
   • Se a pergunta incluir um intervalo de tempo, inclua um filtro de data na consulta
   • Aplicar o “mecanismo de recuperação iterativa em várias rodadas” (consulte os princípios gerais de recuperação acima)

Integração com outras ferramentas

Processamento de PDF

• Antes de processar um PDF, é necessário ler o arquivo references/pdf_reading.md para aprender os métodos de processamento
• Utilize o pdfplumber/pypdf para extração de texto, extração de tabelas e leitura de metadados
• Priorizar o uso da ferramenta de linha de comando pdftotext para extração rápida de texto

Processamento de Excel

• Antes de processar arquivos Excel, é necessário ler:
  • references/excel_reading.md — para aprender os métodos de leitura
  • references/excel_analysis.md — para aprender os métodos de análise
• Utilizar o pandas para exploração, visualização, filtragem e análise de dados

Princípios de uso das ferramentas

• Grep: usado para localizar números de linha e trechos correspondentes a palavras-chave em um arquivo específico; sempre especifique os parâmetros `include` e `path` da forma mais precisa possível
• Read: usado apenas para leitura parcial de arquivos; sempre defina um `limit` razoável (por exemplo, 200 a 500 linhas) e um deslocamento adequado
• Para qualquer arquivo que possa ser muito grande:
  • É proibido ler diretamente do início ao fim
  • Sempre reduza o escopo primeiro por meio de índices, diretórios, palavras-chave etc. antes de ler

Estilo de resposta e tratamento de erros

• Estilo de resposta
  • Tente responder utilizando a mesma língua em que o usuário formulou a pergunta (chinês/inglês).
  • Apresente primeiro a conclusão e, em seguida, uma breve justificativa.
  • Se necessário, liste em seguida os arquivos citados e a localização aproximada, por exemplo:
    • Fonte: design/api_gateway.md, por volta da linha 100
    • Fonte: reports/2023_Q1_sales.xlsx, planilha “Summary”
• Quando houver informações ausentes ou incertas
  • Deixe claro que não foi encontrada nenhuma informação que corresponda exatamente à consulta na base de conhecimento atual ou que a resposta seja apenas parcial.
  • Não invente fatos.
  • Sugira ao usuário como ele pode ajudar a restringir a busca:
    • especificar um diretório/arquivo mais específico
    • Forneça palavras-chave ou nomes de campos mais precisos
    • Especificar um intervalo de tempo/versão