lukezielke/lecture-to-anki

講義 → Anki (v2)

エビデンスに基づいた主題別チューターとして機能し、スライド箇条書き変換ツールではありません。ローカルの講義資料、宿題、解答、過去問題を、正確で試験に役立ち、アトミックで自己完結したAnkiノートに変換します。ソース参照を保持し、アイデンティティを維持することで、再インポートしたパッケージが既存のノートを更新できるようにします。未確認の図や未解決の試験問題を推測しないでください。

入力、デフォルト、制約

• コースルート: ユーザーのフォルダまたは作業ディレクトリ。再帰的に読み取りますが、anki-output/、.git、.agents、build などは除外します。
• 出力: <コース>/anki-output。正規の編集可能データは cards.json です。
• デッキ: 特に指定がない限りコースのフォルダ名を使用します。更新間で名前を変更しないでください。デッキ/モデルのアイデンティティが変わるためです。
• モード: exam-focused（デフォルト）、comprehensive、topic-specific、update。
• 配信形式: デフォルトで deck.apkg、オプションで basic.txt / cloze.txt。.apkg には genanki が必要です。必要な場合のみユーザーの許可を得てインストールします。利用できない場合は、--format text でテキストをエクスポートし、制限事項を説明します。
• コースツリー/指定された出力ディレクトリ内でのみ読み書きします。講義資料を変更または削除しないでください。ユーザーからの要求なしに、サードパーティへのアップロードやWeb検索を行わないでください。
• 更新時も同じデッキ名、ノート id 値、カードタイプを維持します。カードのノートタイプを変更すると、そのアイデンティティが壊れ、Anki内に別のノートが作成される可能性があります。

ワークフロー

1) 抽出前に初回実行か更新かを判断

<output>/cards.json と <output>/source_manifest.json が存在する場合、最初に以下を実行します。

python3 <skill-dir>/scripts/plan_update.py "/path/to/course"

anki-output/update_plan.json を読み取ります。新しく追加されたソースファイル、変更されたソースファイル、削除されたソースファイル（SHA-256ハッシュ）と、変更/削除されたファイルに依存する既存のノートが報告されます。このステップは新しいエクスポートの前に行う必要があります。エクスポートが成功すると、更新されたマニフェストがコミットされるためです。ベースラインがない場合は、最初の完全なデッキを生成します。マテリアルに変更がない場合の更新では、通常、新しいカードは必要ありません。それでも、明示的に要求された改善は許可します。

明示的なノートIDがない古いv1 cards.json：質問を編集する前に、一度以下を実行します。

python3 <skill-dir>/scripts/migrate_ids.py "/path/to/course/anki-output/cards.json"

これにより.bakバックアップが作成され、元の質問を使用して欠落しているIDが補完されます。これらのIDは、対応する質問の文言や参照スライドが変更されても、永久に変更しないでください。

2) ソースの読み取りと棚卸し

python3 <skill-dir>/scripts/extract_sources.py "/path/to/course" \
  --output "/path/to/course/anki-output/sources.jsonl"

sources_report.json を参照します。これには、ファイルごとのハッシュ、タイプ、カテゴリ分類、アクセス不能なファイル、空のPDFページが含まれます。カテゴリ: 講義、宿題、宿題の解答、過去試験、試験の解答、ノート。PDFテキストには pdftotext または pymupdf が必要です。PPTX/DOCX/Markdown/LaTeX/HTML/text がサポートされています。画像が多いファイルやスキャンされたファイルは目視検査が必要です。テキスト抽出は、すべての内容が理解されたことを証明するものではありません。必要に応じてローカルのPDF/PPTXレンダラーを使用し、でっち上げたOCR/図の解釈は使用しないでください。省略したコンテンツは coverage.md に記録します。

初回実行時は関連するすべてのソースドキュメントを読み取ります。インクリメンタル実行では、主に新規/変更されたソースとそれに関連する既存のマテリアルを調査して、競合や重複する事実を検出します。両方について、コース全体のシラバス/カバレッジマップを保持します。ファイル名や孤立したスニペットのみに基づいてカードを発行しないでください。

3) 試験対策の学習マップを作成

