0xsline/openchatcut

Formulários com Widgets

Use a ferramenta de formulário em vez de escrever marcação manualmente: o chat do editor renderiza o formulário como um cartão interativo e retorna a resposta estruturada do usuário.

Regra de Execução

Chame ask_followup_questions. Ela serializa seus campos no cartão de formulário nativo do editor; a submissão do usuário volta como a próxima mensagem.

Planeje todo o questionário antes de chamar a ferramenta. Envie um formulário final, não um formulário de teste seguido de um formulário corrigido. A ferramenta suporta no máximo 12 campos; se o usuário solicitar mais perguntas, mescle prompts relacionados em campos combinados antes da primeira chamada.

Após chamar ask_followup_questions, interrompa a rodada e aguarde a resposta submetida aparecer no chat. Não aplique uma escolha, crie ativos ou continue o planejamento a partir de uma recomendação até que a seleção do usuário esteja presente na conversa.

Mapeamento de Campos Suportados

Construa um array fields. Escreva toda string visível no idioma da conversa do usuário.

• <form-single> nativo -> { type: "single", variant: "default" }
• <form-multi> nativo -> { type: "multi", variant: "default" }
• <form-text> / <form-textarea> nativo -> { type: "text" }
• <form-visual> nativo -> { type: "single", variant: "visual" }
• Cartões de teste de voz -> { type: "single", variant: "voice" }
• Cartões de cenário de início nativo -> { type: "single", variant: "scenario" }

Tom da Cópia do Formulário

Para o texto de nível do formulário (title, prompt, fields[].label, submitLabel e messagePrefix), escreva como se o OpenChatCut fosse um parceiro capaz de criação de vídeo convidando o usuário a descrever o que deseja, não como uma pesquisa rígida.

Busque por:

• Tom caloroso, aberto e orientado à ação. A cópia deve sugerir "escolha a necessidade de vídeo mais próxima ou apenas me conte sua ideia; podemos descobrir juntos."
• Texto curto e escaneável. Use uma frase natural para prompt e rótulos de perguntas concisos.
• Enquadramento honesto de capacidades. O OpenChatCut pode ajudar com muitos fluxos de trabalho de vídeo, mas não afirme habilidades não suportadas nem garanta um resultado antes que as entradas sejam conhecidas.
• Idioma do usuário e termos locais do produto. Mantenha "OpenChatCut", "B-roll", "Motion Graphics", "MG 动画", nomes de modelos/produtos e nomes de plataformas em suas formas estabelecidas.
• Redação criativa voltada ao usuário. Para formulários de planejamento inicial ou captura criativa, prefira termos naturais como ideia, direção, plano, história, lista de cenas, público, clima ou necessidade de vídeo em vez de linguagem interna de documento de produção.

Evite rótulos rígidos como "Selecione o tipo de vídeo", "Por favor, escolha o tipo de vídeo para este projeto" ou "Que tipo de vídeo você quer fazer?" para captura de cenário, a menos que o host não tenha espaço para uma cópia mais calorosa.

Para um formulário de captura de cenário, prefira uma cópia como:

{
  "title": "O que você quer fazer?",
  "prompt": "Escolha o cenário de vídeo mais próximo, ou escolha Outra coisa e descreva sua ideia.",
  "submitLabel": "Começar a criar",
  "messagePrefix": "Quero começar com esta direção de vídeo:",
  "fields": [
    {
      "id": "scenario",
      "label": "Qual cenário se encaixa melhor no seu vídeo?",
      "type": "single",
      "variant": "scenario",
      "otherPlaceholder": "Por exemplo: transformar minhas imagens de viagem em um vlog atmosférico / fazer um vídeo de lançamento para um novo produto"
    }
  ]
}

Não inclua perguntas de upload de arquivos em formulários. Se uma tarefa realmente precisar de mídia de origem e o projeto/chat ainda não a tiver, peça ao usuário separadamente para fazer upload de arquivos no editor (arrastar e soltar ou o botão de upload, ou colar no compositor do chat). Upload de arquivo não é um pré-requisito padrão para todo questionário; só solicite quando o próximo passo de edição depender de mídia ausente.

Para campos de escolha:

• Use id para o valor interno que a próxima chamada de ferramenta precisará.
• Use label para o que o usuário vê.
• Para cartões comuns de seleção única e múltipla (variant: "default"), mantenha apenas rótulos nas opções. Não adicione description por opção a menos que o usuário não consiga distinguir as escolhas apenas pelos rótulos.
• Use description principalmente para cartões de voz. Cartões de estilo visual geralmente devem usar apenas preview + label.
• Quando uma resposta fora da lista for aceitável, adicione uma opção explícita com id: "__other__" e um label no mesmo idioma do restante do formulário, usando a palavra que o usuário esperaria para uma resposta fora da lista. O widget transformará esta opção em uma entrada de texto quando selecionada. Use otherPlaceholder se a entrada de texto precisar de um placeholder.

Para cartões visuais:

