Communitygithub.com

why20261/tiktok-insight

Ferramenta de análise de concorrência do TikTok, que monitora o desempenho de tráfego dos concorrentes em tempo real, analisa vídeos de referência, desvenda estratégias de tráfego e constrói bibliotecas de palavras-chave de forma eficiente.

O que é tiktok-insight?

O TikTok Insight é uma skill de agente de IA especializada em análise competitiva, otimização de tráfego e pesquisa de palavras-chave no TikTok. Ela oferece três funcionalidades principais: busca por palavras-chave (com opções de ordenação por curtidas/relevância e filtro por data de publicação), listagem de vídeos de um criador (por link do perfil ou nome de usuário, com ordenação por mais recentes ou mais populares), e extração de comentários de vídeos (incluindo autores, dados de interação e tags, retornando JSON estruturado). A skill é ideal para marcas, criadores de conteúdo e agências que precisam de dados públicos do TikTok para análise de concorrência, pesquisa de tendências e monitoramento de reputação. Ela é executada via scripts Node.js (search-cli, post-cli, comment-cli), requer a variável de ambiente `GUAIKEI_API_TOKEN` e é estritamente somente leitura, sem interações privadas ou ações de postagem.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add why20261/tiktok-insight

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

🎯 Análise de Concorrência no TikTok

1. Visão Geral da Skill

💡 Valor em uma frase: Um comento simples para obter dados públicos de vídeos, criadores e comentários do TikTok, gerando JSON estruturado — ideal para seleção de influenciadores, análise de dados, pesquisa de mercado, monitoramento de reputação, ideias de conteúdo viral, monitoramento de contas concorrentes, análise de sentimento em comentários e rastreamento de tendências, sem precisar navegar manualmente no TikTok.

FuncionalidadeScript de EntradaParâmetro ObrigatórioRetorno
Busca por Palavra-chavescripts/tiktok/search-cli.js--keywordLista de vídeos: autor, curtidas/comentários/compartilhamentos/favoritos, tags, URL do vídeo
Vídeos do Criadorscripts/tiktok/post-cli.js--url (perfil ou nome de usuário)Lista de vídeos públicos do perfil (suporta ordenação por mais recentes/populares)
Comentários de Vídeoscripts/tiktok/comment-cli.js--url (link do vídeo ou ID)Comentários, autores, número de curtidas e respostas

Público-Alvo

  • 🎯 Marcas — Aproveitar tendências para criar conteúdo orgânico
  • 🏢 Agências MCN — Descobrir contas de alto engajamento
  • ✍️ Criadores de Conteúdo — Encontrar benchmarks e inspiração
  • 📊 Analistas de Conteúdo — Relatórios semanais e análise de concorrência

Pré-requisito: Deve ser executado no diretório raiz da skill com a variável de ambiente GUAIKEI_API_TOKEN configurada. Se não configurada, todos os comandos retornam código de saída 3 e error_code=AUTH_REQUIRED — neste caso, instrua o usuário a configurar o Token, não tente novamente nem altere parâmetros.


2. Quando Chamar / Quando Não Chamar

2.1 Deve Chamar

  • O usuário deseja consultar conteúdo público do TikTok (vídeos, imagens, criadores, comentários, tendências).
  • O usuário quer fazer pesquisa de tópicos virais, monitoramento de contas concorrentes, seleção de influenciadores, análise de sentimento em comentários ou decodificação de estilos de conteúdo.
  • O usuário forneceu uma palavra-chave, link de vídeo ou link de perfil do TikTok e espera dados estruturados.
  • Após obter os dados, o usuário planeja fazer resumos, comparações, ordenações, agrupamentos ou gerar relatórios/tabelas.

2.2 Não Deve Chamar

  • O usuário pede apenas texto/título/script, sem solicitar dados do TikTok.
  • A plataforma não é TikTok, mas sim outra (Douyin, Xiaohongshu, Bilibili, Weibo, WeChat) → redirecione para a skill correspondente. Esta skill lida apenas com TikTok.
  • Dados que exigem login, são privados ou ocultos → não suportado.
  • O usuário forneceu tanto uma palavra-chave quanto um link identificável com intenção ambígua → primeiro pergunte, não adivinhe.

2.3 Limites da Skill (Não Faz)

Não suporta nenhuma operação de escrita (publicar, curtir, comentar, seguir, enviar mensagem privada). Não faz login em contas. Não coleta números de telefone, localização, mensagens privadas ou outros campos privados. Não toma decisões de marketing pelo usuário — a responsabilidade é trazer os dados; a análise fica por conta de camadas superiores.


3. Roteamento de Chamadas (Primeiro Decida, Depois Execute)

