guanxiong/VibeSMS

¿Qué hace VibeSMS?

Conecta un agente de IA a un teléfono Android de propiedad del usuario y a su tarjeta SIM sin exponer toda la bandeja de entrada de SMS. Una sola VIBESMS_KEY le da al agente acceso únicamente a su número de teléfono asignado y admite cuatro acciones específicas:

• Verificar si el terminal Android está vinculado y en línea.
• Capturar un cursor de eventos antes de que un servicio externo envíe un mensaje.
• Esperar un nuevo código de verificación de 4 a 8 dígitos después de ese cursor.
• Leer eventos de SMS y llamadas entrantes aislados por clave.

El terminal Android carga los eventos mediante una credencial de dispositivo separada, por lo que la Clave del Agente no puede cargar eventos ni leer otro número. Usa el cliente incluido para llamadas API deterministas. Resuelve scripts/vibesms.py de forma relativa a este SKILL.md; no asumas que el directorio de trabajo actual contiene la habilidad.

Precondiciones

• Requiere VIBESMS_KEY en el entorno o en el almacén de secretos del agente.
• Usa VIBESMS_BASE_URL solo para una instancia autoalojada; su valor predeterminado es https://sms.shareapi.ai.
• Nunca le pidas al usuario que pegue una Clave en el chat, en argumentos de comandos, en código fuente o en registros.
• Nunca expongas la Clave en la salida. Si falta, pídele al usuario que configure el Secreto.

Recibir un código de verificación

1. Captura un cursor inmediatamente antes de activar el SMS externo:

   python3 <directorio-de-la-habilidad>/scripts/vibesms.py status
   

2. Lee el valor de cursor de la respuesta JSON.

3. Activa la acción autorizada por el usuario que envía el SMS.

4. Espera el primer código de 4 a 8 dígitos recibido después de ese cursor:

   python3 <directorio-de-la-habilidad>/scripts/vibesms.py wait-otp --after-id <cursor> --timeout 60
   

5. Usa el código solo para la tarea que el usuario autorizó. No lo conserves después de completarla.

Siempre captura el cursor primero. Sin él, un mensaje anterior podría confundirse con el nuevo código de verificación.

Verificar el estado del terminal

Ejecuta:

python3 <directorio-de-la-habilidad>/scripts/vibesms.py status

Si bound es falso, dile al usuario que la Clave no se ha emparejado con una SIM de Android. Si online es falso, explícale que los mensajes pueden llegar después de que el terminal se reconecte y reproduzca su cola fuera de línea.

Leer eventos de la bandeja de entrada

Ejecuta uno de:

python3 <directorio-de-la-habilidad>/scripts/vibesms.py inbox --after-id <cursor>
python3 <directorio-de-la-habilidad>/scripts/vibesms.py inbox --type sms --limit 20
python3 <directorio-de-la-habilidad>/scripts/vibesms.py inbox --type call --limit 20

Prefiere after-id para lecturas específicas de tareas. Devuelve solo los campos necesarios para la tarea del usuario; evita repetir contenido de mensajes o números de teléfono no relacionados.

Errores

• 401: la Clave no es válida, está deshabilitada o ha sido rotada. Pídele al usuario que actualice el Secreto.
• status=timeout: no llegó ningún OTP coincidente a tiempo. Verifica el estado del terminal y luego reintenta solo si el usuario aún desea esperar.
• Error de red/TLS: informa el endpoint y el error sin imprimir encabezados ni la Clave.

Lee references/api.md solo cuando se necesiten esquemas de endpoint sin procesar o detalles de integración autoalojada.