小学口算出题与错题本
这个技能做什么、不做什么
- 出题：按人教版一到六年级、上册/下册的计算单元出口算题。可选题数、难度（1 基础 / 2 标准 / 3 提高）、题型（口算、填空、比大小、竖式、应用题、混合）。
- 保证：不出负数（中间步骤也不出）；整数阶段的除法要么整除，要么就是「有余数的除法」单元的题；小数除法只出除得尽的；不超出所选年级学期学过的内容。
- 出卷：可打印的 A4 PNG 或 PDF，最后一页是答案页。需要 Pillow（
pip install pillow），没装会提示；不出卷时只用标准库。 - 错题本：家长录入孩子的答案 → 自动批改 → 统计错误类型（进位错、退位错、口诀错、运算顺序错、小数点错……）→ 按错误类型再出一组针对性练习；孩子做对了自动销账。数据按孩子昵称分文件存在本机 JSON。
- 不做：不联网，不拍照识别孩子手写答案（家长把答案打成文字），不收集任何个人信息（只记昵称，不要填真实姓名、学校、年龄）。
- 答案一律以脚本输出为准，不要自己心算后改动脚本给的答案。
使用流程
所有命令：python {baseDir}/scripts/drill.py <命令> ...
- 看知识点列表（代号、中文名、对应人教版单元）：
`` python {baseDir}/scripts/drill.py topics ``
- 出题。用户说「二年级上册，出 30 道口算」就是：
`` python {baseDir}/scripts/drill.py gen --grade 2 --term 上 --n 30 python {baseDir}/scripts/drill.py gen --grade 1 --term 上 --topics 凑十法 --n 20 --level 1 python {baseDir}/scripts/drill.py gen --grade 3 --term 上 --type mix --n 30 --out 练习卷.pdf python {baseDir}/scripts/drill.py gen --kid 豆豆 --grade 2 --term 上 --n 20 --out 豆豆.png --no-answers ``
| 参数 | 说明 | |---|---| | --grade / --term | 年级 1-6（也可写「二」）；学期 上/下 | | --topics | 知识点代号或中文名，逗号分隔；不写就是本学期全部计算单元。超纲的会被拒绝 | | --n | 题数（默认 20，最多 200） | | --level | 1 基础 / 2 标准（默认）/ 3 提高 | | --type | oral 口算（默认）/ fill 填空 / compare 比大小 / vertical 竖式 / word 应用题 / mix 混合 | | --out | xxx.png（每页一张，答案页单独一张）或 xxx.pdf（一个文件） | | --kid | 孩子昵称：把卷子存进这个孩子的错题本，返回卷号，批改时用 | | --seed | 随机种子，同样参数同样种子出同一套题 | | --no-answers | 屏幕上不显示答案（答案仍在 PDF/PNG 最后一页） |
某个知识点不支持某种题型时（比如比大小不适用于有余数除法），这道题自动改成口算。
- 批改。孩子做完，家长按题号把答案打出来（逗号分隔；余数写
7……2、7余2都行；分数写3/4、带分数写1又1/2；比大小写><=；应用题只写得数，单位写不写都行）：
`` python {baseDir}/scripts/drill.py grade --kid 豆豆 --answers "83, 56, 9……2, >, 3/4" python {baseDir}/scripts/drill.py grade --kid 豆豆 --sheet 0923-01 --answers-file 答案.txt ``
不写 --sheet 就批改最近一张。空着的答案算「未作答」。
- 看统计、再练一组：
`` python {baseDir}/scripts/drill.py report --kid 豆豆 python {baseDir}/scripts/drill.py retry --kid 豆豆 --n 10 --out 再练.pdf ``
retry 按错题本里还没改正的错误类型出题：进位错 → 专出要进位的加法；口诀错 → 只练错过的那几句口诀；运算顺序错 → 混合运算；小数点错 → 小数乘除……做对后对应错题自动标记「已改正」。
- 不存档的临时批改、验算（适合用户直接在对话里贴题目）：
`` python {baseDir}/scripts/drill.py check --problems "38 + 45 = 7 × 8 =" --answers "73, 56" python {baseDir}/scripts/drill.py verify --problems "23 × 4 = 3/4 + 1/6 =" ``
verify 给出每道题的程序答案，并提示题目里有没有负数。题目写法：× ÷ 或 * /（/ 表示分数线），填空用 □ 或 ( )，比大小用 ○，比写 化简比：12 : 18 / 求比值：12 : 18，解比例写 解比例：x : 4 = 6 : 8。
其它：kids 列出本机有哪些错题本；forget --kid 豆豆 --yes 删除某个孩子的错题本文件；render --kid 豆豆 --sheet 0923-01 --out a.pdf 把旧卷子重新出成文件。错题本目录默认 ~/.satloot-kids-math/，可用 --data 或环境变量 KIDS_MATH_DATA 改。
各年级出题范围（人教版 2012 版 2014 修订本的计算单元）
| 年级学期 | 默认知识点 | 规则 | |---|---|---| | 一上 | 10以内加减法；20以内进位加法（凑十法） | 只有加减，数不超过 20 | | 一下 | 20以内退位减法（破十法）；两位数加减一位数、整十数 | 只有加减，不超过 100 | | 二上 | 两位数加减两位数（进位、退位、连加连减）；表内乘法 | 乘法只出九九表 | | 二下 | 表内除法；有余数的除法；两步混合运算（含括号） | 除数、商都不超过 9；余数小于除数 | | 三上 | 多位数乘一位数（两位数乘一位数为主）；有余数的除法（复习）；万以内加减法；可选：同分母分数加减 | 乘法有一个因数是一位数；分数只出分母相同、≤10、结果不用约分 | | 三下 | 除数是一位数的除法（含商中间有 0、有余数）；两位数乘两位数；一位小数加减 | 小数只有一位 | | 四上 | 三位数乘两位数；除数是两位数的除法 | 被除数不超过三位数 | | 四下 | 四则混合运算；简便运算（凑整、乘法分配律、25×4、125×8 等）；小数加减法 | 所有中间结果都是非负整数 | | 五上 | 小数乘法；小数除法（含「除到末尾补 0」） | 商必定除得尽，最多 3 位小数 | | 五下 | 分数加减法（同分母、异分母、三个数） | 结果化成最简分数 | | 六上 | 分数乘法、分数除法；比（化简比、求比值）；百分数（互化、求一个数的百分之几） | 化简比要最简整数比 | | 六下 | 百分数应用（折扣、成数、税率、利率）；解比例；分数乘除复习 | 「负数」单元不出题 |
说明：人教版把「有余数的除法」放在二年级下册，三年级上册只作复习；三年级的「两位数乘一位数」在「多位数乘一位数」单元里。2024 年起一、二年级陆续换用新版教材，单元顺序略有调整，但计算内容和范围基本一致；想只练某一项时用 --topics 指定即可。
错误类型（批改时自动识别）
| 类型 | 怎么认出来的 | 再练什么 | |---|---|---| | 进位错 | 答案正好是「不进位」的结果，或少了 10、100 | 必须进位的加法 / 乘法 | | 退位错 | 答案是「大数减小数」逐位硬减的结果，或多了 10 | 必须退位的减法 | | 口诀错 | 表内乘除算错，提示给出正确口诀 | 只练错过的那几张表 | | 运算顺序错 | 答案等于「从左往右硬算」或「不管括号」的结果 | 混合运算 | | 看错符号 | 答案是用别的运算算出来的 | 同一知识点 | | 小数点错 / 漏写0或多写0 | 答案差 10、100、1000 倍 | 小数乘除 / 末尾有 0 的乘法 | | 未约分 / 通分错 / 分数乘除错 | 分数没化简、分子分母直接相加、除法没乘倒数 | 分数运算 | | 余数错 / 试商错 / 商中漏0 | 余数不小于除数或漏写、商差 1、商中间的 0 丢了 | 除法 | | 比大小错 / 填空逆推错 / 列式错 | 对应题型答错 | 同知识点、同题型 | | 比和比值混淆 / 化简比错 / 百分数换算错 | 化简比写成了数、没化到最简、差 100 倍 | 比、百分数 | | 计算错 | 以上都不像 | 同一知识点 |
识别是按常见错法推断的，不一定每次都准；批改对错本身是精确的。
在腾讯元器代码节点里用
scripts/drill.py 是单文件，出题、批改只用标准库，整段粘进 Python 代码节点即可（出 PNG/PDF 在代码节点里用不了，也不需要）：
def main(params: dict) -> dict
# action: gen（出题）/ check（批改）/ verify（验算）/ retry（按错误类型出题）/ topics
# gen: grade, term, topics, n, level, qtype, seed
# check: problems（每行一道，应用题写「题目 || 算式」）, answers（逗号分隔）, grade
# verify: problems（可带 answers：核对模型给的答案）
# retry: grade, term, errors（如 {"进位错": 2, "口诀错": 1}）, n
# 返回: status / text（给用户看的全文）/ problems 或 results / errors代码节点是无状态的，不存错题本；错题本功能只在本机命令行版里有。
自测
python {baseDir}/scripts/selftest.py覆盖：12 个学期 × 全部知识点 × 3 档难度 × 5 种题型，共 12000 道题，每道题的答案由生成器直接算和批改器重新解析题面算两条路核对一致（填空代回去、比大小两边分别算、余数按定义验）；用一张独立的年级规则表逐题检查不超纲、无负数、除得尽；标准答案交给批改器必须判对；错误类型样例；错题本全流程（临时目录）；代码节点入口；PNG/PDF 出卷。
边界
- 应用题是固定模板套数字（分苹果、坐船、买东西、折扣利息等），题面比较朴素，不是课本原题。
- 竖式题只把竖式框架画好，孩子自己写过程；批改只看最后得数，不检查竖式过程。
- 错误类型是推断，孩子的真实想法要家长结合草稿看。
- 默认按人教版；北师大版、苏教版单元顺序不同，可以用
--topics自己挑知识点。