dsh-zju-lecture-note 2.2.3 → 2.2.5
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.
- package/CHANGELOG.md +102 -1
- package/README.md +98 -150
- package/SECURITY.md +136 -44
- package/docs/technical.md +175 -45
- package/lib/client.js +14 -13
- package/lib/index.js +53 -19
- package/lib/tools.js +28 -3
- package/lib/tools.schema.json +28 -3
- package/mcp_server.py +285 -34
- package/package.json +6 -2
- package/skills/scholia-notes/SKILL.md +8 -1
- package/skills/scholia-notes/references/format-spec.md +57 -6
- package/skills/scholia-notes/references/prelude.typ +55 -0
- package/skills/scholia-notes/references/typography-spec.md +4 -4
- package/skills/scholia-notes.manifest.json +9 -9
- package/skills/zju-lecture-summarizer/SKILL.md +56 -11
- package/skills/zju-lecture-summarizer-help/SKILL.md +95 -0
- package/skills/zju-lecture-summarizer-help.manifest.json +14 -0
- package/skills/zju-lecture-summarizer-login/SKILL.md +40 -0
- package/skills/zju-lecture-summarizer-login.manifest.json +14 -0
- package/skills/zju-lecture-summarizer.manifest.json +4 -4
- package/zju_lecture/__init__.py +16 -0
- package/zju_lecture/browser_login.py +923 -0
- package/zju_lecture/cli.py +98 -3
- package/zju_lecture/client.py +808 -741
- package/zju_lecture/handout.py +390 -60
- package/zju_lecture/handout_prelude.typ +47 -2
- package/zju_lecture/note_lint.py +12 -0
- package/zju_lecture/prelude.typ +55 -0
- package/zju_lecture/study_notes.py +415 -4
- package/zju_lecture/typst-packages/VENDORED.md +1 -1
- package/zju_lecture/typst-packages/preview/noteworthy/0.4.0/LICENSE +20 -20
- package/zju_lecture/typst-packages/preview/noteworthy/0.4.0/lib.typ +128 -128
- package/zju_lecture/typst-packages/preview/noteworthy/0.4.0/typst.toml +15 -15
- package/zju_lecture/typst-packages/preview/scholia/0.1.0/src/lib.typ +2 -2
- package/zju_lecture/typst-packages/preview/showybox/2.0.4/LICENSE +21 -21
- package/zju_lecture/typst-packages/preview/showybox/2.0.4/lib/func.typ +142 -142
- package/zju_lecture/typst-packages/preview/showybox/2.0.4/lib/id.typ +11 -11
- package/zju_lecture/typst-packages/preview/showybox/2.0.4/lib/pre-rendering.typ +50 -50
- package/zju_lecture/typst-packages/preview/showybox/2.0.4/lib/sections.typ +141 -141
- package/zju_lecture/typst-packages/preview/showybox/2.0.4/lib/shadows.typ +118 -118
- package/zju_lecture/typst-packages/preview/showybox/2.0.4/showy.typ +267 -267
- package/zju_lecture/typst-packages/preview/showybox/2.0.4/typst.toml +11 -11
package/zju_lecture/client.py
CHANGED
|
@@ -1,741 +1,808 @@
|
|
|
1
|
-
# -*- coding: utf-8 -*-
|
|
2
|
-
"""
|
|
3
|
-
Client for Zhejiang University 智云课堂 (classroom.zju.edu.cn) APIs.
|
|
4
|
-
Pure Python standard library implementation with zero external dependencies.
|
|
5
|
-
"""
|
|
6
|
-
|
|
7
|
-
import http.client
|
|
8
|
-
import json
|
|
9
|
-
import os
|
|
10
|
-
import random
|
|
11
|
-
import re
|
|
12
|
-
import socket
|
|
13
|
-
import ssl
|
|
14
|
-
import time
|
|
15
|
-
import urllib.error
|
|
16
|
-
import urllib.parse
|
|
17
|
-
import urllib.request
|
|
18
|
-
from typing import Any, Dict, List, Optional
|
|
19
|
-
|
|
20
|
-
from .security import sanitize_cookie_header
|
|
21
|
-
|
|
22
|
-
BASE_URL = "https://classroom.zju.edu.cn"
|
|
23
|
-
BASE_HOST = (urllib.parse.urlparse(BASE_URL).hostname or "classroom.zju.edu.cn").lower()
|
|
24
|
-
USER_AGENT = (
|
|
25
|
-
"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
|
|
26
|
-
"AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"
|
|
27
|
-
)
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
_CA_SOURCE = "system"
|
|
31
|
-
_CA_PATH: Optional[str] = None
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
def _certifi_ca_path() -> Optional[str]:
|
|
35
|
-
"""Location of certifi's bundle, when certifi is installed and readable."""
|
|
36
|
-
try:
|
|
37
|
-
import certifi # type: ignore
|
|
38
|
-
|
|
39
|
-
path = certifi.where()
|
|
40
|
-
except Exception: # noqa: BLE001 - a broken certifi must not crash the tool
|
|
41
|
-
return None
|
|
42
|
-
return path if path and os.path.isfile(path) else None
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
def _bundled_ca_path() -> Optional[str]:
|
|
46
|
-
"""The CA bundle shipped inside this package (``zju_lecture/cacert.pem``).
|
|
47
|
-
|
|
48
|
-
dsh ships its own Python interpreter **without** certifi, and a plain
|
|
49
|
-
``ssl.create_default_context()`` on an incomplete OS root store raises
|
|
50
|
-
``CERTIFICATE_VERIFY_FAILED``. Carrying our own bundle means the common case
|
|
51
|
-
(dsh on a fresh machine) stops depending on what the user happened to pip
|
|
52
|
-
install.
|
|
53
|
-
"""
|
|
54
|
-
path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "cacert.pem")
|
|
55
|
-
return path if os.path.isfile(path) else None
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
def _context_from_cafile(path: str) -> Optional[ssl.SSLContext]:
|
|
59
|
-
"""Build a verifying context from ``path``; ``None`` when it is unusable."""
|
|
60
|
-
try:
|
|
61
|
-
return ssl.create_default_context(cafile=path)
|
|
62
|
-
except (OSError, ssl.SSLError):
|
|
63
|
-
return None
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
def create_ssl_context() -> ssl.SSLContext:
|
|
67
|
-
"""Create the TLS context used for every request.
|
|
68
|
-
|
|
69
|
-
Certificate verification is **never** disabled. The login cookie is sent
|
|
70
|
-
over this connection, so silently downgrading to an unverified context
|
|
71
|
-
(as an earlier version did when the local root store was incomplete) would
|
|
72
|
-
turn a missing CA bundle into a cookie-exfiltration path.
|
|
73
|
-
|
|
74
|
-
Trust store order: ``certifi``(跟得上 CA 轮换)→ 随包 ``cacert.pem``
|
|
75
|
-
(dsh 自带 Python 没有 certifi 时的兜底)→ 系统根证书。三档都失败才会
|
|
76
|
-
在握手上报错,且错误信息里会写清用的是哪一档。
|
|
77
|
-
"""
|
|
78
|
-
global _CA_SOURCE, _CA_PATH
|
|
79
|
-
|
|
80
|
-
for source, resolver in (("certifi", _certifi_ca_path), ("bundled", _bundled_ca_path)):
|
|
81
|
-
path = resolver()
|
|
82
|
-
if not path:
|
|
83
|
-
continue
|
|
84
|
-
context = _context_from_cafile(path)
|
|
85
|
-
if context is not None:
|
|
86
|
-
_CA_SOURCE, _CA_PATH = source, path
|
|
87
|
-
return context
|
|
88
|
-
_CA_SOURCE, _CA_PATH = "system", None
|
|
89
|
-
return ssl.create_default_context()
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
_SSL_CONTEXT: Optional[ssl.SSLContext] = None
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
def get_ssl_context() -> ssl.SSLContext:
|
|
96
|
-
"""Return the shared SSL context, building it on first use."""
|
|
97
|
-
global _SSL_CONTEXT
|
|
98
|
-
if _SSL_CONTEXT is None:
|
|
99
|
-
_SSL_CONTEXT = create_ssl_context()
|
|
100
|
-
return _SSL_CONTEXT
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
def ssl_context_health() -> Dict[str, Any]:
|
|
104
|
-
"""Report the trust store actually in use (for actionable error messages)."""
|
|
105
|
-
try:
|
|
106
|
-
ca_count = len(get_ssl_context().get_ca_certs())
|
|
107
|
-
except Exception: # noqa: BLE001 - diagnostics must never mask the real error
|
|
108
|
-
ca_count = -1
|
|
109
|
-
return {"source": _CA_SOURCE, "path": _CA_PATH, "ca_certs": ca_count}
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
def
|
|
113
|
-
"""
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
"""
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
"""
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
lines.append(
|
|
164
|
-
"1.
|
|
165
|
-
"
|
|
166
|
-
)
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
return
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
)
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
``
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
)
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
"""
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
"""
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
raise ZJUAPIError("
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
)
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
)
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
if
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
""
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
(
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
return
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
""
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
return
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
1
|
+
# -*- coding: utf-8 -*-
|
|
2
|
+
"""
|
|
3
|
+
Client for Zhejiang University 智云课堂 (classroom.zju.edu.cn) APIs.
|
|
4
|
+
Pure Python standard library implementation with zero external dependencies.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
import http.client
|
|
8
|
+
import json
|
|
9
|
+
import os
|
|
10
|
+
import random
|
|
11
|
+
import re
|
|
12
|
+
import socket
|
|
13
|
+
import ssl
|
|
14
|
+
import time
|
|
15
|
+
import urllib.error
|
|
16
|
+
import urllib.parse
|
|
17
|
+
import urllib.request
|
|
18
|
+
from typing import Any, Dict, List, Optional
|
|
19
|
+
|
|
20
|
+
from .security import REDACTOR, sanitize_cookie_header
|
|
21
|
+
|
|
22
|
+
BASE_URL = "https://classroom.zju.edu.cn"
|
|
23
|
+
BASE_HOST = (urllib.parse.urlparse(BASE_URL).hostname or "classroom.zju.edu.cn").lower()
|
|
24
|
+
USER_AGENT = (
|
|
25
|
+
"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
|
|
26
|
+
"AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
_CA_SOURCE = "system"
|
|
31
|
+
_CA_PATH: Optional[str] = None
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def _certifi_ca_path() -> Optional[str]:
|
|
35
|
+
"""Location of certifi's bundle, when certifi is installed and readable."""
|
|
36
|
+
try:
|
|
37
|
+
import certifi # type: ignore
|
|
38
|
+
|
|
39
|
+
path = certifi.where()
|
|
40
|
+
except Exception: # noqa: BLE001 - a broken certifi must not crash the tool
|
|
41
|
+
return None
|
|
42
|
+
return path if path and os.path.isfile(path) else None
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _bundled_ca_path() -> Optional[str]:
|
|
46
|
+
"""The CA bundle shipped inside this package (``zju_lecture/cacert.pem``).
|
|
47
|
+
|
|
48
|
+
dsh ships its own Python interpreter **without** certifi, and a plain
|
|
49
|
+
``ssl.create_default_context()`` on an incomplete OS root store raises
|
|
50
|
+
``CERTIFICATE_VERIFY_FAILED``. Carrying our own bundle means the common case
|
|
51
|
+
(dsh on a fresh machine) stops depending on what the user happened to pip
|
|
52
|
+
install.
|
|
53
|
+
"""
|
|
54
|
+
path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "cacert.pem")
|
|
55
|
+
return path if os.path.isfile(path) else None
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def _context_from_cafile(path: str) -> Optional[ssl.SSLContext]:
|
|
59
|
+
"""Build a verifying context from ``path``; ``None`` when it is unusable."""
|
|
60
|
+
try:
|
|
61
|
+
return ssl.create_default_context(cafile=path)
|
|
62
|
+
except (OSError, ssl.SSLError):
|
|
63
|
+
return None
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def create_ssl_context() -> ssl.SSLContext:
|
|
67
|
+
"""Create the TLS context used for every request.
|
|
68
|
+
|
|
69
|
+
Certificate verification is **never** disabled. The login cookie is sent
|
|
70
|
+
over this connection, so silently downgrading to an unverified context
|
|
71
|
+
(as an earlier version did when the local root store was incomplete) would
|
|
72
|
+
turn a missing CA bundle into a cookie-exfiltration path.
|
|
73
|
+
|
|
74
|
+
Trust store order: ``certifi``(跟得上 CA 轮换)→ 随包 ``cacert.pem``
|
|
75
|
+
(dsh 自带 Python 没有 certifi 时的兜底)→ 系统根证书。三档都失败才会
|
|
76
|
+
在握手上报错,且错误信息里会写清用的是哪一档。
|
|
77
|
+
"""
|
|
78
|
+
global _CA_SOURCE, _CA_PATH
|
|
79
|
+
|
|
80
|
+
for source, resolver in (("certifi", _certifi_ca_path), ("bundled", _bundled_ca_path)):
|
|
81
|
+
path = resolver()
|
|
82
|
+
if not path:
|
|
83
|
+
continue
|
|
84
|
+
context = _context_from_cafile(path)
|
|
85
|
+
if context is not None:
|
|
86
|
+
_CA_SOURCE, _CA_PATH = source, path
|
|
87
|
+
return context
|
|
88
|
+
_CA_SOURCE, _CA_PATH = "system", None
|
|
89
|
+
return ssl.create_default_context()
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
_SSL_CONTEXT: Optional[ssl.SSLContext] = None
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def get_ssl_context() -> ssl.SSLContext:
|
|
96
|
+
"""Return the shared SSL context, building it on first use."""
|
|
97
|
+
global _SSL_CONTEXT
|
|
98
|
+
if _SSL_CONTEXT is None:
|
|
99
|
+
_SSL_CONTEXT = create_ssl_context()
|
|
100
|
+
return _SSL_CONTEXT
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def ssl_context_health() -> Dict[str, Any]:
|
|
104
|
+
"""Report the trust store actually in use (for actionable error messages)."""
|
|
105
|
+
try:
|
|
106
|
+
ca_count = len(get_ssl_context().get_ca_certs())
|
|
107
|
+
except Exception: # noqa: BLE001 - diagnostics must never mask the real error
|
|
108
|
+
ca_count = -1
|
|
109
|
+
return {"source": _CA_SOURCE, "path": _CA_PATH, "ca_certs": ca_count}
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def _mask_proxy_credentials(value: str) -> str:
|
|
113
|
+
"""Hide ``user:password@`` in a proxy URL before it reaches an error message."""
|
|
114
|
+
return re.sub(r"(?i)([a-z][a-z0-9+.-]*://)[^/@\s]+@", r"\1[REDACTED]@", value)
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def _proxy_env() -> str:
|
|
118
|
+
"""Describe the proxy environment, naming the variables to inspect.
|
|
119
|
+
|
|
120
|
+
"未设置" on its own does not tell the user which variable to look at, so the
|
|
121
|
+
unset case spells the names out. Returns a phrase without brackets: the
|
|
122
|
+
callers already wrap it in (). Proxy userinfo is masked.
|
|
123
|
+
"""
|
|
124
|
+
found = []
|
|
125
|
+
for key in ("HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"):
|
|
126
|
+
value = os.environ.get(key)
|
|
127
|
+
if value:
|
|
128
|
+
found.append(f"{key}={_mask_proxy_credentials(value)}")
|
|
129
|
+
if found:
|
|
130
|
+
return ",".join(found)
|
|
131
|
+
return "HTTPS_PROXY / HTTP_PROXY 均未设置"
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def describe_network_error(error: BaseException) -> str:
|
|
135
|
+
"""Turn a transport exception into ``原因 + 下一步``.
|
|
136
|
+
|
|
137
|
+
The tool used to surface the raw ``<urlopen error ...>`` text, which made an
|
|
138
|
+
incomplete CA store look like "the plugin's request is broken". 证书校验失败、
|
|
139
|
+
代理拦截、超时、连接被拒这四类占了网络失败的大头,各自给出可执行的下一步。
|
|
140
|
+
"""
|
|
141
|
+
text = str(error)
|
|
142
|
+
# urllib 把真实原因包一层 URLError(URLError(reason=SSLCertVerificationError(...))),
|
|
143
|
+
# 不拆包的话「证书校验失败」这条分支永远命中不了。
|
|
144
|
+
inner = getattr(error, "reason", None)
|
|
145
|
+
if isinstance(error, urllib.error.URLError) and isinstance(inner, BaseException):
|
|
146
|
+
text = f"{error} {inner}"
|
|
147
|
+
error = inner
|
|
148
|
+
context = ssl_context_health()
|
|
149
|
+
store = {
|
|
150
|
+
"certifi": "certifi",
|
|
151
|
+
"bundled": "插件内置 cacert.pem",
|
|
152
|
+
"system": "系统根证书",
|
|
153
|
+
}.get(context["source"], "系统根证书")
|
|
154
|
+
if context["path"]:
|
|
155
|
+
store = f"{store} ({context['path']})"
|
|
156
|
+
|
|
157
|
+
if isinstance(error, ssl.SSLCertVerificationError) or "CERTIFICATE_VERIFY_FAILED" in text:
|
|
158
|
+
lines = [
|
|
159
|
+
"原因:TLS 证书校验不通过(接口本身没挂,不要用关闭校验的方式绕过——登录 Cookie 走这条连接)。",
|
|
160
|
+
f"信任库:{store},已加载 {context['ca_certs']} 张 CA 证书;代理环境:{_proxy_env()}。",
|
|
161
|
+
]
|
|
162
|
+
if context["ca_certs"] == 0:
|
|
163
|
+
lines.append(
|
|
164
|
+
"1. 已加载 0 张证书 → 连随包 CA 都没读到,安装包可能不完整:"
|
|
165
|
+
"重装插件;或 `pip install certifi` 后重试。"
|
|
166
|
+
)
|
|
167
|
+
else:
|
|
168
|
+
lines.append(
|
|
169
|
+
"1. 信任库里没有能验证该站点的根证书:`pip install --upgrade certifi`,"
|
|
170
|
+
"或重装插件取回最新内置 cacert.pem。"
|
|
171
|
+
)
|
|
172
|
+
lines += [
|
|
173
|
+
"2. 代理若做 HTTPS 解密(Clash / Surge / 企业网关),把 classroom.zju.edu.cn 设为直连,"
|
|
174
|
+
"或设置 `NO_PROXY=classroom.zju.edu.cn`。",
|
|
175
|
+
"3. 系统时间偏差过大会直接导致握手失败,核对一下系统时间。",
|
|
176
|
+
]
|
|
177
|
+
return "\n".join(lines)
|
|
178
|
+
|
|
179
|
+
if isinstance(error, (socket.timeout, TimeoutError)):
|
|
180
|
+
return f"原因:请求超时({_proxy_env()})。可稍后重试;若代理不可用,先关掉代理或设置 NO_PROXY。"
|
|
181
|
+
if isinstance(error, ConnectionRefusedError) or "Connection refused" in text or "10061" in text:
|
|
182
|
+
return f"原因:连接被拒绝,代理很可能没启动({_proxy_env()})。"
|
|
183
|
+
if isinstance(error, ssl.SSLEOFError) or "EOF occurred in violation of protocol" in text:
|
|
184
|
+
return f"原因:TLS 握手被中断({_proxy_env()}),通常是代理/网关拦截,建议重试或改直连。"
|
|
185
|
+
return f"原因:{text}(代理环境:{_proxy_env()})。"
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
_RETRY_ATTEMPTS = 3
|
|
189
|
+
_RETRY_BASE_DELAY = 0.5
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
def _is_transient(error: BaseException) -> bool:
|
|
193
|
+
"""Classify a transport failure as worth retrying."""
|
|
194
|
+
if isinstance(error, ssl.SSLCertVerificationError):
|
|
195
|
+
return False # 证书问题重试多少次都一样,立刻把诊断交出去
|
|
196
|
+
if isinstance(error, urllib.error.HTTPError):
|
|
197
|
+
return error.code >= 500 or error.code == 429
|
|
198
|
+
if isinstance(error, urllib.error.URLError):
|
|
199
|
+
return _is_transient(error.reason)
|
|
200
|
+
return isinstance(
|
|
201
|
+
error,
|
|
202
|
+
(socket.timeout, TimeoutError, ConnectionError, ssl.SSLError, http.client.HTTPException),
|
|
203
|
+
)
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
def _fetch_bytes(
|
|
207
|
+
url: str,
|
|
208
|
+
headers: Dict[str, str],
|
|
209
|
+
timeout: int,
|
|
210
|
+
attempts: int = _RETRY_ATTEMPTS,
|
|
211
|
+
max_bytes: Optional[int] = None,
|
|
212
|
+
allow_cross_host_redirect: bool = False,
|
|
213
|
+
) -> bytes:
|
|
214
|
+
"""GET ``url`` and read the **whole** body, retrying transient failures.
|
|
215
|
+
|
|
216
|
+
The retry has to cover ``read()``, not just the handshake. ``urllib`` builds the
|
|
217
|
+
TLS connection lazily on first use and the body arrives afterwards, so a flaky
|
|
218
|
+
proxy can走完 TCP 握手之后才在读取阶段丢包,表现为
|
|
219
|
+
``IncompleteRead(201704 bytes read)`` / ``EOF occurred in violation of protocol``。
|
|
220
|
+
只重试建连的话,这类失败仍然一次就穿透到用户面前。
|
|
221
|
+
|
|
222
|
+
Certification failures are *not* retried: they need a fix, not a rerun.
|
|
223
|
+
``max_bytes`` refuses oversized bodies (slide screenshots) before they are
|
|
224
|
+
materialised in memory.
|
|
225
|
+
"""
|
|
226
|
+
total = max(1, attempts)
|
|
227
|
+
last: Optional[BaseException] = None
|
|
228
|
+
for index in range(total):
|
|
229
|
+
try:
|
|
230
|
+
if allow_cross_host_redirect:
|
|
231
|
+
context = _open_request(
|
|
232
|
+
url, headers, timeout, allow_cross_host_redirect=True
|
|
233
|
+
)
|
|
234
|
+
else:
|
|
235
|
+
context = _open_request(url, headers, timeout)
|
|
236
|
+
with context as response:
|
|
237
|
+
if max_bytes is None:
|
|
238
|
+
return response.read()
|
|
239
|
+
data = response.read(max_bytes + 1)
|
|
240
|
+
if len(data) > max_bytes:
|
|
241
|
+
raise ZJUAPIError(
|
|
242
|
+
f"响应超过 {max_bytes // (1024 * 1024)} MiB 上限,已停止读取"
|
|
243
|
+
)
|
|
244
|
+
return data
|
|
245
|
+
except Exception as error: # noqa: BLE001 - re-raised below unless transient
|
|
246
|
+
if not _is_transient(error):
|
|
247
|
+
raise
|
|
248
|
+
last = error
|
|
249
|
+
if index + 1 < total:
|
|
250
|
+
time.sleep(_RETRY_BASE_DELAY * (2**index) + random.uniform(0, 0.25))
|
|
251
|
+
assert last is not None
|
|
252
|
+
raise last
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
class _SameHostRedirectHandler(urllib.request.HTTPRedirectHandler):
|
|
256
|
+
"""Follow redirects only on the classroom host.
|
|
257
|
+
|
|
258
|
+
``urllib`` re-sends request headers on a redirect, so a compromised or
|
|
259
|
+
misconfigured endpoint that answers ``302`` to another origin would leak
|
|
260
|
+
the ``Cookie`` header. Cross-origin redirects are refused instead.
|
|
261
|
+
"""
|
|
262
|
+
|
|
263
|
+
def redirect_request(self, req, fp, code, msg, headers, newurl): # noqa: D401
|
|
264
|
+
parsed = urllib.parse.urlparse(newurl)
|
|
265
|
+
target = (parsed.hostname or "").lower()
|
|
266
|
+
if target != BASE_HOST or parsed.scheme != "https":
|
|
267
|
+
raise urllib.error.HTTPError(
|
|
268
|
+
req.full_url,
|
|
269
|
+
code,
|
|
270
|
+
f"拒绝跨域或非 HTTPS 重定向到 {target or '(未知主机)'}(保护登录凭据)",
|
|
271
|
+
headers,
|
|
272
|
+
fp,
|
|
273
|
+
)
|
|
274
|
+
return super().redirect_request(req, fp, code, msg, headers, newurl)
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
class _StripAuthOnCrossHostRedirectHandler(urllib.request.HTTPRedirectHandler):
|
|
278
|
+
"""Allow slide-CDN redirects, but never carry credentials across origins.
|
|
279
|
+
|
|
280
|
+
Slide screenshots are static files and may redirect to a media host. The
|
|
281
|
+
classroom API keeps the stricter same-host rule; this handler is only used
|
|
282
|
+
for image downloads, and it drops ``Cookie`` / ``Authorization`` whenever
|
|
283
|
+
the redirect changes the host.
|
|
284
|
+
"""
|
|
285
|
+
|
|
286
|
+
def redirect_request(self, req, fp, code, msg, headers, newurl): # noqa: D401
|
|
287
|
+
new_request = super().redirect_request(req, fp, code, msg, headers, newurl)
|
|
288
|
+
if new_request is None:
|
|
289
|
+
return None
|
|
290
|
+
old_host = (urllib.parse.urlparse(req.full_url).hostname or "").lower()
|
|
291
|
+
new_host = (urllib.parse.urlparse(newurl).hostname or "").lower()
|
|
292
|
+
if old_host != new_host:
|
|
293
|
+
new_request.remove_header("Cookie")
|
|
294
|
+
new_request.remove_header("Authorization")
|
|
295
|
+
return new_request
|
|
296
|
+
|
|
297
|
+
|
|
298
|
+
def _open_request(
|
|
299
|
+
url: str,
|
|
300
|
+
headers: Dict[str, str],
|
|
301
|
+
timeout: int,
|
|
302
|
+
allow_cross_host_redirect: bool = False,
|
|
303
|
+
):
|
|
304
|
+
"""Open ``url`` with certificate verification and a redirect policy."""
|
|
305
|
+
redirect_handler = (
|
|
306
|
+
_StripAuthOnCrossHostRedirectHandler()
|
|
307
|
+
if allow_cross_host_redirect
|
|
308
|
+
else _SameHostRedirectHandler()
|
|
309
|
+
)
|
|
310
|
+
opener = urllib.request.build_opener(
|
|
311
|
+
urllib.request.HTTPSHandler(context=get_ssl_context()),
|
|
312
|
+
redirect_handler,
|
|
313
|
+
)
|
|
314
|
+
request = urllib.request.Request(url, headers=headers)
|
|
315
|
+
return opener.open(request, timeout=timeout)
|
|
316
|
+
|
|
317
|
+
|
|
318
|
+
class ZJUAPIError(Exception):
|
|
319
|
+
"""Raised when an API call to ZJU Classroom fails."""
|
|
320
|
+
pass
|
|
321
|
+
|
|
322
|
+
|
|
323
|
+
class TranscriptAuthError(ZJUAPIError):
|
|
324
|
+
def __init__(self, status: int):
|
|
325
|
+
self.status = status
|
|
326
|
+
super().__init__(f"字幕接口返回 HTTP {status},当前请求未获访问许可。")
|
|
327
|
+
|
|
328
|
+
|
|
329
|
+
def parse_lecture_url(url_or_sub_id: str) -> Dict[str, str]:
|
|
330
|
+
"""Extract course_id, sub_id, and tenant_code from a classroom URL or sub_id.
|
|
331
|
+
|
|
332
|
+
Accepts:
|
|
333
|
+
- Full livingroom URL: https://classroom.zju.edu.cn/livingroom?course_id=123&sub_id=456&tenant_code=112
|
|
334
|
+
- Short query string: ?sub_id=456
|
|
335
|
+
- Pure sub_id integer string: "456"
|
|
336
|
+
"""
|
|
337
|
+
url_or_sub_id = url_or_sub_id.strip()
|
|
338
|
+
if not url_or_sub_id:
|
|
339
|
+
raise ZJUAPIError("URL 或 sub_id 不能为空")
|
|
340
|
+
|
|
341
|
+
# If it's a numeric string, treat directly as sub_id
|
|
342
|
+
if url_or_sub_id.isdigit():
|
|
343
|
+
return {
|
|
344
|
+
"course_id": "",
|
|
345
|
+
"sub_id": url_or_sub_id,
|
|
346
|
+
"tenant_code": "112",
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
try:
|
|
350
|
+
parsed = urllib.parse.urlparse(url_or_sub_id)
|
|
351
|
+
query = urllib.parse.parse_qs(parsed.query)
|
|
352
|
+
except Exception as e:
|
|
353
|
+
raise ZJUAPIError(f"URL 格式解析失败: {e}")
|
|
354
|
+
|
|
355
|
+
sub_id = query.get("sub_id", [None])[0]
|
|
356
|
+
if not sub_id:
|
|
357
|
+
# Check path segments just in case
|
|
358
|
+
parts = [p for p in parsed.path.split("/") if p]
|
|
359
|
+
for idx, part in enumerate(parts):
|
|
360
|
+
if part in ("sub_id", "record", "livingroom") and idx + 1 < len(parts) and parts[idx + 1].isdigit():
|
|
361
|
+
sub_id = parts[idx + 1]
|
|
362
|
+
break
|
|
363
|
+
|
|
364
|
+
if not sub_id:
|
|
365
|
+
raise ZJUAPIError("无法从 URL 中识别 sub_id 参数,请确认输入包含有效 sub_id")
|
|
366
|
+
|
|
367
|
+
return {
|
|
368
|
+
"course_id": query.get("course_id", [""])[0],
|
|
369
|
+
"sub_id": str(sub_id),
|
|
370
|
+
"tenant_code": query.get("tenant_code", ["112"])[0],
|
|
371
|
+
}
|
|
372
|
+
|
|
373
|
+
|
|
374
|
+
_CLOCK_RE = re.compile(r"(\d{1,2}):(\d{2})(?::(\d{2}))?")
|
|
375
|
+
|
|
376
|
+
|
|
377
|
+
def _clock_seconds(value: Any) -> Optional[int]:
|
|
378
|
+
"""Parse ``HH:MM[:SS]`` (or a full datetime) into seconds of day."""
|
|
379
|
+
if value is None:
|
|
380
|
+
return None
|
|
381
|
+
text = str(value).strip()
|
|
382
|
+
if not text:
|
|
383
|
+
return None
|
|
384
|
+
if text.isdigit():
|
|
385
|
+
return int(text)
|
|
386
|
+
match = _CLOCK_RE.search(text)
|
|
387
|
+
if not match:
|
|
388
|
+
return None
|
|
389
|
+
hour, minute, second = match.group(1), match.group(2), match.group(3) or "0"
|
|
390
|
+
return int(hour) * 3600 + int(minute) * 60 + int(second)
|
|
391
|
+
|
|
392
|
+
|
|
393
|
+
def _transcript_text(item: Dict[str, Any]) -> str:
|
|
394
|
+
for key in ("Text", "zhtext", "TransText", "entext"):
|
|
395
|
+
value = item.get(key)
|
|
396
|
+
if isinstance(value, str) and value.strip():
|
|
397
|
+
return value.strip()
|
|
398
|
+
return ""
|
|
399
|
+
|
|
400
|
+
|
|
401
|
+
def fetch_transcript(
|
|
402
|
+
sub_id: str,
|
|
403
|
+
tenant_code: str = "112",
|
|
404
|
+
timeout: int = 60,
|
|
405
|
+
*,
|
|
406
|
+
cookie: Optional[str] = None,
|
|
407
|
+
) -> List[Dict[str, Any]]:
|
|
408
|
+
"""Fetch transcript segments, optionally authenticating with a locally supplied session."""
|
|
409
|
+
query = urllib.parse.urlencode({"sub_id": sub_id, "tenant_code": tenant_code, "format": "json"})
|
|
410
|
+
url = f"{BASE_URL}/courseapi/v3/web-socket/search-trans-result?{query}"
|
|
411
|
+
req_headers = {"User-Agent": USER_AGENT}
|
|
412
|
+
if cookie is not None:
|
|
413
|
+
cookie = sanitize_cookie_header(cookie)
|
|
414
|
+
REDACTOR.add_cookie(cookie)
|
|
415
|
+
token = extract_classroom_token(cookie)
|
|
416
|
+
if not token:
|
|
417
|
+
raise ZJUAPIError(
|
|
418
|
+
"本地登录态缺少可用的 _token,无法进行字幕鉴权;请重新登录智云课堂并更新本机登录态。"
|
|
419
|
+
)
|
|
420
|
+
REDACTOR.add(token)
|
|
421
|
+
req_headers["Authorization"] = f"Bearer {token}"
|
|
422
|
+
try:
|
|
423
|
+
data = json.loads(_fetch_bytes(url, req_headers, timeout).decode("utf-8"))
|
|
424
|
+
except urllib.error.HTTPError as e:
|
|
425
|
+
e.close()
|
|
426
|
+
if e.code in (401, 403):
|
|
427
|
+
raise TranscriptAuthError(e.code) from e
|
|
428
|
+
raise ZJUAPIError(f"字幕接口返回 HTTP {e.code}。") from e
|
|
429
|
+
except Exception as e:
|
|
430
|
+
raise ZJUAPIError(
|
|
431
|
+
"请求字幕接口失败。\n" + REDACTOR.redact(describe_network_error(e))
|
|
432
|
+
) from e
|
|
433
|
+
|
|
434
|
+
code = data.get("code")
|
|
435
|
+
if code != 0:
|
|
436
|
+
msg = REDACTOR.redact(data.get("msg") or f"未知错误 (code={code})")
|
|
437
|
+
raise ZJUAPIError(f"字幕接口返回非零状态码: {msg}")
|
|
438
|
+
|
|
439
|
+
items = data.get("list") or []
|
|
440
|
+
if not items:
|
|
441
|
+
raise ZJUAPIError("字幕数据列表为空,可能课程刚结束尚未生成字幕或该课程未开启录制转写")
|
|
442
|
+
|
|
443
|
+
raw_segments = items[0].get("all_content") or []
|
|
444
|
+
# 老课程(trans_type="ai")只有 time/zhtext/entext,没有 BeginSec;
|
|
445
|
+
# 用第一条时间戳作为相对零点,至少保证顺序与间隔正确。
|
|
446
|
+
uses_clock = not any(item.get("BeginSec") not in (None, "") for item in raw_segments)
|
|
447
|
+
clock_base: Optional[int] = None
|
|
448
|
+
if uses_clock:
|
|
449
|
+
clock_base = next(
|
|
450
|
+
(clock for clock in (_clock_seconds(item.get("time")) for item in raw_segments) if clock is not None),
|
|
451
|
+
None,
|
|
452
|
+
)
|
|
453
|
+
|
|
454
|
+
segments: List[Dict[str, Any]] = []
|
|
455
|
+
for item in raw_segments:
|
|
456
|
+
text = _transcript_text(item)
|
|
457
|
+
if not text:
|
|
458
|
+
continue
|
|
459
|
+
if uses_clock:
|
|
460
|
+
clock = _clock_seconds(item.get("time"))
|
|
461
|
+
if clock is None or clock_base is None:
|
|
462
|
+
continue
|
|
463
|
+
sec = max(0, clock - clock_base)
|
|
464
|
+
else:
|
|
465
|
+
try:
|
|
466
|
+
sec = int(item.get("BeginSec"))
|
|
467
|
+
except (TypeError, ValueError):
|
|
468
|
+
continue
|
|
469
|
+
segments.append({"begin_sec": sec, "text": text})
|
|
470
|
+
|
|
471
|
+
segments.sort(key=lambda x: x["begin_sec"])
|
|
472
|
+
if not segments:
|
|
473
|
+
raise ZJUAPIError("字幕内容经清洗后为空")
|
|
474
|
+
|
|
475
|
+
return segments
|
|
476
|
+
|
|
477
|
+
|
|
478
|
+
def _record(diagnostics: Optional[List[str]], message: str) -> None:
|
|
479
|
+
"""Collect a degradation reason for the caller to surface (never raises)."""
|
|
480
|
+
if diagnostics is not None:
|
|
481
|
+
diagnostics.append(message)
|
|
482
|
+
|
|
483
|
+
|
|
484
|
+
_CLASSROOM_TOKEN_RE = re.compile(
|
|
485
|
+
r'\{i:\d+;s:\d+:"_token";i:\d+;s:\d+:"([^"]+)";\}'
|
|
486
|
+
)
|
|
487
|
+
|
|
488
|
+
|
|
489
|
+
def is_zju_host(host: Optional[str]) -> bool:
|
|
490
|
+
"""True for ``zju.edu.cn`` and its subdomains (never lookalikes)."""
|
|
491
|
+
value = (host or "").strip().lower().strip(".")
|
|
492
|
+
return value == "zju.edu.cn" or value.endswith(".zju.edu.cn")
|
|
493
|
+
|
|
494
|
+
|
|
495
|
+
def secure_zju_url(url: str) -> str:
|
|
496
|
+
"""Upgrade ZJU ``http://`` URLs to HTTPS; leave other URLs untouched.
|
|
497
|
+
|
|
498
|
+
The classroom SSO cookie has no ``Secure`` flag, so downloading a
|
|
499
|
+
screenshot over plain HTTP would send the login credential unencrypted.
|
|
500
|
+
"""
|
|
501
|
+
value = (url or "").strip()
|
|
502
|
+
if value.startswith("//"):
|
|
503
|
+
value = "https:" + value
|
|
504
|
+
parsed = urllib.parse.urlparse(value)
|
|
505
|
+
if parsed.scheme.lower() == "http" and is_zju_host(parsed.hostname):
|
|
506
|
+
return "https" + value[4:]
|
|
507
|
+
return value
|
|
508
|
+
|
|
509
|
+
|
|
510
|
+
def extract_classroom_token(cookie_header: str) -> Optional[str]:
|
|
511
|
+
"""Extract the classroom Bearer token from a Cookie header.
|
|
512
|
+
|
|
513
|
+
The token is not a cookie of its own: the classroom session cookie stores
|
|
514
|
+
a percent-encoded PHP-serialized payload and ``_token`` is a field inside
|
|
515
|
+
it. Plain ``_token=...`` is accepted as a fallback for hand-written
|
|
516
|
+
cookie files. Returns ``None`` when no usable token is present.
|
|
517
|
+
"""
|
|
518
|
+
if not cookie_header:
|
|
519
|
+
return None
|
|
520
|
+
decoded = urllib.parse.unquote(cookie_header)
|
|
521
|
+
match = _CLASSROOM_TOKEN_RE.search(decoded)
|
|
522
|
+
token = match.group(1) if match else ""
|
|
523
|
+
if not token:
|
|
524
|
+
for part in decoded.split(";"):
|
|
525
|
+
name, separator, value = part.partition("=")
|
|
526
|
+
if separator and name.strip() == "_token":
|
|
527
|
+
token = value.strip()
|
|
528
|
+
break
|
|
529
|
+
token = token.strip()
|
|
530
|
+
if not token or len(token) > 4096:
|
|
531
|
+
return None
|
|
532
|
+
if any(ord(char) < 0x21 or ord(char) > 0x7E for char in token):
|
|
533
|
+
return None
|
|
534
|
+
return token
|
|
535
|
+
|
|
536
|
+
|
|
537
|
+
def _classroom_headers(
|
|
538
|
+
cookie: str,
|
|
539
|
+
token: Optional[str],
|
|
540
|
+
sub_id: str,
|
|
541
|
+
) -> Dict[str, str]:
|
|
542
|
+
"""Headers shared by the authenticated classroom endpoints."""
|
|
543
|
+
headers = {
|
|
544
|
+
"User-Agent": USER_AGENT,
|
|
545
|
+
"Cookie": cookie,
|
|
546
|
+
"Referer": f"{BASE_URL}/livingroom?sub_id={sub_id}",
|
|
547
|
+
}
|
|
548
|
+
if token:
|
|
549
|
+
headers["Authorization"] = f"Bearer {token}"
|
|
550
|
+
return headers
|
|
551
|
+
|
|
552
|
+
|
|
553
|
+
def _clean_text(value: Any) -> str:
|
|
554
|
+
return value.strip() if isinstance(value, str) else ""
|
|
555
|
+
|
|
556
|
+
|
|
557
|
+
def _first_not_none(*values: Any) -> Any:
|
|
558
|
+
for value in values:
|
|
559
|
+
if value is not None:
|
|
560
|
+
return value
|
|
561
|
+
return None
|
|
562
|
+
|
|
563
|
+
|
|
564
|
+
def normalize_slide(item: Any, index: int) -> Dict[str, Any]:
|
|
565
|
+
"""Flatten one ``search-ppt`` row into a stable slide record.
|
|
566
|
+
|
|
567
|
+
``content`` is a JSON *string* in the real response
|
|
568
|
+
(``{"pptimgurl": "http://..."}``), not note text. The old formatter
|
|
569
|
+
rendered that string verbatim, so the model saw JSON instead of slides.
|
|
570
|
+
"""
|
|
571
|
+
row = item if isinstance(item, dict) else {}
|
|
572
|
+
content_raw = row.get("content")
|
|
573
|
+
parsed: Dict[str, Any] = {}
|
|
574
|
+
text = ""
|
|
575
|
+
|
|
576
|
+
if isinstance(content_raw, dict):
|
|
577
|
+
parsed = content_raw
|
|
578
|
+
elif isinstance(content_raw, str):
|
|
579
|
+
stripped = content_raw.strip()
|
|
580
|
+
if stripped.startswith("{"):
|
|
581
|
+
try:
|
|
582
|
+
decoded = json.loads(stripped)
|
|
583
|
+
except ValueError:
|
|
584
|
+
decoded = None
|
|
585
|
+
if isinstance(decoded, dict):
|
|
586
|
+
parsed = decoded
|
|
587
|
+
else:
|
|
588
|
+
text = stripped
|
|
589
|
+
else:
|
|
590
|
+
text = stripped
|
|
591
|
+
|
|
592
|
+
def pick(*keys: str) -> str:
|
|
593
|
+
for source in (parsed, row):
|
|
594
|
+
for key in keys:
|
|
595
|
+
value = _clean_text(source.get(key))
|
|
596
|
+
if value:
|
|
597
|
+
return value
|
|
598
|
+
return ""
|
|
599
|
+
|
|
600
|
+
image_url = secure_zju_url(
|
|
601
|
+
pick("pptimgurl", "ppt_img_url", "image_url", "imgurl")
|
|
602
|
+
)
|
|
603
|
+
text = text or pick("ocr_content", "ocr_text", "text", "ppttext", "ppt_text")
|
|
604
|
+
slide: Dict[str, Any] = {
|
|
605
|
+
"page": index,
|
|
606
|
+
"image_url": image_url,
|
|
607
|
+
"text": text,
|
|
608
|
+
}
|
|
609
|
+
time_point = _first_not_none(
|
|
610
|
+
row.get("time"),
|
|
611
|
+
row.get("time_point"),
|
|
612
|
+
row.get("sec"),
|
|
613
|
+
parsed.get("time"),
|
|
614
|
+
parsed.get("time_point"),
|
|
615
|
+
)
|
|
616
|
+
if time_point is not None:
|
|
617
|
+
slide["time"] = time_point
|
|
618
|
+
if not image_url and not text:
|
|
619
|
+
slide["raw"] = json.dumps(item, ensure_ascii=False)[:500]
|
|
620
|
+
return slide
|
|
621
|
+
|
|
622
|
+
|
|
623
|
+
def fetch_slides(
|
|
624
|
+
sub_id: str,
|
|
625
|
+
tenant_code: str = "112",
|
|
626
|
+
cookie: Optional[str] = None,
|
|
627
|
+
timeout: int = 30,
|
|
628
|
+
diagnostics: Optional[List[str]] = None,
|
|
629
|
+
course_id: str = "",
|
|
630
|
+
) -> Optional[List[Dict[str, Any]]]:
|
|
631
|
+
"""Fetch projected-slide screenshots from the classroom API.
|
|
632
|
+
|
|
633
|
+
The endpoint returns **screenshots** (``content.pptimgurl``), not a text
|
|
634
|
+
layer. Pagination is required because the API returns at most ~100 rows
|
|
635
|
+
per page; it also sometimes ignores ``per_page`` and repeats the first
|
|
636
|
+
page, so URLs are de-duplicated in order.
|
|
637
|
+
|
|
638
|
+
Requires a login cookie that contains the classroom ``_token`` (found in
|
|
639
|
+
the parent-domain ``.zju.edu.cn`` session cookie). ``diagnostics`` records
|
|
640
|
+
one human-readable degradation reason on failure.
|
|
641
|
+
"""
|
|
642
|
+
if not cookie:
|
|
643
|
+
_record(diagnostics, "未提供登录 Cookie")
|
|
644
|
+
return None
|
|
645
|
+
|
|
646
|
+
try:
|
|
647
|
+
cookie = sanitize_cookie_header(cookie)
|
|
648
|
+
except ValueError as error:
|
|
649
|
+
_record(diagnostics, f"Cookie 头未通过校验:{error}")
|
|
650
|
+
return None
|
|
651
|
+
|
|
652
|
+
token = extract_classroom_token(cookie)
|
|
653
|
+
headers = _classroom_headers(cookie, token, sub_id)
|
|
654
|
+
endpoint = f"{BASE_URL}/pptnote/v1/schedule/search-ppt"
|
|
655
|
+
|
|
656
|
+
slides: List[Dict[str, Any]] = []
|
|
657
|
+
seen: set = set()
|
|
658
|
+
total = 0
|
|
659
|
+
page = 1
|
|
660
|
+
max_pages = 50
|
|
661
|
+
while page <= max_pages:
|
|
662
|
+
params = {
|
|
663
|
+
"sub_id": sub_id,
|
|
664
|
+
"tenant_code": tenant_code,
|
|
665
|
+
"page": page,
|
|
666
|
+
"per_page": 100,
|
|
667
|
+
}
|
|
668
|
+
if course_id:
|
|
669
|
+
params["course_id"] = course_id
|
|
670
|
+
url = f"{endpoint}?{urllib.parse.urlencode(params)}"
|
|
671
|
+
try:
|
|
672
|
+
data = json.loads(_fetch_bytes(url, headers, timeout).decode("utf-8"))
|
|
673
|
+
except urllib.error.HTTPError as error:
|
|
674
|
+
hint = ""
|
|
675
|
+
if error.code in (401, 403):
|
|
676
|
+
hint = ";登录态无效或 Cookie 缺少 _token,请重新登录智云课堂后重试"
|
|
677
|
+
_record(diagnostics, f"PPT 接口返回 HTTP {error.code}{hint}")
|
|
678
|
+
return slides or None
|
|
679
|
+
except Exception as error: # noqa: BLE001 - degradation path, reason is recorded
|
|
680
|
+
_record(diagnostics, "PPT 接口请求失败。" + describe_network_error(error))
|
|
681
|
+
return slides or None
|
|
682
|
+
|
|
683
|
+
if not isinstance(data, dict):
|
|
684
|
+
_record(diagnostics, "PPT 接口返回了非对象 JSON,可能改版了")
|
|
685
|
+
return slides or None
|
|
686
|
+
|
|
687
|
+
code = data.get("code")
|
|
688
|
+
if code != 0:
|
|
689
|
+
message = data.get("msg") or f"未知错误 (code={code})"
|
|
690
|
+
hint = (
|
|
691
|
+
""
|
|
692
|
+
if token
|
|
693
|
+
else ";Cookie 中未解析到 _token,请确认包含父域 .zju.edu.cn 的会话 Cookie"
|
|
694
|
+
)
|
|
695
|
+
_record(diagnostics, f"PPT 接口返回 code={code}: {message}{hint}")
|
|
696
|
+
return slides or None
|
|
697
|
+
|
|
698
|
+
items = data.get("list") or []
|
|
699
|
+
try:
|
|
700
|
+
page_total = int(data.get("total") or 0)
|
|
701
|
+
except (TypeError, ValueError):
|
|
702
|
+
page_total = 0
|
|
703
|
+
if page_total:
|
|
704
|
+
total = page_total
|
|
705
|
+
|
|
706
|
+
added = 0
|
|
707
|
+
for item in items:
|
|
708
|
+
slide = normalize_slide(item, len(slides) + 1)
|
|
709
|
+
key = (
|
|
710
|
+
slide.get("image_url")
|
|
711
|
+
or slide.get("text")
|
|
712
|
+
or json.dumps(item, sort_keys=True, ensure_ascii=False)
|
|
713
|
+
)
|
|
714
|
+
if key in seen:
|
|
715
|
+
continue
|
|
716
|
+
seen.add(key)
|
|
717
|
+
slides.append(slide)
|
|
718
|
+
added += 1
|
|
719
|
+
|
|
720
|
+
# The API may return the whole deck on page 1 and repeat it on page 2.
|
|
721
|
+
if not items or added == 0:
|
|
722
|
+
break
|
|
723
|
+
if total and len(slides) >= total:
|
|
724
|
+
break
|
|
725
|
+
page += 1
|
|
726
|
+
|
|
727
|
+
if not slides:
|
|
728
|
+
if not course_id:
|
|
729
|
+
_record(
|
|
730
|
+
diagnostics,
|
|
731
|
+
"PPT 列表为空;如果输入的是纯 sub_id,请补上 course_id"
|
|
732
|
+
"(完整回放 URL 通常带有 course_id=...)后重试",
|
|
733
|
+
)
|
|
734
|
+
else:
|
|
735
|
+
_record(diagnostics, "PPT 列表为空:老师可能没有使用智云投屏,或截图尚未生成")
|
|
736
|
+
return None
|
|
737
|
+
|
|
738
|
+
if total and len(slides) < total:
|
|
739
|
+
_record(
|
|
740
|
+
diagnostics,
|
|
741
|
+
f"PPT 接口标记共 {total} 张,去重后取到 {len(slides)} 张(后续分页无新数据)",
|
|
742
|
+
)
|
|
743
|
+
if page > max_pages and (not total or len(slides) < total):
|
|
744
|
+
_record(diagnostics, f"PPT 分页达到上限 {max_pages} 页,已停止")
|
|
745
|
+
return slides
|
|
746
|
+
|
|
747
|
+
|
|
748
|
+
def _find_mp4_in_json(obj: Any) -> Optional[str]:
|
|
749
|
+
"""Recursively search for first mp4 URL inside nested JSON response."""
|
|
750
|
+
if isinstance(obj, str):
|
|
751
|
+
if obj.startswith("http") and ".mp4" in obj.split("?")[0]:
|
|
752
|
+
return obj
|
|
753
|
+
return None
|
|
754
|
+
if isinstance(obj, dict):
|
|
755
|
+
for v in obj.values():
|
|
756
|
+
found = _find_mp4_in_json(v)
|
|
757
|
+
if found:
|
|
758
|
+
return found
|
|
759
|
+
elif isinstance(obj, list):
|
|
760
|
+
for item in obj:
|
|
761
|
+
found = _find_mp4_in_json(item)
|
|
762
|
+
if found:
|
|
763
|
+
return found
|
|
764
|
+
return None
|
|
765
|
+
|
|
766
|
+
|
|
767
|
+
def fetch_video_url(
|
|
768
|
+
course_id: str,
|
|
769
|
+
sub_id: str,
|
|
770
|
+
tenant_code: str = "112",
|
|
771
|
+
cookie: Optional[str] = None,
|
|
772
|
+
timeout: int = 30,
|
|
773
|
+
diagnostics: Optional[List[str]] = None,
|
|
774
|
+
) -> Optional[str]:
|
|
775
|
+
"""Fetch direct MP4 replay video URL from play template config.
|
|
776
|
+
|
|
777
|
+
Requires user authentication cookie. Returns ``None`` on any failure, but
|
|
778
|
+
appends the reason to ``diagnostics`` so the caller can tell "没登录" apart
|
|
779
|
+
from "网络坏了".
|
|
780
|
+
"""
|
|
781
|
+
if not cookie:
|
|
782
|
+
_record(diagnostics, "未提供登录 Cookie")
|
|
783
|
+
return None
|
|
784
|
+
|
|
785
|
+
try:
|
|
786
|
+
cookie = sanitize_cookie_header(cookie)
|
|
787
|
+
except ValueError as error:
|
|
788
|
+
_record(diagnostics, f"Cookie 头未通过校验:{error}")
|
|
789
|
+
return None
|
|
790
|
+
|
|
791
|
+
url = (
|
|
792
|
+
f"{BASE_URL}/courseapi/v2/play-template/get-config"
|
|
793
|
+
f"?course_id={course_id}&sub_id={sub_id}&tenant_code={tenant_code}"
|
|
794
|
+
)
|
|
795
|
+
headers = _classroom_headers(
|
|
796
|
+
cookie,
|
|
797
|
+
extract_classroom_token(cookie),
|
|
798
|
+
sub_id,
|
|
799
|
+
)
|
|
800
|
+
try:
|
|
801
|
+
data = json.loads(_fetch_bytes(url, headers, timeout).decode("utf-8"))
|
|
802
|
+
found = _find_mp4_in_json(data)
|
|
803
|
+
if not found:
|
|
804
|
+
_record(diagnostics, "play-template 响应里没有找到 mp4 直链")
|
|
805
|
+
return found
|
|
806
|
+
except Exception as error: # noqa: BLE001 - degradation path, reason is recorded
|
|
807
|
+
_record(diagnostics, "视频直链接口请求失败。" + describe_network_error(error))
|
|
808
|
+
return None
|