Dnnecessary/skills

Habilidade de Formatação de Artigos para WeChat (公众号文章排版 Skill)

Converte um artigo em Markdown em HTML que pode ser copiado e colado diretamente no editor de artigos do WeChat, preservando todos os estilos após a colagem.

O ativo central é a biblioteca de componentes de tema em references/ (cada tema é um conjunto: variáveis de design + HTML completo de cada componente + esqueleto de template + regras de mapeamento) mais 1 biblioteca de componentes comuns (blocos de código, imagens/GIFs, títulos com pequenas tags, compartilhados por todos os temas). A lista de temas tem como fonte única references/theme-index.md. Este SKILL.md é responsável apenas pelo fluxo e decisões; o código HTML específico deve ser sempre obtido da biblioteca de componentes, nunca escrito de memória.

Fluxo de Trabalho

0. Entrada e Normalização de Formato

O usuário pode fornecer: texto Markdown ou caminho para .md (vai direto para o Passo 1), .docx, .pdf, .txt/texto puro sem marcação, ou rich text da web. Entradas que não são Markdown devem primeiro ler references/format-normalize.md e seguir suas regras para converter em um rascunho Markdown, confirmando a estrutura (docx usa scripts/extract_docx.py, PDF usa leitura página por página com limpeza de ruído, texto puro infere estrutura heuristicamente por títulos). Se nada for fornecido, solicite ao usuário.

Se o usuário disser "direto / automático / um clique / não precisa perguntar", entre no modo totalmente automático: pule a confirmação da estrutura e a pergunta de seleção de tema, infira a estrutura automaticamente, escolha o tema com base no assunto, formate, valide e entregue com uma explicação das decisões (estrutura de capítulos, título sugerido, motivo da escolha do tema).

1. Selecionar Tema (Sistema de Recomendação Automática)

Leia references/theme-index.md (fonte única de informações sobre temas). Recomende ativamente o tema mais adequado com base no assunto do artigo e, em seguida, peça confirmação ao usuário — recomende, mas não defina sem consulta:

• Usuário já especificou o tema na solicitação → use diretamente, sem perguntar.
• Assunto tem correspondência clara → pergunte com confirmação única: "Sugiro XX (motivo), confirma ou prefere outro?" Opções: item recomendado + 1~2 alternativas + "Ver todos". Correspondência assunto → tema (consulte a coluna "Cenários de Aplicação" do theme-index):
  • Tutoriais / Avaliações / Listas / Inventários de ferramentas / Organização de conhecimento / Decomposição de metodologias (alta densidade de informação) → Verde Preguiça (摸鱼绿)
  • Análise aprofundada / Opinião / Tópicos com força → Série Vermelha e Branca
  • Design / Crítica de tecnologia / Opinião profissional / Marcas premium → Minimalista Grafite
  • Zen / Vida minimalista / Ensaios profundos → Estilo Zen com Espaço em Branco
  • Comparação de ferramentas / Avaliação criativa (metáfora visual de recibos) → Estilo Recibo Preguiça
  • Notas de boletim interno / Avaliação aprofundada / Revisão de caso → Caderno de Oliveira
• Sem tendência clara → por padrão, coloque o primeiro item do theme-index (Verde Preguiça) como recomendação principal, use AskUserQuestion para o usuário escolher entre algumas opções (se houver mais de 4 temas, agrupe primeiro por estilo e pergunte, depois pergunte sobre o tema dentro do grupo).
• Modo totalmente automático (usuário diz explicitamente "direto / um clique / não precisa perguntar") → não pergunte, escolha automaticamente o tema mais adequado ao assunto ou o primeiro item padrão, e explique o motivo da escolha na entrega.
• Usuário não está satisfeito com nenhum tema existente / quer um novo estilo → siga o fluxo de "Geração de Tema Personalizado" (veja próxima seção), gere e registre, depois volte a este passo para selecionar.
• theme-index vazio → pare a formatação, informe ao usuário que é necessário primeiro adicionar um estilo de tema (pode seguir o fluxo de "Geração de Tema Personalizado").

