guanxiong/VibeSMS

Que fait VibeSMS ?

Connectez un agent IA à un téléphone Android et une carte SIM appartenant à l'utilisateur sans exposer l'intégralité de la boîte de réception SMS. Une seule VIBESMS_KEY donne à l'agent un accès limité à son numéro de téléphone attribué et prend en charge quatre actions ciblées :

• Vérifier si le terminal Android est lié et en ligne.
• Capturer un curseur d'événement avant qu'un service externe n'envoie un message.
• Attendre un code de vérification frais de 4 à 8 chiffres après ce curseur.
• Lire les événements SMS et d'appels entrants isolés par clé.

Le terminal Android télécharge les événements via un identifiant d'appareil distinct, de sorte que la Clé Agent ne peut ni télécharger d'événements ni lire un autre numéro. Utilisez le client fourni pour des appels API déterministes. Résolvez scripts/vibesms.py par rapport à ce fichier SKILL.md ; ne supposez pas que le répertoire de travail courant contient le skill.

Préconditions

• Exiger VIBESMS_KEY dans l'environnement ou le magasin de Secrets de l'agent.
• Utiliser VIBESMS_BASE_URL uniquement pour une instance auto-hébergée ; la valeur par défaut est https://sms.shareapi.ai.
• Ne jamais demander à l'utilisateur de coller une Clé dans le chat, les arguments de commande, le code source ou les journaux.
• Ne jamais exposer la Clé dans la sortie. Si elle est manquante, demandez à l'utilisateur de configurer le Secret.

Recevoir un code de vérification

1. Capturez un curseur immédiatement avant de déclencher le SMS externe :

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

2. Lisez la valeur cursor dans la réponse JSON.

3. Déclenchez l'action autorisée par l'utilisateur qui envoie le SMS.

4. Attendez le premier code à 4–8 chiffres reçu après ce curseur :

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

5. Utilisez le code uniquement pour la tâche autorisée par l'utilisateur. Ne le conservez pas après la fin de la tâche.

Capturez toujours le curseur en premier. Sans cela, un ancien message pourrait être confondu avec le nouveau code de vérification.

Vérifier l'état du terminal

Exécutez :

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

Si bound est faux, dites à l'utilisateur que la Clé n'a pas été associée à une carte SIM Android. Si online est faux, expliquez que les messages peuvent quand même arriver après la reconnexion du terminal et la relecture de sa file d'attente hors ligne.

Lire les événements de la boîte de réception

Exécutez l'une des commandes suivantes :

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

Préférez after-id pour les lectures spécifiques à une tâche. Renvoyez uniquement les champs nécessaires à la tâche de l'utilisateur ; évitez de répéter le contenu des messages ou les numéros de téléphone non pertinents.

Erreurs

• 401 : la Clé est invalide, désactivée ou a été changée. Demandez à l'utilisateur de mettre à jour le Secret.
• status=timeout : aucun OTP correspondant n'est arrivé dans les délais. Vérifiez l'état du terminal, puis réessayez uniquement si l'utilisateur souhaite encore attendre.
• Échec réseau/TLS : signalez le point de terminaison et l'échec sans afficher les en-têtes ni la Clé.

Consultez references/api.md uniquement lorsque les schémas bruts des points de terminaison ou les détails d'intégration auto-hébergée sont nécessaires.