TikZ 探検書 (TikZ Explorer Book)

TikZ 探検書 (TikZ Explorer Book) は何をしますか？

あなたは誰かが探検するための本を作っています：それは単一のウェブページであり、ホームは分野全体の概念マップで、各章は注意深く計算されたTikZ図で1つのアイデアを見える化します。読者はまず全体像を見て、点と点を結び、好きなところへ深く潜りたいと思っています。

可視化が最優先です。章はその図で成り立ちます。テキストは図へ導き、図から結論を引き出します。同じことを示せる図があるなら、テキストがその代わりになることは決してありません。時間をトレードオフするときは、図の品質を保ち、散文を削ってください。

このスキルは全体を orchestrate します；図の作成は、1つの視覚言語 (dlviz.sty、色＝役割) を共有する2つの兄弟スキルにあります。これらは一緒に出荷され、このスキルのフォルダの隣に置かれます；以下、<skills> は3つすべてを保持するフォルダ (このスキルの親フォルダ、インストール先) を意味します。

• 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"> 1つ
├── 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 はソースに従い、セッションまたはユニットごとに1つの章があります。各章はすべてを要約するのではなく、1つのアイデアに深く掘り下げます。
• パート II は読者の目標のためのツールキット、例：「ビデオ生成研究者が知っておくべきこと」：ソースが前提としている、または省略している分野横断的な基礎、実用的かつ最新で、実際の数値が含まれます。読者にソース以外の目標がない場合は、パート II をスキップします。
• ホームページは概念マップ：深みに入る前の全体像。

目的が本当に明確でない場合にのみユーザーに質問してください。そうでなければ、あなたの解釈を1行で述べて先に進んでください。

2. 図を中心に章を計画する

各章についてブリーフを書きます：深い糸 (1文)、2～3の図とそれぞれが何を見える化する必要があるか、どのアーキタイプか、何を計算するか。これが最も重要なステップです。メカニズムを指定したブリーフは素晴らしい図を生みます；トピックを指定したブリーフはボックス図を生みます。

• 弱い：「分類器なしガイダンスについての図」。
• 強い：「1次元2クラス混合；w = 0, 1, 2, 4 に対して正確な速度でガイド付き ODE を積分；結果の密度のスモールマルチプルを p(x|c) および傾斜密度と比較し、ガイダンスが傾斜をオーバーシュートすることを示す」。

良い図の主題：動作中のメカニズム (パス、フロー、更新)、ビフォー/アフター、同一入力に対する2つの方法の比較、形状とカウント (テンソル形状、トークン数、FLOPs)、結果がポイントである数値実験。それぞれは計算可能でなければなりません：著者はすべての数値を Python で生成します。

どの図をライブにするか決定します。 読者が何かを変更してメカニズムが反応するのを見ることで学習し、静的な絵やスモールマルチプルでは同じように示せない場合、図はインタラクションに値します。ブリーフにそのインタラクション文を書きます：「読者はXをドラッグ / Yをスライド / ZにホバーしてWを見る」。予算：章ごとに約1つのライブ図、その章の見出しメカニズムに対して。残りはすべて静的。良い候補：オプティマイザのパス (始点をドラッグ、βをスライド)、アテンションまたは畳み込み (行またはセルにホバー)、ガイダンス重みまたは温度スイープ、線形写像 (基底ベクトルをドラッグ)、サンプリングステップ (再生)。悪い候補：パイプライン、アーキテクチャ図、スモールマルチプルがすでに傾向を示すもの。

• ライブブリーフ：「1次元2クラス混合；読者がガイダンス重み 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 "Book Title" --sub "Source · Term"

