{
  "marca": "kk-sa",
  "nome": "conectores-humano",
  "galhos": [
    { "id": "1", "nome": "Guia humano para criar conectores QQ" },
    { "id": "1.1", "nome": "Este guia é para programadores iniciantes. A ideia é criar um conector em passos pequenos, testando uma parte por vez." },
    { "id": "1.2", "nome": "Um conector QQ recebe uma mensagem JSON, executa uma tarefa e grava uma resposta JSON padronizada." },
    { "id": "2", "nome": "Arquivos envolvidos" },
    { "id": "2.1", "nome": "escuta/catalogo-mensagens/<codigo>.json: define o formato da mensagem que a API aceita." },
    { "id": "2.2", "nome": "conectores/<nome-do-conector>: programa executável que processa a mensagem." },
    { "id": "2.3", "nome": "escuta/api/conect.json: liga o código da mensagem ao caminho lógico do conector." },
    { "id": "2.4", "nome": "ambiente-externo/envio: opcional, usado para simular ou implementar quem envia mensagens para o QQ." },
    { "id": "2.5", "nome": "ambiente-externo/resposta: opcional, usado para receber resposta por callback quando endresposta for informado." },
    { "id": "2.6", "nome": "/etc/secretos/tokens-servicos-conectores/<arquivo>: necessário quando o conector acessa serviço externo autenticado." },
    { "id": "2.6.1", "nome": "Nunca grave tokens, senhas ou chaves dentro do projeto, do catálogo, das mensagens ou das respostas." },
    { "id": "3", "nome": "Passo 1: escolher um objetivo pequeno" },
    { "id": "3.1", "nome": "Defina uma ação simples em uma frase, por exemplo: consultar CEP, enviar e-mail, buscar cliente por CPF ou listar catálogo." },
    { "id": "3.2", "nome": "Escolha um nome curto para o conector, por exemplo: cep, email, cliente ou catalogo." },
    { "id": "3.3", "nome": "Escolha um código livre para a mensagem, por exemplo: 004.json." },
    { "id": "4", "nome": "Passo 2: criar o catálogo da mensagem" },
    { "id": "4.1", "nome": "Crie escuta/catalogo-mensagens/<codigo>.json." },
    { "id": "4.2", "nome": "Preencha id, ativa, entrada, saida e, se quiser callback HTTP, endresposta." },
    { "id": "4.3", "nome": "Use tipos simples no início: texto, url, true ou false." },
    { "id": "4.4", "nome": "Exemplo de entrada: campo cep com tipo texto." },
    { "id": "4.5", "nome": "Exemplo de saída: objeto endereco_completo com cep, logradouro, cidade e uf." },
    { "id": "5", "nome": "Passo 3: mapear a mensagem em escuta/api/conect.json" },
    { "id": "5.1", "nome": "Adicione o código da mensagem na árvore do conect.json." },
    { "id": "5.2", "nome": "O caminho formado pela árvore vira o destinatário da mensagem." },
    { "id": "5.3", "nome": "Se o destino terminar em catalogo, o QQ procurará um executável chamado catalogo, inclusive em conectores/catalogo." },
    { "id": "5.4", "nome": "Para iniciantes: copie o padrão já existente e troque apenas o nome e o código da nova mensagem." },
    { "id": "6", "nome": "Passo 4: criar o handler em conectores/<nome-do-conector>" },
    { "id": "6.1", "nome": "O handler pode ser feito em qualquer linguagem executável no servidor, como PHP, Python, Bash ou Node." },
    { "id": "6.2", "nome": "O arquivo deve ter permissão de execução." },
    { "id": "6.3", "nome": "O comando obrigatório é: conectores/<nome> --ler-mensagem <arquivo-json>." },
    { "id": "6.4", "nome": "Também implemente --help para explicar o uso." },
    { "id": "6.5", "nome": "Também implemente --sa para mostrar ou referenciar a árvore semântica do conector." },
    { "id": "6.6", "nome": "Comece validando apenas o básico: se o arquivo existe, se é JSON e se os campos esperados existem." },
    { "id": "6.7", "nome": "Depois execute a ação real do conector." },
    { "id": "7", "nome": "Passo 5: gerar a resposta padronizada" },
    { "id": "7.1", "nome": "A resposta deve ser JSON." },
    { "id": "7.2", "nome": "Inclua status: ok ou erro." },
    { "id": "7.3", "nome": "Inclua conector: nome do conector executado." },
    { "id": "7.4", "nome": "Inclua mensagem: código da mensagem processada." },
    { "id": "7.5", "nome": "Inclua id: o mesmo id recebido na mensagem." },
    { "id": "7.6", "nome": "Inclua timestamp_resposta em UTC." },
    { "id": "7.7", "nome": "Inclua os campos de saída definidos no catálogo." },
    { "id": "7.8", "nome": "Grave em escuta/espaco/respostas/<id>.json usando gravação atômica: escreva .tmp e depois renomeie para .json." },
    { "id": "8", "nome": "Passo 6: enviar callback se endresposta existir" },
    { "id": "8.1", "nome": "Se a mensagem recebida tiver endresposta preenchido, envie a resposta por HTTP POST." },
    { "id": "8.2", "nome": "Use Content-Type application/json." },
    { "id": "8.3", "nome": "Registre na resposta o resultado do envio em envio_resposta." },
    { "id": "8.4", "nome": "Se não houver endresposta, apenas grave a resposta local." },
    { "id": "9", "nome": "Passo 7: guardar segredos com segurança" },
    { "id": "9.1", "nome": "Se o conector acessar Gmail, APIs pagas, CRMs, ERPs ou outro serviço autenticado, crie um arquivo de segredo em /etc/secretos/tokens-servicos-conectores." },
    { "id": "9.2", "nome": "O conector deve ler o segredo desse local protegido." },
    { "id": "9.3", "nome": "Não coloque segredo no código-fonte. Isso evita vazamentos acidentais." },
    { "id": "9.4", "nome": "Se estiver começando, peça ajuda apenas para configurar permissões; o restante do conector continua simples." },
    { "id": "10", "nome": "Passo 8: testar devagar" },
    { "id": "10.1", "nome": "Primeiro rode o conector manualmente com --help." },
    { "id": "10.2", "nome": "Depois rode com --sa e confirme que ele apresenta sua árvore semântica." },
    { "id": "10.3", "nome": "Depois teste com um arquivo de mensagem JSON simples." },
    { "id": "10.4", "nome": "Por fim, envie uma requisição POST para public/api.php usando o código da mensagem." },
    { "id": "10.5", "nome": "Confira se apareceu um arquivo de resposta em escuta/espaco/respostas." },
    { "id": "10.6", "nome": "Se algo falhar, verifique escuta/espaco/erro e escuta/.runtime/escuta.log." },
    { "id": "11", "nome": "Checklist final" },
    { "id": "11.1", "nome": "Catálogo criado em escuta/catalogo-mensagens/<codigo>.json." },
    { "id": "11.2", "nome": "Mensagem marcada como ativa: true." },
    { "id": "11.3", "nome": "Destino mapeado em escuta/api/conect.json." },
    { "id": "11.4", "nome": "Handler criado em conectores/<nome-do-conector>." },
    { "id": "11.5", "nome": "Handler com permissão executável." },
    { "id": "11.6", "nome": "Handler aceita --ler-mensagem, --help e --sa." },
    { "id": "11.7", "nome": "Resposta local gravada em escuta/espaco/respostas." },
    { "id": "11.8", "nome": "Callback testado quando endresposta for usado." },
    { "id": "11.9", "nome": "Segredos salvos somente em /etc/secretos/tokens-servicos-conectores quando houver autenticação externa." },
    { "id": "12", "nome": "Mensagem de confiança" },
    { "id": "12.1", "nome": "Não tente fazer tudo perfeito na primeira versão. Um conector bom nasce pequeno: primeiro lê, depois valida, depois responde, depois integra." },
    { "id": "12.2", "nome": "Se cada passo funcionar sozinho, o conjunto fica fácil de entender e manter." }
  ],
  "recolhidos": [
  ]
}