monash-study-kit 1.2.0__py3-none-any.whl

monash_study_kit/syncer.py

@@ -0,0 +1,393 @@
+"""把一门课的 Moodle 内容同步成 课程/周次 的目录。
+
+    FIT2102 Programming paradigms (S2 2026)/
+      Week 01 - Introduction to Functional Programming in JavaScript/
+        applied1.zip
+        links.md          ← 本周的外部链接（Slides、YouTube、课程笔记…）
+      Assessments/2. Written/
+        A1 spec.pdf       ← 作业说明里的附件
+
+目录结构来自 core_courseformat_get_state：Monash 的每周是一个 "Week N - 标题"
+章节，下面挂 Own-time / Real-time / Wrap-up 子章节（`parent` 指向周章节）。
+子章节不单独建目录，文件直接放进周目录里，按周浏览更顺手。
+"""
+from __future__ import annotations
+
+import html
+import re
+import urllib.parse
+from dataclasses import dataclass, field
+
+from .moodlelib import (FILES_DIR, HOST, MoodleClient, collect_links, filename_from,
+                        is_attachment, now_iso)
+from .paths import load_settings
+
+WEEK_RE = re.compile(r"^\s*week\s*0*(\d+)\b\s*[-:–—]?\s*(.*)$", re.I)
+CODE_RE = re.compile(r"\b([A-Z]{3}\d{4})\b")
+SUFFIX_RE = re.compile(r"\s*-\s*((?:MUM\s+)?(?:S[12]|Summer|Winter)\b.*?\d{4}.*|(?:Summer|Winter)\s+MUM\s+\d{4})\s*$",
+                       re.I)
+VIDEO_EXT = (".mp4", ".mov", ".m4v", ".webm", ".mkv")
+# 这些活动里没有能下载的东西（论坛、测验、外部工具…），也不去点开它们
+SKIP_MODULES = {"forum", "quiz", "lti", "shadow", "feedback", "choice", "attendance",
+                "turnitintooltwo", "zoom", "h5pactivity", "scorm", "questionnaire", "workshop"}
+
+
+def clean(text: str) -> str:
+    return " ".join(html.unescape(text or "").split())
+
+
+NAME_LIMIT = int(load_settings().get("name_limit") or 80)
+
+
+def safe_name(name: str, limit: int | None = None) -> str:
+    """能当文件/目录名用。去掉路径分隔符和 Windows 不认的字符，截短但保留扩展名。
+
+    默认上限 80（设置里的 name_limit）：Windows 默认整条路径不能超过 260 个字符，
+    课程/周次/文件夹/文件四层叠起来很容易超。只在 Linux 服务器上跑的部署可以放宽，
+    但已经同步过的库别改，改了文件名会变，旧文件会被当成另一份再下一遍。
+    """
+    limit = limit or NAME_LIMIT
+    name = clean(name)
+    name = re.sub(r'[\\/:*?"<>|\x00-\x1f]', " ", name)
+    name = re.sub(r"\s+", " ", name).strip(" .")
+    if len(name) > limit:
+        stem, dot, ext = name.rpartition(".")
+        if dot and 0 < len(ext) <= 8:
+            name = stem[: limit - len(ext) - 1].rstrip() + "." + ext
+        else:
+            name = name[:limit].rstrip()
+    return name or "untitled"
+
+
+def course_code(course: dict) -> str | None:
+    m = CODE_RE.search(clean(course.get("fullname", ""))) or CODE_RE.search(course.get("shortname", ""))
+    return m.group(1) if m else None
+
+
+def course_folder(course: dict) -> str:
+    """"FIT2102 Programming paradigms - S2 2026" → "FIT2102 Programming paradigms (S2 2026)"."""
+    full = clean(course.get("fullname", "")) or course.get("shortname", "") or str(course["id"])
+    m = SUFFIX_RE.search(full)
+    if m:
+        full = f"{full[:m.start()].strip()} ({m.group(1).strip()})"
+    return safe_name(full)
+
+
+def week_folder(title: str) -> str | None:
+    m = WEEK_RE.match(clean(title))
+    if not m:
+        return None
+    rest = m.group(2).strip()
+    return safe_name(f"Week {int(m.group(1)):02d}" + (f" - {rest}" if rest else ""))
+
+
+@dataclass
+class Layout:
+    """章节号 → 相对课程目录的文件夹。"""
+    folders: dict[int, str] = field(default_factory=dict)
+    titles: dict[int, str] = field(default_factory=dict)
+
+
+def plan_layout(state: dict) -> Layout:
+    sections = {s["number"]: s for s in state["section"]}
+
+    def chain(num: int) -> list[dict]:
+        out, seen = [], set()
+        while num is not None and num in sections and num not in seen:
+            seen.add(num)
+            out.append(sections[num])
+            num = sections[num].get("parent")
+        return list(reversed(out))
+
+    layout = Layout()
+    for num, sec in sections.items():
+        layout.titles[num] = clean(sec.get("title"))
+        path = chain(num)
+        week = next((week_folder(s["title"]) for s in reversed(path) if week_folder(s["title"])), None)
+        if week:
+            layout.folders[num] = week
+            continue
+        # 非周次的章节：保留层级，但跳过只当容器的上级：自己没有内容的（比如 "Learning"），
+        # 以及第 0 节（Monash 叫 "Unit dashboard"，Assessments 之类都挂在它下面）
+        parts = [safe_name(s["title"]) for i, s in enumerate(path)
+                 if i == len(path) - 1 or (s.get("cmlist") and s["number"] != 0)]
+        layout.folders[num] = "/".join(parts) or "General"
+    return layout
+
+
+@dataclass
+class SyncStats:
+    downloaded: int = 0
+    skipped: int = 0
+    links: int = 0
+    removed: int = 0
+    errors: list[str] = field(default_factory=list)
+    bytes: int = 0
+
+
+class CourseSync:
+    def __init__(self, client: MoodleClient, con, course: dict, *, dry_run: bool = False, log=print):
+        self.c = client
+        self.con = con
+        self.course = course
+        self.cid = int(course["id"])
+        self.root = course_folder(course)
+        self.dry = dry_run
+        self.log = log
+        self.stats = SyncStats()
+        self.seen_sources: set[str] = set()
+        self.videos = load_settings().get("download_videos", False)
+
+    # ------------------------------------------------------------ 入口
+
+    def run(self) -> SyncStats:
+        state = self.c.course_state(self.cid)
+        layout = plan_layout(state)
+        cms = {str(cm["id"]): cm for cm in state["cm"]}
+        sections = {s["number"]: s for s in state["section"]}
+        if not self.dry:
+            self.clean_partials()
+
+        for num in sorted(sections):
+            for cmid in sections[num].get("cmlist") or []:
+                cm = cms.get(str(cmid))
+                if not cm or cm.get("uservisible") is False:
+                    continue
+                folder = layout.folders.get(cm.get("sectionnumber", num), "General")
+                try:
+                    self.handle_cm(cm, folder, layout.titles.get(num, ""))
+                except Exception as e:  # noqa: BLE001  一个坏活动不该拖垮整门课
+                    if e.__class__.__name__ == "MoodleAuthError":
+                        raise
+                    self.stats.errors.append(f"{cm.get('name')} ({cm['id']}): {e}")
+                    self.log(f"  ! {cm.get('name')}: {e}")
+
+        # label、CMS 块和每个活动的说明文字只在课程页 HTML 里
+        self.scan_section_pages(state, layout, cms)
+        if not self.dry:
+            self.mark_removed()
+            self.con.execute("UPDATE courses SET synced_at=? WHERE id=?", (now_iso(), self.cid))
+            self.con.commit()
+        return self.stats
+
+    def clean_partials(self) -> None:
+        """清掉以前中断的下载留下的临时文件（.dl-*，1.0.3 及以前还会是 .dl-*.part.part）。
+
+        同步是一门一门串行跑的，跑到这门课时不会有正在下的文件。
+        """
+        root = FILES_DIR / self.root
+        if root.exists():
+            for p in root.rglob(".dl-*"):
+                if p.is_file():
+                    p.unlink(missing_ok=True)
+
+    def mark_removed(self) -> None:
+        """这一轮没再见到的文件标成已移除（老师下架了，或者换了个文件名重新上传）。
+
+        只有整门课一个错误都没有时才标：有活动请求失败的话，没见到不代表没了。
+        只管同步器自己下的（cmid 不为空），讲义网页和录播不归这里管。文件本身不删。
+        """
+        if self.stats.errors:
+            return
+        rows = self.con.execute("SELECT source, path, removed_at FROM files WHERE course_id=? AND cmid IS NOT NULL",
+                                (self.cid,)).fetchall()
+        now = now_iso()
+        for r in rows:
+            seen = r["source"] in self.seen_sources
+            # 视频的字幕稿（transcribe 登记成 transcript:<视频路径>）跟着视频一起标
+            sources = (r["source"], f"transcript:{r['path']}")
+            if seen and r["removed_at"]:
+                self.con.execute("UPDATE files SET removed_at=NULL WHERE course_id=? AND source IN (?,?)",
+                                 (self.cid, *sources))
+            elif not seen and not r["removed_at"]:
+                self.con.execute("UPDATE files SET removed_at=? WHERE course_id=? AND source IN (?,?)",
+                                 (now, self.cid, *sources))
+                self.stats.removed += 1
+        self.con.commit()
+
+    # ------------------------------------------------------------ 各类活动
+
+    def handle_cm(self, cm: dict, folder: str, section_title: str) -> None:
+        mod = cm.get("module")
+        url = cm.get("url")
+        if mod in SKIP_MODULES or not url:
+            return
+        if mod == "resource":
+            local, external, resp = self.c.resolve(url + "&redirect=1")
+            if external is None and resp.status == 200 and "text/html" in (resp.headers.get("Content-Type") or ""):
+                # 设成"嵌入显示"的资源不跳转，文件链接在页面里
+                atts = [h for h, _ in collect_links(resp.text()).all if is_attachment(h)]
+                for h in atts[:1]:
+                    self.fetch_file(h, folder, cm, section_title)
+                return
+            self.fetch_file(local, folder, cm, section_title, resolved=True)
+        elif mod == "folder":
+            page = self.c.html(url)
+            sub = f"{folder}/{safe_name(cm['name'])}"
+            for h, _ in collect_links(page).all:
+                if "/mod_folder/content/" in h:
+                    self.fetch_file(h, sub, cm, section_title)
+        elif mod == "url":
+            local, external, _ = self.c.resolve(url + "&redirect=1")
+            target = external or local
+            if urllib.parse.urlsplit(target).hostname == HOST and "/pluginfile.php/" in target:
+                self.fetch_file(target, folder, cm, section_title)
+            else:
+                self.add_link(folder, section_title, clean(cm["name"]), target)
+        elif mod in ("assign", "page", "book"):
+            # 作业说明、页面里挂的附件（spec PDF、starter code）才是要的东西
+            page = self.c.html(url)
+            for h, _ in collect_links(page).all:
+                if is_attachment(h) and f"/{self._context_hint(mod)}" in h:
+                    self.fetch_file(h, folder, cm, section_title)
+            self.add_link(folder, section_title, clean(cm["name"]), url)
+
+    @staticmethod
+    def _context_hint(mod: str) -> str:
+        return {"assign": "mod_assign/", "page": "mod_page/", "book": "mod_book/"}[mod]
+
+    def scan_section_pages(self, state: dict, layout: Layout, cms: dict) -> None:
+        pages: dict[str, None] = {}
+        for sec in state["section"]:
+            if not sec.get("cmlist") or not sec.get("sectionurl"):
+                continue
+            pages[sec["sectionurl"].split("#", 1)[0]] = None
+        for page_url in pages:
+            try:
+                found = collect_links(self.c.html(page_url)).by_activity
+            except Exception as e:  # noqa: BLE001
+                if e.__class__.__name__ == "MoodleAuthError":
+                    raise
+                self.stats.errors.append(f"{page_url}: {e}")
+                continue
+            for cmid, links in found.items():
+                cm = cms.get(cmid)
+                if not cm:
+                    continue
+                num = cm.get("sectionnumber")
+                folder = layout.folders.get(num, "General")
+                title = layout.titles.get(num, "")
+                for href, text in links:
+                    if is_attachment(href):
+                        try:
+                            self.fetch_file(href, folder, cm, title)
+                        except Exception as e:  # noqa: BLE001
+                            if e.__class__.__name__ == "MoodleAuthError":
+                                raise
+                            self.stats.errors.append(f"{href}: {e}")
+                    elif is_external(href):
+                        label = text or clean(cm.get("name"))
+                        self.add_link(folder, title, label, href)
+
+    # ------------------------------------------------------------ 落盘
+
+    def fetch_file(self, url: str, folder: str, cm: dict, section_title: str, resolved: bool = False) -> None:
+        # pluginfile 地址本身就带 revision，不用再请求一次；其它的要跟一下跳转才知道
+        if resolved or "/pluginfile.php/" in url:
+            source = url.split("?", 1)[0]
+        else:
+            source = self.c.resolve(url)[0].split("?", 1)[0]
+        if source in self.seen_sources:
+            return
+        self.seen_sources.add(source)
+        row = self.con.execute("SELECT path FROM files WHERE course_id=? AND source=?",
+                               (self.cid, source)).fetchone()
+        if row and (FILES_DIR / row["path"]).exists():
+            self.stats.skipped += 1
+            return
+        guess = urllib.parse.unquote(urllib.parse.urlsplit(source).path.rsplit("/", 1)[-1])
+        if not self.videos and guess.lower().endswith(VIDEO_EXT):
+            # 默认不下录像：记成链接，在 links.md 里能点开看（monash config download_videos true 改）
+            self.add_link(folder, section_title, f"🎬 {clean(cm.get('name')) or guess}", source)
+            return
+        rel_dir = f"{self.root}/{folder}"
+        if self.dry:
+            self.log(f"  + {rel_dir}/{safe_name(guess)}")
+            self.stats.downloaded += 1
+            return
+        tmp = FILES_DIR / rel_dir / f".dl-{cm['id']}"   # 下载时 client.download 自己会加 .part
+        resp = self.c.download(source, tmp)
+        name = safe_name(filename_from(resp, guess) or guess)
+        rel = self._unique(f"{rel_dir}/{name}", source)
+        dest = FILES_DIR / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        tmp.replace(dest)
+        size = dest.stat().st_size
+        self.con.execute(
+            "INSERT INTO files (course_id, source, cmid, path, size, section, title, synced_at)"
+            " VALUES (?,?,?,?,?,?,?,?) ON CONFLICT(course_id, source) DO UPDATE SET"
+            " path=excluded.path, size=excluded.size, synced_at=excluded.synced_at",
+            (self.cid, source, int(cm["id"]), rel, size, section_title, clean(cm.get("name")), now_iso()))
+        self.con.commit()
+        self.stats.downloaded += 1
+        self.stats.bytes += size
+        self.log(f"  ↓ {rel} ({size // 1024} KB)")
+
+    def _unique(self, rel: str, source: str) -> str:
+        """同名文件换了内容（revision 变了）或者旧的已经下架，就覆盖旧的；别的来源撞名才加序号。"""
+        stem, dot, ext = rel.rpartition(".")
+        if not dot or "/" in ext:
+            stem, ext = rel, ""
+        n, cand = 1, rel
+        while True:
+            owner = self.con.execute("SELECT source, removed_at FROM files WHERE course_id=? AND path=?",
+                                     (self.cid, cand)).fetchone()
+            # 已经下架的旧文件占着这个名字，也直接让给新文件
+            if owner is None or owner["source"] == source or owner["removed_at"] or _same_file(owner["source"], source):
+                if owner is not None and owner["source"] != source:
+                    self.con.execute("DELETE FROM files WHERE course_id=? AND source=?",
+                                     (self.cid, owner["source"]))
+                return cand
+            n += 1
+            cand = f"{stem} ({n}).{ext}" if ext else f"{stem} ({n})"
+
+    def add_link(self, folder: str, section: str, title: str, url: str) -> None:
+        if self.dry:
+            return
+        cur = self.con.execute(
+            "INSERT OR IGNORE INTO links (course_id, folder, section, title, url, synced_at)"
+            " VALUES (?,?,?,?,?,?)", (self.cid, folder, section, title, url, now_iso()))
+        self.stats.links += cur.rowcount
+        self.con.commit()
+
+
+def _same_file(a: str, b: str) -> bool:
+    """pluginfile 地址去掉 revision 那一段后相同，就是同一个文件的新版本。"""
+    strip = lambda u: re.sub(r"/content/\d+/", "/content/X/", urllib.parse.urlsplit(u).path)  # noqa: E731
+    return strip(a) == strip(b)
+
+
+IGNORED_HOSTS = ("okta.com", "monash.edu/students", "google.com/url")
+
+
+def is_external(href: str) -> bool:
+    parts = urllib.parse.urlsplit(href)
+    if parts.scheme not in ("http", "https") or not parts.hostname:
+        return False
+    if parts.hostname == HOST:
+        return False
+    return not any(h in href for h in IGNORED_HOSTS)
+
+
+def write_links_md(con, course_id: int, root: str) -> None:
+    """每个目录一份 links.md，从数据库重写（外部链接没法下载，就汇总成清单）。"""
+    rows = con.execute("SELECT folder, section, title, url FROM links WHERE course_id=?"
+                       " ORDER BY folder, section, rowid", (course_id,)).fetchall()
+    by_folder: dict[str, list] = {}
+    for r in rows:
+        by_folder.setdefault(r["folder"], []).append(r)
+    for folder, items in by_folder.items():
+        lines = [f"# {folder} 的链接", ""]
+        last = None
+        seen = set()
+        for r in items:
+            if r["url"] in seen:
+                continue
+            seen.add(r["url"])
+            if r["section"] != last and r["section"]:
+                lines += ["", f"## {r['section']}", ""]
+                last = r["section"]
+            lines.append(f"- [{r['title'] or r['url']}]({r['url']})")
+        path = FILES_DIR / root / folder / "links.md"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text("\n".join(lines).replace("\n\n\n", "\n\n") + "\n", encoding="utf-8")