book.json (パート、チャプターID、ロール) と chapters/00-front.html を編集します。最初にそれぞれを読んでください。ファイルツールは、読んでいないファイルの上書きを拒否するからです。テンプレートのロールは汎用的な深層学習用のもの (入力、隠れ、潜在...) です：分野独自のものに置き換えてください (オプティマイザの場合：反復、勾配、速度、損失...)。<book>/SPEC.md を references/author-spec.md から書き、すべての «…» ブロックを埋めてください：読者、パート、ロール表、慣例、チャプターマップ。著者は SPEC.md と自分のブリーフだけを見るので、SPEC.md は単独で成立しなければなりません。あなた自身が本の著者である場合でも書いてください：それは後の章や後のセッションのために慣例が生きる場所です。

誰かを始動させる前に、bash <book>/tools/fig.sh を使って使い捨ての図を1つレンダリングし、TeX パイプラインが動作することを確認し、計画にライブ図がある場合は、ライブ図も1つ確認します：<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章以上) の場合、汎用のサブエージェントを並行して起動し、それぞれが 2～4 の関連する章 (約 5～7 の図) を担当します。各プロンプトは言います：最初に <book>/SPEC.md を読み、それに従うこと；担当するチャプターID；チャプターごとに、セッションメタデータ、論文、深い糸、図のブリーフ；レンダリング、確認、修正、その後 SPEC セクション5に従って報告すること。共有図が一貫性を保つように、関連する章を1人の著者の下にグループ化します (例：動的 OT と OT カップリング)。

使用量制限は現実的です：一度に9人の著者がセッション制限を使い切る可能性があります。エージェントがレート制限エラーで停止した場合、そのファイルは保持されます。制限がリセットされたら、新しいエージェントを開始する代わりに、SendMessage (「中断したところから続けてください。すでに作成したものを確認してください」) でそれぞれを再開します。大きな本の場合は、2つの波で立ち上げることを検討してください。

小さな本 (1つのトピック、3～5章) の場合は、サブエージェントをスキップして自分で書き、それでも SPEC.md に従ってください。

5. 著者が描いている間：前付とマップ

chapters/00-front.html (ヒーロー、読み方、慣例、<!--ROLES--> 凡例、オプションでソースを反映した表、例：チャプターリンク付きのコースカレンダー) と map/data.json を書きます。スキーマと、ファミリー、ノード、関係、ツアーの選び方については references/concept-map.md を読んでください。マップは概要です：各アイデアが何であるか、どこに位置するか、どのように関連するか、そしてどの章がより深く掘り下げるか。そこでメカニズムを説明しないでください。

6. レポートが届いたらレビューする

各レポートは、図の1アイデア文と未検証の主張をリストします。最も重要な図 (見出しの比較、ユーザーが名前を指定して要求したもの) を自分で開き、あなたが知っている事実と照らし合わせて確認します。具体的な修正を、それを描いた著者に送り返します。

7. 組み立て、確認、読む

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

次に references/qa-and-publish.md に従います：コンタクトシートの一瞥、ブラウザチェック (数式エラー、電話幅でのオーバーフロー、マップ、ライトモード、ライブ図：すべてマウントされているか、ドラッグとホバーが機能するか、テーマトグルが再配色するか)、そして公開前にすべての章のテキストを読みます。あなたのブリーフから著者が引き継いだメタデータのミス (セッション番号、日付) を修正します。

ブラウザチェックをスキップしないでください。静的チェックはページの JavaScript を実行できず、最も重要な失敗は沈黙します：レンダリングされないマップ、タイプセットを停止する数式。本当にブラウザを開けない場合は、引き継ぎでその旨を述べ、ブラウザチェックが未完了であることをリストしてください。

8. 公開する

<book>/index.html をすべての図の PNG をサポートファイルとして添えてアーティファクトとして公開するか (check_book.py --files-json がリストを出力します；ライブ図はページにインライン化されるため、その PNG は含まれません)、アーティファクトツールがない場合はフォルダを引き渡します。各部分に何が含まれているか、何が未検証か、どの図が計算結果ではなくイラストか、そして再構築方法 (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 がコピーする本のスケルトン。