szcharlesji/tikz-explorer-book

Livro explorador TikZ

Você está fazendo um livro que alguém irá explorar: uma única página web cuja página inicial é um mapa conceitual de todo o campo, e cujos capítulos tornam uma ideia visível com figuras TikZ cuidadosamente computadas. O leitor quer ver o panorama primeiro, conectar os pontos e, em seguida, se aprofundar onde escolher.

A visualização é a prioridade. Um capítulo são suas figuras. O texto leva a uma figura e extrai a conclusão dela; ele nunca substitui uma figura que poderia mostrar a mesma coisa. Ao equilibrar o tempo, priorize a qualidade da figura e corte a prosa.

Esta skill orquestra; a criação das figuras reside em duas skills irmãs que compartilham uma linguagem visual (dlviz.sty, cor = função). Elas vêm juntas e ficam ao lado da pasta desta skill; abaixo, <skills> significa a pasta que contém as três (a pasta pai desta skill, onde quer que esteja instalada):

• tikz-dl-visualizer (<skills>/tikz-dl-visualizer/): figuras estáticas. Seu arquivo de estilo, arquétipos e script de renderização definem o que é uma boa figura. A maioria das figuras em um livro são estáticas.
• tikz-live (<skills>/tikz-live/): figuras vivas. Um esqueleto TikZ compilado por pdflatex mais uma pequena especificação JS que desenha a parte móvel, para que o leitor possa arrastar um ponto de partida, deslizar uma temperatura ou passar o mouse sobre um token enquanto cada rótulo continua sendo TeX real. O livro as incorpora e elas seguem seu tema claro/escuro.

Leia ambos os arquivos SKILL.md uma vez antes de planejar, para saber o que é uma boa figura e quando a interação merece seu lugar.

O que você entrega

<book>/
├── book.json            título, partes, ids dos capítulos, funções de cor, configurações do mapa
├── SPEC.md              o contrato que todo autor de capítulo segue
├── chapters/00-front.html   hero, espaço do mapa, como ler, convenções, legenda
├── chapters/<cid>.html  uma <section class="chapter"> por capítulo
├── figs/<cid>-<slug>.tex/.png/-light.png/.pdf
├── figs/<cid>-<slug>.js     apenas figuras vivas: a especificação; fig.sh também escreve
│                            .live.html (incorporado pela build), .html (autônomo)
│                            e <slug>.<snapshot>.png (para revisão)
├── scripts/<cid>-<slug>.py  o Python por trás de cada número em uma figura
├── map/data.json        mapa conceitual: famílias, conceitos, trabalhos-chave, links, tour
├── tools/               build.py, shell.html (design da página), fig.sh, dllive.js (runtime ao vivo)
└── index.html, preview.html   página construída (publique index.html)

Requisitos: uma instalação TeX com TikZ/pgfplots (pdflatex), Ghostscript ou poppler para PNGs, ImageMagick para folhas de contato, uv (ou Python com numpy/scipy) para números das figuras, e para figuras vivas node mais PyMuPDF (uv run --with pymupdf, que fig.sh faz para você). A página carrega MathJax (jsDelivr) e d3 (cdnjs). Verifique which pdflatex gs magick uv node no início; se pacotes TeX estiverem faltando, diga ao usuário o comando tlmgr install em vez de instalar.

Fluxo de trabalho

1. Entenda a fonte e o leitor

Leia a fonte (busque o calendário do curso ou programa, liste as leituras). Em seguida, defina o leitor: o que ele já sabe (pule o básico que ele conhece, mas ainda desenhe os fundamentos bem) e aonde ele está mirando (um emprego, um exame, uma direção de pesquisa). O objetivo decide a forma do livro:

• A Parte I segue a fonte, um capítulo por sessão ou unidade. Cada um vai fundo em uma ideia em vez de resumir tudo.
• A Parte II é um kit de ferramentas para o objetivo do leitor, por exemplo, "o que um pesquisador de geração de vídeo deve saber": os fundamentos transversais que a fonte assume ou ignora, práticos e atuais, com números reais. Pule a Parte II se o leitor não tiver nenhum objetivo além da fonte.
• A página inicial é um mapa conceitual: o panorama geral antes de qualquer profundidade.

Pergunte ao usuário apenas quando o objetivo estiver genuinamente obscuro; caso contrário, declare sua interpretação em uma linha e siga em frente.