1. スライドは範囲です: キーワード、定理、形式的仮定、表記、アルゴリズム、例。
2. 宿題は転移を訓練します: 演習戦略、証明パターン、繰り返し発生する誤解。
3. 解答は回答を検証します。検証済みの解答がない試験/宿題の問題に対して、答えをでっち上げないでください。
4. 過去問題は頻度と期待されるタスク形式を示しますが、完全なシラバスではありません。歴史的な再発を証拠として扱い、決して保証された試験予測として扱わないでください。
5. トピックを、中心性、コースの学習目標、独立したマテリアル間での再発、試験/宿題での強調によってランク付けします。孤立した古い答えを暗記するよりも、再利用可能な知識を優先します。

カードを書き始める前に、以下を両方とも読んでください。

• references/card-quality.md
• references/math-cs-cards.md

トピック別カバレッジ計画を使用します: 定義と条件、理解/理由、適用/認識、エラーケース。特に数学/CSでは、定理/仮定/証明戦略/証明ステップ/反例/不変条件/複雑性/アルゴリズムトレース/帰着/マイクロアプリケーションを意図的に検討します。すべてのトピックにすべてのタイプが必要なわけではありません。正当化され、簡潔で、テスト可能なカードのみを選択します。量化子と前提条件を保持します。使用する複雑性尺度、入力仮定、グラフの慣習を明記します。Anki MathJax \(...\) または \[...\] を正しいJSONエスケープで使用します。

4) 必要な場合の画像と図表

テキストのみのプロンプトは、グラフ、オートマトン、ツリー、アーキテクチャ図、アルゴリズムトレース、幾何学的構成、表記法の多い数式には不十分な場合があります。視覚情報が不可欠な場合は、学習者に想像させるのではなく、図をカードに含めます。

まず図を目視で検査して正確な領域を特定します。スライド全体を自動的にコピーしたり、無差別に図を含めたりしないでください。

トリミングされたPDF図の場合（座標はPDFポイント）:

python3 <skill-dir>/scripts/prepare_media.py pdf "/path/to/course/slides/L3.pdf" \
  --page 12 --crop 100,90,490,330 --output "/path/to/course/anki-output/media"

PPTXスライド全体（LibreOffice + PyMuPDFが必要）または埋め込まれたPPTX画像の場合:

python3 <skill-dir>/scripts/prepare_media.py pptx-slide "/path/to/course/slides/L3.pptx" \
  --slide 7 --output "/path/to/course/anki-output/media"
python3 <skill-dir>/scripts/prepare_media.py pptx-image "/path/to/course/slides/L3.pptx" \
  --slide 7 --image 1 --output "/path/to/course/anki-output/media"

既存の.png、.jpgなどには、prepare_media.py image ... --output ... を使用します。

正確なベース名をカードのHTMLに挿入します: <img src="lta_example_abcdef1234.png">。また、そのノートに "media": ["media/lta_example_abcdef1234.png"] を追加します。HTMLファイル名はベース名のみ（media/ プレフィックスなし）です。アセットはローカルで、選択した出力フォルダ配下にある必要があります。これにより、.apkg にそれらが含まれることが保証されます。references/cards-schema.md を参照してください。

コピー可能でスクリーンリーダー対応の数学テキストが同じ内容を伝えられる場合は、ユーザー固有のコース回答を画像として保存しないでください。重要な視覚的関係はテキストで説明またはキャプションを付けてください。図は概念的正しさを検証する代わりにはなりません。

5) cards.json の生成/維持

references/cards-schema.md のスキーマを使用します。すべてのノートは一意で安定した id（例: graphs.dijkstra.nonnegative）を持つ必要があります。更新時に、編集された質問テキストから新しいIDを決して導出しないでください。初回生成時に安定したIDを1つ作成し、cards.json に保持します。IDはデッキ内で一意であり、カード type は安定している必要があります。

以下を含めます:

• type: basic または cloze（Ankiノートタイプ。ほとんどの数学/CSタスクはBasicが適しています）。
• kind: 例: theorem、proof_idea、counterexample、algorithm_trace、complexity、application（分類タグであり、Ankiテンプレートではありません）。
• front/back または text/extra。
• source_file と source_location、さらに複数のファイル間で内容が検証された場合は supporting_sources。
• tags に topic::...、priority::...、from::... を含めます。
• 使用する場合は media。

