obsidian-course-vault

Obsidian Course Vault

ユーザーが Obsidian に長期的なコースノートを作成したい場合は、このスキルを使用してください。

コマンドは、このスキルのルートディレクトリから実行されるものとします。それ以外の場合は、scripts/ に対して絶対パスを使用してください。

基本的な境界

• Vault の構造、リプレイの同期、リプレイの診断、キャッシュの更新、トラッカーの保守、ファイルへの書き込みはスクリプトに任せてください。
• コースとの整合性、概念の確認、用語の修正、グラフの解釈、最終ノートの文章作成はエージェントが担当してください。
• 決定論的に生成されたシードノートを、完成したコースノートとして扱わないでください。

主なコマンド

Vault を初期化します。

python scripts\init_obsidian_course_vault.py --obsidian-dir "<obsidian-install-dir>" --vault-dir "<vault-dir>"

コースを追加します。

python scripts\add_course.py --vault-dir "<vault-dir>" --course-name "<course-name>"

コースを保守するか、BUAA のリプレイ状態を同期します。

python scripts\maintain_obsidian_course.py --vault-dir "<vault-dir>" --course-name "<course-name>" --course-page-url "<coursedetail-url>" --replay-output-dir "<replay-output-dir>"

コースの識別と配置

BUAA のコースを Vault に追加または保守する前に、次の点を確認してください。

• 可能な限り、抽出したコース名から course-name を特定します。正規化したタイトルがコースの識別子になります。
• 特定したタイトルがすでに Vault に存在する場合は、そのコースフォルダーを再利用します。新しい coursedetail URL の course_id、講師、スケジュール、教室、sub_id の範囲が異なっていても、タイトルが同じなら同じコースです。
• タイトルが不明または信頼できない場合は、course_id を course-136278 のような暫定的なコース名としてのみ使用するか、正式なノートを書く前にユーザーに意図するタイトルを尋ねます。既存の Vault フォルダー、教師名、授業時間、古い抽出ディレクトリからコースを推測しないでください。
• 「以前の Vault を使う」とは、Vault のルートを選択することを意味し、その中の既存のコースフォルダーを自動的に選択することではありません。
• 複数の教室ソースから同じタイトルのコースにデータを取り込めるよう、各ソースの course_id と URL を同期メタデータに保持し、出所情報が上書きされないようにします。

リプレイノートを作成または再作成します。

python scripts\maintain_obsidian_course.py --vault-dir "<vault-dir>" --course-name "<course-name>" --draft-replay-sub-ids "<sub-id>" --replay-note-mode "final-explained"

必須のリプレイ診断

リプレイノートを作成する前に、スクリプトで replay_diagnosis を一度計算し、レッスンを次のいずれか1つだけに振り分ける必要があります。

• waiting_transcript
• partial_transcript
• transcript_only

以降のノート生成では、ルートの判断を個別に再計算せず、この診断を使用してください。

推奨するリプレイモード

通常、ユーザー向けに使用するモードは次のとおりです。

• final-lite
• final-explained

従来の final は、最終的な文章を直接書き込む許可ではなく、意味パケットの準備経路として扱います。draft はプレースホルダーまたはバックログノートにのみ使用してください。

意味モードでは、スクリプトが書き込めるのは次のファイルだけです。

• semantic_rebuild/semantic_rebuild_input.json
• semantic_rebuild/semantic_rebuild_prompt.md

デフォルトでは、Vault にシードレッスンノートを書き込まないでください。エージェントはそのパケットを読み、意味再構築が完了した後にのみ、ユーザーに表示される最初のレッスンノートを作成する必要があります。

再構築したノートを正式なレッスンページとして数える前に、次を実行します。

python scripts\validate_final_note.py "<lesson-note.md>"

バリデーターに失敗した場合は、ノートを needs_review としてマークするか、品質上の理由で却下します。コーストラッカー、概要の完了数、グラフの成長には含めないでください。

次に、レビュアーパケットを作成します。

python scripts\review_final_note.py --note "<lesson-note.md>" --semantic-input "<semantic_rebuild_input.json>" --output-dir "<review-dir>"

