bb-sync 1.9.0__py3-none-any.whl

bb_sync/core/update.py

@@ -0,0 +1,286 @@
+"""检查 bb-sync 是否有新版本，并在落后时提示用户升级。
+
+更新检查属于「锦上添花」的非关键路径，必须满足三条约束：
+
+- **绝不阻塞/破坏主命令**：网络、缓存或 GitHub API 异常都静默忽略；
+- **不频繁访问网络**：结果（含失败）缓存到 ``BB_SYNC_HOME/update-check.json``，
+  默认 24 小时内不重复检查；
+- **不污染 stdout**：提示通过 :class:`~bb_sync.core.output.Console` 写 stderr，
+  ``--json`` 的 stdout 仍然只有命令结果。
+
+只在普通命令成功返回后调用本模块；``--help`` / ``--version`` / 无参数等早退路径
+不会触发网络请求。
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import re
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+from urllib import error, request
+
+from bb_sync import __version__, paths
+
+if TYPE_CHECKING:  # 仅用于类型标注，运行时由 Console 自己惰性导入 rich
+    from bb_sync.core.output import Console
+
+#: GitHub 最新 release API。仓库是 bb-sync 的唯一发布入口。
+RELEASES_API = "https://api.github.com/repos/asdukw/cuhk-shenzhen-blackboard-sync/releases/latest"
+
+#: 更新检查缓存文件（放在用户运行时目录，不写当前工作目录）。
+CACHE_NAME = "update-check.json"
+
+#: 同一版本检查结果的缓存时长：一天最多访问一次 GitHub。
+CACHE_TTL_SECONDS = 24 * 60 * 60
+
+#: 单次 HTTP 请求超时；更新检查不应明显拖慢 CLI 退出。
+REQUEST_TIMEOUT_SECONDS = 2.0
+
+#: 设置该环境变量为非空值时关闭自动更新检查（主要供脚本 / CI 使用）。
+DISABLE_ENV = "BB_SYNC_NO_UPDATE_CHECK"
+
+_VERSION_RE = re.compile(r"^[vV]?(\d+(?:\.\d+)*)")
+_SOURCE_DEV_VERSION = "0.0.0.dev0"
+
+
+@dataclass(frozen=True)
+class ReleaseInfo:
+    """GitHub 最新 release 的规范化信息。"""
+
+    version: str
+    tag: str
+    url: str
+
+
+@dataclass(frozen=True)
+class UpdateInfo:
+    """调用方需要展示的「当前版本 → 最新版本」信息。"""
+
+    current: str
+    latest: str
+    release_url: str
+
+
+def _version_key(value: str) -> tuple[int, ...] | None:
+    """把 ``v1.2.3`` 这类版本号转成可比较的数字元组。
+
+    只支持本项目使用的语义化数字版本；遇到无法识别的字符串时返回 ``None``，
+    让调用方安静跳过，而不是猜一个可能错误的比较结果。
+    """
+    match = _VERSION_RE.match(value.strip())
+    if match is None:
+        return None
+    try:
+        return tuple(int(part) for part in match.group(1).split("."))
+    except ValueError:  # pragma: no cover - 正则已限制为数字与点
+        return None
+
+
+def is_outdated(current: str, latest: str) -> bool:
+    """判断 ``current`` 是否严格落后于 ``latest``。"""
+    current_key = _version_key(current)
+    latest_key = _version_key(latest)
+    if current_key is None or latest_key is None:
+        return False
+
+    width = max(len(current_key), len(latest_key))
+    current_padded = current_key + (0,) * (width - len(current_key))
+    latest_padded = latest_key + (0,) * (width - len(latest_key))
+    return current_padded < latest_padded
+
+
+def _normalize_version(value: str) -> str | None:
+    """去掉版本号开头的 ``v``，并校验其格式。"""
+    normalized = value.strip()
+    if normalized[:1] in {"v", "V"}:
+        normalized = normalized[1:]
+    return normalized if _version_key(normalized) is not None else None
+
+
+def _release_url(version: str, tag: str | None = None) -> str:
+    """GitHub release 页面地址；API 没给 html_url 时兜底生成。"""
+    return f"https://github.com/asdukw/cuhk-shenzhen-blackboard-sync/releases/tag/{tag or f'v{version}'}"
+
+
+def _disabled() -> bool:
+    """是否通过环境变量关闭更新检查。"""
+    return bool(os.environ.get(DISABLE_ENV, "").strip())
+
+
+def fetch_latest_release(timeout: float = REQUEST_TIMEOUT_SECONDS) -> ReleaseInfo | None:
+    """请求 GitHub 最新 release；任何失败都返回 ``None``。"""
+    req = request.Request(
+        RELEASES_API,
+        headers={
+            "Accept": "application/vnd.github+json",
+            "User-Agent": f"bb-sync/{__version__}",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    )
+    try:
+        with request.urlopen(req, timeout=timeout) as response:
+            payload = json.load(response)
+    except (OSError, error.URLError, ValueError):
+        return None
+
+    if not isinstance(payload, dict):
+        return None
+    tag = payload.get("tag_name")
+    if not isinstance(tag, str):
+        return None
+    version = _normalize_version(tag)
+    if version is None:
+        return None
+
+    html_url = payload.get("html_url")
+    if not isinstance(html_url, str) or not html_url:
+        html_url = _release_url(version, tag)
+    return ReleaseInfo(version=version, tag=tag, url=html_url)
+
+
+def _cache_path() -> Path:
+    """缓存文件路径；每次调用都从 ``paths`` 读取，方便测试隔离。"""
+    return paths.BB_SYNC_HOME / CACHE_NAME
+
+
+def _read_cache() -> dict[str, Any] | None:
+    """读取缓存；文件缺失、损坏或类型不对时都视为没有缓存。"""
+    try:
+        payload = json.loads(_cache_path().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _write_cache(*, checked_at: float, release: ReleaseInfo | None) -> None:
+    """原子写入缓存；写入失败不影响调用方。"""
+    payload: dict[str, Any] = {"checked_at": checked_at}
+    if release is None:
+        payload["latest_version"] = None
+    else:
+        payload.update(
+            {
+                "latest_version": release.version,
+                "tag_name": release.tag,
+                "release_url": release.url,
+            }
+        )
+
+    cache_path = _cache_path()
+    tmp_path = cache_path.with_suffix(cache_path.suffix + ".tmp")
+    try:
+        cache_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp_path.write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")
+        tmp_path.replace(cache_path)
+    except OSError:
+        # 用户目录只读等情况下仍允许主命令正常执行；下次再尝试检查。
+        with contextlib.suppress(OSError):
+            tmp_path.unlink(missing_ok=True)
+
+
+def _cache_release(payload: dict[str, Any]) -> ReleaseInfo | None:
+    """从缓存 JSON 还原 release；非法字段按无缓存处理。"""
+    version = payload.get("latest_version")
+    if not isinstance(version, str):
+        return None
+    normalized = _normalize_version(version)
+    if normalized is None:
+        return None
+
+    tag = payload.get("tag_name")
+    if not isinstance(tag, str) or not tag:
+        tag = f"v{normalized}"
+    url = payload.get("release_url")
+    if not isinstance(url, str) or not url:
+        url = _release_url(normalized, tag)
+    return ReleaseInfo(version=normalized, tag=tag, url=url)
+
+
+def _cache_checked_at(payload: dict[str, Any]) -> float | None:
+    checked_at = payload.get("checked_at")
+    if not isinstance(checked_at, (int, float)):
+        return None
+    return float(checked_at)
+
+
+def check_for_update(
+    *,
+    current: str | None = None,
+    now: float | None = None,
+    timeout: float = REQUEST_TIMEOUT_SECONDS,
+) -> UpdateInfo | None:
+    """返回更新信息；没有新版本、已禁用或检查失败时返回 ``None``。
+
+    ``current`` / ``now`` / ``timeout`` 主要供测试注入；生产调用使用默认值。
+    """
+    current_version = current or __version__
+    # 源码直跑或开发版不提示更新：版本号本身不代表一个可升级的用户安装。
+    if current_version == _SOURCE_DEV_VERSION or _disabled():
+        return None
+
+    checked_now = time.time() if now is None else now
+    cache = _read_cache()
+    if cache is not None:
+        cached_at = _cache_checked_at(cache)
+        cached_release = _cache_release(cache)
+        if cached_at is not None and 0 <= checked_now - cached_at < CACHE_TTL_SECONDS:
+            return _outdated_info(current_version, cached_release)
+    else:
+        cached_release = None
+
+    release = fetch_latest_release(timeout=timeout)
+    if release is None:
+        # 网络失败也写缓存，避免离线用户每次执行命令都等待超时；若之前拿到过
+        # 最新的版本号，则保留它，只更新检查时间（旧 release 不会倒退）。
+        _write_cache(checked_at=checked_now, release=cached_release)
+        return _outdated_info(current_version, cached_release)
+
+    _write_cache(checked_at=checked_now, release=release)
+    return _outdated_info(current_version, release)
+
+
+def _outdated_info(current: str, release: ReleaseInfo | None) -> UpdateInfo | None:
+    """把内部 release 转换为调用方需要展示的更新信息。"""
+    if release is None or not is_outdated(current, release.version):
+        return None
+    return UpdateInfo(current=current, latest=release.version, release_url=release.url)
+
+
+def notify_if_outdated(
+    console: Console,
+    *,
+    current: str | None = None,
+    now: float | None = None,
+    timeout: float = REQUEST_TIMEOUT_SECONDS,
+) -> UpdateInfo | None:
+    """检查并输出更新提示；异常一律吞掉，绝不改变主命令结果。"""
+    try:
+        info = check_for_update(current=current, now=now, timeout=timeout)
+    except Exception:  # 更新检查是附加功能，不能影响正常命令
+        return None
+
+    if info is None:
+        return None
+    console.warn(f"bb-sync 有新版本：当前 {info.current}，最新 {info.latest}")
+    console.hint(f"运行 uv tool upgrade bb-sync 更新；详情见 {info.release_url}")
+    return info
+
+
+__all__ = [
+    "CACHE_NAME",
+    "CACHE_TTL_SECONDS",
+    "DISABLE_ENV",
+    "RELEASES_API",
+    "REQUEST_TIMEOUT_SECONDS",
+    "ReleaseInfo",
+    "UpdateInfo",
+    "check_for_update",
+    "fetch_latest_release",
+    "is_outdated",
+    "notify_if_outdated",
+]

bb_sync/creds.py

@@ -0,0 +1,91 @@
+"""凭据存储：仅使用系统钥匙串（keyring），不在任何文件里落明文。
+
+- 钥匙串：Windows 凭据管理器 / macOS 钥匙串 / Linux Secret Service，
+  凭据以 JSON 存在服务 ``"bb-sync"`` 下，不落明文文件。
+- 不再支持 ``.env`` 兜底：明文凭据容易误提交或泄漏，一律走钥匙串。
+  若钥匙串在无桌面环境不可用，请改用交互式录入以外的部署方式。
+"""
+
+from __future__ import annotations
+
+import json
+from typing import NamedTuple
+
+import keyring
+import keyring.errors
+
+SERVICE = "bb-sync"
+ACCOUNT = "credentials"
+
+
+class Credentials(NamedTuple):
+    student_id: str
+    password: str
+    source: str  # 目前恒为 "keyring"
+
+    @property
+    def ok(self) -> bool:
+        """两项都非空才算可用。"""
+        return bool(self.student_id and self.password)
+
+
+def load_credentials() -> Credentials:
+    """从系统钥匙串读取凭据；不存在或读取失败时返回空凭据。"""
+    try:
+        blob = keyring.get_password(SERVICE, ACCOUNT)
+    except keyring.errors.KeyringError:
+        blob = None
+    if not blob:
+        return Credentials("", "", "keyring")
+    try:
+        data = json.loads(blob)
+    except json.JSONDecodeError:
+        data = {}
+    return Credentials(data.get("student_id", ""), data.get("password", ""), "keyring")
+
+
+def save_credentials(student_id: str, password: str) -> str:
+    """凭据存入系统钥匙串，返回实际使用的后端名称。"""
+    keyring.set_password(
+        SERVICE,
+        ACCOUNT,
+        json.dumps({"student_id": student_id, "password": password}),
+    )
+    return str(keyring.get_keyring())
+
+
+def delete_credentials() -> bool:
+    """从钥匙串删除凭据；不存在时返回 False。"""
+    if keyring.get_password(SERVICE, ACCOUNT) is None:
+        return False
+    keyring.delete_password(SERVICE, ACCOUNT)
+    return True
+
+
+def has_keyring_credentials() -> bool:
+    """钥匙串里是否已有凭据（不读取明文内容）。"""
+    try:
+        return keyring.get_password(SERVICE, ACCOUNT) is not None
+    except keyring.errors.KeyringError:
+        return False
+
+
+def mask(secret: str, tail: int = 4) -> str:
+    """脱敏显示：只保留尾部若干位，其余用 * 替代。"""
+    if not secret:
+        return ""
+    if len(secret) <= tail:
+        return "*" * len(secret)
+    return "*" * (len(secret) - tail) + secret[-tail:]
+
+
+__all__ = [
+    "ACCOUNT",
+    "SERVICE",
+    "Credentials",
+    "delete_credentials",
+    "has_keyring_credentials",
+    "load_credentials",
+    "mask",
+    "save_credentials",
+]

bb_sync/paths.py

@@ -0,0 +1,26 @@
+"""路径解析：兼容「源码运行」与「安装为 CLI」两种形态。
+
+用户文件（config.yaml）查找顺序：当前工作目录优先（项目内用法），
+其次 ~/.bb-sync/（安装后的用户配置目录）。运行时目录（Steel、浏览器
+profile、日志、调试产物）统一放 ~/.bb-sync/，可用环境变量 BB_SYNC_HOME 覆盖。
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+BB_SYNC_HOME = Path(os.environ.get("BB_SYNC_HOME") or Path.home() / ".bb-sync")
+
+CONFIG_NAME = "config.yaml"
+
+
+def find_config_file(name: str = CONFIG_NAME) -> Path:
+    """查找用户配置文件：当前工作目录优先，其次 ~/.bb-sync/。"""
+    cwd_candidate = Path.cwd() / name
+    if cwd_candidate.exists():
+        return cwd_candidate
+    return BB_SYNC_HOME / name
+
+
+__all__ = ["BB_SYNC_HOME", "CONFIG_NAME", "find_config_file"]

