zz-mv-gongzuotai · Coordenação de Projetos MV em um Único Skill

Posicionamento

Este é o skill de entrada único para todo o projeto MV.
O workbench serve apenas para exibição e coordenação; a geração é feita pelo agente invocando os scripts em scripts/.
O fluxo termina nos segmentos de vídeo: sem edição bruta, sem montagem, sem vídeo final. Os segmentos + handoff são passados para a próxima fase de edição.

O comando mvwb refere-se ao comando global instalado; se ~/.local/bin não estiver no PATH, use ~/.agents/skills/zz-mv-gongzuotai/start/mvwb (copiado com permissão de execução durante a instalação); se ainda assim não estiver disponível, use python3 ~/.agents/skills/zz-mv-gongzuotai/scripts/mvwb.py.

Workbench e Chaves (Regras Fixas)

O workbench é o arquivo estático workbench.html no projeto: abra diretamente com duplo clique / navegador usando file://...; não inicie nenhum serviço em segundo plano.
Proibido mvwb server, python -m http.server, portas, versão de serviço. O workbench é uma página puramente de visualização, sem nenhuma entrada de configuração.
Quando o usuário disser "abra o workbench": execute mvwb open [--workspace NOME], que apenas abre o HTML local.
Inicialmente, forneça apenas a chave Router: o aluno coloca o arquivo zz-keys.json enviado pelo professor na raiz do projeto (geralmente contém apenas {"router": "..."}); o agente executa mvwb keys import --file <projeto>/zz-keys.json --delete-source. A importação é feita uma vez e vale globalmente; o arquivo fornecido é excluído após a importação.
A chave não passa pelo workbench: o usuário importa zz-keys.json, clica duas vezes em start/setup-keys.*, ou usa o terminal com mvwb keys set; o agente executa mvwb keys import --file <caminho> --delete-source. O agente apenas orienta, não solicita a chave; em ambientes não interativos, não chame keys set.
Chave de backup via alerta B001: se o Router falhar 3 vezes consecutivas em 10 minutos sem uma chave reserva configurada, o agente gera um bloco de alerta B001; o aluno encaminha o texto original do alerta para o professor, que decide se deve fornecer o zz-keys.json reserva (contendo os campos runninghub/apimart). Após o fornecimento, importe e ative, e atualize saldo/workbench. O agente pode usar mvwb keys watch para evitar uma segunda conversa.
Formato de alerta unificado: todas as falhas/erros/avisos passam por scripts/alerts.py (tabela de códigos em references/alerts.md); o aluno só precisa encaminhar o bloco inteiro de alerta original. Proibido dizer diretamente "peça a chave reserva ao professor"; as chaves reservas sempre são decididas pelo professor através do alerta B001.
A chave não é gravada em DATA, HTML, scripts, logs ou capturas de tela; o arquivo de importação baixado deve ser excluído após a importação. Se o usuário já enviou a chave na conversa, avise para invalidá-la e reenviá-la.
Saldo/custo visto apenas no Router (RMB): exiba apenas o saldo do Router no topo; todos os custos são convertidos para ¥ e escritos no DATA (a taxa de câmbio RunningHub Coin → CNY está em config/models.json no campo fx.rh_coin, mantida pelo professor).
Após cada geração/substituição de arquivo: atualize data.json → mvwb build → mvwb check --data .... Se o check reportar ausências, o workbench não as exibirá e a tarefa não pode ser considerada concluída.

Entrega Final

Um diretório por MV, com música, ativos e segmentos de vídeo:

workspaces/<project>/
├─ 原文/
│  ├─ lyric_original.md      Letra original do cliente
│  ├─ story_script.md        Roteiro original do cliente (sem quebra de cenas)
│  └─ lyric.json             Mapeamento de linhas L01…
├─ workbench.html            Workbench do projeto (exibição somente leitura + importação local de chave)
├─ data.json                 Fonte de dados do workbench (atualizada pelo agente)
└─ MV001/
   ├─ mv_manifest.json       Status do estágio/versão/custo
   ├─ 00_framework.md        Plano de música/ativos/segmentos
   ├─ 01_music/
   │  ├─ song_v1.mp3
   │  └─ timeline_v1.json     Marcas de início/fim de cada linha (para segmentação/entrega)
   ├─ 02_assets/
   │  ├─ assets_v1.json
   │  ├─ role_xxx.png
   │  ├─ scene_xxx.png
   │  └─ prop_xxx.png
   ├─ 03_segments/
   │  ├─ segments_v1.json    G1/G2… versão atual + histórico
   │  ├─ G1_v1.mp4
   │  ├─ G1_v2.mp4           Histórico de revisões
   │  └─ G2_v1.mp4 …
   └─ handoff_v1.json        Lista para o editor