Após o usuário definir o tema, só então entre na correspondência de componentes dentro desse tema (Passos 3 e 4: determinar o tipo de artigo → selecionar a combinação de componentes de acordo com a tabela de receitas do tema).

2. Ler Biblioteca de Componentes (Duas Partes)

(1) Com base na coluna "Arquivo da Biblioteca de Componentes" do tema no theme-index, leia a biblioteca de componentes exclusiva do tema references/theme-{identificador}.md (contém componentes exclusivos do tema, como cartão de citação, título de capítulo, marcação de texto, assinatura, etc.). (2) Ao mesmo tempo, leia a biblioteca de componentes comuns references/common-components.md — blocos de código, imagens/GIFs e títulos com pequenas tags são compartilhados por todos os temas, bastando aplicar a cor principal do tema atual.

A geração subsequente depende exclusivamente dessas duas bibliotecas de componentes; todo HTML deve ser obtido delas, não escrito manualmente.

3. Analisar Estrutura Markdown

Elemento	Regra de Identificação
Título do artigo	# Título ou title do frontmatter
Citação de abertura	Bloco > Citação no início do artigo
Título de capítulo	## Título
Subcapítulo	### Título
Negrito / Destaque / Sublinhado	**texto** / ==texto== / <u>texto</u> ou ++texto++
Parágrafos de citação	Blocos > texto que não estão no início
Imagem / GIF	,  (GIF tratado como imagem)
Código / Comando / Prompt	``` bloco de código ```, `code` inline
Linha divisória / Lista	---, *** / - item ou 1. item
Tabela	Tabela Markdown separada por | (geralmente de conversão docx) → priorize usar o componente de tabela/cartão da biblioteca de temas (conforme regras de mapeamento da biblioteca)

Após analisar a estrutura, determine o tipo de artigo (pegue o tipo dominante, pode ser composto): Tutorial/Guia de operação, Inventário/Lista de ferramentas, Opinião/Análise aprofundada, Entrevista/Perfil de pessoa, Revisão de dados/Relatório, Ensaio de vida/emoções, Caso prático. Critérios: muitas etapas e comandos → Tutorial; muitos itens paralelos → Inventário; muitas citações e narrativa de personagens → Entrevista; muitos números e comparações → Dados; muita argumentação e dedução → Opinião.

4. Selecionar Combinação de Componentes por Receita → Montar HTML

Primeiro, consulte a tabela de "Tipo de Artigo → Combinação de Componentes" da biblioteca de temas selecionada e determine a combinação principal de componentes e componentes de destaque deste artigo com base no tipo de artigo — não selecione componentes aleatoriamente parágrafo por parágrafo ao obter a biblioteca; a receita garante a consistência visual de artigos do mesmo tipo. Elementos fora da receita são complementados pelas regras de mapeamento da biblioteca de temas.

Em seguida, monte de acordo com a seção "Esqueleto de Template de Artigo Completo" da biblioteca de temas, substituindo cada elemento Markdown pelo componente correspondente:

• A ordem do esqueleto deve seguir a biblioteca de temas; esqueletos podem variar entre temas, não use o esqueleto de outros temas.
• Marcações inline devem ser mapeadas semanticamente para os componentes correspondentes na biblioteca de temas selecionada (os números dos componentes variam entre bibliotecas, sempre use a semântica, não use números fixos): **negrito** → negrito na cor principal; ==destaque== → destaque com fundo claro da cor sólida; <u>texto</u> ou ++texto++ → sublinhado; ~~texto~~ → marcador (fundo claro da cor sólida); >citação → bloco de citação destacado.
• Componentes da biblioteca de componentes comuns: ``` bloco de código ``` → 1a bloco de código escuro / 1b claro, inline `code` → 1c; ![descrição](url) → 2a imagem (adicione componente de descrição apenas se houver descrição), .gif → 2b GIF; sub título / ênfase que precisa de destaque → 3a sub título com barra vertical esquerda ou 3b tag pílula, frase de ouro → 3d, nota de dica → 3e. Prioridade: primeiro consulte a tabela de regras de mapeamento da biblioteca de temas — se o tema tiver um componente semanticamente equivalente (como sua própria frase de ouro ou bloco de dica), use a versão da biblioteca de temas para manter a consistência visual; se não houver componente correspondente na biblioteca de temas, use os componentes 3x da biblioteca comum e aplique as regras de troca de cor para a cor do tema.
• Um artigo usa apenas o conjunto de componentes do tema selecionado, não misture componentes de diferentes temas.
• Para ênfase e sub títulos, use "pequenas tags / barra vertical esquerda", não use borda tracejada: para destacar um sub título ou trecho de conteúdo, use sub título com barra vertical esquerda (3a), tag pílula (3b), bloco de frase de ouro/dica com barra vertical esquerda (3d/3e); não use borda tracejada (dashed border) ao redor de um título, pois fica pesado e rouba a atenção.

