🎯 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.
| Funcionalidade | Script de Entrada | Parâmetro Obrigatório | Retorno |
|---|---|---|---|
| Busca por Palavra-chave | scripts/tiktok/search-cli.js | --keyword | Lista de vídeos: autor, curtidas/comentários/compartilhamentos/favoritos, tags, URL do vídeo |
| Vídeos do Criador | scripts/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ídeo | scripts/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_TOKENconfigurada. Se não configurada, todos os comandos retornam código de saída3eerror_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ário | Script | Palavras-Chave de Decisão |
|---|---|---|
| Pesquisar por palavra-chave, encontrar conteúdo ou virais | search-cli | pesquisar / encontrar / palavra-chave / viral / mais popular |
| Ver vídeos / perfil / conta de um criador/influenciador | post-cli | vídeos / perfil / conta / criador / influenciador / KOL |
| Ver comentários de um vídeo específico | comment-cli | comentários / feedback / opiniões do público |
3.1 Regras de Desambiguação (Obrigatório Seguir)
- 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.
- Se houver "palavra-chave" e não houver "comentário" →
- 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). - 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ário | Parâ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
--sortda busca com--sortdos 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âmetroshttps://www.tiktok.com/@username?lang=en, ouauthor_sec_uiddiretamente - 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
| status | Significado | results | O Que Fazer |
|---|---|---|---|
success | Dados obtidos | Array não vazio | Analise diretamente |
empty | Requisição bem-sucedida, mas sem dados | null | Considere resultado válido. Informe ao usuário que nada foi encontrado, sem tratar como falha |
error | Falha na requisição | null | Trate de acordo com error_code, não invente dados |
5.2 Códigos de Saída
| Código | Significado | Comportamento do Agente |
|---|---|---|
0 | Sucesso (success ou empty) | Continue analisando |
1 | Erro 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 |
3 | AUTH_REQUIRED: Token ausente ou formato incorreto | Pare imediatamente, instrua a configurar GUAIKEI_API_TOKEN, proibido tentar novamente |
5.3 Tratamento de Códigos de Erro
| error_code | Tratamento |
|---|---|
AUTH_REQUIRED | Pare e instrua a configurar o Token. Proibido tentar novamente ou modificar parâmetros para contornar |
INVALID_KEYWORD | Informe que a palavra-chave deve ter 2–100 caracteres e não pode conter < > " ' & nem links http |
NO_MATCH | Resultado vazio válido. Sugira trocar de palavra-chave ou aumentar --time |
NETWORK_ERROR | Já possui retry embutido; se ainda falhar, sugira verificar a rede, com no máximo 1 tentativa manual |
TIMEOUT_ERROR | Já 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
emptycomo 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_countdecrescente, pegue o Top N, resuma padrões de títulos, hashtags e distribuição de duração - Monitoramento de Concorrentes → Ordene por
create_timepara 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_TOKENpara 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, semevalouchild_process.
8. Perguntas Frequentes
| Problema | Causa e Solução |
|---|---|
| Código de saída 3 / AUTH_REQUIRED | Token não configurado ou formato incorreto (deve ter 16–256 caracteres alfanuméricos, sublinhados ou hífens) |
| Resultado da busca vazio | Troque 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 --limit | O servidor não tem mais dados para retornar ou o limite máximo foi atingido; reduza para ≤ 1000 e busque em lotes |
| Timeout constante | Reduza --limit e tente novamente; o script já possui retry com backoff exponencial |
| Quer "vídeos mais populares" mas recebe ordem cronológica | No post-cli, use --sort 1 |
| Parâmetros não surtiram efeito / ordenação diferente da esperada | Verifique 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
- Ambiente: Node.js ≥ 16.14.0, Windows / macOS / Linux; necessário
GUAIKEI_API_TOKEN. - Site oficial: Site de Análise de Concorrência TikTok (ative seu Token, consulte uso e documentação da API).
- Histórico de mudanças: references/changelog.md