Communitygithub.com

why20261/tiktok-insight

Herramienta de análisis de competencia en TikTok que monitorea el rendimiento del tráfico en tiempo real, desglosa videos de la competencia, analiza estrategias y construye bibliotecas de palabras clave. Ideal para marcas y creadores de contenido.

¿Qué es tiktok-insight?

El skill **TikTok Competitor Insight** (why20261/tiktok-insight) ofrece tres capacidades principales para analizar contenido público de TikTok: búsqueda por palabras clave (ordenable por likes o relevancia, con filtro de tiempo), obtención de videos de un creador (por enlace de perfil o nombre de usuario, con ordenación por más recientes o más populares), y extracción de comentarios de un video (obtiene texto, autor, interacciones). Los resultados se devuelven en JSON estructurado, listo para análisis posterior. Está diseñado para marcas, agencias MCN, creadores y analistas que necesitan investigar tendencias, monitorear competidores, analizar sentimiento en comentarios o descubrir contenido viral, todo sin necesidad de navegar manualmente en TikTok. Requiere la variable de entorno `GUAIKEI_API_TOKEN` y solo utiliza módulos nativos de Node.js, garantizando seguridad y sin dependencias externas. El skill distingue claramente entre búsqueda, perfil de creador y comentarios, siguiendo reglas precisas de desambiguación para elegir el script correcto según la intención del usuario.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add why20261/tiktok-insight

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

🎯 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.

CapacidadScript de entradaParámetros obligatoriosRetorno
Búsqueda por palabras clavescripts/tiktok/search-cli.js--keywordLista de videos: autor, likes/comentarios/compartidos/guardados, etiquetas, enlace de reproducción
Videos de creadorscripts/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 videoscripts/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 salida 3, 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 usuarioScriptPalabras clave de decisión
Buscar por palabra clave, encontrar cierto tipo de contenido, buscar contenido viralsearch-clibuscar / encontrar / palabra clave / viral / más popular
Ver los videos / perfil / cuenta de un creador / influencer / celebridad / publicaciones recientespost-clivideos / perfil / cuenta / creador / influencer / celebridad / KOL
Ver los comentarios de un video específicocomment-clicomentarios / mensajes / opiniones en la sección de comentarios

3.1 Reglas de desambiguación (obligatorio)

  1. 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.
  2. 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).
  3. 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 usuarioPará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 --sort de búsqueda con --sort de 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ámetros https://www.tiktok.com/@username?lang=en, o directamente author_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

statusSignificadoresultsQué hacer
successSe obtuvieron datosArray no vacíoAnaliza directamente
emptySolicitud exitosa, pero realmente no hay datosnullTrátalo como resultado válido; informa al usuario que no se encontró nada, no lo tomes como error
errorSolicitud fallidanullProcesa según error_code, no inventes datos

5.2 Códigos de salida

Código de salidaSignificadoComportamiento del Agente
0Éxito (success o empty)Continúa con el análisis
1Error 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
3AUTH_REQUIRED: Token faltante o con formato incorrectoDetente inmediatamente, indica que debe configurar GUAIKEI_API_TOKEN, prohíbe reintentar

5.3 Manejo de códigos de error

error_codeAcción
AUTH_REQUIREDDetente e indica que configure el Token. Prohíbe reintentar o cambiar parámetros para evitarlo
INVALID_KEYWORDIndica que la palabra clave debe tener entre 2 y 100 caracteres, no puede contener < > " ' & ni enlaces http
NO_MATCHResultado vacío válido; sugiere cambiar la palabra clave o ampliar --time
NETWORK_ERRORYa incluye reintentos internos; si sigue fallando, indica que verifique la red y reintenta manualmente como máximo 1 vez
TIMEOUT_ERRORYa 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 empty como 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_count descendente y toma los Top N; resume patrones de títulos / etiquetas / duración
  • Monitoreo de competencia → ordena por create_time para 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_count para 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_TOKEN para 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, sin eval / child_process.

8. Preguntas frecuentes

SituaciónCausa y solución
Código de salida 3 / AUTH_REQUIREDToken no configurado o con formato incorrecto (debe tener entre 16 y 256 caracteres alfanuméricos, guiones bajos y guiones)
Resultados de búsqueda vacíosPrueba 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 --limitEl servidor no tiene más datos para devolver, o el límite único se truncó; reduce a ≤ 1000 y obtén en lotes
Timeout constanteReduce --limit y reintenta; el script ya incluye reintentos con retroceso exponencial
Quiero ver "los videos más populares" pero se ordenan por fechaEn post-cli debes usar --sort 1
Los parámetros no tienen efecto / el orden no es el esperadoRevisa 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

Skills relacionados