guanxiong/VibeSMS

Was macht VibeSMS?

Verbinde einen KI-Agenten mit einem benutzereigenen Android-Handy und einer SIM-Karte, ohne das gesamte SMS-Postfach offenzulegen. Ein einzelner VIBESMS_KEY gibt dem Agenten Zugriff nur auf seine zugewiesene Telefonnummer und unterstützt vier gezielte Aktionen:

• Überprüfen, ob das Android-Endgerät gebunden und online ist.
• Erfassen eines Ereignis-Cursors, bevor ein externer Dienst eine Nachricht sendet.
• Warten auf einen frischen 4–8-stelligen Verifikationscode nach diesem Cursor.
• Lesen von schlüsselisolierten SMS- und eingehenden Anrufereignissen.

Das Android-Endgerät lädt Ereignisse über separate Geräte-Anmeldedaten hoch, sodass der Agentenschlüssel keine Ereignisse hochladen oder eine andere Nummer lesen kann. Verwende den mitgelieferten Client für deterministische API-Aufrufe. Löse scripts/vibesms.py relativ zu dieser SKILL.md auf; nimm nicht an, dass das aktuelle Arbeitsverzeichnis den Skill enthält.

Vorbedingungen

• VIBESMS_KEY muss in der Umgebung oder im Secret-Speicher des Agenten vorhanden sein.
• VIBESMS_BASE_URL wird nur für eine selbst gehostete Instanz verwendet; standardmäßig ist es https://sms.shareapi.ai.
• Fordere den Benutzer niemals auf, einen Schlüssel in den Chat, in Befehlsargumente, in Quellcode oder in Logs einzufügen.
• Gib den Schlüssel niemals in der Ausgabe preis. Fehlt er, bitte den Benutzer, das Secret zu konfigurieren.

Empfangen eines Verifikationscodes

1. Erfasse sofort einen Cursor, bevor die externe SMS ausgelöst wird:

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

2. Lies den cursor-Wert aus der JSON-Antwort.

3. Löse die vom Benutzer autorisierte Aktion aus, die die SMS sendet.

4. Warte auf den ersten 4–8-stelligen Code, der nach diesem Cursor empfangen wurde:

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

5. Verwende den Code nur für die vom Benutzer autorisierte Aufgabe. Speichere ihn nicht nach Abschluss.

Erfasse immer zuerst den Cursor. Ohne ihn könnte eine ältere Nachricht fälschlicherweise als neuer Verifikationscode angesehen werden.

Endgerätestatus überprüfen

Führe folgenden Befehl aus:

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

Wenn bound false ist, teile dem Benutzer mit, dass der Schlüssel noch nicht mit einer Android-SIM gekoppelt wurde. Wenn online false ist, erkläre, dass Nachrichten möglicherweise noch ankommen, nachdem das Endgerät wieder verbunden ist und seine Offline-Warteschlange abspielt.

Posteingangsereignisse lesen

Führe einen der folgenden Befehle aus:

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

Bevorzuge after-id für aufgabenspezifische Lesevorgänge. Gib nur die Felder zurück, die für die Aufgabe des Benutzers erforderlich sind; vermeide die Wiederholung von nicht zusammenhängendem Nachrichteninhalt oder Telefonnummern.

Fehler

• 401: Der Schlüssel ist ungültig, deaktiviert oder wurde rotiert. Bitte den Benutzer, das Secret zu aktualisieren.
• status=timeout: Es ist kein passender OTP rechtzeitig eingetroffen. Überprüfe den Endgerätestatus und wiederhole den Vorgang nur, wenn der Benutzer noch warten möchte.
• Netzwerk-/TLS-Fehler: Melde den Endpunkt und den Fehler, ohne Header oder den Schlüssel auszudrucken.

Lies references/api.md nur, wenn rohe Endpunktschemata oder Details zur Selbsthosting-Integration benötigt werden.