5. Verificar Conformidade (Obrigatório)

Após escrever o HTML gerado no arquivo de destino, execute o script de validação obrigatoriamente. A conclusão só é considerada quando o número de ERROS for zero:

# Use o caminho absoluto do script no diretório da skill, e o caminho real do HTML (geralmente em diretórios diferentes)
<SKILL_ROOT>/scripts/validate_gzh_html.py <caminho_real_do_.html_gerado>

Ele verifica deterministicamente itens proibidos pela plataforma e o encapsulamento <span leaf>. Se houver ERRO, volte ao Passo 4 para corrigir; AVISOS de pontuação de meia-largura também devem ser corrigidos até zero antes da entrega (este é o ponto de retrabalho mais frequente no uso real).

AVISOS de fundo gradiente devem ser tratados um a um: destaque de texto, citações, cartões de dados/guia devem, por padrão, usar uma cor sólida do tema ou rgba sólido; se o usuário solicitar explicitamente a retenção, informe na entrega que pode acionar o popup darkmode-no-gradient. Fundos gradientes puramente decorativos também geram aviso, e ainda não foi confirmado se não acionam o popup; ao retê-los, explique o risco.

6. Saída

Formato do produto: fragmento de corpo puro <section>…</section>, começando com o contêiner global, não inclua <!DOCTYPE>/<html>/<head>/<body> — o editor do WeChat aceita apenas fragmentos de corpo; invólucros extras de documento são descartados ou interferem na colagem.

1. Arquivo de corpo limpo: salve o HTML no diretório de trabalho atual, nome do arquivo: {nome_do_arquivo_original}_formatado_{nome_do_tema_em_chinês}({identificador_em_inglês}).html (identificador em inglês = nome do arquivo da biblioteca de componentes do theme-index sem o prefixo theme- e o sufixo .md). Este arquivo é usado para validação e colagem manual de fallback.
2. Página de pré-visualização com botão "Copiar" (para o usuário copiar com um clique, evitando seleção manual):

   <SKILL_ROOT>/scripts/wrap_preview.py <caminho_do_arquivo_de_corpo_limpo_acima>
   

   Gera {...}_preview.html — ao abrir no navegador, há um botão "Copiar para o WeChat" no canto superior direito; ao clicar, o rich text renderizado é copiado para a área de transferência (equivalente a Ctrl+A/Ctrl+C), e então Ctrl/⌘+V no editor do WeChat. O botão e o script estão apenas no invólucro de pré-visualização, não dentro da <section> a ser copiada, portanto, o que é colado no WeChat continua sendo o corpo limpo e conforme.
3. Informe ao usuário: Abra {...}_preview.html → clique em "Copiar" no canto superior direito → cole no editor do WeChat; e forneça o caminho do arquivo de corpo limpo como fallback. Anexe a conclusão do script de validação (aprovado / avisos restantes).

Processamento Inteligente Durante a Geração (Estas são características especiais desta skill, devem ser feitas)

