🎯 Analyse Concurrentielle TikTok et Comparaison de Marques
1. Aperçu des Capacités
💡Valeur en une phrase : Une instruction orale pour obtenir les données publiques des vidéos/auteurs/commentaires TikTok, directement en JSON structuré — pour le recrutement d'influenceurs, l'analyse de données, les études de marché, la surveillance de l'opinion, la sélection de sujets viraux, le suivi de comptes de référence, l'analyse des commentaires et la détection des tendances, sans avoir à parcourir TikTok manuellement.
| Capacité | Script d'entrée | Paramètre obligatoire | Retour |
|---|---|---|---|
| Recherche par mot-clé | scripts/tiktok/search-cli.js | --keyword | Liste des publications : auteur, mentions J'aime/commentaires/partages/sauvegardes, hashtags, URL |
| Publications d'un créateur | scripts/tiktok/post-cli.js | --url (profil ou nom d'utilisateur) | Liste des publications publiques du créateur (tri par date/popularité) |
| Commentaires d'une vidéo | scripts/tiktok/comment-cli.js | --url (lien vidéo ou ID) | Texte du commentaire, auteur, nombre de J'aime, nombre de réponses |
Public cible
- 🎯 Marques — Surf sur les tendances pour créer du contenu engageant
- 🏢 Agences MCN — Découverte de comptes à fort potentiel d'engagement
- ✍️ Créateurs de contenu — Recherche de références et inspiration créative
- 📊 Community managers — Sélection de sujets pour les rapports hebdomadaires et analyse concurrentielle
Prérequis : Doit être exécuté depuis le répertoire racine de la compétence, et la variable d'environnement
GUAIKEI_API_TOKENdoit être configurée. Sinon, toutes les commandes retournent le code de sortie3eterror_code=AUTH_REQUIRED– dans ce cas, indiquez directement à l'utilisateur de configurer le token, sans réessayer ni modifier les paramètres.
2. Quand invoquer / Quand ne pas invoquer
2.1 Quand invoquer
- L'utilisateur souhaite consulter du contenu public TikTok (vidéos/images/auteurs/commentaires/tendances).
- L'utilisateur souhaite faire une étude de sujets viraux, une surveillance de comptes concurrents, un recrutement d'influenceurs, une analyse des commentaires, un décorticage de styles de contenu.
- L'utilisateur a déjà fourni un mot-clé TikTok, un lien vidéo ou un lien de profil de créateur, et souhaite obtenir des données structurées.
- Après avoir obtenu les données, l'utilisateur souhaite effectuer des résumés, des comparaisons, des tris, des regroupements ou générer des rapports/tableaux.
2.2 Quand ne pas invoquer
- L'utilisateur ne demande que du texte/un titre/un script, sans besoin de données TikTok.
- La plateforme n'est pas TikTok, mais une autre (Douyin, Xiaohongshu, Bilibili, Weibo, WeChat Official Account) → rediriger vers la compétence correspondante. Cette compétence ne traite que TikTok.
- Demande de données nécessitant une connexion, des données privées ou masquées → non supporté.
- L'utilisateur fournit à la fois un mot-clé et un lien identifiable, mais l'objectif n'est pas clair → demander d'abord une clarification, ne pas deviner.
2.3 Limites des capacités (explicitement non fait)
Toute opération d'écriture (publier, liker, commenter, suivre, envoyer un message privé) n'est pas supportée ; aucune connexion à un compte TikTok ; aucune collecte de numéros de téléphone, localisation, messages privés ou autres données privées ; aucune décision marketing pour l'utilisateur – le rôle est de récupérer les données, l'analyse est laissée à un niveau supérieur.
3. Routage des appels (d'abord juger, puis exécuter)
| Intention de l'utilisateur | Script | Mots-clés de décision |
|---|---|---|
| Rechercher un mot-clé, un type de contenu, un contenu viral | search-cli | rechercher / trouver / mot-clé / viral / le plus populaire |
| Voir les publications, le profil, les derniers posts d'un créateur/influenceur | post-cli | publications / profil / compte / créateur / influenceur / KOL |
| Voir les commentaires d'une vidéo | comment-cli | commentaires / avis / opinions dans les commentaires |
3.1 Règles de désambiguïsation (à respecter impérativement)
- Le mot "vidéo" seul ne doit pas être attribué par défaut à
post-cli.- S'il y a un "mot-clé" et pas de "commentaire" →
search-cli(l'utilisateur veut chercher ce type de vidéos). - S'il y a "les commentaires / les avis de cette vidéo" →
comment-cli. - Seulement s'il y a "publications / profil / compte / créateur / influenceur" →
post-cli.
- S'il y a un "mot-clé" et pas de "commentaire" →
- Les commentaires ont priorité sur les publications : si le lien fourni est
/video/<id>et la question porte sur les commentaires →comment-cli; si la question porte sur "les publications de cette personne" →post-cli(avec@username). - Si l'utilisateur donne un lien
/video/<id>mais demande "la liste des publications" → confirmer d'abord s'il s'agit des publications de l'auteur ou des commentaires de la vidéo.
3.2 Règles d'inférence des paramètres
| Formulation de l'utilisateur | Paramètre |
|---|---|
| Pertinence / par défaut | --sort 0 (recherche) |
| Le plus populaire / le plus de likes / viral | --sort 1 (recherche) |
| Les plus récents / par ordre chronologique | --sort 0 (publications) |
| Les publications les plus populaires | --sort 1 (publications) |
| Un jour / 24 heures | --time 1 |
| Une semaine / 7 jours | --time 7 |
| Un mois / trois mois / six mois | --time 30 / 90 / 180 |
| N résultats / les N premiers / en vouloir N | --limit N |
Valeurs par défaut : sort=0, time=0, limit=10.
⚠️ Ne pas confondre
--sortde la recherche avec celui des publications : le premier signifie "Pertinence / Plus de likes", le second "Les plus récents / Les plus populaires".
Tout paramètre réinitialisé à une valeur par défaut en raison d'une valeur invalide apparaît dans le tableau warnings du JSON de sortie. Il doit être affiché à l'utilisateur, sans faire comme si le paramètre avait été appliqué tel quel.
4. Mode d'exécution
Pour la description complète des paramètres, voir references/options.md ; le schéma au niveau des champs se trouve dans 6 fichiers de schéma JSON (draft-07) sous
assets/.
# Recherche par mot-clé
node scripts/tiktok/search-cli.js --keyword "IA" --sort 1 --limit 20
node scripts/tiktok/search-cli.js --keyword "modèle IA" --time 7 --limit 20
# Publications d'un créateur
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
# Commentaires d'une vidéo
node scripts/tiktok/comment-cli.js --url "https://www.tiktok.com/@username/video/1234567890123456789" --limit 40
Formats d'entrée acceptés
- Créateur :
https://www.tiktok.com/@username, lien avec paramètreshttps://www.tiktok.com/@username?lang=en, ou directementauthor_sec_uid - Vidéo :
https://www.tiktok.com/@username/video/<id>, lien court, ou directement l'ID de la publication<id>
Discipline d'exécution
- Ne considérer que stdout comme sortie lisible par machine (JSON pur) ; les bannières, les barres de progression et les journaux d'erreurs sont sur stderr, ne pas les mélanger.
--limitunique recommandé ≤ 1000.- Ne pas automatiquement élargir les critères en cas de résultat vide : signaler d'abord le résultat vide à l'utilisateur, c'est à lui de décider si changer de mot-clé / élargir
--time.
5. Contrat de sortie (à lire impérativement par l'IA)
Tous les points d'entrée produisent le même enveloppe, avec une structure identique en cas de succès ou d'échec :
{
"status": "success | empty | error",
"error_code": "OK | NO_MATCH | AUTH_REQUIRED | INVALID_KEYWORD | ...",
"message": "description lisible par un humain",
"timestamp": "2026-09-16 21:00:00",
"request": {
"command": "search",
"keyword": "IA",
"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": ["La valeur 99999 est invalide, réinitialisée à 10"]
}
5.1 Sémantique de status
| status | Signification | results | Que faire |
|---|---|---|---|
success | Données obtenues | Tableau non vide | Analyser directement |
empty | Requête réussie, mais aucune donnée | null | Considérer comme un résultat valide, informer l'utilisateur qu'aucune donnée n'a été trouvée, ne pas traiter comme une erreur |
error | Échec de la requête | null | Traiter selon error_code, ne pas inventer de données |
5.2 Codes de sortie
| Code de sortie | Signification | Comportement de l'agent |
|---|---|---|
0 | Succès (success ou empty) | Continuer l'analyse |
1 | Erreur d'exécution (réseau/timeout/interface/paramètres invalides) | Afficher message, demander à l'utilisateur s'il souhaite réessayer avec différents paramètres |
3 | AUTH_REQUIRED : Token manquant ou format incorrect | Arrêter immédiatement, indiquer de configurer GUAIKEI_API_TOKEN, ne pas réessayer |
5.3 Gestion des codes d'erreur
| error_code | Traitement |
|---|---|
AUTH_REQUIRED | Arrêter et indiquer de configurer le token. Ne pas réessayer, ne pas modifier les paramètres |
INVALID_KEYWORD | Indiquer que le mot-clé doit faire 2–100 caractères, ne peut pas contenir < > " ' & ni de lien http |
NO_MATCH | Résultat vide valide, suggérer de changer de mot-clé ou d'élargir --time |
NETWORK_ERROR | Nouvelle tentative intégrée ; si toujours en échec, indiquer de vérifier le réseau, maximum 1 nouvelle tentative manuelle |
TIMEOUT_ERROR | Nouvelle tentative intégrée ; si toujours en échec, suggérer de réduire --limit puis réessayer |
| Autres (code serveur) | Afficher error_code + message tels quels, ne pas deviner leur signification |
5.4 warnings doivent être affichés
Lorsque des paramètres sont invalides et automatiquement réinitialisés (ex. --sort 9, --limit 99999), le tableau warnings explique "quel paramètre a été changé en quoi". Doit être communiqué tel quel à l'utilisateur, sans faire comme si le paramètre avait été appliqué avec sa valeur d'origine.
5.5 Comportements interdits
- ❌ Ne pas inventer, compléter ou remplir de données de mémoire.
- ❌ En cas de
AUTH_REQUIRED, ne pas réessayer, ne pas changer de script, ne pas modifier les paramètres. - ❌ Ne pas considérer
emptycomme autre chose que "le contenu demandé par l'utilisateur n'existe pas" (ce n'est pas une panne de l'interface). - ❌ Ne pas élargir automatiquement les critères de recherche sans l'accord de l'utilisateur.
6. Recommandations pour l'exploitation des résultats (améliorer la qualité finale)
Après avoir obtenu results, organiser la sortie en fonction de l'objectif initial de l'utilisateur, plutôt que de restituer le JSON brut :
- Étude de sujets viraux → Trier par
digg_countdécroissant et prendre les N premiers, résumer les schémas de titres/hashtags/distribution des durées - Surveillance concurrentielle → Trier par
create_timepour voir le rythme de publication, compter la fréquence de mise à jour et la proportion de contenus viraux - Analyse des commentaires → Prendre les commentaires les plus likés par
digg_countpour un regroupement d'opinions, sortir les proportions positives/négatives - Recrutement d'influenceurs → Croiser
author_nickname/ engagement moyen / fréquence de publication, générer une liste de candidats - Besoin d'archivage → Chaque exécution enregistre automatiquement un fichier de log, dont le chemin est indiqué sur stderr à la ligne "Enregistré dans …"
7. Sécurité et Conformité (Confiance)
- Lecture seule : Ne se connecte pas à un compte TikTok, n'effectue aucune opération d'écriture (publier, liker, commenter, suivre, envoyer un message privé), aucun risque de bannissement.
- Privilèges minimaux : Ne nécessite qu'une seule variable d'environnement
GUAIKEI_API_TOKENpour le métier ; ne lit aucun autre fichier local, n'écrit pas en dehors du répertoire de la compétence (les logs sont écrits dans le répertoire temporaire système). - Protection des identifiants : Le token est uniquement lu depuis la variable d'environnement, jamais écrit dans stdout, les logs ou les messages d'erreur.
- Périmètre des données envoyées (à connaître impérativement) : Lors de l'appel, les données suivantes sont envoyées à
www.guaikei.com: votre API Token, le mot-clé de recherche ou l'URL/ID cible, ainsi que le nom de la compétence et la version de Node. Aucune autre information locale n'est collectée. - Conformité des données : Ne collecte que les données publiques visibles sur TikTok (pseudonyme, publications publiques, commentaires publics). Aucune donnée privée comme numéro de téléphone, localisation, messages privés. Les données sont destinées uniquement à une analyse personnelle/au sein de l'équipe ; pour une publication externe ou un usage commercial, veuillez obtenir les autorisations nécessaires et anonymiser les pseudonymes des utilisateurs.
- Aucune dépendance tierce : Utilise uniquement les modules intégrés de Node.js (
https/fs/path/os/querystring), aucune dépendance npm, aucun chargement de script distant, aucuneval/child_process.
8. Questions fréquentes
| Problème | Cause et traitement |
|---|---|
| Code de sortie 3 / AUTH_REQUIRED | Token non configuré ou format incorrect (doit faire 16–256 caractères alphanumériques, underscores, tirets) |
| Résultat de recherche vide | Changer pour un mot-clé plus général, ou utiliser --time 0 pour enlever la fenêtre temporelle ; empty est un résultat normal, pas une erreur |
Nombre de résultats inférieur à --limit | Le serveur n'a plus de données à retourner, ou la limite unique est atteinte ; réduire à ≤ 1000 et récupérer par lots |
| Toujours en timeout | Réduire --limit puis réessayer ; le script intègre une nouvelle tentative avec backoff exponentiel |
| Vouloir "les publications les plus populaires" mais obtenez un ordre chronologique inverse | post-cli nécessite --sort 1 |
| Paramètre non appliqué / ordre de tri différent de l'attendu | Vérifier warnings dans la sortie ; les paramètres invalides sont silencieusement réinitialisés à la valeur par défaut |
| Où se trouve le fichier de log ? | Voir la ligne "Enregistré dans …" sur stderr (dossier temporaire système tiktok-guaikei/logs/<date>/) |
9. Environnement et support
- Environnement : Node.js ≥ 16.14.0, Windows / macOS / Linux ; nécessaire :
GUAIKEI_API_TOKEN. - Site officiel : Site officiel TikTok Competitor Radar (obtention autonome du token, consultation de l'utilisation et des descriptions d'interface).
- Journal des modifications : references/changelog.md