dsh-zju-lecture-note 2.2.4 → 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 CHANGED
@@ -1,7 +1,67 @@
1
1
  # 更新日志
2
2
 
3
3
  版本号在 `package.json`、`pyproject.toml`、`mcp_server.SERVER_VERSION`、
4
- `.minimax-plugin/plugin.json` 与两个 Skill manifest 六处对齐。
4
+ `.minimax-plugin/plugin.json` 与四个 Skill manifest 八处对齐。
5
+
6
+ ## 2.2.5 — 2026-11-06
7
+
8
+ - **默认安装即可用**:字幕鉴权改为核心链路的一部分。保留 `classroom.zju.edu.cn`,先匿名;
9
+ 仅 HTTP 401/403 时自动读取本机登录态、解析 Bearer 重试一次,不再要求开启登录辅助开关。
10
+ 字幕不发 Cookie 头,不用模型传凭据;`enableLoginTools` 只控制视频直链与读 Cookie 工具。
11
+ - **兼容老课程字幕**:`trans_type=ai` 返回 `time` / `zhtext` / `entext` 而非 `BeginSec` / `Text`,
12
+ 现在以第一条时间戳为相对零点换算秒数,旧课程也能生成讲义。
13
+ - **错误诊断更准确**:区分 HTTP 拒绝、接口业务错误与凭据读取失败;不再把 403 直接归因校园网。
14
+ 读不到凭据 / 遇到 ABE 时调用 `zju_login` 打开独立登录窗口,不索要 Cookie;
15
+ 代理 URL 的 userinfo 在诊断中掩码。
16
+ - **用户引导**:README 首屏说明首次登录与 401/403 处理;插件设置页、Skill 同步更新;
17
+ `zju_doctor(login=true)` 可选检查登录态与 Bearer 可用性,默认不读取凭据。
18
+ - **新增用户命令**:`/zju-lecture-summarizer-help` 面向登录辅助与查错(401/403、登录态、
19
+ 代理、Typst/PDF、工具开关)。它只对用户命令可见、不进入模型技能目录,且明确禁止索要或回显凭据。
20
+ - **CLI 默认自动重试**:`fetch` 在 401/403 后自动使用本机登录态;`--no-login` 可关闭,
21
+ `--cookie-file` 可指定本地文件,不新增明文 token 参数。
22
+
23
+ ### 一键登录窗口(2026-11-06 追加,仍在 2.2.5)
24
+
25
+ **不再让用户开开发者工具配 Cookie。**
26
+
27
+ - **`zju_login` 常驻工具**:字幕 / 投影遇到 401/403、或本机 Edge 因 ABE 无法读取时,
28
+ 插件用独立浏览器 profile 打开登录窗口(不碰日常 Edge)。用户正常登录(SSO / 2FA 由页面处理),
29
+ 插件通过 `127.0.0.1` 随机端口从浏览器进程内读取 Cookie,成功后自动关闭窗口。
30
+ - **登录态安全保存**:只保存 Cookie(不保存账号密码),Windows 用 DPAPI 绑定当前用户,
31
+ macOS / Linux 用 0600 文件;`zju_login(clear=true)` 一并删除登录态与独立浏览器配置。
32
+ 登录态失效时自动清除,下次从真正的登录页开始,不重放死 Cookie。
33
+ - **新的解析顺序**:内存缓存 → `ZJU_COOKIE` → `ZJU_COOKIE_FILE` → `zju_login` 登录态 → 本机 Edge。
34
+ `ZJU_COOKIE_FILE` 降为无图形界面服务器的高级兜底,普通用户不再需要手工配置。
35
+ - **跨平台**:Windows / macOS / Linux 均优先 Edge,其次 Chrome / Chromium;
36
+ 可用 `ZJU_BROWSER_BIN` 指定浏览器,`ZJU_LOGIN_DIR` 覆盖状态目录。
37
+ - **新用户命令** `/zju-lecture-summarizer-login`:只负责打开登录窗口或清除本机登录态。
38
+ 主 Skill 与 help Skill 同步改写 401/403 SOP,禁止索要 Cookie、密码或开发者工具内容。
39
+ - **工具集**:默认 7 个核心工具、全开 11 个;核心 Skill 3 个(主 Skill / help / login),
40
+ 填空模式再加 scholia-notes。设置页说明「登录入口始终可用」,`enableLoginTools` 只控制两个可选辅助工具。
41
+ - **回归**:新增 `tests/test_login_v225.py`(23 条),覆盖安全存储、Cookie 域过滤、
42
+ URL 白名单、解析顺序、失效清除、`clear=true` 与无浏览器失败原因。
43
+
44
+ ### 框的跨段边界(2026-11-06 追加,仍在 2.2.5)
45
+
46
+ 修一个「框太长」的排版问题:2.2.4 让定理 / 定义 / 例跨段之后,旧规则只认标题、已知标记
47
+ 与整行粗体,框会一路收到下一个标题,把后续讲解、`> [!IMPORTANT]` 提示块和结论整段吞进去。
48
+
49
+ - **新增五种收尾边界**:`>` 引用 / 提示块;以 `⚠` 开头的提醒段(qed 因此落在推导的
50
+ 最后一条公式之后,而不是列表末尾);「粗体小标题 + 冒号」(可带时间码,
51
+ `**矛盾从哪里来**` `[00:05]`:…);没加粗的「短引导词 + 时间码 + 冒号」
52
+ (`推导要点` `[00:43]`:…,证明块除外,避免 qed 停在半路);未知的中文标记
53
+ (如 `[推导]`)。普通段落、块级公式、列表、表格仍然留在框里,证明与例题的
54
+ 多段正文不受影响。
55
+ - **例题四段式例外**:`**题目**` / `**切入点**` / `**关键步骤**` / `**易错点**` 仍留在框内,
56
+ 不会被当成新的小节抬头。
57
+ - **「重点」不再套方框**:`> [!IMPORTANT]` 改成 `#keypoint` —— 规范蓝色
58
+ (`palette.thm` / `#33609B`)的无框文字段落,标签「重点」加粗;阅读版与填空版一致。
59
+ 其余 alert(注意 / 说明 / 提示)保持原提示块 / 灰色引用。
60
+ - **未知标记不再印方括号**:`[推导] …` 按旧规范的 Proof 样式兜底(斜体 `Proof.` +
61
+ 块末 qed,跨段、不套框);其余未知标记按「加粗小标题 + 正文」排。`note_lint`
62
+ 新增 `unknown_marker` 提示,引导改成已支持的标记。
63
+ - 两条链路(阅读版讲义与填空笔记)共用 `study_notes.block_boundary()`;
64
+ 回归加进 `tests/test_marker_span_v224.py`。
5
65
 
