buaa-classroom-summarizer

BUAA 授業要約

次の用途でこのスキルを使用します。

• classroom.msa.buaa.edu.cn/livingroom のリプレイ URL が 1 つある場合
• classroom.msa.buaa.edu.cn/coursedetail のコースページが 1 つある場合

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

基本方針

• 認証、抽出、リプレイの診断、キャッシュ、成果物の書き込みはスクリプトに任せます。
• コースとの対応付け、概念の確認、用語の修正、最終的な文章の再構成はエージェントが行います。
• セマンティックな再構築が明示的に完了するまでは、決定論的なノート出力を下書きとして扱います。

主なコマンド

単一リプレイの抽出：

python scripts\extract_buaa_classroom.py "<livingroom-url>" --output-dir "<output-dir>"

コース全体のリプレイの一覧表示または抽出：

python scripts\collect_buaa_course_replays.py "<coursedetail-url>" --output-dir "<output-dir>"
python scripts\collect_buaa_course_replays.py "<coursedetail-url>" --output-dir "<output-dir>" --extract-existing --skip-existing

コース全体に対するコマンドは、抽出と一覧作成のためのものであり、利用可能なすべての授業について最終ノートを生成する許可ではありません。coursedetail URL の場合は、まず成果物を一覧表示または抽出し、その後、ユーザーがバッチでの最終化ワークフローを明示的に依頼していない限り、次にセマンティックな再構築を行う授業をユーザーに確認してください。

コースの識別ルール

coursedetail URL の場合、コースフォルダーを選択したり、Vault のコンテキストを再利用したりする前に、コースを特定してください。

• まず、classroom／SPoC のメタデータ、保存済みのコース詳細ファイル、リプレイのメタデータ、または安定したリプレイタイトルから、最も確かなコース名を抽出します。
• 正規化したコース名を正式なコース識別情報として扱います。タイトルが既存のコースと一致する場合、course_id、講師、授業時間、教室、sub_id の範囲が異なっていても同じコースです。
• 信頼できるタイトルが得られない場合は、course-136278 のように course_id を暫定的な識別情報として使用します。教師、時間割、授業日、古い抽出ディレクトリ、近隣の Vault の内容を根拠に、既存のタイトル付きコースへ統合してはいけません。
• course_id とソース URL はソースのメタデータとして保持しますが、タイトルが確認済みのコースを分割するためには使用しないでください。
• タイトルの抽出が曖昧で、対象の Vault にコースフォルダーの候補がすでにある場合は、正式なノートを書き込んだり、トラッカーを更新したりする前に、ユーザーに確認してください。

ローカル Cookie の再利用が不安定な場合のランタイムブラウザー認証：

python scripts\extract_buaa_classroom.py "<livingroom-url>" --output-dir "<output-dir>" --browser-runtime-auth --browser-channel "auto"

必須のリプレイ診断

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

• waiting_transcript
• partial_transcript
• transcript_only

後続のノート処理では、他の場所でルート判定を再計算せず、この診断結果を使用する必要があります。

単独 Markdown ノートのワークフロー

セマンティック再構築パケットを準備します。

python scripts\extract_buaa_classroom.py "<livingroom-url>" --output-dir "<output-dir>" --export-markdown-note

ユーザー向けの優先モード：

python scripts\extract_buaa_classroom.py "<livingroom-url>" --output-dir "<output-dir>" --export-markdown-note --markdown-note-mode "final-lite"
python scripts\extract_buaa_classroom.py "<livingroom-url>" --output-dir "<output-dir>" --export-markdown-note --markdown-note-mode "final-explained"

これらのモードでは、次のファイルのみを書き込みます。

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

従来の final を含む、最終ノート作成を目的とするすべてのモードでは、セマンティックパケットのみを書き込みます。デフォルトでは lesson_note.md を出力しないでください。パケットを唯一の中間成果物として扱い、その後、エージェントに最終ノートを作成させます。

エージェントが作成したノートを最終版として受け入れる前に、次を実行します。

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

バリデーターに失敗した場合は、抽出成果物とセマンティックパケットのみを保持します。失敗したノートの名前を変更したり、最終ノートとして提示したりしないでください。

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

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