handoff_v1.json contém apenas os campos necessários para a edição:

{
  "mv_id": "MV001",
  "status": "ready",
  "segments": [
    {
      "segment_id": "G1",
      "line_ids": ["L01", "L02"],
      "music_start": 0.0,
      "music_end": 6.0,
      "duration": 6.0,
      "video_file": "03_segments/G1_v1.mp4",
      "model": "muse-video-ext",
      "resolution": "720x1280",
      "notes": "Versão atual aprovada na revisão"
    }
  ]
}

Contrato de Execução (Obrigatório em Cada Etapa)

Detalhes de entrada/saída/autoverificação em references/step-contract.md. Cada etapa tem cinco itens fixos:

Etapa	Pergunte primeiro (só se faltar)	Produto	Autoverificação	Portão
0 Inicialização	Nome do projeto, quantidade, duração, estilo, proporção, orçamento	workspace + `data.json` + `workbench.html`	`mvwb check` = 0 pendências	Confirmação de parâmetros
1 Texto original	Arquivo de letra/roteiro	`原文/*` + `lyric.json`	Linhas contínuas/IDs/não quebradas	Verificação do texto original
2 Workbench vazio	Parâmetros do lote	DATA + HTML estático	build + check + abrir com duplo clique	Confirmação do workbench
3 Framework	Comentários de revisão	manifest + framework + segments	Duração/linhas faltantes/segmentos ≤10s	Confirmação do framework + cotação
4 Geração	Itens apontados	Música/ativos/segmentos/handoff	Arquivos existem/duração/QA/timeline	Bloqueio por item

A saída da conversa deve ser padronizada como: "conclusão + caminho do produto + resultado da autoverificação + pendências de confirmação", sem colar blocos inteiros de JSON.
A autoverificação deve ser executada de verdade e referenciar o resultado; se falhar, pare na etapa atual, não avance silenciosamente para a próxima.

Quatro Etapas

Etapa 1 · Texto Original

Primeiro, procure por arquivos de letra/roteiro em 原文/, 甲方资料/, 输入/; nomes contendo 歌词, lyric, 脚本, script.
Se encontrado, apenas leia e armazene, sem reescrever, quebrar linhas ou "otimizar".
Se não encontrado: primeiro pergunte ao usuário se há material do cliente; se não, guie com base em produto/história/personagem/estilo/duração/referência e gere um rascunho.
Armazenamento:

原文/lyric_original.md    Nome da música/estrofe/refrão, texto original
原文/story_script.md     Roteiro original, sem quebra de cenas
原文/lyric.json          Mapeamento de linhas L01…

Portão: Confirmação do texto original. Após o usuário dizer "ok/uso esta versão", bloqueie; alterar o texto original = recomeçar o workbench.

Etapa 2 · Workbench Vazio

mvwb init my_project          # Projeto vazio: 原文/ a preencher, mvs=[], workbench.html gerado
mvwb init demo_project --demo # Quando precisar de exemplo: copiar demo completo
# Após preencher workspaces/my_project/原文/, peça ao agente para gerar o workbench vazio

Agente reconstrói usando templates/workbench.html + DATA.json:

python3 scripts/build_workbench.py \
  --template templates/workbench.html \
  --data workspaces/my_project/data.json \
  --out workspaces/my_project/workbench.html

Abra o workbench estático:

mvwb open --workspace my_project

Após gerar, pare e pergunte (o que faltar, pergunte; cada item com valor padrão):

