批量下载中小学电子课本并加书签（tchMaterial-parser）

国家中小学智慧教育平台的电子课本放在网页预览页里，一册一册点开再逐个保存，成套备课资料下载下来要花不少工夫。tchMaterial-parser 处理的就是从预览页网址到本地 PDF 这一段路，把解析、命名、书签这几件事一并做完。

tchMaterial-parser 是 Python 写的桌面工具，把国家中小学智慧教育平台的电子课本预览页网址批量解析成 PDF 下载到本地，供教师备课和家长取用。

它面向需要成套保存课本 PDF 的人。输入是一行一条的电子课本预览页网址，输出是保存在选定目录下、按课本名称命名的 PDF 文件。仓库用 Python 写成，语言占比 100%，许可证是 MIT。抓取时仓库有 7083 star、890 fork、57 watcher，开放 Issue 8 个；项目创建于 2023-08-10，最近一次提交在 2026-10-07，版本已发布到 v4.4。

v4.0 是一次大改版，仓库把它描述为不再只面向电子课本下载：主界面与资源浏览体验重做，可解析的资源类型做了扩展，发行包补齐了更多平台和处理器架构。此后 v4.1 到 v4.4 接连补上私有资源下载、批量勾选与下载管理。

它不做什么

运行环境上，这个工具需要图形界面，没有桌面的服务器跑不起来。README 的跨平台支持一条后面就跟着「需要图形界面」。

内容层面，它只提供下载上的便利，不存储、不托管、不分发任何资源内容，所有资源直接来自国家中小学智慧教育平台。资源版权归原平台及相关权利人所有，README 要求仅用于个人学习与教学参考，不要用于商业用途或二次分发。

视频不在范围内。Issue 列表里有用户问「将来会更新下载视频功能吗？」，这条目前是待解决状态，仓库没有提供课程视频下载能力。

不设置 Access Token 也能用，工具会改用其他方法下载资源，README 说明这一方法并不长期有效，官方仍然建议配置。

Token 持久化只在 Windows、Linux、macOS 三个平台成立。其他操作系统目前不支持持久化，仓库表示正在寻找通用的解决方案。

项目与国家中小学智慧教育平台没有任何隶属或合作关系。

用之前先准备好什么

系统与架构方面，GitHub Releases 提供适用于 Windows 10（Server 2019）及以上、Linux、macOS 10.15 及以上的 x86_64 与 Arm64 包。想跑源码需要 Python 3.10+。

输入数据是要下载的电子课本预览页网址，一条一行。

可选但建议的一步是获取 Access Token：先登录国家中小学智慧教育平台账号，再用应用内提供的脚本从浏览器控制台取出凭据。v4.2 起，「设置 Token」必须粘贴包含 access_token、mac_key、diff 的整段 JSON，不再接受单独的 Access Token 字符串。

macOS 上还有一道手工程序。应用没有签名，系统会报告文件已损坏，需要先执行 xattr -cr /path/to/tchMaterial-parser.app 移除隔离属性；为了让 Access Token 能持久化，建议把应用移动到 /Applications 目录下再运行。

网络要能正常访问平台。部分旧资源可能已被移除，这类网址会解析失败。

主要功能

• 批量解析与下载：一次输入多个预览页网址，工具自动解析并批量下载。选定目录里已下载完成的同名课本会被自动跳过，重新下载整套课本时只补齐缺失与上次失败的文件。下载过程可以随时点「停止下载」，已完成的文件保留，未下载完的文件不会留下残缺内容。
• 下载管理（v4.4 新增）：逐项显示资源名称、状态、进度、文件大小与下载速度，支持搜索，也能按「进行中 / 需处理 / 已完成」筛选。列表显示排队、连接、下载、写入书签与完成状态；服务器未提供文件大小时显示已接收的数据量。关闭管理窗口后，下载仍在继续。
• 自动命名与书签：默认文件名取自电子课本名称。开启「设置 PDF 书签」后，下载完成会为 PDF 添加书签，在阅读器里可以快速跳转到指定位置。
• Access Token 支持：手动输入并自动保存，下次启动自动加载。应用内提供「如何获取？」引导，支持一键打开登录页面与一键复制获取脚本。
• 资源浏览与搜索：v4.0 起用资源树替代多级下拉菜单，可按资源名称或「学段、学科、年级」等完整分类路径组合筛选，Ctrl+F 或 ⌘+F 可快速聚焦搜索框，结果自动展开，封面有缩略图和悬停大图预览。
• 勾选与链接同步（v4.3）：资源列表新增复选框，可单独选择或按分类批量勾选、取消勾选，列表显示已选总数，空格键能切换勾选。勾选状态与链接输入框双向同步，手动粘贴、删除或撤销链接编辑时也会更新勾选。
• 失败处理与重试：下载与解析错误统一在任务列表中展示，可查看、复制错误详情或打开保存文件夹。当前下载结束后，可对失败或已停止的任务「重新下载」，也能一键「重试失败项」，解析失败的页面可单独「重新解析」。重新下载从头开始。
• 界面适配：支持深色模式，启动时跟随系统的浅色或深色设置，也可手动切换并记住；针对高分辨率屏幕做了优化，避免界面模糊。

安装与最短示例

最省事的路径是从 GitHub Releases 页面下载对应平台的包，解压后不需要额外的安装步骤，Windows 与 Linux 可直接运行。

