dsh-zju-lecture-note 2.2.5 → 2.2.7
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 +91 -1
- package/README.md +37 -31
- package/SECURITY.md +101 -36
- package/docs/technical.md +47 -24
- package/lib/bridge.js +278 -79
- package/lib/client.js +907 -758
- package/lib/index.js +232 -61
- package/lib/tools.js +26 -1
- package/lib/tools.schema.json +21 -1
- package/mcp_server.py +102 -24
- package/package.json +1 -1
- package/skills/scholia-notes/references/prelude.typ +9 -1
- package/skills/scholia-notes.manifest.json +3 -3
- package/skills/zju-lecture-summarizer/SKILL.md +1 -1
- package/skills/zju-lecture-summarizer/SLIDES.md +5 -3
- package/skills/zju-lecture-summarizer-help/SKILL.md +2 -2
- package/skills/zju-lecture-summarizer-help.manifest.json +4 -4
- package/skills/zju-lecture-summarizer-login/SKILL.md +1 -1
- package/skills/zju-lecture-summarizer-login.manifest.json +4 -4
- package/skills/zju-lecture-summarizer.manifest.json +6 -6
- package/zju_lecture/browser_login.py +17 -6
- package/zju_lecture/cli.py +26 -0
- package/zju_lecture/client.py +95 -18
- package/zju_lecture/courseware.py +37 -2
- package/zju_lecture/deps.py +98 -17
- package/zju_lecture/note_lint.py +34 -10
- package/zju_lecture/paths.py +57 -2
- package/zju_lecture/prelude.typ +9 -1
- package/zju_lecture/slides.py +73 -35
- package/zju_lecture/study_notes.py +105 -15
package/docs/technical.md
CHANGED
|
@@ -23,7 +23,7 @@ dsh-zju-lecture-note/
|
|
|
23
23
|
├── server.mjs # 启动器:解析 Python 解释器并拉起 MCP 服务
|
|
24
24
|
├── mcp_server.py # MCP stdio 服务器(JSON-RPC 2.0,隐私边界在这里)
|
|
25
25
|
├── zju_lecture/ # 核心库(纯标准库)
|
|
26
|
-
│ ├── client.py # 智云课堂 API 客户端(TLS 校验 +
|
|
26
|
+
│ ├── client.py # 智云课堂 API 客户端(TLS 校验 + origin/SSRF 重定向校验)
|
|
27
27
|
│ ├── cookies.py # Edge Cookie 读取与安全清理
|
|
28
28
|
│ ├── browser_login.py # 一键登录窗口:CDP 取 Cookie + 安全保存 + 清除
|
|
29
29
|
│ ├── security.py # Cookie 校验 / redactor / 本地文件边界
|
|
@@ -201,10 +201,17 @@ v2.0.1 起,「字幕 → 讲义 → PDF」主链路与投影、填空笔记等
|
|
|
201
201
|
|
|
202
202
|
- dsh 默认注册 **7** 个工具;`enableStudyNotes` +1、`enableSlides` +1、`enableLoginTools` +2,
|
|
203
203
|
全开 **11** 个。
|
|
204
|
+
- **所有设置项都标 `.volatile()`**:dsh 只把 volatile 字段投影进配置表单,也只有这些字段能由
|
|
205
|
+
设置页写入。2.2.7 起 `python` / `timeoutMs` / `registerSkill` 以及新增的 `typstPath` /
|
|
206
|
+
`typstMirror` 也一并纳入,设置页才覆盖「工具、依赖、解释器」三层,而不是只有模块开关。
|
|
204
207
|
- **`.volatile()` 字段是引用,不是布尔值**:dsh 把它们投影成 `{ get() }`,供插件在设置改动后
|
|
205
208
|
读取新值。`lib/index.js` 的 `readSetting()` 统一解包;直接写 `config.enableSlides === true`
|
|
206
209
|
会永远得到 `false`——2.1.1 修的「设置全开仍只有字幕」就是这个原因。新增设置项时务必走
|
|
207
210
|
`readSetting()`,并补一条 ref 形状的测试。
|
|
211
|
+
- **设置热更新**:只改 volatile 字段时,dsh 不重新执行 `apply()`,而是更新引用并发出
|
|
212
|
+
`loader/volatile-update`。插件监听该事件后重新同步工具、Skill、系统提示词(`text` 是 thunk,
|
|
213
|
+
每次组装都重新读取配置)并把已启动的 Python 子进程作废,下一次调用用新环境变量拉起。
|
|
214
|
+
因此保存后 Agent 下一轮就能读到;只有安装 / 更新插件本身仍需完全重启。
|
|
208
215
|
- MCP 未设置新变量时保持旧行为(11 个);仓库自带的 `zju-lecture.mcp.json` 默认关掉三个可选模块(7 个)。
|
|
209
216
|
- 关闭时:不注册对应工具、不加载对应模块、Skill 不追加对应附录;系统提示会说明
|
|
210
217
|
「这个模块已关闭」,Agent 不会调用或假装调用。
|
|
@@ -231,7 +238,7 @@ v2.0.1 起,「字幕 → 讲义 → PDF」主链路与投影、填空笔记等
|
|
|
231
238
|
|
|
232
239
|
| 变量 | 作用 |
|
|
233
240
|
| :--- | :--- |
|
|
234
|
-
| `ZJU_PYTHON` | 指定 Python
|
|
241
|
+
| `ZJU_PYTHON` | 指定 Python 解释器(dsh 对应 `python`,留空走自带解释器) |
|
|
235
242
|
| `ZJU_WORKSPACE` | 相对路径的解析根;dsh 插件自动传入 session workspace |
|
|
236
243
|
| `ZJU_BACKUP_DIR` | `zju_check_note` / `zju_write_note` 的备份目录(默认系统临时目录) |
|
|
237
244
|
| `ZJU_COOKIE` / `ZJU_COOKIE_FILE` | 显式本机登录态(优先级最高);存在且损坏时会挡住 `zju_login`,字幕仅在 HTTP 401/403 后自动使用 |
|
|
@@ -239,8 +246,8 @@ v2.0.1 起,「字幕 → 讲义 → PDF」主链路与投影、填空笔记等
|
|
|
239
246
|
| `ZJU_BROWSER_BIN` | 指定登录窗口使用的浏览器可执行文件(默认 Edge → Chrome → Chromium) |
|
|
240
247
|
| `ZJU_RENDER_PDF` | 默认 `0`(MCP);对应 dsh `renderPdf`(默认开) |
|
|
241
248
|
| `ZJU_TYPST_AUTO_INSTALL` | 缺 Typst 时自动下载安装(默认 `1`;dsh 对应 `typstAutoInstall`) |
|
|
242
|
-
| `ZJU_TYPST_BIN` | 指定已有 Typst
|
|
243
|
-
| `ZJU_TYPST_MIRROR` | Typst 下载 URL 的镜像前缀,例如 `https://ghfast.top
|
|
249
|
+
| `ZJU_TYPST_BIN` | 指定已有 Typst 可执行文件(优先级最高;dsh 对应 `typstPath`) |
|
|
250
|
+
| `ZJU_TYPST_MIRROR` | Typst 下载 URL 的镜像前缀,例如 `https://ghfast.top/`(dsh 对应 `typstMirror`) |
|
|
244
251
|
| `ZJU_TYPST_CACHE` | 覆盖 Typst 缓存目录(默认用户缓存;测试与换盘时用) |
|
|
245
252
|
| `ZJU_ENABLE_STUDY_NOTES` / `ZJU_ENABLE_SLIDES` / `ZJU_EMBED_SLIDES` / `ZJU_ENABLE_LOGIN_TOOLS` | 可选模块开关;最后一项只控制登录辅助工具,字幕鉴权不受影响 |
|
|
246
253
|
| `ZJU_ALLOW_SENSITIVE_PATHS` | 显式关闭本地敏感路径保护(不推荐) |
|
|
@@ -404,6 +411,16 @@ v2.0.1 起,「字幕 → 讲义 → PDF」主链路与投影、填空笔记等
|
|
|
404
411
|
- 数学转换是**幂等**的:`_plain_word` 认识转换器自己会产出的名字(`frac` / `cal` / `sum` /
|
|
405
412
|
`quad` / `wide` / `slash` / `"Res"` …),所以 `latex_to_typst(latex_to_typst(x)) == latex_to_typst(x)`,
|
|
406
413
|
不会被拆成 `s u m` / `f r a c`。引号串(`"Res"`)原样搬运,不再被二次加工。
|
|
414
|
+
- **上下标里的整体记号不拆**:`_typst_script` 只对「还没转换过的裸字母串」逐字母拆
|
|
415
|
+
(`a_{ij}` → `a_(i j)`、`u_{tt}` → `u_(t t)`);转换器自己产出的名字
|
|
416
|
+
(`alpha` / `theta` / `compose` / `degree` …)属于**一个**记号,按 `_TYPST_BARE_NAMES`
|
|
417
|
+
原样放行。早先不加区分,`29^{\circ}` 排成 `29^(c o m p o s e)`,PDF 右上角直接印出单词
|
|
418
|
+
(实地会话 `session-42baa52c` 的截图);`x^{\alpha}`、`x_{\theta}` 同样中招。
|
|
419
|
+
`\circ` 出现在上下标里转 `degree`(`29^\circ` 是角度),`f\circ g` 仍是 `compose`;
|
|
420
|
+
不带花括号的 `^\circ` / `^\alpha` 会补成 `^(…)`,`x_1` / `a_n` 保持原样。
|
|
421
|
+
- **`\left` / `\right` 的分隔符必须留下**:`\left\lvert` / `\left\|` / `\lVert` / `\rVert`
|
|
422
|
+
分别落 `|` 与 `‖`,`\left.` / `\right.` 是不可见分隔符(早先会印出一个点);
|
|
423
|
+
`\big` / `\Big` / `\bigl` / `\Bigr` 这类尺寸命令静默丢弃,不印出单词 `big`。
|
|
407
424
|
- 间距命令走 Typst 的真实间距:`\quad` → `quad`(1em)、`\qquad` → `wide`(2em)、
|
|
408
425
|
`\,` → `thin`、`\;` → `med`。早先映射成空格,而 Typst 会折叠连续空格,
|
|
409
426
|
于是「并排的两条公式」粘成 `0∇×H`(实地会话里 Agent 只能写脚本拆公式块)。
|
|
@@ -463,7 +480,8 @@ python tools/check_note.py --fix 讲义.md # 自动修正机械问题
|
|
|
463
480
|
5. 回显:Cookie / 密码 / Bearer 没有;工具 schema 中没有 cookie / password / reveal / domain 参数。
|
|
464
481
|
签名视频直链是例外,会作为预期结果返回给调用方;
|
|
465
482
|
6. 日志:MCP 工具结果、异常、JSON-RPC 输出以及 Python `_log()` 经过 `SecretRedactor`;
|
|
466
|
-
|
|
483
|
+
依赖模块的镜像 URL 先由 `deps._redact_url()` 去掉 userinfo / query / fragment,
|
|
484
|
+
bridge.js 转发 stderr 前再做一层 JS 脱敏(见 [SECURITY.md](../SECURITY.md) §7.4);
|
|
467
485
|
7. 临时文件:只读打开优先;必须复制时连同 `-wal` / `-shm` 一起复制(刚登录的行可能还在 WAL 里),
|
|
468
486
|
权限 0600,读完覆写并删除;
|
|
469
487
|
8. 落盘:只有 `zju_login` 保存的登录态与独立浏览器 profile。登录态仅含 Cookie(不保存账号密码),
|
|
@@ -473,8 +491,9 @@ python tools/check_note.py --fix 讲义.md # 自动修正机械问题
|
|
|
473
491
|
|
|
474
492
|
Cookie 不是正常工具参数:`zju_fetch_transcript` / `zju_fetch_slides` / `zju_get_video_url` 不接受 cookie 参数,
|
|
475
493
|
`zju_read_browser_cookie` 也没有参数;登录态只能由 `zju_login`、本地配置或本机 Edge 提供。
|
|
476
|
-
dsh
|
|
477
|
-
|
|
494
|
+
dsh 0.2.x 不为工具参数生成根级封闭声明,但 `handle_tool_call` 会按
|
|
495
|
+
`inputSchema.properties` 拒绝未声明的字段(`未知参数: cookie`),工具不执行
|
|
496
|
+
(见 [SECURITY.md](../SECURITY.md) §7.7)。
|
|
478
497
|
字幕匿名成功时不读缓存、环境变量、文件或 Edge 凭据;401/403 后读不到凭据 / 遇到 ABE 时,
|
|
479
498
|
调用 `zju_login` 打开独立登录窗口,不向模型索要 Cookie,也不保证关闭 Edge 能解决。
|
|
480
499
|
显式配置优先:`ZJU_COOKIE` → `ZJU_COOKIE_FILE`;两者损坏都会挡住后续来源——诊断文本会明确要求先修/移除。
|
|
@@ -487,10 +506,11 @@ dsh 适配层目前对未声明额外字段的校验不完整,模型传入的
|
|
|
487
506
|
(`my-secret.txt` 拒绝、`secret sharing 第5章.md` 放行),`config.json` 这类通用名不再被拒。
|
|
488
507
|
符号链接会先解析真实路径再判定。确有必要时可用 `ZJU_ALLOW_SENSITIVE_PATHS=1` 显式关闭保护。
|
|
489
508
|
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
509
|
+
写入边界统一由 `paths.require_workspace_path()` 仲裁:`zju_write_note`、截图输出与 PDF
|
|
510
|
+
工程限制在工作区;`zju_check_note(fix=true)` 与 `zju_build_study_notes(mode="patch")`
|
|
511
|
+
在任何情况下都拒绝工作区外目标。读取工作区外课件只有
|
|
512
|
+
`zju_extract_courseware(allow_outside_workspace=true)` 一个显式入口,结果首行标注
|
|
513
|
+
「已读取工作区外文件」,且仍受扩展名/凭据防护(见 [SECURITY.md](../SECURITY.md) §9)。
|
|
494
514
|
|
|
495
515
|
### 网络
|
|
496
516
|
|
|
@@ -502,10 +522,10 @@ Markdown,且 `patch` 没有备份。这是待修复缺口(见 [SECURITY.md](
|
|
|
502
522
|
- 课堂 API 的 Cookie(投影 / 视频直链)与 Bearer 仅发往 `classroom.zju.edu.cn`;字幕不发 Cookie 头。
|
|
503
523
|
课堂 API 的跨域 302 直接拒绝,避免 `urllib` 把 `Cookie` / `Authorization` 头重发到第三方域。
|
|
504
524
|
- 投影截图的**初始**地址只允许 `https://*.zju.edu.cn`;ZJU 的 `http://` 自动升级 HTTPS;
|
|
505
|
-
Cookie 只给 ZJU
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
525
|
+
Cookie 只给 ZJU 图片主机。图片返回 401/403 时 Bearer 只重试到同一图片主机。
|
|
526
|
+
重定向逐跳校验:目标必须是浙大主机,拒绝 HTTPS→HTTP、URL userinfo、IP 字面量与
|
|
527
|
+
私网/loopback;跨 origin 时剥离 Cookie / Authorization / Proxy-Authorization,
|
|
528
|
+
被阻止的跳转只写 diagnostics(见 [SECURITY.md](../SECURITY.md) §10)。
|
|
509
529
|
- 可选的 Typst 自动安装会访问 GitHub 官方 Release,并通过 `ZJU_TYPST_MIRROR` 支持镜像;
|
|
510
530
|
`@preview` 包已 vendor,但底稿显式引用未 vendor 的包时仍可能访问包注册表。
|
|
511
531
|
|
|
@@ -517,8 +537,10 @@ Markdown,且 `patch` 没有备份。这是待修复缺口(见 [SECURITY.md](
|
|
|
517
537
|
(可用 `clear=true` 删除)、Typst 缓存与讲义/备份文件外,不写用户目录。
|
|
518
538
|
|
|
519
539
|
自动修复备份默认位于系统临时目录的 `zju-lecture-backups/`,可用 `ZJU_BACKUP_DIR` 指定;
|
|
520
|
-
|
|
521
|
-
|
|
540
|
+
目录按 0700 创建、备份文件 0600、文件名带 8 位随机后缀,写入前拒绝符号链接
|
|
541
|
+
(见 [SECURITY.md](../SECURITY.md) §7.6)。
|
|
542
|
+
`ZJU_TYPST_MIRROR` 仍不应包含凭据;`zju_doctor`、下载进度与异常只显示
|
|
543
|
+
`scheme://host[:port]/path`(§7.4)。
|
|
522
544
|
|
|
523
545
|
### 可机器验证
|
|
524
546
|
|
|
@@ -563,9 +585,10 @@ Cookie WAL 回放、ABE 探测、PDF 报错带解释器路径、bridge 超时语
|
|
|
563
585
|
登录态安全存储 / Cookie 域过滤 / 登录 URL 白名单 / 失效清除 / `zju_login(clear=true)`、
|
|
564
586
|
阅读版 PDF 的标记装置与真实编译、配色三处一致与字体可再分发性、填空笔记链路。
|
|
565
587
|
|
|
566
|
-
>
|
|
567
|
-
>
|
|
568
|
-
>
|
|
588
|
+
> 2026-11-06 安全审查确认的问题已在 `fix/security-audit-2026-11` 分支全部修复,
|
|
589
|
+
> 每条都有独立回归测试(工作区隔离、重定向、边界、脱敏、掩码、权限、资源上限、
|
|
590
|
+
> 参数白名单、副作用确认、封面注入)。逐条 commit 与验证见
|
|
591
|
+
> [SECURITY.md](../SECURITY.md) 第 7 节。
|
|
569
592
|
|
|
570
593
|
> 测试中的 `subprocess` / 管道 / 临时文件在受限沙箱里可能被拒绝;这是环境限制,不是插件缺陷。
|
|
571
594
|
|
|
@@ -588,7 +611,7 @@ npm view dsh-zju-lecture-note version # 验证
|
|
|
588
611
|
|
|
589
612
|
- `package.json` 的 `prepublishOnly` 已挂「全量测试 + 隐私扫描」,测试红了发不出去。
|
|
590
613
|
- registry 必须是 `https://registry.npmjs.org/`:国内镜像只读,`npm publish` 会 403。
|
|
591
|
-
- 版本号不能覆盖:每次发布前必须 bump
|
|
614
|
+
- 版本号不能覆盖:每次发布前必须 bump(九处对齐,见下节)。
|
|
592
615
|
- 发布后用户安装:`dsh plugin --profile desktop add dsh-zju-lecture-note`。
|
|
593
616
|
|
|
594
617
|
`files` 字段是逐文件枚举的运行时清单(`lib/`、`mcp_server.py`、`zju_lecture/*.py`、`skills/`、
|
|
@@ -605,9 +628,9 @@ dsh 按 `peerDependencies` 校验运行时版本。若升级 dsh 后插件被跳
|
|
|
605
628
|
|
|
606
629
|
### 版本号
|
|
607
630
|
|
|
608
|
-
|
|
609
|
-
`.minimax-plugin/plugin.json`、四个 Skill manifest
|
|
610
|
-
`tests/
|
|
631
|
+
版本在**九处**对齐:`package.json`、`pyproject.toml`、`mcp_server.SERVER_VERSION`、
|
|
632
|
+
`.minimax-plugin/plugin.json`、`adapters/claude_code/plugin.json`、四个 Skill manifest
|
|
633
|
+
(由 `tools/build_skill_manifest.py` 生成)。`tests/test_settings_v227.py` 会断言。
|
|
611
634
|
|
|
612
635
|
### 插件市场条目
|
|
613
636
|
|