1. Numeração automática de capítulos: Atribua 01/02/03… de acordo com a ordem de aparecimento dos ##; se o último capítulo for do tipo conclusão/resumo, use a variante de numeração de conclusão especificada pela biblioteca de temas (ex.: ∞), se a biblioteca de temas não especificar, continue com a numeração numérica.
2. Tags em inglês: Gere tags em inglês com base no título do capítulo em chinês (EXEMPLO → TEST, TUTORIAL → TUTORIAL, RESUMO → SUMMARY, PENSAMENTO → THOUGHTS…), use quando a biblioteca de temas tiver um slot correspondente.
3. Sublinhado de palavras-chave no corpo do texto (característica principal): Para cada parágrafo do corpo do texto, identifique ativamente 1–3 frases mais importantes e marque-as com o CSS de sublinhado do tema (consulte o theme-index). Priorize: ideias centrais, conclusões, dados-chave, nomes próprios; frases de 4–15 caracteres; se o parágrafo inteiro não tiver ponto principal, pode não marcar. Mesmo que o texto original não tenha nenhum negrito, adicione sublinhado ativamente — é a marcação básica mais frequente.
4. Destaque de palavras-chave na citação de abertura: Identifique palavras-chave na frase de ouro inicial e marque-as com o componente de destaque.
5. Extração de sumário: Pegue os primeiros 3 ## como pontos de guia/sumário (quando a biblioteca de temas tiver um componente de sumário).
6. Cartão de citação de abertura com atribuição: Defina de acordo com o autor ou tema do artigo — se o artigo tiver atribuição, escreva "— Nome do Autor"; se não houver autor claro, use uma breve assinatura relacionada ao tema ou omita. Não escreva fixamente "甲木" (a área de assinatura no final também usa o placeholder {{nome do autor}}, veja o item 7).
7. Área de assinatura do autor no final (autor preenche, apenas um local no final): Por padrão, não escreva nenhum nome fixo, use um placeholder de assinatura para o usuário substituir pelo seu próprio.
   • Primeira frase (apresentação do autor): Sou {{nome do autor}}, {{breve descrição, ex.: apaixonado por compartilhar observações e conteúdos sobre IA}} — se o usuário forneceu nome ou descrição na solicitação/preferência, preencha diretamente; caso contrário, mantenha os placeholders {{nome do autor}} / {{descrição}} e instrua o usuário a substituir pela sua própria assinatura na entrega.
   • Segunda frase (incentivo à interação, padrão pode ser mantido): Se você achou este artigo útil hoje, sinta-se à vontade para **curtir, compartilhar e recomendar** — nos vemos no próximo
   • Se o final do texto original já tiver um trecho de assinatura do autor (ex.: "Sou XXX…") → mantenha a assinatura original, não substitua por placeholder.
8. Conversão de listas: Processe de acordo com as regras de mapeamento da biblioteca de temas; se não houver componente de lista exclusivo, converta em parágrafos de corpo com recuo.
9. Pontuação de largura total em chinês: A pontuação no corpo do texto deve ser sempre de largura total (，。！？：；""''（）—— …), nunca use meia-largura , . ! ? : e aspas retas em inglês " '. Ao gerar HTML, escreva diretamente as aspas curvas ""'', não escreva aspas retas primeiro e depois substitua — as aspas retas no texto original são convertidas na hora ao reescrever. Exceção: blocos de código, código inline, nomes próprios em inglês/URLs/identificadores de código mantêm a forma original.

Hierarquia Visual (3 Níveis Progressivos, Comum a Todos os Temas)

Nível	Função	Frequência	Meio
Nível de Âncora	Âncora mais forte: nomes de produtos/passos/CTAs/frases de ouro principais	Até 5 em todo o artigo	Negrito na cor principal, citação com fundo escuro e texto branco
Nível de Marcação	Palavras-chave no corpo do texto, 1–3 por parágrafo	Alta frequência	Marcação com sublinhado
Nível de Contêiner	Blocos de citação, tags de conceito, ênfase em frases longas	Conforme necessário	Citação com fundo claro, marcador, insígnia

Linhas Vermelhas da Plataforma (Principal, Verificação Completa pelo Script de Validação)