Basicの質問は、約5〜30秒で独立して回答可能でなければならず、1つの事実や考えをターゲットとし、前提と結論を区別する必要があります。長いアルゴリズムのウォークスルー/証明は、短くテスト可能なステップに分割してください。穴埋め問題は意味のある文脈コンテンツをテストする必要があります。段落全体を穴埋めにしないでください。

6) インクリメンタル更新ルール

後続の実行では:

1. update_plan.json、古い cards.json、および新しい/関連するソーステキストを読み取ります。
2. 影響を受けるトピックとノートを再検討し、ソースの事実/表記が変更された場合は修正し、ノート id は保持します。変更されていないノートはそのまま維持します。
3. 新しいノートを追加するのは、それらが新しい想起/スキルに貢献する場合のみで、新しいID を使用します。追加する前に、デッキ全体をチェックして意味的な重複がないか確認します。
4. 削除されたソース: 最初に別の引用を確認します。サポートされていないノートはレビュー用にフラグを立てます。ファイル削除時にカードやソースを自動的に消去しないでください。
5. type を安定に保ちます。大幅な Basic から Cloze への置き換えには、異なる ID を作成し、レガシーノートを手動で Anki から削除するよう明示的にフラグを立てます（インポートでは欠落ノートは削除されません）。
6. 検証エラーが発生した場合、cards.json を上書きせず、大きな編集の前に以前のバージョンを cards.json.bak に保持します。
7. 影響を受けるすべてのノートがレビューされた後にのみエクスポートし、新しい source_manifest.json をコミットします。ソーススナップショットを更新することが、その内容が理解されたことを意味するものではありません。

パッケージのデッキ/モデルIDとノートGUIDは、同じデッキとカードIDに対して安定しています。Ankiへの再インポート時には、既存のノートを更新するオプションを選択します。Ankiのインポート設定と更新時刻は、変更が実際に適用されるかどうかに影響を与える可能性があります。同じノートが更新される場合、既存のスケジューリングは一般的に維持されますが、Ankiのインポートプレビューを確認してください。再インポートでは、以前にインポートされた古いノートは削除されません。ユーザーが明示的に要求しない限り、Ankiのコレクションファイルを手動で編集したり、AnkiConnectを使用したりしないでください。

7) バリデーションとエクスポート

python3 <skill-dir>/scripts/export_anki.py "/path/to/course/anki-output/cards.json" \
  --output "/path/to/course/anki-output" \
  --course "/path/to/course" --format both

--format both（デフォルト）は、deck.apkg、basic.txt、cloze.txt（該当する場合）、export_report.json、source_manifest.json を生成します。.apkg または .txt ファイルのいずれか一方を特定のAnkiコレクションにインポートします。両方はインポートしないでください。異なるノートタイプは重複を引き起こすためです。--format text は genanki なしで動作しますが、そのインポーターは最初のフィールドマッチングを使用し、IDによって質問を安全に修正することはできません。継続的なインクリメンタル更新には .apkg を使用してください。--format apkg はテキストエクスポートをスキップします。

利用可能な場合は.apkgの依存関係をインストールします:

python3 -m pip install genanki

export_report.json でカード数、明示的なIDの欠落、スキップされた完全重複、メディア数を確認します。検証エラーは無視せずに解決してください。メディアソースファイル名は一意で、適切に参照されている必要があります。.apkg はAnkiの ファイル → インポート からインポートします。

8) カバレッジとQAの要約

<output>/coverage.md に以下を記述します:

• 読み取った資料とスキップしたファイル。スキャン/図のギャップを明示的にリストアップします。
• カバーしたトピックと、kind および priority 別のノート数。定義と適用のバランス。
• 繰り返し発生する試験/宿題パターン。不確実性と参照を含めます。
• 競合または未解決の証明/解答の前提。
• 更新時: 新規/変更/削除されたソース、保持/修正/追加されたノート、レビューが必要な孤立ノート。不当なサイレント削除がないことを確認します。
• エクスポートされたファイル名とインポート手順。.apkg インポートは欠落したノートを削除せず、Ankiの更新はユーザーのインポートオプションに依存する可能性があることに注意します。

カバレッジが不完全な場合はそのように明記します。検査できなかったソースについて、完全なカード生成を主張しないでください。