bb_sync-1.9.0.dist-info/METADATA

@@ -0,0 +1,265 @@
+Metadata-Version: 2.5
+Name: bb-sync
+Version: 1.9.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
+Project-URL: Issues, https://github.com/asdukw/cuhk-shenzhen-blackboard-sync/issues
+Project-URL: Changelog, https://github.com/asdukw/cuhk-shenzhen-blackboard-sync/blob/main/CHANGELOG.md
+License: MIT License
+        
+        Copyright (c) 2026 bb-sync contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: adfs,blackboard,cli,course,course-download,cuhk-shenzhen,cuhksz,playwright,scraper,sync
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Requires-Python: >=3.11
+Requires-Dist: click>=8.5.0
+Requires-Dist: keyring>=25.7.0
+Requires-Dist: playwright>=1.45
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# bb-sync
+
+**港中深（香港中文大学·深圳 / CUHK-Shenzhen / CUHKSZ）Blackboard 课件下载与课程资源自动同步 CLI**
+
+登录 `bb.cuhk.edu.cn`，把课件、作业和指导增量下载到本地，把公告和全部课程的待办整理成 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`；
+- 全部课程的待办汇总成一份 `due.md`，按「已逾期 → 今天 → 明天 → 未来 7 天 → 之后」排好序，公告里带日期的课堂测验和考试也一并计入。
+
+它**不做**这些：不回传作业、不代签到、不抓成绩、不绕过任何权限——看到的就是你账号里本来能看到的。
+
+## 长什么样
+
+下面是示例输出（课程名和文件名为虚构，链接已缩写为 `…`，实际每条都带回到对应 Blackboard 课程页的链接）。
+
+`due.md`：
+
+````markdown
+# Blackboard 待办
+
+> 更新时间：2026-10-14 21:03（本地时间）
+> 已检查 5 门课程，发现 7 项待办；按优先级和截止日期排列。
+> 其中公告里的测验 1 项、考试 1 项已一并作为待办列出。
+> 另有 1 项公告里的测验/考试日期已过，列在最后仅供回看。
+
+## 已逾期（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 天（3）
+
+- **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/…) — 【考试】期中考试
+
+## 已过期事件（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、Node.js 22+（含 npm）、uv 和 Chrome 或 Edge。bb-sync 会自动探测常见安装位置。
+
+### Windows
+
+在 PowerShell 中执行：
+
+```powershell
+winget install --id Git.Git -e
+winget install --id OpenJS.NodeJS.LTS -e
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Windows 自带的 Edge 即可使用；也可以自行安装 Google Chrome。
+
+### macOS
+
+推荐先安装 [Homebrew](https://brew.sh/)，再执行：
+
+```bash
+brew install git node uv
+brew install --cask google-chrome
+```
+
+如果已经安装 Chrome 或 Edge，可跳过最后一条。Edge 的 cask 名称为 `microsoft-edge`。
+
+### 安装 bb-sync（Windows / macOS 相同）
+
+**重开终端**后执行：
+
+```bash
+uv tool install bb-sync
+bb-sync doctor
+```
+
+也可以直接从 GitHub 安装（跟随 `main` 上的最新代码）：
+
+```bash
+uv tool install git+https://github.com/asdukw/cuhk-shenzhen-blackboard-sync
+```
+
+`bb-sync doctor` 用于检查环境；刚安装时凭据或浏览器后端显示“未配置”是正常的。如果提示找不到 `bb-sync`，执行 `uv tool update-shell` 后重开终端。校外使用 Blackboard 时，可能需要先连接学校 VPN。
+
+## 首次使用
+
+保存学号和密码：
+
+```bash
+bb-sync auth login
+```
+
+密码会保存在 Windows 凭据管理器或 macOS 钥匙串，不会写入配置文件。macOS 首次访问时可能弹出钥匙串授权提示，选择允许即可。
+
+第一次同步请显示浏览器，便于完成登录、MFA 或验证码：
+
+```bash
+bb-sync run --headed
+```
+
+首次运行会自动准备浏览器后端，可能需要几分钟。保持网络连接，不要提前关闭终端。之后同步直接运行：
+
+```bash
+bb-sync run
+```
+
+## 文件位置
+
+默认下载到用户主目录下的 `courses`：
+
+- Windows：`C:\Users\<你>\courses`
+- macOS：`/Users/<你>/courses`
+
+每门课一个文件夹：
+
+- 课件 → `lectures/`
+- 作业 → `assignments/`
+- 指导 / 实验 → `tutorials/`
+- 公告 → `announcements.md`
+- 全部课程待办 → `due.md`（按优先级排列；公告里带日期的课堂测验与考试也计入，日期已过的归入最后的「已过期事件」并保留 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` | 显示浏览器，适合首次登录或 MFA |
+| `bb-sync run --course CSC5010` | 只同步指定课程，可重复使用 |
+| `bb-sync run --dry-run` | 预览下载和待办，不写文件 |
+| `bb-sync due` | 扫描全部课程主页的 Due / To Do 与公告测验、考试，生成 `due.md` |
+| `bb-sync due --course CSC5010` | 只整理指定课程的待办 |
+| `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 doctor` | 检查环境是否就绪 |
+| `bb-sync --help` | 查看完整帮助 |
+
+## 遇到问题
+
+- **`bb-sync` 找不到**：重开终端，或执行 `uv tool update-shell`。
+- **环境检查不通过**：按 `bb-sync doctor` 的提示安装或配置缺失项。
+- **第一次运行很慢**：首次需要准备浏览器后端，耐心等待。
+- **登录失败或需要 MFA**：运行 `bb-sync auth status` 查看凭据，再用 `bb-sync run --headed` 重试。
+- **更换密码**：重新运行 `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) —— 版本变更记录
+
+## 免责声明
+
+本工具只读取你自己账号里本来就能看到的内容，登录凭据保存在本机系统钥匙串中，不会上传到任何第三方。命令成功后会请求一次 GitHub Releases API 检查新版本，只发送 `bb-sync/<版本号>` 作为 User-Agent，不携带任何个人信息；设置环境变量 `BB_SYNC_NO_UPDATE_CHECK=1` 可关闭该检查。课程资料版权归香港中文大学（深圳）及各任课教师所有，**仅供个人学习使用，请勿二次分发**。使用本工具产生的一切后果由使用者自行承担。
+
+## License
+
+[MIT](LICENSE)