Arquitetura e criação de ferramentas
O Projeto Hikari mantém Discord e WhatsApp em processos e repositórios independentes, sem acoplar rotas web administrativas nem misturar sessões de runtime.
1. Isolamento entre processos
Seção intitulada “1. Isolamento entre processos”- Discord (
Hikari): armazena estado persistente emsrc/data/ai_database.json, permissões por servidor emserver_tools.jsone descrições visuais emimage_descriptions.json. - WhatsApp (
HikariZap): isola sessão Web em.whatsapp-auth/com trava.lock, saúde do pool emai-health.jsone vínculosPN <-> LIDemsrc/data/zap/identities.json. - Quedas de conexão, troca de QR Code ou manutenção em uma plataforma não interferem na outra.
2. Portal público estático
Seção intitulada “2. Portal público estático”Este site é compilado como páginas estáticas pelo Astro e Starlight, sem backend conectado às máquinas que executam os bots:
- O Explorador de comandos e o Gerador de config rodam integralmente no navegador.
- Chaves privadas e tokens nunca trafegam pela página; o gerador exporta credenciais apenas como placeholders para edição local no servidor.
- Toda administração em produção ocorre direto pelas plataformas (
/config_servidor,/ia_ferramentas,/config_criadorno Discord e>pausar,>retomar,>filano WhatsApp).
3. Como criar e depurar novas ferramentas
Seção intitulada “3. Como criar e depurar novas ferramentas”Os dois projetos declaram assinaturas em JSON Schema no arquivo src/data/mcp_tools.json e conectam a implementação ao loop do llmHandler.js:
- Declare o esquema adicionando o novo objeto
functiondentro desrc/data/mcp_tools.jsoncomname,descriptionclara eparameters(requirede tipos). - Implemente o handler dentro do fluxo de
src/handlers/llmHandler.js(processQueue()) encapsulado em blocotry-catchpara impedir que falhas de APIs terceiras congelem o processo. - Humanize o retorno: o fluxo dispara chamada recursiva (
isInternalComment: true) após retornar o JSON da ferramenta para a IA formular uma resposta natural, e imprime o"thought"no console durante depuração. - Atenção a permissões e JSON: garanta que o bot possui as permissões necessárias no servidor caso a ferramenta manipule canais ou mensagens, e valide saídas estruturadas de modelos menores para evitar vazamento de objetos crus no texto.
- Declare a ferramenta em
src/data/mcp_tools.jsonseguindo JSON Schema padrão OpenAI/Gemini (enviado automaticamente comtool_choice: "auto"):
{ "type": "function", "function": { "name": "consultar_cep", "description": "Consulta endereço completo a partir de um CEP brasileiro de 8 dígitos.", "parameters": { "type": "object", "properties": { "cep": { "type": "string", "description": "CEP com 8 dígitos." } }, "required": ["cep"] } }}- Implemente a ação no
switchdesrc/whatsapp/tools.jstratando falhas externas com retorno estruturado de erro:
case 'consultar_cep': { const { data } = await axios.get(`https://viacep.com.br/ws/${encodeURIComponent(args.cep)}/json/`); if (data.erro) return { error: 'CEP não encontrado.' }; return { logradouro: data.logradouro, bairro: data.bairro, cidade: data.localidade, uf: data.uf };}- Depure e teste: execute com
LOG_LEVEL=debugpara acompanhar pensamentos intermediários, argumentos e latência das chamadas; adicione cobertura emtests/zap/e valide executandonpm run validate:toolsenpm test.
