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

monash_study_kit/cli_ed.py

@@ -0,0 +1,238 @@
+"""monash ed …：查本地的 Ed 库（终端里是文本，管道/重定向时是 JSON，可用 --json/--text 强制）。
+
+    monash ed new                        # 上次看过之后的新帖/新回复
+    monash ed threads FIT2102 --since 7d --unanswered
+    monash ed search FIT2102 assignment deadline
+    monash ed show FIT2102#42 [--live]   # 正文 + 全部回复；--live 先从 Ed 重抓这一帖
+    monash ed following                  # 有未读新回复的帖子（我发的/关注的排前面）
+    monash ed lessons FIT2109 --module "Week 3"
+    monash ed quiz FIT2109               # Lessons 里的测验题（复习用；Ed 不公开答案）
+    monash ed read FIT2109 "W3 Pre-Class"  # 整节 lesson 的正文（Markdown，按页序，附测验题）
+"""
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime
+
+from . import edlib, edquery
+from .edquery import STATE_FILTERS
+
+
+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(args, data, render) -> int:
+    print(json.dumps(data, ensure_ascii=False, indent=2) if _want_json(args) else render(data))
+    return 0
+
+
+def _when(iso: str | None) -> str:
+    if not iso:
+        return "-"
+    try:
+        return datetime.fromisoformat(iso).astimezone().strftime("%m-%d %H:%M")
+    except ValueError:
+        return iso[:16]
+
+
+def _thread_line(t: dict) -> str:
+    flag = ("📌" if t["is_pinned"] else "") + ("🔒" if t["is_private"] else "")
+    if t["type"] == "question":
+        flag += "✅" if t["is_staff_answered"] or t["is_answered"] else "❓"
+    elif t["type"] == "announcement":
+        flag += "📣"
+    if t.get("is_starred"):
+        flag += "★"
+    unread = f"  (+{t['new_reply_count']} 未读)" if t.get("new_reply_count") else ""
+    return f"{t['ref']:<14} {_when(t['created_at'])}  {flag:<3} 💬{t['reply_count']:<3} {t['title']}{unread}"
+
+
+def _render_threads(rows: list[dict]) -> str:
+    if not rows:
+        return "（没有匹配的帖子）"
+    out = []
+    for t in rows:
+        out.append(_thread_line(t))
+        if t.get("snippet"):
+            out.append(f"{'':<16}{t['snippet']}")
+    return "\n".join(out)
+
+
+def _render_replies(t: dict, width: int = 160) -> list[str]:
+    out = []
+    for r in t["new_replies"]:
+        who = r["author"] + ("（教师/助教）" if r["is_staff"] else "")
+        text = " ".join((r["text"] or "").split())
+        out.append(f"{'':<16}↳ {who} {_when(r['created_at'])}：{text[:width]}{'…' if len(text) > width else ''}")
+    return out
+
+
+def cmd_courses(args):
+    rows = edquery.courses(edlib.db_connect())
+    return _emit(args, rows, lambda rs: "\n".join(
+        f"{r['id']:>7}  {'★' if r['tracked'] else ' '} {r['code']:<16} {r['threads']:>4} 帖  "
+        f"最新 {_when(r['latest'])}  {r['name']}" for r in rs) or "（还没同步过 Ed：monash sync）")
+
+
+def cmd_threads(args):
+    state = [k for k in STATE_FILTERS if getattr(args, k, False)]
+    rows = edquery.list_threads(edlib.db_connect(), args.course, args.since, args.category, args.type,
+                                args.unanswered, args.limit, args.offset, state)
+    return _emit(args, rows, _render_threads)
+
+
+def cmd_search(args):
+    conn = edlib.db_connect()
+    course, words = args.course, list(args.words)
+    if course:
+        try:                                   # 第一个词是课号就当课程，否则当搜索词
+            edquery.resolve_course(conn, course)
+        except edquery.NotFound:
+            words.insert(0, course)
+            course = None
+    rows = edquery.search(conn, " ".join(words), course, args.since, args.category, args.type, args.limit)
+    return _emit(args, rows, _render_threads)
+
+
+def cmd_show(args):
+    from . import edsync
+    conn = edlib.db_connect()
+    if args.live:
+        try:
+            tid = edquery.resolve_thread(conn, args.thread)
+        except edquery.NotFound:
+            if not str(args.thread).isdigit():
+                raise
+            tid = int(args.thread)
+        try:
+            edsync.refresh_thread(conn, tid)
+        except edlib.EdForbidden:
+            print("[注意] Ed 上已经看不到这个帖子了（被删除或改成私密），下面是库里的旧副本。", file=sys.stderr)
+        args.thread = str(tid)
+    return _emit(args, edquery.get_thread(conn, args.thread), edquery.thread_markdown)
+
+
+def _render_new(d: dict) -> str:
+    out = [f"自 {_when(d['since'])} 以来（最近一次同步 {_when(d['last_sync'])}）"]
+    if d["new_threads"]:
+        out += ["", f"## 新帖 {len(d['new_threads'])}", _render_threads(d["new_threads"])]
+    if d["threads_with_new_replies"]:
+        out += ["", f"## 有新回复 {len(d['threads_with_new_replies'])}"]
+        for t in d["threads_with_new_replies"]:
+            out.append(_thread_line(t))
+            out += _render_replies(t, 140)
+    if len(out) == 1:
+        out.append("没有新动态。")
+    return "\n".join(out)
+
+
+def cmd_new(args):
+    d = edquery.new_activity(edlib.db_connect(), args.since, args.course, cursor="cli",
+                             advance=not args.peek, limit=args.limit)
+    return _emit(args, d, _render_new)
+
+
+def _render_following(rows: list[dict]) -> str:
+    if not rows:
+        return "（没有未读的新回复）"
+    out = []
+    for t in rows:
+        who = "，".join(w for w, on in (("我发的", t["is_mine"]), ("关注", t["is_watched"]),
+                                        ("收藏", t["is_starred"])) if on)
+        out += ["", _thread_line(t) + (f"  [{who}]" if who else "")] + _render_replies(t)
+    return "\n".join(out).lstrip("\n")
+
+
+def cmd_following(args):
+    return _emit(args, edquery.following(edlib.db_connect(), args.course, args.limit), _render_following)
+
+
+def _render_lessons(rows: list[dict]) -> str:
+    if not rows:
+        return "（没有课程内容；先 monash sync）"
+    out, last = [], None
+    mark = {"completed": "✅", "attempted": "◐", "unattempted": "○"}
+    for x in rows:
+        if x["module"] != last:
+            out += ([""] if out else []) + [f"## {x['module'] or '（未分组）'}"]
+            last = x["module"]
+        due = f"  截止 {_when(x['due_at'])}" if x["due_at"] else ""
+        out.append(f"{mark.get(x['status'], '·')} {x['title']}  [{x['type']}]{due}")
+        for f in x["files"]:
+            where = f["file_url"] or f["url"] or "（正文已存到本地，monash grep 能搜到）"
+            out.append(f"     {'📄' if f['type'] == 'pdf' else '🔗' if f['type'] == 'webpage' else '📝'} "
+                       f"{f['title'] or f['type']}  {where}")
+    return "\n".join(out)
+
+
+def cmd_lessons(args):
+    return _emit(args, edquery.lessons(edlib.db_connect(), args.course, args.module, args.status), _render_lessons)
+
+
+def cmd_read(args):
+    from . import lesson_reader
+    d = lesson_reader.lesson_markdown(edlib.db_connect(), args.course, args.lesson)
+    return _emit(args, d, lambda x: x["markdown"])
+
+
+def cmd_quiz(args):
+    return _emit(args, edquery.quizzes(edlib.db_connect(), args.course, args.module, args.status),
+                 edquery.quiz_markdown)
+
+
+def add_commands(sub) -> None:
+    def out(name, fn, **kw):
+        p = sub.add_parser(name, **kw)
+        g = p.add_mutually_exclusive_group()
+        g.add_argument("--json", action="store_true", help="输出 JSON（管道里默认就是）")
+        g.add_argument("--text", action="store_true", help="输出文本（终端里默认就是）")
+        p.set_defaults(fn=fn)
+        return p
+
+    def filters(p):
+        p.add_argument("--since", help="只看这之后发的：7d / 12h / 2w / 2026-09-01")
+        p.add_argument("--category", help="分类（或子分类）包含这个词")
+        p.add_argument("--type", choices=["question", "post", "announcement"])
+        p.add_argument("--limit", type=int, default=20)
+
+    out("courses", cmd_courses, help="本地库里的课程")
+    p = out("threads", cmd_threads, help="列帖子（最新在前）")
+    p.add_argument("course", nargs="?", help="课号；不给就是全部跟踪的课")
+    filters(p)
+    p.add_argument("--unanswered", action="store_true", help="只看还没人回答的提问")
+    p.add_argument("--starred", action="store_true", help="只看我收藏的")
+    p.add_argument("--watching", action="store_true", help="只看我关注的")
+    p.add_argument("--mine", action="store_true", help="只看我发的")
+    p.add_argument("--unseen", action="store_true", help="只看还没点开过的")
+    p.add_argument("--unread-replies", dest="unread_replies", action="store_true", help="只看有新回复的")
+    p.add_argument("--offset", type=int, default=0)
+    p = out("search", cmd_search, help="搜标题、正文和回复（每个词都要出现）")
+    p.add_argument("course", help="课号（可省略：第一个词不是课号时就当搜索词）")
+    p.add_argument("words", nargs="*")
+    filters(p)
+    p = out("show", cmd_show, help="读一个帖子：正文 + 全部回复")
+    p.add_argument("thread", help="FIT2102#42、帖子 id 或 Ed 链接")
+    p.add_argument("--live", action="store_true", help="先从 Ed 重抓这一帖")
+    p = out("new", cmd_new, help="上次看过之后的新帖和新回复")
+    p.add_argument("course", nargs="?")
+    p.add_argument("--since", help="不用游标，看这之后的：7d / 2026-09-20")
+    p.add_argument("--peek", action="store_true", help="看完不推进游标")
+    p.add_argument("--limit", type=int, default=50)
+    p = out("following", cmd_following, help="有未读新回复的帖子")
+    p.add_argument("course", nargs="?")
+    p.add_argument("--limit", type=int, default=30)
+    p = out("read", cmd_read, help="整节 lesson 的正文：文字页、阅读网页、PDF 按页序拼成 Markdown，附测验题")
+    p.add_argument("course")
+    p.add_argument("lesson", help="lesson id 或标题的一部分，如 'W3 Pre-Class'")
+    for name, fn, h in (("lessons", cmd_lessons, "课程内容（Lessons）和课件"),
+                        ("quiz", cmd_quiz, "Lessons 里的测验题（题面+选项）")):
+        p = out(name, fn, help=h)
+        p.add_argument("course")
+        p.add_argument("--module", help="模块名的一部分，如 'Week 3'")
+        p.add_argument("--status", help="completed / attempted / unattempted / all")

