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

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

@@ -2,6 +2,37 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [2.2.0] — 2026-10-31
+
+### 修复
+
+- **公告里的考试日期跨行也能读到**：此前只取关键词同段内的日期，遇到
+  `Midterm Exam Information` 换行、空行后才写 `Date: November 1` 的公告会整条漏掉
+  （DDA5002、MDS5020 的期中就是这样漏报的）。现在在关键词之后 240 字符内查找，
+  允许跨段，仍只取关键词之后的日期。
+- **公告里的作业 deadline 计入待办**：新增 `assignment` 类型，逐行识别「日期 +
+  due / deadline / submit / 截止 / 提交」的截止行，并要求能认出 `HW4` /
+  `Assignment 2` 这类作业名；没名字的日期不收录。公告推断的作业逾期仍留在
+  「已逾期」（可能还没交），不像考完的考试那样归档。
+- **To Do 与公告条目去重**：同一课程、同一天、标题指向同一件事时保留 To Do 模块
+  那份，公告推断的重复条目丢弃（如 MDS5020 的 Coding Assignment 2）。
+- **`due.md` 内容没变时不再重写**：比较时忽略「更新时间」行，避免每次运行都产生
+  只有时间戳的 diff；终端会提示「内容未变，未重写」。
+
+### 新增
+
+- **`due.md` 支持勾选完成**：每条待办渲染为 GFM 任务列表 `- [ ]`，手动改成
+  `- [x]` 后下次同步按「日期 + 课程 + 标题」认回同一条并保留完成状态——签名不含
+  「还有 N 天」这类每天变化的相对时间，跨天同步也不会丢。
+
+## [2.1.1] — 2026-10-31
+
+### 变更
+
+- `run` / `due` 不再逐课程打印「待办 xN，公告测验/考试 xM」：这几行与末尾的
+  「待办明细」定位重复，只有计数、看不到内容。待办结果统一在「待办明细」与
+  `due.md` 中呈现；抓取失败仍会即时告警。
+
 ## [2.1.0] — 2026-10-31
 
 ### 新增

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bb-sync
-Version: 2.1.0
+Version: 2.2.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
@@ -72,7 +72,7 @@ Blackboard 上的东西散在「课程内容」「作业」「公告」几个入
 
 - 课件、作业、指导按课程归好类，重跑只下新增的；
 - 每门课的公告存成一份 `announcements.md`；
-- 全部课程的待办汇总成一份 `due.md`，按「已逾期 → 今天 → 明天 → 未来 7 天 → 之后」排好序，公告里带日期的课堂测验和考试也一并计入。
+- 全部课程的待办汇总成一份 `due.md`，按「已逾期 → 今天 → 明天 → 未来 7 天 → 之后」排好序，公告里带日期的课堂测验、考试和作业截止时间也一并计入；每条待办都是可勾选的任务列表（`- [ ]`），做完勾上 `- [x]`，下次同步会保留完成状态。
 
 它**不做**这些：不回传作业、不代签到、不抓成绩、不绕过任何权限——看到的就是你账号里本来能看到的。
 
@@ -217,7 +217,7 @@ bb-sync run
 - 作业 → `assignments/`
 - 指导 / 实验 → `tutorials/`
 - 公告 → `announcements.md`
-- 全部课程待办 → `due.md`（按优先级排列；公告里带日期的课堂测验与考试也计入，日期已过的归入最后的「已过期事件」并保留 7 天，没有待办时显示 Congratulations）
+- 全部课程待办 → `due.md`（按优先级排列；公告里带日期的课堂测验、考试和作业截止时间也计入，考完的测验 / 考试归入最后的「已过期事件」并保留 7 天；每条待办带 `- [ ]` 复选框，勾选状态跨次同步保留；内容没变化时不重写，没有待办时显示 Congratulations）
 
 要修改下载目录：
 

{bb_sync-2.1.0 → bb_sync-2.2.0}/README.md

@@ -21,7 +21,7 @@ Blackboard 上的东西散在「课程内容」「作业」「公告」几个入
 
 - 课件、作业、指导按课程归好类，重跑只下新增的；
 - 每门课的公告存成一份 `announcements.md`；
