dsh-zju-lecture-note 2.2.8 → 2.2.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,19 +1,19 @@
1
1
  {
2
2
  "name": "zju-lecture-summarizer",
3
- "version": "2.2.8",
4
- "contentHash": "sha256:b2095059461297e200f3348ab835b3272962daabe0479beed156c9c1b348e880",
3
+ "version": "2.2.9",
4
+ "contentHash": "sha256:9a1e26141a9cf32f38a7ad9c8290cf5a50b0d150638463d6db270667e8214eae",
5
5
  "fileCount": 2,
6
6
  "files": [
7
7
  {
8
8
  "path": "SKILL.md",
9
- "sha256": "b2095059461297e200f3348ab835b3272962daabe0479beed156c9c1b348e880",
10
- "size": 26431,
9
+ "sha256": "9a1e26141a9cf32f38a7ad9c8290cf5a50b0d150638463d6db270667e8214eae",
10
+ "size": 28438,
11
11
  "mode": "0644"
12
12
  },
13
13
  {
14
14
  "path": "SLIDES.md",
15
- "sha256": "a66fe2e3b88c28bcd8280d07dcc7508f986259eca6d512a0fc4f081dcaae2ae3",
16
- "size": 7110,
15
+ "sha256": "a4588d67c0a1d6e72b9b685d143ff262e50134cf1ce30582c67a589c6dfbd858",
16
+ "size": 8237,
17
17
  "mode": "0644"
18
18
  }
19
19
  ]
@@ -9,14 +9,17 @@ ship this same implementation, so their tools behave identically.
9
9
 
10
10
  from .client import (
11
11
  BASE_URL,
12
+ INTERACTIVE_BASE_URL,
12
13
  ZJUAPIError,
13
14
  extract_classroom_token,
14
15
  fetch_slides,
15
16
  fetch_transcript,
16
17
  fetch_video_url,
18
+ is_allowed_image_host,
17
19
  is_zju_host,
18
20
  normalize_slide,
19
21
  parse_lecture_url,
22
+ secure_image_url,
20
23
  secure_zju_url,
21
24
  )
22
25
  from .cookies import CookieAccessError, get_edge_cookie, read_edge_cookies
@@ -99,6 +102,7 @@ def __getattr__(name: str):
99
102
 
100
103
  __all__ = [
101
104
  "BASE_URL",
105
+ "INTERACTIVE_BASE_URL",
102
106
  "ZJUAPIError",
103
107
  "CookieAccessError",
104
108
  "CoursewareError",
@@ -110,6 +114,8 @@ __all__ = [
110
114
  "normalize_slide",
111
115
  "extract_classroom_token",
112
116
  "is_zju_host",
117
+ "is_allowed_image_host",
118
+ "secure_image_url",
113
119
  "secure_zju_url",
114
120
  "download_slides",
115
121
  "build_slides_pdf",
@@ -213,7 +213,8 @@ def _validated_payload(cookie: str, browser: str = "") -> Dict[str, Any]:
213
213
  if not extract_classroom_token(header):
214
214
  raise LoginError(
215
215
  "登录态里没有 _token,无法用于字幕鉴权。",
216
- "请确认登录的是 classroom.zju.edu.cn(不是其他浙大站点),然后重试。",
216
+ "请确认登录的是智云课堂 / 互动式课堂(classroom.zju.edu.cn 或 "
217
+ "interactivemeta.cmc.zju.edu.cn),而不是其他浙大站点,然后重试。",
217
218
  reason="save_failed",
218
219
  )
219
220
  return {
@@ -1,6 +1,7 @@
1
1
  # -*- coding: utf-8 -*-
2
2
  """
3
- Client for Zhejiang University 智云课堂 (classroom.zju.edu.cn) APIs.
3
+ Client for Zhejiang University 智云课堂 (classroom.zju.edu.cn) and the
4
+ interactive-classroom backend (interactivemeta.cmc.zju.edu.cn) APIs.
4
5
  Pure Python standard library implementation with zero external dependencies.
5
6
  """
6
7
 
@@ -21,6 +22,9 @@ from typing import Any, Dict, List, Optional, Tuple
21
22
  from .security import REDACTOR, sanitize_cookie_header
22
23
 
23
24
  BASE_URL = "https://classroom.zju.edu.cn"
25
+ #: 互动式课堂回放与备用 API 后端;回放链接形如
26
+ #: ``https://interactivemeta.cmc.zju.edu.cn/#/replay?course_id=...&sub_id=...``。
27
+ INTERACTIVE_BASE_URL = "https://interactivemeta.cmc.zju.edu.cn"
24
28
  BASE_HOST = (urllib.parse.urlparse(BASE_URL).hostname or "classroom.zju.edu.cn").lower()
25
29
  USER_AGENT = (
26
30
  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
@@ -312,17 +316,19 @@ def _redirect_block_reason(old_url: str, new_url: str) -> str:
312
316
 
313
317
 
314
318
  class _SameHostRedirectHandler(urllib.request.HTTPRedirectHandler):
315
- """Follow redirects only on the classroom **origin**.
319
+ """Follow redirects only on the **same origin as the request**.
316
320
 
317
321
  ``urllib`` re-sends request headers on a redirect, so a compromised or
318
322
  misconfigured endpoint that answers ``302`` to another origin would leak
319
- the ``Cookie`` header. Scheme, host and port must all match — a downgrade
320
- to HTTP or a different port is refused as well.
323
+ the ``Cookie`` / ``Authorization`` headers. This is used for both the
324
+ primary classroom host and the interactive-classroom backend; scheme, host
325
+ and port must all match the request — a downgrade to HTTP or a different
326
+ port is refused as well.
321
327
  """
322
328
 
323
329
  def redirect_request(self, req, fp, code, msg, headers, newurl): # noqa: D401
324
330
  reason = _redirect_block_reason(req.full_url, newurl)
325
- if not reason and _origin(newurl) != _origin(BASE_URL):
331
+ if not reason and _origin(newurl) != _origin(req.full_url):
326
332
  reason = f"拒绝跨域重定向到 {_origin(newurl)[1] or '(未知主机)'}(保护登录凭据)"
327
333
  if reason:
328
334
  raise urllib.error.HTTPError(
@@ -338,11 +344,11 @@ class _SameHostRedirectHandler(urllib.request.HTTPRedirectHandler):
338
344
  class _StripAuthOnCrossHostRedirectHandler(urllib.request.HTTPRedirectHandler):
339
345
  """Allow slide-CDN redirects, but never carry credentials across origins.
340
346
 
341
- Slide screenshots are static files and may redirect to a media host. Only
342
- ``*.zju.edu.cn`` targets are followed (one hop at a time, re-validated by
343
- urllib for every hop); everything else is blocked and recorded. Whenever
344
- the redirect changes scheme/host/port, ``Cookie`` / ``Authorization`` /
345
- ``Proxy-Authorization`` are dropped.
347
+ Slide screenshots are static files and may redirect to a ZJU media host or
348
+ an official image CDN. Only those targets are followed (one hop at a time,
349
+ re-validated by urllib for every hop); everything else is blocked and
350
+ recorded. Whenever the redirect changes scheme/host/port, ``Cookie`` /
351
+ ``Authorization`` / ``Proxy-Authorization`` are dropped.
346
352
  """
347
353
 
348
354
  def __init__(self, diagnostics: Optional[List[str]] = None) -> None:
@@ -357,8 +363,11 @@ class _StripAuthOnCrossHostRedirectHandler(urllib.request.HTTPRedirectHandler):
357
363
  reason = _redirect_block_reason(req.full_url, newurl)
358
364
  if not reason:
359
365
  _, new_host, _ = _origin(newurl)
360
- if not is_zju_host(new_host):
361
- reason = f"已阻止跳转到非浙大域: {new_host or '(未知主机)'}"
366
+ if not is_allowed_image_host(new_host):
367
+ reason = (
368
+ "已阻止跳转到非浙大域/非官方图片 CDN: "
369
+ f"{new_host or '(未知主机)'}"
370
+ )
362
371
  if reason:
363
372
  self._blocked(reason)
364
373
  return None
@@ -403,13 +412,27 @@ class TranscriptAuthError(ZJUAPIError):
403
412
  super().__init__(f"字幕接口返回 HTTP {status},当前请求未获访问许可。")
404
413
 
405
414
 
415
+ def _fragment_query(fragment: str) -> Dict[str, List[str]]:
416
+ """Parse the query part of a hash-route fragment.
417
+
418
+ The interactive classroom page uses ``#/replay?course_id=...&sub_id=...``;
419
+ ``urllib.parse.urlparse`` puts everything after ``#`` in ``fragment``, so a
420
+ normal ``parse_qs(parsed.query)`` would see nothing.
421
+ """
422
+ value = (fragment or "").strip()
423
+ if "?" in value:
424
+ value = value.split("?", 1)[1]
425
+ return urllib.parse.parse_qs(value)
426
+
427
+
406
428
  def parse_lecture_url(url_or_sub_id: str) -> Dict[str, str]:
407
- """Extract course_id, sub_id, and tenant_code from a classroom URL or sub_id.
408
-
409
- Accepts:
410
- - Full livingroom URL: https://classroom.zju.edu.cn/livingroom?course_id=123&sub_id=456&tenant_code=112
411
- - Short query string: ?sub_id=456
412
- - Pure sub_id integer string: "456"
429
+ """Extract course_id, sub_id, and tenant_code from a replay URL or sub_id.
430
+
431
+ Accepts both classroom link shapes:
432
+ - ``https://classroom.zju.edu.cn/livingroom?course_id=...&sub_id=...``
433
+ - ``https://interactivemeta.cmc.zju.edu.cn/#/replay?course_id=...&sub_id=...``
434
+ - a short query string ``?sub_id=456``
435
+ - a pure sub_id integer string ``"456"``
413
436
  """
414
437
  url_or_sub_id = url_or_sub_id.strip()
415
438
  if not url_or_sub_id:
@@ -426,6 +449,12 @@ def parse_lecture_url(url_or_sub_id: str) -> Dict[str, str]:
426
449
  try:
427
450
  parsed = urllib.parse.urlparse(url_or_sub_id)
428
451
  query = urllib.parse.parse_qs(parsed.query)
452
+ # Hash routes keep the replay parameters after ``#``. Merge them in
453
+ # only when the outer query has no sub_id, so a normal livingroom URL
454
+ # cannot be overridden by an unrelated fragment.
455
+ if parsed.fragment and not query.get("sub_id"):
456
+ for key, values in _fragment_query(parsed.fragment).items():
457
+ query.setdefault(key, values)
429
458
  except Exception as e:
430
459
  raise ZJUAPIError(f"URL 格式解析失败: {e}")
431
460
 
@@ -439,7 +468,11 @@ def parse_lecture_url(url_or_sub_id: str) -> Dict[str, str]:
439
468
  break
440
469
 
441
470
  if not sub_id:
442
- raise ZJUAPIError("无法从 URL 中识别 sub_id 参数,请确认输入包含有效 sub_id")
471
+ raise ZJUAPIError(
472
+ "无法从 URL 中识别 sub_id。请粘贴完整回放地址,支持两种形态:\n"
473
+ " · https://classroom.zju.edu.cn/livingroom?course_id=...&sub_id=...\n"
474
+ " · https://interactivemeta.cmc.zju.edu.cn/#/replay?course_id=...&sub_id=..."
475
+ )
443
476
 
444
477
  return {
445
478
  "course_id": query.get("course_id", [""])[0],
@@ -482,10 +515,19 @@ def fetch_transcript(
482
515
  *,
483
516
  cookie: Optional[str] = None,
484
517
  ) -> List[Dict[str, Any]]:
485
- """Fetch transcript segments, optionally authenticating with a locally supplied session."""
518
+ """Fetch transcript segments, optionally authenticating with a local session.
519
+
520
+ The primary classroom backend is tried first. When a cookie is supplied,
521
+ the interactive-classroom backend (``interactivemeta.cmc.zju.edu.cn``) is
522
+ tried as a fallback; both accept the same ``search-trans-result`` path and
523
+ the Bearer token extracted from ``_token``. Subtitle requests deliberately
524
+ do **not** send the Cookie header: the Bearer token alone is sufficient and
525
+ keeps the credential surface minimal.
526
+ """
486
527
  query = urllib.parse.urlencode({"sub_id": sub_id, "tenant_code": tenant_code, "format": "json"})
487
- url = f"{BASE_URL}/courseapi/v3/web-socket/search-trans-result?{query}"
488
- req_headers = {"User-Agent": USER_AGENT}
528
+ path = f"/courseapi/v3/web-socket/search-trans-result?{query}"
529
+
530
+ token: Optional[str] = None
489
531
  if cookie is not None:
490
532
  cookie = sanitize_cookie_header(cookie)
491
533
  REDACTOR.add_cookie(cookie)
@@ -495,29 +537,66 @@ def fetch_transcript(
495
537
  "本地登录态缺少可用的 _token,无法进行字幕鉴权;请重新登录智云课堂并更新本机登录态。"
496
538
  )
497
539
  REDACTOR.add(token)
498
- req_headers["Authorization"] = f"Bearer {token}"
499
- try:
500
- data = json.loads(_fetch_bytes(url, req_headers, timeout).decode("utf-8"))
501
- except urllib.error.HTTPError as e:
502
- e.close()
503
- if e.code in (401, 403):
504
- raise TranscriptAuthError(e.code) from e
505
- raise ZJUAPIError(f"字幕接口返回 HTTP {e.code}。") from e
506
- except Exception as e:
507
- raise ZJUAPIError(
508
- "请求字幕接口失败。\n" + REDACTOR.redact(describe_network_error(e))
509
- ) from e
510
-
511
- code = data.get("code")
512
- if code != 0:
513
- msg = REDACTOR.redact(data.get("msg") or f"未知错误 (code={code})")
514
- raise ZJUAPIError(f"字幕接口返回非零状态码: {msg}")
540
+ origins = (BASE_URL, INTERACTIVE_BASE_URL)
541
+ else:
542
+ origins = (BASE_URL,)
543
+
544
+ data: Optional[Dict[str, Any]] = None
545
+ last_error = ""
546
+ auth_status: Optional[int] = None
547
+ saw_non_auth_error = False
548
+ for origin in origins:
549
+ headers = {
550
+ "User-Agent": USER_AGENT,
551
+ "Referer": f"{origin}/",
552
+ }
553
+ if token:
554
+ headers["Authorization"] = f"Bearer {token}"
555
+ try:
556
+ payload = json.loads(_fetch_bytes(f"{origin}{path}", headers, timeout).decode("utf-8"))
557
+ except urllib.error.HTTPError as error:
558
+ error.close()
559
+ last_error = f"HTTP {error.code}"
560
+ if error.code in (401, 403):
561
+ auth_status = error.code
562
+ else:
563
+ saw_non_auth_error = True
564
+ continue
565
+ except Exception as error: # noqa: BLE001 - aggregate attempts below
566
+ last_error = REDACTOR.redact(describe_network_error(error))
567
+ saw_non_auth_error = True
568
+ continue
515
569
 
516
- items = data.get("list") or []
517
- if not items:
518
- raise ZJUAPIError("字幕数据列表为空,可能课程刚结束尚未生成字幕或该课程未开启录制转写")
570
+ if not isinstance(payload, dict):
571
+ last_error = "接口返回了非对象 JSON,可能改版了"
572
+ saw_non_auth_error = True
573
+ continue
574
+ code = payload.get("code")
575
+ if code != 0:
576
+ message = REDACTOR.redact(payload.get("msg") or f"未知错误 (code={code})")
577
+ last_error = f"字幕接口返回非零状态码: {message}"
578
+ saw_non_auth_error = True
579
+ continue
580
+ if not payload.get("list"):
581
+ last_error = "字幕数据列表为空,可能课程刚结束尚未生成字幕或该课程未开启录制转写"
582
+ saw_non_auth_error = True
583
+ continue
584
+ data = payload
585
+ break
586
+
587
+ if data is None:
588
+ if cookie is None:
589
+ if auth_status is not None:
590
+ raise TranscriptAuthError(auth_status)
591
+ raise ZJUAPIError("请求字幕接口失败。\n" + last_error)
592
+ if auth_status is not None and not saw_non_auth_error:
593
+ raise TranscriptAuthError(auth_status)
594
+ raise ZJUAPIError(
595
+ "字幕接口抓取失败(主站与互动式课堂后端均不可用)。\n"
596
+ + (last_error or "未获得可用的字幕响应")
597
+ )
519
598
 
520
- raw_segments = items[0].get("all_content") or []
599
+ raw_segments = data["list"][0].get("all_content") or []
521
600
  # 老课程(trans_type="ai")只有 time/zhtext/entext,没有 BeginSec;
522
601
  # 用第一条时间戳作为相对零点,至少保证顺序与间隔正确。
523
602
  uses_clock = not any(item.get("BeginSec") not in (None, "") for item in raw_segments)
@@ -569,6 +648,32 @@ def is_zju_host(host: Optional[str]) -> bool:
569
648
  return value == "zju.edu.cn" or value.endswith(".zju.edu.cn")
570
649
 
571
650
 
651
+ _IMAGE_HOST_SUFFIXES = (
652
+ ".zju.edu.cn",
653
+ ".chinamcloud.com",
654
+ ".chinamcloud.cn",
655
+ ".chinamcache.com",
656
+ )
657
+
658
+
659
+ def is_allowed_image_host(host: Optional[str]) -> bool:
660
+ """True for ZJU hosts and the official image CDNs used by the classroom.
661
+
662
+ The interactive-classroom projector backend may return screenshots from
663
+ ``chinamcloud`` / ``chinamcache``. These are a closed allowlist, never a
664
+ wildcard: lookalikes such as ``evilchinamcloud.com`` do not match.
665
+ """
666
+ value = (host or "").strip().lower().rstrip(".")
667
+ if not value:
668
+ return False
669
+ if is_zju_host(value):
670
+ return True
671
+ return any(
672
+ value == suffix.lstrip(".") or value.endswith(suffix)
673
+ for suffix in _IMAGE_HOST_SUFFIXES
674
+ )
675
+
676
+
572
677
  def secure_zju_url(url: str) -> str:
573
678
  """Upgrade ZJU ``http://`` URLs to HTTPS; leave other URLs untouched.
574
679
 
@@ -584,6 +689,17 @@ def secure_zju_url(url: str) -> str:
584
689
  return value
585
690
 
586
691
 
692
+ def secure_image_url(url: str) -> str:
693
+ """Normalise an image URL and upgrade allowed image hosts to HTTPS."""
694
+ value = (url or "").strip()
695
+ if value.startswith("//"):
696
+ value = "https:" + value
697
+ parsed = urllib.parse.urlparse(value)
698
+ if parsed.scheme.lower() == "http" and is_allowed_image_host(parsed.hostname):
699
+ return "https" + value[4:]
700
+ return value
701
+
702
+
587
703
  def extract_classroom_token(cookie_header: str) -> Optional[str]:
588
704
  """Extract the classroom Bearer token from a Cookie header.
589
705
 
@@ -615,12 +731,24 @@ def _classroom_headers(
615
731
  cookie: str,
616
732
  token: Optional[str],
617
733
  sub_id: str,
734
+ origin: str = BASE_URL,
618
735
  ) -> Dict[str, str]:
619
- """Headers shared by the authenticated classroom endpoints."""
736
+ """Headers shared by the authenticated classroom endpoints.
737
+
738
+ ``origin`` is the API backend actually being queried. The cookie/token are
739
+ still only sent to ZJU hosts; callers must not pass an arbitrary origin.
740
+ """
741
+ if origin not in (BASE_URL, INTERACTIVE_BASE_URL):
742
+ raise ValueError("拒绝向非浙大官方主机发送课堂凭据")
743
+ referer = (
744
+ f"{origin}/livingroom?sub_id={sub_id}"
745
+ if origin == BASE_URL
746
+ else f"{origin}/"
747
+ )
620
748
  headers = {
621
749
  "User-Agent": USER_AGENT,
622
750
  "Cookie": cookie,
623
- "Referer": f"{BASE_URL}/livingroom?sub_id={sub_id}",
751
+ "Referer": referer,
624
752
  }
625
753
  if token:
626
754
  headers["Authorization"] = f"Bearer {token}"
@@ -638,6 +766,36 @@ def _first_not_none(*values: Any) -> Any:
638
766
  return None
639
767
 
640
768
 
769
+ _SLIDE_CAPTURE_RE = re.compile(r"/(\d{13})\.(?:jpe?g|png)(?:\?.*)?$", re.IGNORECASE)
770
+ _CAPTURE_MIN_MS = 946684800000 # 2000-01-01T00:00:00Z
771
+ _CAPTURE_MAX_MS = 4102444800000 # 2100-01-01T00:00:00Z
772
+
773
+
774
+ def _slide_capture_ms(image_url: str) -> Optional[int]:
775
+ """Read the capture time encoded in a classroom screenshot URL.
776
+
777
+ ``search-ppt`` returns image URLs whose basename is a 13-digit epoch
778
+ millisecond timestamp, e.g. ``.../1794441389000.jpg``. That timestamp is
779
+ the only page-time signal the API gives us, and it lines up with the
780
+ transcript duration almost exactly (within seconds for a 100-minute
781
+ lecture), so it is worth keeping instead of discarding.
782
+ """
783
+ raw = str(image_url or "").strip()
784
+ if not raw:
785
+ return None
786
+ try:
787
+ path = urllib.parse.urlparse(raw).path
788
+ except ValueError:
789
+ return None
790
+ match = _SLIDE_CAPTURE_RE.search(path)
791
+ if not match:
792
+ return None
793
+ value = int(match.group(1))
794
+ if not _CAPTURE_MIN_MS <= value <= _CAPTURE_MAX_MS:
795
+ return None
796
+ return value
797
+
798
+
641
799
  def normalize_slide(item: Any, index: int) -> Dict[str, Any]:
642
800
  """Flatten one ``search-ppt`` row into a stable slide record.
643
801
 
@@ -674,7 +832,7 @@ def normalize_slide(item: Any, index: int) -> Dict[str, Any]:
674
832
  return value
675
833
  return ""
676
834
 
677
- image_url = secure_zju_url(
835
+ image_url = secure_image_url(
678
836
  pick("pptimgurl", "ppt_img_url", "image_url", "imgurl")
679
837
  )
680
838
  text = text or pick("ocr_content", "ocr_text", "text", "ppttext", "ppt_text")
@@ -683,6 +841,9 @@ def normalize_slide(item: Any, index: int) -> Dict[str, Any]:
683
841
  "image_url": image_url,
684
842
  "text": text,
685
843
  }
844
+ capture_ms = _slide_capture_ms(image_url)
845
+ if capture_ms is not None:
846
+ slide["capture_ms"] = capture_ms
686
847
  time_point = _first_not_none(
687
848
  row.get("time"),
688
849
  row.get("time_point"),
@@ -697,6 +858,28 @@ def normalize_slide(item: Any, index: int) -> Dict[str, Any]:
697
858
  return slide
698
859
 
699
860
 
861
+ def _apply_slide_time_axis(slides: List[Dict[str, Any]]) -> None:
862
+ """Turn URL capture timestamps into transcript-relative seconds.
863
+
864
+ The first captured page is the zero point. This keeps the slide index
865
+ aligned with the ``[HH:MM]`` transcript timestamps without needing the
866
+ wall-clock lecture start. API-provided ``time`` values win; they are
867
+ left untouched.
868
+ """
869
+ captures = [
870
+ (slide, slide.get("capture_ms"))
871
+ for slide in slides
872
+ if isinstance(slide.get("capture_ms"), int)
873
+ ]
874
+ if not captures:
875
+ return
876
+ base = min(int(value) for _slide, value in captures)
877
+ for slide, value in captures:
878
+ if slide.get("time") is not None:
879
+ continue
880
+ slide["time"] = max(0, int(round((int(value) - base) / 1000.0)))
881
+
882
+
700
883
  def fetch_slides(
701
884
  sub_id: str,
702
885
  tenant_code: str = "112",
@@ -712,6 +895,12 @@ def fetch_slides(
712
895
  per page; it also sometimes ignores ``per_page`` and repeats the first
713
896
  page, so URLs are de-duplicated in order.
714
897
 
898
+ The main classroom backend is queried first; when it returns an empty deck
899
+ or a transport/business failure, the interactive-classroom backend
900
+ (``interactivemeta.cmc.zju.edu.cn/pptnoteapi``) is tried. Auth failures
901
+ (401/403) are not retried against the fallback: the same session is bad and
902
+ the user needs to log in again.
903
+
715
904
  Requires a login cookie that contains the classroom ``_token`` (found in
716
905
  the parent-domain ``.zju.edu.cn`` session cookie). ``diagnostics`` records
717
906
  one human-readable degradation reason on failure.
@@ -727,82 +916,101 @@ def fetch_slides(
727
916
  return None
728
917
 
729
918
  token = extract_classroom_token(cookie)
730
- headers = _classroom_headers(cookie, token, sub_id)
731
- endpoint = f"{BASE_URL}/pptnote/v1/schedule/search-ppt"
732
-
919
+ backends = (
920
+ (BASE_URL, "/pptnote"),
921
+ (INTERACTIVE_BASE_URL, "/pptnoteapi"),
922
+ )
923
+ max_pages = 50
733
924
  slides: List[Dict[str, Any]] = []
734
- seen: set = set()
735
925
  total = 0
736
- page = 1
737
- max_pages = 50
738
- while page <= max_pages:
739
- params = {
740
- "sub_id": sub_id,
741
- "tenant_code": tenant_code,
742
- "page": page,
743
- "per_page": 100,
744
- }
745
- if course_id:
746
- params["course_id"] = course_id
747
- url = f"{endpoint}?{urllib.parse.urlencode(params)}"
748
- try:
749
- data = json.loads(_fetch_bytes(url, headers, timeout).decode("utf-8"))
750
- except urllib.error.HTTPError as error:
751
- hint = ""
752
- if error.code in (401, 403):
753
- hint = ";登录态无效或 Cookie 缺少 _token,请重新登录智云课堂后重试"
754
- _record(diagnostics, f"PPT 接口返回 HTTP {error.code}{hint}")
755
- return slides or None
756
- except Exception as error: # noqa: BLE001 - degradation path, reason is recorded
757
- _record(diagnostics, "PPT 接口请求失败。" + describe_network_error(error))
758
- return slides or None
759
-
760
- if not isinstance(data, dict):
761
- _record(diagnostics, "PPT 接口返回了非对象 JSON,可能改版了")
762
- return slides or None
763
-
764
- code = data.get("code")
765
- if code != 0:
766
- message = data.get("msg") or f"未知错误 (code={code})"
767
- hint = (
768
- ""
769
- if token
770
- else ";Cookie 中未解析到 _token,请确认包含父域 .zju.edu.cn 的会话 Cookie"
771
- )
772
- _record(diagnostics, f"PPT 接口返回 code={code}: {message}{hint}")
773
- return slides or None
926
+ last_reason = ""
927
+ reached_limit = False
928
+
929
+ for origin, prefix in backends:
930
+ headers = _classroom_headers(cookie, token, sub_id, origin=origin)
931
+ endpoint = f"{origin}{prefix}/v1/schedule/search-ppt"
932
+ backend_slides: List[Dict[str, Any]] = []
933
+ seen: set = set()
934
+ backend_total = 0
935
+ page = 1
936
+
937
+ while page <= max_pages:
938
+ params = {
939
+ "sub_id": sub_id,
940
+ "tenant_code": tenant_code,
941
+ "page": page,
942
+ "per_page": 100,
943
+ }
944
+ if course_id:
945
+ params["course_id"] = course_id
946
+ url = f"{endpoint}?{urllib.parse.urlencode(params)}"
947
+ try:
948
+ data = json.loads(_fetch_bytes(url, headers, timeout).decode("utf-8"))
949
+ except urllib.error.HTTPError as error:
950
+ if error.code in (401, 403):
951
+ hint = ";登录态无效或 Cookie 缺少 _token,请重新登录智云课堂后重试"
952
+ _record(diagnostics, f"PPT 接口返回 HTTP {error.code}{hint}")
953
+ return None
954
+ last_reason = "PPT 接口请求失败。" + describe_network_error(error)
955
+ break
956
+ except Exception as error: # noqa: BLE001 - degradation path, reason is recorded
957
+ last_reason = "PPT 接口请求失败。" + describe_network_error(error)
958
+ break
774
959
 
775
- items = data.get("list") or []
776
- try:
777
- page_total = int(data.get("total") or 0)
778
- except (TypeError, ValueError):
779
- page_total = 0
780
- if page_total:
781
- total = page_total
782
-
783
- added = 0
784
- for item in items:
785
- slide = normalize_slide(item, len(slides) + 1)
786
- key = (
787
- slide.get("image_url")
788
- or slide.get("text")
789
- or json.dumps(item, sort_keys=True, ensure_ascii=False)
790
- )
791
- if key in seen:
792
- continue
793
- seen.add(key)
794
- slides.append(slide)
795
- added += 1
960
+ if not isinstance(data, dict):
961
+ last_reason = "PPT 接口返回了非对象 JSON,可能改版了"
962
+ break
796
963
 
797
- # The API may return the whole deck on page 1 and repeat it on page 2.
798
- if not items or added == 0:
799
- break
800
- if total and len(slides) >= total:
964
+ code = data.get("code")
965
+ if code != 0:
966
+ message = data.get("msg") or f"未知错误 (code={code})"
967
+ hint = (
968
+ ""
969
+ if token
970
+ else ";Cookie 中未解析到 _token,请确认包含父域 .zju.edu.cn 的会话 Cookie"
971
+ )
972
+ last_reason = f"PPT 接口返回 code={code}: {message}{hint}"
973
+ break
974
+
975
+ items = data.get("list") or []
976
+ try:
977
+ page_total = int(data.get("total") or 0)
978
+ except (TypeError, ValueError):
979
+ page_total = 0
980
+ if page_total:
981
+ backend_total = page_total
982
+
983
+ added = 0
984
+ for item in items:
985
+ slide = normalize_slide(item, len(backend_slides) + 1)
986
+ key = (
987
+ slide.get("image_url")
988
+ or slide.get("text")
989
+ or json.dumps(item, sort_keys=True, ensure_ascii=False)
990
+ )
991
+ if key in seen:
992
+ continue
993
+ seen.add(key)
994
+ backend_slides.append(slide)
995
+ added += 1
996
+
997
+ # The API may return the whole deck on page 1 and repeat it on page 2.
998
+ if not items or added == 0:
999
+ break
1000
+ if backend_total and len(backend_slides) >= backend_total:
1001
+ break
1002
+ page += 1
1003
+
1004
+ if backend_slides:
1005
+ slides = backend_slides
1006
+ total = backend_total
1007
+ reached_limit = page > max_pages and (not total or len(slides) < total)
801
1008
  break
802
- page += 1
803
1009
 
804
1010
  if not slides:
805
- if not course_id:
1011
+ if last_reason:
1012
+ _record(diagnostics, last_reason)
1013
+ elif not course_id:
806
1014
  _record(
807
1015
  diagnostics,
808
1016
  "PPT 列表为空;如果输入的是纯 sub_id,请补上 course_id"
@@ -817,8 +1025,9 @@ def fetch_slides(
817
1025
  diagnostics,
818
1026
  f"PPT 接口标记共 {total} 张,去重后取到 {len(slides)} 张(后续分页无新数据)",
819
1027
  )
820
- if page > max_pages and (not total or len(slides) < total):
1028
+ if reached_limit:
821
1029
  _record(diagnostics, f"PPT 分页达到上限 {max_pages} 页,已停止")
1030
+ _apply_slide_time_axis(slides)
822
1031
  return slides
823
1032
 
824
1033