🎯 TikTok-Wettbewerbsanalyse
1. Fähigkeiten im Überblick
💡Wert auf einen Satz: Ein natürlicher Befehl ruft öffentliche TikTok-Video-/Autor-/Kommentardaten ab und gibt strukturiertes JSON aus – für Creator-Screening, Datenanalyse, Marktforschung, Stimmungsmonitoring, virale Themenfindung, Benchmark-Konten-Überwachung, Kommentaranalyse und Trendverfolgung. Kein manuelles Scrollen mehr nötig.
| Fähigkeit | Einstiegsskript | Erforderlicher Parameter | Rückgabe |
|---|---|---|---|
| Keyword-Suche | scripts/tiktok/search-cli.js | --keyword | Videoliste: Autor, Likes/Kommentare/Teilen/Favoriten, Tags, Play-URL |
| Creator-Videos | scripts/tiktok/post-cli.js | --url (Profil oder Benutzername) | Öffentliche Videoliste des Creators (sortierbar nach Datum/Beliebt) |
| Video-Kommentare | scripts/tiktok/comment-cli.js | --url (Video-Link oder ID) | Kommentartext, Verfasser, Likes, Antwortanzahl |
Zielgruppen
- 🎯 Marken – Trends nutzen für Branded Content
- 🏢 MCNs – Hochinteraktive potenzielle Creator finden
- ✍️ Content-Creator – Benchmark-Beispiele analysieren, Inspiration holen
- 📊 Content-Manager – Wochenberichte und Wettbewerbsanalysen
Voraussetzung: Das Skript muss im Stammverzeichnis des Skills ausgeführt werden und die Umgebungsvariable
GUAIKEI_API_TOKENmuss gesetzt sein. Fehlt sie, geben alle Befehle Exit-Code3underror_code=AUTH_REQUIREDzurück – in diesem Fall den Nutzer direkt auffordern, den Token zu konfigurieren, nicht wiederholen oder andere Parameter probieren.
2. Wann aufrufen / Wann nicht aufrufen
2.1 Sollte aufgerufen werden
- Der Nutzer möchte öffentliche TikTok-Inhalte (Videos/Bilder/Autoren/Kommentare/Trends) abrufen.
- Der Nutzer möchte virale Themen recherchieren, Wettbewerberkonten überwachen, Influencer filtern, Kommentarstimmungen analysieren, Content-Stile dekonstruieren.
- Der Nutzer hat ein TikTok-Keyword, einen Video-Link oder ein Creator-Profil angegeben und erwartet strukturierte Daten.
- Der Nutzer möchte die erhaltenen Daten anschließend zusammenfassen, vergleichen, sortieren, clustern oder in Berichten/Tabellen aufbereiten.
2.2 Sollte nicht aufgerufen werden
- Der Nutzer benötigt nur Text/Titel/Skripte, ohne TikTok-Daten abzufragen.
- Die Plattform ist nicht TikTok, sondern eine andere (Douyin, Xiaohongshu, Bilibili, Weibo, WeChat) → an das entsprechende Skill weiterleiten. Dieses Skill verarbeitet ausschließlich TikTok.
- Es werden Login-Status, private oder versteckte Daten verlangt → Nicht unterstützt.
- Es liegen sowohl ein Keyword als auch ein identifizierbarer Link vor, und das Ziel ist unklar → zuerst nachfragen, nicht raten.
2.3 Leistungsgrenzen (Ausdrücklich nicht abgedeckt)
Schreiboperationen wie Veröffentlichen, Liken, Kommentieren, Folgen, Direktnachrichten usw. werden nie unterstützt; es wird kein Konto angemeldet; keine privaten Felder wie Telefonnummern, Standorte oder DMs erfasst; der Agent trifft keine Marketingentscheidungen für den Nutzer – seine Aufgabe ist es, die Daten zu beschaffen, die Analyse obliegt einer höheren Ebene.
3. Aufruf-Routing (Erst prüfen, dann ausführen)
| Nutzerabsicht | Skript | Entscheidungs-Keywords (DE) |
|---|---|---|
| Nach Keywords suchen, bestimmte Inhalte oder Virales finden | search-cli | Suche / Keyword / viral / beliebt / Trend |
| Videos/Profil eines Creators/Influencers ansehen | post-cli | Creator / Influencer / Konto / Profil / Kanal |
| Kommentare zu einem bestimmten Video ansehen | comment-cli | Kommentar / Meinungen / Diskussion / Feedback |
3.1 Disambiguierungsregeln (Müssen beachtet werden)
- Steht nur „Video“ da, wird nicht automatisch
post-clizugeordnet.- Mit „Keyword“ und ohne „Kommentar“ →
search-cli(der Nutzer möchte solche Videos suchen). - Explizit „Kommentare / Meinungen zu diesem Video“ →
comment-cli. - Erst wenn „Profil / Konto / Creator / Kanal“ vorkommt →
post-cli.
- Mit „Keyword“ und ohne „Kommentar“ →
- Kommentare haben Vorrang vor Videos: Bei einem Link
/video/<id>und Frage nach Kommentaren →comment-cli; bei Frage nach „Videos dieser Person“ →post-cli(mit@username). - Nutzer gibt
/video/<id>-Link, fragt aber nach „Videoliste“ → Erst klären, ob die Videos des Autors oder die Kommentare zu diesem Video gemeint sind.
3.2 Parameter-Inferenzregeln
| Nutzerformulierung (DE) | Parameter |
|---|---|
| Relevanz / Standard | --sort 0 (Suche) |
| Beliebteste / Meiste Likes / Viral / Trend | --sort 1 (Suche) |
| Neueste / Zuletzt veröffentlicht / Chronologisch absteigend | --sort 0 (Videos) |
| Beliebteste Videos | --sort 1 (Videos) |
| Letzte 24 Stunden / Heute | --time 1 |
| Letzte Woche / 7 Tage | --time 7 |
| Letzter Monat / Drei Monate / Sechs Monate | --time 30 / 90 / 180 |
| N Einträge / Top N / N Stück | --limit N |
Standardwerte: sort=0, time=0, limit=10.
⚠️ Die
--sort-Parameter für Suche und Videos nicht verwechseln: Ersterer bedeutet „Relevanz / Meiste Likes“, letzterer „Neueste / Beliebteste“.
Wird ein Parameter auf einen ungültigen Wert zurückgesetzt, erscheint dies im warnings-Array der Ausgabe. Diese Warnungen müssen dem Nutzer unverändert angezeigt werden – nicht so tun, als ob der ursprüngliche Wert gegolten hätte.
4. Ausführungsmodus
Vollständige Parameterdokumentation siehe references/options.md; feldgenaue Schemas siehe 6 JSON-Schema-Dateien (draft-07) im
assets/-Ordner.
# Keyword-Suche
node scripts/tiktok/search-cli.js --keyword "KI" --sort 1 --limit 20
node scripts/tiktok/search-cli.js --keyword "KI Model" --time 7 --limit 20
# Creator-Videos
node scripts/tiktok/post-cli.js --url "https://www.tiktok.com/@username" --limit 30
node scripts/tiktok/post-cli.js --url "https://www.tiktok.com/@username" --sort 1 --limit 30
# Video-Kommentare
node scripts/tiktok/comment-cli.js --url "https://www.tiktok.com/@username/video/1234567890123456789" --limit 40
Akzeptierte Eingabeformen
- Creator:
https://www.tiktok.com/@username, Link mit Parametern wiehttps://www.tiktok.com/@username?lang=en, oder direktauthor_sec_uid - Video:
https://www.tiktok.com/@username/video/<id>, Kurzlink, oder direkte Video-<id>
Ausführungsdisziplin
- Nur stdout als maschinenlesbare Ausgabe behandeln (reines JSON); Banner, Fortschritt, Fehlerlogs erscheinen auf stderr – nicht vermischen.
- Einmaliges
--limitsollte ≤ 1000 sein. - Nicht bei einem leeren Ergebnis automatisch die Bedingungen lockern und wiederholen: Das leere Ergebnis dem Nutzer melden; der Nutzer entscheidet, ob er das Keyword ändern oder
--timeerweitern möchte.
5. Ausgabe-Contract (Pflichtlektüre für KI-Analyse)
Alle Einstiegspunkte geben denselben Umschlag zurück, Erfolg und Fehler haben dieselbe Struktur:
{
"status": "success | empty | error",
"error_code": "OK | NO_MATCH | AUTH_REQUIRED | INVALID_KEYWORD | ...",
"message": "Lesbare Erklärung",
"timestamp": "2026-09-16 21:00:00",
"request": {
"command": "search",
"keyword": "KI",
"sort": 1,
"time": 0,
"limit": 20
},
"metadata": {
"skill_version": "1.0.0",
"skill_name": "tiktok-creator-videos",
"runtime_version": "22.22.2",
"execution_time": 8421
},
"results": [],
"warnings": ["Wert 99999 ungültig, auf 10 zurückgesetzt"]
}
5.1 status-Bedeutung
| status | Bedeutung | results | Vorgehen |
|---|---|---|---|
success | Daten erfolgreich abgerufen | Nicht-leeres Array | Direkt analysieren |
empty | Anfrage erfolgreich, aber keine Daten | null | Als gültiges Ergebnis betrachten, Nutzer informieren, nicht als Fehler behandeln |
error | Anfrage fehlgeschlagen | null | Je nach error_code behandeln, keine Daten erfinden |
5.2 Exit-Codes
| Exit-Code | Bedeutung | Agenten-Verhalten |
|---|---|---|
0 | Erfolg (success oder empty) | Mit Analyse fortfahren |
1 | Laufzeitfehler (Netzwerk/Timeout/API-Fehler/ungültiger Parameter) | message anzeigen, Nutzer nach Parameteränderung für Wiederholung fragen |
3 | AUTH_REQUIRED: Token fehlt oder ungültiges Format | Sofort anhalten, Nutzer auffordern GUAIKEI_API_TOKEN zu setzen, keine Wiederholung |
5.3 Fehlercode-Behandlung
| error_code | Vorgehen |
|---|---|
AUTH_REQUIRED | Anhalten und Token-Konfiguration vorschlagen. Keine Wiederholung, keine Parameterumgehung |
INVALID_KEYWORD | Hinweis: Keyword muss 2–100 Zeichen lang sein, darf keine < > " ' & oder http-Links enthalten |
NO_MATCH | Gültiges leeres Ergebnis; neues Keyword oder größeres --time vorschlagen |
NETWORK_ERROR | Eingebaute Wiederholung bereits erfolgt; bei erneutem Fehler Netzwerk prüfen, max. 1 manuelle Wiederholung |
TIMEOUT_ERROR | Eingebaute Wiederholung bereits erfolgt; bei erneutem Fehler --limit reduzieren und wiederholen |
| Andere (Server-Fehlercodes) | error_code + message unverändert anzeigen, keine eigene Interpretation |
5.4 warnings müssen angezeigt werden
Wenn ein übergebener Parameter ungültig war und automatisch zurückgesetzt wurde (z.B. --sort 9, --limit 99999), enthält das warnings-Array eine Erklärung, „welcher Parameter auf welchen Wert geändert wurde“. Dies muss dem Nutzer unverändert mitgeteilt werden – nicht so tun, als ob der ursprüngliche Wert gegolten hätte.
5.5 Verbotene Handlungen
- ❌ Keine Daten erfinden, ergänzen oder aus dem Gedächtnis auffüllen.
- ❌ Nach Erhalt von
AUTH_REQUIREDnicht wiederholen, kein anderes Skript oder andere Parameter verwenden. - ❌
emptynicht mit „Inhalt existiert nicht“ gleichsetzen (es heißt nicht, dass die API kaputt ist). - ❌ Suchbedingungen nicht ohne Zustimmung des Nutzers automatisch lockern.
6. Empfehlungen zur Nutzung der Ergebnisse (Verbesserung der Ausgabequalität)
Nach Erhalt von results die Ausgabe nach dem ursprünglichen Ziel des Nutzers strukturieren, nicht das rohe JSON ausgeben:
- Themenrecherche → Top N nach
digg_countabsteigend, Titel-Muster / Tags / Längenverteilung zusammenfassen - Wettbewerber-Monitoring → Veröffentlichungsrhythmus nach
create_timeordnen, Update-Frequenz und Viralitätsanteil berechnen - Kommentar-Einblicke → Hoch-votierte Kommentare nach
digg_countclustern, positive/negative Stimmungsanteile ausgeben - Influencer-Screening →
author_nickname, durchschnittliche Interaktion, Veröffentlichungshäufigkeit kreuzreferenzieren, Kandidatenliste erstellen - Archivierung → Bei jeder Ausführung wird automatisch eine Logdatei geschrieben; der Pfad wird in stderr mit „Gespeichert unter …“ ausgegeben
7. Sicherheit und Compliance (Trust)
- Nur lesend: Kein TikTok-Konto-Login, keine Schreiboperationen (Veröffentlichen, Liken, Kommentieren, Folgen, DM) – kein Risiko einer Kontosperrung.
- Minimale Berechtigungen: Nur eine Umgebungsvariable (
GUAIKEI_API_TOKEN) wird benötigt; keine anderen lokalen Dateien gelesen; keine Pfade außerhalb des Skill-Verzeichnisses beschrieben (Logs ins System-Temp-Verzeichnis). - Credential-Schutz: Token wird nur aus Umgebungsvariablen gelesen, nie in stdout, Logs oder Fehlermeldungen geschrieben.
- Datenweitergabe (bitte beachten): Bei Aufruf werden an
www.guaikei.comgesendet: Ihr API Token, das Such-Keyword oder die Ziel-URL/ID, sowie Skill-Name und Node-Version. Darüber hinaus werden keine lokalen Informationen erfasst. - Daten-Compliance: Es werden nur öffentlich sichtbare TikTok-Daten abgerufen (Nickname, öffentliche Videos, öffentliche Kommentare). Keine privaten Felder wie Telefonnummern, Standorte oder DMs. Die Daten sind nur für die persönliche oder teaminterne Analyse bestimmt; vor externer Veröffentlichung oder kommerzieller Nutzung bitte die erforderlichen Genehmigungen einholen und Benutzernamen ggf. anonymisieren.
- Keine Drittanbieter-Abhängigkeiten: Verwendet nur Node.js-Built-in-Module (
https/fs/path/os/querystring), keine npm-Abhängigkeiten, kein Remote-Script-Loading, keineval/child_process.
8. Häufige Fragen
| Phänomen | Ursache und Lösung |
|---|---|
| Exit-Code 3 / AUTH_REQUIRED | Token nicht gesetzt oder Format falsch (muss 16–256 Zeichen alphanumerisch plus Unterstrich/Bindestrich sein) |
| Suchergebnis leer | Allgemeineres Keyword verwenden, oder --time 0 um Zeitfenster zu öffnen; empty ist normales Ergebnis, kein Fehler |
Weniger Ergebnisse als --limit | Server hat nicht mehr Daten, oder das Limit wurde gekappt; auf ≤1000 reduzieren und schrittweise abrufen |
| Ständige Timeouts | --limit reduzieren und wiederholen; Skript hat bereits exponentielles Backoff-Retry eingebaut |
| „Beliebteste Videos“ gewünscht, aber chronologisch absteigend erhalten | Bei post-cli muss --sort 1 verwendet werden |
| Parameter scheinen nicht zu wirken / Sortierung anders als erwartet | Auf warnings in der Ausgabe prüfen; ungültige Parameter werden stillschweigend auf Standardwerte zurückgesetzt |
| Wo finde ich die Logdatei? | Siehe stderr-Zeile „Gespeichert unter …“ (System-Temp-Verzeichnis tiktok-guaikei/logs/<Datum>/) |
9. Umgebung und Support
- Umgebung: Node.js ≥ 16.14.0, Windows / macOS / Linux;
GUAIKEI_API_TOKENerforderlich. - Webseite: TikTok-Wettbewerbsanalyse Webseite (Token selbstständig aktivieren, Nutzung und API-Referenz einsehen).
- Änderungsprotokoll: references/changelog.md