课程表导出

将杂乱的课表输入转换为经过校验的日历导出文件。以准确性为首要目标：不得静默推断周次范围，不得跳过非空单元格，且在归一化后的课表未与原始输入完成交叉核对前，不得生成最终的 .ics 文件。推荐采用多轮工作流：先归一化 → 再验证 → 解决歧义 → 再次验证 → 最后导出。

不得假定其他学校的日历日期、课时时间、时区或学期结构适用于当前场景。若用户未提供“第1周锚点日期”、课时时间表、时区，或其他任何实现确定性导出所必需的校本日历设置，请在生成最终 .ics 文件前主动索取。

工作流

1. 收集权威输入源。
   必需项：

   • 至少一个主课表来源
   • 课时时间表（period-time table）
   • 第1周锚点日期（理想情况下为第1周的周一），若存在任何按周循环的课程，则此项必须提供
     可选项：
   • 用于实验课、补课或周末课程的补充截图
   • 第二个课表来源，用于交叉核对
   • 此前导出的日历文件或清单（manifest），用于差异比对
     若任一必需项缺失，请明确向用户索取，切勿复用此前学校或此前导出中使用的值。

2. 在生成日历输出前，先构建归一化的课表清单（manifest）。
   使用 references/manifest-schema.md 中定义的 Schema。
   支持以下两种结构：

   • 按“星期 + 课时槽位 + 周次集合”为键组织的循环课程组（recurring course groups）
   • 按“具体日历日期 + 课时槽位”为键组织的日期限定课程组（dated course groups）
     每个课程组应唯一对应以下组合：
   • 课程名称
   • 上课地点
   • 循环依据（recurrence basis）
     若源单元格中包含多个课程，且其周次规则不同，则需将其拆分为多个课程组。
     为每个课程组保留其原始来源信息（source provenance），以便后续审查时可追溯该课程组由哪个输入源引入。

3. 严格保留源内容的字面含义。

   • 显式展开明确的范围，例如将 1-8 展开为第1至第8周。
   • 显式展开奇偶周规则，例如将 9-16 even 或 5-11 odd 展开为对应的所有偶数周或奇数周。
   • 将源中明确给出的日历日期直接作为日期限定课程组保留，而非强行套入周次计算逻辑。
   • 若源文本存在歧义，应立即中止并显式提示歧义，不得擅自猜测。
   • 不安全猜测示例：将 5,9 odd 错误地解释为 5-9 odd。

4. 仅当源明确支持时才执行合并。
   仅当满足以下全部条件时，方可将连续的课时槽位合并为一个更长的事件：

   • 课程名称相同
   • 教师相同（若已提供）
   • 上课地点相同
   • 星期相同
   • 周次集合相同
     否则必须保持分离。

5. 首轮验证：对照原始输入进行校验。
   在提出后续问题或执行导出前，须完成以下验证：

   • 所有非空课表单元格均已纳入处理
   • 清单中每个课程组均可由至少一个已准备的源条目解释
   • 未遗漏任何课程组
   • 第1周周一映射到预期的日历周
   • 奇偶周处理方式与源文本一致
   • 合并的课时确实来自相邻且匹配的槽位
   • 补充截图已明确整合或被显式排除
   • 清单中每个派生课程组均附有对应的源引用
     当你已完成源条目覆盖检查清单后，运行 scripts/check_manifest_coverage.py。将其视为双向覆盖检查：
   • 每个已准备的源条目必须至少映射到一个清单课程组
   • 每个清单课程组必须至少被一个已准备的源条目覆盖
   • 若某覆盖条目指定了 source_id，则仅引用该源的清单课程组可满足该条目

6. 通过小轮次问询解决歧义。
   每次仅提出当前阻塞问题集中最小必要的一组未解问题。
   良好的问询节奏示例：

   • 第1轮：时区、课时时间表，以及（若存在循环课程）第1周锚点日期
   • 第2轮：冲突的周次标注或源间矛盾
   • 第3轮：剩余的合并/拆分决策
     切勿一次性抛出所有可能问题。仅将彼此关联、且对下一步确定性操作所必需的歧义批量处理。

