🎯 Análisis de Competidores en TikTok y Comparación de Marcas
1. Resumen de Capacidades
💡Valor en una frase: Con una instrucción en lenguaje natural obtén datos públicos de TikTok (videos, autores y comentarios) y recíbelos en JSON estructurado: ideal para selección de creadores, análisis de datos, investigación de mercado, monitoreo de opinión, temas virales, seguimiento de cuentas competidoras, análisis de comentarios y tendencias, sin tener que hacer scroll manualmente en TikTok.
| Capacidad | Script de entrada | Parámetros obligatorios | Devuelve |
|---|---|---|---|
| Búsqueda por palabra clave | scripts/tiktok/search-cli.js | --keyword | Lista de publicaciones: autor, likes/comentarios/compartidos/guardados, etiquetas, URL de reproducción |
| Publicaciones de un creador | scripts/tiktok/post-cli.js | --url (perfil o nombre de usuario) | Lista de publicaciones públicas de ese creador (ordenación por fecha o popularidad) |
| Comentarios de un video | scripts/tiktok/comment-cli.js | --url (enlace o ID del video) | Texto del comentario, autor, número de likes, número de respuestas |
Público objetivo
- 🎯 Marcas: aprovechar tendencias para crear contenido de marketing.
- 🏢 Agencias MCN: descubrir cuentas con alto potencial de interacción.
- ✍️ Creadores de contenido independientes: encontrar referentes e inspiración.
- 📊 Gestores de contenido: análisis semanal de temas y competidores.
Requisito previo: Debe ejecutarse en el directorio raíz de la skill, y la variable de entorno
GUAIKEI_API_TOKENdebe estar configurada. 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 los parámetros.
2. Cuándo invocar / Cuándo no invocar
2.1 Debe invocarse
- 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 opinión en comentarios, o desglose de estilos de contenido.
- El usuario proporciona palabras clave de TikTok, enlaces de video o enlaces de perfil de creador, y desea obtener datos estructurados.
- Después de obtener los datos, el usuario quiere continuar con resúmenes, comparaciones, ordenaciones, agrupaciones o generar informes / tablas.
2.2 No debe invocarse
- El usuario solo necesita texto / títulos / guiones, sin consultar datos de TikTok.
- La plataforma no es TikTok, sino otra (Douyin, Xiaohongshu, Bilibili, Weibo, WeChat Official Accounts) → enruta a la skill correspondiente. Esta skill solo maneja TikTok.
- Se requieren datos que necesiten inicio de sesión, sean privados u ocultos → no es 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 hacer)
No se admiten operaciones de escritura como publicar, dar like, comentar, seguir o enviar mensajes privados; no se inicia sesión en ninguna cuenta; no se recopilan campos privados como números de teléfono, ubicación o mensajes directos; no se toman decisiones de marketing por el usuario: la responsabilidad es obtener los datos, el análisis se deja a un nivel superior.
3. Enrutamiento de invocación (primero evalúa, luego ejecuta)
| Intención del usuario | Script | Palabras clave de decisión |
|---|---|---|
| Buscar palabra clave, encontrar cierto tipo de contenido, encontrar tendencias | search-cli | buscar / encontrar / palabra clave / tendencia / más popular |
| Ver publicaciones / perfil / cuenta / creador / influencer, publicaciones recientes | post-cli | publicaciones / perfil / cuenta / creador / influencer / KOL |
| Ver comentarios / respuestas de un video determinado | comment-cli | comentarios / respuestas / opiniones en la sección de comentarios |
3.1 Reglas de desambiguación (obligatorias)
- Cuando aparezca solo "video", no lo asignes por defecto a
post-cli.- Si hay "palabra clave" y no "comentarios" →
search-cli(el usuario quiere buscar ese tipo de videos). - Si dice explícitamente "comentarios / respuestas de este video" →
comment-cli. - Solo si aparecen "publicaciones / perfil / cuenta / creador / influencer" →
post-cli.
- Si hay "palabra clave" y no "comentarios" →
- La prioridad de comentarios es mayor que la de publicaciones: si el enlace es
/video/<id>y la pregunta es sobre comentarios →comment-cli; si la pregunta es "publicaciones de esta persona" →post-cli(usando@username). - Si el usuario da un enlace
/video/<id>pero quiere "lista de publicaciones" → primero confirma si se refiere a las publicaciones del autor o a los comentarios de ese video.
3.2 Reglas de inferencia de parámetros
| Lo que dice el usuario | Parámetro |
|---|---|
| Relevancia / por defecto | --sort 0 (búsqueda) |
| Más popular / más likes / tendencia / más visto | --sort 1 (búsqueda) |
| Publicaciones recientes / en orden cronológico inverso | --sort 0 (publicaciones) |
| Publicaciones más populares | --sort 1 (publicaciones) |
| 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 por defecto: sort=0, time=0, limit=10.
⚠️ No confundir
--sortde búsqueda con--sortde publicaciones: el primero es "relevancia / más likes", el segundo es "más reciente / más popular".
Cualquier parámetro que se degrade por valor inválido aparecerá en el array warnings del JSON de salida, y debe mostrarse al usuario; no se debe asumir que el valor original ha surtido efecto.
4. Modo de ejecución
La documentación completa de parámetros está en references/options.md; los esquemas JSON a nivel de campo están en los 6 archivos de
assets/(draft-07).
# 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
# Publicaciones de un 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 un video
node scripts/tiktok/comment-cli.js --url "https://www.tiktok.com/@username/video/1234567890123456789" --limit 40
Formatos de entrada disponibles
- 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, el progreso y los logs de error están en stderr, no los mezcles al analizar.
- Se recomienda un único
--limit≤ 1000. - No reintentes automáticamente si obtienes un resultado vacío: informa primero al usuario del resultado vacío y deja que él decida si cambiar la palabra clave o ampliar
--time.
5. Contrato de salida (lectura obligatoria para la IA)
Todas las entradas producen el mismo envoltorio, con estructura idéntica para éxito y error:
{
"status": "success | empty | error",
"error_code": "OK | NO_MATCH | AUTH_REQUIRED | INVALID_KEYWORD | ...",
"message": "Explicación legible por humanos",
"timestamp": "2026-09-16 21:00:00",
"request": {
"command": "search",
"keyword": "AI",
"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 cantidad 99999 no es válida, se ha degradado a 10"]
}
5.1 Semántica de status
| status | Significado | results | Qué hacer |
|---|---|---|---|
success | Datos obtenidos correctamente | Array no vacío | Analizar directamente |
empty | La solicitud fue exitosa, pero no hay datos | null | Considerarlo un resultado válido, informa al usuario que no se encontró nada, no lo trates como un error |
error | La solicitud falló | null | Procesar 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) | Continuar el análisis |
1 | Error de ejecución (red / timeout / excepción de API / parámetro inválido) | Mostrar message, preguntar al usuario si desea reintentar con otros parámetros |
3 | AUTH_REQUIRED: Token faltante o con formato incorrecto | Detenerse inmediatamente, indicar que configure GUAIKEI_API_TOKEN, prohibido reintentar |
5.3 Manejo de códigos de error
| error_code | Manejo |
|---|---|
AUTH_REQUIRED | Detenerse e indicar que configure el Token. Prohibido reintentar o cambiar parámetros para evitarlo |
INVALID_KEYWORD | Indicar que la palabra clave debe tener entre 2 y 100 caracteres, no puede contener < > " ' & ni enlaces http |
NO_MATCH | Resultado vacío válido, sugerir cambiar la palabra clave o ampliar --time |
NETWORK_ERROR | Ya tiene reintentos incorporados; si aún falla, indica al usuario que verifique la red, máximo 1 reintento manual |
TIMEOUT_ERROR | Ya tiene reintentos incorporados; si aún falla, sugerir reducir --limit y reintentar |
| Otros (códigos de servidor) | Mostrar error_code + message tal cual, sin adivinar su significado |
5.4 warnings deben mostrarse
Cuando un parámetro introducido no es válido y se degrada automáticamente (ej. --sort 9, --limit 99999), el array warnings explicará "qué parámetro se ha cambiado a qué". Debes informar al usuario exactamente igual, no puedes fingir que el valor original ha surtido efecto.
5.5 Comportamientos prohibidos
- ❌ No inventar, no completar, no rellenar ningún dato de memoria.
- ❌ Al recibir
AUTH_REQUIRED, no reintentar, no cambiar de script, no modificar parámetros. - ❌ No interpretar
emptycomo "el contenido que el usuario quiere no existe" más allá de esa conclusión (no significa que la interfaz esté rota). - ❌ No ampliar automáticamente las condiciones de búsqueda sin el consentimiento del usuario.
6. Sugerencias para el consumo de resultados (mejora la calidad final)
Una vez obtenidos los results, orgánizalos según el objetivo original del usuario, no los presentes como JSON en bruto:
- Investigación de temas → ordenar por
digg_countdescendente y tomar los Top N, resumir patrones de títulos / etiquetas / duración - Monitoreo de competidores → ordenar por
create_timepara ver la cadencia de publicación, calcular frecuencia de actualización y porcentaje de publicaciones virales - Análisis de comentarios → ordenar por
digg_countpara agrupar opiniones de los comentarios más populares, mostrar proporción de positivos y negativos - Selección de influencers → cruzar
author_nickname/ interacción media / frecuencia de publicación, ofrecer una lista de candidatos - Necesidad de archivo → cada ejecución guarda automáticamente un archivo de registro; la ruta aparece en stderr en la línea "Guardado en …"
7. Seguridad y Cumplimiento (Trust)
- Solo lectura: no se inicia sesión en cuentas de TikTok, no se ejecuta ninguna operación de escritura como publicar, dar like, comentar, seguir o enviar mensajes privados; no hay riesgo de bloqueo por infracción.
- Mínimos privilegios: solo solicita la variable de entorno
GUAIKEI_API_TOKENnecesaria para el negocio; no lee otros archivos locales, no escribe fuera del directorio de la skill (los registros se escriben en el directorio temporal del sistema). - Protección de credenciales: el Token solo se lee de la variable de entorno, no se escribe en stdout, no se incluye en los registros, no aparece en los mensajes de error.
- Ámbito de envío de datos (imprescindible saber): al realizar la llamada, se envía a
www.guaikei.com: tu API Token, la palabra clave de búsqueda o URL/ID de destino, junto con el nombre de la skill y la versión de Node. No se recopila ninguna otra información local. - Cumplimiento de datos: solo se obtienen datos visibles públicamente de TikTok (nombre de usuario, publicaciones públicas, comentarios públicos). No incluye datos privados como números de teléfono, ubicación o mensajes directos. Los datos están destinados únicamente para análisis interno personal o de equipo; antes de su divulgación pública o uso comercial, el usuario debe confirmar la autorización correspondiente y anonimizar campos como los nombres de usuario.
- Sin dependencias de terceros: solo utiliza módulos integrados de Node.js (
https/fs/path/os/querystring), sin dependencias npm, sin carga de scripts remotos, sineval/child_process.
8. Preguntas Frecuentes
| Problema | Causa y solución |
|---|---|
| Código de salida 3 / AUTH_REQUIRED | El Token no está configurado o su formato es incorrecto (debe tener entre 16 y 256 caracteres alfanuméricos, guiones bajos y guiones) |
| Resultados de búsqueda vacíos | Prueba con una palabra clave más genérica 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 ha truncado; reduce a ≤ 1000 y obtén en lotes |
| Timeout constante | Reduce --limit y reintenta; el script ya tiene reintentos con retroceso exponencial |
| Quieres ver "publicaciones más populares" pero aparecen en orden cronológico inverso | En post-cli debes usar --sort 1 |
| El parámetro no surte efecto / el orden no es el esperado | Revisa los warnings en la salida; si el parámetro no es válido, se degrada silenciosamente al valor por defecto |
| ¿Dónde está el archivo de registro? | Consulta 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, Windows / macOS / Linux; requiere
GUAIKEI_API_TOKEN. - Sitio web oficial: Sitio web oficial de Análisis de Competidores en TikTok y Comparación de Marcas (activa tu Token, consulta el uso y la documentación de la interfaz).
- Registro de cambios: references/changelog.md