6
66
  ## 2.2.4 — 2026-11-05
7
67
 
package/README.md CHANGED
@@ -3,41 +3,42 @@
3
3
  由 [`nzw806/zju-lecture-summerizer-`](https://github.com/nzw806/zju-lecture-summerizer-) 改编的 DeepSeek Harness 原生插件,提供开箱即用的体验。
4
4
  面向 **DeepSeek Harness(dsh)** 与任意 **MCP 宿主**(Claude Code / Cursor / Cline / MiniMax Code…)。
5
5
 
6
- > 把浙大智云课堂(`classroom.zju.edu.cn`)的课程回放,变成一份**能直接复习的讲义**:
7
- > - 结构化 Markdown + 同名 PDF(封面、目录、公式、三线表、边注),在**本机**排好。
8
- > - 字幕接口公开免登录;登录 Cookie 只在本机进程内存里使用,工具不收、不回显、不落盘。
9
- > - 核心只用 Python 标准库;PDF 排版用的 Typst、中文字体与 Typst 包由插件自带或首次使用时自动准备(PDF 课件另需可选的 `pypdf`)。
6
+ > 把浙大智云课堂(`classroom.zju.edu.cn`)的课程回放,变成一份**能直接复习的讲义**:
7
+ > - 结构化 Markdown + 同名 PDF(封面、目录、公式、三线表、边注),在**本机**排好。
8
+ > - 字幕先匿名;401/403 时自动使用本机登录态重试一次。仍不可用时插件会打开独立登录窗口,你正常登录即可;登录态按系统能力保存在本机(Windows DPAPI;macOS/Linux 0600),不回显、不进入对话、不保存密码。
9
+ > - 核心只用 Python 标准库;PDF 排版所需的 Typst、中文字体与 Typst 包由插件自带或首次使用时自动准备。
10
10
  > - **非官方工具**:与浙江大学及其「智云课堂」平台无隶属关系,也未获其背书。
11
11
 
12
12
  ## 开始使用
13
13
 
14
- - 安装 DeepSeek Harness
15
- - 进入插件→添加插件,复制 npm 包名 dsh-zju-lecture-note 或仓库链接 https://github.com/chenqianyu486-sys/dsh-zju-lecture-note
16
- - 安装并启用插件
17
- - 在新会话中键入 /zju-lecture-summarizer 即可使用插件总结课堂内容,例:
14
+ - 安装 DeepSeek Harness。
15
+ - 进入插件 → 添加插件,填入 npm 包名 `dsh-zju-lecture-note` 或仓库链接 https://github.com/chenqianyu486-sys/dsh-zju-lecture-note 。
16
+ - 安装并启用插件。
17
+ - 首次使用**不需要配置 Cookie**:字幕被拒时,Agent 会调用 `zju_login` 打开独立登录窗口;你在窗口里正常登录,成功后窗口自动关闭并按系统能力保存登录态。也可主动输入 `/zju-lecture-summarizer-login`。
18
+ - 新会话输入 `/zju-lecture-summarizer` 总结课程;`/zju-lecture-summarizer-login` 管理登录;`/zju-lecture-summarizer-help` 排查 401/403 与依赖问题。例:
18
19
  ```text
19
20
  /zju-lecture-summarizer 帮我总结课程内容 https://classroom.zju.edu.cn/livingroom?course_id=87517&sub_id=1988617&tenant_code=112
20
21
  ```
22
+ ```text
23
+ /zju-lecture-summarizer-help 帮我解决当前无法使用的问题
24
+ ```
21
25
 
22
26
  ## 功能特色
23
27
 
24
28
  - **一句话出讲义**:给回放链接或 `sub_id`,Agent 抓字幕、写 Markdown、修公式、校验、命名,一次完成。
25
- - **装完即用**:缺少 Typst 时首次排版自动下载安装(SHA256 固定、可关),中文字体与 Typst 包随插件分发,
26
- 填空笔记离线也能编译;`zju_doctor` 随时报告本机依赖状态。
27
- - **自动 PDF**:写完讲义就在本地排同名 PDF(封面、目录、标题层级、居中公式、三线表、边注);
28
- PDF 失败不影响 Markdown,Agent 只多收一行路径。
29
- - **内容不丢**:字幕按分钟 / 逐句 / 分块读取;可读本地 PPTX / DOCX / PDF 课件校准术语;
30
- 可选把课堂投影截图合成 PDF。
31
- - **能动手复习**:可选「填空式学习笔记」——**基于 Typst scholia 模板排版的填空式学习笔记**;
32
- 配色与段落规范由本项目定义,见 [scholia-notes 规范](skills/scholia-notes/references/typography-spec.md)。
33
- - **隐私优先**:Cookie 不进工具参数与返回值,全输出脱敏;敏感文件拒绝;TLS 永不降级。
29
+ - **登录不用配 Cookie**:401/403 时自动打开独立登录窗口,登录后保存在本机;不碰日常 Edge,也不用开发者工具。
30
+ - **装完即用**:缺少 Typst 时首次排版自动准备(可关);中文字体与 Typst 包随插件分发,填空笔记离线也能编译;遇到问题可让 Agent 跑 `zju_doctor` 自检。
31
+ - **自动 PDF**:写完讲义就在本地排同名 PDF;PDF 失败不影响 Markdown。
32
+ - **内容不丢**:字幕按分钟 / 逐句 / 分块读取;可读本地 PPTX / DOCX / PDF 课件校准术语;可选把课堂投影截图合成 PDF。
33
+ - **能动手复习**:可选「填空式学习笔记」——基于 Typst scholia 模板排版的填空式学习笔记;配色与段落规范由本项目定义。
34
+ - **隐私优先**:常规工具不要求或读取 Cookie 参数,登录态不回显,Cookie/Bearer 输出脱敏;敏感文件拒绝;TLS 永不降级。当前版本仍有已知安全缺口,见 [SECURITY.md](SECURITY.md)。
34
35
  - **到处能用**:dsh 原生插件、标准 MCP、MiniMax Code 插件包、命令行四种入口。
35
36
 
36
37
  ## 安装
37
38
 
38
39
  ### 1. DeepSeek Harness(dsh)
39
40
 
40
- 从 npm 安装(推荐,2.1.0 起):
41
+ 从 npm 安装(推荐):
41
42
 
42
43
  ```bash
43
44
  dsh plugin --profile desktop add dsh-zju-lecture-note
@@ -52,8 +53,8 @@ dsh plugin --profile desktop add github:chenqianyu486-sys/dsh-zju-lecture-note
52
53
  - `desktop` profile 请用 **dsh 自带的 dsh 命令**(`resources/runtime/cli/bin/dsh.cmd`),
53
54
  不要用 npm 全局安装的 `dsh`。
54
55
  - **装完 / 更新后完全重启 DeepSeek Harness**(不是刷新页面):设置页的
55
- 「浙大智云课堂讲义」一栏要重启后才会出现。原因见 [技术细节](docs/technical.md#2-安装形态与依赖)。
56
- - 不要只解压 zip 让 dsh 加载(peer 依赖由 pnpm 在 `dsh plugin add` 时安装)。
56
+ 「浙大智云课堂讲义」一栏与左栏入口要重启后才会出现。
57
+ - 不要只解压 zip 让 dsh 加载;请用 npm 包名、`github:` 或 `file:` 方式安装。
57
58
 
58
59
  装好后直接说:
59
60
 
@@ -70,13 +71,12 @@ dsh plugin --profile desktop add github:chenqianyu486-sys/dsh-zju-lecture-note
70
71
  "type": "stdio",
71
72
  "command": "node",
72
73
  "args": ["/绝对路径/dsh-zju-lecture-note/server.mjs"],
73
- "timeout": 120000
74
+ "timeout": 600000
74
75
  }
75
76
  }
76
77
  }
77
78
  ```
78
79
 
79
- `server.mjs` 会自己找 Python(`ZJU_PYTHON` → `python3` / `python` / `py -3`,要求 3.9+)。
80
80
  Claude Code 一行接入:
81
81
 
82
82
  ```bash
@@ -90,6 +90,7 @@ claude mcp add zju-lecture node /绝对路径/dsh-zju-lecture-note/server.mjs
90
90
  python tools/build_plugin.py --install --zip
91
91
 
92
92
  # 命令行
93
+ python -m zju_lecture.cli login "<回放链接>"
93
94
  python -m zju_lecture.cli parse "<回放链接>"
94
95
  python -m zju_lecture.cli fetch 123456 --format min -o 字幕.txt
95
96
  python -m zju_lecture.cli courseware ./课件.pptx
@@ -108,137 +109,97 @@ python -m zju_lecture.cli slides "<回放链接>" --download
108
109
  (`知识总结-2026-10-28-复变函数-保角映射.md`),PDF 同名同目录。
109
110
  - 同名讲义默认拒绝覆盖,要覆盖请明确说「覆盖」。
110
111
  - 讲义不进 Git:`.gitignore` 已挡掉任意层级的 `知识总结*.md` 与 `/notes/`。
111
- - 字幕接口公开,但请一次只抓一节课,不要批量抓取。
112
+ - 字幕先匿名;401/403 时自动用本机登录态重试一次。一次只抓一节课,不要批量抓取。
112
113
 
113
114
  ### 阅读版 PDF
114
115
 
115
- `zju_write_note` 写完 Markdown、修完公式、跑完校验之后,会把**同一份内容**排成同名 PDF,
116
- Agent 只多收到一行 `PDF: <路径>(N 页)`。失败时 Markdown 照常写入,只回一行 `PDF 跳过: …`。
117
- 关掉自动排版(`renderPdf`)后只交付 Markdown;已有讲义可用 `zju_check_note(pdf=true)` 补排。
118
-
119
- 讲义里可以直接写这些标记:
120
-
121
- | 你写 | 得到 |
122
- | :--- | :--- |
123
- | `[直觉]` / `[定义] 标题 —— 正文` / `[定理]` / `[例]` | 淡彩方框(青绿 / 蓝 / 琥珀) |
124
- | `[证明]` | 斜体 `Proof.` + **块末** qed |
125
- | `[练习]` | 带 3 行书写横线的练习块 |
126
- | `[边注]` / `[边注!]` | 右侧留白栏的边注 |
127
- | `[强调]` / `[易错]` / `[弱注]` / `[分隔]` | 行内高亮 / 提示 / 弱化 / 分隔 |
128
- | `____` / `[缺口: …]` | 灰色填空线 / 留白 |
129
- | `<def:x>` + `@def:x` | 编号与回指(原生交叉引用) |
130
-
131
- 方框与 `[证明]` 是「块」不是「一行」:从标记行排到下一个标记 / 标题 / 整行粗体的小标题,
132
- 块里的空行是段落分隔,`$$…$$`、列表、表格都留在装置里 —— 证明的 qed 因此落在真正的结尾。
133
- 语义、预算(每节方框 ≤ 2 个)与数学写法由
134
- [格式规范](skills/scholia-notes/references/format-spec.md) 统一规定;字体、字号、版心、
135
- 边注等排版数值以[排版规范](skills/scholia-notes/references/typography-spec.md) 为唯一真相源;
136
- 两条链路共用同一套参数。
116
+ 讲义写完会自动在同目录生成同名 PDF,不需要额外操作。PDF 失败不影响 Markdown,
117
+ 只少这一份文件;也可以关闭自动排版,只交付 Markdown。需要给旧讲义补 PDF 时,
118
+ 让 Agent 重新检查并排版即可。
137
119
 
138
120
  ### 填空式学习笔记(可选)
139
121
 
140
- 打开 `enableStudyNotes` 后,`zju_build_study_notes` 产出**基于 Typst scholia 模板排版的
141
- 填空式学习笔记**:`mode=draft` 生成填空底稿,`mode=patch` 把一批挖空/标记一次写回,
142
- `mode=compile` 排成 PDF + 逐页 PNG。
143
- **配色与段落规范由本项目定义**,见
144
- [scholia-notes 规范](skills/scholia-notes/references/typography-spec.md)。
145
- 工具只做搬运与排版,哪句是定理、哪里挖空仍由你判断——自动挖空等于替读者决定「考什么」。
146
-
147
- 字体:两条 PDF 链路默认都用随包的 **Notes Kai SC**(LXGW WenKai / 霞鹜文楷的
148
- GB2312 子集)与 **Notes Serif SC**(Noto Serif SC 的 GB2312 子集),均为 SIL OFL,
149
- 不再依赖系统商业字体;生僻字回退到 Noto / Source Han(OFL)。对外分发 PDF 前按
150
- [排版规范 §8](skills/scholia-notes/references/typography-spec.md) 用 `pdffonts`
151
- 确认没嵌入 SimSun / KaiTi 等系统商业字体。
122
+ 打开「填空式学习笔记」后,可以直接让 Agent 出一版填空笔记:把已完成的讲义变成
123
+ 一份可动手填写的复习 PDF(另附逐页图片)。它基于 Typst scholia 模板排版;
124
+ 配色与段落规范由本项目定义。哪里挖空、哪些内容进方框属于内容判断,
125
+ 插件只负责搬运与排版。
152
126
 
153
127
  ### 投影截图(可选,默认关闭)
154
128
 
155
- 先打开 `enableSlides`(总开关),再决定 `embedSlideImages`(是否把截图插进讲义)。
156
- 打开后 Agent 会把截图下载到 `ppt-assets/<sub_id>/images/`,挑 **3–8 张**关键页写进讲义。
157
- 投影接口只返回截图,没有文字层 / OCR;需要幻灯片原文请提供原始 `.pptx`。
158
- 登录态优先读本机 Edge,也可用 `ZJU_COOKIE` / `ZJU_COOKIE_FILE`(**不要把 Cookie 贴进对话**)。
159
-
160
- ## 工具一览
161
-
162
- dsh 默认注册 **6 个**核心工具(含依赖自检 `zju_doctor`);打开填空笔记 +1、投影 +1、登录辅助 +2,**全开 10 个**。
163
- 关掉的模块不占工具列表、不加载代码。
164
-
165
- | 工具 | 用途 | 默认 |
166
- | :--- | :--- | :--- |
167
- | `zju_parse_url` | 解析回放链接,取 `sub_id` / `course_id` / `tenant_code` | 开 |
168
- | `zju_fetch_transcript` | 抓整节课或指定时间段的语音字幕(按分钟 / 逐句 / 分块 / JSON) | 开 |
169
- | `zju_extract_courseware` | 提取本地 PPTX / DOCX / TXT / MD / CSV / JSON / PDF 文本 | 开 |
170
- | `zju_check_note` | 检查 / 修复**已有**讲义;`pdf=true` 重排 PDF | 开 |
171
- | `zju_write_note` | 写入讲义:自动命名、拒绝静默覆盖、修公式、校验、自动排 PDF | 开 |
172
- | `zju_doctor` | 检查 Python / Typst / 字体 / 包;`install=true` 自动装 Typst | 开 |
173
- | `zju_build_study_notes` | 讲义 → 填空底稿 →(批量挖空)→ scholia PDF + 逐页 PNG | 关(`enableStudyNotes`) |
174
- | `zju_fetch_slides` | 抓投影截图清单,可选下载并合成 PDF | 关(`enableSlides`) |
175
- | `zju_get_video_url` | 解析回放 MP4 直链(供下载或 Whisper 重识别) | 关(`enableLoginTools`) |
176
- | `zju_read_browser_cookie` | 读本机 Edge 登录态并缓存到服务端内存(只回名称与长度) | 关(`enableLoginTools`) |
129
+ 打开「抓取 PPT 投影截图」后,可把课堂投影截图作为讲义的视觉补充(需要浙大登录态)。
130
+ 投影接口只返回截图,没有文字层或 OCR;需要幻灯片原文请提供原始 `.pptx`。
177
131
 
178
132
  ## 设置
179
133
 
180
- dsh 的六个开关在 **设置 → 左侧导航「浙大智云课堂讲义」**(独立一栏,不占通用设置),
181
- 按「核心链路 → 阅读输出 → 环境与依赖 → 主动回忆 → 课堂投影 → 登录辅助」分组,并有三枚预设:
182
- **省 Token / 复习模式 / 全功能**。
134
+ 设置有两个入口,内容与配置完全一致:
135
+
136
+ - **设置 → 左侧导航「浙大智云课堂讲义」**;
137
+ - **主界面左栏「智云讲义」**,点开在主区域显示同一页。
183
138
 
184
- 同一页也在**左侧栏的「智云讲义」一行**(`插件` / `自动化任务` 下面):点它直接在主区域打开,
185
- 不必先进设置。左栏入口与设置页共用同一份配置和同一个控制器,改哪边都一样;
186
- 侧边栏收起时它只显示图标,悬停给出同一个名字。
139
+ 设置按「核心链路 → 阅读输出 → 环境与依赖 → 主动回忆 → 课堂投影 → 登录辅助」分组,
140
+ 并提供三枚预设:**省 Token / 复习模式 / 全功能**。
187
141
 
188
142
  | 设置 | 作用 | 默认 |
189
143
  | :--- | :--- | :--- |
190
- | `renderPdf` | 写完讲义自动排同名 PDF | 开 |
191
- | `typstAutoInstall` | 缺少 Typst 时自动下载安装(约 20 MB,SHA256 校验) | 开 |
192
- | `enableStudyNotes` | 填空式学习笔记(`zju_build_study_notes` + scholia Skill) | 关 |
193
- | `enableSlides` | 投影抓取总开关(`zju_fetch_slides`) | 关 |
194
- | `embedSlideImages` | 投影截图是否插进讲义(仅在总开关打开时有效) | 关 |
195
- | `enableLoginTools` | 登录辅助(视频直链 / 读 Edge Cookie) | 关 |
144
+ | 自动排版 PDF 讲义 | 写完讲义后自动生成同名 PDF | 开 |
145
+ | 自动安装 Typst | 缺少排版引擎时自动准备(约 20 MB) | 开 |
146
+ | 填空式学习笔记 | 额外提供填空笔记 PDF | 关 |
147
+ | 抓取 PPT 投影截图 | 获取课堂投影截图(需登录态) | 关 |
148
+ | 把截图引用进讲义 | 是否把截图插入讲义(需先开启上一项) | 关 |
149
+ | 视频直链与登录态工具 | 额外的登录辅助工具;不影响字幕与一键登录 | 关 |
196
150
 
197
- MCP 宿主的对应环境变量:`ZJU_RENDER_PDF`、`ZJU_TYPST_AUTO_INSTALL`、`ZJU_ENABLE_STUDY_NOTES`、
198
- `ZJU_ENABLE_SLIDES`、`ZJU_EMBED_SLIDES`、`ZJU_ENABLE_LOGIN_TOOLS`(仓库自带的 `zju-lecture.mcp.json`
199
- 默认关掉可选模块)。另有 `ZJU_TYPST_BIN`(指定已有 Typst)与 `ZJU_TYPST_MIRROR`(下载镜像前缀)。
151
+ 保存后需**完全重启 DeepSeek Harness** 才会按新配置加载。环境变量与开关分层见
152
+ [技术细节](docs/technical.md#3-工具与开关分层)。
200
153
 
201
154
  ## 常见问题
202
155
 
203
156
  **设置里找不到「浙大智云课堂讲义」一栏?**
204
- 完全重启 DeepSeek Harness。dsh 在启动时缓存 `dsh.client` 元数据,刷新页面或只重装插件都不够。
157
+ 完全重启 DeepSeek Harness;刷新页面或只重装插件都不够。
205
158
 
206
159
  **返回 `PDF 跳过: …`?**
207
- 先让 Agent 跑 `zju_doctor`:它会报 Typst 版本 / 路径 / 来源、字体与 Typst 包是否就位。
208
- 缺少 Typst 时 `zju_doctor(install=true)` 会下载并校验安装;也可以自己装好(`typst --version` 能跑)
209
- 后用 `zju_check_note(pdf=true)` 给已有讲义补排。Markdown 本身不受影响。
210
- 若返回 `PDF 跳过: 找不到 typst:…` 且自动安装被关闭(`ZJU_TYPST_AUTO_INSTALL=0`),
211
- 打开设置里的「自动安装 Typst」或手动安装即可。
160
+ Markdown 已经正常写入,只是 PDF 没排出来。让 Agent 跑一次 `zju_doctor` 查看缺什么;
161
+ 缺少 Typst 时可让 Agent 安装,或打开设置里的「自动安装 Typst」。
212
162
 
213
- **看不到投影 / 登录工具?**
214
- 它们默认关闭。到设置里打开 `enableSlides` / `enableLoginTools` 后才注册;字幕主链路不需要登录。
163
+ **看不到投影或登录辅助工具?**
164
+ 它们默认关闭,到设置里打开并完全重启 dsh。一键登录 `zju_login` 始终可用,
165
+ 字幕鉴权也不依赖登录辅助开关。
215
166
 
216
- **只解压 zip 启用,报 `Cannot find package '@deepseek-ai/schemastery'`?**
217
- 那是 peer 依赖,由 pnpm 在 `dsh plugin add` 时装进 profile。请用 npm 包名、`github:` 或 `file:` 方式安装。
167
+ **只解压 zip 启用报错?**
168
+ 请用 npm 包名、`github:` 或 `file:` 方式安装,不要直接让 dsh 加载解压目录。
218
169
 
219
170
  **市场安装报 `connection to github.com timed out after 5000ms`?**
220
- 这是 dsh 宿主在 pnpm 启动前做 GitHub 连通性预检(`git ls-remote`,默认 5 秒)超时,不是插件本身报错。
221
- 优先用上面的 npm 命令安装,不经过 GitHub;必须走 GitHub 源时,先确认
222
- `git ls-remote https://github.com/chenqianyu486-sys/dsh-zju-lecture-note HEAD` 能在 5 秒内返回。
223
- 超时的话给 git 配代理,并让 dsh 进程能读到 `HTTPS_PROXY` / `HTTP_PROXY`(它不读 Windows 系统代理);
224
- 或在该 profile 的 `cordis.patch.yml` 里把 `plugin-manager` 的 `githubConnectionTimeoutMs` 调大后重启。
171
+ 这是安装前的网络连通性检查超时。优先改用上面的 npm 命令安装;必须走 GitHub 源时,
172
+ 先确认 git 能正常访问 GitHub。
225
173
 
226
- **字幕抓取失败(证书 / 代理)?**
227
- 插件不会关闭证书校验,按 `certifi` → 随包 `cacert.pem` → 系统根证书三级回落,
228
- 错误里会给出当前信任库、CA 张数与代理设置。详见 [SECURITY.md](SECURITY.md)。
174
+ **字幕抓取失败(401/403 / 证书 / 代理)?**
175
+ 让 Agent 调用 `zju_login`(或输入 `/zju-lecture-summarizer-login`)打开独立登录窗口,
176
+ 正常登录后会自动重试一次。不要输入开发者工具复制的 Cookie,也不要反复重试。
177
+ 只有无图形界面的服务器才需要本地 Cookie 文件兜底;证书校验不会降级,
178
+ 更多说明见 [SECURITY.md](SECURITY.md)。
229
179
 
230
180
  ## 隐私与安全
231
181
 
232
- - **Cookie 不是工具参数**:投影 / 视频直链 / 读 Cookie 工具都不接受 cookie 参数;
233
- 登录态只能由本地配置或本机 Edge 提供。
234
- - **Cookie 不回显、不落盘**:读 Cookie 只返回名称、数量、长度与来源类别,
235
- 所有输出经过 redactor;必须复制 Edge 数据库时用 0600 临时文件,读完覆写并删除。
236
- - **网络边界**:只允许 `classroom.zju.edu.cn` 与 `https://*.zju.edu.cn` 截图主机,跨域重定向拒绝;
237
- 证书校验不降级,只有瞬时故障才重试。
238
- - **本地文件有边界**:课件 / 讲义工具只接受指定扩展名,拒绝凭据、私钥与浏览器数据。
239
- - **可机器验证**:`python tools/privacy_scan.py` 扫描工作区、git 历史与 npm 产物。
240
-
241
- 完整威胁模型见 [SECURITY.md](SECURITY.md),实现细节见 [技术细节](docs/technical.md#8-隐私设计)。
182
+ > **当前安全状态(2026-11-06)**:最近一轮安全审查确认若干问题尚未修复,重点包括
183
+ > 多会话工作区隔离、截图重定向、部分修复/填空路径的工作区外回写、镜像 URL 诊断、
184
+ > 隐私扫描器输出和 POSIX 备份权限。修复前请不要在共享多用户机器上处理敏感课程材料,
185
+ > 不要让不同工作区的会话并发处理课程,也不要给 `ZJU_TYPST_MIRROR` 配置带凭据的 URL。
186
+ > 完整清单与临时规避见 [SECURITY.md](SECURITY.md) 第 7 节。
187
+
188
+ - **登录态不是正常工具参数**:字幕 / 投影 / 视频直链 / 读 Cookie 工具不要求 Cookie;
189
+ 登录态只能由 `zju_login`、本地配置或本机 Edge 提供。dsh 对未声明额外字段的校验
190
+ 仍有缺口,不要把凭据粘进工具调用。
191
+ - **登录态落盘、不回显**:`zju_login` 只保存 Cookie(不保存账号密码),
192
+ Windows 用 DPAPI 绑定当前用户,macOS / Linux 是 **0600 权限的明文文件**;
193
+ `zju_login(clear=true)` 会一并删除登录态与独立浏览器配置。Cookie/Bearer 输出脱敏,
194
+ 但镜像 URL 等非 Cookie 秘密尚未覆盖。
195
+ - **网络边界**:正常请求只到 `classroom.zju.edu.cn`、`https://*.zju.edu.cn` 截图主机
196
+ 与 Typst 官方下载地址;课堂 API 拒绝跨域重定向。投影截图的重定向目标尚未逐跳校验,
197
+ 这是已知缺口;证书校验不降级。
198
+ - **本地文件有边界**:课件 / 讲义工具只接受指定扩展名,拒绝凭据、私钥与浏览器数据;
199
+ `zju_write_note` 只写工作区,但部分修复/填空路径可以写回工作区外文件,详见
200
+ [SECURITY.md](SECURITY.md)。
201
+
202
+ 完整威胁模型和已知缺口见 [SECURITY.md](SECURITY.md)。
242
203
 
243
204
  ## 许可与致谢
244
205
 
@@ -248,41 +209,28 @@ MCP 宿主的对应环境变量:`ZJU_RENDER_PDF`、`ZJU_TYPST_AUTO_INSTALL`、
248
209
  **PDF 排版的上游模板**(特别感谢):
249
210
 
250
211
  - [`@preview/scholia`](https://typst.app/universe/package/scholia) **0.1.0**(MIT,© Eric Yang / 杨星宇,
251
- 仓库 [`Eryc123Y/scholia`](https://github.com/Eryc123Y/scholia)):**基于 Typst scholia 模板
252
- 排版的填空式学习笔记**的排版引擎(knot / note / 边注 / 封面 / 淡彩主题);配色与段落规范
253
- 由本项目定义,见 [scholia-notes 规范](skills/scholia-notes/references/typography-spec.md)。
254
- **该包及其依赖已随本仓库分发(vendored)**在 `zju_lecture/typst-packages/`,使填空笔记编译
255
- 不再依赖 Typst 包注册表;逐包保留上游 `LICENSE` / `UNLICENSE` 与 `typst.toml`,删除 README
256
- 与模板示例,并对 `src/fonts.typ` / `src/lib.typ` 打了补丁(见
257
- [`VENDORED.md`](zju_lecture/typst-packages/VENDORED.md))。
258
- 本插件的阅读版讲义 PDF 使用自研模板(`zju_lecture/handout_prelude.typ`),
259
- **视觉设计参考了它的浅色 notes 主题**,未拷贝其源码。
260
- - [`@preview/frame-it`](https://typst.app/universe/package/frame-it)(MIT,© Marc Thieme)、
261
- [`@preview/marginalia`](https://typst.app/universe/package/marginalia)(UNLICENSE)、
262
- [`@preview/theoretic`](https://typst.app/universe/package/theoretic)(UNLICENSE)、
263
- [`@preview/showybox`](https://typst.app/universe/package/showybox)(MIT)与
264
- [`@preview/noteworthy`](https://typst.app/universe/package/noteworthy)(MIT):scholia 的传递依赖,
265
- 同样随包分发,版本与许可见 [`VENDORED.md`](zju_lecture/typst-packages/VENDORED.md)。
212
+ 仓库 [`Eryc123Y/scholia`](https://github.com/Eryc123Y/scholia)):填空式学习笔记的排版引擎。
213
+ 该包及其依赖已随本仓库分发(vendored),逐包保留上游许可;版本与修改记录见
214
+ [`VENDORED.md`](zju_lecture/typst-packages/VENDORED.md)。阅读版讲义使用本项目自研模板,
215
+ 视觉上参考其浅色主题,未拷贝源码。
216
+ - 其他传递依赖(frame-it / marginalia / theoretic / showybox / noteworthy)同样随包分发。
266
217
  - 上游 scholia 声明自己是受 [`loom-notes`](https://github.com/Polaris-Aeterna/loom-notes)
267
- 设计启发的独立重写(XeLaTeX,MIT,未复用源码);本仓库也未分发它。
268
- - 「scholia」一词仅用于指代所依赖的 Typst 包;本插件与 Eric Yang 无隶属关系,也未获其背书。
269
- 逐条归属与「未拷贝代码」边界见 [ATTRIBUTION.md](ATTRIBUTION.md) 与
218
+ 设计启发的独立重写;本仓库未分发它。
219
+ - 「scholia」一词仅用于指代所依赖的 Typst 包;本插件与 Eric Yang 无隶属关系,
220
+ 也未获其背书。逐条归属见 [ATTRIBUTION.md](ATTRIBUTION.md) 与
270
221
  [THIRD_PARTY_NOTICES.md](skills/scholia-notes/THIRD_PARTY_NOTICES.md)。
271
222
 
272
- **随包中文字体**:`zju_lecture/fonts/NotesKaiSC-Subset.ttf` 是
273
- [LXGW WenKai](https://github.com/lxgw/LxgwWenKai)(霞鹜文楷)v1.530 的 GB2312 子集,
274
- `NotesSerifSC-Subset.ttf` 是 [Noto Serif SC](https://fonts.google.com/noto/specimen/Noto+Serif+SC)
275
- 的 GB2312 子集,均为 SIL OFL 1.1;两个字体都已改名以免与本机完整字体冲突。
276
- `OFL.txt` / `OFL-Kai.txt` 与 `FONT-NOTICE.md` 必须随字体一起分发。
223
+ **随包中文字体**:`Notes Kai SC` 与 `Notes Serif SC` 是霞鹜文楷 / Noto Serif SC 的
224
+ GB2312 子集,均为 SIL OFL 1.1,已改名以避免与本机字体冲突;许可文件随字体一起分发。
277
225
 
278
226
  其他项目:
279
227
 
280
228
  - [`PeiPei233/zju-learning-assistant`](https://github.com/PeiPei233/zju-learning-assistant)(ZLA,MIT):
281
229
  智云课堂 / 学在浙大 API 流程的原始实现,本插件与参考 CLI 的共同上游。
282
- - [`8eoyw/zju-learning-cli`](https://github.com/8eoyw/zju-learning-cli)(MIT):投影 PPT 管线的参考
283
- (`_token` → Bearer、分页去重、截图合成 PDF),本仓库按零第三方依赖重新实现,未拷贝代码。
284
- - [Typst](https://typst.app)(Apache-2.0):两条 PDF 链路的排版编译器。插件**不分发** Typst 二进制:
285
- 缺少时从官方 GitHub Release 下载到用户缓存目录,按仓库内固定的 SHA256 校验后再使用。
230
+ - [`8eoyw/zju-learning-cli`](https://github.com/8eoyw/zju-learning-cli)(MIT):投影 PPT 管线的参考,
231
+ 本仓库按零第三方依赖重新实现,未拷贝代码。
232
+ - [Typst](https://typst.app)(Apache-2.0):PDF 排版编译器;插件不分发 Typst 二进制,
233
+ 缺少时从官方 Release 下载并按固定 SHA256 校验。
286
234
  - [`certifi`](https://github.com/certifi/python-certifi) 与 Mozilla CA 证书库:随包 `cacert.pem` 的来源。
287
235
  - 以及为本插件提交 issue、做实地运行反馈、审查代码与文档的同学。
288
236
 
@@ -294,6 +242,5 @@ MCP 宿主的对应环境变量:`ZJU_RENDER_PDF`、`ZJU_TYPST_AUTO_INSTALL`、
294
242
  | [CHANGELOG.md](CHANGELOG.md) | 版本历史 |
295
243
  | [SECURITY.md](SECURITY.md) | 威胁模型、Cookie 生命周期、已知边界 |
296
244
  | [ATTRIBUTION.md](ATTRIBUTION.md) | 逐文件来源、第三方许可、参考实现边界 |
297
- | [format-spec.md](skills/scholia-notes/references/format-spec.md) | 规范性文件:Markdown → PDF 装置的语义对应、预算、配色与字体 |
298
245
 
299
246
  仅供个人学习使用:只抓取本人有权限访问的回放,Cookie 属个人凭证,不要外传。