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

monash_study_kit/help_menu.py

@@ -0,0 +1,121 @@
+"""功能大全和预设提示：让朋友知道能问什么。
+
+工具不是靠关键词触发的（Claude 按意思挑工具），但人不知道有什么功能就想不到去问。所以：
+  * FEATURES：按类别列出能做的事，每条一句示例问法和对应的命令。`monash help` 打印它，
+    MCP 的“功能大全”提示也用它，两边不会对不上。
+  * PROMPTS：MCP 预设提示。它们只在用户从 Claude 的“+”菜单里选中时才发给 Claude，
+    平时不占额度，这是它们比多加一个 help 工具划算的地方（工具清单每次对话都要整份发）。
+"""
+from __future__ import annotations
+
+# (类别, [(能做什么, 示例问法, 命令行)])
+FEATURES = [
+    ("这周要做什么", [
+        ("本周待办：截止、可能漏交、Ed 没做完的 lesson、最新公告", "这周我有什么要做的？", "monash todo"),
+        ("截止日期（没登录时也能查）", "FIT2102 接下来两周有什么要交？", "monash due FIT2102"),
+        ("作业提交状态、可能漏交", "我有没有漏交什么作业？", "monash moodle assignments --missing"),
+    ]),
+    ("课程资料", [
+        ("全文搜课件、课程笔记网页、Ed 课件、录播字幕稿，带页码/时间戳", "哪一周讲了 monad？在哪份讲义第几页？",
+         'monash grep "monad"'),
+        ("读课件原文、帮你解释", "帮我看看 A2 的 spec 要求什么", "monash open"),
+        ("某周的课件和外部链接", "FIT2109 第 5 周有哪些资料？", "monash moodle ls FIT2109 5"),
+    ]),
+    ("Ed 论坛", [
+        ("上次看过之后的新帖和新回复", "Ed 上有什么新消息？", "monash ed new"),
+        ("我发的/关注的帖子有没有人回", "我上次问的问题有人回了吗？", "monash ed following"),
+        ("搜帖子、读全文", "有没有人问过 A1 能不能用 lodash？", "monash ed search FIT2102 lodash"),
+        ("整节读 Ed lesson：正文、阅读网页、PDF 按页序拼好，附测验题", "带我过一遍 FIT2109 第 3 周的 pre-class",
+         "monash ed read FIT2109 'W3 Pre-Class'"),
+        ("Ed Lessons 进度和测验题（复习用）", "用第 3 周的测验题帮我复习", "monash ed quiz FIT2109 --module 'Week 3'"),
+    ]),
+    ("成绩和通知", [
+        ("各课总分、每项得分和反馈", "我 FIT2109 现在成绩多少？", "monash moodle grades FIT2109"),
+        ("Moodle 公告", "FIT2102 最近有什么公告？", "monash moodle news FIT2102"),
+        ("Moodle 私信（只读）", "Moodle 上有人给我发消息吗？", "monash moodle messages"),
+    ]),
+    ("维护", [
+        ("登录 / 重新登录 Moodle", "帮我重新登录 Moodle", "monash login"),
+        ("马上同步一次", "同步一下最新的", "monash sync"),
+        ("出问题时体检", "monash 用不了了", "monash doctor"),
+    ]),
+]
+
+
+def render(cli: bool = True) -> str:
+    """cli=True 给终端看（带命令）；False 给 Claude 看（只有功能和问法）。"""
+    out = ["能做的事（直接用自己的话问就行，下面只是例子）：" if not cli else "monash 能做的事：", ""]
+    for cat, items in FEATURES:
+        out.append(f"■ {cat}")
+        for what, ask, cmd in items:
+            out.append(f"  · {what}")
+            out.append(f"      问：“{ask}”" + (f"   命令：{cmd}" if cli else ""))
+        out.append("")
+    out.append("不能做的：交作业、做测验、在 Ed 上发帖，这些要自己去网页上操作。")
+    if cli:
+        out.append("每个命令都有 --help；Claude 里输入框的“+”菜单里有 monash 的预设提示，点一下就能用。")
+    return "\n".join(out)
+
+
+# ---------------------------------------------------------------- MCP 预设提示
+# name → (标题, 说明, [(参数名, 说明, 必填)], 生成用户消息的函数)
+
+def _todo(a):
+    return ("这周我有什么要做的？按截止时间排，标出可能漏交的作业，"
+            "再列 Ed 上还没做完的 lesson 和最近的公告。最后给我一个今天先做什么的建议。")
+
+
+def _ed(a):
+    course = f"（只看 {a['course']}）" if a.get("course") else ""
+    return (f"Ed 上有什么新消息{course}？先说老师的公告和回答，再说我发的或关注的帖子有没有新回复，"
+            "其余的一句话概括就行。")
+
+
+def _topic(a):
+    course = f"在 {a['course']} 里，" if a.get("course") else ""
+    return (f"{course}“{a['topic']}”在哪份资料里讲过？列出课件名和页码或录播时间戳，"
+            "然后读原文，用简单的话给我解释一遍。")
+
+
+def _quiz(a):
+    week = f"第 {a['week']} 周" if a.get("week") else "最近一周"
+    return (f"用 {a['course']} Ed Lessons 里{week}的测验题帮我复习：一次出一道，等我回答后再判断对错并解释。"
+            "Ed 不公开答案，请根据课件判断，拿不准的地方直接说。")
+
+
+def _grades(a):
+    return "我各门课现在的成绩和老师反馈怎么样？有没有需要特别注意的？"
+
+
+def _help(a):
+    return "我刚装了 monash。告诉我你能帮我做什么，按类别列出来，每类给我几句可以直接问的例子。\n\n" + render(cli=False)
+
+
+PROMPTS = {
+    "help": ("功能大全", "列出能做的所有事，每条附一句示例问法", [], _help),
+    "weekly_todo": ("本周待办", "这周要做什么、有没有漏交", [], _todo),
+    "ed_catchup": ("Ed 新消息", "公告、老师回答、我的帖子有没有人回", [("course", "只看某门课，如 FIT2102", False)], _ed),
+    "find_topic": ("找知识点", "某个概念在哪份讲义/哪节录播，并解释",
+                   [("topic", "要找的知识点，如 monad", True), ("course", "课号，可不填", False)], _topic),
+    "quiz_review": ("测验题复习", "用 Ed Lessons 的测验题一题一题练",
+                    [("course", "课号，如 FIT2109", True), ("week", "第几周，可不填", False)], _quiz),
+    "grades": ("成绩和反馈", "各课成绩和老师反馈", [], _grades),
+}
+
+
+def prompt_list() -> list[dict]:
+    return [{"name": name, "title": title, "description": desc,
+             "arguments": [{"name": n, "description": d, "required": req} for n, d, req in args]}
+            for name, (title, desc, args, _) in PROMPTS.items()]
+
+
+def get_prompt(name: str, arguments: dict | None) -> dict:
+    if name not in PROMPTS:
+        raise KeyError(name)
+    title, desc, args, build = PROMPTS[name]
+    arguments = {k: v for k, v in (arguments or {}).items() if v not in (None, "")}
+    missing = [n for n, _, req in args if req and n not in arguments]
+    if missing:
+        raise ValueError(f"缺少参数：{', '.join(missing)}")
+    return {"description": desc,
+            "messages": [{"role": "user", "content": {"type": "text", "text": build(arguments)}}]}

