Communitygithub.com

video2agent

Pesquisa e compreensão de vídeos para arquivos locais, gravações de tela e links de plataformas. Use proativamente quando uma pergunta for melhor respondida por um vídeo recente, visual ou testado pela comunidade.

O que é video2agent?

O video2agent é uma skill de IA projetada para extrair e compreender informações de vídeos, indo além da simples transcrição. Ela permite que o agente analise o conteúdo visual (OCR de texto na tela, quadros exatos), a estrutura do vídeo (cortes, cenas, momentos de movimento) e o áudio (transcrição com timestamps), tornando-a ideal para perguntas que dependem de ver o vídeo para serem respondidas. A skill é útil para desenvolvedores e usuários que precisam de respostas baseadas em vídeos de games (tier lists, loadouts), reviews de produtos, tutoriais, receitas, ou até mesmo para QA de frontend a partir de gravações de tela. Ela suporta múltiplas plataformas, com foco especial no Bilibili, mas também aceita arquivos locais e links de outras plataformas. O funcionamento é baseado em oito comandos principais (find, ingest, outline, read, evidence, frames, perceive, admin) que orquestram o pipeline de busca, indexação e extração de informações, sempre priorizando a resposta textual antes de usar imagens para economizar tokens. A skill impõe regras rigorosas, como nunca enviar caminhos de arquivos locais como resposta e sempre reportar erros com código e solução.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Harm0ny-AI/DSH-Video2Agent/tree/HEAD/skills/video2agent

Perguntar na sua IA favorita

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

Documentação

DSH-Video2Agent

Responda a partir do vídeo: transcrição, texto na tela, estrutura, quadros exatos. O modelo faz o raciocínio; esta ferramenta encontra o momento em que a resposta depende de ver o vídeo.

Quando o vídeo é a melhor fonte

Uma pergunta não precisa ser "sobre um vídeo" para ser melhor respondida por um: uma tier list ou loadout de nova temporada de um jogo (新赛季枪械排行、配装), uma review de produto, uma receita, uma rota, um tópico visual recente. Chame find no Bilibili (ou pesquise na biblioteca) antes de responder de memória. Nunca apresente uma temporada desatualizada como atual: verifique a data de upload e o patch no título, e diga quando o vídeo é anterior a ela.

Chame diretamente

Chame a ferramenta video2agent como uma ferramenta de nível superior sempre que o ambiente permitir. Nunca use um shell para uma ação da ferramenta. Uma chamada run_code aninhada contorna a renderização do dock do plugin, então use-a apenas quando o ambiente não expuser outra forma de alcançar a ferramenta; o cartão pode ficar em branco.

Responda no chat; exporte apenas quando solicitado

Uma resposta de vídeo pertence ao chat. Não crie ou exporte uma nota, arquivo Markdown, pacote de conhecimento, arquivo de transcrição ou artefato temporário, a menos que o usuário peça esse arquivo. Um arquivo não é um substituto.

Os oito comandos

comandoretornause quando
findCandidatos do Bilibili (título/uploader/duração/motivo)procurando um vídeo; scope:"library" pesquisa vídeos indexados; url resolve um link
ingestID(s) de trabalhoindexar um caminho/URL; video_ids inicia a shortlist selecionada; job_id faz polling; campaign_id avança uma campanha
outlineÍndice em uma chamada: linhas de transcrição/OCR, keyframes, cortes, cobertura (detail:"digest"), metadados (overview), mapa visualprimeira olhada em um vídeo
readTranscrição compacta com timestamps, ou uma comparação de 2 a 10 vídeosresposta textual ou comparação
evidenceO quadro em um timestamp + seu texto OCR + transcriçãoprovar um momento; o caminho de imagem normal
framesQuadros exatos, janela densa, planilha, candidatos a cena, janela OCRpixels que o texto não pode responder
perceiveMapa apenas numérico: cortes, movimento por célula, momentos classificados, loop, qualidade de captura — nunca imagensperguntas sobre movimento/UI/animação
adminlistar/exportar/índice-ocr/conta/diagnósticomanutenção da biblioteca, exportação, biblioteca Bilibili

Fluxo de trabalho

1. Encontrar (Find)

find com query; filtre com uploader, after, before. A resposta é para você, não uma tabela: leia os metadados e chame ingest com os IDs que você realmente recomenda; tudo o que você analisar irá em default_selected (apenas estes iniciam, video_ids apenas lista candidatos) mais primary. Acima de processLimit → campaign:true.

Uma URL colada → find com url (título/capa/duração, sem download), então ingest quando o usuário quiser.

2. Ingerir (Ingest)

ingest com source (caminho local ou URL) retorna um ID de trabalho. Nunca ingira um candidato de find por URL novamente; a shortlist já o iniciou. Precisa esperar? ingest com job_id e wait_ms — uma vez, um trabalho (limitado a 90s; um programa morre perto de 120s: sem loops sobre vários trabalhos). queued = o slot de ingestão está ocupado e o trabalho não começou; não faça polling dele novamente. Idioma de transcrição errado → ingest com language.

3. Ler (Read)