レビュアーパケットのディレクトリは、Obsidian Vault の外部に置く必要があります。--note が Vault 内にあり、--output-dir が省略されている場合、review_final_note.py は $HOME/.codex/course-vault-work/final_note_review/... に書き込みます。独立したレビュアーエージェントで final_note_review_prompt.md を使用するのは、現在のシステム／開発者の指示でエージェントの起動が許可されている場合に限ります。サブエージェントを利用できない場合、または許可されていない場合は、同じプロンプトを使って自分で別途レビューを行い、その結果を final_note_review_result.json に書き込みます。レビュー中はノートを編集しないでください。

効率的な一括処理ワークフロー

ユーザーがコースの保留中の BUAA リプレイをすべて整理するよう明示的に依頼した場合：

1. 既存のリプレイ抽出ディレクトリとセマンティックパケットがある場合は、それらを再利用します。
2. 不足しているセマンティックパケットを先に作成します。最新の transcript.txt と semantic_rebuild_input.json がすでにあるレッスンについては、ブラウザー抽出を再実行しないでください。
3. 作成前に候補を絞り込みます。最終化済みのレッスンと未来のレッスンはスキップし、トランスクリプトが不足している、空である、またはほぼ空である場合は、待機中／バックログに残します。
4. 各レッスンを作成する前に、トランスクリプトで安定して確認できる教育上の要素と既存のコースグラフに基づいて、採用する正式な概念のセットを決定します。既存の概念ページはすぐに再利用できます。新しい概念を本当に追加する場合は、グラフへの追加が承認され、概念ページ／ハブの配置が計画されてから、Wiki リンクまたは concepts フロントマター項目として使用できます。
5. 対象となる各レッスンについて、トランスクリプト全体を読み、採用済みの概念のみを使用して正式なノートを作成し、検証を実行し、レビューパケットを作成して、現在のノートハッシュに対する合格レビューを記録します。
6. 採用した新しい概念は、同じレッスン／一括作成の作業中に、ノートを最終化済みと見なす前に実体化します。後から追加する予定の概念リンクを含むレッスンを、最終化済みにしないでください。
7. 一括処理の後に maintain_obsidian_course.py を一度実行して、概要、トラッカー、バックログ、同期ノートを更新します。チェックポイントが必要な場合、または不足しているディレクトリ／パケットの作成が必要な場合に限り、それより前に実行します。
8. 一括処理中に、トランスクリプトだけに基づく弱いヒントから概念ページを再生成しないでください。グラフの拡張は、トランスクリプトで安定して確認できる概念と通常のメンテナンス処理に委ねます。

これは一括処理を効率化するためのものであり、セマンティックゲートを緩和するものではありません。

必須のセマンティックワークフロー

セマンティックモードでは：

1. リプレイの成果物と最近のコースコンテキストからセマンティックパケットを作成します。
2. ノートを承認する前に、コースとの整合性を確認します。
3. 文章を作成する前に、採用する概念のセットを決定します。既存の概念ページ、採用する新しい概念、却下する／弱いヒントを分けます。
4. 採用した新しい概念ページを実体化し、Wiki リンクまたはレッスンのフロントマター概念として使用する前に、既存または新規のハブに接続します。
5. 採用した概念のみを使って、ノートをセマンティックに書き直します。
6. 書き直した Markdown に対して scripts\validate_final_note.py を実行します。
7. scripts\review_final_note.py を使って、Vault 外の作業ディレクトリにレビューパケットを生成します。
8. 現在のノートハッシュに対して、独立したレビューパスを実行します。
9. セマンティック再構築が完了し、概念の採用／実体化に一貫性があり、ハードゲートに合格し、レビュー結果が pass になった後にのみ、レッスンを完了としてマークします。
10. トランスクリプトの網羅性と、トランスクリプトに基づく要約の網羅性の両方に合格した場合にのみ、正式なレッスンページを許可します。

セマンティック再構築がまだ保留中の場合、そのレッスンをコーストラッカーで完了として数えないでください。

正式な Obsidian リプレイノートのフロントマターには、少なくとも以下を含める必要があります。

• type: lesson
• course
• title
• date
• replay_sub_id
• source: buaa-replay-semantic-rebuild
• replay_diagnosis
• has_semantic_rebuild_packet: true
• semantic_rebuild_completed: true
• semantic_rebuild_status: completed
• concepts

