szcharlesji/tikz-explorer-book

TikZ 탐험형 북

당신은 누군가가 탐험하게 될 책을 만듭니다: 전체 분야의 개념 지도를 홈으로 하는 단일 웹 페이지이며, 각 장은 신중하게 계산된 TikZ 그림을 통해 하나의 아이디어를 시각적으로 드러냅니다. 독자는 먼저 지형을 살펴보고, 점들을 연결한 다음, 원하는 곳을 깊이 파고들고 싶어 합니다.

시각화가 최우선입니다. 장은 곧 그림입니다. 텍스트는 그림으로 이끌고 그림에서 결론을 도출합니다. 텍스트가 같은 내용을 보여줄 수 있는 그림을 대체하지는 않습니다. 시간을 절충할 때는 그림 품질을 유지하고 산문을 줄이십시오.

이 스킬은 조정 역할을 합니다. 그림 제작은 하나의 시각 언어(dlviz.sty, 색상 = 역할)를 공유하는 두 개의 자매 스킬에 존재합니다. 이들은 함께 제공되며 이 스킬의 폴더 옆에 있습니다. 아래에서 <skills>는 세 스킬 모두를 포함하는 폴더(이 스킬의 상위 폴더, 설치된 위치)를 의미합니다.

• tikz-dl-visualizer (<skills>/tikz-dl-visualizer/): 정적 그림입니다. 스타일 파일, 아키타입 및 렌더링 스크립트는 좋은 그림의 기준을 정의합니다. 책의 대부분 그림은 정적입니다.
• tikz-live (<skills>/tikz-live/): 라이브 그림입니다. pdflatex으로 컴파일된 TikZ 스캐폴드와 움직이는 부분을 그리는 작은 JS 사양으로, 독자가 시작점을 드래그하고, 온도를 슬라이드하거나 토큰에 호버할 수 있으며 모든 레이블은 실제 TeX으로 유지됩니다. 책에 인라인으로 포함되며 라이트/다크 테마를 따릅니다.

계획을 세우기 전에 두 SKILL.md 파일을 모두 읽어 좋은 그림이 무엇인지, 상호작용이 언제 가치가 있는지 파악하십시오.

제공되는 결과물

<book>/
├── book.json            제목, 파트, 장 ID, 색상 역할, 지도 설정
├── SPEC.md              모든 장 작성자가 따라야 할 계약서
├── chapters/00-front.html   히어로, 지도 슬롯, 읽는 방법, 규칙, 범례
├── chapters/<cid>.html  각 장에 대한 하나의 <section class="chapter">
├── figs/<cid>-<slug>.tex/.png/-light.png/.pdf
├── figs/<cid>-<slug>.js     라이브 그림 전용: 사양; fig.sh가 .live.html(빌드에 인라인됨),
│                           .html(독립 실행형) 및 <slug>.<snapshot>.png(검토용)도 작성
├── scripts/<cid>-<slug>.py  그림의 모든 숫자 뒤에 있는 Python
├── map/data.json        개념 지도: 패밀리, 개념, 주요 연구, 링크, 투어
├── tools/               build.py, shell.html(페이지 디자인), fig.sh, dllive.js(라이브 런타임)
└── index.html, preview.html   빌드된 페이지(index.html 게시)

요구 사항: TikZ/pgfplots가 포함된 TeX 설치(pdflatex), PNG용 Ghostscript 또는 poppler, 연락처 시트용 ImageMagick, 그림 숫자용 uv(또는 numpy/scipy가 포함된 Python), 라이브 그림의 경우 node와 PyMuPDF(uv run --with pymupdf, fig.sh가 자동으로 처리). 페이지는 MathJax(jsDelivr)와 d3(cdnjs)를 로드합니다. which pdflatex gs magick uv node를 일찍 확인하십시오. TeX 패키지가 누락된 경우 설치하는 대신 tlmgr install 명령을 사용자에게 알리십시오.

워크플로우

1. 출처와 독자 이해

출처를 읽으십시오(강의 일정이나 교과 과정을 가져오고, 읽기 목록을 나열). 그런 다음 독자를 파악하십시오: 그들이 이미 알고 있는 것(알고 있는 기본은 건너뛰되, 기본은 여전히 잘 그릴 것)과 그들이 목표로 하는 것(취업, 시험, 연구 방향). 목표는 책의 구조를 결정합니다.

• 파트 I은 출처를 따릅니다, 세션이나 단위당 하나의 장. 각 장은 모든 것을 요약하기보다 하나의 아이디어에 깊이 들어갑니다.
• 파트 II는 독자의 목표를 위한 도구 키트입니다, 예: "비디오 생성 연구자가 반드시 알아야 할 것": 출처가 가정하거나 건너뛰는 교차적인 기본 사항, 실용적이고 최신이며 실제 숫자가 포함됩니다. 독자가 출처 외에 다른 목표가 없다면 파트 II는 생략하십시오.
• 홈페이지는 개념 지도입니다: 깊이 들어가기 전의 큰 그림.

