教师排课占档规整

把教务系统的班级明细转换为校区主管可读、可筛选、可复核的课表。所有人数、容量、冲突选择和汇总均由脚本确定性计算。

何时触发

满足以下任一入口时触发本 Skill：

1. 首次整理：使用者提供教务系统导出的班级明细 .xlsx，要求查看教师各时段已排班、可排空段、班型供给或剩余容量。
2. 模板回传：使用者把本 Skill 第一版 teacher-schedule-result.xlsx 人工修改后重新上传，要求比较关班、新开班、换教师、移动时段或计划新班。
3. 规则调整：使用者用自然语言要求修改班容、开班线、课次、时段/轮次、校区组、排除值或配色，或要求“恢复初始规则”。
4. 结果复核：使用者要求解释 ready、needs_confirmation、blocked，或检查冲突、容量和模板差异。

首次生成或重跑前必须确认三个条件：数据日期、校区/管理单元、原始班级明细。仅解释已有结果时可以只读取结果工作簿和 schedule-review.json，但不得据此重新计算。首次运行没有人工模板时固定采用 rule_first。如果任务是未来 12 个月教师/教室产能规划，应改用 xdf-plan-campus-capacity；如果任务是自动排课、直接修改教务系统、非小学课程或本 Skill 范围外的临时班型，不得调用本 Skill 伪造结果。

适用范围

• 重庆新东方校区主管查看小学一至六年级素养课程。
• 科目只包括：思维（NL/SW）、双语 STEAM（ST）、博学（BX）。
• 首个可运行版本读取暑假和秋季明细；寒假、春季口径已记录，但没有对应源表时不得虚构输出。
• 输出用于查看教师占档、可排空段和班型供给多样性，不替代人工排课决策。

当前排课逻辑

脚本按以下固定顺序处理，后一步不能绕过前一步：

1. 输入安全：检查工作表、列、静态值、唯一班号、公式、外部链接和疑似公式注入。安全或数据合同失败时状态为 blocked，只输出校验信息。
2. 范围过滤：按完整校区名或管理单元选择数据；只保留小学 1–6 年级的 ST/BX/NL/SW，排除 S2/S3、复习、补课、定金、取消班和关闭班。
3. 班型识别：科目、年级和难度以班级编码为主，班级名称和源年级交叉验证；冲突时采用班号结果并提示。每年 7 月 1 日后，暑假年级按当年 9 月即将升入的年级理解。
4. 课次与时段：寒假 8 次、春秋 16 次、暑假 1–3 年级 12 次、4–6 年级 15 次；非标准课次进入待确认，确认前不进正式课表和容量。暑假按轮次与 08/10/13/16/18 点时段展示，混合周课和连续课时优先解析带“每天/每日/连续”的密集片段；秋季默认展示周四、周五晚间和周末时段，源数据出现周一至周三的合规时段时动态增加对应列。
5. 教师选择：授课教师只有一人时直接使用；有多人时必须采用唯一且属于授课教师列表的 主带课老师，否则进入待确认。
6. 人工模板：先执行数据源新增、模板遗留、同班号教师/时间变化的三向对比，再按显式 rule_first 或 template_first 决定是否应用模板位置。
7. 时段冲突：以“季节 + 教师 + 轮次/星期时段”为冲突键。多班冲突时，当前人数唯一最多的班临时入表；最高人数并列时所有候选都不入表，等待人工确认。
8. 容量与样式：按版本化开班线和最大班容计算总容量、当前数量、差额。允许超售；未达开班线为蓝色、已开未满为绿色、满班或超售为红色，均加粗。
9. 人工闭环：生成结果后必须询问导出快照之后是否发生关班、新开班、换教师或移动时段。AI 只能解释、比较和生成受限补丁，不自动确认排课，也不回写教务系统。

规则优先与模板优先如何切换

两种模式使用同一份数据源、数据日期和校区范围重跑；切换的是“正式班与回传模板冲突时相信谁”，不是切换安全规则。