• Proibido: <style>/<script>/<div>, atributos class/id, position:fixed/absolute/sticky, float, @media/@keyframes, display:grid, variáveis CSS, fontes/CSS externos.
• Obrigatório: todos os estilos inline style; todos os nós de texto devem ser encapsulados com <span leaf="">texto</span> (caso contrário, os estilos são perdidos após a colagem).
• Permitido: display:flex (limitado), border-radius, box-shadow, <section>/<p>/<span>/<strong>/<img>/<h3>.
• Compatibilidade de fundo gradiente: gradientes podem ser renderizados, mas podem acionar a detecção de estrutura de conteúdo darkmode-no-gradient do WeChat; fundos de texto e cartões devem, por padrão, usar cor sólida, sem adicionar gradientes. Componentes antigos/temas personalizados que encontrarem isso também devem seguir o Passo 5.

Gotchas (Armadilhas Encontradas em Formatações Reais)

• Falta de encapsulamento <span leaf> é o erro fatal mais comum — após colar no WeChat, todo o estilo é perdido. A verificação pelo script de validação no Passo 5 é a salvação; não pule.
• Sublinhado: implementar parágrafo por parágrafo, 1–3 frases por parágrafo. Não sublinhe o parágrafo inteiro (perde o foco), nem marque alguns parágrafos e pule outros; descrições-chave em itens de lista também devem ser marcadas.
• Numeração de capítulos incorreta: siga estritamente a ordem dos ##, não pule números; a variante de numeração de conclusão é usada apenas no último capítulo, não pode ser usada em capítulos intermediários.
• A área de assinatura existe apenas no final: use o texto fixo, não apareça no meio ou em vários lugares; se o final do texto original já tiver um parágrafo do tipo "assinatura do autor" / "curtir, compartilhar e recomendar", incorpore-o nesta única área de assinatura/cartão CTA, não mantenha o parágrafo original e gere outro.
• Invenção de descrição de imagem: só gere o componente de descrição se ![descrição](url) realmente tiver texto de descrição; se for ![](url) com alt vazio, não invente uma descrição.
• Imagem adaptativa, não esticada: <img> sempre com max-width:100%;height:auto;display:block;margin:0 auto — exibe a imagem em seu tamanho original, centralizada; imagens grandes são reduzidas à largura do contêiner, imagens pequenas mantêm o tamanho original. Não use width:100% (esticaria imagens pequenas, deixando-as borradas); apenas elementos de layout como tabelas, cartões de capa, diagramas de fluxo usam width:100%.
• Mistura de componentes entre temas: um artigo usa apenas componentes do tema selecionado + biblioteca comum, não pegue componentes de outros temas.
• Abuso do nível de âncora: a ênfase mais forte deve ser usada no máximo 5 vezes em todo o artigo; negrito em todo lugar equivale a nenhum destaque.
• Omissão de conteúdo original: cada parágrafo, cada imagem deve ser convertida; não omita; não adicione ou remova conteúdo substancial do texto original.
• Placeholder de imagem residual: se a área de assinatura/componente CTA tiver um placeholder de imagem de cartão de visita (ex.: <img src="...URL de cartão de visita ou imagem de guia">), e não houver URL de imagem real, remova a linha inteira; não deixe placeholders no produto final.
• Sumário é selecionado, não completo: o componente de guia/sumário na introdução exibe 3 pontos principais selecionados, não uma lista completa de capítulos; se houver mais de 3 capítulos, escolha os 3 mais importantes, não force a inserção ou induza o leitor a pensar que existem apenas 3 capítulos.
• Não use borda tracejada: para destacar título/ênfase, use pequenas tags ou barra vertical esquerda (biblioteca comum 3a–3e); não use border:…dashed ao redor de um título. Exceção: componentes tracejados claramente definidos na biblioteca de temas (ex.: o bloco de citação quote-box do Verde Preguiça, o cartão de destaque oneliner-card) são características de estilo do tema e podem ser usados normalmente conforme a biblioteca.
• Pontuação não misturada com meia-largura: vírgulas, pontos, aspas retas em inglês " ' no corpo do texto devem ser convertidos para largura total; mas símbolos de meia-largura dentro de blocos de código/código inline devem permanecer originais, não "alargue" o código.
• Código/Prompt devem usar bloco de código: código, comandos, prompts no artigo usam o componente de bloco de código da biblioteca comum (1a/1b); não os coloque em parágrafos comuns ou blocos de citação, caso contrário, o recuo e a largura fixa serão perdidos.
• Blocos de código devem ser compactos, evitar grandes espaços em branco: use a escrita "cada linha um <p style="margin:0">" dos componentes 1a/1b da biblioteca comum; nunca use white-space:pre — isso renderizaria o recuo antes de <span> e as quebras de linha entre linhas no código-fonte HTML como grande recuo à esquerda + linhas em branco; use apenas espaços de largura total 　 para recuo, e line-height:1.6 para espaçamento entre linhas.
• Centralização de materiais a serem complementados: placeholders como 【Inserir…】, [aguardando gravação de tela], GIF, vídeo, imagem de resultado, etc., use o componente 2c de placeholder de material centralizado da biblioteca comum (caixa de borda tracejada suave com fundo claro + ícone centralizado e descrição); não use bloco de dica alinhado à esquerda.