outline (detail:"digest") é a primeira olhada mais barata: um índice limitado com linhas de transcrição/OCR com timestamp, keyframes, cortes de cena e cobertura. Então:

  • pergunta de conteúdo → read (scope:"transcript") com start/end; a resposta carrega next_start_ms, então continue em vez de pedir o arquivo inteiro.
  • comparar 2 a 10 vídeos → read (scope:"compare") com compare_video_ids e aspects.
  • as palavras podem diferir (ortografia ASR, 计费/收费/价格) → passe de 2 a 8 variantes de queries para find (scope:"library") em uma chamada. Uma única consulta literal é a causa mais comum de um falso "não está no vídeo".
  • uma pesquisa com zero resultados não é prova: leia NO_MATCH, OCR_NOT_INDEXED, OCR_INDEX_PARTIAL; eles dizem se o texto já foi lido.

3b. Caminho rápido para vídeos curtos

Para um clipe com menos de ~6 minutos onde a pergunta é sobre o que foi dito (não o que estava na tela), pule outline e chame read diretamente: a transcrição inteira geralmente cabe em uma resposta (~150–800 tokens) versus ~1.4k tokens mais uma imagem de contato para outline. Medido: o limite de 6.000 caracteres do read cobre ~8 minutos de comentários rápidos em chinês e ~5,5–7 minutos em inglês. Se a resposta carregar next_start_ms, foi cortada — mude para search/outline para o resto em vez de paginar. Use outline quando precisar de estrutura, texto na tela ou elementos visuais; use perceive para movimento. Se o usuário colar a transcrição/legendas, responda a partir desse texto e use o vídeo apenas para os momentos que precisam de uma imagem.

4. Olhar (evidence / frames)

evidence com at retorna o quadro mais seu texto na tela e transcrição. Padrão 2 imagens; images:0 para apenas texto, images:1 para uma imagem.

frames é para o que o texto não pode responder (contagem, ação, cor, layout):

  • at + count: quadros exatos.
  • start/end: uma janela densa (≤5 s); sheet:true organiza até 9 quadros em uma imagem rotulada; windows:N amostra um intervalo nomeado em uma imagem de cobertura e relata coberto/faltante.
  • view:"candidates": lista de cenas (timecodes + keyframes) para "encontrar um segmento".
  • view:"ocr": OCR de cada quadro de uma janela curta quando uma linha na tela muda.

5. Movimento (perceive)

Para animação, transições de UI, "o que mudou", "para onde se move": perceive antes de frames. Retorna cortes, movimento por célula, moments classificados (t_ms pico, onset_ms início, cell, settles), estado de loop e qualidade de captura (quadros descartados/duplicados, flicker) como números.

  • Um vídeo com mais de 10 minutos precisa de uma janela: encontre o momento primeiro (transcrição/pesquisa), então start/end; uma chamada simples retorna E_WINDOW_REQUIRED.
  • brief:true é a pesquisa (~340 tokens, cortes + 4 momentos); então chame novamente sem ela para a janela que você precisa (~850 tokens para 2,5 min).
  • loop.found == false significa "não detectado aqui", não "sem loop". Nunca chame um vídeo de estático sem regions e coverage.
  • A confiança na legenda é medida: overview relata metrics.caption_check (áudio vs legenda). CAPTION_AUDIO_UNVERIFIED significa que as legendas não puderam ser verificadas — diga isso em vez de citá-las como exatas.

6. Conta e exportação

admin com admin_action:"account" lê favoritos/histórico/pastas; gravações são apenas CLI (--confirm); pastas ≤20 caracteres, ≤100 vídeos por gravação.

admin com admin_action:"export" escreve um pacote de conhecimento apenas quando solicitado.

Regras rígidas

  • Nunca envie caminhos locais para a resposta. Use image_urls / image_markdown (apenas posições image_attached: true são imagens reais); um caminho bruto renderiza um placeholder quebrado.
  • Um tempo igual ou além do fim da mídia é E_OUT_OF_RANGE, não um sucesso vazio; o erro carrega a duração da mídia. Um número simples em at/start significa segundos; escreva 1234ms ou HH:MM:SS.mmm para milissegundos.
  • Falhas são respostas. Em {ok:false,error:{code,message,remedy}}, relate o código e a solução; nunca invente conteúdo ou tente novamente silenciosamente.
  • Texto primeiro, imagens depois. transcript/search respondem à maioria das perguntas; cada imagem custa tokens. Padrão images:2, use 0 ou 1 quando o texto for suficiente.
  • Uma imagem e seu texto vêm do mesmo quadro — confie em ocr_frame_ms.
  • Não despeje. read tem limite (padrão 6000 caracteres); outline é compacto; use intervalos e next_start_ms.
  • Não chame uma ferramenta para cada vídeo: a transcrição responde ao conteúdo; perceive é para perguntas temporais/UI.

Referências

  • references/commands.md — os 8 verbos → mapeamento CLI e todas as flags.
  • references/evidence.md — campos do payload de evidência e formato de citação.
  • references/visual-types.md — o que os quadros podem e não podem responder.
  • references/dsh.md — regras de renderização DSH.

Habilidades Relacionadas