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

monash_study_kit/moodlelib.py

@@ -0,0 +1,485 @@
+"""Monash Moodle 的最小客户端：会话 cookie、AJAX 接口、页面解析、文件下载。
+
+登录靠浏览器里拿到的 cookie（Okta SAML 没法在这里走，见 browser_login.py）。Monash 关掉了
+移动端 Web Service（tool_mobile_get_public_config 里 enablemobilewebservice=0），
+所以 moodle-cli 那种"用移动端令牌无限续期"的办法在这里用不了，只能靠定时
+core_session_touch 让会话一直不空闲。
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shlex
+import sqlite3
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from html.parser import HTMLParser
+from pathlib import Path
+
+from .paths import DATA_DIR, FILES_DIR, SECRETS_DIR, write_secret  # noqa: F401  FILES_DIR 给 syncer 等模块用
+
+BASE_URL = os.environ.get("MOODLE_BASE_URL", "https://learning.monash.edu").rstrip("/")
+HOST = urllib.parse.urlsplit(BASE_URL).hostname or ""
+BASE_SCHEME = urllib.parse.urlsplit(BASE_URL).scheme
+COOKIE_FILE = SECRETS_DIR / "moodle-cookie"
+UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0 Safari/537.36"
+# 请求之间歇一下：这是用个人账号访问学校系统，别像爬虫一样猛打
+REQUEST_GAP = float(os.environ.get("MONASH_KIT_GAP", "0.4"))
+# 会话失效时提示用户跑的命令。服务器上的部署登录方式不一样，用环境变量换掉
+LOGIN_HINT = os.environ.get("MONASH_KIT_LOGIN_HINT", "monash login")
+
+
+class MoodleAuthError(RuntimeError):
+    """会话失效或 cookie 不对。调用方应退出码 2，提示运行 `monash login`。"""
+
+
+class MoodleError(RuntimeError):
+    """Moodle 返回了意料之外的东西：HTTP 错误、跳转太多、AJAX 接口报错。命令行退出码 3。"""
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+# ---------------------------------------------------------------- cookie
+
+def parse_cookie_input(text: str) -> dict[str, str]:
+    """从用户粘贴的东西里抠出 cookie。
+
+    接受三种：DevTools 里 "Copy as cURL" 的整段命令、一行 `a=b; c=d` 的
+    cookie 头、或者只有 MoodleSession 的值。
+    """
+    text = text.strip()
+    if not text:
+        return {}
+    header = None
+    if text.startswith("curl "):
+        try:
+            argv = shlex.split(text.replace("\\\n", " "))
+        except ValueError:
+            argv = text.split()
+        for i, arg in enumerate(argv):
+            nxt = argv[i + 1] if i + 1 < len(argv) else ""
+            if arg in ("-b", "--cookie"):
+                header = nxt
+            elif arg in ("-H", "--header") and nxt.lower().startswith("cookie:"):
+                header = nxt.split(":", 1)[1]
+        if header is None:
+            return {}
+    elif "=" in text:
+        header = text
+    else:
+        return {"MoodleSession": text}
+    jar = {}
+    for part in header.split(";"):
+        if "=" in part:
+            k, v = part.split("=", 1)
+            if k.strip():
+                jar[k.strip()] = v.strip()
+    return jar
+
+
+def load_cookies() -> dict[str, str]:
+    if not COOKIE_FILE.exists():
+        raise MoodleAuthError(f"还没登录 Moodle，先运行 `{LOGIN_HINT}`")
+    try:
+        jar = json.loads(COOKIE_FILE.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        jar = parse_cookie_input(COOKIE_FILE.read_text(encoding="utf-8"))
+    if not any(k.startswith("MoodleSession") for k in jar):
+        raise MoodleAuthError(f"{COOKIE_FILE} 里没有 MoodleSession")
+    return jar
+
+
+def save_cookies(jar: dict[str, str]) -> None:
+    write_secret(COOKIE_FILE, json.dumps(jar))
+
+
+# ---------------------------------------------------------------- HTTP
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args, **kwargs):
+        return None
+
+
+_opener = urllib.request.build_opener(_NoRedirect)
+
+
+@dataclass
+class Response:
+    status: int
+    url: str
+    headers: object
+    body: bytes = b""
+    location: str | None = None
+
+    def text(self) -> str:
+        return self.body.decode("utf-8", "replace")
+
+
+class MoodleClient:
+    def __init__(self, jar: dict[str, str] | None = None, persist: bool = True):
+        self.jar = jar if jar is not None else load_cookies()
+        self.persist = persist
+        self._sesskey: str | None = None
+        self.userid: int | None = None
+        self._last = 0.0
+
+    # 只有发往 Moodle 本站的请求才带 cookie。下载会被 302 到 CloudFront，
+    # 自己一步步跟跳转，保证 MoodleSession 不会被带到别的域名去。
+    def _request(self, url: str, *, data: bytes | None = None, headers: dict | None = None,
+                 stream_to: Path | None = None) -> Response:
+        gap = REQUEST_GAP - (time.monotonic() - self._last)
+        if gap > 0:
+            time.sleep(gap)
+        self._last = time.monotonic()
+        req = urllib.request.Request(url, data=data, method="POST" if data is not None else "GET")
+        req.add_header("User-Agent", UA)
+        for k, v in (headers or {}).items():
+            req.add_header(k, v)
+        parts = urllib.parse.urlsplit(url)
+        # 只发给本站，而且协议要和 BASE_URL 一样：http:// 的链接不带 cookie，免得明文发出去
+        if parts.hostname == HOST and parts.scheme == BASE_SCHEME:
+            req.add_unredirected_header("Cookie", "; ".join(f"{k}={v}" for k, v in self.jar.items()))
+        try:
+            resp = _opener.open(req, timeout=60)
+        except urllib.error.HTTPError as e:
+            resp = e
+        status = resp.status if hasattr(resp, "status") else resp.code
+        if parts.hostname == HOST and parts.scheme == BASE_SCHEME:
+            self._absorb_cookies(resp.headers)      # http:// 的回复可能被人改过，里面的 Set-Cookie 不收
+        location = resp.headers.get("Location")
+        out = Response(status, url, resp.headers,
+                       location=urllib.parse.urljoin(url, location) if location else None)
+        if stream_to is not None and status == 200:
+            tmp = stream_to.with_name(stream_to.name + ".part")
+            tmp.parent.mkdir(parents=True, exist_ok=True)
+            try:
+                with open(tmp, "wb") as f:
+                    while chunk := resp.read(1 << 16):
+                        f.write(chunk)
+            except BaseException:
+                tmp.unlink(missing_ok=True)      # 下到一半断了，别在课件目录里留半个文件
+                resp.close()
+                raise
+            os.replace(tmp, stream_to)
+        else:
+            out.body = resp.read()
+        resp.close()
+        return out
+
+    def _absorb_cookies(self, headers) -> None:
+        changed = False
+        for raw in headers.get_all("Set-Cookie") or []:
+            name, _, rest = raw.partition("=")
+            value = rest.split(";", 1)[0]
+            name = name.strip()
+            if not name or value in ("deleted", ""):
+                continue
+            if self.jar.get(name) != value:
+                self.jar[name] = value
+                changed = True
+        if changed and self.persist:
+            save_cookies(self.jar)
+
+    def get(self, url: str, max_hops: int = 8) -> Response:
+        """GET 本站页面，只在本站内跟跳转；被踢去 Okta 就当会话失效。"""
+        url = self.abs(url)
+        for _ in range(max_hops):
+            r = self._request(url)
+            if not _is_redirect(r):
+                return r
+            _check_login_url(r.location)
+            url = r.location
+        raise MoodleError(f"跳转太多：{url}")
+
+    def post(self, url: str, fields: list[tuple[str, str]] | None = None, *, body: bytes | None = None,
+             content_type: str | None = None, max_hops: int = 8) -> Response:
+        """POST 一个表单（或 multipart），然后像浏览器一样跟着 303 用 GET 走到最终页面。
+
+        返回的 Response.url 是最终落地的地址，Moodle 的表单靠"落在哪一页"
+        判断成功与否（比如生成日历链接后停在导出页）。
+        """
+        url = self.abs(url)
+        if body is None:
+            body = urllib.parse.urlencode(fields or []).encode()
+            content_type = "application/x-www-form-urlencoded"
+        r = self._request(url, data=body, headers={"Content-Type": content_type or "application/octet-stream"})
+        for _ in range(max_hops):
+            if not _is_redirect(r):
+                return r
+            _check_login_url(r.location)
+            r = self._request(r.location)
+        raise MoodleError(f"跳转太多：{url}")
+
+    def html(self, url: str) -> str:
+        r = self.get(url)
+        if r.status != 200:
+            raise MoodleError(f"GET {url} -> {r.status}")
+        return r.text()
+
+    @staticmethod
+    def abs(url: str) -> str:
+        return url if url.startswith("http") else BASE_URL + url
+
+
+    # ---------------------------------------------------------- AJAX
+
+    def sesskey(self) -> str:
+        if self._sesskey is None:
+            page = self.html("/my/courses.php")
+            m = re.search(r'"sesskey":"([^"]+)"', page)
+            if not m:
+                raise MoodleAuthError("页面里没有 sesskey，大概是没登录上")
+            self._sesskey = m.group(1)
+        return self._sesskey
+
+    def call(self, method: str, args: dict | None = None):
+        url = f"{BASE_URL}/lib/ajax/service.php?sesskey={self.sesskey()}&info={method}"
+        body = json.dumps([{"index": 0, "methodname": method, "args": args or {}}]).encode()
+        r = self._request(url, data=body, headers={"Content-Type": "application/json"})
+        if _is_redirect(r):
+            _check_login_url(r.location)
+        try:
+            payload = json.loads(r.body)
+        except json.JSONDecodeError:
+            raise MoodleAuthError(f"{method} 返回的不是 JSON（{r.status}），会话可能已失效")
+        first = payload[0] if isinstance(payload, list) and payload else payload
+        if isinstance(first, dict) and first.get("error"):
+            exc = first.get("exception") or {}
+            code = exc.get("errorcode", "")
+            if code in ("servicerequireslogin", "invalidsesskey", "requireloginerror"):
+                raise MoodleAuthError(f"{method}: {code}")
+            raise MoodleError(f"{method}: {exc.get('message') or first}")
+        if isinstance(first, dict) and "exception" in first:
+            raise MoodleError(f"{method}: {first.get('message')}")
+        return first.get("data") if isinstance(first, dict) else first
+
+    def time_remaining(self) -> int | None:
+        data = self.call("core_session_time_remaining")
+        if not isinstance(data, dict):
+            return None
+        self.userid = data.get("userid") or self.userid
+        return data.get("timeremaining")
+
+    def touch(self) -> int | None:
+        self.call("core_session_touch")
+        return self.time_remaining()
+
+    def courses(self) -> list[dict]:
+        data = self.call("core_course_get_enrolled_courses_by_timeline_classification",
+                         {"classification": "all", "limit": 0, "offset": 0, "sort": "fullname"})
+        return data["courses"]
+
+    def course_state(self, course_id: int) -> dict:
+        return json.loads(self.call("core_courseformat_get_state", {"courseid": course_id}))
+
+    # ---------------------------------------------------------- 下载
+
+    def resolve(self, url: str, max_hops: int = 8) -> tuple[str, str | None, Response]:
+        """只在本站内跟跳转，不下载正文。
+
+        返回 (最后一个本站 URL, 第一个站外地址或 None, 最后的响应)。本站 pluginfile
+        地址里带着文件的 revision 和文件名，拿它当变更指纹；站外地址（CloudFront、
+        Google Slides…）只记下来，不带 cookie 去碰。
+        """
+        url = self.abs(url)
+        for _ in range(max_hops):
+            r = self._request(url)
+            if not _is_redirect(r):
+                return url, None, r
+            _check_login_url(r.location)
+            if urllib.parse.urlsplit(r.location).hostname != HOST:
+                return url, r.location, r
+            url = r.location
+        raise MoodleError(f"跳转太多：{url}")
+
+    def download(self, url: str, dest: Path, max_hops: int = 8) -> Response:
+        """下载到 dest。站外那一跳（CloudFront 签名链接）不带 cookie。"""
+        url = self.abs(url)
+        for _ in range(max_hops):
+            r = self._request(url, stream_to=dest)
+            if not _is_redirect(r):
+                if r.status != 200:
+                    raise MoodleError(f"下载失败 {url} -> {r.status}")
+                return r
+            _check_login_url(r.location)
+            url = r.location
+        raise MoodleError(f"跳转太多：{url}")
+
+
+def multipart(fields: list[tuple[str, str]], files: list[tuple[str, str, bytes]]) -> tuple[bytes, str]:
+    """标准库没有 multipart 编码器，自己拼一个。files: (字段名, 文件名, 内容)。
+
+    本包只读，用不到；自己在服务器上部署、要交作业的话用它上传文件。"""
+    import secrets
+    boundary = "----mdl" + secrets.token_hex(12)
+    out = bytearray()
+    for name, value in fields:
+        out += (f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"\r\n\r\n').encode()
+        out += str(value).encode() + b"\r\n"
+    for name, filename, data in files:
+        safe = filename.replace('"', "%22")
+        out += (f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"; filename="{safe}"\r\n'
+                f"Content-Type: application/octet-stream\r\n\r\n").encode()
+        out += data + b"\r\n"
+    out += f"--{boundary}--\r\n".encode()
+    return bytes(out), f"multipart/form-data; boundary={boundary}"
+
+
+def _is_redirect(r: Response) -> bool:
+    return bool(r.location) and r.status in (301, 302, 303, 307, 308)
+
+
+def _check_login_url(url: str) -> None:
+    """在跟进跳转之前检查：要是往 Okta / 登录页跳，就是会话没了。
+
+    必须在请求之前查，不然下载时会把 Okta 登录页当成课件写进文件里。
+    """
+    parts = urllib.parse.urlsplit(url)
+    host = parts.hostname or ""
+    if host.endswith("okta.com") or (host == HOST and parts.path.startswith("/login/")) \
+            or (host == HOST and "/auth/saml" in parts.path):
+        raise MoodleAuthError(f"Moodle 登录已过期（被跳到登录页），运行 `{LOGIN_HINT}` 重新登录")
+
+
+def filename_from(resp: Response, fallback: str) -> str:
+    cd = resp.headers.get("Content-Disposition") or ""
+    m = re.search(r"filename\*=UTF-8''([^;]+)", cd) or re.search(r'filename="?([^";]+)"?', cd)
+    if m:
+        return urllib.parse.unquote(m.group(1))
+    path = urllib.parse.urlsplit(resp.url).path
+    name = urllib.parse.unquote(path.rsplit("/", 1)[-1])
+    return name or fallback
+
+
+# ---------------------------------------------------------------- HTML
+
+class LinkCollector(HTMLParser):
+    """按活动（li[data-id] / [data-for=cmitem]）归类收集链接。
+
+    课程页里 label、CMS 块的内容只出现在 HTML 里，接口不给，所以得自己扫。
+    """
+
+    def __init__(self):
+        super().__init__(convert_charrefs=True)
+        self.stack: list[tuple[str, str | None]] = []  # (tag, activity id or None)
+        self.by_activity: dict[str, list[tuple[str, str]]] = {}
+        self.all: list[tuple[str, str]] = []
+        self._a: tuple[str, list[str]] | None = None
+
+    def _current(self) -> str | None:
+        for _, act in reversed(self.stack):
+            if act:
+                return act
+        return None
+
+    VOID = {"br", "img", "input", "meta", "link", "hr", "source", "area", "base", "col", "wbr"}
+
+    def handle_starttag(self, tag, attrs):
+        a = dict(attrs)
+        act = None
+        cls = a.get("class") or ""
+        if tag == "li" and "activity" in cls.split() and a.get("data-id"):
+            act = a["data-id"]
+        if tag not in self.VOID:
+            self.stack.append((tag, act))
+        if tag == "a" and a.get("href"):
+            self._a = (a["href"], [])
+
+    def handle_endtag(self, tag):
+        if tag == "a" and self._a:
+            href, text = self._a
+            item = (href, " ".join("".join(text).split()))
+            self.all.append(item)
+            act = self._current()
+            if act:
+                self.by_activity.setdefault(act, []).append(item)
+            self._a = None
+        for i in range(len(self.stack) - 1, -1, -1):
+            if self.stack[i][0] == tag:
+                del self.stack[i:]
+                break
+
+    def handle_data(self, data):
+        if self._a:
+            self._a[1].append(data)
+
+
+def collect_links(html_text: str) -> LinkCollector:
+    p = LinkCollector()
+    p.feed(html_text)
+    p.close()
+    return p
+
+
+DOC_EXT = re.compile(r"\.(pdf|pptx?|docx?|xlsx?|zip|tar|gz|tgz|7z|rar|ipynb|py|hs|ts|js|java|c|cpp|h|"
+                     r"txt|md|csv|json|mzn|dzn|r|rmd|sql|mp4|mov|key|pages|numbers)$", re.I)
+
+
+def is_attachment(url: str) -> bool:
+    """本站 pluginfile 里真正的课件（排除主题图片、背景图之类）。"""
+    parts = urllib.parse.urlsplit(url)
+    if parts.hostname != HOST or "/pluginfile.php/" not in parts.path:
+        return False
+    if re.search(r"/(theme_|msttools_imglib|user/icon|core_admin|block_)", parts.path):
+        return False
+    return bool(DOC_EXT.search(urllib.parse.unquote(parts.path)))
+
+
+def db_connect(path: Path | None = None) -> sqlite3.Connection:
+    # MCP 的后台同步和工具调用会同时开库：WAL 让读写互不阻塞，timeout 兜住偶尔的写锁
+    path = path or DATA_DIR / "moodle.db"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    con = sqlite3.connect(path, timeout=30, check_same_thread=False)
+    con.row_factory = sqlite3.Row
+    con.execute("PRAGMA journal_mode=WAL")
+    con.executescript("""
+    CREATE TABLE IF NOT EXISTS files (
+        course_id   INTEGER NOT NULL,
+        source      TEXT NOT NULL,      -- 本站最后一个 URL（含 revision），当指纹
+        cmid        INTEGER,
+        path        TEXT NOT NULL,      -- 相对 FILES_DIR
+        size        INTEGER,
+        section     TEXT,
+        title       TEXT,
+        synced_at   TEXT NOT NULL,
+        removed_at  TEXT,               -- Moodle 上已经没有了：文件先留着，列表和搜索里不再出现
+        PRIMARY KEY (course_id, source)
+    );
+    CREATE TABLE IF NOT EXISTS links (
+        course_id INTEGER NOT NULL, folder TEXT NOT NULL, section TEXT,
+        title TEXT, url TEXT NOT NULL, synced_at TEXT NOT NULL,
+        PRIMARY KEY (course_id, folder, url)
+    );
+    CREATE TABLE IF NOT EXISTS courses (
+        id INTEGER PRIMARY KEY, code TEXT, folder TEXT, fullname TEXT,
+        tracked INTEGER DEFAULT 0, synced_at TEXT
+    );
+    CREATE TABLE IF NOT EXISTS state (k TEXT PRIMARY KEY, v TEXT);
+    """)
+    # 1.0.3 以前的库没有 removed_at，补上
+    if "removed_at" not in {r["name"] for r in con.execute("PRAGMA table_info(files)")}:
+        con.execute("ALTER TABLE files ADD COLUMN removed_at TEXT")
+    return con
+
+
+def removed_paths(con) -> set[str]:
+    """Moodle 上已经下架的文件（相对 FILES_DIR）。"""
+    return {r["path"] for r in con.execute("SELECT path FROM files WHERE removed_at IS NOT NULL")}
+
+
+def set_state(con, k: str, v) -> None:
+    con.execute("INSERT INTO state VALUES (?, ?) ON CONFLICT(k) DO UPDATE SET v=excluded.v",
+                (k, json.dumps(v)))
+    con.commit()
+
+
+def get_state(con, k: str, default=None):
+    row = con.execute("SELECT v FROM state WHERE k=?", (k,)).fetchone()
+    return json.loads(row["v"]) if row else default

monash_study_kit/output.py

@@ -0,0 +1,73 @@
+"""终端输出：交互终端里打表格，管道或 --json 时打 JSON。"""
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+import unicodedata
+from datetime import datetime, timezone
+
+
+def want_json(args) -> bool:
+    if getattr(args, "json", False):
+        return True
+    if getattr(args, "text", False):
+        return False
+    return not sys.stdout.isatty()
+
+
+def emit_json(data) -> None:
+    print(json.dumps(data, ensure_ascii=False, indent=2))
+
+
+def width(s: str) -> int:
+    return sum(2 if unicodedata.east_asian_width(ch) in "WF" else 1 for ch in s)
+
+
+def cut(s: str, n: int) -> str:
+    s = " ".join(str(s or "").split())
+    if width(s) <= n:
+        return s + " " * (n - width(s))
+    out, w = "", 0
+    for ch in s:
+        cw = width(ch)
+        if w + cw > n - 1:
+            break
+        out += ch
+        w += cw
+    return out + "…" + " " * (n - w - 1)
+
+
+def table(rows: list[dict], cols: list[tuple[str, str, int]]) -> None:
+    """cols: (key, 表头, 最大宽度)。最后一列吃掉剩余宽度。"""
+    if not rows:
+        print("（没有内容）")
+        return
+    term = shutil.get_terminal_size((120, 20)).columns
+    widths = []
+    for key, head, maxw in cols:
+        w = max([width(head)] + [width(" ".join(str(r.get(key) or "").split())) for r in rows])
+        widths.append(min(w, maxw))
+    used = sum(widths[:-1]) + 2 * (len(cols) - 1)
+    widths[-1] = max(10, min(widths[-1], term - used))
+    print("  ".join(cut(h, w) for (_, h, _), w in zip(cols, widths)).rstrip())
+    print("  ".join("─" * w for w in widths))
+    for r in rows:
+        print("  ".join(cut(r.get(k, ""), w) for (k, _, _), w in zip(cols, widths)).rstrip())
+
+
+def local_time(iso: str | None, fmt: str = "%m-%d %a %H:%M") -> str:
+    if not iso:
+        return "—"
+    return datetime.fromisoformat(iso).astimezone().strftime(fmt)   # 按这台电脑的时区
+
+
+def relative(iso: str | None) -> str:
+    if not iso:
+        return ""
+    delta = datetime.fromisoformat(iso) - datetime.now(timezone.utc)
+    secs = delta.total_seconds()
+    if secs < 0:
+        return "已过期"
+    days = int(secs // 86400)
+    return f"{days} 天后" if days else f"{int(secs // 3600)} 小时后"

monash_study_kit/paths.py

@@ -0,0 +1,126 @@
+"""所有东西放在哪：一个目录装下数据、课件、登录凭据和专用浏览器配置。
+
+    macOS    ~/Library/Application Support/monash-study-kit
+    Windows  %LOCALAPPDATA%\\monash-study-kit
+    Linux    ~/.local/share/monash-study-kit
+
+设 MONASH_KIT_HOME 可以换位置（测试也靠它）。卸载时删掉这个目录就干净了。
+用户可改的设置在 settings.json（`monash config`）。
+
+服务器上的部署把数据、凭据、Ed 库放在各自的目录，用这几个环境变量指过去：
+    MONASH_KIT_DATA     moodle.db 所在目录
+    MONASH_KIT_SECRETS  cookie、日历链接、Ed 令牌所在目录
+    MONASH_KIT_FILES    课件目录
+    MONASH_KIT_ED_DATA  Ed 的数据目录（里面是 ed.db 和 files/，ed-digest 就是这个布局）
+    MONASH_KIT_ED_TOKEN Ed 令牌文件
+settings.json 里的每一项也能用 MONASH_KIT_<大写名字> 覆盖，比如 MONASH_KIT_DOWNLOAD_VIDEOS=true。
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def _default_home() -> Path:
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "monash-study-kit"
+    if os.name == "nt":
+        base = os.environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
+        return Path(base) / "monash-study-kit"
+    base = os.environ.get("XDG_DATA_HOME") or str(Path.home() / ".local" / "share")
+    return Path(base) / "monash-study-kit"
+
+
+HOME = Path(os.environ.get("MONASH_KIT_HOME") or _default_home())
+SETTINGS_FILE = HOME / "settings.json"
+
+DEFAULTS = {
+    "download_videos": False,     # 录像动辄几百 MB；没装 [media] 转不了字幕，下下来 Claude 也看不了
+    "auto_sync_hours": 1,         # MCP 在跑的时候，多久在后台同步一次
+    "keepalive_minutes": 20,      # MCP 在跑的时候，多久给 Moodle 会话续一次期（空闲 4 小时就过期）
+    "tz_offset": 8,               # Moodle 账号的时区（页面上的时间按它显示）：马来西亚 8，澳洲 10（夏令时 11）
+    "files_dir": "",              # 课件放哪；空 = 数据目录下的 files。Windows 路径太长时改成 C:\\Monash 之类
+    "browser": "",                # 登录窗口用哪个浏览器程序；空 = 自动找 Chrome / Edge / Brave
+    "web_notes": True,            # 抓 Moodle / Ed 链接到的课程笔记网页（老师的 github.io 讲义站之类）进全文搜索
+    "update_check": True,         # 每天查一次 GitHub 上有没有新版本，有就提示
+    "name_limit": 80,             # 文件名最长几个字符：Windows 整条路径不能超过 260，课程/周次/文件夹/文件四层很容易超
+    "pdf_extractor": "pypdf",     # PDF 抽文字用什么：pypdf（随包装好）或 pdftotext（要另装 poppler，排版更准）
+}
+
+
+def _env_value(key: str, default):
+    """MONASH_KIT_<KEY> 覆盖一项设置，按默认值的类型转换。"""
+    raw = os.environ.get("MONASH_KIT_" + key.upper())
+    if raw is None:
+        return None
+    if isinstance(default, bool):
+        return raw.strip().lower() in ("1", "true", "yes", "on")
+    if isinstance(default, (int, float)):
+        try:
+            return type(default)(float(raw))
+        except ValueError:
+            return None
+    return raw
+
+
+def load_settings() -> dict:
+    try:
+        out = {**DEFAULTS, **json.loads(SETTINGS_FILE.read_text(encoding="utf-8"))}
+    except (OSError, ValueError):
+        out = dict(DEFAULTS)
+    for key, default in DEFAULTS.items():
+        v = _env_value(key, default)
+        if v is not None:
+            out[key] = v
+    return out
+
+
+# 设置在导入时读一次：Claude Desktop 启动的 MCP 读不到终端里设的环境变量，所以常用的都进 settings.json；
+# 环境变量仍然优先（测试和高级用法）。
+_s = load_settings()
+SECRETS_DIR = Path(os.environ.get("MONASH_KIT_SECRETS") or HOME / "secrets")   # Moodle cookie、Ed 令牌、日历链接（600 权限）
+DATA_DIR = Path(os.environ.get("MONASH_KIT_DATA") or HOME / "data")            # moodle.db、ed.db
+FILES_DIR = Path(os.environ.get("MONASH_KIT_FILES") or _s["files_dir"] or HOME / "files").expanduser()
+_ED_DATA = os.environ.get("MONASH_KIT_ED_DATA")
+ED_DB = Path(_ED_DATA) / "ed.db" if _ED_DATA else DATA_DIR / "ed.db"
+ED_FILES_DIR = Path(_ED_DATA) / "files" if _ED_DATA else DATA_DIR / "ed-files"   # Ed Lessons 的课件 PDF
+ED_TOKEN_FILE = Path(os.environ.get("MONASH_KIT_ED_TOKEN") or SECRETS_DIR / "ed-token")
+BROWSER_PROFILE = HOME / "browser-profile"   # 专用登录窗口的配置目录，和日常浏览器分开
+LOG_FILE = HOME / "mcp.log"
+TZ_OFFSET = float(os.environ.get("MONASH_KIT_TZ_OFFSET") or _s["tz_offset"])
+BROWSER = os.environ.get("MONASH_KIT_BROWSER") or _s["browser"]
+
+
+def ensure_private_dir(path: Path) -> None:
+    path.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(path, 0o700)
+    except OSError:
+        pass
+
+
+def write_secret(path: Path, text: str) -> None:
+    """原子写入、只有自己能读（Windows 上 chmod 不起作用，但目录本来就在用户自己的目录下）。"""
+    ensure_private_dir(path.parent)
+    # 临时文件名带进程号：Claude Desktop 和 Claude Code 各开一个 MCP，后台同步也会续 cookie，
+    # 共用一个 .tmp 会互相覆盖，后 replace 的那个直接报错
+    tmp = path.with_name(f"{path.name}.{os.getpid()}.tmp")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        f.write(text)
+    os.replace(tmp, path)
+
+
+def save_settings(values: dict) -> None:
+    HOME.mkdir(parents=True, exist_ok=True)
+    cur = {}
+    try:
+        cur = json.loads(SETTINGS_FILE.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        pass
+    cur.update(values)
+    tmp = SETTINGS_FILE.with_suffix(".tmp")
+    tmp.write_text(json.dumps(cur, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    os.replace(tmp, SETTINGS_FILE)