monash_study_kit/textextract.py

@@ -0,0 +1,89 @@
+"""从课件里抽文字：PDF（按页）、docx/pptx（按段/页）。
+
+PDF 默认用 pypdf（纯 Python，随包安装）；朋友的电脑上多半没有 pdftotext，Windows 更没有。
+装了 poppler 的机器（比如服务器）可以 `monash config pdf_extractor pdftotext`，排版更准。
+"""
+from __future__ import annotations
+
+import html
+import logging
+import re
+import shutil
+import subprocess
+import zipfile
+from pathlib import Path
+
+logging.getLogger("pypdf").setLevel(logging.ERROR)   # 课件 PDF 常有小毛病，pypdf 会刷一堆警告
+
+
+def pdf_pages(path: Path) -> list[str]:
+    """每页一段文字；坏文件、加密文件返回空列表。"""
+    from .paths import load_settings
+    if load_settings().get("pdf_extractor") == "pdftotext" and shutil.which("pdftotext"):
+        pages = _pdftotext(path)
+        if pages is not None:
+            return pages
+    try:
+        from pypdf import PdfReader
+        reader = PdfReader(str(path))
+        if reader.is_encrypted:
+            try:
+                reader.decrypt("")
+            except Exception:  # noqa: BLE001
+                return []
+        out = []
+        for page in reader.pages:
+            try:
+                out.append(page.extract_text() or "")
+            except Exception:  # noqa: BLE001  一页坏了不影响别的页
+                out.append("")
+        return out
+    except Exception:  # noqa: BLE001
+        return []
+
+
+def _pdftotext(path: Path) -> list[str] | None:
+    try:
+        r = subprocess.run(["pdftotext", "-layout", str(path), "-"], capture_output=True, text=True,
+                           timeout=120, errors="replace")
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if r.returncode != 0:
+        return None
+    pages = r.stdout.split("\f")
+    if pages and not pages[-1].strip():
+        pages.pop()                     # 最后一页后面也有一个换页符
+    return pages
+
+
+def _xml_text(xml: str, para_end: str, sep: str) -> str:
+    """去掉标签、还原 & < 这些转义。
+
+    一个词常被拆成好几个 run（<a:t>Hel</a:t><a:t>lo</a:t>），所以标签之间不加空格，
+    只在段落结尾加 sep，不然搜 "Hello" 会搜不到。"""
+    xml = re.sub(r"<[aw]:(?:br|tab)\b[^>]*/>", " ", re.sub(para_end, sep, xml))   # 换行、制表符当空格
+    return html.unescape(re.sub(r"<[^>]+>", "", xml))
+
+
+OFFICE_XML_MAX = 50 * 1024 * 1024   # 单个 slide/document.xml 解压后最多读这么多，防解压炸弹
+
+
+def _read_member(z: zipfile.ZipFile, name: str) -> str:
+    with z.open(name) as f:
+        data = f.read(OFFICE_XML_MAX + 1)
+    if len(data) > OFFICE_XML_MAX:
+        raise ValueError(f"{name} 解压后太大，不读")
+    return data.decode(errors="replace")
+
+
+def office_parts(path: Path) -> list[tuple[str, str]]:
+    """pptx → [("slide N", 文字)]；docx → [("", 全文，段落间空行)]。"""
+    with zipfile.ZipFile(path) as z:
+        if path.suffix.lower() == ".pptx":
+            nums = sorted(int(m.group(1)) for n in z.namelist()
+                          if (m := re.match(r"ppt/slides/slide(\d+)\.xml$", n)))
+            return [(f"slide {i}", " ".join(_xml_text(_read_member(z, f"ppt/slides/slide{i}.xml"),
+                                                      r"</a:p>", " ").split()))
+                    for i in nums]
+        xml = _read_member(z, "word/document.xml")
+    return [("", _xml_text(xml, r"</w:p>", "\n\n"))]

