bb-sync：把 Blackboard 课件和待办同步到本地

这是什么

bb-sync 是我写的命令行工具，只服务港中深。它登录 bb.cuhk.edu.cn，把课件、作业、指导（tutorial / lab）增量下载到本地，把公告存成 Markdown，再把全部课程的待办汇总成一份 due.md。

同步一次之后，下载目录是这样：

~/courses/
├── CSC5010_人工智能/
│   ├── lectures/
│   │   ├── 01 绪论.pdf
│   │   └── 02 搜索算法.pdf
│   ├── assignments/hw1/
│   │   ├── hw1.pdf
│   │   └── starter.zip
│   ├── tutorials/tutorial01.ipynb
│   └── announcements.md
├── MAT1001_微积分/
└── due.md

重复运行只下新增的文件，已经有的直接跳过，所以每天跑一遍也很快。

它能帮你做什么

• 一门课一个文件夹。课件、作业、指导自动分到 lectures/、assignments/、tutorials/，作业再按 hw1、hw2 分一层。
• 全部课程的截止时间汇总进 due.md，按「已逾期 → 今天 → 明天 → 未来 7 天 → 之后」排序。
• 很多老师只在公告里写考试日期，例如「Midterm: November 1」。这类测验、考试和作业截止时间也会收进待办。
• 每条待办是 - [ ]，手动改成 - [x] 就行，下次同步不会把勾选擦掉。

due.md 长这样：

## 已逾期（1）

- [ ] **2026-10-12**（逾期 2 天） — [CSC5010](…) — 作业 3 实验报告

## 今天（1）

- [ ] **2026-10-14**（今天） — [MAT1001](…) — 习题 5

## 未来 7 天（3）

- [x] **2026-10-17**（还有 3 天） — [ENG1001](…) — Essay 1 初稿
- [ ] **2026-10-21**（还有 7 天） — [MAT1001](…) — 【考试】期中考试

安装

支持 Windows 10/11 和 macOS（Intel / Apple Silicon）。需要电脑上装了 Chrome 或 Edge，Windows 自带的 Edge 就够了，不用另外下载。

方式一：uv（推荐，不用先装 Python）

uv 是一个 Python 工具管理器。装软件时它会自动挑一个兼容的 Python，不会把系统里的 Python 搞乱。

Windows（PowerShell）：

winget install --id Git.Git -e
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS（先装 Homebrew）：

brew install git uv

重开终端，执行：

uv tool install bb-sync
bb-sync doctor

方式二：pip

机器上已经有 Python 3.11 或更新版本的话，用 pip 也可以：

pip install --user bb-sync

macOS 上一般用 pip3 install --user bb-sync。装完检查三件事：

• 能直接敲 bb-sync 就没问题。
• 提示「找不到命令」，说明 Python 的脚本目录不在 PATH 里。这时把 bb-sync 换成 python -m bb_sync，例如 python -m bb_sync doctor。
• 不想动系统 Python 就用 pipx：pipx install bb-sync。

bb-sync doctor 检查环境，逐项告诉你哪里没准备好：

bb-sync 2.2.0 — doctor

[✓] Python     3.12.14
[✓] git        git version 2.5x
[✓] 浏览器      Chrome (C:\Program Files\Google\Chrome\Application\chrome.exe)
[✓] 网络       https://bb.cuhk.edu.cn 可达
[✓] 凭据       未配置（首次运行会提示录入）
[✓] 浏览器后端  未运行（下次同步自动启动）

第一次使用

1. 保存学号和密码：

   bb-sync auth login
   

   密码存在 Windows 凭据管理器或 macOS 钥匙串里，不会写进配置文件，也不会发到任何服务器。macOS 可能弹一次钥匙串授权，选允许。

2. 先跑一次能看到浏览器的同步，确认登录成功，需要的话手动过验证码：

   bb-sync run --headed
   

   浏览器会自动登录、开始下载，跑完自己关掉。登录状态会记住，之后不用每次登录。

3. 以后就一条命令：

   bb-sync run
   

   跑起来先启动后台浏览器、登录、列出课程，再打印一份「同步计划」，写明哪个课程代码会落到哪个文件夹，动手前可以核对：

   

   跑完是汇总（这轮新下载了什么、跳过了多少已存在的文件）和逐条待办明细，逾期的标红，测验和考试带类型标签：

   

   两张都是我账号的真实输出，课程代码和路径是本机的实际情况。

默认下载到 ~/courses（Windows 是 C:\Users\<你>\courses）。换位置：

bb-sync config set root "~/University/courses"

常用命令

命令	作用
bb-sync run	增量同步全部课程，并更新 due.md
bb-sync run --course CSC5010	只同步某一门课（可重复写多个）
bb-sync run --dry-run	先看看会下哪些东西，不写文件
bb-sync due	只重新生成待办 due.md，不下载课件
bb-sync course list	列出你这学期有哪些课
bb-sync auth login / logout / status	录入 / 删除 / 查看保存的凭据
bb-sync config set root <目录>	改下载位置
bb-sync doctor	检查环境
bb-sync --help	看完整帮助

bb-sync run 结束时逐条列出这次真正新下载的文件，没有新文件就不打印。due.md 内容没变就不重写，屏幕上会提示一句。

常见问题

bb-sync 找不到？ 重开终端。uv 装的还可以执行 uv tool update-shell 再重开，pip 装的试 python -m bb_sync。

doctor 里网络那项没过？

登录失败？ bb-sync auth status 看凭据在不在，再用 bb-sync run --headed 重试一次。还不行的话，~/.bb-sync/ 下会留一张失败截图和 debug_login.html，可以拿来排查，提 issue 时也可以附上。

想看着浏览器跑，或者连着跑好几条命令？ bb-sync run --headed --keep-open 会让窗口留在屏幕上，之后用 bb-sync browser status 看状态、bb-sync browser stop 关掉。

想换账号？

最后

工具是给自己省事写的，用得上的话可以试试。遇到 bug，或者哪门课的课件抓不下来，直接开 issue。仓库里还有两份文档：配置项说明，以及接脚本用（--json 输出和退出码）。

• 仓库：github.com/asdukw/cuhk-shenzhen-blackboard-sync
• 安装：uv tool install bb-sync 或 pip install --user bb-sync