🎯 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.
| Capacidade | Script de Entrada | Parâmetro Obrigatório | Retorno |
|---|---|---|---|
| Pesquisa por Palavra-chave | scripts/tiktok/search-cli.js | --keyword | Lista de vídeos: autor, curtidas/comentários/compartilhamentos/salvamentos, hashtags, URL de reprodução |
| Postagens do Criador | scripts/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ídeo | scripts/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_TOKENdeve estar configurada. Se não configurada, todos os comandos retornam código de saída3,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ário | Script | Palavras-chave para Decisão |
|---|---|---|
| Pesquisar por palavra-chave, encontrar conteúdo, encontrar virais | search-cli | pesquisa / encontrar / palavra-chave / viral / mais popular |
| Ver postagens/perfil/conta de um criador/influenciador | post-cli | postagens / perfil / conta / criador / influenciador / KOL |
| Ver comentários/respostas de um vídeo específico | comment-cli | comentários / respostas / opiniões na seção de comentários |
3.1 Regras de Desambiguação (Devem Ser Seguidas)
- Quando aparece apenas o termo "vídeo", não assuma
post-cliautomaticamente.- 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.
- Se há "palavra-chave" e não há "comentário" →
- 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). - 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ário | Parâ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
--sortda pesquisa com--sortdas 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 comohttps://www.tiktok.com/@username?lang=en, ou diretamenteauthor_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
| status | Significado | results | O que fazer |
|---|---|---|---|
success | Dados obtidos | Array não vazio | Analisar diretamente |
empty | Requisição bem-sucedida, mas nenhum dado encontrado | null | Considerar como resultado válido, informar ao usuário que não encontrou, não como falha |
error | Falha na requisição | null | Tratar conforme error_code, não inventar dados |
5.2 Códigos de Saída
| Código de Saída | Significado | Comportamento do Agente |
|---|---|---|
0 | Sucesso (success ou empty) | Continuar análise |
1 | Erro 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 |
3 | AUTH_REQUIRED: Token ausente ou formato incorreto | Parar imediatamente, instruir a configurar GUAIKEI_API_TOKEN, proibido tentar novamente |
5.3 Tratamento de Códigos de Erro
| error_code | Tratamento |
|---|---|
AUTH_REQUIRED | Parar e instruir a configurar Token. Proibido tentar novamente ou alterar parâmetros para contornar |
INVALID_KEYWORD | Informar que a palavra-chave deve ter 2–100 caracteres, não pode conter < > " ' & nem links http |
NO_MATCH | Resultado vazio válido, sugerir mudar palavra-chave ou ampliar --time |
NETWORK_ERROR | Já possui retry embutido; se ainda falhar, instruir a verificar a rede, no máximo 1 tentativa manual |
TIMEOUT_ERROR | Já 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
emptycomo 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_countem ordem decrescente, pegar os Top N, resumir padrões de títulos/hashtags/distribuição de duração - Monitoramento de concorrentes → Ordenar por
create_timepara 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_countpara 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, semeval/child_process.
8. Perguntas Frequentes
| Fenômeno | Causa e Tratamento |
|---|---|
| Código de saída 3 / AUTH_REQUIRED | Token não configurado ou formato incorreto (deve ter 16–256 caracteres alfanuméricos, sublinhados e hífens) |
| Resultado de pesquisa vazio | Tente 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 --limit | O servidor não tem mais dados para retornar, ou o limite único foi atingido; reduza para ≤ 1000 e busque em lotes |
| Sempre timeout | Reduza --limit e tente novamente; o script já possui retry com backoff exponencial |
| Quer ver "postagens mais quentes" mas veio ordem cronológica inversa | No post-cli, use --sort 1 |
| Parâmetro não funcionou / ordenação diferente da esperada | Verifique 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
- Ambiente: Node.js ≥ 16.14.0, Windows / macOS / Linux; obrigatório
GUAIKEI_API_TOKEN. - Site oficial: Site oficial do Análise de Concorrentes e Comparação de Marcas no TikTok (habilite o Token, consulte uso e documentação da interface).
- Registro de alterações: references/changelog.md