monash_study_kit/htmldom.py

@@ -0,0 +1,162 @@
+"""极简 HTML 树，给 Moodle 页面解析用（成绩表、论坛、作业、测验）。
+
+标准库的 HTMLParser 只给事件流，这里把它搭成一棵树，再提供 find / find_all /
+text 这几个最常用的操作。Moodle 的 HTML 大体规整，不需要 html5lib 那种容错。
+"""
+from __future__ import annotations
+
+import html as _html
+from html.parser import HTMLParser
+
+VOID = {"area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta",
+        "source", "track", "wbr"}
+# 这些标签遇到同级的新标签时自动闭合（HTML 允许省略结束标签）
+AUTOCLOSE = {"p": {"p", "div", "ul", "ol", "table", "h1", "h2", "h3", "h4"},
+             "li": {"li"}, "tr": {"tr"}, "td": {"td", "th", "tr"}, "th": {"td", "th", "tr"},
+             "option": {"option"}}
+
+
+class Node:
+    __slots__ = ("tag", "attrs", "children", "parent")
+
+    def __init__(self, tag: str, attrs: dict | None = None, parent: "Node | None" = None):
+        self.tag = tag
+        self.attrs = attrs or {}
+        self.children: list[Node | str] = []
+        self.parent = parent
+
+    def get(self, key: str, default=None):
+        return self.attrs.get(key, default)
+
+    @property
+    def classes(self) -> set[str]:
+        return set((self.attrs.get("class") or "").split())
+
+    def iter(self):
+        for ch in self.children:
+            if isinstance(ch, Node):
+                yield ch
+                yield from ch.iter()
+
+    def _match(self, tag, cls, attrs) -> bool:
+        if tag and self.tag not in (tag if isinstance(tag, (set, tuple, list)) else {tag}):
+            return False
+        if cls and not set(cls.split()) <= self.classes:
+            return False
+        for k, v in (attrs or {}).items():
+            have = self.attrs.get(k)
+            if v is True:
+                if have is None:
+                    return False
+            elif callable(v):
+                if have is None or not v(have):
+                    return False
+            elif have != v:
+                return False
+        return True
+
+    def find_all(self, tag=None, cls: str | None = None, **attrs) -> list["Node"]:
+        attrs = {k.rstrip("_").replace("__", "-"): v for k, v in attrs.items()}
+        return [n for n in self.iter() if n._match(tag, cls, attrs)]
+
+    def find(self, tag=None, cls: str | None = None, **attrs) -> "Node | None":
+        attrs = {k.rstrip("_").replace("__", "-"): v for k, v in attrs.items()}
+        return next((n for n in self.iter() if n._match(tag, cls, attrs)), None)
+
+    def text(self, sep: str = " ") -> str:
+        parts: list[str] = []
+
+        def walk(n: Node):
+            for ch in n.children:
+                if isinstance(ch, str):
+                    parts.append(ch)
+                elif ch.tag not in ("script", "style"):
+                    if ch.tag in ("br", "p", "div", "li", "tr") and parts:
+                        parts.append(sep)
+                    walk(ch)
+        walk(self)
+        return " ".join("".join(parts).split()) if sep == " " else \
+            "\n".join(" ".join(line.split()) for line in "".join(parts).split(sep) if line.strip())
+
+    def inner_html(self) -> str:
+        out = []
+
+        def walk(n: Node):
+            for ch in n.children:
+                if isinstance(ch, str):
+                    out.append(_html.escape(ch, quote=False))
+                else:
+                    attrs = "".join(f' {k}="{_html.escape(v or "")}"' for k, v in ch.attrs.items())
+                    out.append(f"<{ch.tag}{attrs}>")
+                    if ch.tag not in VOID:
+                        walk(ch)
+                        out.append(f"</{ch.tag}>")
+        walk(self)
+        return "".join(out)
+
+    def __repr__(self):
+        return f"<{self.tag} {self.attrs.get('class', '')!r}>"
+
+
+class _Builder(HTMLParser):
+    def __init__(self):
+        super().__init__(convert_charrefs=True)
+        self.root = Node("#root")
+        self.cur = self.root
+
+    def handle_starttag(self, tag, attrs):
+        closes = AUTOCLOSE.get(self.cur.tag)
+        if closes and tag in closes:
+            self._close(self.cur.tag)
+        node = Node(tag, {k: (v if v is not None else "") for k, v in attrs}, self.cur)
+        self.cur.children.append(node)
+        if tag not in VOID:
+            self.cur = node
+
+    def handle_startendtag(self, tag, attrs):
+        node = Node(tag, {k: (v if v is not None else "") for k, v in attrs}, self.cur)
+        self.cur.children.append(node)
+
+    def handle_endtag(self, tag):
+        self._close(tag)
+
+    def _close(self, tag):
+        n = self.cur
+        while n is not None and n.tag != tag:
+            n = n.parent
+        if n is not None and n.parent is not None:
+            self.cur = n.parent
+
+    def handle_data(self, data):
+        self.cur.children.append(data)
+
+
+def parse(html_text: str) -> Node:
+    b = _Builder()
+    b.feed(html_text)
+    b.close()
+    return b.root
+
+
+def form_fields(form: Node) -> list[tuple[str, str]]:
+    """像浏览器一样收集一个表单要提交的字段（不含提交按钮）。"""
+    out = []
+    for n in form.iter():
+        name = n.get("name")
+        if not name or n.get("disabled") is not None:
+            continue
+        if n.tag == "input":
+            t = (n.get("type") or "text").lower()
+            if t in ("submit", "button", "image", "file", "reset"):
+                continue
+            if t in ("checkbox", "radio") and n.get("checked") is None:
+                continue
+            out.append((name, n.get("value") or ("on" if t in ("checkbox", "radio") else "")))
+        elif n.tag == "textarea":
+            out.append((name, "".join(c for c in n.children if isinstance(c, str))))
+        elif n.tag == "select":
+            opts = n.find_all("option")
+            chosen = [o for o in opts if o.get("selected") is not None] or opts[:1]
+            for o in chosen:
+                out.append((name, o.get("value") if o.get("value") is not None else o.text()))
+    return out

