obsidian-course-vault

Obsidian Course Vault

当用户希望在 Obsidian 中长期记录课程笔记时，使用此技能。

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

核心边界

• 让脚本处理知识库结构、回放同步、回放诊断、缓存刷新、追踪器维护和文件写入。
• 让 Agent 处理课程对齐、概念确认、术语修正、图谱解读和最终笔记正文。
• 不要让确定性种子笔记冒充已完成的课程笔记。

主要命令

初始化知识库：

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 课程之前：

• 尽可能根据提取出的课程标题确定 course-name。规范化后的标题就是课程身份。
• 如果知识库中已存在解析出的标题，则复用该课程文件夹。标题相同即为同一门课程，即使新的 coursedetail URL 使用了不同的 course_id、讲师、时间表、教室或 sub_id 范围。
• 如果标题缺失或不可靠，则仅将 course_id 用作临时课程名称，例如 course-136278；或者在写入正式笔记前询问用户预期的标题。不要根据现有知识库文件夹、教师姓名、上课时间或旧的提取目录推断课程。
• 将“使用之前的知识库”理解为选择知识库根目录，而不是自动选择其中已有的课程文件夹。
• 在同步元数据中保留每个源 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，并将课程内容准确归入以下一种状态：

• waiting_transcript
• partial_transcript
• transcript_only

所有下游笔记生成流程都应使用此诊断结果，而不是各自重新计算路由决策。

推荐的回放模式

将以下模式视为面向用户的常规模式：

• final-lite
• final-explained

旧版 final 被视为语义数据包准备流程，而不是直接撰写最终正文的许可。仅对占位内容或待处理笔记使用 draft。

在语义模式下，脚本只能写入：

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

默认情况下，不要将种子课程笔记写入知识库。只有在语义重建完成后，Agent 才应读取该数据包并生成第一篇用户可见的课程笔记。

重建笔记被计为正式课程页面之前，运行：

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 知识库之外。如果 --note 位于知识库内且省略了 --output-dir，review_final_note.py 会将文件写入 $HOME/.codex/course-vault-work/final_note_review/...。只有在当前系统/开发者指令允许启动独立审阅者时，才使用 final_note_review_prompt.md 配合独立的审阅 Agent。如果无法使用或不允许使用子 Agent，则自行进行单独的审阅，并使用相同提示词，将结果写入 final_note_review_result.json。审阅期间不要编辑笔记。

高效批量工作流

当用户明确要求整理某门课程的所有待处理 BUAA 回放时：

1. 如果已有回放提取目录和语义数据包，则沿用它们。
2. 先构建缺失的语义数据包；对于已有最新 transcript.txt 和 semantic_rebuild_input.json 的课程，不要重新运行浏览器提取。
3. 写入前先筛选候选项：跳过已完成整理的课程，跳过未来课程，并将缺失、空或几乎为空的转录文本留在等待队列／待办清单中。
4. 整理每节课之前，根据转录文本中稳定的教学对象和现有课程图谱，确定准予纳入的正式概念集合。可立即复用已有概念页面；只有获准扩展图谱的真正新概念，且已规划好概念页面／中心页位置后，才能作为 Wiki 链接或 concepts frontmatter 条目出现。
5. 对每节符合条件的课程，阅读完整转录文本，仅使用准予纳入的概念编写正式笔记，运行验证，创建审阅数据包，并记录针对当前笔记哈希的通过审阅结果。
6. 在同一轮课程／批次整理过程中落实获准纳入的新概念，之后才能将笔记视为已完成。不要让已完成的课程包含仅承诺日后补齐的概念链接。
7. 批次完成后运行一次 maintain_obsidian_course.py，以刷新概览、跟踪文件、待办清单和同步笔记。只有在需要检查点，或需要它创建缺失目录／数据包时，才提前运行。
8. 批次期间不要根据薄弱的、仅来自转录文本的线索重新生成概念页面；应将图谱扩展留给转录文本中稳定的概念和常规维护流程。

这是批处理优化，不是放宽语义门槛。

强制语义工作流

对于语义模式：

