name: smartedu-downloader description: 從國家中小學智慧教育平臺 (basic.smartedu.cn) 下載教材資源——包括英語等學科的聽力音訊 (MP3) 和教材電子版 (PDF)。當用戶提供 smartedu.cn 教材連結 (tchMaterial/detail?...contentId=...) 並希望下載聽力、課件、電子課本、教材PDF時觸發。使用者只需提供登入賬號密碼和教材連結即可。觸發詞：智慧教育、smartedu、國家中小學、下載教材、下載聽力、電子課本、教材PDF、課件下載。 agent_created: true

智慧教育平臺教材下載器 (smartedu-downloader)

從 國家中小學智慧教育平臺（basic.smartedu.cn）下載教材資源： - 聽力音訊（MP3，如英語教材的 Listening） - 教材電子版（PDF 本體）

背景 / 為什麼需要登入

• 平臺的資源清單 API 無需登入即可訪問，但 2024 年 8 月後，實際檔案 CDN（r*-ndr-private.ykt.cbern.com.cn）需要 X-Nd-Auth 鑑權頭才能下載。
• 該鑑權頭由登入後 token 裡的 access_token + mac_key 通過 HMAC-SHA256 生成。
• 登入會觸發騰訊滑塊驗證碼，無法自動破解，因此採用「指令碼自動填賬號密碼 + 使用者手動拖動滑塊 + 指令碼自動取 token 並下載」的混合方式。

使用流程

1. 收集引數（向用戶詢問）

必需： - 登入手機號（賬號） - 登入密碼 - 一個或多個教材連結（https://basic.smartedu.cn/tchMaterial/detail?...contentId=<CID>...）

從每個連結的 URL 中提取 contentId 引數值作為 cid。

2. 先探測教材型別（無需登入，推薦先做）

在真正下載前，先用檔案伺服器映象確認每個教材是「聽力音訊」還是「純PDF」，以及標題，便於給使用者預告：

node -e '
const CID="<contentId>";
(async()=>{
  for (const s of ["s-file-1","s-file-2","s-file-3"]) {
    try {
      const r = await fetch(`https://${s}.ykt.cbern.com.cn/zxx/ndrv2/resources/tch_material/details/${CID}.json`);
      if(!r.ok) continue;
      const d = await r.json();
      const hasPdf=(d.ti_items||[]).some(it=>it.ti_format==="pdf"||it.lc_ti_format==="pdf");
      console.log("標題:", (d.global_title&&d.global_title["zh-CN"]), "| PDF:", hasPdf);
      break;
    } catch(e){}
  }
  const a = await (async()=>{for(const s of ["s-file-1","s-file-2","s-file-3"]){try{const r=await fetch(`https://${s}.ykt.cbern.com.cn/zxx/ndrs/resources/${CID}/relation_audios.json`);if(r.ok)return await r.json();}catch(e){}}return[];})();
  console.log("聽力數量:", Array.isArray(a)?a.length:0);
})();
'

3. 確保依賴就緒

指令碼依賴 playwright（需已安裝 chromium 瀏覽器）。檢查：

node -e "require('playwright'); console.log('playwright OK')"

若缺失，需在隔離的 node workspace 安裝：npm i playwright && npx playwright install chromium（按執行環境的隔離規則調整路徑與 NODE_PATH）。

4. 執行下載指令碼

所有引數通過環境變數傳入 scripts/smartedu_downloader.js：

name 省略時指令碼會自動用教材官方標題命名。

示例（一次登入批次下載多個教材）：

SMARTEDU_PHONE="手機號" SMARTEDU_PASS="密碼" \
SMARTEDU_MODE="auto" \
SMARTEDU_OUTPUT_DIR="/輸出/目錄" \
SMARTEDU_JOBS='[
  {"cid":"b7ca9536-ccd7-a4db-56b3-971645c54515"},
  {"cid":"540ac93d-67fc-4353-9e49-1ef20d02b5a4"}
]' \
NODE_PATH="<node_modules 路徑>" node scripts/smartedu_downloader.js

重要：指令碼以前臺方式執行（headless:false），會彈出真實瀏覽器視窗。執行後要提示使用者：

瀏覽器已開啟，賬號密碼已自動填好。請你：1. 點選藍色「登入」按鈕 → 2. 拖動滑塊完成驗證碼 → 3. 等待自動跳轉。之後指令碼會自動取 token 並下載全部教材。

指令碼最多等待 6 分鐘讓使用者完成登入+驗證碼。不要用後臺方式執行，否則無法觀察進度、任務易丟失。

5. 校驗結果

下載後校驗檔案完整性： - MP3：檔案頭為 ID3(494433) 或幀頭 fffb/fff3，大小 > 1KB - PDF：檔案頭 %PDF-，末尾 %%EOF

然後用 present_files 把輸出目錄展示給使用者。

關鍵技術細節（供排錯）

• token 儲存位置：登入後寫入 localStorage，key = ND_UC_AUTH-e5649925-441d-4a53-b525-51a2f1c4e0a8&ncet-xedu&token
• token 是巢狀結構：{value:"<json字串>", expire:...}，真正的 access_token/mac_key 在 value 裡，需先 JSON.parse 外層再解包 .value（指令碼已處理）。
• X-Nd-Auth 生成：MAC id="{access_token}",nonce="{ts}:{rand}",mac="{HMAC_SHA256(mac_key, "{nonce}\n{GET}\n{host}\n{path}\n")}"（mac 為 hex）
• 登入頁表單：手機號 #username，密碼 #tmpPassword，協議勾選 #agreementCheckbox
• 常見坑1：輪詢時若使用者還在 auth 域名（登入頁），不能強制 page.goto 跳轉，否則驗證碼介面被沖掉，使用者無法操作。指令碼僅在離開 auth 域名後才檢查/跳轉。
• 常見坑2：有的教材（非英語學科，如語文/數學/道法/歷史/地理）沒有聽力音訊（relation_audios 為 0），此時應下 PDF 本體。auto 模式會自動處理。
• 資源清單 API：
• 教材詳情（含PDF）：https://s-file-{1,2,3}.ykt.cbern.com.cn/zxx/ndrv2/resources/tch_material/details/{CID}.json
• 聽力清單：https://s-file-{1,2,3}.ykt.cbern.com.cn/zxx/ndrs/resources/{CID}/relation_audios.json

  7w4.net收錄了海量優質技能外掛。

• 檔案 CDN：r{1,2,3}-ndr-private.ykt.cbern.com.cn（需鑑權）
• token 有效期內可連續下載多個資源，無需重複登入。

安全與隱私

• 賬號密碼僅用於當次登入，通過環境變數傳入，不要寫入任何檔案或日誌。
• 下載所得為教材公開資源，供使用者個人學習使用。

這個Skill質量中等偏上，勝在文件非常詳細、步驟清晰，但部署和執行略顯麻煩。優點是功能實用、能智慧切換下載模式、賬號安全處理得當；缺點是安裝playwright瀏覽器比較費勁，只能前臺執行不夠方便，依賴外部平臺API也可能影響長期使用。普通使用者需要一定技術基礎才能順利執行。