Geração de Tema Personalizado (Segundo Fluxo de Trabalho)

Quando o usuário quiser um novo estilo além dos temas integrados (disser "gerar um novo tema / estilo personalizado / criar um conjunto de componentes com base nesta imagem de referência", ou não estiver satisfeito com nenhum tema existente), leia references/theme-generator.md e execute estritamente de acordo com seu fluxo:

1. Coletar preferências: a descrição do tema é obrigatória (ou imagem de referência); nome/ID/cinco cores/fonte/três tipos de TAG/raio de borda/sombra podem ser deixados em branco e serão preenchidos automaticamente; pergunte tudo de uma vez, não faça perguntas campo por campo.
2. Gerar biblioteca de blocos HTML: execute exatamente o [Prompt de Geração] no final do theme-generator.md, produzindo uma biblioteca completa de 45~75 Blocos, salve em assets/theme-previews/{theme-id}.html — todos os blocos dispostos continuamente na mesma página; o usuário abre a página inteira de uma vez para confirmar o estilo, não confirme bloco por bloco.
3. Converter + Registrar: após o usuário confirmar o estilo, converta para o formato padrão references/theme-{identificador}.md (deve adicionar encapsulamento <span leaf="">, remover IDs de pré-visualização, completar os cinco capítulos; veja as regras detalhadas no terceiro passo do theme-generator.md), registre no theme-index.md, execute component_lint.py até 0 ERRO.
4. Após a entrega, o tema se torna um tema opcional permanente, com os mesmos direitos que os temas integrados em formatações futuras.

A fase de geração segue as regras do prompt; a fase de conversão para a biblioteca de temas segue este documento ("Linhas Vermelhas da Plataforma" e "Normas para Adicionar Novos Temas") — em caso de conflito, estas últimas prevalecem, pois a biblioteca de temas determina diretamente o produto da formatação.

Normas para Adicionar Novos Temas

Novos temas devem ser nomeados como references/theme-{identificador_em_inglês}.md, e o conteúdo deve incluir:

1. Tabela de Consulta Rápida de Variáveis de Design (cor principal/fundo claro/texto escuro/cor do título/cor do corpo/cor da linha divisória, etc.)
2. HTML completo de cada componente (estilo inline + encapsulamento <span leaf="">, respeitando as "Linhas Vermelhas da Plataforma" acima)
3. Esqueleto de template de artigo completo (ordem de montagem dos componentes; se houver componente de sumário/navegação, especifique sua posição relativa à capa/introdução)
4. Tabela de combinação de componentes por tipo de artigo (combinação principal de componentes + componentes de destaque para cada tipo de artigo; a receita é a chave para a consistência visual da formatação)
5. Tabela de regras de mapeamento Markdown → Componente

Após adicionar, registre uma linha em references/theme-index.md (nome do tema / cor principal / cenários de aplicação / arquivo da biblioteca de componentes / CSS de sublinhado do corpo) e execute python3 scripts/component_lint.py . para confirmar que a biblioteca de componentes não contém antipadrões (0 ERRO).

Casos de teste para regressão de acionamento e seleção de tema estão em references/eval-cases.md (usado para verificação de regressão durante a manutenção, não afeta a geração individual).