1. 根据回放产物和近期课程上下文构建语义数据包。
2. 接受笔记前，先运行课程对齐检查。
3. 起草正文前，确定准予纳入的概念集合。区分已有概念页面、获准纳入的新概念以及被拒绝／较弱的线索。
4. 使用新概念作为 Wiki 链接或课程 frontmatter 概念之前，先落实获准纳入的新概念页面，并将其连接到现有或新的中心页。
5. 仅使用准予纳入的概念，从语义上重写笔记。
6. 对重写后的 Markdown 运行 scripts\validate_final_note.py。
7. 使用 scripts\review_final_note.py 在知识库外的工作目录中生成审阅数据包。
8. 针对当前笔记哈希运行独立审阅。
9. 只有在语义重建完成、概念准入／落实保持一致、硬性门槛通过且审阅结果为 pass 后，才能将课程标记为已完成。
10. 只有在转录文本覆盖率和基于转录文本的摘要覆盖率均通过时，才允许创建正式课程页面。

如果语义重建仍在等待处理，则不要在课程跟踪文件中将该课程计为已完成。

正式的 Obsidian 回放笔记的 frontmatter 至少必须包含：

• 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 仍是未经审核的自动生成占位文件时，才刷新该文件
• 仅在 Agent 审核事务候选内容并完成提炼后，才更新知识库级 03-Admin/作业总表.md 和 03-Admin/考试与通知.md

课程级事务是经过审核的摘要，而不是关键词罗列。只保留会影响学生应做什么、核对什么、提交什么、阅读什么、参加什么或考核预期的事项。将重复或含糊的提及压缩为每个日期的一条简短记录。排除常规教学内容、一般性鼓励、没有具体交付内容的学习建议、概念复习建议以及宽泛的课程叙述。课程安排 可以保留在课程笔记中作为局部背景，但除非包含属于 通知 的具体日程、地点或课程安排变更，否则不要将其汇总到课程级 事务.md。

不要让关键词提取直接写入最终事务。按以下流程操作：生成 .course-internal/affairs-candidates.md；在主 Agent 中进行事务审核，或交由允许的独立审核者审核；然后将精简后的审核结果写入 事务.md 和 Admin 表格。无需要求人工审核，也不要在日常维护期间覆盖经 Agent 审核的 事务.md。

不要在面向用户的笔记中公开事务候选内容。不要从 事务.md、00-课程总览.md、跟踪表或 Admin 页面链接到 .course-internal/affairs-candidates.md。

Agent 事务审核必须明确排除或合并以下内容：

• 常规教学内容或概念复习建议
• 一般性鼓励、学习方法或激励性言论
• 对同一作业、考试或通知的重复提及
• 没有具体交付内容、含糊提到“可能对作业有用”的笔记
• 仅因 分数、分类 或模型分数等词而命中的类考试关键词

不要汇总来自等待转写笔记、部分转写笔记、质量审核未通过的笔记或语义重建尚未完成的笔记中的事务。诸如“当前未从转写中识别出稳定...”之类的占位句不是事务，不得出现在 事务.md 或 Admin 表格中。

最终笔记质量门槛

如果课程笔记只是一份加了装饰的转写片段清单，就不要将其写入或计为已完成。若笔记包含以下内容，应予以退回并保持为 needs_review：

• 将原始 ASR/OCR 片段作为“代表性表达”或代表性语句呈现
• 使用 课堂讲解与主题推进 1 之类的标题
• 反复出现诸如 整理时建议不要把这一段只当作... 的通用建议
• 几乎适用于任何课程的章节正文
• 未经修正地将误识别的数学符号照搬到最终正文
• 课程跟踪表或总览将诊断内容或质量较弱的草稿标记为正式笔记

对于数学内容较多的课程，最终笔记必须重建具体的数学对象、假设、方程、证明思路、示例及其相互关系。如果 Agent 无法根据转写内容做到这一点，应撰写一份需要审核的草稿，而不是正式课程笔记页。

语义信息包不得包含面向用户的种子文本，例如 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：当前源材料或笔记不适合定稿。保留提取产物和语义数据包；不要提交最终笔记，也不要扩展图谱。

