Communitygithub.com

why20261/tiktok-competitor-radar

Compare o desempenho de conteúdo em vídeo no TikTok, dados de interação e tendências de discussão entre marcas, com suporte a análise histórica para gerar diferenças, evidências e oportunidades acionáveis, ideal para análise de concorrentes, comparação de marcas, avaliação de mudanças periódicas, revisão de comunicação de marca e otimização de estratégia.

O que é tiktok-competitor-radar?

Esta skill é uma ferramenta técnica para agentes de IA (como Claude Code, Cursor, Codex) que fornece acesso programático a dados públicos do TikTok – vídeos, autores e comentários – através de três scripts de linha de comando: `search-cli.js` para pesquisa por palavra-chave (com ordenação por relevância/curtidas e filtro por tempo), `post-cli.js` para coletar postagens públicas de um criador (por URL do perfil ou nome de usuário, com ordenação recente/mais quente), e `comment-cli.js` para extrair comentários de um vídeo (por URL ou ID). Ela é útil para análises de concorrentes, monitoramento de tendências, triagem de influenciadores, análise de sentimento de comentários e pesquisa de tópicos virais, eliminando a necessidade de navegação manual no TikTok. A saída é sempre um JSON estruturado com metadados, resultados e avisos. A skill é puramente leitura (sem ações de postagem/curtida), requer a variável de ambiente `GUAIKEI_API_TOKEN` para autenticação e opera sem dependências npm, usando apenas módulos internos do Node.js. As plataformas suportadas são Windows, macOS e Linux, com Node.js ≥ 16.14.0.

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

Perguntar na sua IA favorita

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

Documentação

🎯 Análise de Concorrentes e Comparação de Marcas no TikTok

1. Visão Geral das Capacidades

💡Valor em uma frase: Um comando em linguagem natural para obter dados públicos de vídeos/autores/comentários do TikTok, gerando JSON estruturado – para seleção de influenciadores, análise de dados, pesquisa de mercado, monitoramento de reputação, tópicos virais, monitoramento de contas concorrentes, análise de sentimento em comentários e rastreamento de tendências – sem precisar navegar manualmente no TikTok.

CapacidadeScript de EntradaParâmetro ObrigatórioRetorno
Pesquisa por Palavra-chavescripts/tiktok/search-cli.js--keywordLista de vídeos: autor, curtidas/comentários/compartilhamentos/salvamentos, hashtags, URL de reprodução
Postagens do Criadorscripts/tiktok/post-cli.js--url (URL do perfil ou nome de usuário)Lista de postagens públicas daquele criador (com suporte a ordenação Recente/Mais Quente)
Comentários do Vídeoscripts/tiktok/comment-cli.js--url (URL do vídeo ou ID)Conteúdo do comentário, autor, curtidas, respostas

Público-Alvo

  • 🎯 Marcas — Aproveitar tendências para criar conteúdo de product placement
  • 🏢 Agências MCN — Descobrir contas com alto potencial de engajamento
  • ✍️ Criadores de Conteúdo — Encontrar benchmarks e inspiração criativa
  • 📊 Profissionais de Conteúdo — Análise de concorrentes e seleção de tópicos para relatórios semanais

Pré-requisito: Deve ser executado no diretório raiz da skill, e a variável de ambiente GUAIKEI_API_TOKEN deve estar configurada. Se não configurada, todos os comandos retornam código de saída 3, error_code=AUTH_REQUIRED – nesse caso, instrua o usuário a configurar o Token imediatamente, não tente novamente nem altere os 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ídeo/foto/autor/comentário/tendência).
  • O usuário deseja fazer pesquisa de tópicos virais, monitoramento de contas concorrentes, seleção de influenciadores, análise de sentimento de comentários, análise de estilo de conteúdo.
  • O usuário já forneceu palavras-chave do TikTok, URLs de vídeos, ou URLs de perfis de criadores, e deseja obter dados estruturados.
  • Após obter os dados, o usuário deseja continuar com resumo, comparação, ordenação, agrupamento, geração de relatórios/tabelas.

2.2 Não Deve Chamar

  • O usuário só quer texto/título/script, sem consultar dados do TikTok.
  • A plataforma não é TikTok, mas outra (Douyin, Xiaohongshu, Bilibili, Weibo, WeChat Official Accounts) → encaminhe para a skill correspondente. Esta skill só lida com TikTok.
  • Requer dados de login, privados ou ocultos → não suportado.
  • O usuário forneceu tanto palavras-chave quanto URLs identificáveis, e o objetivo não está claro → primeiro pergunte, não adivinhe.