これらのフィールドがない場合、メンテナンス処理によって、レッスンがセマンティック再構築の保留状態に維持されたり、已整理课次.md から除外されたりすることがあります。

コース運営事項

コース運営事項は付随的な文章ではなく、独立した重要な成果物として扱ってください。

書き起こしに根拠のある運営事項が含まれている場合は、該当するカテゴリを使って、講義ノートの ## 课程事务 に記載してください。

• ### 作业
• ### 考试
• ### 课程安排
• ### 通知

既存のノートでは ## 课堂事务 が使われている場合がありますが、メンテナンスでは同じ集約元として扱います。新たにノートを書く場合は、構成を明確にするため、## 课程事务 を優先してください。

書き起こしで裏付けられる運営事項だけを、確実な箇条書きとして記載してください。期限、配点、提出形式、試験範囲、方針の詳細に不確かな点がある場合は、確定した運営事項として扱わず、待核对 の下に記載してください。

メンテナンス中、スクリプトは以下を更新する場合があります。

• 完了した講義ノートから、コース内の .course-internal/affairs-candidates.md を更新する
• コースレベルの 事务.md が未レビューの自動生成プレースホルダーのままである場合に限り、これを更新する
• エージェントによる運営事項のレビューを経て候補を整理した後に限り、Vault レベルの 03-Admin/作业总表.md と 03-Admin/考试与通知.md を更新する

コースレベルの運営事項はレビュー済みの要約であり、キーワードを羅列するものではありません。学生が何をすべきか、確認すべきか、提出すべきか、読むべきか、出席すべきか、または評価で何を予期すべきかを変える項目だけを残してください。繰り返し出てくる記述や曖昧な言及は、日付ごとに短い項目一つにまとめてください。通常の授業内容、一般的な励まし、具体的な提出物を伴わない学習上の助言、概念の復習の提案、コース全般についての説明は除外してください。講義ノート内では、ローカルな文脈を示すために 课程安排 を残しても構いませんが、通知 に該当する具体的な日程、場所、セッションの変更がない限り、コースレベルの 事务.md には集約しないでください。

キーワード抽出によって最終的な運営事項を直接書き込ませないでください。次の手順を使用してください。まず .course-internal/affairs-candidates.md を生成し、メインエージェントまたは許可された独立レビュアーによる運営事項レビューを行い、その後、レビュー済みの簡潔な項目を 事务.md と Admin の表に記載してください。人間によるレビューを必須にしないでください。また、通常のメンテナンス中にエージェントがレビュー済みの 事务.md を上書きしないでください。

ユーザー向けのノートに運営事項の候補を公開しないでください。.course-internal/affairs-candidates.md を 事务.md、00-课程总览.md、トラッカー、Admin ページからリンクしないでください。

エージェントによる運営事項レビューでは、以下を明示的に除外または統合してください。

• 通常の授業内容や概念の復習の提案
• 一般的な励まし、学習方法、動機づけに関する発言
• 同じ課題、試験、通知に関する重複した言及
• 具体的な提出物を伴わない、「課題に役立つかもしれない」といった曖昧な記述
• 分数、分类、モデルのスコアなどの単語だけに反応した、試験を示すキーワードの誤検出

待機中の書き起こしノート、部分的な書き起こしノート、品質審査で却下されたノート、または意味に基づく再構築が未完了のノートから運営事項を集約しないでください。「当前未从转写中识别出稳定...」のようなプレースホルダー文は運営事項ではないため、事务.md や Admin の表に記載しないでください。

最終ノートの品質ゲート

ノートが装飾された書き起こしの断片リストにすぎない場合、その講義を完了として記載またはカウントしないでください。以下に該当するノートは却下し、needs_review のままにしてください。

• 生の ASR/OCR 抜粋が、「代表的な表現」または代表的な発言として提示されている
• 课堂讲解与主题推进 1 のような見出しがある
• 整理时建议不要把这一段只当作... のような一般的な助言が繰り返されている
• ほとんどすべてのコースに当てはまるような本文のセクションがある
• 誤認識された数学記号が修正されずに最終的な本文へ転記されている
• 診断用のノートや質の低い草稿が、コースのトラッカーまたは概要で正式なノートとして扱われている