缺失内容不等于失败。只有当转录中有相关证据，而笔记却遗漏、歪曲或捏造时，缺少作业、考试、评分或截止日期信息才是问题。如果转录显示提前下课、课堂练习、学生展示、讨论或仅涉及后勤安排的课程，笔记可以很短，但必须忠实描述实际情况。

编写约定

根据语义包撰写正式的 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
• 让 Agent 根据课程转录文本和课程上下文推断真实的教学结构
• 不要要求脚本预先确认仅依据转录文本的概念，也不要根据薄弱的转录文本线索创建概念页面
• 默认不要将种子笔记视为已完成的笔记

PPT 规则

• PPT 仅作为补充材料。
• 不要将 PPT 设为最终重建的必要条件。
• PPT 仅可用于核对术语拼写、页面或书籍标题、公式符号和后勤安排截图。
• PPT 不得决定课程结构、概念扩展或完成状态。

等待和不完整转录文本规则

• waiting_transcript：仅创建等待占位内容。不要编造摘要。
• 即使跟踪器当前将回放列在积压项下，而不是 waiting_transcript，空白或几乎为空的 transcript.txt 也应视为等待材料。
• 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/* 仅为遗留／内部脚本产物；避免在库中创建新的用户可见工作流材料。
• 绝不要在公开输出中链接内部产物。面向用户的占位文本也应避免使用「Agent 审阅」「候选项」或「语义重建」等流程用语。
• 确保 Obsidian 忽略 .course-internal、semantic_rebuild 和 final_note_review 等遗留内部工作流路径，但不要依赖忽略筛选器来划定边界。新的 final_note_review 材料包必须放在库外。
• 概念链接应显示在笔记正文中，而不只是放在 frontmatter 里。
• 在最终课程章节中保留可见的时间参考。时间参考是硬性要求：写出可定位回放的时间范围，例如 时间参考：约 \03:29-18:58`；超过第一小时后，使用 时间参考：约 `01:05:31-01:23:21`。绝不要用 01:20-01:39表示课堂第 80 至 99 分钟；超过一小时后，使用HH:MM:SS`。时间范围必须按笔记顺序递增，且时长应足以代表一个真正的主要课程章节。
• 数学公式仅使用 $...$ 或 $$...$$。
• 图谱增长规则仅保留在语义材料包内部。不要将辅助规则笔记作为库内容公开。
• 课程页面应以概念为中心。课程笔记为图谱提供支持，不应成为图谱本身。
• 仅根据稳定的转录内容扩展概念页面。不要因 PPT 或 OCR 噪声创建概念页面。
• 不要根据低质量的转录片段、代表性表达或通用章节标签创建概念页面。
• 将缺失页面检查视为回归防护，而非主要工作流。主要工作流是在撰写前准入概念：在概念页面已存在或正在同一轮撰写之前，不得将任何已接受的正式概念纳入课程笔记。
• 宣布课程批次完成前，仍须执行缺失页面检查：收集已定稿课程笔记中的 concepts 和可见概念 Wiki 链接，忽略课程跟踪页／管理页，并核实每个正式概念在 02-Concepts/<course>/ 下都有对应的已完成概念页面。
• 如果检查发现缺失页面，应视为流程失败：要么从课程笔记中移除薄弱概念，要么撰写有课程内容支持的概念卡并建立枢纽连接，然后再更新 章节完成度.md。
• 概念页面应内容充实但简洁：结合本课程语境定义概念，链接前置／相关／对比概念，列出课程笔记引用，并仅包含有转录内容支持的公式或示例。
• 如果 validate_final_note.py 拒绝某篇课程笔记，不要将其加入课程跟踪表或图谱增长内容。

在 Windows 上验证生成的文件时，优先使用 UTF-8 shell。如有需要，在手动使用 Get-Content 或其他控制台检查之前，将 [Console]::InputEncoding 和 [Console]::OutputEncoding 设为 UTF-8。

在 PowerShell 中编写内联 Python 时，使用：

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

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