-- 全部课程的待办汇总成一份 `due.md`，按「已逾期 → 今天 → 明天 → 未来 7 天 → 之后」排好序，公告里带日期的课堂测验和考试也一并计入。
+- 全部课程的待办汇总成一份 `due.md`，按「已逾期 → 今天 → 明天 → 未来 7 天 → 之后」排好序，公告里带日期的课堂测验、考试和作业截止时间也一并计入；每条待办都是可勾选的任务列表（`- [ ]`），做完勾上 `- [x]`，下次同步会保留完成状态。
 
 它**不做**这些：不回传作业、不代签到、不抓成绩、不绕过任何权限——看到的就是你账号里本来能看到的。
 
@@ -166,7 +166,7 @@ bb-sync run
 - 作业 → `assignments/`
 - 指导 / 实验 → `tutorials/`
 - 公告 → `announcements.md`
-- 全部课程待办 → `due.md`（按优先级排列；公告里带日期的课堂测验与考试也计入，日期已过的归入最后的「已过期事件」并保留 7 天，没有待办时显示 Congratulations）
+- 全部课程待办 → `due.md`（按优先级排列；公告里带日期的课堂测验、考试和作业截止时间也计入，考完的测验 / 考试归入最后的「已过期事件」并保留 7 天；每条待办带 `- [ ]` 复选框，勾选状态跨次同步保留；内容没变化时不重写，没有待办时显示 Congratulations）
 
 要修改下载目录：
 

{bb_sync-2.1.0 → bb_sync-2.2.0}/docs/scripting.md

@@ -121,9 +121,11 @@ esac
 > **提示**：`bb-sync run` 的诊断信息（含「同步计划」）全部走 stderr，
 > 所以 `--json` 模式下 stdout 依然干净，可以放心重定向。
 >
-> 正常模式下 `bb-sync run` 还会生成或更新 `<root>/due.md`（含公告里带日期的课堂测验与考试；
-> 日期已过的测验 / 考试归入最后的「已过期事件」，保留 7 天后不再收录）；
-> `--dry-run` 只统计待办，不会写文件。
+> 正常模式下 `bb-sync run` 还会生成或更新 `<root>/due.md`（含公告里带日期的课堂测验、
+> 考试与作业 deadline；考完的测验 / 考试归入最后的「已过期事件」，保留 7 天后不再收录；
+> 每条待办是可勾选的任务列表 `- [ ]`，手动改成 `- [x]` 后下次同步会按「日期 + 课程 +
+> 标题」认回同一条并保留勾选；内容没有变化时不重写文件，避免只产生一行「更新时间」的
+> diff）；`--dry-run` 只统计待办，不会写文件。
 
 ## 相关
 

{bb_sync-2.1.0 → bb_sync-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bb-sync"
-version = "2.1.0"
+version = "2.2.0"
 description = "港中深（CUHK-Shenzhen）Blackboard 课件下载与课程资源自动同步：登录 ADFS SSO，增量下载课件/作业/指导、公告与待办"
 readme = "README.md"
 license = { file = "LICENSE" }

{bb_sync-2.1.0 → bb_sync-2.2.0}/src/bb_sync/blackboard/scraper.py

@@ -375,6 +375,16 @@ _ANNOUNCEMENT_KIND_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
     ("quiz", _QUIZ_RE),
 )
 
+#: 公告里的作业 / 项目编号（HW4、Assignment 2、Project 3）。只有能认出这类名字的
+#: 截止行才会变成待办：一条公告里带日期的句子太多，没名字的日期分不清是什么事。
+_ASSIGNMENT_NAME_RE = re.compile(
+    r"\b(?:homework|hw|assignment|project|lab)\s*(?:assignment\s*)?#?\s*\d{1,2}\b",
+    re.IGNORECASE,
+)
+
+#: 截止表达；与日期出现在同一行才算作业 deadline。
+_DEADLINE_RE = re.compile(r"\b(?:due|deadline|submit|submission)\b|截止|提交", re.IGNORECASE)
+
 #: 关键词之后最多检查这么多字符，避免把远处的日期牵强算成考试/测验日期。
 _KEYWORD_DATE_WINDOW = 240
 