monash_study_kit/todo.py

@@ -0,0 +1,178 @@
+"""本周待办：把 Moodle 和 Ed 两边“要我做点什么”的东西合成一张清单。
+
+    monash todo [--days 7]
+
+  - Moodle：接下来 N 天的截止/日历事件（会话失效时用 iCal 订阅链接）、已过截止但没交也没分的作业；
+  - 最近 N 天新同步下来的课件（读本地库，不发请求）；
+  - Ed：还没做完的 lesson（只到你目前进度的下一周）、最近 N 天的公告、有未读新回复的帖子。
+
+Ed 的部分读本地的 ed.db（只读打开），不发请求；库由 sync 维护。
+Moodle 某一块拿不到（比如会话失效后作业汇总要登录）就在 notes 里说一声，其余照常给。
+"""
+from __future__ import annotations
+
+import re
+import sqlite3
+import time
+import urllib.error
+from datetime import datetime, timedelta, timezone
+
+from . import features as F
+from .edlib import DB_PATH as ED_DB
+from .moodlelib import MoodleAuthError, MoodleClient, MoodleError, db_connect
+from .syncer import course_code
+
+# 没网、Moodle 抽风：这些错误只影响 Moodle 那一块，Ed 部分读的是本地库，照常给
+NETWORK_ERRORS = (MoodleError, urllib.error.URLError, TimeoutError, ConnectionError)
+
+WEEK_RE = re.compile(r"\bW(?:eek)?\s*(\d{1,2})\b", re.I)
+
+
+def _week(*texts: str | None) -> int | None:
+    for t in texts:
+        m = WEEK_RE.search(t or "")
+        if m:
+            return int(m.group(1))
+    return None
+
+
+def _code(s: str | None) -> str:
+    m = re.search(r"[A-Z]{3}\d{4}", s or "")
+    return m.group(0) if m else (s or "").strip()
+
+
+def _ed_conn() -> sqlite3.Connection | None:
+    db = ED_DB
+    if not db.exists():
+        return None
+    con = sqlite3.connect(f"file:{db}?mode=ro", uri=True, timeout=10)
+    con.row_factory = sqlite3.Row
+    return con
+
+
+def ed_lessons_todo(con: sqlite3.Connection) -> list[dict]:
+    """没做完的 lesson，只到“目前进度的下一周”。
+
+    Ed 的 lesson 没有截止日期，也不知道现在是第几周（Monash 有期中假，按开学日推算会差一周），
+    所以用你自己的进度判断：每门课里做过（attempted/completed）的最大周次 + 1。
+    这样落下的前几周会列出来，还没到的后几周不会刷屏。
+    """
+    rows = con.execute("""SELECT l.id, l.course_id, l.title, l.status, m.name AS module, c.code
+                          FROM lessons l LEFT JOIN modules m ON m.id = l.module_id
+                          JOIN courses c ON c.id = l.course_id
+                          WHERE c.tracked = 1 AND COALESCE(l.is_hidden, 0) = 0""").fetchall()
+    by_course: dict[int, list] = {}
+    for r in rows:
+        by_course.setdefault(r["course_id"], []).append(r)
+    out = []
+    for cid, ls in by_course.items():
+        done_weeks = [w for r in ls if r["status"] in ("attempted", "completed")
+                      and (w := _week(r["title"], r["module"])) is not None]
+        upto = (max(done_weeks) + 1) if done_weeks else 1
+        for r in ls:
+            w = _week(r["title"], r["module"])
+            if r["status"] == "completed" or w is None or w > upto:
+                continue
+            out.append({"course": _code(r["code"]), "week": w, "title": r["title"], "status": r["status"],
+                        "url": f"https://edstem.org/au/courses/{cid}/lessons/{r['id']}"})
+    return sorted(out, key=lambda x: (x["course"], x["week"], x["title"]))
+
+
+def ed_announcements(con: sqlite3.Connection, days: int) -> list[dict]:
+    since = (datetime.now(timezone.utc) - timedelta(days=days)).isoformat()
+    rows = con.execute("""SELECT t.number, t.title, t.created_at, t.url, c.code FROM threads t
+                          JOIN courses c ON c.id = t.course_id
+                          WHERE c.tracked = 1 AND t.type = 'announcement'
+                            AND julianday(t.created_at) >= julianday(?)
+                          ORDER BY julianday(t.created_at) DESC""", (since,)).fetchall()
+    return [{"course": _code(r["code"]), "source": "ed", "ref": f"{_code(r['code'])}#{r['number']}",
+             "title": r["title"], "time": r["created_at"], "url": r["url"]} for r in rows]
+
+
+def ed_unread_replies(con: sqlite3.Connection) -> list[dict]:
+    try:
+        rows = con.execute("""SELECT t.number, t.title, t.url, c.code, u.new_reply_count, u.is_mine, u.is_watched
+                              FROM thread_state u JOIN threads t ON t.id = u.thread_id
+                              JOIN courses c ON c.id = t.course_id
+                              WHERE c.tracked = 1 AND u.new_reply_count > 0
+                              ORDER BY (u.is_mine OR u.is_watched) DESC, julianday(t.updated_at) DESC""").fetchall()
+    except sqlite3.OperationalError:       # 还没同步过 Ed
+        return []
+    return [{"ref": f"{_code(r['code'])}#{r['number']}", "title": r["title"], "new": r["new_reply_count"],
+             "mine_or_watched": bool(r["is_mine"] or r["is_watched"]), "url": r["url"]} for r in rows]
+
+
+def _ts(iso: str | None) -> float:
+    try:
+        return datetime.fromisoformat(iso).timestamp() if iso else 0.0
+    except ValueError:
+        return 0.0
+
+
+def new_files(courses: list[dict], days: int, limit: int = 30) -> list[dict]:
+    """最近 N 天新下载或者被老师换过的课件。synced_at 在重新下载时也会更新，所以换过的也算。"""
+    ids = [int(c["id"]) for c in courses]
+    if not ids:
+        return []
+    since = (datetime.now(timezone.utc) - timedelta(days=days)).isoformat(timespec="seconds")
+    con = db_connect()
+    try:
+        rows = con.execute(f"""SELECT f.path, f.title, f.synced_at, c.code FROM files f
+                               JOIN courses c ON c.id = f.course_id
+                               WHERE f.course_id IN ({",".join("?" * len(ids))}) AND f.removed_at IS NULL
+                                 AND f.synced_at >= ? AND f.path NOT LIKE '%.transcript.md'
+                               ORDER BY f.synced_at DESC LIMIT ?""", (*ids, since, limit)).fetchall()
+    finally:
+        con.close()
+    return [{"course": _code(r["code"]), "path": r["path"], "activity": r["title"], "synced_at": r["synced_at"]}
+            for r in rows]
+
+
+def build(client: MoodleClient | None, courses: list[dict], days: int = 7) -> dict:
+    notes: list[str] = []
+    out: dict = {"days": days, "generated_at": datetime.now(timezone.utc).isoformat(timespec="minutes")}
+
+    try:
+        out["due"] = [d for d in F.due(client, days, include_overdue_days=0) if not d["overdue"]]
+        if out["due"] and out["due"][0]["source"] == "ical":
+            notes.append("Moodle 会话失效：截止日期来自日历订阅链接，没有提交状态")
+    except MoodleAuthError:
+        out["due"] = []
+        notes.append("Moodle 没登录（或登录已过期），也没有日历订阅链接：截止日期缺失")
+    except NETWORK_ERRORS as e:
+        out["due"] = []
+        notes.append(f"连不上 Moodle（{e}）：截止日期缺失，稍后再试")
+
+    missing, news = [], []
+    now = int(time.time())
+    for c in courses:
+        try:
+            missing += [a for a in F.assignments(client, c) if a["missing"]]
+            news += [{"course": course_code(c), "source": "moodle", "ref": None, "title": n["title"],
+                      "time": n["time"], "url": n.get("url")}
+                     for n in F.news(client, c, 3) if (n.get("time_ts") or 0) >= now - days * 86400]
+        except MoodleAuthError:
+            notes.append("Moodle 会话失效：作业汇总和 Moodle 公告缺失")
+            break
+        except NETWORK_ERRORS as e:
+            notes.append(f"连不上 Moodle（{e}）：作业汇总和 Moodle 公告缺失")
+            break
+    out["possibly_missing"] = missing
+    out["new_files"] = new_files(courses, days)
+
+    con = _ed_conn()
+    if con is None:
+        notes.append("还没同步过 Ed（没设置令牌，或者第一次同步还没跑完）：Ed 部分缺失")
+        out.update(ed_lessons=[], ed_unread_replies=[])
+    else:
+        with con:
+            try:
+                out["ed_lessons"] = ed_lessons_todo(con)
+            except sqlite3.OperationalError:
+                out["ed_lessons"] = []
+            news += ed_announcements(con, days)
+            out["ed_unread_replies"] = ed_unread_replies(con)
+        con.close()
+    out["announcements"] = sorted(news, key=lambda n: _ts(n["time"]), reverse=True)
+    out["notes"] = notes
+    return out