Qual o nome do projeto? Padrão: nome do cliente/data.
Quantos MVs gerar por lote? Padrão: 1 para amostra (recomendado 1–5).
Duração de cada MV? Padrão: 30s (15/30/45/60s).
Qual estilo? Padrão: conforme pacote de referência (3D Pixar / série curta live-action / fofo japonês / vídeo de referência do cliente).
Proporção? Padrão: 9:16 vertical (1080×1920).
Referências de personagens/cenários/produtos? Se houver imagem, forneça; senão, descrição textual.
Orçamento máximo? Se não fornecido, faça cotação primeiro, não submeta.

Saída apenas: caminho do produto + resultado da autoverificação + confirmação destes 7 itens. Portão: Confirmação dos parâmetros do lote. Esta etapa não consome créditos.

Contrato de Duração (Objetivo do Usuário vs. Duração Real da Música)

Duração	Quem define	Uso
`target_duration`	Usuário na Etapa 2 (ex.: 45s)	Segundos solicitados para música, duração alvo total do MV, orçamento/nº de segmentos, planejamento do framework
`actual_duration` / `timeline_v1.json`	Lido após geração da música	Duração real dos storyboards/segmentos de vídeo, `seconds` para Muse, quadros H3, handoff

Duração total conforme definido pelo usuário: ao gerar a música, passe target_duration para o 116:value do ACE; a duração total, número de segmentos e orçamento do framework são planejados com base nisso.
Duração de cada segmento conforme a música real: após a música ficar pronta, leia actual_duration e o timeline linha a linha, atualize a duration dos storyboards/segmentos de vídeo; os segmentos de vídeo são gerados com base na duração real das linhas, não cortados rigidamente pela duração planejada.
Tratamento de desvio: se a diferença entre real e alvo for >1s ou >2%, pause e deixe o usuário escolher entre "aceitar real / regenerar música / cortar na pós"; não use a duração planejada para gerar vídeos.
Apenas vídeo, sem música: primeiro faça um plano provisório com target_duration; após adicionar a música, marque todos os segmentos de vídeo como stale e regenere pela timeline real.
Dessa forma, respeitamos a duração total definida pelo usuário e garantimos o alinhamento quadro a quadro da música.

Etapa 3 · Framework de Texto do MV

Crie MV001…MV00N, cada um:

Proporção padrão 9:16 vertical (workbench em 1080×1920, saída Muse em 720×1280); mude apenas se o usuário especificar explicitamente.
Primeiro, escreva o genome: cast_id/outfit_id/face_seed, story_id, music, visual, edit; regras em references/variation.md. Quaisquer dois MVs no mesmo lote devem diferir em pelo menos 3 dimensões. Proibido mesmo personagem + mesma roupa, mesmo conflito de história, mesmo genre+BPM+vocal, mesmo pacote de cena.
Gere uma tabela de diferenciação (cast/story/music/visual/edit de cada MV); se houver combinação repetida, pare e escolha a próxima do pool, não inicie.
mv_manifest.json: stages todos not_started; genome, cost/spent=0.
00_framework.md: plano musical, lista de ativos, storyboards padrão, plano de segmentos de vídeo; a duration aqui é o valor planejado, com target_duration como alvo total.
A lista de ativos é para revisão do usuário: vistas de três quartos do personagem/cenas vazias/props, usada para garantir consistência visual nos vídeos seguintes; não é opcional. Explique ao usuário: "sem imagens de ativos, o personagem/cena de cada vídeo variará".
03_segments/segments_v1.json: primeiro escreva o plano, videos: [].
Atualize DATA.mvs: música/ativos vazios, storyboards/segmentos com plano; mantenha snapshot das chaves.

Mostre ao usuário um resumo do framework:

O framework precisa de alterações? Qual MV, qual cena, qual linha? Altere apenas as partes que você apontar.

Portão: Revisão do framework aprovada + confirmação do escopo de geração/cotação.

Etapa 4 · Geração e Revisão

4.0 Pré-verificação

mvwb keys status
mvwb keys import --file workspaces/my_project/zz-keys.json --delete-source
mvwb keys watch --timeout 600 --data workspaces/my_project/data.json
mvwb keys balance --data workspaces/my_project/data.json
mvwb quote --model muse-video-ext --seconds 2

Falta de chave / saldo insuficiente / falha na consulta: pare. Cotação = quantidade × preço unitário; execute apenas após confirmação do usuário.

4.1 Ordem: Música → Timeline → Ativos → Segmentos de Vídeo