有効なシステム／開発者の指示でエージェントの起動が許可されている場合に限り、独立したレビュアーエージェントで final_note_review/final_note_review_prompt.md を使用します。サブエージェントを利用できない、または許可されていない場合は、同じプロンプトを使って自身で別途レビューを行い、結果を final_note_review/final_note_review_result.json に書き込みます。レビュー中はノートを編集しないでください。

エージェントが最終的な単独 Markdown ノートを作成する際は、次の点に従います。

• 読みやすい授業ノートのファイル名を使用します。できれば、授業タイトルを使います。例：2026-04-13 贝叶斯统计 第7周星期1第3,4,5节.md
• 最終ノートに lesson_note.md という名前を付けないでください。
• 同じコースの最終授業 Markdown ノートは、コースタイトルを名前にした1つのコースフォルダーに格納します。例：贝叶斯统计/2026-04-13 贝叶斯统计 第7周星期1第3,4,5节.md
• 選択した出力ディレクトリの名前がすでにコースタイトルと完全に一致する場合は、最終授業 Markdown ノートをそのディレクトリに直接書き込みます。课程名/课程名/... のように入れ子にしないでください。
• metadata.json、transcript.json、セマンティック再構築パケットなどの抽出成果物は、元のリプレイ出力ディレクトリに保持します。コースフォルダー形式で整理する必要があるのは、ユーザー向けの最終 Markdown ノートのみです。
• 授業タイトルと本文から直接始めます。
• 状态、来源、文字起こしの網羅率、リプレイの診断、PPT の抽出状況などの作成用メタデータを、ユーザー向けノートに表示しないでください。
• ノートを最終版とする前に、scripts\validate_final_note.py に合格させます。
• ノートを最終版とする前に、現在のファイルハッシュでレビューゲートに合格させます。

バッチ最終化ルール

コース全体の抽出を行っても、すべてのリプレイを無条件に最終化してよいわけではありません。コース全体の実行では、次の成果物が生成される場合があります。

• リプレイの一覧
• 抽出成果物
• セマンティック再構築パケット
• コース単位の未完了タスクリスト

ユーザーが現在保留中の授業をすべて処理するよう明示的に依頼した場合は、バッチ最終化が許可されます。ただし、バッチ内でも授業ごとに次の手順を実行する必要があります。

• ユーザーから修正を依頼されていない限り、すでに最終化された授業はスキップします。
• 候補となる各授業について、ノートを作成する前に、文字起こしが存在し、空でないことを確認します。
• その授業のノートを書く前に、文字起こし全体とセマンティックパケットを読みます。
• その授業を最終版とする前に、validate_final_note.py を実行し、レビューパケットを作成して、現在のノートハッシュに対する合格結果を記録します。
• 授業がいずれかのゲートに失敗した場合は、成果物／パケット、またはレビューゲート待ちのドラフトのみを残し、他の対象授業の処理を続けます。
• 中間チェックポイントが必要な場合を除き、トラッカー／概要の更新は授業ごとではなく、バッチの最後に一度だけ実行することを優先します。
• 入力に変更がない場合は、既存の抽出成果物とセマンティックパケットを再利用します。文章を作り直すためだけにブラウザー抽出を再実行しないでください。

最終ノート品質ゲート

ユーザー向けの最終ノートは、装飾を施した文字起こしのセグメント一覧ではなく、意味を再構成したものでなければなりません。最終ノートを作成または承認する前に、次のパターンが含まれている場合は却下してください。

• 「代表的な表現」や「代表性表达」として提示された、生の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：現在の資料またはノートは最終化に適していません。抽出アーティファクトと意味パケットを残し、最終ノートとして提示しないでください。

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

意味的な再構築のルール

• 書き換えを最終版として承認する前に、コースとの整合性を確認してください。
• コースの文脈から意図された用語が明確な場合は、明らかなASR/OCRの用語誤りを修正してください。
• レッスンの時間軸を見える形で保ってください。各最終セクションには、パケットの時間範囲、または大まかなMM:SS-MM:SSのタイムスタンプを残してください。
• 数式は$...$または$$...$$のみで記述してください。数式をバッククォートで囲まないでください。
• セクションの区切り、レッスンの主題の流れ、完了確認の根拠として使用する一次資料は、コースの文字起こしのみとしてください。
• コースの文字起こしの網羅性と要約の網羅性の両方を満たした場合に限り、レッスンを最終版として扱ってください。
• コース固有の内容を再構成してください。意味を理解できていない部分を、一般的な学習アドバイスで置き換えないでください。
• transcript.txtが存在しない、空である、またはほぼ空の場合は、トラッカーでバックログに記載されていても、リプレイには文字起こしの資料がまだないものとして扱ってください。メタデータ、スケジュール、タイトル、またはPPTのみから正式なノートを作成しないでください。

