scholar-slides

scholar-slides

研究論文（またはトピック）から、原典への忠実さを最優先した学術スライドデッキを作成します。学術用途では、通常のデッキ作成ツールとは優先順位が逆になります。原典への忠実さ > 見栄え、エビデンス > 説得力、編集可能性 > 派手さです。数式、表、数値、図、引用は、原典をたどれるテキスト／ベクター形式のまま維持されます。画像モデルでラスタライズしたり、捏造したりすることはありません。

設計の根拠とその基盤となる調査は docs/ に、実装計画は IMPLEMENTATION_PLAN.md にあります。

固定スタック（docs/03-design-proposal.md §0 を参照）

• レンダリングバックエンド： reveal.js + KaTeX → ベクター PDF（Playwright）+ 編集可能な PPTX（同等性テスト済み）。Beamer は後日対応します。
• デフォルトのデッキタイプ： 研究室ミーティング／ジャーナルクラブ（组会）— 読みやすさを重視した高密度の構成です。
• 引用： Zotero を優先（mcp__zotero__*）、代替として Crossref/arXiv/DOI を使用します。
• 言語： バイリンガル、デフォルトは英語です。

妥協しない整合性ゲート（常時有効 — references/integrity.md を参照）

すべての段階で適用し、チェックポイント 3 で強制します。

• 数値、引用、図を捏造しません。 すべて原典のダイジェストまでたどれるようにします。
• 数式／表／引用はベクター／テキスト形式のまま維持し、画像モデルのピクセルには変換しません。
• 実際の図を再利用し（bbox で切り抜き、Figure N [cite] を付記）、概念図を描き直す場合は「原典の図ではなく、描き直したもの」と明記します。
• 不明点はフラグを立て、創作しません。 解決していない図／数値／引用は、ユーザーに表示される [MISSING: …]／[UNVERIFIED: …] のプレースホルダーとして示し、黙って補完することはありません。
• 出典情報は必須です。 再利用するすべての素材に出典を付け、すべての主張を追跡可能にします。

パイプライン（7 段階、3 回の人間によるチェックポイント）

INPUT → 1.INGEST/DIGEST → [CKPT-1] → 2.DECK-TYPE → 3.OUTLINE → [CKPT-2]
      → 4.PER-SLIDE SPEC → 5.RENDER → 6.SELF-REVIEW(QA) → [CKPT-3] → 7.EXPORT

1. 取り込み → 型付きダイジェスト — references/ingestion.md。
   scripts/prepare_source.py <pdf|arXiv id|arXiv URL> を実行して、ダイジェスト入力バンドル （テキスト、bbox 付きの図表一覧、切り抜き図）を作成し、それを基に型付き 論文ダイジェストをまとめます（バンドルに基づき、決して捏造しません）。 → [CKPT-1] ユーザーとダイジェストの内容（貢献、主な結果、 図からスライドへの対応、FLAGGED のアセットがあればその内容）を確認します。
2. デッキの種類とパラメーター — references/deck-types.md。デッキの種類（デフォルトは组会）、 対象者、所要時間 → スライド数、密度の設定、必要なアーキタイプを選びます。
3. ナラティブのアウトライン — references/narrative.md。論文を発表の流れに沿って並べ替え、 各スライドにアクションタイトルを付け、ストーリー展開の緊張感を確認します。 → [CKPT-2] ストーリー展開の承認を得ます。
4. スライドごとの仕様 — references/slide-spec.md。各スライドについて、レイアウト、 コンテンツ、数式、図、引用、発表者ノートを含む、自己完結したオンディスク仕様を作成します。
5. レンダリング — references/math.md、references/figures-tables.md、references/citations.md、 references/charts.md、references/design-system.md、references/export.md。reveal.js + KaTeX を使用します。 実際の表、bbox で切り抜いた実際の図（周辺要素を除去し、複数パネルの図は 1 スライドにつき 1 パネル）、 データに基づいて再描画したチャート、Zotero/BibTeX の引用を使います。meta.theme でビジュアルテーマを選びます（デフォルトは journal-club、または conference）。
6. セルフレビュー QA — references/qa-self-review.md + references/integrity.md の後、 references/aesthetics-review.md の美的レビューの反復を行います。整合性スキャン + 静的バリデーター + レンダリングのスクリーンショット + ナラティブと所要時間の確認を実施します。レンダリング工程では、 ジオメトリも決定論的に測定します（キャンバスの空白、12px の可読性下限を下回る位置に投影された図中文字）。 その後、6 項目の評価基準（敵対的なペルソナ）に基づいてレンダリング済みの ピクセル を採点し、スコアを <deck>/aesthetics_report.json に書き込みます（スキーマは aesthetics-review.md を参照）。いずれかの項目が 2 以下、または合計が 18 未満のスライドは、レポートの rework リストが空になるまで修正します。QA ゲートは レポートの欠落（P3）と未対応の修正項目（P2）にフラグを立てます。また、箇条書きの比率やレイアウトの単調さについても注意を促します。 → [CKPT-3] 真偽の最終確認：すべての [MISSING]／[UNVERIFIED] と生成されたアセットを確認します。
7. エクスポート — references/export.md。ベクター PDF（投影用）+ 発表者ノート + 編集可能な PPTX を出力し、 scripts/verify_pptx_parity.py で、PPTX が仕様をネイティブに保持していることを検証します （最小限の手動編集で済むという約束を守るためです）。node scripts/run_benchmark.mjs でコーパス全体を回帰テストします。