Etapa	Comando	Produto
Música	`mvwb rh --app 2075301815628943362 ...`	`01_music/song_v1.mp3`
Timeline	`mvwb timeline ...`	`01_music/timeline_v1.json`
Ativos	`mvwb rh --app 2116462203997081601 ...`	`02_assets/*` + `assets_v1.json`
Vídeo H3	`mvwb rh --wf 2110943749894402050 ...`	`03_segments/G*_v1.mp4`
Vídeo Muse	`mvwb muse --prompt ... --seconds N --size 720x1280 --out ...`	`03_segments/G*_v1.mp4`
Música/Ativos (Router)	`tokentech_task.py music	image ...`(protocolo em`references/providers/router.md`)
Entrega	Escreva `handoff_v1.json`	Para o editor

Música é bloqueada primeiro; leia a duration/timeline real e atualize a duração dos segmentos; ativos conforme pacote de referência; segmentos de vídeo gerados um a um com base na duração real das linhas.
Ativos gerados com base na ficha do personagem: vistas de três quartos do personagem usando o template em references/prompts/casting-style.md + pacote de estilo; a regra MOSS é: quadro esquerdo rosto, quadro central corpo inteiro mas cabeça completamente fora do quadro, quadro direito costas. Cada personagem gera primeiro 4 candidatos, seleciona 1 e depois bloqueia.
Consistência do personagem no mesmo MV: todos os ativos/segmentos de vídeo referenciam a mesma ficha de personagem com cast_id e outfit_id; troca de roupa só ocorre quando a história exigir e é registrada.
Sem repetição entre MVs: cast_id, história, música, pacote de cena do mesmo lote são diferenciados pelo genome; antes de bloquear os ativos, verifique dois aleatoriamente para evitar "mesma pessoa com roupa diferente = novo MV".
Cada segmento pode gerar múltiplos vídeos: o primeiro é atual, o histórico é adicionado como G1_v2.mp4.
Nova versão escreve *_v{n+1}.json, não sobrescreve a antiga.
Atualize stages/status/spent, reconstrua DATA.
Após reconstruir, autoverificação obrigatória: mvwb build --data ... --out ... && mvwb check --data ...; o número de arquivos faltantes deve ser 0, caso contrário, corrija os caminhos ou regenere.
A página é estática file://, caminhos relativos baseados no diretório onde workbench.html está; não mude manualmente para caminhos absolutos.

4.2 Ciclo de Revisão

Geração concluída. O que precisa ser alterado? Qual MV, qual segmento de vídeo, qual imagem/música?

Regere apenas os itens apontados; nova versão + histórico.
Música não pode ser alterada após locked; trocar música = criar novo MV.
Primeiro, faça desduplicação aproximada de músicas no mesmo lote: genre + faixa de BPM + vocal não podem ser todos iguais; se os primeiros 10 segundos soarem como a mesma música, troque music_id.
Ativos qa: pass / warn / fail: fail deve ser regenerado; warn requer confirmação do usuário antes de usar.
Alteração de ativo → segmentos de vídeo que dependem dele são marcados como stale.
Alteração no plano de storyboards/segmentos → segmentos de vídeo correspondentes stale.
Usuário diz "finalizado/aprovado" → estágio correspondente locked.

4.3 Entrega

Após todos os segmentos de vídeo locked:

Escreva handoff_v1.json (ou handoff_v1.csv).
Verifique cada segmento: video_file existe, duration ≤10s, music_start/end consistente com a timeline.
Projeto finalizado; o editor pega os segmentos de vídeo e o handoff para a próxima fase.

Próximo MV: dentro do mesmo workbench, continue com MV002, reutilizando regras de música/ativos já bloqueadas; primeiro faça o framework, depois gere. Para trocar letra/cliente, use mvwb init <nome_do_projeto> para criar um novo workspace, não sobrescreva projetos antigos.

Regras de Revisão/Versão

Status	Significado	UI
`not_started`	Não gerado	Círculo cinza
`draft`	Produto gerado, aguardando revisão	Círculo âmbar
`locked`	Finalizado	Círculo verde
`stale`	Upstream alterado, precisa regenerar	Círculo laranja
`failed`	Falhou	Círculo vermelho

