dsh-zju-lecture-note 2.1.0 → 2.2.3

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