调用方式：

--manual-template <人工修改后的课表.xlsx> --template-policy rule_first
--manual-template <人工修改后的课表.xlsx> --template-policy template_first

template_first 不能覆盖输入安全、支持年级/科目、标准课次、班号分类、容量、季节和计划新班语法。模式选择只对本次运行生效，不会自动写成永久业务规则。

计划新班不属于“教务正式班位置冲突”，因此合规的 新班ST3A 等在两种模式下都会以当前人数 0 纳入容量和冲突重算。若只是演练、不希望纳入计划新班，应从回传模板中移除该记录后再运行。

第一版课表回传后的 AI 处理

使用者可以下载第一版结果，在暑假/秋季课表中移动或删除正式班，并按约定写入计划新班，然后把文件重新上传给 AI。AI 必须按以下闭环处理：

1. 确认文件来自本 Skill，复用原始班级明细、数据日期和校区范围；不能只拿人工模板反推完整数据。
2. 只读取标准课表单元格中的正式班号和 新班... 记录，不把底色、批注或自由文本自动当成规则。
3. 执行三向对比：数据源有但模板没有、模板有但数据源没有、同班号教师或时段不同。
4. 解释差异含义：模板外的源班可能是人工关班或漏登；源外正式班号可能是陈旧/取消班；新班ST3A 等才是计划新班；正式班移动表示教师或时段变更。
5. 在应用前要求使用者明确说“规则优先”或“模板优先”。未明确时保持 rule_first，不得替使用者选择高风险的模板覆盖。
6. 对模板做硬约束校验。重复位置、跨季移动、缺教师、非法时段、源内不合格班和无效计划新班只进入待确认，不能因 template_first 被强制采用。
7. 重跑后同时交付新课表、模板对比、待确认 和 schedule-review.json，列明采用了哪些模板变更、移除了哪些源班以及哪些改动未应用。

模板记录与业务规则必须分开：一次人工移动、删班或新班只影响相应回传季节和本次模板重跑，不会被 AI 暗中“学习”为通用规则。

后续规则如何变化

规则分为三层，优先级和持久化方式不同：

AI 不直接修改初始配置，也不根据一次模板改动自行扩大规则。若使用者明确提出“以后思维一二年级最大班容都改为 17”，这属于本地规则覆盖；若只把某班从周六移到周日，这属于模板记录。说“恢复初始规则”时只清空本地覆盖并重跑，人工模板不会被改写。

工作流

1. 确认源文件是本地脱敏或受控的 .xlsx，不得提交到 Git。
2. 阅读 data-contract.md 和 business-rules.md。
3. 按实际源表列名核对版本化初始配置 config/teacher-schedule.json，不得让模型猜列，也不得把自然语言覆盖直接写回该文件。
4. 加载 Skill 后先运行一次基准课表：

python3 .agents/skills/xdf-normalize-teacher-schedule/scripts/normalize_schedule.py 
  --input <班级明细.xlsx> 
  --config config/teacher-schedule.json 
  --campus <完整校区名称> 
  --data-as-of YYYY-MM-DD 
  --output-dir <输出目录>

同一管理口径包含多个系统校区时，优先使用配置中的管理单元：

  --campus-group 礼嘉管理单元

临时组合也可以重复提供 --campus <完整校区名称>。输出摘要必须同时展示管理口径和实际纳入的源校区名称。

若使用者在上次生成的课表中按约定写入计划新班，增加 --manual-template；暑假和秋季模板分开保存时可重复提供：

  --manual-template <人工修改后的课表.xlsx>

人工模板必须执行三向对比：数据源新增、模板遗留、同班号教师/时间变更。只比较当前支持的 ST/BX/NL/SW，小学范围外编码不得制造陈旧班误报。

回传模板后必须显式选择开关并重新运行：

  --template-policy rule_first
  --template-policy template_first

