前言¶
在 DeepSeek Harness（DSH）裏做課程相關的自動化時，常見做法是手寫腳本抓頁面或手動下載附件，既難維護，也很難在「文件是否已更新」上做到穩定判斷。清華網絡學堂依賴瀏覽器登錄，驗證碼、掃碼和會話狀態又不好塞進純命令行工具。
下面介紹的 dsh-tsinghua-course-sync 由維護者 ZhiX-Wang 發佈，歸類爲聯網工具。它在系統默認瀏覽器（或指定的 Chrome、Edge、Firefox）中複用你已登錄的學堂會話，按當前學期課程列表把資料落到本機，並在再次同步時用學堂側標識、更新時間與大小，以及本地 SHA-256 校驗做增量跳過或更新。每輪運行會寫 JSONL 日誌，便於在 DSH 裏用自然語言查「上次新增了哪些、有沒有失敗」。
插件當前爲 0.1.0 預覽版，適配 DSH 0.2.1-rc.2 至 0.2.1 系列（package.json 中 engines.dsh 爲 >=0.2.1-rc.2 <0.2.2-0）。DSH 工具與配套瀏覽器擴展需同時安裝，缺一不可。
這是什麼¶
一句話：在自己瀏覽器裏登錄清華網絡學堂後，把當前學期各科目課程資料按目錄歸檔到本機，後續調用只拉有變化的文件，並保留去重與逐項日誌。
- 倉庫：https://github.com/ZhiX-Wang/dsh-tsinghua-course-sync
- 社區目錄頁：https://www.skillhub.cn/plugins/ZhiX-Wang/dsh-tsinghua-course-sync
- 許可證：MIT（見倉庫
package.json）
社區插件目錄（如 SkillHub）與 DeepSeek / 幻方無官方從屬關係；安裝前建議自行查看源碼與許可證。插件以當前 DSH 進程權限讀寫本機目錄並與瀏覽器擴展通信，使用前請確認路徑與隱私邊界可接受。
核心功能¶
同步範圍¶
README 中寫明的範圍包括：
- 登錄用戶當前學期課程列表中的課程文件與全部分類。
- 課程公告附件與原文說明。
- 本人未提交、已提交未批改和已批改作業中的附件與原文說明。
課程列表在每次登錄後從頁面動態獲取；新課程、新分類和新附件在下次調用時發現。
本地目錄結構¶
默認保存目錄爲當前 OS 用戶的 Documents/清華網絡學堂/課程。用戶可在對話中指定其他絕對路徑，後續更新繼續使用同一目錄。
每個課程文件夾採用學堂顯示的課程名和課程編號，並保留原文件分類；公告與作業分別放在「課程公告」「課程作業」子文件夾。
增量與去重¶
保存目錄下的 .學堂同步/manifest.json 記錄文件標識、元數據指紋、相對路徑、大小、校驗值與保存時間。.學堂同步/logs/ 下每次運行生成一個 JSONL 日誌，逐行記錄操作結果。
| 日誌動作 | 含義 |
|---|---|
saved |
首次保存 |
updated |
文件發生變化，保存新版本 |
skipped |
遠程元數據和本地校驗均未變化，跳過下載 |
deduplicated |
取得內容後發現與已有文件一致，複用原文件 |
failed |
當前項目失敗，成功項目已保留，可再次同步補齊 |
recovered |
從之前中斷的保存日誌恢復索引 |
run_finished |
本輪最終狀態與統計 |
同名文件內容變化時，新版本文件名帶校驗值後綴，舊版本保留。更新判斷依賴學堂公開的文件標識、更新時間和大小；公告或作業正文還會覈對原文內容。README 註明：若學堂在保留相同標識、時間和大小的同時替換附件，當前版本無法僅從列表元數據識別該變化。
DSH 註冊工具¶
在 DSH 0.2.1-rc.2 的 ToolRuntime 中註冊 4 個工具（README「工具」一節）：
| 工具 | 用途 |
|---|---|
tsinghua_courses_sync |
開始增量同步，可指定 root 與 browser |
tsinghua_courses_status |
查看運行狀態，可等待最多 25 秒 |
tsinghua_courses_history |
查看最近同步日誌 |
tsinghua_courses_cancel |
取消當前任務並保留已完成文件 |
browser 可選 default、chrome、edge 或 firefox。任務返回 waiting_for_browser 或 waiting_for_login 時，按頁面提示完成操作後會自動繼續。
安裝與啓用¶
在 GitHub Release v0.1.0 可下載 DSH 安裝包與配套瀏覽器擴展。DSH 部分也可直接用發佈地址安裝：
dsh plugin --profile desktop add https://github.com/ZhiX-Wang/dsh-tsinghua-course-sync/releases/download/v0.1.0/dsh-tsinghua-course-sync-0.1.0.tgz
若已下載 dsh-tsinghua-course-sync-0.1.0.tgz 到本機某文件夾，可在該目錄執行：
dsh plugin --profile desktop add ./dsh-tsinghua-course-sync-0.1.0.tgz
然後重新啓動 DSH。非 desktop profile 的用戶將命令中的 desktop 換成自己的 profile 名。
瀏覽器擴展安裝步驟（摘自 README）：
- 解壓 Release 中的配套瀏覽器擴展 ZIP，保留解壓後的文件夾。
- Chrome：打開
chrome://extensions；Edge：打開edge://extensions。啓用開發者模式，「加載已解壓的擴展程序」，選擇包內chromium文件夾。 - Firefox：使用
firefox文件夾；預覽可在about:debugging#/runtime/this-firefox臨時載入manifest.json（重啓後失效；長期安裝需 Firefox 簽名）。
DSH 啓動器若未加入 PATH，可使用安裝目錄中的 dsh；macOS 應用版常見路徑爲 /Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh。
Safari：默認瀏覽器爲 Safari 時，預覽版會提示選用已安裝的 Chrome、Edge 或 Firefox（例如在 DSH 中說「這次用 Chrome 同步」）。Safari 擴展需另行生成應用包並簽名。
驗證狀態：README 寫明 Windows、Linux、Firefox 和 Safari 的完整使用流程尚未實機驗證；Chrome/Edge 商店分發與 Firefox 簽名尚未完成，當前通過加載源碼文件夾預覽。
典型用法¶
在 DSH 對話中輸入 README 給出的任一句即可觸發（模型會調用插件工具）：
幫我同步清華網絡學堂當前學期的課程資料。
把課程資料保存到我指定的絕對路徑，之後繼續同步這個目錄。
看看上次課程同步新增了哪些文件，有沒有失敗。
流程概要：
- 插件打開系統默認瀏覽器中的連接頁，點擊「允許本次課程同步」。
- 學堂在同一瀏覽器新標籤頁打開；已有登錄會話會直接使用。瀏覽器自動填入賬號密碼後，插件會嘗試點擊一次登錄；驗證碼、掃碼、二次驗證或失效密碼需在學堂頁面手動完成。
- 同步期間保留連接頁與學堂標籤頁。完成後 DSH 顯示結果與日誌位置，連接頁也會顯示完成狀態。
擴展僅訪問清華網絡學堂、清華身份認證頁面和本機迴環連接；用戶每次點擊允許後才接收該輪同步。賬號密碼由瀏覽器管理，擴展檢查自動填充狀態以觸發登錄；課程原文與附件在本機處理，聊天記錄的處理方式由用戶自己的 DSH 模型與會話配置決定。
適用場景與注意¶
適合：已在 Chromium 系瀏覽器（或 README 支持的 Firefox 預覽流程）中維護學堂登錄習慣、希望把當前學期資料定期歸檔到本機、並需要可重複的增量日誌與失敗補齊的 DSH 用戶。
注意：
- 運行環境：
package.json要求 Node>=22.19.0，DSH 版本需在 0.2.1-rc.2～0.2.1 區間內。 - 權限與安全：插件以 DSH 進程權限寫盤；擴展權限範圍見 README「瀏覽器權限」一節。安裝前請閱讀倉庫源碼與 MIT 許可證。
- 侷限：元數據未變但附件被替換的場景，當前版本可能無法識別；Safari 與部分平臺的完整流程尚未在 README 中標記爲已實機驗證。
結尾¶
dsh-tsinghua-course-sync 把「瀏覽器登錄 + 當前學期課程列表 + 本地增量索引」串成一條可在 DSH 裏用自然語言驅動的同步鏈路，適合需要穩定歸檔學堂資料、又不想每次全量下載的開發者或學生用戶。
