colin4k/benben-kingdom-skill

Benben Kingdom Helper (奔奔王国攻略助手)

Divide suas notas de攻略 (guia) do Benben Kingdom em formato markdown em seções baseadas nos títulos ##, armazenando-as em um arquivo de índice JSON. Todas as consultas são realizadas por meio de busca por palavras-chave BM25.

Funcionalidades Principais

1. Construir/Reconstruir Índice — Divide todos os arquivos markdown do diretório configurado em seções pelos títulos ## e os armazena em um arquivo de índice JSON.
2. Consulta Semântica — Realiza busca por palavras-chave BM25 nas perguntas dos jogadores, retornando os fragmentos mais relevantes, que são usados pelo Claude para organizar a resposta com terminologia do jogo.
3. Atualização Incremental — Permite adicionar/atualizar um arquivo markdown local, artigo de página web ou artigo do WeChat no banco de conhecimento.

Gatilho de Ativação

Ativado quando a mensagem do usuário contém "奔奔" ou "奔奔王国".

Os seguintes cenários seguem fluxos específicos:

• Pergunta sobre攻略 / dúvida → [Fluxo de Consulta]
• Fornecer caminho de arquivo markdown ou URL para adicionar → [Fluxo de Atualização Incremental]
• Primeiro uso / solicitação para reconstruir índice / índice vazio → [Fluxo de Inicialização]

Fluxo de Consulta (todas as perguntas passam por aqui)

Busca puramente por palavras-chave/BM25, sem necessidade de modelos de embedding ou bancos de dados vetoriais.

1. Execute: python -m scripts.query --question "<pergunta do usuário>" --top-k 8
2. Analise o JSON retornado (estrutura em references/schemas.md), extraia o campo _footer para uso posterior:
   • chunks: fragmentos originais mais relevantes (com arquivo de origem, título, heading, conteúdo, tags, pontuação)
   • concepts: array vazio (conceitos removidos)
   • sources: lista de arquivos encontrados (sem duplicatas)
   • max_score: maior pontuação BM25
   • _footer: texto fixo do rodapé
3. Use os resultados da busca para organizar a resposta, anexando o valor de _footer obtido no passo 2:
   • Use a terminologia própria do Benben Kingdom ("传说" (lendário), "集结" (reunir), "驻防" (defesa), "夯" (golpe forte), "白嫖" (grátis), "体力" (energia), "号角" (corneta), "试炼" (provação), "秘境" (masmorra), "四代" (quarta geração), "三代" (terceira geração)... NÃO traduza para linguagem genérica)
   • Responda como um veterano do jogo, dando conclusões e razões, sem usar modelos prontos
   • Se os resultados da busca contiverem dicas de "armadilhas" (como "nunca faça" ou "atenção"), inclua-as obrigatoriamente
4. Quando max_score for 0 ou o resultado estiver vazio, não invente respostas. Informe honestamente: "Não há conteúdo relacionado no banco de notas. Deseja adicionar um novo攻略?"

Fluxo de Inicialização (primeiro uso)

Passo 1 — Configurar o caminho do vault de conhecimento

python -m scripts.setup --set-vault /caminho/para/seu/vault

/caminho/para/seu/vault é o diretório onde você armazena seus arquivos markdown de攻略 do Benben Kingdom.

Passo 2 — Construir o índice

python -m scripts.index_vault

Escaneia todos os arquivos .md no diretório vault, divide em seções pelos títulos ## e gera ~/.benben-kingdom/index.json.

Uso subsequente: basta fazer perguntas diretamente, o índice já está pré-construído.

Fluxo de Atualização Incremental

A. Arquivo markdown local

python -m scripts.add_source --path <caminho absoluto>

B. URL de página web / WeChat

1. Use o skill wechat-article-pdf (ou outra ferramenta) para converter a URL em markdown e salvar em um arquivo temporário
2. Execute:

python -m scripts.add_source --path /tmp/benben-xxx.md \
  --origin-url <URL original> --title "<título do artigo>"

C. Texto colado diretamente

Escreva o texto em um arquivo markdown temporário e siga o fluxo A, usando --title para especificar o título.

Após cada atualização incremental, o índice é automaticamente reconstruído, sem ação adicional.

Referência Rápida de Scripts

Todos os scripts são executados a partir do diretório do skill com python -m scripts.<nome>:

Script	Uso	Parâmetros Principais
setup.py	Verificar dependências, inicializar	--check, --reset
index_vault.py	Construir índice JSON	--vault <caminho>
add_source.py	Adicionar/atualizar um único arquivo markdown e reconstruir índice	--path, --origin-url, --title
query.py	Busca por palavras-chave/BM25, retorna JSON	--question, --top-k

Princípios de Design

• Busca por palavras-chave é a única entrada: Todas as perguntas devem passar por query.py, nunca responda lendo arquivos markdown diretamente.
• Operações determinísticas ficam com scripts, compreensão linguística com o modelo: A construção do índice e a lógica de busca são claras e confiáveis; a organização da resposta fica a cargo do Claude.
• Não invente: Se a busca não encontrar nada, informe que não há conteúdo. As versões do jogo são atualizadas rapidamente; uma resposta errada é pior do que nenhuma.
• Use gírias de jogadores: Termos como "夯" (golpe forte), "白嫖" (grátis), "卡点" (ponto crítico), "上号子" (subir corneta), "进队伍" (entrar na equipe) devem ser usados diretamente, pois soam como conselhos de um veterano.

Documentos de Referência

• references/schemas.md — Esquema JSON do script / estrutura de tabela do banco de dados
• references/configuration.md — Explicação das opções de configuração
• references/troubleshooting.md — Erros comuns (arquivo de índice ausente, caminho de vault incorreto, etc.)