智慧教育教材下载技能

概述

此技能封装了 tchMaterial-parser 的核心解析与下载逻辑，让 AI 助手能够直接帮助用户从「国家中小学智慧教育平台」下载电子课本 PDF。

核心原则：用户提供 URL，助手负责解析和下载。不主动代用户搜索教材名称（平台没有公开搜索引擎，必须用 URL）。

---

⚠️ 前置步骤：如何获取课本 URL（用户必读）

下载教材需要课本的「预览页网址」，获取步骤如下：

1. 打开浏览器，访问 国家中小学智慧教育平台
2. 登录账号（右上角点击登录，无账号需先注册）
3. 在教材栏目中按「学段 → 学科 → 出版社 → 年级」逐级筛选
4. 点击目标课本进入预览页面
5. 复制浏览器地址栏的完整 URL（格式如 https://basic.smartedu.cn/tchMaterial/detail?contentType=...）
6. 将 URL 粘贴给我即可

---

触发场景

当用户提到以下关键词组合时激活此技能：

• 「下载电子课本」+「URL」
• 直接粘贴 https://basic.smartedu.cn/tchMaterial/detail?... 格式的链接
• 「帮我下载这本教材」
• 「下载国家中小学智慧教育平台的课本」

工作流程

决策入口：用户是否提供了 URL？

情况 A：用户提供了 URL → 直接进入「标准下载流程」

情况 B：用户只说"下载某某教材"但无 URL → 不要尝试代用户搜索。按以下模板回复：

📚 要下载教材，需要你先在国家中小学智慧教育平台找到对应课本，把网址给我。

请按以下步骤操作：

1️⃣ 打开浏览器，访问 https://basic.smartedu.cn/tchMaterial
2️⃣ 登录你的账号（右上角登录，无账号需先注册）
3️⃣ 按「学段 → 学科 → 出版社 → 年级」筛选找到你要的课本
4️⃣ 点击课本进入预览页
5️⃣ 复制浏览器地址栏的完整网址（以 https://basic.smartedu.cn/tchMaterial/detail? 开头）
6️⃣ 把网址粘贴给我，我帮你下载！

> 💡 提示：如果想看看平台上都有哪些教材，我可以帮你拉取教材目录。

如果用户说「帮我看看有哪些教材」→ 执行 python scripts/tchMaterial_downloader.py browse 拉取目录树。

标准下载流程

1. 创建工作文件夹

   • 先为当前下载任务创建独立文件夹（如 教材下载_20260629/）

2. 执行下载

   python tchMaterial-skill/scripts/tchMaterial_downloader.py download "<URL>" -o "教材下载_日期/教材名称.pdf"
   

   • 脚本自动解析 URL，获取 PDF 下载链接，保存到工作空间
   • 默认以教材名称命名 PDF 文件
   • 默认添加 PDF 书签（可用 --no-bookmarks 禁用）

3. 重命名文件（如有必要）

   • 下载完成后，如果文件名不够直观，用脚本输出的教材标题重命名
   • 调用 open_preview 预览确认

4. 报告结果

   • 告知用户：教材名称、文件大小、保存路径

Token 管理流程

平台对登录用户提供更稳定的下载链接。未登录也可下载但稳定性较差。

获取 Token 的方法（引导用户在浏览器执行）：

1. 打开 https://auth.smartedu.cn/uias/login 登录账号
2. 按 F12 打开开发者工具 → 控制台（Console）
3. 粘贴以下代码并回车：

(function () {
  const authKey = Object.keys(localStorage).find((key) =>
    key.startsWith("ND_UC_AUTH"),
  );
  if (!authKey) {
    console.error("未找到 Access Token，请确保已登录！");
    return;
  }
  const tokenData = JSON.parse(localStorage.getItem(authKey));
  const accessToken = JSON.parse(tokenData.value).access_token;
  console.log(
    "%cAccess Token:",
    "color: green; font-weight: bold",
    accessToken,
  );
})();

4. 复制控制台输出的 Access Token

Token 使用：

• 用户首次使用时引导获取
• 获取后在当前会话中缓存（用 memory 工具记下）
• Token 过期（7天）时提醒用户重新获取

浏览教材目录（可选）

python scripts/tchMaterial_downloader.py browse [--token TOKEN]

• 拉取平台教材分层目录（学段 → 学科 → 出版社 → 年级 → 具体课本）
• 输出树形结构，辅助用户确认教材

仅解析 URL（不下载）

python scripts/tchMaterial_downloader.py parse "<URL>" [--token TOKEN]

• 输出 JSON 格式的教材名和下载链接
• 用于用户只想获取链接而不下载的场景

重要约束

1. 不代用户搜索教材名称：平台不提供公开搜索引擎，AI 无法通过教材名称搜索。用户必须提供 URL
2. 不存储 Token：Token 仅在用户主动提供时使用，不在工作空间持久化存储
3. 版权意识：下载的教材仅限个人学习使用，不得分发
4. 网络依赖：下载依赖 ykt.cbern.com.cn 系列域名的可达性

依赖

• Python 3.10+
• 依赖库：requests、pypdf（首次运行脚本前用 pip install -r requirements.txt 安装）

故障排查