smartedu-textbook

从国家中小学智慧教育平台（教育部主办）下载中小学电子课本，自动合成 PDF 并按
年级 / 科目 / 版本归档。

既是一个 Claude Code Skill，也是一个可独立运行的命令行工具。

python scripts/download.py --search "苏教版 三年级 数学 上册"

桌面/教材下载/三年级上册/数学/苏教版（江苏凤凰教育出版社）/
    （根据2022年版课程标准修订）义务教育教科书•数学三年级上册.pdf   23.6 MB / 132 页
    info.json

特点

说出书名就能下 —— 内置全量教材检索，覆盖 3085 本（小学 / 初中 / 高中），
不需要打开浏览器复制任何链接
不需要账号 —— 只用平台公开资源，不绕过任何鉴权
自动归档 —— 年级册次 / 科目 / 版本（出版社）三层目录，元数据全部来自官方，无需手工映射
规避旧版陷阱 —— 平台的单本详情接口会返回过期坐标，下到的是旧版教材且不会报错；
本工具只用权威目录源（见下方"实现要点"）
健壮 —— 断点续传、三镜像轮换、JPEG 完整性校验、PDF 自检、并发上限保护

安装

git clone https://github.com/DanielHuang-ning/smartedu-textbook.git
cd smartedu-textbook
pip install -r requirements.txt

需要 Python 3.10+。

作为 Claude Code Skill 使用时，把整个目录放进 ~/.claude/skills/（或项目的
.claude/skills/），之后直接对 Claude 说"下载苏教版三年级数学上册"即可。

使用

下载

# 关键词
python scripts/download.py --search "苏教版 三年级 数学 上册"

# 结构化条件
python scripts/download.py --grade 八年级 --subject 物理 --version 苏科版 --volume 上册

先看有哪些版本

python scripts/download.py --list --grade 三年级 --subject 数学

匹配 14 本：
  …义务教育教科书•数学三年级上册  [小学 · 三年级上册 · 数学 · 苏教版]
  …义务教育教科书 · 数学三年级上册  [小学 · 三年级上册 · 数学 · 人教版]
  …

批量

cat > books.txt <<'EOF'
苏教版 二年级 数学 上册
苏教版 二年级 数学 下册
苏教版 三年级 数学 上册
EOF

python scripts/download.py --batch books.txt

目录里没有的教材（约 15%）

在平台上右键教材封面图 → 复制图片地址：

python scripts/download.py --url "https://r3-ndr.ykt.cbern.com.cn/.../transcode/image/1.jpg"

选项

选项	默认	说明
`--out <目录>`	桌面/教材下载	输出根目录
`--jobs N`	8	并发数，上限 16
`--slow`	关	弱网模式，降低请求频率
`--compress`	关	压缩 PDF（体积约 1/3，画质略降）
`--keep-pages`	关	保留单页图片
`--force`	关	已存在时重新下载
`--refresh`	关	强制刷新目录缓存
`--yes`	关	非交互模式（条件不唯一时直接报错而非等待选择）

⚠️ 请核对版次

2024–2025 年是义务教育教材按 2022 年版新课标换版的窗口，新旧版单元结构差异很大。

下载后请翻到 PDF 的版权页（通常第 3–5 页）核对「版次」。
新版教材书名带「（根据2022年版课程标准修订）」前缀。

实现要点

平台有三处可拿教材信息，质量差别很大

数据源	状态
`.../zxx/ndrs/tch_material/version/data_version.json`	403。网上多数教程用的是这个路径，少了 `resources/`，因而普遍认为接口已下线
`.../resources/tch_material/details/{id}.json`	可用，但数据过期：返回 2023 年的旧版坐标，`provider_list` 还是平台方而非出版社
`.../resources/tch_material/version/data_version.json` → `part_*.json`	本工具使用的源。权威、最新，3637 条完整元数据

旧版坐标为什么危险

同一本三年级数学，两个来源给出不同 timestamp：

timestamp 来源	第 1 页	第 50 页	第 132 页
详情接口（≈2023-07）	✅	✅	❌ 403
目录分片（≈2025-08）	✅	✅	✅

用旧坐标能下载、能合成、页数看着也正常——只有翻到版权页才会发现是旧版教材。
所以本工具代码里不给详情接口留调用入口。

为什么走图片而不是整本 PDF

平台把资源分成两类，鉴权规则不同：

资源	状态
整本 PDF `.pkg/pdf.pdf`	403，需登录 Token
单页图 `.t/zh-CN/{ts}/transcode/image/{n}.jpg`	200，公开

本工具只走公开的图片通道，抓单页后本地合成 PDF。内容完全一致，
代价是稍慢，好处是不需要用户交出任何账号凭据。

其它

页数探测用倍增 + 二分，约 12–16 次请求；平台对不存在的页返回 403 而非 404，
而限流同样是 403，因此判定末页前会二次确认，避免把限流误判成"下完了"
PDF 合成默认 img2pdf：原样嵌入 JPEG，无损，画质等同原件。
实测同一册 118 页，img2pdf 62.6 MB、Pillow 重编码 19.9 MB——
无损版体积约为压缩版 3 倍，需要小文件时加 --compress。
Pillow 路径采用惰性打开、不预先 convert()，否则一册 130 页全部解码约 1 GB
Windows 桌面路径读注册表而非拼 %USERPROFILE%\Desktop，
否则 OneDrive 重定向后会写到用户看不到的地方

已知限制

约 15% 的教材目录中无预览坐标，需用 --url 回退
高中教材命名不如义务教育规整，检索可能需要人工确认
平台偶发限流，弱网建议 --jobs 4 --slow
只下载电子课本，不下载教师用书、课件、音视频

免责声明

本工具仅访问国家中小学智慧教育平台公开提供的电子教材资源，
不破解、不绕过任何鉴权机制，也不实现需要登录的下载通道
教材版权归各出版社所有。下载内容仅供个人教学、学习使用
禁止将本工具用于商业用途，禁止二次分发下载得到的教材文件，禁止规模化爬取
工具内置并发上限与速率控制，且不提供解除开关
平台接口随时可能变更或关闭，本工具不保证长期可用
使用者须自行遵守当地法律法规及平台服务条款，作者不承担因使用本工具产生的任何责任

License

代码部分采用 MIT License。

License 仅覆盖本仓库的代码，不涉及通过本工具获取的任何教材内容。