목표가 명확하지 않은 경우에만 사용자에게 물어보십시오. 그렇지 않으면 한 줄로 해석을 명시하고 진행하십시오.

2. 그림 중심으로 장 계획

각 장에 대해 브리핑을 작성하십시오: 깊은 연결 고리(한 문장), 2~3개의 그림과 각각이 시각화해야 할 내용, 아키타입, 계산할 내용. 이것이 가장 중요한 단계입니다. 메커니즘을 명명한 브리핑은 훌륭한 그림을 제공하고, 주제를 명명한 브리핑은 상자 다이어그램을 제공합니다.

• 약함: "분류기 없는 안내에 관한 그림".
• 강함: "1차원 두 클래스 혼합; w = 0, 1, 2, 4에 대해 정확한 속도로 안내된 ODE를 적분; 결과 밀도의 소규모 배수와 p(x|c) 및 기울어진 밀도, 안내가 기울기를 초과함을 보여줌".

좋은 그림 주제: 작동 중인 메커니즘(경로, 흐름, 업데이트), 전후 비교, 동일한 입력에 대한 두 방법 비교, 모양 및 개수(텐서 모양, 토큰 개수, FLOPs), 결과가 요점인 수치 실험. 각각은 계산 가능해야 합니다. 작성자는 모든 숫자를 Python으로 생성할 것입니다.

어느 그림이 라이브가 될지 결정하십시오. 독자가 무언가를 변경하고 메커니즘이 반응하는 것을 지켜봄으로써 배울 때, 정적 그림이나 소규모 배수가 동등하게 보여줄 수 없는 방식으로 상호작용이 가치를 얻습니다. 브리핑에 상호작용 문장을 작성하십시오: "독자가 X를 드래그 / Y를 슬라이드 / Z에 호버하고 W를 봄". 예산: 장당 약 1개의 라이브 그림, 해당 장의 주요 메커니즘용; 나머지는 모두 정적입니다. 좋은 후보: 최적화 프로그램 경로(시작점 드래그, β 슬라이드), 어텐션 또는 합성곱(행이나 셀 호버), 안내 가중치 또는 온도 스위프, 선형 맵(기저 벡터 드래그), 샘플링 단계(재생). 나쁜 후보: 파이프라인, 아키텍처 다이어그램, 소규모 배수가 이미 추세를 보여주는 모든 것.

• 라이브 브리핑: "1차원 두 클래스 혼합; 독자가 안내 가중치 w를 0에서 6으로 슬라이드하고 안내된 밀도가 기울어진 대상을 초과하는 것을 봄; 재생 버튼이 ODE를 단계별로 적분; 숫자: 대상에 대한 KL, 실시간".

또한 전체 책에 대해 색상 역할(어떤 색상이 무엇을 의미하는지; book.json에 넣어 그림, 수식 산문 및 범례가 일치하도록), 해당 분야에서 의견이 갈리는 관례(시간 방향, 부호, 표기법 및 장마다 다른 의미를 갖는 기호(예: 모멘텀의 속도와 Adam의 두 번째 모멘트에 대한 (v))), 그리고 장 ID(w01…, v01…; 문자는 그림 레이블 접두사, W3.2, V5.1이 됩니다)를 한 번 결정하십시오.

3. 스캐폴드

python3 <skill>/scripts/init_book.py <book> --title "책 제목" --sub "출처 · 학기"

book.json(파트, 장 ID, 역할)과 chapters/00-front.html을 편집하십시오. 각 파일을 먼저 읽으십시오. 파일 도구는 읽지 않은 파일을 덮어쓰지 않기 때문입니다. 템플릿의 역할은 일반적인 딥러닝 역할(입력, 은닉, 잠재...): 해당 분야의 고유한 역할로 교체하십시오(최적화 프로그램의 경우: 반복, 기울기, 속도, 손실...). <book>/SPEC.md를 references/author-spec.md에서 작성하고 모든 «…» 블록을 채우십시오: 독자, 파트, 역할 표, 관례, 장 맵. 작성자는 SPEC.md와 자신의 브리핑만 보므로 SPEC.md는 단독으로 작동해야 합니다. 책을 직접 작성하는 경우에도 작성하십시오. 이후 장과 이후 세션을 위한 관례가 있는 곳입니다.

누군가를 시작하기 전에 bash <book>/tools/fig.sh를 통해 하나의 테스트용 그림을 렌더링하여 TeX 파이프라인이 작동하는지 확인하고, 계획에 라이브 그림이 있는 경우 하나의 라이브 그림도 테스트하십시오: <skills>/tikz-live/assets/examples/momentum/momentum.{tex,js}를 figs/_test/로 복사하고 bash <book>/tools/fig.sh figs/_test/momentum.tex를 실행한 다음 rm -rf <book>/figs/_test(중간 파일은 figs/_test/.dllive/에 있으므로 아무것도 남지 않음). 이렇게 하면 node와 PyMuPDF가 작동하고 tools/dllive.js가 제자리에 배치됩니다. 9명의 병렬 작성자가 발견한 파이프라인 오류는 9배의 비용이 듭니다.