数学を多く含むコースでは、最終ノートに具体的な数学的対象、仮定、方程式、証明の着想、例、およびそれらの関係を再構成して記載する必要があります。書き起こしからそれらを再構成できない場合は、正式な講義ページではなく、レビュー待ちの草稿として作成してください。

セマンティックパケットに、seed_bullets、生の sample_lines、transcript_excerpt などのユーザー向けシード文章を含めないでください。時間範囲と書き起こしへのパスを含めても構いませんが、エージェントは書き起こし自体を読み、意味に基づいてノートを再構成する必要があります。

レビュアーゲート

最終確定には、現在の Markdown のバイト列に対して、次の両方のゲートを通過する必要があります。

• scripts\validate_final_note.py が成功すること。
• 独立したレビュアーが decision=pass および finalization_allowed=true を返し、reviewed_note_sha256 が final_note_review_input.json の note.sha256 と一致すること。

いずれかのゲート通過後にノートを変更した場合、両方のゲート結果は無効となるため、再実行する必要があります。古いレビューに基づいて、コース概要、トラッカー、またはグラフの拡張を更新しないでください。

レビュアーの実装に関する詳細：

• サブエージェントの使用が許可されている場合は、独立したレビュアーエージェントを使用してください。
• 有効な指示によってサブエージェントの使用が許可されていない場合は、メインエージェント内で別途レビュアーの確認を行い、final_note_review_result.json を作成して、reviewed_note_sha256 が final_note_review_input.json と一致するようにしてください。
• 既存の final_note_review_result.json が同じハッシュに対して合格しており、ノートに変更がない場合は、レビューを再実行しないでください。

レビュアーの判定：

• pass：ノートがトランスクリプトを忠実に網羅し、コース内容を適切に扱い、根拠のある事実や強調点を保持しており、最終版として提示しても問題ありません。
• needs_revision：トランスクリプトをもとに最終ノートを作成できますが、現行のノートには根拠のある内容の欠落、過度な一般化、または修正が必要な箇所があります。修正後、ハードゲートを再実行し、その後レビュアーによる確認を再実行してください。
• reject：現在の資料またはノートは最終確定に適していません。抽出アーティファクトとセマンティックパケットは保持し、最終ノートを提示したり、グラフを拡張したりしないでください。

情報がないこと自体は、失敗ではありません。宿題、試験、成績評価、または締め切りに関する情報の欠落が問題となるのは、トランスクリプトにそれらの根拠があり、ノートがその情報を省略、歪曲、または捏造している場合に限られます。トランスクリプトに早期終了、授業内演習、学生の発表、ディスカッション、または連絡事項のみの授業が示されている場合、ノートは短くても構いませんが、実際の内容を忠実に記述する必要があります。

作成ガイドライン

セマンティックパケットから正式なObsidian授業ノートを作成する際は、次の点に従ってください。

• 作成するのは完成したノートです。下書き用ノート、診断用ノート、または後の整理担当者への指示ではありません。
• transcript.txt 全体を読んでから作成してください。semantic_rebuild_input.json はメタデータ、時間の目安、資料の索引としてのみ使用してください。
• 根拠となる抜粋、候補の表現、OCRの断片、生のASR行、内部作業メモを記載しないでください。
• ノート本文を書き始める前に、採用する概念を確定してください。概念をconceptsフロントマターに含めたり、表示されるWikiリンクにしたりできるのは、すでに完成したページがある場合、または同じ作業内で完成したページとして作成する場合に限ります。
• 根拠の弱い概念の手がかりは、記述する前に除外してください。節のラベル、一般的な名詞、単発の例、OCRやPPTだけに現れる用語、文字起こしのノイズ、授業の文字起こしとコースの文脈から説明できない概念は含めないでください。
• 有用な用語でも、概念ページにするにはまだ根拠が不十分な場合は、授業ノート内で通常のテキストとして記載し、概念のWikiリンクやフロントマターの概念にはしないでください。
• 主要な時間帯ごとに、どのような指導が行われたかを説明してください。定義、モデル、議論、証明、例、比較、事例の検討、方針の説明、教員のコメント、課題、試験の案内、授業運営などが該当します。
• 授業で特に重要な情報を記録してください。試験、宿題、締切、提出形式、配点、読書要件、教員が強調した要点、繰り返し強調された表現、公式、定理、定義、例、よくある間違いなどです。
• 教員が重要だ、試験に出やすい、間違えやすい、よく誤答される、授業後に復習が必要だと明言した場合、その内容をノートに残してください。
• 文字起こしの根拠が弱い場合、確定的な結論として扱わず、待核对の項目に記載してください。
• 最終ノートは、学生に直接伝える形にしてください。「整理時には……」「後で書き直す……」「この部分では主に……」など、作業過程に関するコメントは避けてください。