執筆の指針

意味パケットをもとに、学生向けの最終版 Markdown ノートを作成する際は、次の点に従ってください。

• 作成するのは完成したノートであり、たたき台や診断用ノート、後任の整理担当者への指示ではありません。
• 執筆前に transcript.txt を最後まで読んでください。semantic_rebuild_input.json はメタデータ、時間の目印、資料の索引としてのみ使用してください。
• 根拠となる抜粋、候補表現、OCR の断片、生の ASR 行、内部作業メモは記載しないでください。
• 各主要な時間帯で、どのような指導が行われたかを説明してください。たとえば、定義、モデル、議論、証明、例、比較、事例の検討、方針の説明、教員のコメント、課題、試験の段取り、授業運営などです。
• 授業における重要な情報を記録してください。試験、宿題、期限、提出形式、成績評価の比重、読書要件、教員が強調した要点、繰り返し強調された表現、公式、定理、定義、例、よくある誤りなどです。
• 教員が明示的に重要だと述べた内容、出題される可能性が高い内容、混同しやすい内容、間違いが多い内容、授業後の復習が必要な内容は、必ずノートに残してください。
• 文字起こしの根拠が弱い場合は、確実な結論として述べるのではなく、その項目を 要確認 に記載してください。
• 最終版のノートは、学生に直接語りかける内容にしてください。「整理時には……」「後で書き直す……」「この部分では主に……」など、作業過程に関する記述は避けてください。

コース領域ごとの再構成ガイド：

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

文字起こしのみを使う場合のルール

replay_diagnosis=transcript_only の場合：

• 「授業の位置づけ／基礎概念／方法の流れ」のような、内容を偽って補うテンプレートを出力しないでください。
• スクリプトが提供するのは、コースの文字起こしから得られる時間区分、代表的な発言、transcript_overview に限ります。
• コースの文字起こしとコースの文脈をもとに、エージェントが実際の授業構成を推定してください。
• 文字起こしのみの資料から、スクリプトに概念を事前確認させないでください。

PPT のルール

• 原則として、教員の配信映像を優先してください。
• PPT は補助資料としてのみ扱ってください。PPT の配信映像がある場合も同様です。
• PPT は、用語の表記、ページや書籍のタイトル、数式の記号、運営に関するスクリーンショットの確認に役立ててかまいません。
• セクションの区切り、授業の主軸、概念の生成、完了状態の判断に PPT を用いてはいけません。

運営事項のみを対象とした教員レビュー

課題、試験、連絡、段取りについてのみユーザーが確認を求めている場合：

python scripts\extract_buaa_classroom.py "<livingroom-url>" --output-dir "<output-dir>" --export-markdown-note --lightweight-teacher-review

このモードでは、教員の配信映像から短いレビュー用クリップを作成し、teacher_review.json を生成します。後続の確認手順で確定とマークされるまでは、結論をノートにひそかに書き換えてはいけません。

失敗時のルール

• コースの文字起こしがない場合は、抽出した成果物を保持しますが、正式なレッスンノートを作成しないでください。
• コースの文字起こしが空、またはほとんど空の場合は、文字起こしがない場合と同様に扱います。待機中／バックログに残し、最終ノートを作成しないでください。
• コースの文字起こしの内容が明らかに一部に限られている場合は、最終ノートではなく、診断用の下書きのみを残してください。
• コースの文字起こしは存在するものの、現在の要約がレッスンの序盤しか扱っていない、または大きな未カバー部分がある場合は、最終版にせず、ノートに needs_review のマークを付けてください。
• セッションの再利用に失敗した場合は、--browser-runtime-auth を指定して再実行してください。

Windows で生成したファイルを検証する際は、UTF-8 のシェルを使用してください。必要に応じて、手動で Get-Content を実行したり、コンソールで内容を確認したりする前に、[Console]::InputEncoding と [Console]::OutputEncoding を UTF-8 に設定してください。PowerShell でインライン Python を使う場合は、次のようにします。

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

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