dbs-video-extract: Extração de Informações de Vídeos Curtos
Objetivo: processar o texto de compartilhamento de um mesmo vídeo curto por uma única entrada. O TikHub fornece dados estruturados do Douyin, Xiaohongshu e WeChat Channels; o Qingdou fornece a transcrição de áudio do vídeo curto. Por fim, retorna um resumo dos dados e o caminho do arquivo Markdown.
Verificar credenciais primeiro
Antes de qualquer extração, execute a verificação somente leitura:
python3 scripts/extract_video.py --check-keys
Processe de acordo com o credential_state:
| Estado | Capacidade | O que informar ao usuário |
|---|---|---|
complete | Dados e transcrição disponíveis | Ambas as partes podem ser executadas |
data_only | Apenas consulta de dados TikHub disponível | Só é possível obter dados do vídeo/conta, sem gerar transcrição de áudio |
transcript_only | Apenas transcrição Qingdou disponível | Só é possível obter a transcrição de áudio, sem consultar dados do TikHub |
unavailable | Nenhuma das partes disponível | Não é possível usar no momento; primeiro explique as credenciais, depois guie o usuário para compra e configuração |
Permite continuar com apenas uma chave, sem exigir que o usuário forneça a outra. Antes de executar, deixe claro qual parte pode ser resolvida e restrinja o modo padrão ao lado disponível. Se o usuário ainda solicitar both, mantenha o resultado obtido e marque o outro lado como "credencial ausente".
Se ambas as chaves estiverem ausentes, pare a extração. Não use termos como "API Key" ou "autenticação de interface" como conclusão. Primeiro, explique com a frase abaixo:
Para que este Skill funcione, é necessário ativar serviços externos de dados. A API Key é um token de uso fornecido pelo provedor após a ativação. Pode ser entendida como um passe exclusivo para o Skill acessar o serviço. Você não precisa entender os detalhes técnicos e não deve compartilhá-la no chat.
Em seguida, informe ao usuário: "Atualmente, nenhum dos dois serviços está ativado. Sem comprar e configurar pelo menos um, este Skill não pode ser usado." Depois, siga references/api-setup.md para concluir a seleção de requisitos, compra, salvamento de credenciais e teste de conexão.
Não faça pagamentos, aceite termos de serviço ou processe chaves completas para o usuário. Não peça ao usuário para enviar a chave para o chat. Os links de compra, orientação passo a passo, script de configuração segura e teste de conexão estão em references/api-setup.md.
Sempre que mostrar um endereço de compra ou recarga para o usuário, exiba o aviso abaixo exatamente como está, sem omitir ou alterar:
dbskill é um projeto gratuito e de código aberto, sem afiliação, parceria ou interesse financeiro com TikHub ou Qingdou. A recarga é uma decisão do usuário; todas as transações, serviços, controvérsias e riscos relacionados são de responsabilidade do usuário. Salvo disposição legal em contrário, dbskill não assume responsabilidade.
Não repita o aviso se o usuário não estiver em um fluxo de compra ou recarga.
Requisitos de diálogo quando faltam credenciais
Quando faltar qualquer serviço, a resposta deve seguir o caminho contínuo abaixo:
- Explique a API Key em linguagem simples;
- Peça ao usuário que escolha com base no resultado: funcionalidade completa, apenas dados ou apenas transcrição;
- Explique qual serviço precisa ser comprado para cada escolha e o que será perdido se comprar apenas um;
- Exiba o aviso legal fixo e, em seguida, o endereço de recarga correspondente;
- Oriente passo a passo: registrar/login, visualizar planos na página, recarregar, acessar o centro pessoal ou página de gerenciamento de chaves, e obter a credencial;
- Informe ao usuário que, após obter a credencial, não a envie para o chat; responda "TikHub recarregado", "Qingdou recarregado" ou "Ambos recarregados";
- Após o usuário informar que recarregou, oriente a executar o script de configuração segura no terminal local:
python3 scripts/configure_api_key.py tikhub
python3 scripts/configure_api_key.py qingdou
O script lerá a credencial ocultamente no terminal e a salvará em uma configuração local privada; a credencial completa não deve aparecer em comandos, respostas ou logs. Após salvar, execute --check-keys novamente até que o status correspondente fique disponível.
Não envie apenas um link de uma vez, nem presuma que o usuário sabe onde encontrar a credencial. Se os nomes das páginas do provedor mudarem, oriente com possíveis locais como "Centro Pessoal", "API Key", "Gerenciamento de Chaves", "Configurações do Desenvolvedor"; se ainda não encontrar, peça ao usuário que envie uma captura de tela da página com conta, saldo e credenciais ocultos, para continuar a localização.
Quando o usuário apenas invocar este Skill, sem fornecer um link ou especificar o tipo de resultado desejado, após a pré-verificação de credenciais, faça apenas duas coisas: explique a API Key e peça ao usuário que responda 1, 2 ou 3 para selecionar funcionalidade completa, apenas dados ou apenas transcrição. Após receber a escolha, exiba o aviso legal, o endereço de recarga correspondente e os passos de compra. Se o usuário já enviou um link de vídeo ou solicitou explicitamente extração completa, o padrão é funcionalidade completa, sem necessidade de perguntar novamente.
Execução padrão
Prefira usar a entrada padrão para evitar que caracteres especiais no texto de compartilhamento sejam interpretados pelo Shell:
python3 scripts/extract_video.py \
--output-dir "/caminho/absoluto/Transcrições de Vídeos Curtos" \
--stdin
O modo padrão é both:
- Extrair o link do texto de compartilhamento completo;
- De acordo com a plataforma do link, chamar o MCP do TikHub: Douyin suporta página inicial do usuário ou vídeo único; Xiaohongshu e WeChat Channels suportam vídeo único;
- Enviar o texto de compartilhamento completo para a API do Qingdou e fazer polling até obter a transcrição;
- Salvar a transcrição como
{diretório de saída}/{autor}/{título}.md; - Gerar um resumo JSON contendo status das credenciais, resumo dos dados do TikHub e caminho do arquivo de transcrição.
Se qualquer lado (TikHub ou Qingdou) falhar, continue com o outro lado e marque partial_success no resumo. Os resultados já obtidos não devem ser descartados devido a falha de um único lado.
Modos opcionais
Alterne apenas quando o usuário solicitar explicitamente um único lado, ou quando a pré-verificação confirmar que apenas um lado tem chave:
python3 scripts/extract_video.py --mode data --stdin
python3 scripts/extract_video.py --mode transcript --stdin
data: consulta apenas dados do TikHub, suporta Douyin, Xiaohongshu e WeChat Channels;transcript: extrai apenas a transcrição, suporta plataformas reconhecíveis pela API do Qingdou;both: executa ambos os lados simultaneamente.
Se a mesma fonte já existir, por padrão, a escrita da transcrição é ignorada para preservar a edição do usuário; use --overwrite se o usuário solicitar explicitamente a regeneração. Para obter a resposta completa do TikHub, use --raw-data.
Chaves e custos
O script lê as chaves na seguinte ordem:
- Variáveis de ambiente:
TIKHUB_API_KEY,QINGDOU_API_KEY; - Arquivo local especificado pelo usuário:
TIKHUB_API_KEYS_FILE,QINGDOU_API_KEYS_FILE; ~/.config/dbs/API_Keys.md;- Keychain do macOS:
dbs-tikhub-api-key,dbs-qingdou-api-key.
Não escreva chaves no Skill, parâmetros de comando, Markdown, Git ou logs. As consultas ao TikHub e transcrições pelo Qingdou podem gerar custos; informe o usuário antes de executar. Se o usuário já solicitou explicitamente a extração, não é necessário confirmar novamente.
Limites de dados
- O TikHub é responsável por perfil do vídeo/conta, estatísticas e metadados de mídia; para vídeos do Douyin, prioriza App V3; se não houver dados válidos, faz apenas 1 fallback para Web; Xiaohongshu usa App V2 para detalhes de nota de vídeo; WeChat Channels usa Channels V2 para detalhes do vídeo.
- O Qingdou é responsável pela transcrição de áudio. O conteúdo é salvo fielmente conforme retornado pela API, sem complementos, correções ou revisões de gírias.
- Atualmente, a análise de dados dedicada do TikHub suporta Douyin, Xiaohongshu e WeChat Channels; outras plataformas reconhecíveis pelo Qingdou ainda podem executar apenas extração de transcrição.
- Restrições de visibilidade (público, excluído, privado, direitos autorais) são baseadas no retorno da interface; não tente contorná-las.
- Não baixe mídia automaticamente, publique conteúdo, faça commit no Git ou envie.
Detalhes da chamada TikHub em references/tikhub-api.md; códigos de status e lógica de compatibilidade do Qingdou em references/qingdou-api.md. Leia apenas ao solucionar problemas ou manter a parte correspondente.
Entrega
Relate de forma concisa após a conclusão:
- Qual API Key está configurada e o escopo de capacidade disponível;
- Se a consulta de dados foi bem-sucedida, qual ferramenta MCP foi usada, se houve fallback App → Web;
- Dados principais do vídeo/conta;
- Se a transcrição foi bem-sucedida, o caminho absoluto do Markdown gerado ou ignorado;
- Motivo específico da falta de chave ou falha em um lado;
- Se a interface retornou explicitamente cobrança.
Não exiba API Key, batchId ou identificadores internos de solicitação desnecessários na resposta.
Finalize a tarefa atual e encerre. Apenas se o usuário perguntar explicitamente sobre o próximo passo, e o ambiente atual já tiver /dbs instalado, dê uma dica curta: "Se não souber o que fazer a seguir, digite /dbs."