Criação de Documentos Técnicos em Coreano

Cria documentos técnicos e de negócios em coreano como HTML autocontido e, se necessário, os exporta para PDF.

Os dois modos de saída usam tokens de design comuns e CSS específico para cada modo.
Tabelas, figuras e ilustrações são geradas programaticamente a partir dos dados fornecidos.
O HTML não faz requisições a recursos externos no momento da execução.
A fonte do corpo do texto só é incorporada se --font for especificada.

As convenções de redação são de responsabilidade do skill korean-report-style. O escopo deste skill é limitado à produção.

1. Decisões Iniciais

1.1 Modo

	paper	deck
Finalidade	Análise, benchmark, relatório técnico, status	Reunião, pauta, solicitação de decisão
Orientação	Retrato	Paisagem
Páginas	Fluxo contínuo	1 seção = 1 página
Largura do corpo	720px	1120px
Densidade	Prosa completa	Um tópico por página
Template	`assets/paper_template.html`	`assets/deck_template.html`
Estrutura do corpo	`<section>` dentro de `<div class="doc">`	Sequência de `<section class="tile ...">`

Neste documento, layout refere-se à disposição de páginas e elementos, e typesetting refere-se à etapa de processamento que gera o HTML final, aplicando CSS, fontes e equações.

Não misture. Um deck com parágrafos longos parece um relatório com layout incorreto de deck, e um paper com fundo de tile parece uma impressão errada de slides.

1.2 Necessidade de Artefato

Crie o documento somente quando solicitado. Responda a explicações, resumos e análises na conversa. Faça um relatório, Gere em PDF, Organize em um documento são os sinais.

1.3 Ambiente de Execução

A construção HTML requer Node 20 ou superior e KaTeX. O mathbuild.js procura o KaTeX primeiro no diretório de trabalho e depois no caminho de instalação do skill.
A garantia de qualidade de renderização, capturas de tela e saída PDF requerem Python 3.11 ou superior, Playwright e Chromium.
Para incorporar a fonte do corpo, prepare arquivos WOFF2 com permissão de uso.

2. Pipeline de Build

Dados ──▶ Gerador (Python) ──▶ HTML bruto (marcadores de equação + tokens de substituição)
                                     │
                                     ▼
                      Pós-processamento (Node + KaTeX) — mathbuild.js
                      · Renderização de ⟦I⟧ / ⟦D⟧
                      · Inserção de base.css + CSS do modo
                      · Incorporação da fonte do corpo especificada e do KaTeX woff2 em base64
                                     │
                                     ▼
                          Único .html ──▶ impressão headless ──▶ .pdf

Os templates são carcaças finas contendo apenas tokens de substituição. As regras reais estão em assets/css/.

Token	Preenchido por
`__TITLE__` · `__BODY__`	Gerador
`__FONTCSS__` · `__KATEXCSS__` · `__BASECSS__` · `__MODECSS__`	`mathbuild.js`

Não escreva CSS diretamente nos templates. Já houve um incidente em que os dois templates copiavam as regras individualmente, e as regras de impressão do deck sobrescreviam as do paper. O CSS comum fica em css/base.css, e o específico de cada modo, em css/paper.css e css/deck.css, cada um em um único local.

2.1 Escrevendo o Gerador

import sys; sys.path.insert(0, "<caminho-do-skill>/assets")
from figures import tbl, wide, fig_gantt, fig_flow, figcap, esc, BADGE_MEAS

def I(t): return "⟦I⟧" + t + "⟦/I⟧"   # Equação inline
def D(t): return "⟦D⟧" + t + "⟦/D⟧"   # Equação em display

def sub(tpl, *args):
    """Substitui %s sequencialmente e devolve %% como %"""
    out, i, ai = [], 0, 0
    while True:
        j = tpl.find("%s", i)
        if j < 0:
            out.append(tpl[i:]); break
        out.append(tpl[i:j]); out.append(str(args[ai])); ai += 1; i = j + 2
    return "".join(out).replace("%%", "%")

BODY = sub('''<section id="s1"><h2><span class="sn">1</span>Título</h2>
%s
</section>''', tbl(...))