2.3 Limites de Capacidade (Explícito que Não Faz)

Operações de escrita como publicar/curtir/comentar/seguir/mensagem privada não são suportadas; não faz login em nenhuma conta; não coleta campos privados como número de telefone, localização, mensagens privadas; não toma decisões de marketing pelo usuário – a responsabilidade é obter os dados, a análise fica para a camada superior.


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

Intenção do UsuárioScriptPalavras-chave para Decisão
Pesquisar por palavra-chave, encontrar conteúdo, encontrar viraissearch-clipesquisa / encontrar / palavra-chave / viral / mais popular
Ver postagens/perfil/conta de um criador/influenciadorpost-clipostagens / perfil / conta / criador / influenciador / KOL
Ver comentários/respostas de um vídeo específicocomment-clicomentários / respostas / opiniões na seção de comentários

3.1 Regras de Desambiguação (Devem Ser Seguidas)

  1. Quando aparece apenas o termo "vídeo", não assuma post-cli automaticamente.
    • Se há "palavra-chave" e não há "comentário" → search-cli (o usuário quer pesquisar esse tipo de vídeo).
    • Se há explicitamente "comentários/respostas deste vídeo" → comment-cli.
    • Só quando aparecer "postagens / perfil / conta / criador / influenciador" → post-cli.
  2. Comentários têm prioridade sobre postagens: Se a URL for /video/<id> e a pergunta for sobre comentários → comment-cli; se a pergunta for "as postagens desta pessoa" → post-cli (usando @username).
  3. Usuário forneceu URL /video/<id> mas pede "lista de postagens" → primeiro confirme se ele quer as postagens daquele autor ou os comentários daquele vídeo.

3.2 Regras de Inferência de Parâmetros

Fala do UsuárioParâmetro
Relevância / padrão--sort 0 (pesquisa)
Mais popular / mais curtido / viral / mais quente--sort 1 (pesquisa)
Postagens recentes / em ordem cronológica inversa--sort 0 (postagens)
Postagens mais quentes--sort 1 (postagens)
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 postagens / as N primeiras / quero N--limit N

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

⚠️ Não confunda --sort da pesquisa com --sort das postagens: o primeiro é "relevância / mais curtidas", o segundo é "mais recente / mais quente".

Se algum parâmetro for revertido por valor inválido, isso aparecerá no array warnings do JSON de saída, e deve ser exibido ao usuário como está, sem fingir que o parâmetro original foi aplicado.


4. Modo de Execução

Documentação completa de parâmetros em references/options.md; Schema de campos nos 6 JSON Schemas (draft-07) em assets/.

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

# Postagens 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, URL com parâmetros como https://www.tiktok.com/@username?lang=en, ou diretamente author_sec_uid
  • Vídeo: https://www.tiktok.com/@username/video/<id>, URL curta, ou diretamente o ID do vídeo <id>

Disciplina de Execução

  • Considere apenas a stdout como saída legível por máquina (JSON puro); banners / progresso / logs de erro estão todos na stderr, não misture com a análise.
  • Recomenda-se --limit ≤ 1000 por chamada.
  • Não retente automaticamente com condições mais amplas só porque o resultado veio vazio: primeiro informe o resultado vazio ao usuário, deixe que ele decida se quer mudar a palavra-chave ou ampliar --time.

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

Todas as entradas produzem um mesmo envelope, com estrutura consistente para sucesso e erro:

{
  "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, revertida para 10"]
}

5.1 Significado de status

statusSignificadoresultsO que fazer
successDados obtidosArray não vazioAnalisar diretamente
emptyRequisição bem-sucedida, mas nenhum dado encontradonullConsiderar como resultado válido, informar ao usuário que não encontrou, não como falha
errorFalha na requisiçãonullTratar conforme error_code, não inventar dados

5.2 Códigos de Saída

Código de SaídaSignificadoComportamento do Agente
0Sucesso (success ou empty)Continuar análise
1Erro de execução (rede/timeout/exceção de API/parâmetro inválido)Exibir message, perguntar ao usuário se deseja tentar com outros parâmetros
3AUTH_REQUIRED: Token ausente ou formato incorretoParar imediatamente, instruir a configurar GUAIKEI_API_TOKEN, proibido tentar novamente

5.3 Tratamento de Códigos de Erro

