bb-sync 2.2.0__tar.gz → 2.3.0__tar.gz

{bb_sync-2.2.0 → bb_sync-2.3.0}/.gitignore

@@ -18,3 +18,8 @@ debug_*.txt
 # 个人工作区与课程资料（课程资料属版权内容，禁止公开）
 .workbuddy/
 courses/
+
+# 本地 AI / 工作流工具目录（个人环境，不入库）。openspec/ 不在此列：
+# 它保存项目的 specs 与 change 归档，属于该跟代码一起版本化的规划产物。
+.claude/
+.pi/

bb_sync-2.3.0/AGENTS.md

@@ -0,0 +1,50 @@
+# AGENTS.md
+
+给 AI 编码代理的最小必要上下文。展开细节按需查阅：
+[architecture.md](docs/architecture.md)（目录与实现约定）、[testing.md](docs/testing.md)（测试与门禁）、
+[CONTRIBUTING.md](CONTRIBUTING.md)（开发流程、风格、发布）。
+
+## 项目速览
+
+- Blackboard 课程资源同步 CLI：登录港中深 `bb.cuhk.edu.cn`（ADFS SSO），把课件 / 作业 / 指导
+  增量下载到课程目录，公告存 `announcements.md`，全部待办汇总到 `due.md`。
+- **只适配** `bb.cuhk.edu.cn` 及其 ADFS 登录流程；不要为其他站点引入通用化假设。
+- 目标平台 Windows 10/11（PowerShell）与 macOS（Intel / Apple Silicon，zsh / bash）；
+  Python ≥3.11，技术栈 Typer + Click、pydantic v2、PyYAML、rich、keyring、Playwright。
+- 代码注释、docstring、提交信息、文档一律中文；命令与路径示例同时覆盖 PowerShell 与 zsh / bash。
+
+## 五条不能破的红线
+
+1. **输出分流**：结果走 stdout、诊断走 stderr，一律经 `core.output.Console`；禁止 `print`，
+   不要打开 Rich markup（诊断里满是 `[new]`、`[作业]` 这类方括号）。`--json` 时 stdout 只有一个 JSON 文档。
+2. **错误语义化**：可预期错误抛 `BbSyncError` 子类（`core/errors.py`），退出码由自带的 `exit_code`
+   决定；不要裸 `sys.exit(1)` 或临时整数。
+3. **冷启动**：`cli.py` / `context.py` / `commands/__init__.py` 顶层不得导入 playwright、pydantic、rich；
+   命令模块靠 `LazyGroup` 延迟导入，`--version` / `--help` 必须快速返回。
+4. **配置**：CLI > `BB_SYNC_<KEY>` > config.yaml > 内置默认；`config set/unset` 必须走
+   `core/config_store.py` 的行级编辑，保留注释与未知键，不要整份 YAML 重写。
+5. **浏览器**：只驱动本机已装的 Chrome / Edge（分离进程 + CDP + 自有 profile），不引入 Node / npm
+   或任何需联网下载的运行时；默认跑完即关，关闭只走 CDP `Browser.close`，绝不读写用户的日常 profile。
+
+## 常用命令
+
+```shell
+uv sync                       # 安装依赖（含 dev 组）
+uv run bb-sync --help         # 从源码运行 CLI
+uv run pytest                 # 单元 + CLI 端到端，默认全离线
+uv run ruff check .           # 静态检查；格式化检查用 ruff format --check .
+uv run pyright                # 类型检查
+```
+
+改动提交前 `pytest` / `ruff check` / `ruff format --check` / `pyright` 必须全绿；
+纯文档改动至少自查命令示例。测试与检查完全离线，只有真实 `run` / `doctor` 才需要浏览器和凭据。
+
+## 文档地图
+
+| 想知道 | 看 |
+| --- | --- |
+| 目录结构、模块职责、五条红线的细节与理由 | [docs/architecture.md](docs/architecture.md) |
+| 测试分层、`conftest` 隔离、CI、真实站点手工验证 | [docs/testing.md](docs/testing.md) |
+| 代码风格、提交信息、版本与发布 | [CONTRIBUTING.md](CONTRIBUTING.md) |
+| 配置项与 `--json` 输出结构 | [docs/config.md](docs/config.md)、[docs/scripting.md](docs/scripting.md) |
+| 安装与用户侧用法 | [README.md](README.md) |