TPL = open("paper_template.html", encoding="utf-8").read()
out = TPL.replace("__BODY__", BODY).replace("__TITLE__", "Título do Documento")
open("raw.html", "w", encoding="utf-8").write(out)

Os delimitadores de equação devem ser obrigatoriamente ⟦I⟧ e ⟦D⟧. Delimitadores ASCII como %%I%% podem gerar acidentalmente %%D%% em equações de um caractere (como I(r"D")), fazendo o analisador interpretar erroneamente. Isso é um bug real que já ocorreu. O build falha se encontrar marcadores da versão antiga.

Não escreva tokens de substituição em comentários ou no corpo do texto. Como str.replace do Python substitui todas as ocorrências, se __BODY__ estiver em um comentário, o corpo será inserido duas vezes. Isso também já aconteceu.

O fluxo de geração completo consiste em colocar as figuras de assets/figures.py em assets/paper_template.html ou assets/deck_template.html e, em seguida, pós-processar com assets/mathbuild.js.

2.2 Pós-processamento

node mathbuild.js raw.html out.html \
     --assets <caminho-do-skill>/assets \
     --font Pretendard-Regular.woff2 --font Pretendard-SemiBold.woff2

No momento da construção, as equações são renderizadas pelo KaTeX, e apenas os woff2 referenciados pelo resultado da renderização são selecionados e incorporados como base64. A fonte completa tem 1,2 MB, mas o necessário é cerca de 160 KB.

Em caso de falha, a saída é exit 1. Erros de equação, tokens não substituídos, marcadores antigos e caminhos de fonte inexistentes interrompem o build. Uma equação renderizada incorretamente em silêncio é pior do que a ausência de equação.

Se --font for omitido, apenas um aviso é emitido e o processo continua. Nesse caso, o documento usará as fontes do sistema do leitor, fazendo com que o resultado do typesetting varie entre dispositivos. Para distribuição, as fontes devem ser incorporadas.

2.3 PDF

python <caminho-do-skill>/assets/qa.py out.html --pdf --shot shots/

Para chamar diretamente:

from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    b = p.chromium.launch(); pg = b.new_page()
    pg.goto('file:///abs/path/out.html'); pg.wait_for_timeout(2500)
    pg.pdf(path='out.pdf', format='A4', print_background=True)   # deck: landscape=True
    b.close()

Dê um wait_for_timeout suficiente. Imprimir antes do carregamento de fontes e imagens resulta em documento corrompido.

3. Figuras

Todas as figuras são SVG inline. Não crie PNGs com matplotlib. Elas são nítidas quando ampliadas, herdam tokens, seu texto é pesquisável e o arquivo não fica grande.

assets/figures.py fornece 7 tipos — timeline, gantt, grid de cartões, fluxo, linha vertical, barras de contraste e dispersão. As coordenadas são calculadas em Python e inseridas como literais no SVG. Calculá-las com JavaScript no navegador não funcionaria da mesma forma na saída PDF.

As cores são especificadas por classes, não por hex (preenchimento fi-*, traçado st-*). O base.css associa essas classes a variáveis CSS; assim, em tiles escuros, basta alterar os tokens para que as figuras acompanhem. Inserir hex pode fazer com que #1d1d1f desapareça sobre um tile #272729.

Consulte references/figures.md para as regras detalhadas.

3.1 Exceções para Raster

Visualizações que sobrepõem dados de medição a desenhos reais ou nuvens de pontos não podem ser feitas manualmente em SVG. Nesse caso, rasters são permitidos, desde que três condições sejam atendidas:

Incorporados como data URI em base64 — referências a caminhos relativos quebram se o arquivo for movido
Com borda — use a classe .plate (borda de 1px, raio de 10px, largura máxima de 820px)
Valores numéricos escritos nativamente — para que o raster não seja o único portador da evidência

4. QA — Inspeção Pós-renderização

Não confie na fonte. Renderize no navegador para inspecionar.

python <caminho-do-skill>/assets/qa.py out.html --shot shots/

