guanxiong/VibeSMS

O que VibeSMS faz?

Conecte um agente de IA a um telefone Android e SIM de propriedade do usuário sem expor toda a caixa de entrada de SMS. Uma única VIBESMS_KEY concede ao agente acesso apenas ao seu número de telefone designado e suporta quatro ações focadas:

• Verificar se o terminal Android está vinculado e online.
• Capturar um cursor de evento antes que um serviço externo envie uma mensagem.
• Aguardar um novo código de verificação de 4 a 8 dígitos após esse cursor.
• Ler eventos de SMS e chamadas recebidas isolados por chave.

O terminal Android faz upload usando uma credencial de dispositivo separada, portanto a Chave do Agente não pode fazer upload de eventos ou ler outro número. Use o cliente integrado para chamadas de API determinísticas. Resolva scripts/vibesms.py em relação a este SKILL.md; não presuma que o diretório de trabalho atual contém a habilidade.

Pré-condições

• Exija VIBESMS_KEY no ambiente ou no armazenamento de Secrets do agente.
• Use VIBESMS_BASE_URL apenas para uma instância auto-hospedada; o padrão é https://sms.shareapi.ai.
• Nunca peça ao usuário para colar uma Chave no chat, argumentos de comando, código-fonte ou logs.
• Nunca exponha a Chave na saída. Se estiver faltando, peça ao usuário para configurar o Secret.

Receber um código de verificação

1. Capture um cursor imediatamente antes de acionar o SMS externo:

   python3 <skill-directory>/scripts/vibesms.py status
   

2. Leia o valor cursor da resposta JSON.

3. Acione a ação autorizada pelo usuário que envia o SMS.

4. Aguarde o primeiro código de 4 a 8 dígitos recebido após esse cursor:

   python3 <skill-directory>/scripts/vibesms.py wait-otp --after-id <cursor> --timeout 60
   

5. Use o código apenas para a tarefa que o usuário autorizou. Não o persista após a conclusão.

Sempre capture o cursor primeiro. Sem ele, uma mensagem mais antiga pode ser confundida com o novo código de verificação.

Verificar status do terminal

Execute:

python3 <skill-directory>/scripts/vibesms.py status

Se bound for falso, informe ao usuário que a Chave não foi pareada com um SIM Android. Se online for falso, explique que as mensagens ainda podem chegar após o terminal reconectar e reproduzir sua fila offline.

Ler eventos da caixa de entrada

Execute um dos comandos:

python3 <skill-directory>/scripts/vibesms.py inbox --after-id <cursor>
python3 <skill-directory>/scripts/vibesms.py inbox --type sms --limit 20
python3 <skill-directory>/scripts/vibesms.py inbox --type call --limit 20

Prefira after-id para leituras específicas de tarefa. Retorne apenas os campos necessários para a tarefa do usuário; evite repetir conteúdo de mensagens ou números de telefone não relacionados.

Erros

• 401: a Chave é inválida, desabilitada ou rotacionada. Peça ao usuário para atualizar o Secret.
• status=timeout: nenhum OTP correspondente chegou a tempo. Verifique o status do terminal e repita apenas se o usuário ainda quiser aguardar.
• Falha de rede/TLS: informe o endpoint e a falha sem imprimir cabeçalhos ou a Chave.

Leia references/api.md apenas quando forem necessários esquemas de endpoint brutos ou detalhes de integração auto-hospedada.