2. Planeje capítulos em torno de figuras

Para cada capítulo, escreva uma breve descrição: o fio condutor profundo (uma frase), 2–3 figuras com o que cada uma deve tornar visível, qual arquétipo e o que computar. Este é o passo mais importante. Briefings que nomeiam o mecanismo geram ótimas figuras; briefings que nomeiam um tópico geram diagramas de caixa.

• Fraco: "figura sobre orientação sem classificador".
• Forte: "Mistura 1-D de duas classes; integre a EDO guiada com velocidades exatas para w = 0, 1, 2, 4; pequenos múltiplos das densidades resultantes contra p(x|c) e a densidade inclinada, mostrando que a orientação ultrapassa a inclinação".

Bons assuntos para figuras: um mecanismo em ação (caminhos, fluxos, atualizações), um antes/depois, uma comparação de dois métodos em entradas idênticas, formas e contagens (formas de tensores, contagens de tokens, FLOPs), um experimento numérico cujo resultado é o ponto principal. Cada uma deve ser computável: o autor produzirá cada número em Python.

Decida quais figuras são vivas. Uma figura merece interação quando o leitor aprende mudando algo e observando o mecanismo responder, de uma forma que uma imagem estática ou pequenos múltiplos não conseguem mostrar tão bem. Escreva sua frase de interação no briefing: "o leitor arrasta X / desliza Y / passa o mouse sobre Z e vê W". Orçamento: cerca de uma figura viva por capítulo, para o mecanismo principal do capítulo; todo o resto estático. Bons candidatos: caminhos de otimizadores (arraste o início, deslize β), atenção ou convolução (passe o mouse sobre uma linha ou célula), um peso de orientação ou varredura de temperatura, um mapa linear (arraste os vetores de base), etapas de amostragem (reproduzir). Ruins: pipelines, diagramas de arquitetura, qualquer coisa onde pequenos múltiplos já mostrem a tendência.

• Briefing para figura viva: "Mistura 1-D de duas classes; o leitor desliza o peso de orientação w de 0 a 6 e vê a densidade orientada ultrapassar o alvo inclinado; um botão de reprodução integra a EDO passo a passo; números: KL em relação ao alvo, ao vivo."

Decida também, uma vez, para todo o livro: as funções de cor (qual cor significa o quê; coloque-as em book.json para que figuras, matemática da prosa e a legenda concordem), as convenções sobre as quais o campo discorda (direção do tempo, sinais, notação e símbolos que significam coisas diferentes em capítulos diferentes, como (v) para a velocidade do momentum e o segundo momento do Adam) e os ids dos capítulos (w01…, v01…; a letra se torna o prefixo do rótulo da figura, W3.2, V5.1).

3. Estrutura inicial

python3 <skill>/scripts/init_book.py <book> --title "Título do Livro" --sub "Fonte · Termo"

Edite book.json (partes, ids dos capítulos, funções) e chapters/00-front.html; leia cada um primeiro, pois as ferramentas de arquivo se recusam a sobrescrever um arquivo que você não leu. As funções do modelo são genéricas de aprendizado profundo (entrada, oculta, latente...): substitua-as pelas do próprio campo (para otimizadores: iterar, gradiente, velocidade, perda...). Escreva <book>/SPEC.md a partir de references/author-spec.md, preenchendo cada bloco «…»: leitor, partes, tabela de funções, convenções, mapa de capítulos. Os autores veem apenas SPEC.md e seu briefing, portanto SPEC.md deve ser autossuficiente. Escreva-o mesmo quando você mesmo for o autor do livro: é onde as convenções vivem para capítulos posteriores e sessões posteriores.

Antes de lançar qualquer pessoa, renderize uma figura descartável através de bash <book>/tools/fig.sh para provar que o pipeline TeX funciona e, se o plano tiver figuras vivas, também uma figura viva: copie <skills>/tikz-live/assets/examples/momentum/momentum.{tex,js} para figs/_test/, execute bash <book>/tools/fig.sh figs/_test/momentum.tex, depois rm -rf <book>/figs/_test (seus intermediários vivem em figs/_test/.dllive/, portanto nada é deixado para trás). Isso prova que node e PyMuPDF funcionam e coloca tools/dllive.js no lugar. Um pipeline quebrado descoberto por nove autores em paralelo custa nove vezes mais.