Verifica a presença de marcadores de equação e tokens de substituição não processados, overflow horizontal, tabelas que ultrapassam o contêiner, falha na inserção de CSS, figuras fora do viewBox e figuras sem legenda. Em caso de falha, a saída é exit 1.

Em decks, a inspeção inclui o layout de impressão. Se um tile ultrapassar uma página (A4 paisagem: 210mm), a verificação falha e informa qual tile e quantos pixels excederam. Como .tile tem overflow: hidden na impressão, o conteúdo excedente é cortado silenciosamente — a falha mais comum em decks. Se houver overflow, não reduza o tipo; divida a seção (design.md §7.1).

4.1 Itens que Requerem Inspeção Humana

O que a máquina não consegue detectar é verificado por meio de capturas de tela e PDF.

Impressão

O número de páginas corresponde ao esperado (deck: número de seções = número de páginas)
Tabelas, equações e callouts não são cortados nos limites da página
Não há páginas mais da metade vazias
Títulos não ficam isolados no final da página
Tiles escuros são invertidos na impressão

Numeração

A numeração de figuras, tabelas, seções e riscos é sequencial
As referências no texto (§5.2, Figura 8) apontam para os alvos reais

Se a edição foi realizada várias vezes, execute a verificação a cada vez. A exclusão de um único item pode quebrar a numeração e as referências em cascata.

5. Tratamento de Solicitações de Edição

Solicitações de modificação no documento devem ser tratadas como operações estruturais, não como simples substituição de texto.

Solicitação	Ações Conjuntas
Exclusão de item	Renumerar itens subsequentes · Atualizar referências no texto · Revisar resumo · Remover definições não utilizadas
Exclusão de seção	Verificar consistência da lista de argumentos · Verificar se funções de figura não estão mais em uso · Renumerar subseções
Exclusão de coluna de tabela	Revisar frases introdutórias que perderam o sentido · Verificar consistência das colunas restantes
Suavização de redação	Verificar globalmente se a mesma expressão aparece em rótulos de figuras, legendas e células de tabela

Comunique as cascatas. Pergunte, por exemplo: "Se eu excluir a S3, o resumo abaixo referencia a S4. Quer que eu corrija junto?" Corrigir silenciosamente faz com que o usuário não saiba o que mudou.

6. Pontos que Exigem Julgamento

Exclusão de ressalvas — Excluir critérios arbitrários ou itens não medidos pode fazer com que os números pareçam verificados. Mesmo que a solicitação seja de exclusão, pergunte se pode mantê-los em uma única linha.
Aviso de correção — Se os critérios de cálculo de valores compartilhados anteriormente mudaram, mesmo que o tom seja suavizado, o fato deve ser mantido.
Limite entre análise e layout do documento — Descobrir relações nos dados está fora do escopo deste skill, mas impacta significativamente o valor do documento. Se os números forem fornecidos, valide a consistência e alerte se houver anomalias.

7. Arquivos de Referência

references/design.md — Regras completas de cor, tipografia, componentes e impressão
references/figures.md — Uso e convenções de coordenadas dos 7 tipos de figura
assets/paper_template.html · assets/deck_template.html
assets/css/base.css · assets/css/paper.css · assets/css/deck.css
assets/figures.py · assets/mathbuild.js · assets/qa.py

JangHyun-bin/korean-report-skills

O que é korean-report-skills?

Perguntar na sua IA favorita

Documentação

Criação de Documentos Técnicos em Coreano

1. Decisões Iniciais

1.1 Modo

1.2 Necessidade de Artefato

1.3 Ambiente de Execução

2. Pipeline de Build

2.1 Escrevendo o Gerador

2.2 Pós-processamento

2.3 PDF

3. Figuras

3.1 Exceções para Raster

4. QA — Inspeção Pós-renderização

4.1 Itens que Requerem Inspeção Humana

5. Tratamento de Solicitações de Edição

6. Pontos que Exigem Julgamento

7. Arquivos de Referência

Habilidades Relacionadas

steipete/notion

langchain-ai/langchain

bytedance/podcast-generation

composiohq/twitter-algorithm-optimizer

composiohq/competitive-ads-extractor

upstash/context7