{bb_sync-2.2.0 → bb_sync-2.3.0}/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [2.3.0] — 2026-11-04
+
+### 修复
+
+- **公告里没有编号的作业名也能认出**：此前作业名规则要求 `HW4` / `Assignment 2`
+  这类带编号写法，CSC5010 的 `Homework on Probabilistic Reasoning`（截止
+  2026-11-15）整条被静默丢弃。现在接受「作业词 + 可选编号 + on / about 主题」的
+  写法，守卫改为「标题或截止行相邻行含作业词」；`Week 4 Materials Uploaded` 这类
+  没有作业语境的日期仍然不收录。
+- **To Do 与公告叫法不一致时不再静默丢弃**：Blackboard 把 HW4 的作业容器命名成
+  `Assignment 5`，与同一天公告的 `Homework assignment 4` 冲突，旧版按「To Do 优先」
+  直接丢弃公告条目。现在保留 To Do 的日期与类型，把公告标题记为该条目的别名，
+  `due.md` 渲染成 `Assignment 5（公告称 Homework assignment 4）`，文件头部解释括号含义。
+- **同一编号的两种写法不再重复成两条**：`HW4` 与 `Homework assignment 4` 的主题词
+  集合没有交集，旧版判不成同一件事，同一天会列两条；现在补充「同为作业类说法且
+  编号相同」的判定。
+- **分歧提示补全到待办明细**：`bb-sync due` 与 `bb-sync run` 的汇总会打印
+  「发现 N 处来源分歧」，`run` 的明细行与 `due.md` 共用同一套标题渲染，直接显示
+  `Assignment 5（公告称 Homework assignment 4）`，不必再回 `due.md` 对照。
+
+### 变更
+
+- `due.md` 行格式：带来源分歧的条目会在标题后追加 `（公告称 …）`，文件头部相应多一行说明。
+- `--json` 的 `items` 元素新增 `aliases` 字段（无分歧时为空数组）。
+
+## [2.2.1] — 2026-11-02
+
+### 修复
+
+- **`doctor` 网络检查不再建议连接学校 VPN**：`bb.cuhk.edu.cn` 校外可以直接访问，
+  原提示「校外使用需要先连接学校 VPN」会把网络问题误导向 VPN，连上后仍失败反而
+  更难判断。现在改为提示检查本机网络，说明系统代理无法转发 HTTPS 时先关代理重试，
+  并给出 `bb-sync doctor --skip-network` 作为跳过检查的方式；README 排障条目同步更新。
+
 ## [2.2.0] — 2026-10-31
 
 ### 修复

{bb_sync-2.2.0 → bb_sync-2.3.0}/CONTRIBUTING.md

@@ -1,6 +1,7 @@
 # 参与开发
 
 本文面向修改 bb-sync 源码的开发者。普通安装与使用请先阅读 [README.md](README.md)。
+实现约定见 [docs/architecture.md](docs/architecture.md)，测试细节见 [docs/testing.md](docs/testing.md)。
 
 ## 开发环境
 
@@ -41,24 +42,42 @@ uv run pyright
 
 - `tests/test_units.py`：纯逻辑单元测试，覆盖配置分层与行级编辑、文件名和分类推断、异常与退出码映射等。
 - `tests/test_cli_e2e.py`：把完整命令链跑在进程内的端到端测试，覆盖命令行契约、退出码、stdout/stderr 分流和配置读写。
+- `tests/test_update_e2e.py`：自动更新提示的通道行为。
 
-测试环境通过 `tests/conftest.py` 隔离 `BB_SYNC_HOME`、工作目录和系统钥匙串，不应访问真实网站、下载文件或读取真实凭据。
+测试环境通过 `tests/conftest.py` 隔离 `BB_SYNC_HOME`、工作目录、系统钥匙串和浏览器 profile 路径，
+不应访问真实网站、下载文件或读取真实凭据，也不应真的拉起浏览器进程。fixture 清单与测试相关坑见
+[docs/testing.md](docs/testing.md)。
 
 ## CI
 
-`.github/workflows/ci.yml` 在 push 和 PR 时运行（Ubuntu 与 macOS）：
+`.github/workflows/ci.yml` 在 push 和 PR 时运行：
 
 - Ruff lint；
 - Ruff format check；
 - Pyright；
 - pytest；
-- 干净容器中的安装冒烟测试。
+
+以上四项跑在 Ubuntu、macOS 与 Windows 三平台矩阵上；另有干净容器里的安装冒烟测试（Ubuntu）。
 
 启动浏览器、登录 Blackboard 和真实下载不属于默认离线测试范围。修改相关逻辑时，请在本地补充可重复的手工验证步骤。
 
+## 代码风格
+
+- 格式与静态检查统一由工具把关：ruff（line-length 100、目标 py311、`known-first-party = ["bb_sync"]`）
+  与 ruff format；pyright 用 `standard` 模式且必须零报错。
+- 注释 / docstring 用中文，解释职责与「为什么」；模块 docstring 说明该模块的关键约束。
+- 全面类型标注，模块头统一 `from __future__ import annotations`。
+- 面向用户的错误信息要带可操作的 hint（下一步敲什么命令）。
+
 ## 提交习惯
 
-- 提交信息使用 `feat|fix|docs|refactor|test|chore(范围): 摘要`；
+- 提交信息使用中文，格式 `feat|fix|docs|refactor|test|chore(范围): 摘要`；
 - 一个提交只处理一件事；
 - 不提交密钥、`.env`、浏览器 profile、课程文件、构建产物或其他生成物；
 - 只暂存本次改动相关的文件。
+
+## 发布
+
+- 版本号写在 `pyproject.toml`，发布前在本地跑完整四件套（见上文「常用检查」）；
+- 打 `v*` tag 触发 `.github/workflows/release.yml`：发布会校验 wheel 文件名与 tag 一致，
+  并同步更新 `CHANGELOG.md`。

