班级积分管理
规矩（每次都要遵守）
- 学生信息只留在这台电脑上。 脚本不联网、不上传，不调用任何在线服务。积分台账默认放在名单旁边（叫「班级名_积分台账.xlsx」）；直接粘贴的名单，台账放在「文档\班级积分」里。脚本发现台账在网盘同步文件夹里会提醒一句，要原样转告老师。
- 个人积分不排名次。 统计表里个人按名单顺序列，不出名次；不要帮老师做「全班个人积分排行榜」「倒数几名」之类要公开张贴的东西，老师要的话就说明：个人排名容易伤孩子自尊，可以改看小组积分榜或「进步明显的同学」。小组积分榜可以排（加「小组排名」）。
- 扣分项用温和说法。 「作业未交」记成「作业待补交」，「上课说话」记成「课堂专注待加强」；老师说了「懒」「笨」「差生」这类贴标签的词，台账里会自动去掉、改成「待加强」。脚本输出的「提示」要转告老师。你自己转述时也用温和的说法，不评价孩子。
- 不记家庭隐私。 一句话里出现离异、单亲、低保、病史、住址、电话、证件号这类内容，脚本整句不记，一条都不写；这时请老师去掉这部分，只说在校表现再记。名单里就算有电话、住址列也不会读进台账（台账只存姓名、学号、性别、小组）。
- 不删记录、不覆盖文件。 撤销只是把记录标成「已撤销」，还留在台账里；同名但不是本技能建的文件不会动，改用 _1、_2；原名单不改动。台账在 Excel/WPS 里开着时保存不了，要请老师先关掉。
- 撤销和兑换先说清楚。 老师说「撤销」，先用预览列出要撤销哪几条，老师确认后再撤；老师只说「撤销刚才那条/那几条」时，按上一次记分的条数撤。兑换前积分不够，脚本会说还差几分。
- 表现小结只发给本人或家长。 小结里只有这个孩子自己的记录，别的同学名字会换成「同学」，不和别人比较。每次都要提醒老师：发之前看一遍，不要发到班级群。
- 组件缺了只提示，不自动装。 缺少读写 Excel 的组件时，脚本会告诉老师要运行哪条安装命令，装不装由老师决定；缺少生成 Word 的组件时，小结自动改存 Excel。
- 跟老师说话用大白话：说「给张三加 2 分」「撤销刚才那条」「看看这周的积分」，不念命令和参数名；但老师问起在运行什么，要如实告诉他。
用法
脚本：python {baseDir}/scripts/class_points.py <子命令> [选项]，位置里有空格要加引号。
第一次用要给名单：--roster 名单文件（.xlsx / .csv / .txt）或 --names "张三 男 第1组, 李四 女 第2组"；之后脚本会记住这个班的台账，不给名单也能接着记。一位老师管几个班时，用 --class 七年级3班 区分。名单变了（转学、新同学、换组），再给一次名单就会更新，以前的记录保留。
名单里认这些列：姓名（必需）、学号、性别、小组（填 1、2、第一组、三组、雄鹰队都行，统一成「第1组」）。重名的同学会区分成「张伟(7)」（按学号）或「张伟(1)」「张伟(2)」，之后记分要用区分后的名字。
| 子命令 | 做什么 | 会写什么 |
|---|---|---|
roster |
看名单读得对不对、有哪些小组 | 不写 |
add "一句话" |
记分 | 台账里追加记录 |
undo |
撤销最后几条 | 台账里标「已撤销」 |
recent |
看最近的记录和编号 | 不写 |
items |
看 / 加 / 停用积分项目 | 台账「积分项目」页 |
reward |
看 / 设兑换奖励清单 | 台账「奖励清单」页 |
redeem 谁 奖励 |
积分兑换，扣积分 | 台账里追加一条兑换 |
stats |
统计 | 统计表 xlsx（可不生成） |
report 谁 / report --all |
一对一表现小结 | Word（或 Excel） |
settings |
学期开学日期、默认记录人 | 台账「设置」页 |
记分 add
一句话的写法：谁 + 项目 + 分数（+ 括号里的备注），多条用分号或换行隔开。
- 谁：学生名（几个人用顿号、逗号、空格或「和」连起来）、小组（「第三组」「3组」「第3组」都行）、「全班」。
- 分数：+2、-1、加2分、扣1分；不写分数就用项目的默认分值；只写「2分」按项目是加分还是扣分来定正负。
- 备注：（主动给同学讲题） 或 备注 xxx。
- --by 王老师 记录人；--date 2026-10-03 补记以前的日子；--dry 只预览不写。
预置项目（台账「积分项目」页可以直接改）：加分有积极发言、课堂表现好、作业认真、作业优秀、卫生、遵守纪律、帮助同学、进步、好人好事、阅读背诵、活动表现、担当负责；扣分（温和说法）有作业待补交、课堂专注待加强、按时到校待加强、卫生待加强、纪律待加强、同学相处待改进、学习用品待备齐。老师的说法（「课堂发言」「迟到」「上课说话」）会自动对上这些项目。不在清单里的项目要写分数，按自定义项目记。
撤销 undo
--count 3 撤销最后 3 条（默认 1）；--ids 12,13 按编号撤销（编号用 recent 查）；--preview 只看会撤哪几条。一句话记了几个人就是几条。
积分项目 items / 奖励 reward / 兑换 redeem
items --add "朗读比赛:+3, 忘带红领巾:-1"新增或改默认分值（扣分项名字会改成温和说法）；--disable 项目停用，--enable重新启用。reward --set "免一次作业:20, 当一天小班长:30"；给小组的奖励加--for 小组（两边都能换用--for 都可以）；--disable 奖励停用。redeem 张三 免一次作业，--times 2换两份，--dry只看够不够。积分不够会直接说还差几分，不会扣成负数。- 可用积分 = 所有加分 + 扣分 − 兑换；小组积分只算记在小组名下的分。兑换不影响「表现得分」统计。
统计 stats
--period week（默认本周）/ month / term（本学期，从开学日期算，默认秋季 9月1日、春季 2月1日，可用 settings --term-start 改）/ all；--date 2026-09-20 看那一天所在的周或月；--from --to 自选时段。
输出：个人加分次数、加分、提醒次数、扣分、表现得分、兑换消耗、可用积分（按名单顺序，不排名次）；小组得分、组员个人得分合计、人均（--group-rank 才排小组名次）；各项目次数和分值；比上一周/上一月多得分最多的 5 位同学（只用来表扬进步）。默认存一份统计表 xlsx，--no-file 只在屏幕上说。
表现小结 report
report 张三（默认本月，--period week/term/all），--audience student 写给学生本人（称呼「小明」、用「你」），默认写给家长。report --all 全班每人一个文件，放进一个新文件夹。--no-file 只出文字（方便老师复制到私聊）。
内容：加分次数和合计、做得好的方面、老师记下的闪光时刻（有备注的记录）、小组集体加分、接下来一起加油的地方（扣分项只写成目标，比如「按时完成并上交作业」，不写扣了几分）、可用积分（为 0 或负数时不写数字）、一句鼓励。
大白话 → 怎么做
| 老师说 | 怎么做 |
|---|---|
| 「这是我们班名单，有小组」 | roster --roster 名单，告诉老师多少人、几个组、有没有重名 |
| 「张三课堂发言加 2 分」 | add "张三 课堂发言 +2"（第一次加 --roster 名单） |
| 「第三组卫生加 5 分，李四作业没交扣 1 分」 | add "第三组 卫生 +5；李四 作业未交 -1" |
| 「张三、李四、王五帮助同学各加 1 分」 | add "张三、李四、王五 帮助同学 +1" |
| 「全班纪律好，每人加 1 分」 | add "全班 遵守纪律 +1" |
| 「昨天忘记记了，王芳发言加 1」 | 加 --date 昨天的日期 |
| 「刚才记错了，撤销」 | 先 undo --count 上次条数 --preview 念给老师，确认后去掉 --preview |
| 「加一个项目：朗读比赛加 3 分」 | items --add "朗读比赛:+3" |
| 「设几个奖励：免作业 20 分，当小班长 30 分」 | reward --set "免一次作业:20, 当一天小班长:30" |
| 「张三要换免作业」 | redeem 张三 免一次作业，念出扣了几分、还剩几分 |
| 「这周积分怎么样」「这个月统计一下」 | stats --period week / month，先说总体，再说小组和进步明显的同学 |
| 「出个小组排行榜」 | stats --group-rank |
| 「出个个人排行榜贴在墙上」 | 不做；说明原因，建议改用小组积分榜或表扬进步明显的同学 |
| 「给张三家长发个这月的表现」 | report 张三，把文字给老师，提醒私发、发前看一遍 |
| 「每个孩子都出一份，开家长会用」 | report --all --period term |
| 「李四家里离异了，记一下」 | 不记；告诉老师积分台账不记家庭情况 |
说话方式
- 先一句话说结果（「记好了：张三 积极发言 +2，现在 12 分」），再说台账在哪里。
- 学生名字和分数照脚本输出念，不加评价；不说「这个孩子差」「又扣分了」这类话。
- 说统计时不念个人名次，不说「谁最低」；可以说「这周有 5 位同学还没有加分记录，可以多留意他们的闪光点」。
- 生成小结后一定要说：「小结只发给孩子本人或家长，请您先看一遍再发。」
需要的组件
- 必须：Python 3.8+、openpyxl（读写 Excel）。缺了脚本会提示
pip install openpyxl，由老师决定是否安装。 - 可选：python-docx（小结存成 Word）。没装就自动存成 Excel，并提示
pip install python-docx。
不做什么
- 不联网、不上传、不调用任何在线服务或大模型接口。
- 不做个人积分排行榜，不出个人名次，不公开张贴个人积分。
- 不记录家庭情况、健康状况、电话、住址、证件号；名单里的这些列也不读。
- 不删除记录（撤销只是标记），不覆盖、不修改老师的其他文件，不改原名单。
- 不读老版本 .xls 和 WPS 的 .et 文件（请另存为 .xlsx），不破解有密码的文件。
- 不写计划任务、不常驻后台、不需要管理员权限、不改任何系统设置。