@@ -481,8 +491,11 @@ def _extract_keyword_date(
 ) -> date | None:
     """从公告里定位关键词附近的日期。
 
-    只看标题与正文中关键词之后、同一段内的日期：日期必须写在测验 / 考试
-    名称后面，避免把关键词之前的作业截止日期误当成考试日期。
+    只取关键词**之后** ``_KEYWORD_DATE_WINDOW`` 个字符内的日期：日期必须写在
+    测验 / 考试名称后面，避免把关键词之前的作业截止日期误当成考试日期。
+
+    不按空行截断：常见写法是「标题一行 + 空行 + Date: …」（期中考试公告尤其如此），
+    截断到第一段会把紧跟着的考试日期丢掉——DDA5002 / MDS5020 的期中就是这样漏报的。
     """
     reference = posted or date.today()
     if pattern.search(title):
@@ -492,9 +505,6 @@ def _extract_keyword_date(
     text = f"{title}\n{body}" if body else title
     for match in pattern.finditer(text):
         window = text[match.end() : match.end() + _KEYWORD_DATE_WINDOW]
-        para_end = window.find("\n\n")
-        if para_end >= 0:
-            window = window[:para_end]
         chosen = _pick_future_date(_find_dates(window, reference), posted)
         if chosen:
             return chosen
@@ -512,11 +522,18 @@ def _announcement_label_from_body(body: str, pattern: re.Pattern[str]) -> str:
 def parse_announcement_due_items(
     entries: list[dict[str, str]], course: Course, *, today: date | None = None
 ) -> list[DueItem]:
-    """把公告里带日期的课堂测验与考试整理成待办条目。
+    """把公告里可预期的日期整理成待办条目。
+
+    两类来源：
+
+    - **测验 / 考试**：命中关键词后取关键词之后的日期（见 :func:`_extract_keyword_date`）；
+    - **作业 deadline**：逐行找同时含日期与截止表达的行，并要求行内（或上一行、
+      公告标题）能认出 ``HW4`` / ``Assignment 2`` 这类作业名。没有名字的日期太容易
+      是别的事情，宁可不收。
 
     读不出日期、日期早于公告发布时间、或日期已过去超过 ``_PAST_EVENT_RETENTION_DAYS``
-    天的公告一律跳过：宁可不收录，也不要把「复习资料里提到 quiz」误当成待办；
-    已经考完的测验 / 考试只值得回看，不该继续占着待办位。
+    天的条目一律跳过：避免把「复习资料里提到 quiz」误当成待办；已经考完的测验 / 考试
+    只值得回看，不该继续占着待办位。
     """
     oldest = (today or date.today()) - timedelta(days=_PAST_EVENT_RETENTION_DAYS)
     items: list[DueItem] = []
@@ -526,32 +543,85 @@ def parse_announcement_due_items(
         body = _clean_announcement_text(str(entry.get("body_markdown") or entry.get("body") or ""))
         if not title and not body:
             continue
-        matched = _announcement_kind(f"{title}\n{body}" if body else title)
-        if matched is None:
-            continue
-        kind, pattern = matched
         posted = parse_announcement_date(str(entry.get("posted_on") or ""))
-        due_date = _extract_keyword_date(title, body, posted, pattern)
-        if due_date is None or due_date < oldest:
-            continue
-        label = title or _announcement_label_from_body(body, pattern) or course.code or course.title
-        key = (due_date.isoformat(), label.casefold())
-        if key in seen:
-            continue
-        seen.add(key)
-        items.append(
-            DueItem(
-                course_id=course.bb_id,
-                course_code=course.code,
-                course_title=course.title,
-                title=label,
-                due_date=due_date,
-                kind=kind,
-            )
-        )
+
+        matched = _announcement_kind(f"{title}\n{body}" if body else title)
+        if matched is not None:
+            kind, pattern = matched
+            due_date = _extract_keyword_date(title, body, posted, pattern)
+            if due_date is not None and due_date >= oldest:
+                label = (
+                    title
+                    or _announcement_label_from_body(body, pattern)
+                    or course.code
+                    or course.title
+                )
+                _append_announcement_item(items, seen, course, label, due_date, kind)
+
+        for due_date, label in _extract_assignment_deadlines(title, body, posted):
+            if due_date >= oldest:
+                _append_announcement_item(items, seen, course, label, due_date, "assignment")
     return items
 
 
+def _append_announcement_item(
+    items: list[DueItem],
+    seen: set[tuple[str, str]],
+    course: Course,
+    label: str,
+    due_date: date,
+    kind: str,
+) -> None:
+    """按「日期 + 标题」去重后新增条目（同一公告里两处提到同一件事只留一条）。"""
+    key = (due_date.isoformat(), label.casefold())
+    if key in seen:
+        return
+    seen.add(key)
+    items.append(
+        DueItem(
+            course_id=course.bb_id,
+            course_code=course.code,
+            course_title=course.title,
+            title=label,
+            due_date=due_date,
+            kind=kind,
+        )
+    )
+
+
+def _assignment_label(line: str, previous: str, title: str) -> str | None:
+    """从截止行、上一行或公告标题里取出作业名；都认不出时返回 None。
+
+    上一行的兜底对应「小节标题 + 单独一行 Deadline」的写法，例如
+    ``2. Coding Assignment 2 Release`` 下面才是 ``- Deadline: 23:59, November 2, 2026``。
+    """
+    for source in (line, previous, title):
+        match = _ASSIGNMENT_NAME_RE.search(source)
+        if match:
+            return match.group(0).strip()
+    return None
+
+
+def _extract_assignment_deadlines(
+    title: str, body: str, posted: date | None
+) -> list[tuple[date, str]]:
+    """逐行找出「日期 + 截止表达 + 可识别作业名」的作业 deadline。"""
+    reference = posted or date.today()
+    found: list[tuple[date, str]] = []
+    previous = ""
+    for line in body.splitlines():
+        text = line.strip()
+        if not text:
+            continue
+        if _DEADLINE_RE.search(text):
+            dates = _find_dates(text, reference)
+            label = _assignment_label(text, previous, title)
+            if dates and label:
+                found.append((dates[0][1], label))
+        previous = text
+    return found
+
+
 def _clean_announcement_text(value: str) -> str:
     """归一文本：压缩行尾空白，但保留段落和列表产生的换行。"""
     text = value.replace("\xa0", " ").replace("\r\n", "\n").replace("\r", "\n")

bb_sync-2.2.0/src/bb_sync/core/due.py

@@ -0,0 +1,335 @@
+"""把课程 Due / To Do 数据渲染为按优先级排列的 ``due.md``。"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter, defaultdict
+from collections.abc import Collection
+from datetime import date, datetime, timedelta
+from pathlib import Path
+
+from bb_sync.blackboard.models import BASE, Course, DueItem
+
+#: 分组顺序就是学生处理任务的优先级；「已过期事件」只是留档回看，所以排最后。
+_BUCKET_ORDER = ("overdue", "today", "tomorrow", "next_7_days", "future", "unknown", "past_events")
+_BUCKET_LABELS = {
+    "overdue": "已逾期",
+    "today": "今天",
+    "tomorrow": "明天",
+    "next_7_days": "未来 7 天",
+    "future": "之后",
+    "unknown": "日期未知",
+    "past_events": "已过期事件",
+}
+
+#: 非普通任务的待办类型标签（来自公告）；顺序即汇总文案里的出现顺序。
+#: ``assignment`` 是公告里推断出的作业 deadline，和 To Do 模块的普通任务区分开。
+_KIND_LABELS = {"quiz": "测验", "exam": "考试", "assignment": "作业"}
+
+#: 一次性事件：测验 / 考试日期过了只能回看。作业不同——逾期可能只是还没交，
+#: 仍然要留在「已逾期」里提醒。
+_EVENT_KINDS = frozenset({"quiz", "exam"})
+
+
+def kind_label(kind: str) -> str:
+    """返回待办类型的中文标签；普通任务返回空串。"""
+    return _KIND_LABELS.get(kind, "")
+
+
+def _is_past_event(item: DueItem, today: date) -> bool:
+    """公告里的一次性事件（测验 / 考试）日期已过：它只能回看，没法再「做」。
+
+    与 ``overdue`` 的区别：To Do 模块的逾期任务意味着「还没交」，仍然要行动；
+    考完的测验 / 考试已是历史，混进待办里只会淹没真正要做的事。
+    """
+    return item.kind in _EVENT_KINDS and item.due_date is not None and item.due_date < today
+
+
+def _bucket(item: DueItem, today: date) -> str:
+    """按剩余时间归类；无法解析日期的任务放最后，避免被误判成低优先级。"""
+    if item.due_date is None:
+        return "unknown"
+    if _is_past_event(item, today):
+        return "past_events"
+    if item.due_date < today:
+        return "overdue"
+    if item.due_date == today:
+        return "today"
+    if item.due_date == today + timedelta(days=1):
+        return "tomorrow"
+    if item.due_date <= today + timedelta(days=7):
+        return "next_7_days"
+    return "future"
+
+
+def relative_due(item: DueItem, today: date) -> str:
+    """生成截止日期旁的中文提示。"""
+    if item.due_date is None:
+        return item.due_text or "日期未知"
+    delta = (item.due_date - today).days
+    if delta < 0:
+        # 逾期的作业 / To Do 是「还没交」，公告里的测验 / 考试是「已经考过」，措辞分开。
+        return f"已过 {-delta} 天" if item.kind in _EVENT_KINDS else f"逾期 {-delta} 天"
+    if delta == 0:
+        return "今天"
+    if delta == 1:
+        return "明天"
+    return f"还有 {delta} 天"
+
+
+def _escape_markdown(text: str) -> str:
+    """转义会改变 Markdown 结构的常见字符，同时保留可读标题。"""
+    text = re.sub(r"\s+", " ", text).strip()
+    return re.sub(r"([\\`*_\[\]])", r"\\\1", text)
+
+
+def _sort_key(item: DueItem) -> tuple[date, str, str]:
+    return (item.due_date or date.max, item.course_label, item.title)
+
+
+def sort_due_items(items: list[DueItem]) -> list[DueItem]:
+    """按截止日期、课程和任务名返回稳定排序的新列表。"""
+    return sorted(items, key=_sort_key)
+
+
+#: 标题分词：拉丁字母串与数字。中文标题走子串包含，见 :func:`_same_event`。
+_TITLE_TOKEN_RE = re.compile(r"[a-z]+|\d+")
+_CJK_RE = re.compile(r"[\u4e00-\u9fff]")
+
+#: 不承载区分度的词，比较「是不是同一件事」时忽略。
+_TITLE_STOPWORDS = frozenset(
+    {
+        "a",
+        "an",
+        "and",
+        "at",
+        "be",
+        "by",
+        "deadline",
+        "due",
+        "for",
+        "in",
+        "is",
+        "new",
+        "of",
+        "on",
+        "release",
+        "released",
+        "reminder",
+        "the",
+        "to",
+        "update",
+        "updated",
+    }
+)
+
+
+def _title_tokens(text: str) -> set[str]:
+    """标题里可用于判重的实义词；纯数字不算（「HW 2」与「Quiz 2」不是同一件事）。"""
+    return {
+        token
+        for token in _TITLE_TOKEN_RE.findall(text.casefold())
+        if token not in _TITLE_STOPWORDS and not token.isdigit()
+    }
+
+
+def _compact(text: str) -> str:
+    """去掉空格与标点，便于中文标题做包含判断。"""
+    return re.sub(r"[^0-9a-z\u4e00-\u9fff]+", "", text.casefold())
+
+
+def _same_event(left: DueItem, right: DueItem) -> bool:
+    """同一课程、同一天、标题指向同一件事 → 视为重复条目。"""
+    same_course = bool(
+        (left.course_id and left.course_id == right.course_id)
+        or (left.course_code and left.course_code == right.course_code)
+    )
+    if not same_course or left.due_date is None or left.due_date != right.due_date:
+        return False
+    if _CJK_RE.search(left.title) or _CJK_RE.search(right.title):
+        a, b = _compact(left.title), _compact(right.title)
+        return bool(a and b and (a in b or b in a))
+    return bool(_title_tokens(left.title) & _title_tokens(right.title))
+
+
+def merge_due_items(todo_items: list[DueItem], announcement_items: list[DueItem]) -> list[DueItem]:
+    """合并 To Do 模块与公告推断的待办，去掉同一件事的重复条目。
+
+    To Do 模块是站点的原生数据，说明更准确（标题、逾期状态都来自 Blackboard），
+    所以冲突时保留它；公告条目只在没有对应 To Do 时补进来。
+    """
+    merged = list(todo_items)
+    merged.extend(
+        item
+        for item in announcement_items
+        if not any(_same_event(item, existing) for existing in todo_items)
+    )
+    return merged
+
+
+#: due.md 里复选框行的形状：``- [ ] …`` / ``- [x] …``。
+_CHECKBOX_LINE_RE = re.compile(r"^- \[(?P<mark>[ xX])\] (?P<body>.*)$")
+
+#: 行内的相对时间（如「还有 3 天」）；每天都会变，不参与勾选状态的匹配。
+_RELATIVE_TIME_RE = re.compile(r"（[^）]*）")
+
+
+def _item_signature(item: DueItem) -> str:
+    """条目的稳定签名：日期 + 课程 + 标题，不含随日期变化的相对时间。
+
+    用户在 due.md 里勾选后，下次运行靠它认回同一条待办并保留 ``[x]``。
+    """
+    due = item.due_date.isoformat() if item.due_date else "日期未知"
+    course_url = f"{BASE}/webapps/blackboard/execute/launcher?type=Course&id={item.course_id}"
+    label = kind_label(item.kind)
+    badge = f"【{label}】" if label else ""
+    return (
+        f"**{due}** — [{_escape_markdown(item.course_label)}]({course_url}) — "
+        f"{badge}{_escape_markdown(item.title)}"
+    )
+
+
+def _checked_signatures(markdown: str) -> set[str]:
+    """从现有 due.md 读出已勾选条目的签名。"""
+    done: set[str] = set()
+    for line in markdown.splitlines():
+        match = _CHECKBOX_LINE_RE.match(line)
+        if not match or match.group("mark").lower() != "x":
+            continue
+        done.add(_RELATIVE_TIME_RE.sub("", match.group("body"), count=1))
+    return done
+
+
+def build_due_markdown(
+    courses: list[Course],
+    items: list[DueItem],
+    *,
+    failed: int = 0,
+    today: date | None = None,
+    generated_at: datetime | None = None,
+    done: Collection[str] = (),
+) -> str:
+    """生成全局 ``due.md`` 文本。
+
+    输出按「已逾期 → 今天 → 明天 → 未来 7 天 → 之后 → 日期未知 → 已过期事件」排序；
+    同一分组内再按日期、课程和任务名稳定排序。
+
+    ``done`` 是已勾选条目的签名集合（见 :func:`_item_signature`），命中的条目会渲染成
+    ``- [x]``；调用方通常从上一版 due.md 里读出它，从而跨次同步保留完成状态。
+    """
+    day = today or date.today()
+    generated = generated_at or datetime.now().astimezone()
+    grouped: dict[str, list[DueItem]] = defaultdict(list)
+    for item in items:
+        grouped[_bucket(item, day)].append(item)
+    for bucket_items in grouped.values():
+        bucket_items.sort(key=_sort_key)
+
+    # 过期事件单独成区，汇总行也不把它算进「待办」，否则「测验 2 项」里混着考完的。
+    past_events = grouped.get("past_events", [])
+    kind_counts = Counter(item.kind for item in items if not _is_past_event(item, day))
+    # 只统计公告整理出的待办，按 _KIND_LABELS 的固定顺序列出（测验 → 考试）。
+    announcement_parts = [
+        f"{label} {kind_counts[kind]} 项"
+        for kind, label in _KIND_LABELS.items()
+        if kind_counts[kind]
+    ]
+    lines = [
+        "# Blackboard 待办",
+        "",
+        f"> 更新时间：{generated.strftime('%Y-%m-%d %H:%M')}（本地时间）",
+        f"> 已检查 {len(courses)} 门课程，发现 {len(items)} 项待办；按优先级和截止日期排列。",
+    ]
+    if announcement_parts:
+        lines.append(f"> 其中公告里的{'、'.join(announcement_parts)}已一并作为待办列出。")
+    if past_events:
+        lines.append(f"> 另有 {len(past_events)} 项公告里的测验/考试日期已过，列在最后仅供回看。")
+    if failed:
+        lines.append(f"> 注意：{failed} 门课程抓取失败，结果可能不完整。")
+    if items:
+        lines.append("> 完成一项就在前面打勾（`- [ ]` → `- [x]`），下次同步会保留完成状态。")
+    lines.append("")
+
+    if not items:
+        if failed:
+            lines.extend(["本次未读取到待办，但由于部分课程抓取失败，结果可能不完整。", ""])
+        else:
+            lines.extend(["## Congratulations! 🎉", "", "当前没有待办事项。", ""])
+        return "\n".join(lines)
+
+    for bucket in _BUCKET_ORDER:
+        bucket_items = grouped.get(bucket, [])
+        if not bucket_items:
+            continue
+        lines.append(f"## {_BUCKET_LABELS[bucket]}（{len(bucket_items)}）")
+        lines.append("")
+        for item in bucket_items:
+            due = item.due_date.isoformat() if item.due_date else "日期未知"
+            course_url = (
+                f"{BASE}/webapps/blackboard/execute/launcher?type=Course&id={item.course_id}"
+            )
+            label = kind_label(item.kind)
+            badge = f"【{label}】" if label else ""
+            box = "[x]" if _item_signature(item) in done else "[ ]"
+            lines.append(
+                f"- {box} **{due}**（{relative_due(item, day)}） — "
+                f"[{_escape_markdown(item.course_label)}]({course_url}) — "
+                f"{badge}{_escape_markdown(item.title)}"
+            )
+        lines.append("")
+    return "\n".join(lines)
+
+
+#: 头部「更新时间」行的前缀；比较内容是否变化时先把它去掉。
+_UPDATE_LINE_PREFIX = "> 更新时间："
+
+
+def _without_timestamp(text: str) -> str:
+    """去掉头部的更新时间行，用于判断待办内容本身有没有变化。"""
+    return "\n".join(line for line in text.splitlines() if not line.startswith(_UPDATE_LINE_PREFIX))
+
+
+def write_due_markdown(
+    path: Path,
+    courses: list[Course],
+    items: list[DueItem],
+    *,
+    failed: int = 0,
+    today: date | None = None,
+    generated_at: datetime | None = None,
+) -> bool:
+    """写入 ``due.md``；父目录不存在时自动创建。返回是否真的写了文件。
+
+    内容（除更新时间外）和现有文件一样时保持原样：每次运行都重写会把「更新时间」
+    一起改掉，即使待办一条没变，git 里也多出一份只有时间戳的 diff。
+    """
+    previous = ""
+    if path.exists():
+        try:
+            previous = path.read_text(encoding="utf-8")
+        except OSError:
+            previous = ""
+    content = build_due_markdown(
+        courses,
+        items,
+        failed=failed,
+        today=today,
+        generated_at=generated_at,
+        # 用户在上一版里勾选的条目，重新生成时保持 [x]
+        done=_checked_signatures(previous),
+    )
+    if previous and _without_timestamp(previous) == _without_timestamp(content):
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return True
+
+
+__all__ = [
+    "build_due_markdown",
+    "kind_label",
+    "merge_due_items",
+    "relative_due",
+    "sort_due_items",
+    "write_due_markdown",
+]