コース分野に応じた内容の再構成ガイドライン：

• 数学・統計：対象、定義、仮定、方程式、定理、証明の考え方、例、反例、記号の意味、結果どうしの関係を再構成します。
• 工学・コンピューターサイエンス：システムの構成要素、アルゴリズム、設計上の制約、実装手順、実験の設定、失敗事例、トレードオフ、公式やコードと設計との関係を再構成します。
• 人文・社会科学：概念、議論、歴史的・制度的背景、著者の立場、根拠、比較、事例、教員が重視した評価の観点を再構成します。
• 思想・政治関連のコース：政策概念、理論的主張、歴史的背景、文書名や出来事、価値判断、試験を意識した表現、抽象的な主張の説明に使われた例を再構成します。
• 語学・作文・コミュニケーション：語彙、修辞パターン、文章構成、例、添削箇所、練習要件、教員からのフィードバックを再構成します。
• 実験・デザイン・プロジェクトのコース：課題の目標、成果物、ツール、操作手順、データ要件、安全面や形式上の制約、評価基準、トラブルシューティングの助言を再構成します。

コースとの整合性に関するルール

セマンティックな書き換えを採用する前に、授業の再現解釈が次のどれに当たるかを判断してください。

• match
• weak_match
• mismatch

少なくとも次の情報を使用してください。

• 登録されているコース名
• 同じコースの最近の授業ノート
• 既存の概念ページと章のハブ
• 現在の授業再現の文字起こしとセマンティックパケット

コースとの整合性では、内容が一致するかを確認します。講師、曜日、時間帯、教室、course_idが異なっていても、確認済みのコース名が同じなら不一致とはしません。コース名が不明な場合は、整合性の判断を暫定的なものとし、コースの識別が確認されるまでは正式なトラッカーを更新しないでください。

結果がmismatchの場合は、シード用資料または下書きのみを残し、正式な最終授業ノートは作成しないでください。

文字起こしのみのルール

replay_diagnosis=transcript_only の場合：

• 汎用的な見出しを作り出さないでください
• スクリプトには、講座の文字起こしから時間区分、代表的な文字起こしの行、transcript_overview のみを提供させてください
• 講座の文字起こしと講座のコンテキストをもとに、エージェントが実際の講義構成を推測できるようにしてください
• スクリプトに、文字起こしのみから導いた概念を事前に確認させたり、根拠の乏しい文字起こしの手がかりから概念ページを作成させたりしないでください
• シードノートを、デフォルトで完成済みのノートとして扱わないでください

PPT のルール

• PPT は補足資料としてのみ扱ってください。
• 最終的な再構築を進めるために PPT を必須としないでください。
• PPT は、用語の表記、ページ名や書名、数式記号、運営に関するスクリーンショットの補助にのみ使用できます。
• PPT によって、レッスン構成、概念の展開、完了状態を決定しないでください。

待機中および部分的な文字起こしのルール

• waiting_transcript の場合は、待機中であることを示すプレースホルダーのみを作成してください。要約を作り出さないでください。
• transcript.txt が空、またはほぼ空の場合は、トラッカーでリプレイが waiting_transcript ではなくバックログに記載されていても、待機中の資料として扱ってください。
• partial_transcript の場合は、診断用の下書きのみを作成してください。最終的なレッスンノートとして扱わないでください。
• 講座の文字起こしが存在する一方で、現在の文字起こしベースの要約に大きな未カバー範囲が残っている場合は、needs_review とし、レビュー待ちのノートを作成してください。

強化されたソースのレビュー

プラットフォームに PPT ストリーム、ppt_outline、より完全な文字起こしなど、より充実したリプレイ資料が後から追加された場合は、そのレッスンをレビュー候補として 回放同期.md に提示してください。

半自動再構築：

