前言¶
在 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 里用自然语言驱动的同步链路，适合需要稳定归档学堂资料、又不想每次全量下载的开发者或学生用户。
