c0sogi/write-korean-meeting-minutes-hwpx

Gravação de Atas de Reunião em Coreano HWPX

Cria atas de reunião formais em coreano com base em gravações de áudio/vídeo ou transcrições e fornece um arquivo .hwpx válido. Se não houver transcrição, primeiro crie uma transcrição em Markdown com meetdown. O escopo atual vai até a geração HWPX; a conversão para PDF não é realizada.

Ambiente de Execução

• Usa o sistema de arquivos e permissões de execução de shell.
• Use uv e uvx para executar comandos Python e pacotes. A ferramenta de transcrição de áudio meetdown==0.2.1 requer Python 3.12 ou superior.
• A transcrição de áudio requer conexão de rede e credenciais de um dos seguintes: CLOVA Speech, OpenAI ou Gemini.
• A geração HWPX usa um modelo incluído e scripts baseados na biblioteca padrão Python.

Princípios Obrigatórios

• Não presumir data, local, participantes, nomes reais dos falantes, responsáveis, prazos, decisões, valores numéricos ou nomes próprios.
• O Created at do meetdown é o momento da criação da transcrição, não a data/hora da reunião.
• Marcadores como A, B, [[SPEAKER_1]] não são nomes reais; substitua por nomes apenas quando o usuário fornecer um mapeamento de falantes.
• Distinguir entre propostas, preocupações, decisões, ações subsequentes e itens pendentes.
• Não promover automaticamente ideias repetidas a decisões.
• Se a opinião inicial e o acordo explícito no final da reunião forem diferentes, priorizar o último acordo ou instrução.
• Não concretizar referências a "aqui", "esta imagem", "deste lado" sem materiais de referência.
• Não expor chaves de API em argumentos de comando, logs, Markdown, JSON, HWPX ou na resposta final.
• Títulos de documentos, seções e subseções devem estar em negrito.
• Destacar apenas frases curtas de decisões, conclusões ou ações importantes com a cor azul #2F5597 e negrito. Não tornar a maior parte do texto azul.

Materiais Incluídos

Leia apenas os materiais relevantes para a situação.

• references/meetdown-guide.md: Leia quando não houver transcrição ou a execução do meetdown falhar.
• references/minutes-writing.md: Leia antes de reorganizar o conteúdo da transcrição em ata.
• references/hwpx-template.md: Leia ao criar, substituir ou modificar o modelo HWPX.
• references/installation.md: Leia ao orientar sobre local de instalação ou configuração do operador.
• references/evaluation.md: Leia ao projetar testes de regressão após modificar a habilidade.
• assets/minutes.schema.json: Referência para a estrutura de minutes.json.
• assets/example-minutes.json: Use apenas como exemplo de estrutura de dados, não de texto.
• assets/example-audit.json: Exemplo de formato de registro de auditoria.
• assets/meeting-minutes-template.hwpx: Modelo básico de ata de reunião.

Scripts a Usar

Todos os caminhos são relativos à raiz da habilidade.

• scripts/transcribe.py: Executa o meetdown de forma não interativa e protege valores secretos.
• scripts/inspect_transcript.py: Inspeciona a estrutura e fatores de risco do Markdown do meetdown.
• scripts/validate_minutes.py: Valida minutes.json antes da geração HWPX.
• scripts/render_hwpx.py: Aplica conteúdo estruturado ao modelo HWPX.
• scripts/validate_hwpx.py: Verifica ZIP, XML, frases obrigatórias, negrito e destaque azul.
• scripts/validate_skill.py: Verifica regras principais das habilidades do agente.
• scripts/self_test.py: Executa todo o procedimento local sem rede.

Ordem de Trabalho

Status do progresso:

• 1. Classificar arquivos de entrada e materiais de referência.
• 2. Se não houver transcrição, transcrever com meetdown.
• 3. Inspecionar a estrutura e qualidade da transcrição.
• 4. Criar registro de auditoria.
• 5. Criar e validar minutes.json.
• 6. Gerar HWPX.
• 7. Validar HWPX e corrigir erros.
• 8. Relatar saídas e itens que precisam de verificação.