monash_study_kit/jobs.py

@@ -0,0 +1,233 @@
+"""同步、续期、状态：`monash sync` 和 MCP 的后台线程共用。
+
+一次完整同步 = Ed 帖子 + Ed Lessons（有令牌的话）→ Moodle 课件（登录着的话）→ 全文索引。
+哪一边没登录就跳过那一边，在状态里记一笔，不影响另一边。
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import content_index, edlib, edsync, lessons
+from .edlib import EdAuthError
+from .moodlelib import DATA_DIR, MoodleAuthError, MoodleClient, db_connect, get_state, now_iso, set_state
+from .paths import HOME, load_settings
+from .syncer import CourseSync, clean, course_code, course_folder, write_links_md
+
+STATUS_FILE = HOME / "status.json"
+LOCK_FILE = HOME / "sync.lock"
+
+
+# ---------------------------------------------------------------- Moodle 课程
+
+def load_courses(client: MoodleClient, con) -> list[dict]:
+    courses = client.courses()
+    for c in courses:
+        con.execute("INSERT INTO courses (id, code, folder, fullname) VALUES (?,?,?,?)"
+                    " ON CONFLICT(id) DO UPDATE SET code=excluded.code, folder=excluded.folder,"
+                    " fullname=excluded.fullname",
+                    (c["id"], course_code(c), course_folder(c), clean(c["fullname"])))
+    con.commit()
+    return courses
+
+
+TERM_RE = re.compile(r"\b(S1|S2|Summer|Winter)\b(?:\s+MUM)?\s*(20\d\d)?", re.I)
+TERM_ORDER = {"s1": 1, "winter": 2, "s2": 3, "summer": 4}
+
+
+def course_term(course: dict) -> tuple[int, int] | None:
+    """课名或分类里的学期标签 → (年, 学期序号)。"FIT2102 … - S2 2026" → (2026, 3)。"""
+    text = f"{clean(course.get('fullname', ''))} {course.get('coursecategory') or ''}"
+    best = None
+    for m in TERM_RE.finditer(text):
+        year = m.group(2) or (re.search(r"20\d\d", text) or [None])[0]
+        if year:
+            t = (int(year), TERM_ORDER[m.group(1).lower()])
+            best = max(best, t) if best else t
+    return best
+
+
+def current_courses(courses: list[dict], now: float | None = None) -> list[dict]:
+    """本学期的课。
+
+    Moodle 上的开课/结课日期不可靠（有的课 3 月就“开课”、下学期的课也已经挂出来），所以主要看
+    课名/分类里的学期标签：已经开课的课里，最新的那个学期就是本学期。没有学期标签的课退回按日期判断。
+    """
+    now = now or time.time()
+    coded = [c for c in courses if course_code(c)]
+    started = [c for c in coded if (c.get("startdate") or 0) <= now + 7 * 86400]
+    terms = [t for c in started if (t := course_term(c))]
+    if terms:
+        cur = max(terms)
+        return [c for c in started if course_term(c) == cur]
+    return [c for c in started if (c.get("enddate") or now + 1) > now
+            and (c.get("startdate") or 0) > now - 200 * 86400]
+
+
+def tracked_courses(con, courses: list[dict]) -> list[dict]:
+    """跟踪的课；一门都没选过就自动选本学期的课（以后 `monash courses` 可以改）。"""
+    tracked = {r["id"] for r in con.execute("SELECT id FROM courses WHERE tracked=1")}
+    if not tracked:
+        picked = current_courses(courses)
+        con.executemany("UPDATE courses SET tracked=1 WHERE id=?", [(c["id"],) for c in picked])
+        con.commit()
+        return picked
+    return [c for c in courses if c["id"] in tracked]
+
+
+# ---------------------------------------------------------------- 同步
+
+def sync_moodle(log=print, only: list[dict] | None = None, dry_run: bool = False) -> dict:
+    client, con = MoodleClient(), db_connect()
+    courses = load_courses(client, con)
+    targets = only or tracked_courses(con, courses)
+    total = {"courses": [], "downloaded": 0, "bytes": 0, "removed": 0, "errors": 0}
+    for course in targets:
+        log(f"Moodle {course_code(course) or course_folder(course)}")
+        stats = CourseSync(client, con, course, dry_run=dry_run, log=log).run()
+        if not dry_run:
+            write_links_md(con, course["id"], course_folder(course))
+        total["courses"].append(course_code(course))
+        total["downloaded"] += stats.downloaded
+        total["bytes"] += stats.bytes
+        total["removed"] += stats.removed
+        total["errors"] += len(stats.errors)
+    if not dry_run:
+        set_state(con, "last_sync", {"at": now_iso(), "new_files": total["downloaded"]})
+    con.close()
+    return total
+
+
+def sync_ed(log=print) -> dict:
+    client = edlib.EdClient()
+    out = edsync.sync(log=log, client=client)
+    conn = edlib.db_connect()
+    for (cid,) in conn.execute("SELECT id FROM courses WHERE tracked=1").fetchall():
+        lessons.sync_lessons(conn, client, cid, log=log)
+    conn.close()
+    return out
+
+
+def have_ed_token() -> bool:
+    return bool(os.environ.get("ED_TOKEN")) or edlib.TOKEN_FILE.exists()
+
+
+def sync_all(log=print) -> dict:
+    """能同步的都同步一遍。另一个进程正在同步就直接返回。"""
+    if not _lock():
+        log("另一个同步正在进行，这次跳过")
+        return read_status()
+    try:
+        status = read_status()
+        status["errors"] = {}
+        if have_ed_token():
+            try:
+                status["ed"] = {**sync_ed(log), "at": now_iso()}
+            except EdAuthError as e:
+                status["errors"]["ed"] = str(e)
+            except Exception as e:  # noqa: BLE001  网络问题之类，下次再试
+                status["errors"]["ed"] = f"{type(e).__name__}: {e}"
+        else:
+            status["errors"]["ed"] = "还没设置 Ed 令牌（monash login ed）"
+        try:
+            status["moodle"] = {**sync_moodle(log), "at": now_iso()}
+        except MoodleAuthError as e:
+            status["errors"]["moodle"] = str(e)
+        except Exception as e:  # noqa: BLE001
+            status["errors"]["moodle"] = f"{type(e).__name__}: {e}"
+        if load_settings().get("web_notes", True):
+            try:
+                from . import webnotes
+                con = db_connect()
+                status["web_notes"] = webnotes.sync(con, log)
+                con.close()
+            except Exception as e:  # noqa: BLE001  讲义站抓不到不影响别的
+                status["errors"]["web_notes"] = f"{type(e).__name__}: {e}"
+        try:
+            con = db_connect()
+            try:
+                status["index"] = content_index.index(con)
+            finally:
+                con.close()
+        except Exception as e:  # noqa: BLE001
+            status["errors"]["index"] = f"{type(e).__name__}: {e}"
+        status["last_sync"] = now_iso()
+        write_status(status)
+        return status
+    finally:
+        _unlock()
+
+
+def keepalive() -> int | None:
+    """给 Moodle 会话续期一次（会话空闲 4 小时就过期）。返回剩余秒数。"""
+    left = MoodleClient().touch()
+    status = read_status()
+    status["session"] = {"alive": True, "checked_at": now_iso(), "time_remaining": left}
+    write_status(status)
+    return left
+
+
+# ---------------------------------------------------------------- 状态文件
+
+def read_status() -> dict:
+    try:
+        return json.loads(STATUS_FILE.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def write_status(status: dict) -> None:
+    HOME.mkdir(parents=True, exist_ok=True)
+    tmp = STATUS_FILE.with_suffix(".tmp")
+    tmp.write_text(json.dumps(status, ensure_ascii=False, indent=2), encoding="utf-8")
+    os.replace(tmp, STATUS_FILE)
+
+
+def last_sync_at(status: dict | None = None) -> str | None:
+    """上次同步的时间。服务器上自己部署时课件是另一个脚本同步的，不写 status.json，
+    只在库里记 last_sync，所以 status.json 没有就看库里的。"""
+    at = (status or read_status()).get("last_sync")
+    if at:
+        return at
+    if not (DATA_DIR / "moodle.db").exists():
+        return None
+    try:
+        con = db_connect()
+        try:
+            return (get_state(con, "last_sync") or {}).get("at")
+        finally:
+            con.close()
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def hours_since_sync(status: dict | None = None) -> float:
+    at = last_sync_at(status)
+    if not at:
+        return float("inf")
+    return (datetime.now(timezone.utc) - datetime.fromisoformat(at)).total_seconds() / 3600
+
+
+def _lock() -> bool:
+    """跨进程的同步锁（CLI 和 MCP 可能同时想同步）。超过 2 小时的锁当成上次崩了留下的。"""
+    HOME.mkdir(parents=True, exist_ok=True)
+    try:
+        if time.time() - LOCK_FILE.stat().st_mtime > 7200:
+            LOCK_FILE.unlink(missing_ok=True)
+    except OSError:
+        pass
+    try:
+        fd = os.open(LOCK_FILE, os.O_WRONLY | os.O_CREAT | os.O_EXCL)
+    except FileExistsError:
+        return False
+    os.write(fd, str(os.getpid()).encode())
+    os.close(fd)
+    return True
+
+
+def _unlock() -> None:
+    Path(LOCK_FILE).unlink(missing_ok=True)

monash_study_kit/lesson_reader.py

@@ -0,0 +1,94 @@
+"""整节读 Ed lesson：按页序把文字页、阅读网页、PDF 课件拼成一篇 Markdown，末尾附测验题。
+
+适合“带我过一遍第 3 周的 pre-class”“这节讲了什么”。各部分都是同步时已经存在本地的：
+  * document / code 页 → lessons.py 存的 .md（ED_FILES_DIR）
+  * webpage 页        → webnotes.py 抓的课程笔记（FILES_DIR，按网址在 web_pages 表里找）；
+                        没抓的（需要登录的站、视频之类）只留一个链接
+  * pdf 页            → 下载好的 PDF，抽文字，标页码
+不发任何网络请求。
+"""
+from __future__ import annotations
+
+import sqlite3
+
+from . import edquery, textextract
+from .moodlelib import FILES_DIR
+from .paths import ED_FILES_DIR
+
+
+def find_lesson(conn, course, lesson) -> dict:
+    """lesson 写 id，或标题的一部分（如 "W3 Pre-Class"）。匹配到好几节就列出来让人挑。"""
+    rows = edquery.lessons(conn, course)
+    ref = str(lesson).strip()
+    hits = [l for l in rows if str(l["id"]) == ref] or \
+        [l for l in rows if ref.lower() in (l["title"] or "").lower()]
+    if not hits:
+        titles = "、".join(l["title"] for l in rows[:12]) or "（这门课在 Ed 上没有 Lessons）"
+        raise edquery.NotFound(f"{course} 里没有 lesson “{lesson}”。有这些：{titles}")
+    exact = [l for l in hits if (l["title"] or "").lower() == ref.lower()]
+    if len(hits) > 1 and len(exact) != 1:
+        raise edquery.NotFound("匹配到好几节：" + "；".join(f"{l['id']} {l['title']}" for l in hits[:8])
+                               + "。写得更具体一点，或者用 id")
+    return exact[0] if len(hits) > 1 else hits[0]
+
+
+def _web_page(url: str) -> str | None:
+    """课程笔记里抓好的那份网页（在 moodle.db 的 web_pages 表）。"""
+    from . import webnotes
+    from .moodlelib import db_connect
+    u = webnotes.normalize(url or "")
+    if not u:
+        return None
+    try:
+        con = db_connect()
+        row = con.execute("SELECT path FROM web_pages WHERE url=? AND path IS NOT NULL", (u,)).fetchone()
+        con.close()
+    except sqlite3.Error:
+        return None
+    if not row:
+        return None
+    try:
+        return (FILES_DIR / row["path"]).read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+
+def _strip_header(text: str) -> str:
+    """存下来的 .md 第一行是 “# 标题”，拼的时候标题我们自己写，去掉重复的。"""
+    lines = text.strip().splitlines()
+    return "\n".join(lines[1:]).strip() if lines and lines[0].startswith("# ") else text.strip()
+
+
+def lesson_markdown(conn, course, lesson) -> dict:
+    l = find_lesson(conn, course, lesson)       # edquery.lessons 里会顺带补上老库的 idx 列
+    rows = conn.execute("SELECT id, type, title, file_url, url, local_path FROM lesson_files WHERE lesson_id=? "
+                        "ORDER BY COALESCE(idx, 1e9), id", (l["id"],)).fetchall()
+    parts, readable = [], 0
+    for r in rows:
+        title = r["title"] or r["type"]
+        if r["type"] in ("document", "code") and r["local_path"]:
+            try:
+                body = _strip_header((ED_FILES_DIR / r["local_path"]).read_text(encoding="utf-8"))
+            except OSError:
+                continue
+            parts.append(f"## {title}\n\n{body}")
+            readable += 1
+        elif r["type"] == "webpage":
+            page = _web_page(r["url"])
+            if page:
+                parts.append(f"## {title}\n\n{_strip_header(page)}")
+                readable += 1
+            else:
+                parts.append(f"## {title}\n\n[网页：{r['url']}]（没有抓下来：可能要登录，或者还没同步到）")
+        elif r["type"] == "pdf" and r["local_path"]:
+            pages = textextract.pdf_pages(ED_FILES_DIR / r["local_path"])
+            text = "\n\n".join(f"[第 {i} 页] {' '.join(p.split())}" for i, p in enumerate(pages, 1) if p.strip())
+            parts.append(f"## {title}（PDF）\n\n{text or '（这个 PDF 抽不出文字，可能是图片）'}")
+            readable += bool(text)
+    quiz = [q for q in edquery.quizzes(conn, course) if q["url"] == l["url"]]
+    md = [f"# {l['title']}", f"{l['module'] or ''} · {l['status']} · {l['url']}", ""]
+    md.append("\n\n---\n\n".join(parts) if parts else "（这节没有能读的内容，可能全是视频或测验）")
+    if quiz:
+        md += ["", "---", "", edquery.quiz_markdown(quiz)]
+    return {"id": l["id"], "title": l["title"], "status": l["status"], "url": l["url"],
+            "readings": readable, "markdown": "\n".join(md).rstrip() + "\n"}