Intenção do UsuárioScriptPalavras-Chave de Decisão
Pesquisar por palavra-chave, encontrar conteúdo ou viraissearch-clipesquisar / encontrar / palavra-chave / viral / mais popular
Ver vídeos / perfil / conta de um criador/influenciadorpost-clivídeos / perfil / conta / criador / influenciador / KOL
Ver comentários de um vídeo específicocomment-clicomentários / feedback / opiniões do público

3.1 Regras de Desambiguação (Obrigatório Seguir)

  1. Se aparecer apenas "vídeo", não assuma automaticamente post-cli.
    • Se houver "palavra-chave" e não houver "comentário" → search-cli (o usuário quer pesquisar vídeos desse tipo).
    • Se explicitamente "comentários / feedback deste vídeo" → comment-cli.
    • Apenas se aparecer "vídeos / perfil / conta / criador / influenciador" → post-cli.
  2. Comentários têm prioridade sobre vídeos: Se o link for /video/<id> e a pergunta for sobre comentários → comment-cli; se a pergunta for "os vídeos desta pessoa" → post-cli (usando @username).
  3. Se o usuário der um link /video/<id> e pedir "lista de vídeos" → primeiro confirme se ele quer os vídeos do autor ou os comentários do vídeo.

3.2 Regras de Inferência de Parâmetros

Fala do UsuárioParâmetro
Relevância / padrão--sort 0 (busca)
Mais popular / mais curtido / viral / mais quente--sort 1 (busca)
Mais recentes / ordem cronológica--sort 0 (vídeos do criador)
Vídeos mais populares--sort 1 (vídeos do criador)
Um dia / 24 horas--time 1
Uma semana / 7 dias--time 7
Um mês / três meses / seis meses--time 30 / 90 / 180
N itens / os N primeiros / quero N--limit N

Valores padrão: sort=0, time=0, limit=10.

⚠️ Não confunda --sort da busca com --sort dos vídeos do criador: o primeiro é "relevância / mais curtidas", o segundo é "mais recentes / mais populares".

Qualquer parâmetro com valor inválido que retorne ao padrão será listado no array warnings do JSON de saída. Isso deve ser exibido ao usuário, não tratado como se o valor original tivesse sido aceito.


4. Modo de Execução

Documentação completa de parâmetros em references/options.md; Schemas em nível de campo disponíveis nos 6 arquivos JSON Schema (draft-07) em assets/.

# Busca por palavra-chave
node scripts/tiktok/search-cli.js --keyword "IA" --sort 1 --limit 20
node scripts/tiktok/search-cli.js --keyword "modelo de IA" --time 7 --limit 20

# Vídeos do criador
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

# Comentários do vídeo
node scripts/tiktok/comment-cli.js --url "https://www.tiktok.com/@username/video/1234567890123456789" --limit 40

Formatos de Entrada Aceitos

  • Criador: https://www.tiktok.com/@username, link com parâmetros https://www.tiktok.com/@username?lang=en, ou author_sec_uid diretamente
  • Vídeo: https://www.tiktok.com/@username/video/<id>, link curto, ou ID do vídeo <id>

Disciplina de Execução

  • Considere apenas stdout como saída legível por máquina (JSON puro); banners, progresso e logs de erro vão para stderr, não os misture na análise.
  • --limit único recomendado ≤ 1000.
  • Não faça retentativas automáticas com condições mais amplas se um resultado vier vazio: primeiro informe o resultado vazio ao usuário, deixando que ele decida se deseja trocar de palavra-chave ou aumentar --time.

5. Contrato de Saída (Leitura Obrigatória para IA)

Todas as saídas seguem o mesmo envelope, com estrutura idêntica para sucesso e falha:

{
  "status": "success | empty | error",
  "error_code": "OK | NO_MATCH | AUTH_REQUIRED | INVALID_KEYWORD | ...",
  "message": "Descrição legível por 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": ["Quantidade 99999 inválida, retornada para 10"]
}

5.1 Significado de status

statusSignificadoresultsO Que Fazer
successDados obtidosArray não vazioAnalise diretamente
emptyRequisição bem-sucedida, mas sem dadosnullConsidere resultado válido. Informe ao usuário que nada foi encontrado, sem tratar como falha
errorFalha na requisiçãonullTrate de acordo com error_code, não invente dados

5.2 Códigos de Saída

CódigoSignificadoComportamento do Agente
0Sucesso (success ou empty)Continue analisando
1Erro de execução (rede / timeout / exceção de API / parâmetro inválido)Exiba message, pergunte se o usuário deseja tentar com parâmetros diferentes
3AUTH_REQUIRED: Token ausente ou formato incorretoPare imediatamente, instrua a configurar GUAIKEI_API_TOKEN, proibido tentar novamente

5.3 Tratamento de Códigos de Erro