error_codeTratamento
AUTH_REQUIREDParar e instruir a configurar Token. Proibido tentar novamente ou alterar parâmetros para contornar
INVALID_KEYWORDInformar que a palavra-chave deve ter 2–100 caracteres, não pode conter < > " ' & nem links http
NO_MATCHResultado vazio válido, sugerir mudar palavra-chave ou ampliar --time
NETWORK_ERRORJá possui retry embutido; se ainda falhar, instruir a verificar a rede, no máximo 1 tentativa manual
TIMEOUT_ERRORJá possui retry embutido; se ainda falhar, sugerir reduzir --limit e tentar novamente
Outros (códigos do servidor)Exibir error_code + message como estão, não inferir significado

5.4 warnings Devem Ser Exibidos

Quando parâmetros inválidos forem automaticamente revertidos (ex.: --sort 9, --limit 99999), o array warnings explicará "qual parâmetro foi alterado para quê". Deve ser comunicado ao usuário exatamente como está, sem fingir que o parâmetro original foi aplicado.

5.5 Ações Proibidas

  • ❌ Não inventar, não completar, não preencher nenhum dado com base em memória.
  • ❌ Ao receber AUTH_REQUIRED, não tentar novamente, não trocar de script, não alterar parâmetros.
  • ❌ Não tratar empty como conclusão além de "o conteúdo solicitado pelo usuário não existe" (não significa que a interface está quebrada).
  • ❌ Não ampliar automaticamente as condições de pesquisa sem o consentimento do usuário.

6. Recomendações de Consumo dos Resultados (Melhorar Qualidade da Entrega Final)

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

  • Pesquisa de tópicos → Ordenar por digg_count em ordem decrescente, pegar os Top N, resumir padrões de títulos/hashtags/distribuição de duração
  • Monitoramento de concorrentes → Ordenar por create_time para ver ritmo de publicação, estatísticas de frequência de atualização e proporção de virais
  • Insights de comentários → Ordenar por digg_count para pegar comentários mais curtidos e fazer agrupamento de opiniões, gerar proporção positiva/negativa
  • Seleção de influenciadores → Cruzar author_nickname, engajamento médio, frequência de postagem, gerar lista de candidatos
  • Precisa arquivar → Cada execução salvará automaticamente um arquivo de log; o caminho está na linha "Salvo em …" na 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 como publicar/curtir/comentar/seguir/mensagem privada; sem risco de banimento por violação de regras.
  • Mínimos privilégios: Requer apenas uma variável de ambiente necessária para o negócio: GUAIKEI_API_TOKEN; não lê outros arquivos locais, não escreve fora do diretório da skill (logs vão para diretório temporário do sistema).
  • Proteção de credenciais: Token lido apenas da variável de ambiente, não é escrito na stdout, nem em logs, nem aparece em mensagens de erro.
  • Escopo de dados externos (obrigatório saber): Ao chamar, enviará para www.guaikei.com: seu API Token, palavra-chave de consulta ou URL/ID alvo, além do nome da skill e versão do Node. Nenhuma outra informação local é coletada.
  • Conformidade de dados: Apenas dados publicamente visíveis do TikTok são obtidos (apelido, postagens públicas, comentários públicos). Não inclui campos privados como número de telefone, localização, mensagens privadas. Os dados são apenas para análise pessoal/da equipe; antes de publicar externamente ou usar comercialmente, verifique a autorização adequada e realize anonimização de apelidos de usuários.
  • Sem dependências de terceiros: Usa apenas módulos internos do Node.js (https/fs/path/os/querystring), sem dependências npm, sem carregamento remoto de scripts, sem eval/child_process.

8. Perguntas Frequentes

FenômenoCausa e Tratamento
Código de saída 3 / AUTH_REQUIREDToken não configurado ou formato incorreto (deve ter 16–256 caracteres alfanuméricos, sublinhados e hífens)
Resultado de pesquisa vazioTente uma palavra-chave mais genérica, ou --time 0 para abrir o intervalo de tempo; empty é um resultado normal, não um erro
Quantidade de resultados menor que --limitO servidor não tem mais dados para retornar, ou o limite único foi atingido; reduza para ≤ 1000 e busque em lotes
Sempre timeoutReduza --limit e tente novamente; o script já possui retry com backoff exponencial
Quer ver "postagens mais quentes" mas veio ordem cronológica inversaNo post-cli, use --sort 1
Parâmetro não funcionou / ordenação diferente da esperadaVerifique os 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 …" na stderr (diretório temporário do sistema tiktok-guaikei/logs/<data>/)

9. Ambiente e Suporte

Habilidades Relacionadas