Se upstream não está locked, downstream não inicia.
Altere apenas o que foi apontado; o resto permanece inalterado.
Histórico não é sobrescrito; spent acumula custos históricos.
Workbench exibe apenas a cor do círculo, não o texto do status.

Roteamento de Modelos e Prompts

Etapa	Padrão	Consulte qual referência
Música ACE-Step	`2075301815628943362`	`references/prompts/ace.md`
Ativos MOSS	`2116462203997081601`	`references/prompts/moss.md`
Vídeo H3 (multi-parâmetro)	`2110943749894402050`	`references/prompts/h3.md`
Vídeo Muse (Router)	`muse-video-ext`	`references/prompts/muse.md`
S2V (sincronia labial)	`1979183169033375745`	`references/prompts/h3.md`
API RunningHub	—	`references/providers/runninghub.md`
API Router / Saldo	—	`references/providers/router.md`
Contrato DATA do Workbench	—	`references/workbench-contract.md`
Contrato de Execução em Quatro Etapas	—	`references/step-contract.md`
Variação / Diferenciação / Desduplicação	—	`references/variation.md`
Distribuição/Importação de Chaves	—	`references/key-distribution.md`
Tabela de Códigos de Alerta	—	`references/alerts.md`
Ficha de Personagem / Estilo / Gente Bonita / Fofo	—	`references/prompts/casting-style.md`
Campos de Entrega	—	`references/handoff.md`

Vídeo: modelo definido por segmento; segmentos diferentes podem usar modelos diferentes, mas o pacote de estilo/paleta de cores do mesmo MV deve ser uniforme.
Múltiplas imagens de referência: vistas de três quartos do personagem (não quatro)/painéis de cena/props/fotos reais do produto; uma imagem por função; primeiro gere 1 segmento de amostra.

Chave (Key)

Única fonte verdadeira: ~/.config/mv-workbench/keys.json (0600).
Configuração: mvwb keys set runninghub, mvwb keys set router (entrada oculta no terminal).
Saldo: mvwb keys balance --data workspaces/<project>/data.json → mvwb build.
Chave original não entra em HTML/DATA/logs; DATA.keys contém apenas máscara e snapshot de saldo.
Comandos de geração passam por mv_keys.py exec para injeção; não dependa de chave residual no shell.

Comandos Comuns

mvwb doctor
mvwb open
mvwb open --workspace my_project
mvwb init my_project
mvwb keys status
mvwb keys import --file workspaces/my_project/zz-keys.json --delete-source
mvwb keys watch --timeout 600 --data workspaces/my_project/data.json
mvwb keys balance --data workspaces/my_project/data.json
mvwb quote --model muse-video-ext --seconds 2
mvwb build --data workspaces/my_project/data.json --out workspaces/my_project/workbench.html
mvwb check --data workspaces/my_project/data.json
mvwb rh --app <id> --name <tag> --overrides <json> --out <dir>
mvwb muse --prompt "..." --seconds 2 --size 720x1280 --out out.mp4
python3 scripts/providers/tokentech_task.py image --prompt "..." --seed 123 --out out.png
python3 scripts/providers/tokentech_task.py music --lyrics "..." --style "..." --seconds 60 --out out.mp3
mvwb timeline <lyric.json> <audio.mp3> --out <dir>

O que Não Fazer

Não fazer edição bruta, não montar vídeos, não fazer legendas/mixagem de áudio/vídeo final.
Não revisar automaticamente; após o usuário solicitar alterações, regere apenas os itens apontados.
Não submeter letras/roteiros/materiais do cliente para repositórios públicos.

Arquivos

SKILL.md          Entrada do agente (este arquivo)
start/            Entrada para humanos: instalação, comando mvwb, configuração de chave com um clique
scripts/          mvwb, keys, alerts, build, timeline, providers
references/       Contratos do workbench, contratos de etapas, tabela de códigos de alerta, prompts, providers
templates/        workbench.html
contracts/        Contratos de timeline/storyboard/segments/mv
demo/             Demo original (pode abrir diretamente)
config/           Preços de modelos / taxa de câmbio fx / exemplo de chave
workspaces/       Projetos do aluno (um diretório por projeto)

Versão