7. 用户答复后执行第二轮验证。
   仅重新校验受用户答复直接影响的课程组，随后再执行一次完整覆盖检查。
   若某次修改解决了某一歧义，却引发新的不一致，请立即中止并显式指出。
   任何因用户答复导致清单变更后，均需重新运行 scripts/check_manifest_coverage.py。

8. 生成 .ics 文件。
   基于归一化后的清单运行 scripts/generate_ics.py。
   该脚本必须仅依赖 Python 标准库，确保可在典型本地机器上直接运行，无需额外安装依赖。

9. 报告结果时需明确列出限制条件（caveats）。
   在最终响应中：

   • 注明输出文件路径
   • 指出所有需用户确认的歧义项
   • 说明仍存在的任何人工判断环节
   • 说明本次导出是否基于单个或多个输入源完成交叉核对

提取规则

• 当主课表来源与截图同时存在时，优先从主来源直接提取，而非依赖 OCR 识别截图。
• 除非截图明显覆盖主课表，否则一律将课表截图视为次要来源。
• 支持在单次任务中处理多个课表输入。典型来源优先级如下：
  • 机器可读的课表导出文件（如 CSV / JSON）
  • 课表 PDF 或截图
  • 关于实验课、周末课或补课的补充通知
  • 后续聊天中粘贴的纯文本
• 同时支持循环制学期课表和一次性日期限定课程。
• 若两个来源存在分歧，应同时保留双方主张，直至其中一方被明确解决；不得静默以较晚来源覆盖较早来源。
• 将考勤提醒、先修课警告等备注单独保存为注释（note），不得将其编码为虚假的课程事件。
• 日历事件摘要（summary）应简明扼要；周次规则、教师姓名及警告信息统一放入描述（description）字段。
• 导出步骤优先使用内置工具及 Python 标准库。
• 任何需第三方库的解析器均视为可选组件，而非基础能力。
• 若源提取需安装包，请首先尝试免安装路径。
• 若安装仍是最佳方案，须先征得用户同意，并说明为何内置路径不可行。

歧义处理规则

出现以下任一情况时，必须中止并主动询问用户：

• 标点符号导致周次规则含义不清
• 单元格混合多个上课地点，但无清晰的周次划分
• 补充图像与主课表存在冲突
• 源中给出了周次编号，但未提供第1周锚点日期
• 源中给出了课时编号，但未提供起止时间
• 时区缺失，且无法从上下文安全推断
• 正确性依赖于校本节假日、补课规则或学期边界等特定信息
• 源中混合了按周循环课程与明确日历日期课程，且未说明优先级
• 两个课表来源对同一课程组的描述不一致
• 某课程在一个来源中出现，却在另一来源中消失
• 同一课程出现在相邻课时槽位中，但元数据略有差异，导致合并存在风险

若信息已在源中明确给出，且可确定性地归一化，则无需提问。
在具体阻塞点全部解决前，不得提出宽泛的兜底式问题（例如“还有其他需要注意的吗？”）。

常见陷阱

执行非简单导出任务前，请务必通读 references/pitfalls.md，并将其作为起飞前检查清单（pre-flight checklist）。

需避免的常见错误包括：

• 因前一单元格已提过相同课程而遗漏非空单元格
• 将格式错误的周次字符串强行“美化”为看似合理但实际不支持的范围
• 遗漏跨课时槽位课程的后半部分
• 未经核实即将在一个学期中使用的课时时间套用于另一学期
• 仅完成一轮验证即执行导出
• 混淆周末课程或实验课的来源归属
• 将第三方 Python 依赖硬编码进核心导出路径

参考资料

• references/manifest-schema.md
  编写归一化课表清单（manifest）或审阅他人清单前，请务必阅读此文档。

• references/coverage-schema.md
  准备源条目覆盖检查清单时，请参考此文档。

• references/pitfalls.md
  提取前及最终导出前均需再次阅读。

• scripts/generate_ics.py
  用于将归一化后的清单 JSON 文件确定性地转换为 .ics 文件。

• scripts/check_manifest_coverage.py
  用于强制保障已准备源条目与清单课程组之间的双向覆盖关系。

最小交付物

若用户仅需指导，切勿生成文件。请提供：

• 你仍缺少的输入项
• 完整的歧义列表
• 下一步确定性操作

若用户要求完成导出，则应执行归一化并生成 .ics 文件，而非仅描述流程。