Windows 10、11 与 Windows Server 2025 可以用 WinGet 安装：

winget install happycola233.tchMaterial-parser

Arch Linux 走 AUR：

yay -S tchmaterial-parser

macOS 首次运行前先处理隔离属性：

xattr -cr /path/to/tchMaterial-parser.app

从源码运行需要 Python 3.10+，具体步骤写在仓库的 CONTRIBUTING.md 本地开发一节，README 里没有重复列出。

打开程序后最短的流程是把预览页网址粘贴进文本框，每行一条，然后点「下载」：

https://basic.smartedu.cn/tchMaterial/detail?contentType=assets_document&contentId=XXXXXX&catalogType=tchMaterial&subCatalog=tchMaterial

想配置 Token，就在浏览器里登录平台账号，按 F12 打开控制台粘贴应用提供的脚本，复制输出的整段 JSON，再回到工具点「设置 Token」粘贴保存。粘贴时要注意三点：先登录再粘代码；粘到「>」后面而不是「过滤」或「筛选器」上；遇到警告先输入「允许粘贴」四个字再重试。

关键参数

这个工具的配置项不多，集中在登录凭据和书签开关上。

• access_token、mac_key、diff：v4.2 起登录凭据由这三项组成一段 JSON。若仍使用旧版只保存 Access Token 的配置，部分私有资源可能继续返回 400。
• Token 有效期：常见问题里写「一般为 7 天」，过期后重新获取新的 Token 即可。
• Token 存储位置：Windows 存在注册表 HKEY_CURRENT_USER\Software chMaterial-parser 项的 AccessToken 值里；Linux 存在 ~/.config/tchMaterial-parser/data.json；macOS 存在 ~/Library/Application Support/tchMaterial-parser/data.json。
• 「设置 PDF 书签」：开关项，开启后在下载完成后为课本补书签。
• 输入格式：每行一个预览页网址，没有其他分隔符。

仓库里没有说明命令行参数，日常操作都在图形界面里完成。

结果在哪里看

课本 PDF 落在开始下载前选定的目录里，文件名是课本名称，同名文件已存在时会被跳过。

下载管理窗口会在开始下载时打开，也能从主界面底部随时进入。每个任务的排队、连接、下载、写入书签与完成状态都在这里，还有进度、文件大小与速度。搜索框和「进行中 / 需处理 / 已完成」筛选在同一窗口里。

出错时到「需处理」里选中任务，可以查看和复制错误详情，也可以直接打开保存文件夹，不会弹出很长的批量错误提示。

任务记录只保留到退出程序，「清除已完成记录」清的是列表，不会删除已经下载的文件。

实际使用中的坑

Issue 列表里出现最多的是下载失效，多数已经在后续版本里修掉，这些记录能说明哪些环节容易出问题。

• 点保存没反应：有用户反馈保存对话框弹出来了，点保存后没有任何动作，这条已解决。
• Token 正确仍无法下载：写入 Access Token 后依然下不动，已解决。v4.2 的说明也提到旧格式配置会让部分私有资源继续返回 400，需要按整段 JSON 重新设置。
• 卡在「等待下载」：有用户遇到进度一直停在等待下载，改用「解析并复制」再放进 IDM 手动下载，拿到的却是 error.html，这条已解决。
• 下载的 PDF 打不开：已解决，作者在后续版本里处理了这一问题。
• macOS 提示文件损坏：有用户安装后遇到文件损坏或不完整的提示，对应的是签名与隔离属性，处理办法就是 README 给出的 xattr -cr，这条已解决。

还有两条处于待解决状态的需求：手机端，以及下载课程视频。

同类工具横向对照

这两个对比项都只是同一赛道里的参照，解决的问题并不重合。真正要在取舍上做判断，是当下载任务需要无图形界面、能被脚本调用时：tchMaterial-parser 的操作全在图形界面里，仓库没有提供命令行入口，这种场景下它不如 yt-dlp 这类命令行工具顺手，你只能改成人工点选，或者自己按源码改一套调用逻辑。反过来，如果目标就是那一个平台的电子课本，需要在浏览器之外直接拿到 PDF 和书签，yt-dlp 帮不上忙。

合规与授权边界

这个工具的用途是从国家中小学智慧教育平台获取文件，只应用于自己有权访问的资源，以及已经获得授权的目标。

平台的服务条款对抓取和批量下载有约束，电子课本的著作权归原平台及相关权利人。绕开平台正常使用方式批量获取文件，再拿去二次分发或用于商业用途，会同时触碰平台条款与著作权两条线，产生的后果由使用者承担。

README 的免责声明写得很直接：工具只提供下载上的便利，不存储、不托管、不分发任何资源内容，所有资源直接来自国家中小学智慧教育平台，项目与该平台没有任何隶属或合作关系。Access Token 属于账号凭据，工具不会上传也不存云端，仅用于本地请求授权，请不要在公开场合分享，泄露等同于把账号交给别人。

适合谁

需要成套保存中小学电子课本 PDF 的教师、家长，以及按学段学科批量整理教材的人，用 Windows、Linux 或 macOS 桌面都能跑，愿意花几分钟配一次 Access Token 的流程更稳。

把下载放进脚本或定时任务的人不适合选它，这个工具依赖图形界面，仓库里也没有命令行入口。想批量下载课程视频的人同样不适合，仓库目前没有这个能力。只需要偶尔取一两册课本的话，手动保存也够用。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.1 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。