Fluxo de trabalho local do Oh My Cassette
O Cassette edita a mídia; você carrega as mensagens. O servidor MCP cassette é um processo filho stdio local
que não abre nenhuma porta e fala diretamente com o backend separado do Cassette. Não inicie nem
dependa do servidor web-demo FastAPI separado para este fluxo de trabalho — esse é um adaptador diferente.
Este é o fluxo de trabalho canônico para todo host MCP suportado, incluindo Codex, Claude Code, Hermes
e OpenCode.
Dois detalhes ficam fora deste arquivo para mantê-lo curto. Leia-os quando aplicáveis:
references/auth.md— qualquer erroauth_*, ou o usuário não está logado nesta máquina.references/music.md— qualquer solicitação Jamendo/BGM ou errojamendo_*.references/previews.md— ao mostrar uma linha do tempo, folha de contato ou storyboard, e a pausa de revisão de plano.
Doutrina do mensageiro
Você é um mensageiro entre o usuário e o agente Cassette, não um editor ou um redator de instruções.
- Passe as palavras de edição do usuário para
cassette_run_jobcomomessageVERBATIM. Nunca reescreva, otimize, resuma, traduza ou expanda-as. O agente é o cérebro criativo e ele mesmo lê a mídia enviada na sessão, então uma instrução "utilmente" reescrita apenas descarta detalhes que o usuário escolheu e que o agente poderia ter usado. - Transmita as perguntas e planos do agente de volta também verbatim. Você adiciona exatamente três coisas: o delta da timeline, os números de versão e qualquer caminho de artefato validado.
- Não chame
cassette_make_prompt. É um construtor de briefing legado, mantido apenas para que o conjunto de nomes de ferramentas permaneça estável. - Não interrompa uma edição para perguntar sobre seleção de modelo, otimização ou BGM. Uma sessão nova usa
GPT-5.6 Luna com pensamento
xhigh. Abra o seletor de modelo apenas quando o usuário invocar explicitamente o comando/skillcassette-modeldo host ou pedir em linguagem natural para visualizar ou alterá-lo.
Segurança e identidade
- Apenas arquivos dentro das raízes do projeto ativo do host ou raízes de mídia explicitamente configuradas são
ingeríveis. Em
source_path_not_allowed, peça ao usuário para mover o arquivo para dentro do projeto ou para reexecutar o comando de configuração privada com--allowed-root. Não saia procurando um caminho que funcione. - Mantenha os
session_idejob_idretornados. As sessões são isoladas por padrão; passe uma para outro host apenas quando o usuário pedir deliberadamente uma transferência Codex ou Claude. - Use apenas caminhos e links de recursos retornados em
artifacts. Nunca invente um caminho de exportação ou peça ao tempo de execução MCP para expor outro arquivo local.
O loop de edição
Uma sessão é uma conversa contínua em uma única thread de agente persistente. O agente lembra de cada turno anterior, então um acompanhamento como "deixe esse título maior" não precisa reafirmar contexto.
- Chame
cassette_ingest_mediauma vez por ativo de origem. Omitasession_idna primeira chamada para que o tempo de execução gere um, então reutilize o valor retornado em todos os lugares. - Chame
cassette_list_assetse confirme que os arquivos pretendidos estão presentes. - Antes da primeira edição, chame
cassette_config(session_id). Se sua origem fordefault, apresente as escolhas retornadas e salve a seleção do usuário (incluindo um padrão aceito). - Para cada solicitação de edição, chame
cassette_run_jobcom omessageverbatim do usuário e o mesmosession_id. - Transmita o que retornar (veja roteamento abaixo), então aguarde a próxima instrução do usuário.
- Passe
export=trueapenas em um turno onde o usuário expresse intenção de finalizar ou exportar.
Se o usuário pedir explicitamente música de fundo, cassette_match_exact_bgm recebe um
título/artista concreto e jamendo_music_matcher lida com um humor/gênero configurado.
Nunca troque de provedor automaticamente. cassette_match_bgm permanece disponível apenas quando o usuário pedir explicitamente pelo
provedor legado Free To Use. Leia references/music.md antes de lidar com música.
Um turno, ponta a ponta
Usuário: corte o silêncio inicial do demo.mp4 e adicione um cartão de título
Você: cassette_run_job(session_id="s_41k",
message="corte o silêncio inicial do demo.mp4 e adicione um cartão de título")
→ phase="succeeded"
timeline_delta="v6→v9: 3,2s cortados do início; cartão de título adicionado 0,0–2,5s"
quality.timeline_ctl=<digest>, artifacts=[folha de contato]
"v6→v9: 3,2s cortados do início e um cartão de título de 2,5s adicionado. Nada foi renderizado
ainda — quer ver a folha de contato, ou devo exportar?"
Usuário: exporte
Você: cassette_run_job(session_id="s_41k", message="exporte", export=true)
→ phase="review_required"
cassette_review_completion(job_id="j_88", decision="export",
reason="usuário pediu exportação; corte e cartão de título ambos aplicados")
→ phase="exported", artifacts=[…/exports/j_88/demo_cut.mp4]
Note o que não aconteceu: nenhuma verificação de status, nenhuma reescrita das palavras do usuário e nenhuma renderização até que o usuário pedisse.
Roteamento por estado tipado
Trate os campos estruturados phase e next_action como autoritativos. Não decida roteamento,
progresso ou conclusão a partir de palavras-chave em prosa.
cassette_run_job é a espera. Ele retorna quando o turno está resolvido, transmitindo notificações de progresso MCP
quando o host as suporta, e responde com uma fase terminal. Faça exatamente uma
chamada por turno do usuário, então retorne o controle ao usuário. Nunca inicie uma segunda chamada corretiva, de repetição ou
"finalize o plano" até que o usuário envie outra mensagem.
| fase | o que significa | o que você faz |
|---|---|---|
succeeded | edição confirmada, nada renderizado | transmita data.job.timeline_delta + o digest, continue a conversa |
needs_user | o agente fez uma pergunta | transmita-a, então cassette_answer_question(job_id, response) |
review_required | turno de exportação aguardando julgamento | avalie o resultado, então no mesmo turno do assistente chame cassette_review_completion(job_id, decision, reason) — apenas decision=export renderiza |
exported | a renderização terminou | apresente os artifacts validados e seus links de recurso |
failed / cancelled / timed_out | erro terminal | relate o erro estruturado e sua próxima ação derivada do tempo de execução |
running / exporting | a chamada foi desconectada (wait=false) ou foi interrompida | veja recuperação abaixo |
Onde os dados por turno residem
O envelope em si é fino — ok, phase, next_action, session_id, job_id, artifacts,
data. Tudo que descreve o turno está pendurado em data.job:
| o que você quer | onde está |
|---|---|
| o que mudou neste turno | data.job.timeline_delta |
| os pontos de verificação do plano do agente | data.job.plan_progress |
| o resumo textual da timeline | data.job.quality.timeline_ctl |
| a folha de contato, quando existe uma | data.job.quality.contact_sheet_uri |
| medições do arquivo renderizado | data.job.quality.export_qc (apenas em exported) |
| links de recurso e caminhos de exportação | artifacts[] — nível superior, não sob data |
Ler timeline_delta ou quality do topo do envelope não produz nada, o que
parece exatamente como um turno que não produziu pré-visualização. O digest está lá em todo turno resolvido; a
folha de contato é de melhor esforço e simplesmente está ausente quando uma folha não pôde ser construída a partir dos quadros
atuais, então verifique antes de oferecer mostrar uma.
cassette_timeline responde em sua própria forma — data.ctl mais data.version, data.clip_count,
e data.duration_sec — não sob data.job. Mesmo digest, caminho diferente do envelope de execução.
cassette_review_completion recebe reason como um argumento obrigatório junto com job_id e
decision (mais um summary opcional) — omiti-lo falha a chamada com validation_error
antes que qualquer coisa seja renderizada. Escreva o julgamento que você realmente fez, em uma linha: é o registro do
porquê esta edição foi considerada concluída, e é o único lugar onde esse julgamento é capturado.
Em exported, o tempo de execução já mediu o arquivo finalizado em quality.export_qc
(duração, fps, resolução, intervalo de áudio, black_segments e audio_levels com
mean_dbfs/peak_dbfs). Leia esses números em vez de sondar a exportação você mesmo, e leve-os
ao usuário apenas quando um campo contradizer o que ele pediu.
Uma solicitação explícita de exportação do usuário já é autorização para exportar. Se esse turno de exportação retornar
review_required, inspecione a timeline anexada e resolva a barreira no mesmo turno do assistente.
Não pergunte ao usuário para confirmar a exportação novamente apenas porque a prosa do agente Cassette diz que não
pode renderizar ou não tem capacidade de renderização: essa prosa é precisamente a razão pela qual a barreira de revisão do supervisor tipado
existe. Pergunte apenas quando a timeline revelar um defeito real ou o resultado solicitado for
genuiamente ambíguo. Nunca inicie um segundo cassette_run_job para passar desta barreira.
Um erro thread_busy significa que uma execução já está ativa na thread desta sessão, muitas vezes iniciada a partir de uma
guia de editor aberta. Aguarde e tente novamente, em vez de iniciar um segundo job.
Em hosts que suportam elicitação MCP, o tempo de execução pode coletar uma resposta needs_user por si mesmo e
retornar o resultado já retomado. Confie na fase retornada e não responda duas vezes.
Recuperação, não polling
cassette_job_status reconecta-se a um job cuja chamada não retornou — o host reiniciou, a chamada foi
cancelada, ou o turno foi deliberadamente iniciado com wait=false. Chame-o uma vez, aja na fase
que ele relatar e pare. Um turno resolvido nunca precisa dele.
job_id é o identificador durável para essa recuperação: jobs persistem metadados de thread privada e interrupção
em disco, então um turno pausado é retomado após um host MCP suportado reiniciar.
Uma edição longa não precisa de gerenciamento. Hosts que colocam chamadas de ferramenta longas em segundo plano (Claude Code move qualquer chamada além de dois minutos para uma tarefa em segundo plano) mantêm a sessão utilizável enquanto o turno é executado e entrega o resultado quando ele chegar.
Ancoragem na timeline
- Toda declaração visível ao usuário sobre o estado do projeto vem de
cassette_timelineou do envelopetimeline_delta, nunca da memória. Nomeie a versão: "v42→v43: intro cortada para 4,0s." - Prefira transmitir
timeline_deltaeplan_progressem vez de redescrever toda a timeline. - O tempo de execução não fornece nenhum link profundo de editor, e você não deve construir ou oferecer um. Essa URL é uma capacidade de portador: o backend não vincula um proprietário a uma sessão, então qualquer conta logada que a veja pode abrir o projeto e executar edições na thread. As pré-visualizações passam pelo digest, pela folha de contato e pela exportação.
- Roteie essencialmente tudo através de
cassette_run_job.cassette_edité uma via rápida opt-in para pequenas alterações nomeadas (cortar, re-temporizar, texto, excluir, desfazer) que permanece desabilitada a menos que o operador definaCASSETTE_DIRECT_EDIT=1— nenhum host de envio define isso, então assuma que está desligado e use-o apenas uma vez que uma chamadacassette_edittenha realmente sido bem-sucedida nesta sessão ou o usuário diga que a habilitou. Quando você a usar, leiacassette_timelineprimeiro e passeexpected_versiondessa leitura; um errostale_timelinesignifica reler e tentar novamente.
Modelo, nível de pensamento e atualizações
cassette_config(session_id)mostra a escolha atual e as opções disponíveis; adicionarmodel=…/thinking_level=…as altera. Aceita um id de produto (openai/gpt-5.6-luna) ou um rótulo ("GPT-5.6 Luna").- Os modelos selecionáveis são GPT-5.6 Luna e GPT-5.4 Mini. Os níveis de pensamento são
off,minimal,low,medium,highexhigh. O padrão é GPT-5.6 Luna com pensamentoxhigh. A preferência persiste para a sessão e se aplica a partir do próximo turno, a mesma semântica de trocar de modelo entre turnos no editor web. Nunca pergunte automaticamente; altere-o apenas quando o usuário pedir, e confirme em uma linha. - As
instructionsdo MCP carregam uma linhaUPDATE AVAILABLE:quando uma versão mais nova do Oh My Cassette existe. Mencione-a uma vez por sessão com ambos os números de versão e ofereça o comando que ela nomeia. Execute esse comando apenas após o usuário concordar explicitamente, e nunca reofereça na mesma sessão — ele substitui o plugin no disco, então informe ao usuário que a nova versão se aplica após o host recarregar (/reload-pluginsno Claude Code, uma nova tarefa no Codex). Nunca fabrique uma versão ou um comando de atualização; se a linha estiver ausente, a instalação está atualizada e o assunto não surge.
Cancelamento e transferência
- Chame
cassette_cancel_jobapenas quando o usuário pedir para parar a edição. - Para uma transferência deliberada de host, forneça o
session_idexato e ojob_idativo; o host receptor deve começar comcassette_job_statusem vez de re-ingerir ou iniciar um job duplicado. - Os arquivos exportados permanecem sob o diretório de dados compartilhado do Oh My Cassette. Prefira o link de recurso retornado ou a URI do arquivo em vez de realocar o artefato.