error_codeTratamento
AUTH_REQUIREDPare e instrua a configurar o Token. Proibido tentar novamente ou modificar parâmetros para contornar
INVALID_KEYWORDInforme que a palavra-chave deve ter 2–100 caracteres e não pode conter < > " ' & nem links http
NO_MATCHResultado vazio válido. Sugira trocar de palavra-chave ou aumentar --time
NETWORK_ERRORJá possui retry embutido; se ainda falhar, sugira verificar a rede, com no máximo 1 tentativa manual
TIMEOUT_ERRORJá possui retry embutido; se ainda falhar, sugira reduzir --limit e tentar novamente
Outros (códigos do servidor)Exiba error_code + message como estão, sem adivinhar o significado

5.4 warnings Devem Ser Exibidos

Quando parâmetros inválidos são automaticamente revertidos (ex.: --sort 9, --limit 99999), o array warnings explicará "qual parâmetro foi alterado para quê". Informe isso exatamente ao usuário, não finja que o parâmetro original foi aceito.

5.5 Comportamentos Proibidos

  • ❌ Não invente, não complete, não preencha dados com base em memória.
  • ❌ Após receber AUTH_REQUIRED, não tente novamente, não mude de script, não altere parâmetros.
  • ❌ Não interprete empty como outra conclusão além de "o conteúdo solicitado pelo usuário não existe" (não significa que a API está quebrada).
  • ❌ Não amplie automaticamente as condições de busca sem consentimento do usuário.

6. Sugestões de Consumo dos Resultados (Melhore a Qualidade Final)

Após obter results, organize a saída de acordo com o objetivo original do usuário, em vez de exibir o JSON bruto:

  • Pesquisa de Tópicos → Ordene por digg_count decrescente, pegue o Top N, resuma padrões de títulos, hashtags e distribuição de duração
  • Monitoramento de Concorrentes → Ordene por create_time para ver frequência de postagens, calcule taxa de atualização e proporção de virais
  • Análise de Comentários → Ordene por digg_count, agrupe comentários com mais curtidas para análise de sentimento, exiba proporção de positivos/negativos
  • Seleção de Influenciadores → Cruze author_nickname, média de interações e frequência de postagens para gerar uma lista de candidatos
  • Precisa de Registro → Cada execução salva automaticamente um log; o caminho está na linha "Salvo em …" do stderr

7. Segurança e Conformidade (Trust)

  • Somente Leitura: Não faz login em contas do TikTok, não executa nenhuma operação de escrita (publicar, curtir, comentar, seguir, enviar mensagem privada). Sem risco de bloqueio por violação de regras.
  • Mínimos Privilégios: Requer apenas uma variável de ambiente GUAIKEI_API_TOKEN para a operação; não lê outros arquivos locais, não escreve fora do diretório da skill (logs vão para o diretório temporário do sistema).
  • Proteção de Credenciais: O Token é lido apenas da variável de ambiente, nunca escrito no stdout, logs ou mensagens de erro.
  • Escopo de Dados Enviados (Importante Saber): Durante a chamada, os seguintes dados são enviados para www.guaikei.com: seu API Token, a palavra-chave de busca ou URL/ID de destino, além do nome da skill e versão do Node.js. Nenhuma outra informação local é coletada.
  • Conformidade de Dados: Apenas dados publicamente visíveis do TikTok são coletados (apelido, vídeos públicos, comentários públicos). Não inclui números de telefone, localização, mensagens privadas ou outros campos privados. Os dados são apenas para análise interna pessoal ou da equipe; antes de publicar ou usar comercialmente, verifique as autorizações e faça anonimização de apelidos, etc.
  • Sem Dependências de Terceiros: Utiliza apenas módulos nativos do Node.js (https, fs, path, os, querystring). Sem dependências npm, sem carregamento remoto de scripts, sem eval ou child_process.

8. Perguntas Frequentes

ProblemaCausa e Solução
Código de saída 3 / AUTH_REQUIREDToken não configurado ou formato incorreto (deve ter 16–256 caracteres alfanuméricos, sublinhados ou hífens)
Resultado da busca vazioTroque para uma palavra-chave mais genérica ou use --time 0 para remover o filtro de tempo; empty é um resultado normal, não um erro
Resultados com menos itens que --limitO servidor não tem mais dados para retornar ou o limite máximo foi atingido; reduza para ≤ 1000 e busque em lotes
Timeout constanteReduza --limit e tente novamente; o script já possui retry com backoff exponencial
Quer "vídeos mais populares" mas recebe ordem cronológicaNo post-cli, use --sort 1
Parâmetros não surtiram efeito / ordenação diferente da esperadaVerifique warnings na saída; parâmetros inválidos são silenciosamente revertidos para o padrão
Onde está o arquivo de log?Veja a linha "Salvo em …" no stderr (diretório temporário do sistema: tiktok-guaikei/logs/<data>/)

9. Ambiente e Suporte

Habilidades Relacionadas