🎯 Análisis de Competencia en TikTok
1. Resumen de Capacidades
💡Valor en una frase: con una instrucción sencilla obtén datos públicos de videos/autores/comentarios de TikTok en JSON estructurado — ideal para selección de influencers, análisis de datos, investigación de mercado, monitoreo de reputación, temas virales, seguimiento de cuentas competidoras, análisis de sentimiento en comentarios y seguimiento de tendencias, sin necesidad de desplazarte manualmente por TikTok.
| Capacidad | Script de entrada | Parámetros obligatorios | Retorno |
|---|---|---|---|
| Búsqueda por palabras clave | scripts/tiktok/search-cli.js | --keyword | Lista de videos: autor, likes/comentarios/compartidos/guardados, etiquetas, enlace de reproducción |
| Videos de creador | scripts/tiktok/post-cli.js | --url (perfil o nombre de usuario) | Lista de videos públicos del creador (ordenable por más reciente / más popular) |
| Comentarios de video | scripts/tiktok/comment-cli.js | --url (enlace del video o ID) | Texto del comentario, autor, número de likes, respuestas |
Público objetivo
- 🎯 Marcas — aprovechar tendencias para crear contenido de recomendación
- 🏢 Agencias MCN — descubrir cuentas con alto potencial de interacción
- ✍️ Creadores de contenido — encontrar referencias e inspiración
- 📊 Community managers — análisis semanal de temas y competencia
Requisito previo: Debes ejecutar el comando desde el directorio raíz del skill y tener configurada la variable de entorno
GUAIKEI_API_TOKEN. Si no está configurada, todos los comandos devuelven código de salida3,error_code=AUTH_REQUIRED— en ese caso, indica directamente al usuario que configure el Token, no reintentes ni cambies parámetros.
2. Cuándo invocar / Cuándo no invocar
2.1 Debes invocar
- El usuario quiere consultar contenido público de TikTok (videos / imágenes / autores / comentarios / tendencias).
- El usuario quiere hacer investigación de temas virales, monitoreo de cuentas competidoras, selección de influencers, análisis de sentimiento en comentarios, desglose de estilos de contenido.
- El usuario ya proporcionó una palabra clave de TikTok, enlace de video o enlace de perfil de creador, y desea obtener datos estructurados.
- Después de obtener los datos, el usuario quiere hacer resúmenes, comparaciones, ordenamientos, agrupaciones o generar informes / tablas.
2.2 No debes invocar
- El usuario solo pide texto / título / guion, sin solicitar datos de TikTok.
- La plataforma no es TikTok, sino otra (Douyin, Xiaohongshu, Bilibili, Weibo, WeChat Official Accounts) → redirige al skill correspondiente. Este skill solo procesa TikTok.
- Se requiere inicio de sesión, datos privados u ocultos → no compatible.
- Hay tanto una palabra clave como un enlace identificable y el objetivo no está claro → pregunta primero, no adivines.
2.3 Límites de capacidad (explícitamente no se hace)
No se admiten operaciones de escritura como publicar / dar like / comentar / seguir / enviar mensajes privados; no se inicia sesión en ninguna cuenta; no se recopilan campos de privacidad como números de teléfono, ubicación o mensajes privados; no se toman decisiones de marketing por el usuario — la función es obtener los datos, el análisis se deja a la capa superior.
3. Enrutamiento de invocación (primero decide, luego ejecuta)
| Intención del usuario | Script | Palabras clave de decisión |
|---|---|---|
| Buscar por palabra clave, encontrar cierto tipo de contenido, buscar contenido viral | search-cli | buscar / encontrar / palabra clave / viral / más popular |
| Ver los videos / perfil / cuenta de un creador / influencer / celebridad / publicaciones recientes | post-cli | videos / perfil / cuenta / creador / influencer / celebridad / KOL |
| Ver los comentarios de un video específico | comment-cli | comentarios / mensajes / opiniones en la sección de comentarios |
3.1 Reglas de desambiguación (obligatorio)
- Si aparece solo la palabra "video", no asumas que es
post-cli.- Si hay "palabra clave" y no "comentarios" →
search-cli(el usuario quiere buscar ese tipo de videos). - Si es explícitamente "comentarios / mensajes de este video" →
comment-cli. - Solo si aparece "videos / perfil / cuenta / creador / influencer" →
post-cli.
- Si hay "palabra clave" y no "comentarios" →
- Los comentarios tienen prioridad sobre los videos: si se proporciona un enlace
/video/<id>y se piden comentarios →comment-cli; si se piden "los videos de esta persona" →post-cli(usando@username). - Si el usuario da un enlace
/video/<id>pero pide "lista de videos" → primero confirma si quiere los videos de ese autor o los comentarios de ese video.
3.2 Reglas de inferencia de parámetros
| Expresión del usuario | Parámetro |
|---|---|
| Relevancia / predeterminado | --sort 0 (búsqueda) |
| Más popular / más likes / viral / más caliente | --sort 1 (búsqueda) |
| Publicado recientemente / orden cronológico inverso | --sort 0 (videos) |
| Los videos más populares | --sort 1 (videos) |
| Un día / 24 horas | --time 1 |
| Una semana / 7 días | --time 7 |
| Un mes / tres meses / seis meses | --time 30 / 90 / 180 |
| N resultados / los primeros N / quiero N | --limit N |
Valores predeterminados: sort=0, time=0, limit=10.
⚠️ No mezcles
--sortde búsqueda con--sortde videos: el primero es "relevancia / más likes", el segundo es "más reciente / más popular".
Cualquier parámetro que se revierta por valor no válido aparecerá en el array warnings del JSON de salida; debes mostrarlo al usuario, no asumas que se aplicó el valor original.
4. Modo de ejecución
Consulta la referencia completa de parámetros; el esquema a nivel de campo está en los 6 archivos JSON Schema (draft-07) en
assets/.
# Búsqueda por palabra clave
node scripts/tiktok/search-cli.js --keyword "AI" --sort 1 --limit 20
node scripts/tiktok/search-cli.js --keyword "AI model" --time 7 --limit 20
# Videos de creador
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
# Comentarios de video
node scripts/tiktok/comment-cli.js --url "https://www.tiktok.com/@username/video/1234567890123456789" --limit 40
Formatos de entrada aceptados
- Creador:
https://www.tiktok.com/@username, enlace con parámetroshttps://www.tiktok.com/@username?lang=en, o directamenteauthor_sec_uid - Video:
https://www.tiktok.com/@username/video/<id>, enlace corto, o directamente el<id>del video
Disciplina de ejecución
- Solo trata stdout como salida legible por máquina (JSON puro); los banners / progreso / registros de error están en stderr, no los mezcles al parsear.
- Se recomienda
--limit≤ 1000 por llamada. - No reintentes automáticamente con condiciones más amplias ante un resultado vacío: primero informa al usuario del resultado vacío; que sea él quien decida si cambiar de palabra clave o ampliar
--time.
5. Contrato de salida (lectura obligatoria para IA)
Todas las entradas producen el mismo sobre, con estructura idéntica para éxito y error:
{
"status": "success | empty | error",
"error_code": "OK | NO_MATCH | AUTH_REQUIRED | INVALID_KEYWORD | ...",
"message": "Descripción legible para humanos",
"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": ["El valor 99999 es inválido, se ha revertido a 10"]
}
5.1 Semántica de status
| status | Significado | results | Qué hacer |
|---|---|---|---|
success | Se obtuvieron datos | Array no vacío | Analiza directamente |
empty | Solicitud exitosa, pero realmente no hay datos | null | Trátalo como resultado válido; informa al usuario que no se encontró nada, no lo tomes como error |
error | Solicitud fallida | null | Procesa según error_code, no inventes datos |
5.2 Códigos de salida
| Código de salida | Significado | Comportamiento del Agente |
|---|---|---|
0 | Éxito (success o empty) | Continúa con el análisis |
1 | Error de ejecución (red / timeout / excepción de API / parámetro inválido) | Muestra message, pregunta al usuario si quiere reintentar con otros parámetros |
3 | AUTH_REQUIRED: Token faltante o con formato incorrecto | Detente inmediatamente, indica que debe configurar GUAIKEI_API_TOKEN, prohíbe reintentar |
5.3 Manejo de códigos de error
| error_code | Acción |
|---|---|
AUTH_REQUIRED | Detente e indica que configure el Token. Prohíbe reintentar o cambiar parámetros para evitarlo |
INVALID_KEYWORD | Indica que la palabra clave debe tener entre 2 y 100 caracteres, no puede contener < > " ' & ni enlaces http |
NO_MATCH | Resultado vacío válido; sugiere cambiar la palabra clave o ampliar --time |
NETWORK_ERROR | Ya incluye reintentos internos; si sigue fallando, indica que verifique la red y reintenta manualmente como máximo 1 vez |
TIMEOUT_ERROR | Ya incluye reintentos internos; si sigue fallando, sugiere reducir --limit y reintentar |
| Otros (códigos del servidor) | Muestra error_code + message tal cual, no intentes adivinar el significado |
5.4 warnings deben mostrarse
Cuando un parámetro no es válido y se revierte automáticamente (por ejemplo, --sort 9, --limit 99999), el array warnings explicará "qué parámetro se cambió a qué valor". Debes informarlo textualmente al usuario, no asumas que el parámetro se aplicó con el valor original.
5.5 Comportamiento prohibido
- ❌ No inventes, no completes, no rellenes ningún dato de memoria.
- ❌ Al recibir
AUTH_REQUIRED, no reintentes, no cambies de script, no modifiques parámetros. - ❌ No interpretes
emptycomo otra conclusión que no sea "el contenido solicitado no existe" (no significa que la interfaz esté rota). - ❌ No amplíes automáticamente las condiciones de búsqueda sin el consentimiento del usuario.
6. Recomendaciones para consumir resultados (mejora la calidad final)
Una vez obtenidos los results, organiza la salida según el objetivo original del usuario, en lugar de mostrar el JSON tal cual:
- Investigación de temas → ordena por
digg_countdescendente y toma los Top N; resume patrones de títulos / etiquetas / duración - Monitoreo de competencia → ordena por
create_timepara ver la frecuencia de publicación; calcula la tasa de actualización y la proporción de contenido viral - Análisis de comentarios → ordena por
digg_countpara agrupar opiniones de los comentarios con más likes; calcula la proporción de sentimiento positivo/negativo - Selección de influencers → cruza
author_nickname/ interacción promedio / frecuencia de publicación; genera una lista de candidatos - Si necesita archivo → cada ejecución guarda automáticamente un archivo de registro; la ruta aparece en la línea "Guardado en …" de stderr
7. Seguridad y cumplimiento (Confianza)
- Solo lectura: no inicia sesión en cuentas de TikTok, no realiza ninguna operación de escritura (publicar / dar like / comentar / seguir / enviar mensajes privados); sin riesgo de bloqueo por medidas de seguridad.
- Mínimos privilegios: solo requiere una variable de entorno
GUAIKEI_API_TOKENpara su funcionamiento; no lee otros archivos locales, no escribe fuera del directorio del skill (los registros se guardan en el directorio temporal del sistema). - Protección de credenciales: el Token solo se lee desde la variable de entorno; no se escribe en stdout, ni en registros, ni aparece en mensajes de error.
- Alcance de datos enviados (debes saberlo): al realizar la llamada, se envía a
www.guaikei.com: tu API Token, la palabra clave de búsqueda o la URL/ID de destino, así como el nombre del skill y la versión de Node. No se recopila ninguna otra información local. - Cumplimiento de datos: solo se obtienen datos públicos de TikTok (nombre de usuario, videos públicos, comentarios públicos). No incluye números de teléfono, ubicación, mensajes privados ni otros campos de privacidad. Los datos son solo para análisis personal o dentro del equipo; antes de publicarlos externamente o usarlos con fines comerciales, verifica los permisos correspondientes y anonimiza los nombres de usuario.
- Sin dependencias externas: solo utiliza módulos nativos de Node.js (
https/fs/path/os/querystring), sin dependencias npm, sin carga remota de scripts, sineval/child_process.
8. Preguntas frecuentes
| Situación | Causa y solución |
|---|---|
| Código de salida 3 / AUTH_REQUIRED | Token no configurado o con formato incorrecto (debe tener entre 16 y 256 caracteres alfanuméricos, guiones bajos y guiones) |
| Resultados de búsqueda vacíos | Prueba con palabras clave más generales, o --time 0 para eliminar el filtro de tiempo; empty es un resultado normal, no un error |
Número de resultados menor que --limit | El servidor no tiene más datos para devolver, o el límite único se truncó; reduce a ≤ 1000 y obtén en lotes |
| Timeout constante | Reduce --limit y reintenta; el script ya incluye reintentos con retroceso exponencial |
| Quiero ver "los videos más populares" pero se ordenan por fecha | En post-cli debes usar --sort 1 |
| Los parámetros no tienen efecto / el orden no es el esperado | Revisa los warnings en la salida; los parámetros no válidos se revierten silenciosamente a sus valores predeterminados |
| ¿Dónde está el archivo de registro? | Busca la línea "Guardado en …" en stderr (directorio temporal del sistema tiktok-guaikei/logs/<fecha>/) |
9. Entorno y soporte
- Entorno: Node.js ≥ 16.14.0, compatible con Windows / macOS / Linux; se requiere
GUAIKEI_API_TOKEN. - Sitio web oficial: Sitio web de Análisis de Competencia en TikTok (activa tu Token, consulta el uso y la documentación de la API).
- Registro de cambios: references/changelog.md