v0.4.4 (2026-11-14): Protocolo de tarefas Router testado na prática (moss geração de imagem / ace geração de música): POST /v1/responses + metadata.nodeInfoList direto para nós RunningHub; novo scripts/providers/tokentech_task.py; duração/BPM/letra/estilo/negativa/seed totalmente controláveis; faturamento por tempo de execução RH.
v0.4.3 (2026-11-14): UI do Workbench simplificada — removida configuração de chave na página; saldo exibe apenas valor numérico, sem máscara; removido logotipo acumulado no cabeçalho do MV; alinhamento de estado vazio para música/ativos; removido texto "somente leitura" da página; ordem da barra superior: tempo de geração → saldo.
v0.4.2 (2026-11-14): Reorganização de diretórios — arquivos de entrada (instalação/mvwb/setup-keys) movidos para start/, arquivos de desenvolvedor para dev/ e docs/; arquivo de exemplo de chave renomeado para config/zz-keys.example.json; raiz mantém apenas SKILL/README/LICENSE/NOTICE.
v0.4.2 (2026-11-14): Categorização de diretórios — arquivos de entrada em start/, arquivos de desenvolvimento em dev/, docs/; raiz mantém apenas 4 arquivos; exemplo de chave renomeado para config/zz-keys.example.json.
v0.4.1 (2026-11-14): Formato de alerta unificado (scripts/alerts.py + tabela de códigos em references/alerts.md); chave reserva alterada para alerta B001 encaminhado ao professor; integração completa de keys/providers/check/build; manual atualizado com "encaminhe o texto do alerta ao professor". (2026-11-14): Cadeia principal Router + chave reserva sob demanda; exibe apenas saldo Router no topo; custos sempre convertidos para ¥ (fx.rh_coin); camada de chaves suporta segmento apimart independente; saída quote convertida para RMB.
v0.3.9 (2026-11-14): Arquivo de chave fornecido pelo professor padronizado como zz-keys.json; watcher reconhece tanto mv-keys-import*.json quanto zz-keys.json.
v0.3.8 (2026-11-14): JSON de fornecimento de chave simplificado para dois campos {"runninghub":"...","router":"..."}; issued_to/expires_at/mv_keys_import tornados opcionais, necessários apenas para registro ou coleta automática pelo watcher.
v0.3.7 (2026-11-14): Novo padrão para fornecimento de chave pelo professor: zz-keys.json colocado na raiz do projeto, keys import --delete-source; formato de exemplo e regras de fornecimento em references/key-distribution.md.
v0.3.6 (2026-11-14): Novo mvwb keys watch; agente primeiro monitora diretório de download; usuário preenche chave no workbench e baixa → importação automática/exclusão, opcionalmente atualiza saldo e reconstrói workbench.
v0.3.5 (2026-11-14): Canto superior direito do workbench "Configurar Chave" → preenchimento local → download de mv-keys-import.json → agente keys import --delete-source; sem servidor, sem rede.
v0.3.4 (2026-11-14): setup-keys com um clique (Mac/Win); keys set recusa em ambiente não interativo em vez de traceback; miniaturas de vídeo no workbench mostram primeiro quadro; prompt de keys init alterado para --data.
v0.3.3 (2026-11-14): Novas regras de variação/diferenciação e pacotes de prompts de estilo de personagem (look Xiaohongshu / fofa japonesa / coreano bonito / filme fofo / gente bonita); Etapa 3 exige genome e tabela de diferenciação.
v0.3.2 (2026-11-14): Alinhado com manual do usuário: chave inserida localmente pelo usuário; complementado nome do projeto/confirmação em três etapas, bloqueio de música e desvio de duração, QA de ativos, cotação para grandes alterações, diretório data.json.
v0.3.1 (2026-11-14): Instalação/atualização mantém workspaces; init padrão é projeto vazio (--demo copia demo); build/check com fallback de caminho relativo para raiz do skill; documentação simplificada.
v0.3.0 (2026-11-14): Removido serviço em segundo plano, workbench volta a ser puramente estático; chave/saldo movidos para CLI; novo contrato de execução em quatro etapas e mvwb check; corrigidos parâmetros de passagem.

zz-mv-gongzuotai · MV 项目统筹

O que é zz-mv-gongzuotai · MV 项目统筹?

Perguntar na sua IA favorita

Documentação