buaa-classroom-summarizer

BUAA 课堂总结器

将此技能用于：

• 一个 classroom.msa.buaa.edu.cn/livingroom 回放 URL
• 一个 classroom.msa.buaa.edu.cn/coursedetail 课程页面

假设命令从此技能根目录运行。否则请使用 scripts/ 的绝对路径。

核心边界

• 由脚本处理身份验证、提取、回放诊断、缓存和制品写入。
• 由 Agent 处理课程对应、概念确认、术语校正和最终文本重构。
• 除非明确完成语义重建，否则将确定性笔记输出视为种子内容。

主要命令

提取单个回放：

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，请先确定课程身份，再选择课程文件夹或复用知识库上下文：

• 首先从 classroom/SPoC 元数据、已保存的课程详情文件、回放元数据或稳定的回放标题中提取最有力的课程标题。
• 将规范化后的课程标题视为规范课程身份。若标题与现有课程匹配，则视为同一门课程，即使 course_id、讲师、上课时间、教室或 sub_id 范围不同。
• 如果没有可靠的标题，则仅将 course_id 用作临时身份标识，例如 course-136278；不要根据教师、日程、课程日期、旧提取目录或附近的知识库内容，将其合并到已有标题的课程中。
• 保留 course_id 和来源 URL 作为来源元数据，但不要用它们拆分标题已确认相同的课程。
• 如果标题提取结果不明确，且目标知识库中已有可能匹配的课程文件夹，则在写入正式笔记或更新跟踪表之前暂停并向用户确认。

本地 Cookie 复用不可靠时使用浏览器运行时身份验证：

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

必需的回放诊断

构建任何笔记之前，脚本必须生成一份 replay_diagnosis，并将回放归入以下且仅以下一个类别：

• 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。将该语义包视为唯一的中间产物，然后让 Agent 生成最终笔记。

在接受 Agent 编写的笔记作为最终笔记之前，运行：

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>"

仅当当前系统／开发者指令允许启动独立审核 Agent 时，才使用 final_note_review/final_note_review_prompt.md。如果无法使用子 Agent 或不允许使用子 Agent，则自行使用相同提示词进行单独审核，将结果写入 final_note_review/final_note_review_result.json，审核期间不要编辑笔记。

当 Agent 编写最终独立 Markdown 笔记时：

• 使用易读的课程笔记文件名，最好采用课程标题，例如 2026-04-13 贝叶斯统计 第7周星期1第3,4,5节.md
• 最终笔记不要命名为 lesson_note.md
• 同一课程的最终课程 Markdown 笔记应放在一个以课程标题命名的文件夹中，例如 贝叶斯统计/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。可以包含时间范围和转录文件路径；Agent 必须自行阅读转录内容，并对笔记进行语义重构。

审阅门槛

只有当前 Markdown 字节同时通过以下两道门槛，才能定稿：

• scripts\validate_final_note.py 验证通过。
• 独立审阅者返回 decision=pass、finalization_allowed=true，且 reviewed_note_sha256 与 final_note_review_input.json 中的 note.sha256 一致。

如果笔记在通过任一道门槛后发生更改，两道门槛的结果均失效，必须重新运行。

审阅者实现细节：

• 如果允许使用子 Agent，请使用独立审阅者 Agent。
• 如果当前指令不允许使用子 Agent，请由主 Agent 单独进行审阅，并写入 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。
• 由 Agent 根据课程转录和课程背景推断实际课程结构。
• 不要让脚本预先确认仅依据转录内容得出的概念。

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 Shell。如有需要，在手动使用 Get-Content 或其他控制台命令检查文件前，将 [Console]::InputEncoding 和 [Console]::OutputEncoding 设为 UTF-8。在 PowerShell 中使用内联 Python 时，请使用：

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

不要在 PowerShell 中使用 Bash heredoc 语法，例如 python - <<'PY'。