dsh-zju-lecture-note
chenqianyu486-sys/dsh-zju-lecture-note
저장강대 강의 녹화(classroom.zju.edu.cn)를 Markdown 학습 노트와 같은 이름의 Typst 조판 로컬 PDF로 변환합니다. 스크래핑 핵심은 nzw806/zju-lecture-summerizer-의 독립 Python 도구로 DSH 플러그인이 아닙니다. 슬라이드 캡처는 8eoyw/zju-learning-cli(MIT)를 코드 복사 없이 재구현했습니다. Typst가 없으면 공식 릴리스에서 SHA256 고정 설치(선택 해제 가능)합니다. scholia 패키지와 재배포 가능한 OFL CJK 글꼴 일부를 포함해 오프라인에서도 작동합니다. 전사는 분·문장·청크별로 읽습니다. 비공식 도구이며 저장강대나 업스트림 작성자와 제휴/승인을 받지 않았습니다. 전사는 공개 열람 가능하지만 슬라이드 캡처는 설정에서 켜는 선택 기능으로 ZJU 로그인(ZJU_COOKIE / ZJU_COOKIE_FILE 또는 로컬 Edge 프로필)이 필요합니다.
설치
dsh plugin --profile web add github:chenqianyu486-sys/dsh-zju-lecture-noteREADME
浙大智云课堂讲义插件（ZJU Lecture Agent Plugin）
由 nzw806/zju-lecture-summerizer- 改编的 DeepSeek Harness 原生插件，提供开箱即用的体验。
面向 DeepSeek Harness（dsh） 与任意 MCP 宿主（Claude Code / Cursor / Cline / MiniMax Code…）。
把浙大智云课堂（
classroom.zju.edu.cn）的课程回放，变成一份能直接复习的讲义：
- 结构化 Markdown + 同名 PDF（封面、目录、公式、三线表、边注），在本机排好。
- 字幕接口公开免登录；登录 Cookie 只在本机进程内存里使用，工具不收、不回显、不落盘。
- 核心只用 Python 标准库；PDF 排版用的 Typst、中文字体与 Typst 包由插件自带或首次使用时自动准备（PDF 课件另需可选的
pypdf）。- 非官方工具：与浙江大学及其「智云课堂」平台无隶属关系，也未获其背书。
开始使用
- 安装 DeepSeek Harness
- 进入插件→添加插件，复制仓库链接 https://github.com/chenqianyu486-sys/dsh-zju-lecture-note
- 安装并启用插件
- 在新会话中键入 /zju-lecture-summarizer 即可使用插件总结课堂内容，例：
/zju-lecture-summarizer 帮我总结课程内容 https://classroom.zju.edu.cn/livingroom?course_id=87517&sub_id=1988617&tenant_code=112
功能特色
- 一句话出讲义：给回放链接或
sub_id，Agent 抓字幕、写 Markdown、修公式、校验、命名，一次完成。 - 装完即用：缺少 Typst 时首次排版自动下载安装（SHA256 固定、可关），中文字体与 Typst 包随插件分发，
填空笔记离线也能编译；
zju_doctor随时报告本机依赖状态。 - 自动 PDF：写完讲义就在本地排同名 PDF（封面、目录、标题层级、居中公式、三线表、边注）； PDF 失败不影响 Markdown，Agent 只多收一行路径。
- 内容不丢：字幕按分钟 / 逐句 / 分块读取；可读本地 PPTX / DOCX / PDF 课件校准术语； 可选把课堂投影截图合成 PDF。
- 能动手复习：可选「填空式学习笔记」——基于 Typst scholia 模板排版的填空式学习笔记； 配色与段落规范由本项目定义，见 scholia-notes 规范。
- 隐私优先：Cookie 不进工具参数与返回值，全输出脱敏；敏感文件拒绝；TLS 永不降级。
- 到处能用：dsh 原生插件、标准 MCP、MiniMax Code 插件包、命令行四种入口。
安装
1. DeepSeek Harness（dsh）
从 npm 安装（推荐，2.1.0 起）：
dsh plugin --profile desktop add dsh-zju-lecture-note
或直接从 GitHub 仓库安装（跟随最新提交）：
dsh plugin --profile desktop add github:chenqianyu486-sys/dsh-zju-lecture-note
desktopprofile 请用 dsh 自带的 dsh 命令（resources/runtime/cli/bin/dsh.cmd）， 不要用 npm 全局安装的dsh。- 装完 / 更新后完全重启 DeepSeek Harness（不是刷新页面）：设置页的 「浙大智云课堂讲义」一栏要重启后才会出现。原因见 技术细节。
- 不要只解压 zip 让 dsh 加载（peer 依赖由 pnpm 在
dsh plugin add时安装）。
装好后直接说：
帮我把这节课整理成讲义：https://classroom.zju.edu.cn/livingroom?course_id=58133&sub_id=123456
2. 任意 MCP 宿主
本仓库自带 stdio MCP Server，配置里只要一个 PATH 上的 node：
{
"mcpServers": {
"zju-lecture": {
"type": "stdio",
"command": "node",
"args": ["/绝对路径/dsh-zju-lecture-note/server.mjs"],
"timeout": 120000
}
}
}
server.mjs 会自己找 Python（ZJU_PYTHON → python3 / python / py -3，要求 3.9+）。
Claude Code 一行接入：
claude mcp add zju-lecture node /绝对路径/dsh-zju-lecture-note/server.mjs
3. 其它入口
# MiniMax Code 插件包
python tools/build_plugin.py --install --zip
# 命令行
python -m zju_lecture.cli parse "<回放链接>"
python -m zju_lecture.cli fetch 123456 --format min -o 字幕.txt
python -m zju_lecture.cli courseware ./课件.pptx
python -m zju_lecture.cli slides "<回放链接>" --download
怎么用
对 Agent 说一句话就够了：
帮我把这节课整理成讲义：<回放链接>，重点讲后半节的样条插值。
刚才那份讲义，把第 3 节的公式再推导一遍，并出 3 道自测题。
- 讲义默认写在工作区根目录，文件名由 Agent 按「上课日期 + 本节内容」起名
（
知识总结-2026-10-28-复变函数-保角映射.md），PDF 同名同目录。 - 同名讲义默认拒绝覆盖，要覆盖请明确说「覆盖」。
- 讲义不进 Git：
.gitignore已挡掉任意层级的知识总结*.md与/notes/。 - 字幕接口公开，但请一次只抓一节课，不要批量抓取。
阅读版 PDF
zju_write_note 写完 Markdown、修完公式、跑完校验之后，会把同一份内容排成同名 PDF，
Agent 只多收到一行 PDF: <路径>（N 页）。失败时 Markdown 照常写入，只回一行 PDF 跳过: …。
关掉自动排版（renderPdf）后只交付 Markdown；已有讲义可用 zju_check_note(pdf=true) 补排。
讲义里可以直接写这些标记：
| 你写 | 得到 |
|---|---|
[直觉] / [定义] 标题 —— 正文 / [定理] / [例] | 淡彩方框（青绿 / 蓝 / 琥珀） |
[证明] | 斜体 Proof. + 行末 qed |
[练习] | 带 3 行书写横线的练习块 |
[边注] / [边注!] | 右侧留白栏的边注 |
[强调] / [易错] / [弱注] / [分隔] | 行内高亮 / 提示 / 弱化 / 分隔 |
____ / [缺口: …] | 灰色填空线 / 留白 |
<def:x> + @def:x | 编号与回指（原生交叉引用） |
语义、预算（每节方框 ≤ 2 个）与数学写法由 格式规范 统一规定； 字体、字号、版心、边注等排版数值以 排版规范 为唯一真相源。 填空笔记与阅读版讲义两条链路共用同一套参数。
填空式学习笔记（可选）
打开 enableStudyNotes 后，zju_build_study_notes 产出基于 Typst scholia 模板排版的
填空式学习笔记：mode=draft 生成填空底稿，mode=compile 排成 PDF + 逐页 PNG。
配色与段落规范由本项目定义，见
scholia-notes 规范。
工具只做搬运与排版，哪句是定理、哪里挖空仍由你判断——自动挖空等于替读者决定「考什么」。
字体：两条 PDF 链路默认都用随包的 Notes Kai SC（LXGW WenKai / 霞鹜文楷的
GB2312 子集）与 Notes Serif SC（Noto Serif SC 的 GB2312 子集），均为 SIL OFL，
不再依赖系统商业字体；生僻字回退到 Noto / Source Han（OFL）。对外分发 PDF 前按
排版规范 §8 用 pdffonts
确认没嵌入 SimSun / KaiTi 等系统商业字体。
投影截图（可选，默认关闭）
先打开 enableSlides（总开关），再决定 embedSlideImages（是否把截图插进讲义）。
打开后 Agent 会把截图下载到 ppt-assets/<sub_id>/images/，挑 3–8 张关键页写进讲义。
投影接口只返回截图，没有文字层 / OCR；需要幻灯片原文请提供原始 .pptx。
登录态优先读本机 Edge，也可用 ZJU_COOKIE / ZJU_COOKIE_FILE（不要把 Cookie 贴进对话）。
工具一览
dsh 默认注册 6 个核心工具（含依赖自检 zju_doctor）；打开填空笔记 +1、投影 +1、登录辅助 +2，全开 10 个。
关掉的模块不占工具列表、不加载代码。
| 工具 | 用途 | 默认 |
|---|---|---|
zju_parse_url | 解析回放链接，取 sub_id / course_id / tenant_code | 开 |
zju_fetch_transcript | 抓整节课或指定时间段的语音字幕（按分钟 / 逐句 / 分块 / JSON） | 开 |
zju_extract_courseware | 提取本地 PPTX / DOCX / TXT / MD / CSV / JSON / PDF 文本 | 开 |
zju_check_note | 检查 / 修复已有讲义；pdf=true 重排 PDF | 开 |
zju_write_note | 写入讲义：自动命名、拒绝静默覆盖、修公式、校验、自动排 PDF | 开 |
zju_doctor | 检查 Python / Typst / 字体 / 包；install=true 自动装 Typst | 开 |
zju_build_study_notes | 讲义 → 填空底稿 → scholia PDF + 逐页 PNG | 关（enableStudyNotes） |
zju_fetch_slides | 抓投影截图清单，可选下载并合成 PDF | 关（enableSlides） |
zju_get_video_url | 解析回放 MP4 直链（供下载或 Whisper 重识别） | 关（enableLoginTools） |
zju_read_browser_cookie | 读本机 Edge 登录态并缓存到服务端内存（只回名称与长度） | 关（enableLoginTools） |
设置
dsh 的六个开关在 设置 → 左侧导航「浙大智云课堂讲义」（独立一栏，不占通用设置）， 按「核心链路 → 阅读输出 → 环境与依赖 → 主动回忆 → 课堂投影 → 登录辅助」分组，并有三枚预设： 省 Token / 复习模式 / 全功能。
| 设置 | 作用 | 默认 |
|---|---|---|
renderPdf | 写完讲义自动排同名 PDF | 开 |
typstAutoInstall | 缺少 Typst 时自动下载安装（约 20 MB，SHA256 校验） | 开 |
enableStudyNotes | 填空式学习笔记（zju_build_study_notes + scholia Skill） | 关 |
enableSlides | 投影抓取总开关（zju_fetch_slides） | 关 |
embedSlideImages | 投影截图是否插进讲义（仅在总开关打开时有效） | 关 |
enableLoginTools | 登录辅助（视频直链 / 读 Edge Cookie） | 关 |
MCP 宿主的对应环境变量：ZJU_RENDER_PDF、ZJU_TYPST_AUTO_INSTALL、ZJU_ENABLE_STUDY_NOTES、
ZJU_ENABLE_SLIDES、ZJU_EMBED_SLIDES、ZJU_ENABLE_LOGIN_TOOLS（仓库自带的 zju-lecture.mcp.json
默认关掉可选模块）。另有 ZJU_TYPST_BIN（指定已有 Typst）与 ZJU_TYPST_MIRROR（下载镜像前缀）。
常见问题
设置里找不到「浙大智云课堂讲义」一栏？
完全重启 DeepSeek Harness。dsh 在启动时缓存 dsh.client 元数据，刷新页面或只重装插件都不够。
返回 PDF 跳过: …？
先让 Agent 跑 zju_doctor：它会报 Typst 版本 / 路径 / 来源、字体与 Typst 包是否就位。
缺少 Typst 时 zju_doctor(install=true) 会下载并校验安装；也可以自己装好（typst --version 能跑）
后用 zju_check_note(pdf=true) 给已有讲义补排。Markdown 本身不受影响。
若返回 PDF 跳过: 找不到 typst：… 且自动安装被关闭（ZJU_TYPST_AUTO_INSTALL=0），
打开设置里的「自动安装 Typst」或手动安装即可。
看不到投影 / 登录工具？
它们默认关闭。到设置里打开 enableSlides / enableLoginTools 后才注册；字幕主链路不需要登录。
只解压 zip 启用，报 Cannot find package '@deepseek-ai/schemastery'？
那是 peer 依赖，由 pnpm 在 dsh plugin add 时装进 profile。请用 npm 包名、github: 或 file: 方式安装。
市场安装报 connection to github.com timed out after 5000ms？
这是 dsh 宿主在 pnpm 启动前做 GitHub 连通性预检（git ls-remote，默认 5 秒）超时，不是插件本身报错。
优先用上面的 npm 命令安装，不经过 GitHub；必须走 GitHub 源时，先确认
git ls-remote https://github.com/chenqianyu486-sys/dsh-zju-lecture-note HEAD 能在 5 秒内返回。
超时的话给 git 配代理，并让 dsh 进程能读到 HTTPS_PROXY / HTTP_PROXY（它不读 Windows 系统代理）；
或在该 profile 的 cordis.patch.yml 里把 plugin-manager 的 githubConnectionTimeoutMs 调大后重启。
字幕抓取失败（证书 / 代理）？
插件不会关闭证书校验，按 certifi → 随包 cacert.pem → 系统根证书三级回落，
错误里会给出当前信任库、CA 张数与代理设置。详见 SECURITY.md。
隐私与安全
- Cookie 不是工具参数：投影 / 视频直链 / 读 Cookie 工具都不接受 cookie 参数； 登录态只能由本地配置或本机 Edge 提供。
- Cookie 不回显、不落盘：读 Cookie 只返回名称、数量、长度与来源类别， 所有输出经过 redactor；必须复制 Edge 数据库时用 0600 临时文件，读完覆写并删除。
- 网络边界：只允许
classroom.zju.edu.cn与https://*.zju.edu.cn截图主机，跨域重定向拒绝； 证书校验不降级，只有瞬时故障才重试。 - 本地文件有边界：课件 / 讲义工具只接受指定扩展名，拒绝凭据、私钥与浏览器数据。
- 可机器验证：
python tools/privacy_scan.py扫描工作区、git 历史与 npm 产物。
完整威胁模型见 SECURITY.md，实现细节见 技术细节。
许可与致谢
本插件以 MIT 许可证发布，改编自 nzw806/zju-lecture-summerizer-（MIT），
原项目的版权声明保留在 LICENSE。
PDF 排版的上游模板（特别感谢）：
@preview/scholia0.1.0（MIT，© Eric Yang / 杨星宇， 仓库Eryc123Y/scholia）：基于 Typst scholia 模板 排版的填空式学习笔记的排版引擎（knot / note / 边注 / 封面 / 淡彩主题）；配色与段落规范 由本项目定义，见 scholia-notes 规范。 **该包及其依赖已随本仓库分发（vendored）**在zju_lecture/typst-packages/，使填空笔记编译 不再依赖 Typst 包注册表；逐包保留上游LICENSE/UNLICENSE与typst.toml，删除 README 与模板示例，并对src/fonts.typ/src/lib.typ打了补丁（见VENDORED.md）。 本插件的阅读版讲义 PDF 使用自研模板（zju_lecture/handout_prelude.typ）， 视觉设计参考了它的浅色 notes 主题，未拷贝其源码。@preview/frame-it（MIT，© Marc Thieme）、@preview/marginalia（UNLICENSE）、@preview/theoretic（UNLICENSE）、@preview/showybox（MIT）与@preview/noteworthy（MIT）：scholia 的传递依赖， 同样随包分发，版本与许可见VENDORED.md。- 上游 scholia 声明自己是受
loom-notes设计启发的独立重写（XeLaTeX，MIT，未复用源码）；本仓库也未分发它。 - 「scholia」一词仅用于指代所依赖的 Typst 包；本插件与 Eric Yang 无隶属关系，也未获其背书。 逐条归属与「未拷贝代码」边界见 ATTRIBUTION.md 与 THIRD_PARTY_NOTICES.md。
随包中文字体：zju_lecture/fonts/NotesKaiSC-Subset.ttf 是
LXGW WenKai（霞鹜文楷）v1.530 的 GB2312 子集，
NotesSerifSC-Subset.ttf 是 Noto Serif SC
的 GB2312 子集，均为 SIL OFL 1.1；两个字体都已改名以免与本机完整字体冲突。
OFL.txt / OFL-Kai.txt 与 FONT-NOTICE.md 必须随字体一起分发。
其他项目：
PeiPei233/zju-learning-assistant（ZLA，MIT）： 智云课堂 / 学在浙大 API 流程的原始实现，本插件与参考 CLI 的共同上游。8eoyw/zju-learning-cli（MIT）：投影 PPT 管线的参考 （_token→ Bearer、分页去重、截图合成 PDF），本仓库按零第三方依赖重新实现，未拷贝代码。- Typst（Apache-2.0）：两条 PDF 链路的排版编译器。插件不分发 Typst 二进制： 缺少时从官方 GitHub Release 下载到用户缓存目录，按仓库内固定的 SHA256 校验后再使用。
certifi与 Mozilla CA 证书库：随包cacert.pem的来源。- 以及为本插件提交 issue、做实地运行反馈、审查代码与文档的同学。
文档
| 文档 | 内容 |
|---|---|
| docs/technical.md | 技术细节：目录结构、隐私实现、PDF 排版、标记语法、开发测试、发布流程 |
| CHANGELOG.md | 版本历史（2.1.0 → 1.4.0） |
| SECURITY.md | 威胁模型、Cookie 生命周期、已知边界 |
| ATTRIBUTION.md | 逐文件来源、第三方许可、参考实现边界 |
| format-spec.md | 规范性文件：Markdown → PDF 装置的语义对应、预算、配色与字体 |
仅供个人学习使用：只抓取本人有权限访问的回放，Cookie 属个人凭证，不要外传。