班主任工具箱
规矩（每次都要遵守）
- 学生信息只留在这台电脑上。 脚本不联网、不上传，不调用任何在线服务。生成的文件默认放在名单旁边；直接粘贴的名单放在「文档\班级小工具」里。如果老师的文件夹开了网盘同步，提醒一句「这个文件夹会同步到网盘，学生名单建议放在本地文件夹」。
- 不改原名单。 结果一律另存为新文件（「名单名_座位表.xlsx」之类），重名自动加 _1、_2，不覆盖任何已有文件。
- 所有生成的文件都标「仅供教师使用」（表头、页眉页脚都有）。座位表上只写名字，不写身高、视力；分组、值日表里不写任何成绩。不做、不公开任何排名。
- 评语只是草稿。 每次生成后都要提醒老师：逐条读一遍、按孩子真实情况改过再用。评语里不写成绩名次、不写家庭情况、不给孩子贴标签；老师写了「懒」「调皮」这类词，评语里只会变成温和的期望，不会出现原话。
- 随机就是随机。 点名、分组的结果以脚本输出为准，不要自己改名单顺序或替老师「挑人」。
- 组件缺了只提示，不自动装。 缺少读写 Excel 的组件时，脚本会告诉老师要运行哪条安装命令，装不装由老师决定。缺少生成 Word 的组件时，评语自动改存为 Excel。
- 跟老师说话用大白话：说「点 3 个人」「每组 6 人」「矮的坐前面」，不念命令和参数名；但老师问起在运行什么，要如实告诉他。
用法
脚本：python {baseDir}/scripts/class_tools.py <子命令> [名单文件] [选项]，位置里有空格要加引号。
名单可以是 .xlsx / .csv / .txt，也可以用 --names "张三 男 152, 李四 女 148, 王五 男 视力" 直接粘贴（逗号或换行隔开，每人后面可带 男/女、身高、「视力」）。
名单里认这些列（看表头名字，标题行会自动跳过）：姓名（必需）、学号、性别、身高、视力/照顾/前排（填「是」或视力数值，5分制低于4.8、小数低于0.8算需要照顾）、小组、评语关键词。重名的同学自动区分成「张伟(12)」（按学号）或「张伟(1)」「张伟(2)」，之后提到他们要用区分后的名字。
| 子命令 | 做什么 | 会写什么文件 |
|---|---|---|
roster 名单 |
看名单读得对不对：多少人、读到哪些列、男女人数、重名 | 不写 |
call 名单 |
随机点名 | 只写本机点名记录 |
group 名单 |
随机分组 | 分组表 xlsx |
seat 名单 --rows 6 --cols 8 |
排座位 | 座位表 xlsx（多周就是多页） |
duty 名单 --start --end |
值日表 | 值日表 xlsx |
exam 老师名单 --dates 或 --start --end |
监考安排 | 监考安排 xlsx |
comment 名单 |
期末评语草稿 | Word（或 Excel） |
holidays --year 2026 |
看内置的法定节假日 | 不写 |
公共选项：--names 粘贴的名单、--sheet 工作表、--title "七年级3班"（表格标题和文件名用它）、--out 保存位置。
随机点名 call
| 选项 | 意思 |
|---|---|
--count 3 |
一次点几个，默认 1 |
--repeat |
可以重复点（默认这一轮点过的不再点，全班点完会提示开新一轮） |
--exclude 张三,李四 |
这次不点（请假、生病） |
--new-round |
开新一轮；旧记录另存为 _1、_2，不删除 |
--status |
只看这一轮点过谁、还剩谁 |
--class 七3班 |
班级名，区分不同班的记录（默认用名单文件名） |
点名记录在「用户文件夹.satloot-class-tools\点名记录_班级名.json」，只存名字和点名时间。名单有变动（转学、新同学）会自动对上，已点过的人照旧算点过。
随机分组 group
--size 6（每组几人）或 --groups 8（分几组），二选一；分不整齐时每组人数差不超过 1。
--balance-gender 每组男女尽量均衡（要有性别列）；--apart 甲,乙,丙 这几个人互不同组；--together 甲,乙 必须同组；这两项都可以写多次。条件互相矛盾或排不出来时会直接说明。
排座位 seat
--rows 几排 --cols 每排几个座位，--desk 2 每桌几人（默认两人一桌，单数列最后一桌单人）。
规则可叠加，优先顺序：--vision 视力需要照顾的坐前排 → --by-height 矮的在前（身高没填的按中间位置算）→ --mixed 男女同桌；其余随机。
--weeks 4 --rotate shift 每周整体向右平移一张桌子（最右一列桌子挪到最左）；--rotate swap 每周左右交换。前后排不变，所以前排照顾不受影响。
最后一排人不满时坐在中间，同桌不拆开。打印：A4 横向、一页宽，讲台在上方，桌子之间留过道。
值日表 duty / 监考表 exam
| 选项 | 意思 |
|---|---|
--start 2026-10-08 --end 2027-01-22 |
起止日期（一次最多一年） |
--per-day 4 |
每天几人（值日默认 2） |
--tasks 扫地,拖地,擦黑板,倒垃圾 |
值日分工，每天人数就等于分工项数，每轮换一次分工 |
--by-group |
按名单里的小组，每天一个组 |
--shuffle |
打乱名单顺序再轮（默认按名单顺序） |
--weekdays 1-5 |
排哪几天，默认周一到周五；也可写「一三五」 |
--skip 2026-11-03~2026-11-05,2026-12-25 |
另外跳过的日子（运动会、考试周、寒假） |
--extra 2026-11-07 |
另外要排的日子（周末补课） |
--no-makeup |
周末调休上课的日子不排（默认排） |
监考：--dates 2027-01-12,2027-01-13 |
直接给考试日期 |
监考：--sessions 上午,下午 --rooms 12 --per-room 2 |
场次、考场（数量或名称）、每考场几位老师 |
节假日：内置 2026 年国务院放假安排（来源见 references/holidays-2026.md），包括 9月20日、10月10日这类周末调休上课日。2027 年国家还没公布，脚本只去掉周末，并在屏幕上和表格里用红字提醒；这时要告诉老师：「2027 年的放假安排还没出来，寒假和元旦、春节放假的日子请告诉我，我帮您跳过」，然后用 --skip 重排。学校自己的寒暑假、运动会也要老师告诉你。
监考：同一场次一位老师只排一个考场，每位老师监考次数相差不超过 1，尽量不让同一位老师一天连监两场、不总和同一个人搭档。
期末评语 comment
关键词来源：名单里的「评语关键词」列（每人 2~4 个，用顿号隔开），或者 --kw "张三：认真、乐于助人、粗心；李四：爱运动、画画"。
--format word（默认）/ excel / both；--full-name 称呼用全名（默认三个字的名字只称呼后两个字，如「小明：」）；--keywords-help 列出句库认识的关键词。
每条评语 = 开头一句 + 每个关键词一句（按品德、学习、劳动、体育、艺术排）+ 最多一句温和的期望 + 结尾寄语。同一句话在全班里尽量少重复，整条评语不重样。
句库在 scripts/comment_bank.py：品德、学习、劳动、体育、艺术、待改进（温和表达）共 224 句，另有开头 12 句、结尾 24 句。关键词对不上句库、只写了缺点、超过 4 个时，脚本会在「需要老师注意」里写明，要原样转告老师。
大白话 → 怎么做
| 老师说 | 怎么做 |
|---|---|
| 「帮我看看名单」「这个表能用吗」 | roster 名单，告诉老师读到多少人、哪些列、有没有重名 |
| 「随机点 3 个人回答问题」 | call 名单 --count 3，念出名字和「这一轮还剩几人没点」 |
| 「点过的别再点了」 | 默认就是；全班点完了，问老师要不要开新一轮，同意后加 --new-round |
| 「可以重复点，王芳今天请假」 | call 名单 --repeat --exclude 王芳 |
| 「这轮都点了谁」 | call 名单 --status |
| 「分成 8 个小组，男女搭配」 | group 名单 --groups 8 --balance-gender |
| 「每组 6 人，张三和李四别分一组，王五要和赵六一组」 | group 名单 --size 6 --apart 张三,李四 --together 王五,赵六 |
| 「排个座位，6 排 8 列，矮的坐前面，近视的往前」 | seat 名单 --rows 6 --cols 8 --by-height --vision |
| 「男女同桌，每周轮换，排一个月」 | 加 --mixed --weeks 4；问老师是整体平移还是左右交换（--rotate shift/swap） |
| 「排一下这学期的值日表，每天 4 个人」 | 问清起止日期，duty 名单 --start … --end … --per-day 4；结束日期在 2027 年就提醒老师标寒假和节日 |
| 「每天一个小组值日」 | duty 名单 --start … --end … --by-group |
| 「值日分扫地、拖地、擦黑板、倒垃圾」 | 加 --tasks 扫地,拖地,擦黑板,倒垃圾 |
| 「运动会 11 月 3 号到 5 号不排」 | 加 --skip 2026-11-03~2026-11-05 |
| 「期末考试 1 月 12、13 号，12 个考场，每场两位老师」 | 用老师名单：exam 老师名单 --dates 2027-01-12,2027-01-13 --rooms 12 --per-room 2；先提醒这两天在 2027 年，放假安排还没公布 |
| 「帮我写期末评语」 | 名单里有关键词列就 comment 名单；没有就请老师给每个孩子说 2~4 个词，用 --kw |
| 「这个孩子很懒、上课总说话」 | 照样写进关键词；评语里会写成「希望你……」这类温和的期望，并提醒老师补一个孩子的优点 |
| 「评语给我 Excel 就行」 | 加 --format excel |
| 「今年国庆怎么放假」 | holidays --year 2026 |
说话方式
- 先一句话说结果（「点到了：王芳、李明」「分好了 8 组，每组 5~6 人，男女都均衡」），再说保存在哪里。
- 学生名字照脚本输出念，不加评价；不要说「这个孩子差」「成绩不好」之类的话。
- 每次生成评语都要说：「这些是草稿，请您逐条看一遍、改成符合孩子实际的话再用。」
- 排班遇到 2027 年的日期，一定转告「放假安排还没公布，需要您标一下」。
需要的组件
- 必须：Python 3.8+、openpyxl（读写 Excel）。缺了脚本会提示
pip install openpyxl，由老师决定是否安装。 - 可选：python-docx（评语存成 Word）。没装就自动存成 Excel，并提示
pip install python-docx。
不做什么
- 不联网、不上传、不调用任何在线服务或大模型接口；评语全部来自内置句库。
- 不修改、不覆盖、不删除老师的任何文件；点名「开新一轮」时旧记录是另存，不是删除。
- 不保存学生信息到任何云端；本机点名记录只有名字和时间。
- 不排名次、不分析成绩、不按成绩分组或排座；不在座位表上写身高视力。
- 不替老师定稿评语，不写成绩名次、家庭情况，不给学生贴标签。
- 不编造 2027 年及以后的放假安排；不处理学校自己的寒暑假，要老师告诉。
- 不读老版本 .xls 和 WPS 的 .et 文件（请另存为 .xlsx），不破解有密码的文件。
- 不写计划任务、不常驻后台、不需要管理员权限、不改任何系统设置。