現在の段階に対応するリファレンスファイルのみを読みます（段階的開示 — references/ を glob で検索してはいけません）。 各段階では、論文から情報を再抽出するのではなく、前段階で確認済みの成果物、すなわちダイジェスト （ステージ 1、CKPT-1 でユーザーが確認済み）と、その後の deck.json を読み込みます。

スクリプト（scripts/）

取り込み — パイプラインのステージ 1（Python、./.venv/bin/python 経由。依存関係は requirements.txt）：

• prepare_source.py — ステージ 1 のエントリーポイント：PDF/arXiv → ダイジェスト入力バンドル。
• ingest_pdf.py — PyMuPDF によるテキストとレイアウトの抽出、arXiv-id の検出。
• detect_figures.py — 図表キャプションの一覧化とバウンディングボックスによる位置特定。
• crop_figure.py — 隣の列が入らない、単一の図のクリーンなバウンディングボックス切り抜き。

デッキのビルドとレンダリング — パイプラインのステージ 5（Node、node 経由。依存関係は package.json。npm install と npx playwright install chromium を実行）：

• build_deck.mjs — レンダリングのエントリーポイント：deck.json → 自己完結型の reveal.js デッキ。
• render_deck.mjs — デッキ → 1 スライド 1 ページのベクター PDF（QA 用のスライドごとの PNG も生成）。
• lib/ — layouts（登録済みレイアウトのロック）、math（KaTeX）、table、figure、escape、qa。

引用と QA — パイプラインのステージ 5～6（引用 = Python、QA = Node）：

• fetch_bib.py — 引用解決ツール（arXiv/DOI/Crossref）。順序に依存するタイトル検証機能付き。
• qa_report.mjs — CKPT-3 ゲート：整合性スキャン + validate_deck.mjs + verify_slides.mjs + タイミング。

スピーカーノート（Node）：

• speaker_notes.mjs — deck.json → 配布資料 notes.md + バイリンガルの発表時間見積もり。
• lib/notes.mjs — タイミングと配布資料の純粋ロジック。デザインシステムは assets/templates/themes/ にあります。

エクスポートとチャート — パイプラインのステージ 7（エクスポート = Node、チャート = Python）：

• export_pptx.mjs — deck.json → 編集可能な PPTX（ネイティブのテキスト／表／ノート。図と数式は画像）。
• make_chart.py — チャート仕様 → データにバインドされた岡部–伊藤プロット（値をそのままプロット）。

テスト：./.venv/bin/python -m pytest（Python）および node --test tests/*.test.mjs（Node — テストファイルを個別に指定すると、新しいテストファイルが黙って実行対象から漏れるため、glob を使用します）。

学び：パイプラインの動作を変更する前にお読みください

learnings/ には、実測値（図のサイズに関する縦方向の予算、見た目と制作ルールの比較）を記載したインシデント後のメモがあります。レンダリング、サイズ設定、QA の動作を変更する前に確認し、再作業が必要になるような予想外の問題があれば、日付入りのメモを追記してください。

ビルド状況

パイプライン全体は実装済みで、実際の論文を使った検証も完了しています。未実装：Beamer エクスポート、スキャン PDF 用 OCR、ドラフトデッキの取り込み。学会発表／答弁デッキの種類は references/deck-types.md に作成ガイドとして記載されています（専用コードはありません）。デッキが「完成」となるのは、CKPT-3 の人による真偽確認が完了した後だけです。このゲートは欠陥を明らかにしますが、内容の正しさを保証することはできません。