• rule_first（默认）：教务数据与确定性规则优先，模板中的删班、换教师、换时段只提示差异。
• template_first：对已回传季节，模板中正式班的保留、教师和时段优先；未出现的源班不入表。安全、支持范围、课次、班号、容量和季节是硬约束，模板不能覆盖。

5. 检查退出码和 schedule-review.json：
   • ready：无异常，仍需使用者确认是否存在系统导出后的人工变化。
   • needs_confirmation：已生成安全子集，但冲突、非标准课次或人工候选必须确认。
   • blocked：输入安全、数据合同或唯一性失败；只解释校验问题，不输出正式课表和容量结论。
6. 阅读 output-spec.md 做视觉和业务复核。
7. 生成基准课表后必须询问使用者：是否有关班、新开班、换教师或移动时段等人工调整。使用者回传修改结果后，按选定开关复用同一数据源重跑，不得仅凭任意底色推断业务规则。

自然语言规则变更与回退

AI 先把使用者的自然语言要求转换为最小 JSON 补丁，展示“旧值→新值”，然后只能通过受限管理脚本写入 Git 已忽略的本地覆盖：

python3 .agents/skills/xdf-normalize-teacher-schedule/scripts/manage_schedule_rules.py 
  --base config/teacher-schedule.json 
  --overlay data/local/teacher-schedule-rules/active-overrides.json 
  apply --patch <AI生成并校验的补丁.json> --request "<使用者原话>"

重跑课表时增加：

  --rules-overlay data/local/teacher-schedule-rules/active-overrides.json

只允许覆盖校区组、标准课次、容量、时段/轮次、排除值和配色。源字段映射、安全、班号分类、冲突策略和计划新班语法不得由自然语言覆盖。

使用者说“恢复初始规则”、“回到初始规则”时，调用：

python3 .agents/skills/xdf-normalize-teacher-schedule/scripts/manage_schedule_rules.py 
  --base config/teacher-schedule.json 
  --overlay data/local/teacher-schedule-rules/active-overrides.json 
  restore --request "<使用者原话>"

初始规则始终保留在版本化配置中；恢复操作只清空本地覆盖，随后必须重跑并报告差异。基础配置哈希变化时阻断旧覆盖，不得静默迁移。

计划新班格式

只识别带 新班 前缀的单元格：

• 新班ST3A
• 新班SW3B
• 新班NL3A
• 新班BX3A
• 新班NL1、新班NL2：低年级思维基础班型。
• 新班NL1A、新班NL2A：低年级思维拔高班型。

计划新班当前数量为 0，容量按科目和年级规则取得。其他 NL1/NL2 后缀进入待确认。

强制边界

• 输入含公式、外部链接、疑似公式注入文本时阻断。
• 复习班、补课班、定金班、取消班、S2/S3 和非小学课程不进入正式结果。
• 非标准课次进入待确认，确认前不进入课表和容量汇总。
• 暑假同时包含周课和连续课时，优先用带“每天/每日/连续”的密集片段识别轮次与时段；多个密集片段结论不一致时进入待确认。
• 班型以班号为主、班级名称交叉验证；冲突时采用班号并提示。
• 授课教师只有一人时直接入表；有多人时必须从 主带课老师取唯一且存在于授课教师列表的人选，否则进入待确认。
• 同一教师同一时段多班时，人数唯一较大的班临时入表，其余进入冲突清单；最高人数相同时必须人工确认。
• 人工模板中的正式班教师/时段变化只能按显式 template_first 开关应用；默认 rule_first 只做差异提示。
• 不自动发送消息，不修改教务系统，不自动确认人工排课。
• 输出、日志和公开仓库不得包含真实样本、工号或可逆身份映射。

输出

• teacher-schedule-result.xlsx
• schedule-review.json

工作簿包含运行摘要、校验问题、排除记录、各季课表、容量总览、容量汇总、容量明细、排课冲突、待确认、模板对比和假设与版本。容量指标仅展示总容量、当前数量和差额。