4. 장 위임

전체 강의(10개 이상의 장)의 경우, 각각 24개의 관련 장(약 57개 그림)을 소유하는 일반 목적의 하위 에이전트를 병렬로 생성하십시오. 각 프롬프트는 다음과 같습니다: 먼저 <book>/SPEC.md를 읽고 따르십시오. 소유한 장 ID; 장별로 세션 메타데이터, 논문, 깊은 연결 고리 및 그림 브리핑; 렌더링, 확인, 수정 후 SPEC 섹션 5에 따라 보고. 관련 장은 공유 그림이 일관되도록 한 작성자 아래에 그룹화하십시오(예: 동적 OT와 OT 커플링).

사용량 제한은 실제입니다: 한 번에 9명의 작성자가 중간에 세션 제한을 소진할 수 있습니다. 에이전트가 속도 제한 오류로 중지되면 해당 파일은 유지됩니다. 제한이 재설정되면 새 에이전트를 시작하는 대신 SendMessage("중단된 지점에서 계속; 이미 만든 것을 확인")로 각각을 재개하십시오. 큰 책의 경우 두 번에 나누어 시작하는 것을 고려하십시오.

작은 책(하나의 주제, 3~5개 장)의 경우 하위 에이전트를 건너뛰고 직접 작성하되, 여전히 SPEC.md를 따르십시오.

5. 작성자가 그림을 그리는 동안: 앞부분과 지도

chapters/00-front.html(히어로, 읽는 방법, 규칙, <!--ROLES--> 범례, 선택적으로 출처를 반영하는 표(예: 장 링크가 있는 강의 일정))과 map/data.json을 작성하십시오. 스키마와 패밀리, 노드, 관계 및 투어를 선택하는 방법은 references/concept-map.md를 읽으십시오. 지도는 개요입니다: 각 아이디어가 무엇인지, 어디에 위치하는지, 어떻게 관련되는지, 어떤 장이 더 깊이 다루는지. 거기서 메커니즘을 설명하지 마십시오.

6. 보고서가 도착하면 검토

각 보고서는 그림의 한-아이디어 문장과 확인되지 않은 주장을 나열합니다. 가장 중요한 그림(주요 비교, 사용자가 이름으로 요청한 것)을 직접 열고 알고 있는 사실과 대조하십시오. 구체적인 수정 사항을 해당 작성자에게 보내십시오.

7. 조합, 확인, 읽기

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

그런 다음 references/qa-and-publish.md를 따르십시오: 연락처 시트 훑어보기, 브라우저 확인(수식 오류, 전화 너비 오버플로, 지도, 라이트 모드, 라이브 그림: 모두 마운트됨, 드래그 및 호버 작동, 테마 토글이 색상 변경), 그리고 게시 전에 모든 장의 텍스트를 읽으십시오. 브리핑에서 상속된 메타데이터 오류(세션 번호, 날짜)를 수정하십시오.

브라우저 확인을 건너뛰지 마십시오. 정적 확인은 페이지의 JavaScript를 실행할 수 없으며, 가장 중요한 실패는 조용히 발생합니다: 렌더링되지 않는 지도, 조판을 멈추는 수식. 브라우저를 열 수 없다면 인계 시 그렇게 말하고 브라우저 확인이 완료되지 않았음을 나열하십시오.

8. 게시

<book>/index.html을 Artifact로 게시하고 모든 그림 PNG를 지원 파일로 포함(check_book.py --files-json이 목록을 출력; 라이브 그림은 페이지에 인라인되므로 해당 PNG는 제외)하거나, Artifact 도구가 없는 경우 폴더를 전달하십시오. 사용자에게 각 파트에 무엇이 있는지, 무엇이 확인되지 않았는지, 어떤 그림이 계산된 결과가 아닌 일러스트레이션인지, 그리고 재구축(python3 tools/build.py) 또는 그림 재렌더링 방법을 알리십시오.

이후 요청

동일한 폴더를 편집하고 동일한 파일 경로를 다시 게시하여 링크가 동일하게 유지되도록 하십시오: 장 추가(book.json에 ID 추가), 지도 확장(map/data.json 편집), 또는 스타일 재지정(tools/shell.html 편집). references/qa-and-publish.md §3에 나열된 수정 사항을 셸이나 map.js를 건드릴 때 유지하십시오.

참조 파일

• references/author-spec.md — SPEC.md용 템플릿, 장 작성자 계약서(그림 규칙, HTML 조각 형식, 인용 규칙).
• references/concept-map.md — map/data.json 스키마 및 점들을 연결하는 지도를 작성하는 방법.
• references/qa-and-publish.md — 확인, 브라우저 스니펫, 템플릿에서 이미 수정된 알려진 함정, 게시.
• assets/template/ — init_book.py가 복사하는 책 스캐폴드.