37-vertin/markdown-math-render

Regras de Renderização de Fórmulas Matemáticas em Markdown e Verificação

Cadeia de Gatilhos: Três Seguranças para Evitar que a Habilidade Não Seja Executada

Esta habilidade garante a execução ao escrever fórmulas por meio de três vias de segurança:

1. Gatilho Antecipado: A description declara "antes de escrever qualquer fórmula matemática" para acionamento, sem esperar falhas de renderização para correção.
2. Montagem no Fluxo de Trabalho: A habilidade principal do repositório math-question-skill (D:\math_question\SKILL.md) faz referência a esta habilidade em suas regras obrigatórias — qualquer resolução de problemas, explicações ou questões do dia passam por esta cadeia.
3. Autoverificação Pré-publicação: Antes de finalizar saídas com fórmulas, execute scripts/check_inline_math.py para escanear; se encontrar $...$ inline, deve ser convertido para fórmula em bloco ou texto puro antes de enviar/gravar.

Regras Principais (Obrigatórias no App Codex)

O aplicativo Codex desktop renderiza apenas fórmulas em bloco $$...$$ em linhas independentes, não renderiza $...$ inline (conforme confirmado no issue #14985 oficial). A fórmula em si está correta, o problema é o delimitador errado:

❌ $f(x)=\sqrt[3]{x}$                     ← inline $...$, App não renderiza
❌ $\dfrac{f(x_0+h)-f(x_0)}{h}$           ← inline $...$, App não renderiza

Correção — isole a fórmula em uma linha independente usando $$...$$:

✅ Então
$$
f'(x_0)=\lim_{h\to0}\dfrac{f(x_0+h)-f(x_0)}{h}
$$
é diferenciável ⟺ o limite existe e é finito

Expressões inline curtas devem ser embelezadas com símbolos Unicode, com aparência próxima ao resultado renderizado:

• Sobrescrito/Subscrito: xˣ (U+02E3), 10⁶, 2ⁿ, x₀, x₁
• Raiz: √x (U+221A), ∛x (U+221B raiz cúbica)
• Fração com sobrescrito: x¹⁄³ (¹ U+00B9 + ⁄ U+2044 + ³ U+00B3)
• Apóstrofo de derivada: f′(x) (U+2032, não usar apóstrofo reto ')
• Operadores/relacionais: ·, −, ±, ∞, ≠, ≤, ≥, ∈

⚠️ Não usar notação de programação ^(...): x^(1/3) parece código-fonte; substitua por ∛x ou x¹⁄³.

Expressões inline complexas (frações, raízes, limites) devem ser convertidas em bloco $$...$$, não forçadas como texto puro.

O que fazer quando o usuário pedir "manter fórmulas inline" (regras rígidas permanecem inalteradas)

Durante a conversa, o usuário pode dizer "mantenha $...$ inline, apenas corrija espaços grudados" — isso não altera o comportamento de renderização do App. $...$ inline nunca é renderizado no App Codex; adicionar espaços resulta em "código-fonte + espaços", piorando a aparência, ainda considerado falha (lição histórica: após corrigir espaços grudados, usuários ainda relatavam "estes lugares ainda estão com problemas", a causa raiz era que $...$ inline não foi convertido para Unicode). Portanto:

• Antes da finalização, ainda siga as regras rígidas: expressões inline curtas convertidas para Unicode, expressões complexas isoladas em linhas independentes $$...$$;
• Se o usuário insistir explicitamente em manter $...$ inline, primeiro explique as consequências (App exibe código-fonte) e anexe um "aviso de renderização" no final da saída;
• Não pule a autoverificação check_inline_math.py devido à solicitação do usuário; [FAIL] deve ser zerado para conclusão.

Tabela de Conversão Rápida: Fórmula Inline → Unicode

Cenário	LaTeX Inline (proibido)	Correção Unicode
Variável de letra única	$f$, $g$, $A$	f, g, A (texto puro)
Sobrescrito/Subscrito	$x^n$, $x_0$, $a_n$	xⁿ, x₀, aₙ
Radicais	$\sqrt{x}$, $\sqrt[3]{x}$	√x, ∛x
Frações	$\frac1n$, $\frac{x^n}{1+x}$	Curta 1/n; complexa separar em bloco $$...$$
Limites	$\lim_{n\to\infty}a_n$	lim(n→∞) aₙ (Unicode sem seta subscrita, condição de aproximação entre parênteses após lim; complexo separar em bloco)
Integrais	$\int_0^1 f(x)\,dx$	Complexo separar em bloco $$...$$, não forçar inline
Valor absoluto	$\lvert x\rvert$	`
Conjuntos/Relacionais	$x\in[0,1]$, $f\le g$	x∈[0,1], f ≤ g
Setas	$x\to0$, $n\to\infty$	x→0, n→∞
Elipse	$a_1+\cdots+a_k$	a₁+…+aₖ

Fórmulas em Tabelas (Segunda Situação Mais Frequente no App Codex)

Dentro de células de tabela, $...$ não é renderizado; e $$...$$ em linhas independentes quebra a linha da tabela. Nunca coloque delimitadores de fórmulas em células de tabela:

Prática	Explicação
❌ Escrever $x^{1/3}$ na célula	Inline não renderiza, exibe como código-fonte
❌ Escrever $$x^{1/3}$$ na célula	Delimitadores multilinha quebram a tabela
✅ Colocar apenas texto puro/Unicode na célula	∛x, `
✅ Colocar fórmulas abaixo da tabela	Cada fórmula em linha independente $$...$$, logo após a tabela
✅ Conteúdo predominantemente de fórmulas	Usar lista estruturada (subtítulo + $$...$$), evitar tabela

Exemplo — três exemplos de não diferenciabilidade:

Função	Modo de falha em x = 0
∛x	Tangente vertical, quociente de diferenças → +∞
x·sin(1/x)	Oscilação violenta, limite não existe

Fórmula abaixo da tabela:

$$ \lim_{h\to0}\frac{h^{1/3}}{h}=+\infty $$

Autoverificação Pré-publicação (30 segundos, obrigatório antes da finalização)

⚠️ Primeiro defina a codificação do console para UTF-8: O console padrão do Windows é GBK, scripts com saída contendo chinês ou emoji (como ✅) geram UnicodeEncodeError ou caracteres ilegíveis. Antes de executar a verificação:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8
$env:PYTHONIOENCODING = 'utf-8'

Rascunho de resposta do chat:

python "D:\math_question\.agents\skills\markdown-math-render\scripts\check_inline_math.py" - < rascunho.txt

Arquivo já gravado a ser verificado:

python "D:\math_question\.agents\skills\markdown-math-render\scripts\check_inline_math.py" "D:\math_question\arquivo_alvo.md"

• Código de saída 0 (saída [OK]) → limpo, pode enviar/gravar
• Código de saída 0 + aviso [STYLE] → há ^(...) estilo código (ex.: x^(1/3)), aparência de código-fonte, sugere alterar para ∛x/x¹⁄³ ou fórmula em bloco (sugestão de estilo, não bloqueante)
• Código de saída 1 (saída [FAIL] com números de linha) → dois tipos de problemas: $...$ inline (converter para $$...$$ em linha independente ou Unicode/texto puro); $$...$$ não em linha independente (mover texto no início/fim da linha com $$). Corrija por linha e reexecute até nenhum [FAIL]

Confirmar que a Fórmula em Si Não Está Quebrada (30 segundos)

O repositório inclui KaTeX CLI para verificação de sintaxe TeX:

@'
\dfrac{f(x_0+h)-f(x_0)}{h}
'@ | node scripts/node_modules/katex/cli.js

• Saída contém <annotation ...> e código de saída 0 → fórmula correta, problema é delimitador/renderizador
• ParseError lançado → erro de sintaxe TeX, corrija a fórmula primeiro

Princípio em Uma Frase

No App Codex, fórmulas sempre em linhas independentes com $$...$$; inline curtas com Unicode sobescrito/subscrito (xˣ, f′(x)); células de tabela nunca contêm fórmulas, fórmulas abaixo da tabela; antes da finalização, execute check_inline_math.py como garantia, proibido $...$ inline.