{bb_sync-2.2.0 → bb_sync-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bb-sync
-Version: 2.2.0
+Version: 2.3.0
 Summary: 港中深（CUHK-Shenzhen）Blackboard 课件下载与课程资源自动同步：登录 ADFS SSO，增量下载课件/作业/指导、公告与待办
 Project-URL: Homepage, https://github.com/asdukw/cuhk-shenzhen-blackboard-sync
 Project-URL: Repository, https://github.com/asdukw/cuhk-shenzhen-blackboard-sync
@@ -53,7 +53,7 @@ Description-Content-Type: text/markdown
 
 **港中深（香港中文大学·深圳 / CUHK-Shenzhen / CUHKSZ）Blackboard 课件下载与课程资源自动同步 CLI**
 
-登录 `bb.cuhk.edu.cn`，把课件、作业和指导增量下载到本地，把公告和全部课程的待办整理成 Markdown。重复运行时会跳过已经下载的文件。
+登录 `bb.cuhk.edu.cn`，把课件、作业和指导 / 实验（tutorial / lab）增量下载到本地，把公告和全部课程的待办整理成 Markdown。重复运行时会跳过已经下载的文件。
 
 *Blackboard course material sync CLI for CUHK-Shenzhen students.*
 
@@ -70,15 +70,24 @@ Description-Content-Type: text/markdown
 
 Blackboard 上的东西散在「课程内容」「作业」「公告」几个入口，一学期下来几十上百个文件，靠手动点、手动记截止日期很容易漏。bb-sync 把这些收进本地一个目录：
 
-- 课件、作业、指导按课程归好类，重跑只下新增的；
-- 每门课的公告存成一份 `announcements.md`；
-- 全部课程的待办汇总成一份 `due.md`，按「已逾期 → 今天 → 明天 → 未来 7 天 → 之后」排好序，公告里带日期的课堂测验、考试和作业截止时间也一并计入；每条待办都是可勾选的任务列表（`- [ ]`），做完勾上 `- [x]`，下次同步会保留完成状态。
+- 课件、作业、指导按课程归好类。重跑只下新增的，结束时逐条列出本轮真正新下载的文件。
+- 有公告的课程会生成一份 `announcements.md`。没有公告的课程不生成，`bb-sync due` 也不写这个文件。
+- 全部课程的待办汇总成一份 `due.md`，按「已逾期 → 今天 → 明天 → 未来 7 天 → 之后 → 日期未知 → 已过期事件」排好序。公告里带日期的课堂测验、考试和作业截止时间也一并计入。每条待办都是可勾选的任务列表（`- [ ]`），做完勾上 `- [x]`，下次同步保留完成状态。
+- To Do 名称与公告写法对不上时（例如教务把 HW4 的作业容器命名成 `Assignment 5`），条目会渲染成 `Assignment 5（公告称 Homework assignment 4）`，两个来源的名字都保留，不静默二选一。
 
-它**不做**这些：不回传作业、不代签到、不抓成绩、不绕过任何权限——看到的就是你账号里本来能看到的。
+它不回传作业、不代签到、不抓成绩，也绕不过任何权限。看到的就是你账号里本来能看到的。
 
 ## 长什么样
 
-下面是示例输出（课程名和文件名为虚构，链接已缩写为 `…`，实际每条都带回到对应 Blackboard 课程页的链接）。
+`bb-sync run` 的真实输出分三段。先启动后台浏览器、登录、列出课程，再打印一份「同步计划」，写明每个课程代码会落到哪个本地目录：
+
+![bb-sync run 的同步计划：登录成功后列出 7 门课程到本地目录的映射](docs/images/run-plan.png)
+
+跑完是汇总，说明这轮新下载了什么、跳过了多少已存在的文件。最后是逐条待办明细，逾期的红色，测验和考试带类型标签：
+
+![bb-sync run 的汇总、新下载明细与待办明细](docs/images/run-summary.png)
+
+下面的文本示例可以直接复制。课程名和文件名是虚构的，链接缩写为 `…`，实际每条都指回对应的 Blackboard 课程页。
 
 `due.md`：
 
@@ -86,31 +95,34 @@ Blackboard 上的东西散在「课程内容」「作业」「公告」几个入
 # Blackboard 待办
 
 > 更新时间：2026-10-14 21:03（本地时间）
-> 已检查 5 门课程，发现 7 项待办；按优先级和截止日期排列。
-> 其中公告里的测验 1 项、考试 1 项已一并作为待办列出。
+> 已检查 5 门课程，发现 8 项待办；按优先级和截止日期排列。
+> 其中公告里的测验 1 项、考试 1 项、作业 1 项已一并作为待办列出。
 > 另有 1 项公告里的测验/考试日期已过，列在最后仅供回看。
+> 完成一项就在前面打勾（`- [ ]` → `- [x]`），下次同步会保留完成状态。
+> 括号里的「公告称 …」表示 To Do 名称与公告写法对不上，两个名字都来自 Blackboard。
 
 ## 已逾期（1）
 
-- **2026-10-12**（逾期 2 天） — [CSC5010](https://bb.cuhk.edu.cn/…) — 作业 3 实验报告
+- [ ] **2026-10-12**（逾期 2 天） — [CSC5010](https://bb.cuhk.edu.cn/…) — 作业 3 实验报告
 
 ## 今天（1）
 
-- **2026-10-14**（今天） — [MAT1001](https://bb.cuhk.edu.cn/…) — 习题 5
+- [ ] **2026-10-14**（今天） — [MAT1001](https://bb.cuhk.edu.cn/…) — 习题 5
 
 ## 明天（1）
 
-- **2026-10-15**（明天） — [CSC5010](https://bb.cuhk.edu.cn/…) — 【测验】Quiz 2
+- [ ] **2026-10-15**（明天） — [CSC5010](https://bb.cuhk.edu.cn/…) — 【测验】Quiz 2
 
-## 未来 7 天（3）
+## 未来 7 天（4）
 
-- **2026-10-17**（还有 3 天） — [ENG1001](https://bb.cuhk.edu.cn/…) — Essay 1 初稿
-- **2026-10-20**（还有 6 天） — [CSC5010](https://bb.cuhk.edu.cn/…) — 作业 4
-- **2026-10-21**（还有 7 天） — [MAT1001](https://bb.cuhk.edu.cn/…) — 【考试】期中考试
+- [x] **2026-10-17**（还有 3 天） — [ENG1001](https://bb.cuhk.edu.cn/…) — Essay 1 初稿
+- [ ] **2026-10-18**（还有 4 天） — [DDA5002](https://bb.cuhk.edu.cn/…) — Assignment 5（公告称 Homework assignment 4）
+- [ ] **2026-10-20**（还有 6 天） — [CSC5010](https://bb.cuhk.edu.cn/…) — 【作业】HW4
+- [ ] **2026-10-21**（还有 7 天） — [MAT1001](https://bb.cuhk.edu.cn/…) — 【考试】期中考试
 
 ## 已过期事件（1）
 
-- **2026-10-08**（已过 6 天） — [CSC5010](https://bb.cuhk.edu.cn/…) — 【测验】Quiz 1
+- [ ] **2026-10-08**（已过 6 天） — [CSC5010](https://bb.cuhk.edu.cn/…) — 【测验】Quiz 1
 ````
 
 下载目录：
@@ -135,7 +147,7 @@ Blackboard 上的东西散在「课程内容」「作业」「公告」几个入
 
 ## 安装
 
-需要 uv 和 Chrome 或 Edge。bb-sync 会自动探测常见安装位置，Windows 自带的 Edge 直接可用。
+需要 Git 和 Chrome 或 Edge。安装 bb-sync 有两个办法：uv 会自己准备兼容的 Python 3.11+ 并隔离安装，不需要预先装 Python；已经装了 Python 3.11+ 的话也可以直接用 pip。浏览器会探测常见安装位置，Windows 自带的 Edge 直接可用。
 
 ### Windows
 
@@ -146,9 +158,7 @@ winget install --id Git.Git -e
 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
-（Git 只在「从 GitHub 安装」时需要，走 PyPI 安装可以跳过。）
-
-Windows 自带的 Edge 即可使用；也可以自行安装 Google Chrome。
+也可以自己装 Google Chrome。
 
 ### macOS
 
@@ -163,7 +173,7 @@ brew install --cask google-chrome
 
 ### 安装 bb-sync（Windows / macOS 相同）
 
-**重开终端**后执行：
+用 uv 安装，重开终端后执行：
 
 ```bash
 uv tool install bb-sync
@@ -176,7 +186,15 @@ bb-sync doctor
 uv tool install git+https://github.com/asdukw/cuhk-shenzhen-blackboard-sync
 ```
 
-`bb-sync doctor` 用于检查环境；刚安装时凭据显示“未配置”、浏览器后端显示“未运行”都是正常的。如果提示找不到 `bb-sync`，执行 `uv tool update-shell` 后重开终端。校外使用 Blackboard 时，可能需要先连接学校 VPN。
+已经装了 Python 3.11 或更新版本时，改用 pip 也行，这条路不需要 uv：
+
+```bash
+pip install --user bb-sync
+```
+
+macOS 上一般用 `pip3 install --user bb-sync`。pip 把命令装进 Python 自己的脚本目录；提示找不到 `bb-sync` 就用 `python -m bb_sync`，例如 `python -m bb_sync doctor`，或者改用 `pipx install bb-sync`。
+
+`bb-sync doctor` 检查环境。刚安装时凭据显示「未配置」、浏览器后端显示「未运行」，都正常。uv 装的如果提示找不到 `bb-sync`，执行 `uv tool update-shell`，再重开终端。
 
 ## 首次使用
 
@@ -188,7 +206,7 @@ bb-sync auth login
 
 密码会保存在 Windows 凭据管理器或 macOS 钥匙串，不会写入配置文件。macOS 首次访问时可能弹出钥匙串授权提示，选择允许即可。
 
-第一次同步请显示浏览器，便于完成登录、MFA 或验证码：
+第一次同步如果想看到登录过程（或手动完成验证码），可以用有头模式：
 
 ```bash
 bb-sync run --headed
@@ -200,9 +218,9 @@ bb-sync run --headed
 bb-sync run
 ```
 
-浏览器默认在**后台无窗口**运行，**跑完自动关闭**，不会在你机器上留下进程。登录态存在 `~/.bb-sync/.browser-profile/` 下、跨次运行保留，所以不必每次登录。
+浏览器默认在后台运行，没有窗口，跑完自动关闭，不在你机器上留下进程。登录状态保存在 `~/.bb-sync/.browser-profile/` 下，跨次运行保留，所以不必每次登录。
 
-需要把窗口留在屏幕上时（手动过 MFA、或想连续跑几条命令）加 `--keep-open`，之后再 `bb-sync browser stop` 关闭。
+想让窗口在命令结束后留在屏幕上（例如连续跑几条命令、观察页面），用 `--headed --keep-open`，之后用 `bb-sync browser stop` 关闭。
 
 ## 文件位置
 
@@ -215,9 +233,14 @@ bb-sync run
 
 - 课件 → `lectures/`
 - 作业 → `assignments/`
-- 指导 / 实验 → `tutorials/`
-- 公告 → `announcements.md`
-- 全部课程待办 → `due.md`（按优先级排列；公告里带日期的课堂测验、考试和作业截止时间也计入，考完的测验 / 考试归入最后的「已过期事件」并保留 7 天；每条待办带 `- [ ]` 复选框，勾选状态跨次同步保留；内容没变化时不重写，没有待办时显示 Congratulations）
+- 指导 / 实验（tutorial / lab） → `tutorials/`
+- 公告 → `announcements.md`（没有公告的课程不会生成）
+
+课程根目录还会生成 `due.md`：
+
+- 按「已逾期 → 今天 → 明天 → 未来 7 天 → 之后 → 日期未知 → 已过期事件」排序。公告里带日期的课堂测验、考试和作业截止时间也计入。
+- 每条待办带 `- [ ]` 复选框，勾选状态跨次同步保留。考完的测验和考试归入最后的「已过期事件」，保留 7 天。
+- 「更新时间」只在待办内容变化时刷新。内容没变就不重写；没有待办时显示 Congratulations。
 
 要修改下载目录：
 
@@ -232,41 +255,49 @@ Windows 也可以使用 `bb-sync config set root "D:/University/courses"`。更
 | 命令 | 作用 |
 | --- | --- |
 | `bb-sync run` | 增量同步全部课程并更新 `due.md` |
-| `bb-sync run --headed` | 显示浏览器，适合首次登录或 MFA |
-| `bb-sync run --course CSC5010` | 只同步指定课程，可重复使用 |
+| `bb-sync run --headed` | 显示浏览器，适合首次登录或观察登录过程 |
+| `bb-sync run --course CSC5010` | 只同步指定课程，可重复使用（`due.md` 也只保留这些课程） |
 | `bb-sync run --dry-run` | 预览下载和待办，不写文件 |
-| `bb-sync run --keep-open` | 跑完保留后台浏览器（手动过 MFA / 连着跑多条命令） |
-| `bb-sync due` | 扫描全部课程主页的 Due / To Do 与公告测验、考试，生成 `due.md` |
-| `bb-sync due --course CSC5010` | 只整理指定课程的待办 |
+| `bb-sync run --root <目录>` | 本次同步到指定目录（临时覆盖配置里的 `root`） |
+| `bb-sync run --keep-open` | 跑完保留浏览器（配合 `--headed` 才能看到窗口；连着跑多条命令） |
+| `bb-sync due` | 扫描全部课程的 Due / To Do 与公告里的测验、考试和作业 deadline，生成 `due.md` |
+| `bb-sync due --course CSC5010` | 只整理指定课程的待办（`due.md` 也只保留这些课程） |
+| `bb-sync due --root <目录>` | 本次把 `due.md` 写到指定目录（临时覆盖配置里的 `root`） |
 | `bb-sync course list` | 列出账号下的课程 |
 | `bb-sync auth login` / `logout` / `status` | 录入、删除、查看已保存的凭据 |
 | `bb-sync config show` | 显示配置文件内容 |
 | `bb-sync config set <键> <值>` | 修改配置；另有 `get` / `unset` / `edit` / `path` / `init` |
 | `bb-sync browser status` | 查看后台浏览器是否在运行（`--keep-open` 留下的实例） |
 | `bb-sync browser stop` | 关闭后台浏览器（登录态保留） |
-| `bb-sync doctor` | 检查环境是否就绪 |
+| `bb-sync doctor` | 检查环境是否就绪（`--skip-network` 跳过网络检查） |
 | `bb-sync --help` | 查看完整帮助 |
 
+`--headed` / `--keep-open` 对 `bb-sync due` 同样适用。用 `--course` 时，`due.md` 会被整份重写为所选课程的待办，其他课程的条目不会保留。
+
 ## 遇到问题
 
 - **`bb-sync` 找不到**：重开终端，或执行 `uv tool update-shell`。
+- **连不上 Blackboard**：校外也能直接访问，不需要学校 VPN；先运行 `bb-sync doctor` 看网络那一项，多数是本机代理无法转发 HTTPS 导致的，关掉代理再试一次。
 - **环境检查不通过**：按 `bb-sync doctor` 的提示安装或配置缺失项。
-- **想留住浏览器窗口**：默认跑完会自动关；加 `--keep-open` 才会保留，之后用 `bb-sync browser status` 看状态、`bb-sync browser stop` 关闭（不影响登录态）。
-- **登录失败或需要 MFA**：运行 `bb-sync auth status` 查看凭据，再用 `bb-sync run --headed` 重试。
+- **想留住浏览器窗口**：默认跑完会自动关；用 `--headed --keep-open` 才会保留可见窗口，之后用 `bb-sync browser status` 看状态、`bb-sync browser stop` 关闭（不影响登录态）。
+- **登录失败**：运行 `bb-sync auth status` 查看凭据，再用 `bb-sync run --headed` 重试。
 - **更换密码**：重新运行 `bb-sync auth login`。
+- **换账号 / 彻底退出登录**：`bb-sync auth logout` 只删除钥匙串里的凭据，浏览器 profile 里的登录态仍然有效；先 `bb-sync browser stop`，再删除 `~/.bb-sync/.browser-profile/`。要换账号，重新运行 `bb-sync auth login` 录入新账号。
 
 更多问题欢迎[开 Issue](https://github.com/asdukw/cuhk-shenzhen-blackboard-sync/issues)。
 
 ## 文档
 
-- [docs/config.md](docs/config.md) —— 配置文件、目录映射与全部配置项
-- [docs/scripting.md](docs/scripting.md) —— `--json` 输出结构与退出码，方便接脚本
-- [CONTRIBUTING.md](CONTRIBUTING.md) —— 开发流程与质量门禁
-- [CHANGELOG.md](CHANGELOG.md) —— 版本变更记录
+- [docs/config.md](docs/config.md)：配置文件、目录映射与全部配置项
+- [docs/scripting.md](docs/scripting.md)：`--json` 输出结构与退出码，方便接脚本
+- [CONTRIBUTING.md](CONTRIBUTING.md)：开发流程与质量门禁
+- [CHANGELOG.md](CHANGELOG.md)：版本变更记录
 
 ## 免责声明
 
-本工具只读取你自己账号里本来就能看到的内容，登录凭据保存在本机系统钥匙串中，不会上传到任何第三方。命令成功后会请求一次 GitHub Releases API 检查新版本，只发送 `bb-sync/<版本号>` 作为 User-Agent，不携带任何个人信息；设置环境变量 `BB_SYNC_NO_UPDATE_CHECK=1` 可关闭该检查。课程资料版权归香港中文大学（深圳）及各任课教师所有，**仅供个人学习使用，请勿二次分发**。使用本工具产生的一切后果由使用者自行承担。
+本工具只读取你自己账号里本来就能看到的内容，登录凭据保存在本机系统钥匙串中，不会上传到任何第三方。命令成功后会检查新版本，结果缓存 24 小时，每天最多请求一次 GitHub Releases API。请求只发送 `bb-sync/<版本号>` 作为 User-Agent，不携带任何个人信息。设置环境变量 `BB_SYNC_NO_UPDATE_CHECK=1` 可关闭该检查。
+
+课程资料版权归香港中文大学（深圳）及各任课教师所有，**仅供个人学习使用，请勿二次分发**。使用本工具产生的一切后果由使用者自行承担。
 
 ## License
 

bb_sync-2.3.0/README.md

@@ -0,0 +1,253 @@
+# bb-sync
+
+**港中深（香港中文大学·深圳 / CUHK-Shenzhen / CUHKSZ）Blackboard 课件下载与课程资源自动同步 CLI**
+
+登录 `bb.cuhk.edu.cn`，把课件、作业和指导 / 实验（tutorial / lab）增量下载到本地，把公告和全部课程的待办整理成 Markdown。重复运行时会跳过已经下载的文件。
+
+*Blackboard course material sync CLI for CUHK-Shenzhen students.*
+
+[![CI](https://github.com/asdukw/cuhk-shenzhen-blackboard-sync/actions/workflows/ci.yml/badge.svg)](https://github.com/asdukw/cuhk-shenzhen-blackboard-sync/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/asdukw/cuhk-shenzhen-blackboard-sync)](https://github.com/asdukw/cuhk-shenzhen-blackboard-sync/releases)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS-lightgrey)](#安装)
+
+> **适用边界**：只适配香港中文大学（深圳）的 `bb.cuhk.edu.cn` 和它的 ADFS SSO 登录流程。
+> 其他学校、其他 Blackboard 站点请勿安装。支持 Windows 10/11（PowerShell）与 macOS（Intel / Apple Silicon，zsh / bash）。
+
+## 它解决什么问题
+
+Blackboard 上的东西散在「课程内容」「作业」「公告」几个入口，一学期下来几十上百个文件，靠手动点、手动记截止日期很容易漏。bb-sync 把这些收进本地一个目录：
+
+- 课件、作业、指导按课程归好类。重跑只下新增的，结束时逐条列出本轮真正新下载的文件。
+- 有公告的课程会生成一份 `announcements.md`。没有公告的课程不生成，`bb-sync due` 也不写这个文件。
+- 全部课程的待办汇总成一份 `due.md`，按「已逾期 → 今天 → 明天 → 未来 7 天 → 之后 → 日期未知 → 已过期事件」排好序。公告里带日期的课堂测验、考试和作业截止时间也一并计入。每条待办都是可勾选的任务列表（`- [ ]`），做完勾上 `- [x]`，下次同步保留完成状态。
+- To Do 名称与公告写法对不上时（例如教务把 HW4 的作业容器命名成 `Assignment 5`），条目会渲染成 `Assignment 5（公告称 Homework assignment 4）`，两个来源的名字都保留，不静默二选一。
+
+它不回传作业、不代签到、不抓成绩，也绕不过任何权限。看到的就是你账号里本来能看到的。
+
+## 长什么样
+
+`bb-sync run` 的真实输出分三段。先启动后台浏览器、登录、列出课程，再打印一份「同步计划」，写明每个课程代码会落到哪个本地目录：
+
+![bb-sync run 的同步计划：登录成功后列出 7 门课程到本地目录的映射](docs/images/run-plan.png)
+
+跑完是汇总，说明这轮新下载了什么、跳过了多少已存在的文件。最后是逐条待办明细，逾期的红色，测验和考试带类型标签：
+
+![bb-sync run 的汇总、新下载明细与待办明细](docs/images/run-summary.png)
+
+下面的文本示例可以直接复制。课程名和文件名是虚构的，链接缩写为 `…`，实际每条都指回对应的 Blackboard 课程页。
+
+`due.md`：
+
+````markdown
+# Blackboard 待办
+
+> 更新时间：2026-10-14 21:03（本地时间）
+> 已检查 5 门课程，发现 8 项待办；按优先级和截止日期排列。
+> 其中公告里的测验 1 项、考试 1 项、作业 1 项已一并作为待办列出。
+> 另有 1 项公告里的测验/考试日期已过，列在最后仅供回看。
+> 完成一项就在前面打勾（`- [ ]` → `- [x]`），下次同步会保留完成状态。
+> 括号里的「公告称 …」表示 To Do 名称与公告写法对不上，两个名字都来自 Blackboard。
+
+## 已逾期（1）
+
+- [ ] **2026-10-12**（逾期 2 天） — [CSC5010](https://bb.cuhk.edu.cn/…) — 作业 3 实验报告
+
+## 今天（1）
+
+- [ ] **2026-10-14**（今天） — [MAT1001](https://bb.cuhk.edu.cn/…) — 习题 5
+
+## 明天（1）
+
+- [ ] **2026-10-15**（明天） — [CSC5010](https://bb.cuhk.edu.cn/…) — 【测验】Quiz 2
+
+## 未来 7 天（4）
+
+- [x] **2026-10-17**（还有 3 天） — [ENG1001](https://bb.cuhk.edu.cn/…) — Essay 1 初稿
+- [ ] **2026-10-18**（还有 4 天） — [DDA5002](https://bb.cuhk.edu.cn/…) — Assignment 5（公告称 Homework assignment 4）
+- [ ] **2026-10-20**（还有 6 天） — [CSC5010](https://bb.cuhk.edu.cn/…) — 【作业】HW4
+- [ ] **2026-10-21**（还有 7 天） — [MAT1001](https://bb.cuhk.edu.cn/…) — 【考试】期中考试
+
+## 已过期事件（1）
+
+- [ ] **2026-10-08**（已过 6 天） — [CSC5010](https://bb.cuhk.edu.cn/…) — 【测验】Quiz 1
+````
+
+下载目录：
+
+```text
+~/courses/
+├── CSC5010_人工智能/
+│   ├── lectures/
+│   │   ├── 01 绪论.pdf
+│   │   └── 02 搜索算法.pdf
+│   ├── assignments/
+│   │   └── hw1/
+│   │       ├── hw1.pdf
+│   │       └── starter.zip
+│   ├── tutorials/
+│   │   └── tutorial01.ipynb
+│   └── announcements.md
+├── MAT1001_微积分/
+│   └── ...
+└── due.md
+```
+
+## 安装
+
+需要 Git 和 Chrome 或 Edge。安装 bb-sync 有两个办法：uv 会自己准备兼容的 Python 3.11+ 并隔离安装，不需要预先装 Python；已经装了 Python 3.11+ 的话也可以直接用 pip。浏览器会探测常见安装位置，Windows 自带的 Edge 直接可用。
+
+### Windows
+
+在 PowerShell 中执行：
+
+```powershell
+winget install --id Git.Git -e
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+也可以自己装 Google Chrome。
+
+### macOS
+
+推荐先安装 [Homebrew](https://brew.sh/)，再执行：
+
+```bash
+brew install git uv
+brew install --cask google-chrome
+```
+
+如果已经安装 Chrome 或 Edge，可跳过最后一条。Edge 的 cask 名称为 `microsoft-edge`。
+
+### 安装 bb-sync（Windows / macOS 相同）
+
+用 uv 安装，重开终端后执行：
+
+```bash
+uv tool install bb-sync
+bb-sync doctor
+```
+
+也可以直接从 GitHub 安装（跟随 `main` 上的最新代码）：
+
+```bash
+uv tool install git+https://github.com/asdukw/cuhk-shenzhen-blackboard-sync
+```
+
+已经装了 Python 3.11 或更新版本时，改用 pip 也行，这条路不需要 uv：
+
+```bash
+pip install --user bb-sync
+```
+
+macOS 上一般用 `pip3 install --user bb-sync`。pip 把命令装进 Python 自己的脚本目录；提示找不到 `bb-sync` 就用 `python -m bb_sync`，例如 `python -m bb_sync doctor`，或者改用 `pipx install bb-sync`。
+
+`bb-sync doctor` 检查环境。刚安装时凭据显示「未配置」、浏览器后端显示「未运行」，都正常。uv 装的如果提示找不到 `bb-sync`，执行 `uv tool update-shell`，再重开终端。
+
+## 首次使用
+
+保存学号和密码：
+
+```bash
+bb-sync auth login
+```
+
+密码会保存在 Windows 凭据管理器或 macOS 钥匙串，不会写入配置文件。macOS 首次访问时可能弹出钥匙串授权提示，选择允许即可。
+
+第一次同步如果想看到登录过程（或手动完成验证码），可以用有头模式：
+
+```bash
+bb-sync run --headed
+```
+
+这条命令会用你机器上的 Chrome（没有则用 Edge）打开一个窗口，登录一次即可。之后同步直接运行：
+
+```bash
+bb-sync run
+```
+
+浏览器默认在后台运行，没有窗口，跑完自动关闭，不在你机器上留下进程。登录状态保存在 `~/.bb-sync/.browser-profile/` 下，跨次运行保留，所以不必每次登录。
+
+想让窗口在命令结束后留在屏幕上（例如连续跑几条命令、观察页面），用 `--headed --keep-open`，之后用 `bb-sync browser stop` 关闭。
+
+## 文件位置
+
+默认下载到用户主目录下的 `courses`：
+
+- Windows：`C:\Users\<你>\courses`
+- macOS：`/Users/<你>/courses`
+
+每门课一个文件夹：
+
+- 课件 → `lectures/`
+- 作业 → `assignments/`
+- 指导 / 实验（tutorial / lab） → `tutorials/`
+- 公告 → `announcements.md`（没有公告的课程不会生成）
+
+课程根目录还会生成 `due.md`：
+
+- 按「已逾期 → 今天 → 明天 → 未来 7 天 → 之后 → 日期未知 → 已过期事件」排序。公告里带日期的课堂测验、考试和作业截止时间也计入。
+- 每条待办带 `- [ ]` 复选框，勾选状态跨次同步保留。考完的测验和考试归入最后的「已过期事件」，保留 7 天。
+- 「更新时间」只在待办内容变化时刷新。内容没变就不重写；没有待办时显示 Congratulations。
+
+要修改下载目录：
+
+```bash
+bb-sync config set root "~/University/courses"
+```
+
+Windows 也可以使用 `bb-sync config set root "D:/University/courses"`。更完整的配置说明见 [docs/config.md](docs/config.md)。
+
+## 常用命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `bb-sync run` | 增量同步全部课程并更新 `due.md` |
+| `bb-sync run --headed` | 显示浏览器，适合首次登录或观察登录过程 |
+| `bb-sync run --course CSC5010` | 只同步指定课程，可重复使用（`due.md` 也只保留这些课程） |
+| `bb-sync run --dry-run` | 预览下载和待办，不写文件 |
+| `bb-sync run --root <目录>` | 本次同步到指定目录（临时覆盖配置里的 `root`） |
+| `bb-sync run --keep-open` | 跑完保留浏览器（配合 `--headed` 才能看到窗口；连着跑多条命令） |
+| `bb-sync due` | 扫描全部课程的 Due / To Do 与公告里的测验、考试和作业 deadline，生成 `due.md` |
+| `bb-sync due --course CSC5010` | 只整理指定课程的待办（`due.md` 也只保留这些课程） |
+| `bb-sync due --root <目录>` | 本次把 `due.md` 写到指定目录（临时覆盖配置里的 `root`） |
+| `bb-sync course list` | 列出账号下的课程 |
+| `bb-sync auth login` / `logout` / `status` | 录入、删除、查看已保存的凭据 |
+| `bb-sync config show` | 显示配置文件内容 |
+| `bb-sync config set <键> <值>` | 修改配置；另有 `get` / `unset` / `edit` / `path` / `init` |
+| `bb-sync browser status` | 查看后台浏览器是否在运行（`--keep-open` 留下的实例） |
+| `bb-sync browser stop` | 关闭后台浏览器（登录态保留） |
+| `bb-sync doctor` | 检查环境是否就绪（`--skip-network` 跳过网络检查） |
+| `bb-sync --help` | 查看完整帮助 |
+
+`--headed` / `--keep-open` 对 `bb-sync due` 同样适用。用 `--course` 时，`due.md` 会被整份重写为所选课程的待办，其他课程的条目不会保留。
+
+## 遇到问题
+
+- **`bb-sync` 找不到**：重开终端，或执行 `uv tool update-shell`。
+- **连不上 Blackboard**：校外也能直接访问，不需要学校 VPN；先运行 `bb-sync doctor` 看网络那一项，多数是本机代理无法转发 HTTPS 导致的，关掉代理再试一次。
+- **环境检查不通过**：按 `bb-sync doctor` 的提示安装或配置缺失项。
+- **想留住浏览器窗口**：默认跑完会自动关；用 `--headed --keep-open` 才会保留可见窗口，之后用 `bb-sync browser status` 看状态、`bb-sync browser stop` 关闭（不影响登录态）。
+- **登录失败**：运行 `bb-sync auth status` 查看凭据，再用 `bb-sync run --headed` 重试。
+- **更换密码**：重新运行 `bb-sync auth login`。
+- **换账号 / 彻底退出登录**：`bb-sync auth logout` 只删除钥匙串里的凭据，浏览器 profile 里的登录态仍然有效；先 `bb-sync browser stop`，再删除 `~/.bb-sync/.browser-profile/`。要换账号，重新运行 `bb-sync auth login` 录入新账号。
+
+更多问题欢迎[开 Issue](https://github.com/asdukw/cuhk-shenzhen-blackboard-sync/issues)。
+
+## 文档
+
+- [docs/config.md](docs/config.md)：配置文件、目录映射与全部配置项
+- [docs/scripting.md](docs/scripting.md)：`--json` 输出结构与退出码，方便接脚本
+- [CONTRIBUTING.md](CONTRIBUTING.md)：开发流程与质量门禁
+- [CHANGELOG.md](CHANGELOG.md)：版本变更记录
+
+## 免责声明
+
+本工具只读取你自己账号里本来就能看到的内容，登录凭据保存在本机系统钥匙串中，不会上传到任何第三方。命令成功后会检查新版本，结果缓存 24 小时，每天最多请求一次 GitHub Releases API。请求只发送 `bb-sync/<版本号>` 作为 User-Agent，不携带任何个人信息。设置环境变量 `BB_SYNC_NO_UPDATE_CHECK=1` 可关闭该检查。
+
+课程资料版权归香港中文大学（深圳）及各任课教师所有，**仅供个人学习使用，请勿二次分发**。使用本工具产生的一切后果由使用者自行承担。
+
+## License
+
+[MIT](LICENSE)