4. Delegue os capítulos

Para um curso completo (10+ capítulos), dispare subagentes de propósito geral em paralelo, cada um sendo dono de 2–4 capítulos relacionados (cerca de 5–7 figuras). Cada prompt diz: leia <book>/SPEC.md primeiro e siga-o; os ids dos capítulos dos quais é dono; por capítulo, os metadados da sessão, artigos, o fio condutor profundo e os briefings das figuras; renderize, veja, corrija e depois relate por seção SPEC 5. Agrupe capítulos relacionados sob um autor para que figuras compartilhadas permaneçam consistentes (por exemplo, OT dinâmico com acoplamentos OT).

Os limites de uso são reais: nove autores de uma vez podem esgotar um limite de sessão no meio da execução. Se os agentes pararem com um erro de limite de taxa, seus arquivos serão mantidos. Retome cada um com SendMessage ("continue de onde parou; verifique o que já fez") quando o limite for reiniciado, em vez de iniciar novos agentes. Para livros grandes, considere lançar em duas ondas.

Para um livro pequeno (um tópico, 3–5 capítulos), pule os subagentes e escreva-o você mesmo, ainda seguindo SPEC.md.

5. Enquanto os autores desenham: material inicial e o mapa

Escreva chapters/00-front.html (hero, como ler, as convenções, a legenda <!--ROLES-->, opcionalmente uma tabela espelhando a fonte, por exemplo, o calendário do curso com links para capítulos) e map/data.json. Leia references/concept-map.md para o esquema e como escolher famílias, nós, relações e o tour. O mapa é uma visão geral: o que cada ideia é, onde se encaixa, como se relaciona e qual capítulo se aprofunda. Não explique mecanismos ali.

6. Revise à medida que os relatórios chegam

Cada relatório lista as frases de uma ideia de suas figuras e suas afirmações não verificadas. Abra você mesmo as figuras mais importantes (a comparação principal, qualquer coisa que o usuário pediu pelo nome) e verifique-as com os fatos que você conhece. Envie correções concretas de volta para o autor que a desenhou.

7. Monte, verifique, leia

python3 <book>/tools/build.py
python3 <skill>/scripts/check_book.py <book> --sheet

Em seguida, siga references/qa-and-publish.md: olhada na folha de contato, verificações no navegador (erros de matemática, transbordamento em largura de telefone, mapa, modo claro, figuras vivas: todas montadas, arrastar e passar o mouse funcionam, a alternância de tema as recoloriza) e leia o texto de cada capítulo antes de publicar. Corrija deslizes de metadados (números de sessão, datas) que os autores herdaram de seus briefings.

Não pule a verificação no navegador. As verificações estáticas não conseguem executar o JavaScript da página, e as falhas mais importantes são silenciosas: um mapa que nunca renderiza, matemática que para de tipografar. Se você realmente não puder abrir um navegador, diga isso na entrega e liste as verificações do navegador como não feitas.

8. Publique

Publique <book>/index.html como um Artefato com cada PNG de figura como um arquivo de suporte (check_book.py --files-json imprime a lista; figuras vivas são incorporadas na página, portanto seus PNGs são deixados de fora), ou entregue a pasta se nenhuma ferramenta de Artefato existir. Diga ao usuário o que está em cada parte, o que não está verificado, quais figuras são ilustrações em vez de resultados computados e como reconstruir (python3 tools/build.py) ou re-renderizar uma figura.

Solicitações posteriores

Edite a mesma pasta e republicue o mesmo caminho de arquivo, para que o link permaneça o mesmo: adicione um capítulo (anexe seu id em book.json), estenda o mapa (edite map/data.json) ou mude o estilo (edite tools/shell.html). Mantenha as correções listadas em references/qa-and-publish.md §3 ao tocar no shell ou map.js.

Arquivos de referência

• references/author-spec.md — o modelo para SPEC.md, o contrato dos autores dos capítulos (regras de figuras, formato de fragmento HTML, regras de citação).
• references/concept-map.md — esquema de map/data.json e como escrever um mapa que conecta os pontos.
• references/qa-and-publish.md — verificações, trechos de navegador, armadilhas conhecidas já corrigidas no modelo, publicação.
• assets/template/ — o esqueleto do livro que init_book.py copia.