python scripts\maintain_obsidian_course.py --vault-dir "<vault-dir>" --course-name "<course-name>" --rebuild-upgraded-replays --replay-note-mode "final-explained"

セマンティック再構築の完了としてすでにマークされているレッスンが、通知なしに上書きされないように保護してください。

出力ルール

• 公開出力は完成した成果物のみです：00-课程总览.md、事务.md、章节完成度.md、已整理课次.md、待回看问题.md、回放同步.md、待整理回放.md、03-Admin/*.md、正式な講義ノート、正式な概念ページ。
• 内部成果物はワークフロー用に限ります。レビュー用パケット、最終ノートのレビュー結果、ドラフトパケット、その他の診断メモをObsidian保管庫に置かないでください。.course-internal/*とsemantic_rebuild/*は旧式の内部スクリプト成果物に限ります。保管庫にユーザー向けの新しいワークフロー資料を作成しないでください。
• 公開出力から内部成果物へリンクしないでください。ユーザー向けのプレースホルダーテキストでも、「エージェントレビュー」「候補」「セマンティック再構築」など、プロセスを示す表現は避けてください。
• Obsidianで.course-internal、semantic_rebuild、final_note_reviewなどの旧式の内部ワークフローパスが無視されるようにしてください。ただし、境界を無視フィルターに依存させないでください。新しいfinal_note_reviewパケットは保管庫の外に置く必要があります。
• 概念リンクは、フロントマターだけでなくノート本文にも見えるようにしてください。
• 最終的な講義セクションには、時間参照を見える形で残してください。時間参照は必須条件です。再生位置を特定できるタイムスタンプ範囲を記述してください。たとえば时间参考：约 \03:29-18:58`、または1時間を超える場合は时间参考：约 `01:05:31-01:23:21`のようにします。授業開始から80～99分を指すために01:20-01:39と記述してはいけません。1時間を超える場合はHH:MM:SS`を使用してください。ノートの順序に沿って時間範囲が単調に進むようにし、実際の主要な講義セクションを表せるだけの長さを確保してください。
• 数式は$...$または$$...$$のみで記述してください。
• グラフ拡張ルールはセマンティックパケット内に限ります。補助ルールのメモを保管庫のコンテンツとして公開しないでください。
• コースページは概念を中心に構成してください。講義ページはグラフを支えるものであり、それ自体がグラフになってはいけません。
• 概念ページは、書き起こしで安定して確認できる概念からのみ作成してください。PPTやOCRのノイズをもとに概念ページを作成しないでください。
• 品質の低い書き起こしの断片、代表的な表現、一般的なセクション名から概念ページを作成しないでください。
• ページの欠落チェックは回帰防止策として扱い、メインのワークフローにしないでください。メインのワークフローでは、執筆前に概念の採否を決定します。承認された正式な概念を講義に含める前に、その概念ページがすでに存在するか、同じ作業中に作成されている必要があります。
• コースのバッチを完了とする前に、ページの欠落チェックを必ず実行してください。最終化された講義のconceptsと、目に見える概念のウィキリンクを収集し、コースのトラッカーと管理ページを除外して、各正式な概念に対応する完成済みの概念ページが02-Concepts/<course>/にあることを確認してください。
• チェックでページの欠落が見つかった場合は、プロセス上の失敗として扱ってください。講義から弱い概念を削除するか、コース資料に裏付けられた概念カードとハブへの接続を作成してから、章节完成度.mdを更新してください。
• 概念ページは内容を充実させつつ、簡潔に保ってください。このコースにおける概念の定義、前提となる概念・関連概念・対照的な概念へのリンク、講義の参照を記載し、書き起こしで裏付けられた数式や例のみを含めてください。
• validate_final_note.pyで拒否された講義を、コースのトラッカーやグラフ拡張に追加しないでください。

Windowsでは、生成ファイルの検証時にUTF-8対応のシェルを優先してください。必要に応じて、手動でGet-Contentを実行したり、コンソール上で確認したりする前に、[Console]::InputEncodingと[Console]::OutputEncodingをUTF-8に設定してください。

PowerShellでインラインのPythonを使う場合は、次の形式を使用してください。

@'
print("hello")
'@ | python -

PowerShellではpython - <<'PY'のようなBashヒアドキュメント構文を使用しないでください。