monash_study_kit/clients.py

@@ -0,0 +1,230 @@
+"""把 monash MCP 接进 Claude 以外的 AI 软件：Codex、Cursor、VS Code、Windsurf、Gemini CLI。
+
+都是本地 stdio MCP，只是每家配置文件的位置和格式不一样。原则：
+- 只改 monash 这一项，文件里别的内容原样保留，改之前备份。
+- 软件自己有 `xxx mcp add` 命令的（Codex），优先用它；没有或失败了再直接改文件。
+- 文件不是合法 JSON（比如带注释）就不动它，打印出要加的那段让用户自己贴。
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+from .claude_setup import SERVER_NAME, server_command
+
+
+@dataclass
+class Client:
+    key: str
+    name: str
+    path: Callable[[], Path]
+    fmt: str                 # "json"：mcpServers；"vscode"：servers + type；"toml"：Codex
+    after: str               # 接好以后要做什么才能用上
+
+
+def _vscode_user_dir() -> Path:
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "Code" / "User"
+    if os.name == "nt":
+        return Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming")) / "Code" / "User"
+    return Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / "Code" / "User"
+
+
+def _codex_home() -> Path:
+    return Path(os.environ["CODEX_HOME"]) if os.environ.get("CODEX_HOME") else Path.home() / ".codex"
+
+
+CLIENTS: dict[str, Client] = {c.key: c for c in [
+    Client("codex", "Codex", lambda: _codex_home() / "config.toml", "toml",
+           "新开一个 Codex 会话，输入 /mcp 能看到 monash。"),
+    Client("cursor", "Cursor", lambda: Path.home() / ".cursor" / "mcp.json", "json",
+           "重启 Cursor（或 Cmd/Ctrl+Shift+P → Developer: Reload Window），在 Settings → MCP 里能看到 monash。"),
+    Client("vscode", "VS Code", lambda: _vscode_user_dir() / "mcp.json", "vscode",
+           "在 VS Code 的 Copilot Chat 里切到 Agent 模式，工具列表里能看到 monash。第一次用时 VS Code 会问你是否信任它。"),
+    Client("windsurf", "Windsurf", lambda: Path.home() / ".codeium" / "windsurf" / "mcp_config.json", "json",
+           "重启 Windsurf，或在 Cascade 面板的 MCP 图标里点刷新。"),
+    Client("gemini", "Gemini CLI", lambda: Path.home() / ".gemini" / "settings.json", "json",
+           "重新打开 gemini，输入 /mcp 能看到 monash。"),
+]}
+
+
+def entry(fmt: str, command: list[str]) -> dict:
+    e = {"command": command[0], "args": command[1:]}
+    return {"type": "stdio", **e} if fmt == "vscode" else e
+
+
+def snippet(client: Client, command: list[str]) -> str:
+    """要加进配置文件的那一段，给 --print 和改不了文件时用。"""
+    if client.fmt == "toml":
+        return _toml_table(command)
+    key = "servers" if client.fmt == "vscode" else "mcpServers"
+    return json.dumps({key: {SERVER_NAME: entry(client.fmt, command)}}, ensure_ascii=False, indent=2)
+
+
+def detected(client: Client) -> bool:
+    """配置文件或它所在的文件夹在，就当这个软件装过。"""
+    p = client.path()
+    return p.exists() or p.parent.exists()
+
+
+def _backup(path: Path, raw: str) -> Path:
+    backup = path.with_name(path.name + f".bak-{time.strftime('%Y%m%d%H%M%S')}")
+    backup.write_text(raw, encoding="utf-8")
+    return backup
+
+
+def _atomic_write(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(text, encoding="utf-8")
+    os.replace(tmp, path)
+
+
+# ---------------------------------------------------------------- JSON（Cursor、VS Code、Windsurf、Gemini CLI）
+
+def write_json(path: Path, fmt: str, command: list[str]) -> Path | None:
+    """加上（或更新）monash 这一项，其他内容原样保留。返回备份路径。文件不是合法 JSON 时抛 ValueError。"""
+    cfg, backup = {}, None
+    if path.exists():
+        raw = path.read_text(encoding="utf-8")
+        cfg = json.loads(raw) if raw.strip() else {}
+        if not isinstance(cfg, dict):
+            raise ValueError(f"{path} 不是一个 JSON 对象")
+        backup = _backup(path, raw)
+    key = "servers" if fmt == "vscode" else "mcpServers"
+    cfg.setdefault(key, {})[SERVER_NAME] = entry(fmt, command)
+    _atomic_write(path, json.dumps(cfg, ensure_ascii=False, indent=2) + "\n")
+    return backup
+
+
+def remove_json(path: Path, fmt: str) -> bool:
+    if not path.exists():
+        return False
+    try:
+        cfg = json.loads(path.read_text(encoding="utf-8") or "{}")
+    except ValueError:
+        return False
+    key = "servers" if fmt == "vscode" else "mcpServers"
+    if not isinstance(cfg, dict) or SERVER_NAME not in (cfg.get(key) or {}):
+        return False
+    del cfg[key][SERVER_NAME]
+    _atomic_write(path, json.dumps(cfg, ensure_ascii=False, indent=2) + "\n")
+    return True
+
+
+# ---------------------------------------------------------------- TOML（Codex）
+# Python 3.10 没有 tomllib，这里只按行处理 [mcp_servers.monash] 这一张表，文件其他部分一个字不动。
+
+_HEADER = re.compile(r"^\s*\[\[?\s*([^\]]+?)\s*\]\]?\s*(#.*)?$")
+
+
+def _toml_str(s: str) -> str:
+    return json.dumps(s, ensure_ascii=False)    # JSON 字符串的转义规则在这里和 TOML basic string 一样
+
+
+def _toml_table(command: list[str]) -> str:
+    args = ", ".join(_toml_str(a) for a in command[1:])
+    return f"[mcp_servers.{SERVER_NAME}]\ncommand = {_toml_str(command[0])}\nargs = [{args}]\n"
+
+
+def _strip_table(text: str) -> tuple[str, bool]:
+    """去掉 [mcp_servers.monash] 和它的子表，返回 (剩下的内容, 有没有去掉东西)。"""
+    ours = f"mcp_servers.{SERVER_NAME}"
+    out, skipping, found = [], False, False
+    for line in text.splitlines(keepends=True):
+        m = _HEADER.match(line)
+        if m:
+            name = m.group(1).replace('"', "").replace(" ", "")
+            skipping = name == ours or name.startswith(ours + ".")
+            found = found or skipping
+        if not skipping:
+            out.append(line)
+    return "".join(out), found
+
+
+def write_toml(path: Path, command: list[str]) -> Path | None:
+    raw = path.read_text(encoding="utf-8") if path.exists() else ""
+    backup = _backup(path, raw) if path.exists() else None
+    rest, _ = _strip_table(raw)
+    rest = rest.rstrip("\n")
+    _atomic_write(path, (rest + "\n\n" if rest else "") + _toml_table(command))
+    return backup
+
+
+def remove_toml(path: Path) -> bool:
+    if not path.exists():
+        return False
+    rest, found = _strip_table(path.read_text(encoding="utf-8"))
+    if found:
+        _atomic_write(path, rest.rstrip("\n") + "\n" if rest.strip() else "")
+    return found
+
+
+# ---------------------------------------------------------------- 对外
+
+def _codex_cli(command: list[str]) -> bool:
+    codex = shutil.which("codex")
+    if not codex:
+        return False
+    subprocess.run([codex, "mcp", "remove", SERVER_NAME], capture_output=True)
+    r = subprocess.run([codex, "mcp", "add", SERVER_NAME, "--", *command], capture_output=True, text=True)
+    return r.returncode == 0
+
+
+def connect(key: str, log=print) -> bool:
+    client = CLIENTS[key]
+    command = server_command()
+    path = client.path()
+    try:
+        if client.fmt == "toml":
+            if _codex_cli(command):
+                log(f"已用 codex mcp add 把 monash 加进 {client.name}")
+                log(client.after)
+                return True
+            backup = write_toml(path, command)
+        else:
+            backup = write_json(path, client.fmt, command)
+    except (ValueError, OSError) as e:
+        log(f"没能自动改 {path}：{e}")
+        log("请打开这个文件，把下面这段合并进去（已有的内容别删）：\n")
+        log(snippet(client, command))
+        return False
+    log(f"已把 monash 加进 {client.name}（{path}）" + (f"，原配置备份在 {backup.name}" if backup else ""))
+    log(client.after)
+    return True
+
+
+def disconnect(key: str) -> bool:
+    client = CLIENTS[key]
+    path = client.path()
+    if client.fmt == "toml":
+        codex = shutil.which("codex")
+        if codex and subprocess.run([codex, "mcp", "remove", SERVER_NAME], capture_output=True).returncode == 0:
+            remove_toml(path)
+            return True
+        return remove_toml(path)
+    return remove_json(path, client.fmt)
+
+
+def is_connected(key: str) -> bool:
+    client = CLIENTS[key]
+    path = client.path()
+    if not path.exists():
+        return False
+    text = path.read_text(encoding="utf-8", errors="replace")
+    if client.fmt == "toml":
+        return _strip_table(text)[1]
+    try:
+        cfg = json.loads(text or "{}")
+    except ValueError:
+        return False
+    key_name = "servers" if client.fmt == "vscode" else "mcpServers"
+    return isinstance(cfg, dict) and SERVER_NAME in (cfg.get(key_name) or {})