1. Classificar Materiais de Entrada

Aplicar a seguinte prioridade.

1. Metadados da reunião confirmados pelo usuário, mapeamento de falantes, terminologia, correções
2. Materiais de referência usados na reunião real: pauta, apresentações, RFP, lista de participantes
3. Transcrição válida com carimbo de data/hora e falante
4. Transcrição completa sem carimbo de data/hora
5. Dica de data do nome do arquivo, apenas se o formato for especificado

Processamento por entrada:

• Se houver uma transcrição Markdown válida, use-a e não retranscreva a mesma gravação.
• Se houver apenas áudio/vídeo, transcreva antes de escrever a ata.
• Se houver transcrição e gravação, priorize a transcrição. Retranscreva apenas se a transcrição estiver vazia, corrompida ou contiver conteúdo de outra reunião.
• Transcreva múltiplas gravações separadamente. Combine na ordem dos arquivos apenas quando confirmado que são gravações contínuas da mesma reunião.
• Se não houver gravação ou transcrição, escreva um rascunho apenas se as anotações da reunião forem suficientes. Se faltarem evidências, não invente o conteúdo da reunião.

2. Transcrever Quando Necessário

Leia references/meetdown-guide.md antes de transcrever.

Execução básica para reuniões em coreano com CLOVA Speech:

uv run scripts/transcribe.py "<arquivo_de_audio>" \
  -o "<transcricao.md>" \
  --provider clova \
  --language ko-KR

Tente novamente com a seguinte opção apenas se o upload único de um arquivo longo falhar ou se houver limitação clara do provedor.

--chunk-duration 10m

Use smallest para compactação padrão. Tente novamente com lossless apenas se houver evidência de degradação na qualidade da transcrição devido à compactação. Em reuniões com vários participantes, mantenha a separação de falantes, a menos que haja um motivo específico.

Após a transcrição, inspecione-a.

uv run scripts/inspect_transcript.py "<transcricao.md>" \
  -o "<transcricao.inspect.json>"

Não escreva atas com arquivos vazios, páginas de erro HTML ou arquivos sem nenhuma transcrição completa utilizável ou intervalo de carimbo de data/hora.

3. Organizar Metadados

Registre os seguintes valores quando confirmados.

• Pauta
• Data/hora
• Órgão responsável
• Local
• Participantes
• Principais pautas
• Mapeamento de falantes
• Terminologia confirmada para nomes, organizações, projetos, produtos, termos técnicos

Não interrompa o trabalho se metadados de baixa importância estiverem faltando. Crie um rascunho, escreva "Precisa de verificação" na célula correspondente e registre em quality.missing_metadata. Solicite verificação adicional apenas para informações que alterem significativamente o resultado se uma versão final completa for absolutamente necessária.

4. Criar Registro de Auditoria

Antes de escrever o texto final, crie minutes.audit.json. Para cada item importante, use o seguinte formato.

{
  "type": "fact | proposal | concern | decision | action | open_question",
  "statement": "Conteúdo curto normalizado",
  "source": "Nome do arquivo da transcrição ou material de referência",
  "speaker": "A ou nome real confirmado",
  "start": "00:42:02",
  "end": "00:42:10",
  "confidence": "high | medium | low"
}

Critérios de classificação:

• fact: Fato confirmado ou explicado na reunião
• proposal: Proposta, ideia, opção
• concern: Objeção, risco, restrição
• decision: Concordância explícita, escolha, confirmação, aprovação, instrução
• action: Tarefa específica a ser realizada
• open_question: Item não concluído

Ações subsequentes devem ter uma tarefa. Preencha o responsável e o prazo apenas quando houver evidência.

5. Criar Dados da Ata

Siga references/minutes-writing.md e assets/minutes.schema.json. Use assets/example-minutes.json apenas como referência de estrutura, não copie o conteúdo.

Estrutura obrigatória do documento:

• A T A
• Tabela de metadados no topo
• C O N T E Ú D O
  • Resumo da reunião
  • 2. Principais Discussões
  • 2.1 e seguintes discussões por tópico, geralmente 3 a 7
• R E S U L T A D O
  • [Resumo]
  • [Ações Subsequentes]
  • [Itens que Precisam de Verificação] apenas quando necessário

Use um estilo de escrita coreano de negócios conciso e neutro. Terminações básicas: -함, -하기로 함, -논의됨, -필요함, -판단됨. Remova interjeições, gaguejos, repetições e conversas irrelevantes, mas mantenha objeções, restrições técnicas, custos e prazos que fundamentam decisões.

As frases a serem destacadas em azul devem ser inseridas no array emphasis como strings curtas idênticas ao texto. Marque itens importantes com important: true.

Validação:

uv run scripts/validate_minutes.py "<minutes.json>"

Corrija todos os erros. Revise também avisos sobre metadados faltantes, frases de destaque não encontradas no texto, proporção excessiva de destaque e parágrafos muito longos.

6. Gerar HWPX

Se o usuário não forneceu um modelo compatível, use o modelo padrão.

uv run scripts/render_hwpx.py \
  --template assets/meeting-minutes-template.hwpx \
  --data "<minutes.json>" \
  --output "<ata_final.hwpx>"

O renderizador mantém a estrutura da tabela e os estilos de parágrafo existentes, coloca títulos e subtítulos em negrito e exibe as frases principais especificadas em #2F5597 com negrito. Não reduza excessivamente o tamanho da fonte se o conteúdo for longo; deixe que flua naturalmente para a próxima página.

Se o usuário fornecer um modelo HWPX significativamente diferente, não o execute cegamente. Primeiro, verifique os endereços das células da tabela e a estrutura dos parágrafos do corpo de acordo com references/hwpx-template.md e ajuste o renderizador.

7. Validar HWPX

uv run scripts/validate_hwpx.py "<ata_final.hwpx>" \
  --expect-data "<minutes.json>"

Se a validação falhar, corrija o JSON ou o modelo e gere novamente. Não entregue arquivos nos seguintes estados.

• mimetype não é o primeiro item ZIP ou está compactado
• XML obrigatório ausente ou não analisável
• Frases esperadas ausentes
• Título do documento ou títulos de seção não estão em negrito
• Destaque solicitado, mas estilo azul negrito ausente
• Placeholders incompletos restantes

Se o Hancom Office estiver disponível, abra o arquivo diretamente para verificar bordas da tabela, substituição de fonte, fluxo de página, frases cortadas e o último parágrafo. Se não foi realmente aberto, não diga que a inspeção visual foi concluída.

8. Saídas e Relatório

Crie o seguinte conforme a situação.

• transcript.md se a transcrição foi necessária
• transcript.inspect.json
• minutes.json
• minutes.audit.json
• minutes.review.md se houver itens não confirmados
• .hwpx final

Formato do relatório final:

Concluído
- HWPX: <caminho>
- Transcrição: <caminho ou transcrição existente usada>
- Validação: Aprovada | Avisos
- Precisa de verificação: Nenhum | Resumo dos itens principais

Tratamento de Falhas

• Se não houver credenciais, informe apenas os nomes das variáveis de ambiente necessárias e não solicite que o valor secreto seja inserido no chat.
• Para limites de tamanho/tempo, tente novamente com --chunk-duration 10m.
• Se a confiabilidade da transcrição for baixa, não corrija nomes próprios e números arbitrariamente; deixe como itens de revisão.
• Se a renderização do HWPX falhar, relate a causa e não forneça um arquivo corrompido como resultado.
• Se for solicitado PDF, informe que está fora do escopo atual da habilidade e que um ambiente de conversão separado é necessário.

Autoteste

Execute após a instalação da habilidade ou após modificar scripts/modelos.

uv run scripts/self_test.py

Este teste não chama APIs de reconhecimento de voz; ele executa a análise da transcrição, validação JSON, geração HWPX e validação estrutural.