• Use URLs reais de imagem ou URLs de dados de imagem em preview.
• Para escolhas do catálogo de Design Style, chame manage_design_style com action: "list" primeiro, depois mapeie cada preset retornado para { id: preset.presetId, label: preset.name } (sem miniaturas nesta versão).
• Nunca codifique ids de preset do catálogo a menos que o usuário já tenha selecionado um.

Para cartões de voz:

• Use audioUrl para o arquivo de amostra.
• Prefira o caminho de amostra documentado como /voice-samples/doubao-liuchang.mp3 ou uma URL HTTPS pública. Não passe URLs de amostra localhost; os iframes do host MCP não resolvem mídia local do editor de forma confiável.
• Mantenha as descrições visíveis ao usuário neutras em relação ao provedor. Descreva a voz da mesma forma que a UI de teste nativa do OpenChatCut: gênero / faixa etária / tom / caso de uso, como Feminina / jovem / amigável, geral ou Masculino / meia-idade / locução séria de conhecimento. Não mostre nomes de provedores como ElevenLabs ou Doubao nas descrições das opções.
• Mantenha o id da opção igual ao id da voz do provedor necessário para submit_voice.

Para cartões de cenário de início nativo:

• Use isto quando o usuário deve escolher qual fluxo de trabalho de vídeo do OpenChatCut iniciar, como edição de talking head, animação MG, vídeo longo para curtas, promo de produto/app, curta-metragem de IA ou vídeo explicativo.
• Apresente-os como necessidades/cenários comuns de vídeo, não como os únicos fluxos de trabalho de vídeo possíveis. O formulário também deve permitir que o usuário descreva uma necessidade de vídeo diferente.
• Use exatamente um campo de seleção única com variant: "scenario".
• Forneça opções usando os ids canônicos abaixo e rótulos localizados no idioma do usuário. Inclua id: "__other__" apenas quando precisar personalizar o rótulo da opção fora da lista; caso contrário, o backend anexa uma opção Outro localizada.
• Rótulos/descrições/prompts iniciais de cenário em inglês, chinês e espanhol já estão embutidos. Para qualquer outro idioma do usuário, traduza fielmente o label, description e prompt inicial em inglês de cada cenário para o idioma do usuário e passe esses valores localizados nos objetos de opção. Preserve os termos do produto OpenChatCut e o significado do fluxo de trabalho; não adicione novos requisitos. Use submitPrompt para o prompt inicial traduzido. Esta substituição é específica para variant: "scenario"; cartões de opção comuns, cartões de voz e cartões de estilo visual já obtêm seu texto visível dos valores que você passa.
• Não forneça preview ou audioUrl personalizados; o backend preenche a imagem de pré-visualização da primeira tela nativa.
• Ids canônicos: talking-head, motion-graphics, long-video-to-shorts, app-promo, ai-cinematic-short-film, explainer, além de __other__ para uma necessidade de vídeo livre.
• Exemplo de opções: { "id": "talking-head", "label": "Edição de Talking Head" }, { "id": "motion-graphics", "label": "Motion Graphics" }, { "id": "long-video-to-shorts", "label": "Vídeo Longo para Curtas" }, { "id": "app-promo", "label": "Promo de Produto / App" }, { "id": "ai-cinematic-short-film", "label": "Curta-Metragem de IA" }, { "id": "explainer", "label": "Vídeo Explicativo" }, { "id": "__other__", "label": "Outra coisa" }.

Lacunas Atuais

ask_followup_questions é apenas para respostas estruturadas. Ela não suporta HTML personalizado nativo, pontes de parâmetros da linha do tempo, seleção de itens do editor ou campos de upload de arquivo. Para arquivos já mantidos pelo runtime do agente ou anexados diretamente ao chat fora deste cartão, o fluxo de trabalho de importação de mídia ainda é válido: chame import_media e execute o caminho de upload auxiliar/direto. Para arquivos que o usuário deseja colocar diretamente em um projeto, peça que usem a UI de upload do editor OpenChatCut.

Exemplo

{
  "title": "Sua ideia de vídeo",
  "prompt": "Escolha ou preencha o que você tem em mente para que o OpenChatCut possa selecionar uma boa direção inicial.",
  "submitLabel": "Enviar ideia",
  "messagePrefix": "Continuar com esta direção de vídeo:",
  "fields": [
    {
      "id": "goal",
      "label": "Qual é o objetivo principal deste vídeo?",
      "type": "single",
      "options": [
        { "id": "product_intro", "label": "Apresentação de produto" },
        { "id": "social_ad", "label": "Anúncio para redes sociais" },
        { "id": "__other__", "label": "Outra coisa" }
      ]
    },
    {
      "id": "elements",
      "label": "O que deve incluir? (Selecione todos que se aplicam)",
      "type": "multi",
      "options": [
        { "id": "broll", "label": "B-roll" },
        { "id": "logo", "label": "Logotipo da marca" },
        { "id": "__other__", "label": "Outra coisa" }
      ]
    }
  ]
}