dsh-zju-lecture-note 2.1.0 → 2.2.4

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 (47) hide show
  1. package/ATTRIBUTION.md +20 -12
  2. package/CHANGELOG.md +204 -0
  3. package/README.md +299 -274
  4. package/docs/technical.md +118 -57
  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 +62 -48
  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 +116 -106
  16. package/skills/scholia-notes/references/prelude.typ +51 -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 +45 -10
  23. package/skills/zju-lecture-summarizer.manifest.json +4 -4
  24. package/zju_lecture/client.py +741 -741
  25. package/zju_lecture/fonts/FONT-NOTICE.md +24 -17
  26. package/zju_lecture/fonts/NotesKaiSC-Subset.ttf +0 -0
  27. package/zju_lecture/fonts/OFL-Kai.txt +94 -0
  28. package/zju_lecture/handout.py +390 -93
  29. package/zju_lecture/handout_prelude.typ +85 -32
  30. package/zju_lecture/note_lint.py +88 -2
  31. package/zju_lecture/prelude.typ +51 -0
  32. package/zju_lecture/study_notes.py +852 -115
  33. package/zju_lecture/typst-packages/VENDORED.md +11 -2
  34. package/zju_lecture/typst-packages/preview/noteworthy/0.4.0/LICENSE +20 -20
  35. package/zju_lecture/typst-packages/preview/noteworthy/0.4.0/lib.typ +128 -128
  36. package/zju_lecture/typst-packages/preview/noteworthy/0.4.0/typst.toml +15 -15
  37. package/zju_lecture/typst-packages/preview/scholia/0.1.0/src/fonts.typ +16 -4
  38. package/zju_lecture/typst-packages/preview/scholia/0.1.0/src/lib.typ +7 -7
  39. package/zju_lecture/typst-packages/preview/scholia/0.1.0/src/theorems.typ +2 -2
  40. package/zju_lecture/typst-packages/preview/showybox/2.0.4/LICENSE +21 -21
  41. package/zju_lecture/typst-packages/preview/showybox/2.0.4/lib/func.typ +142 -142
  42. package/zju_lecture/typst-packages/preview/showybox/2.0.4/lib/id.typ +11 -11
  43. package/zju_lecture/typst-packages/preview/showybox/2.0.4/lib/pre-rendering.typ +50 -50
  44. package/zju_lecture/typst-packages/preview/showybox/2.0.4/lib/sections.typ +141 -141
  45. package/zju_lecture/typst-packages/preview/showybox/2.0.4/lib/shadows.typ +118 -118
  46. package/zju_lecture/typst-packages/preview/showybox/2.0.4/showy.typ +267 -267
  47. package/zju_lecture/typst-packages/preview/showybox/2.0.4/typst.toml +11 -11
package/docs/technical.md CHANGED
@@ -15,7 +15,7 @@ dsh-zju-lecture-note/
15
15
  ├── lib/ # dsh 插件实现(ESM)
16
16
  │ ├── index.js # 插件入口:按开关注册工具 + 内存注册随包 Skill
17
17
  │ ├── bridge.js # 拉起随包 Python 核心(JSON-RPC over stdio)
18
- │ ├── client.js # 浏览器半边:设置页「浙大智云课堂讲义」
18
+ │ ├── client.js # 浏览器半边:设置页 + 左栏「智云讲义」入口
19
19
  │ ├── tools.js # 生成物:dsh 工具定义
20
20
  │ └── tools.schema.json # 生成物:工具定义快照(供测试比对)
21
21
  ├── .minimax-plugin/plugin.json # MiniMax Code(MCode)插件清单
@@ -66,7 +66,8 @@ dsh-zju-lecture-note/
66
66
  →(可选)zju_extract_courseware(本地课件校准术语)
67
67
  → Agent 写 Markdown
68
68
  → zju_write_note:命名 → 修公式 → 校验 → 写文件 → 排版同名 PDF
69
- →(可选)zju_build_study_notes:讲义 → 填空底稿 → scholia PDF + 逐页 PNG
69
+ →(可选)zju_build_study_notes:讲义 →(draft)填空底稿 →(patch,一次写回挖空)
70
+ →(compile)scholia PDF + 逐页 PNG
70
71
  ```
71
72
 
72
73
  ## 2. 安装形态与依赖
@@ -124,6 +125,23 @@ PATH 上的 `python3` / `python` / `py -3`。
124
125
  必须**完全重启 DeepSeek Harness**;可在 `cordis_inspect_query` 的 `Slots` →
125
126
  `factory:dsh-zju-lecture-note` / `settings.section` 验证。
126
127
 
128
+ **浏览器半边的两个席位(同一份配置)**:`lib/client.js` 只创建一个 `PipelineSettings`
129
+ 控制器、一个 `PipelineSection` 组件,然后从两个席位挂同一个页面:
130
+
131
+ | 席位 | 位置 | 注册 |
132
+ | :--- | :--- | :--- |
133
+ | `settings.section` | 设置弹窗的左栏「浙大智云课堂讲义」 | `id: PANEL_ID`、`order: 25` |
134
+ | `sidebar.panellist` + `main` | 主界面左栏「智云讲义」一行,点开在主区域显示同一页 | 行 `id` 与面板 `key` 都取 `PANEL_ID` |
135
+
136
+ - 侧边栏按 id 调 `ctx.layout.selectPanel(id)`,所以**行的 `id` 与 `main` 的 `key` 必须一致**;
137
+ 两处都引用同一个 `PANEL_ID = 'zju-lecture'` 常量,不要写死两份字符串。
138
+ - 两个席位嵌套注册(`main` 外层、`sidebar.panellist` 内层),任一侧失败都不会留下半套入口。
139
+ - `sidebar.panellist` 没有图标字段:注册项自己画 SVG,用 `currentColor` 才能跟随行的
140
+ 悬停/选中颜色;`label` 是 thunk,跟随语言切换。
141
+ - `main` 占的是整列页面,页首要用 `calc(20px + var(--dsh-frame-top-clearance, 0px))` 留出
142
+ 窗口标题栏的高度,否则 Windows 上第一行会被标题栏压住。
143
+ - 面板页把标题渲染成 `h1`(`asPage`),设置弹窗里仍是 `h2`(弹窗自己提供标题)。
144
+
127
145
  ## 3. 工具与开关分层
128
146
 
129
147
  v2.0.1 起,「字幕 → 讲义 → PDF」主链路与所有可选能力解耦。每个模块有自己的工具、
@@ -131,14 +149,18 @@ Skill 附录和系统提示;关掉就**不存在**,不占工具列表、不
131
149
 
132
150
  | 分层 | 工具 | 依赖 | 默认 |
133
151
  | :--- | :--- | :--- | :--- |
134
- | **字幕主链路** | `zju_parse_url` / `zju_fetch_transcript` / `zju_extract_courseware` / `zju_check_note` / `zju_write_note`(含自动 PDF) | 公开字幕接口 + 本地文件 + 可选 Typst | 始终开启 |
152
+ | **字幕主链路** | `zju_parse_url` / `zju_fetch_transcript` / `zju_extract_courseware` / `zju_check_note` / `zju_write_note`(含自动 PDF) / `zju_doctor` | 公开字幕接口 + 本地文件 + 可选 Typst | 始终开启 |
135
153
  | **填空笔记** | `zju_build_study_notes` + `scholia-notes` Skill | 本机 Typst | 关闭(`enableStudyNotes`) |
136
154
  | **投影抓取** | `zju_fetch_slides` | 登录态 + 截图下载 + PDF 合成 | 关闭(`enableSlides`) |
137
155
  | **投影插图** | (`zju_fetch_slides` 的子开关) | 依赖投影抓取 | 关闭(`embedSlideImages`) |
138
156
  | **登录辅助** | `zju_get_video_url` / `zju_read_browser_cookie` | 本机 Edge 或 `ZJU_COOKIE` / `ZJU_COOKIE_FILE` | 关闭(`enableLoginTools`) |
139
157
 
140
- - dsh 默认注册 **5** 个工具;`enableStudyNotes` +1、`enableSlides` +1、`enableLoginTools` +2,
141
- 全开 **9** 个。
158
+ - dsh 默认注册 **6** 个工具;`enableStudyNotes` +1、`enableSlides` +1、`enableLoginTools` +2,
159
+ 全开 **10** 个。
160
+ - **`.volatile()` 字段是引用,不是布尔值**:dsh 把它们投影成 `{ get() }`,供插件在设置改动后
161
+ 读取新值。`lib/index.js` 的 `readSetting()` 统一解包;直接写 `config.enableSlides === true`
162
+ 会永远得到 `false`——2.1.1 修的「设置全开仍只有字幕」就是这个原因。新增设置项时务必走
163
+ `readSetting()`,并补一条 ref 形状的测试。
142
164
  - MCP 未设置新变量时保持旧行为(10 个);仓库自带的 `zju-lecture.mcp.json` 默认关掉三个可选模块(6 个)。
143
165
  - 关闭时:不注册对应工具、不加载对应模块、Skill 不追加对应附录;系统提示会说明
144
166
  「这个模块已关闭」,Agent 不会调用或假装调用。
@@ -196,30 +218,66 @@ Skill 附录和系统提示;关掉就**不存在**,不占工具列表、不
196
218
  不导出逐页 PNG——只有填空笔记需要。
197
219
  - **版式**:封面(标题 / 副题 / 日期)、目录(≥3 节时)、标题层级、正文、列表、三线表、
198
220
  公式、代码、引用、工作区图片。
199
- - 版心不对称:左 2.4cm / 右 3.9cm,右侧 2.6cm 是边注栏;封面与目录不占页码,正文第一页从 1 起。
200
- - 一级标题:灰蓝编号 + 蓝色标题 + 1.1pt 细线;方框淡彩底 + 左侧 2.2pt 竖线、无圆角;
201
- 证明以斜体 `Proof.` + 行末 qed。
202
- - 正文参数:`leading 0.72em`、`spacing 0.95em`、段首 `#h(2em)` 顶首行、公式块 `1.6em`。
221
+ - 版心、封面、边注栏、字号等**数值**统一见
222
+ [`typography-spec.md`](../skills/scholia-notes/references/typography-spec.md);
223
+ 本节只保留机制。
224
+ - 一级标题:灰蓝编号 + 蓝色标题 + 细线;方框淡彩底 + 左侧竖线、无圆角;
225
+ 证明以斜体 `Proof.` + **块末** qed(方块落在证明最后一行,不是第一行)。
226
+ - 各级标题后的间距自 2.2.2 起加大(用户在实地会话里要求「小节标题后的行间距
227
+ 适当大一些」);2.2.4 又把**上方**留白拉开(节标题 12pt → 22pt、章标题 20pt → 24pt),
228
+ 否则绿色小节标题紧贴上一段、看不出新节从哪里开始。具体值见规范 §2;两条链路同步改。
203
229
  - `par.first-line-indent` **不可靠**:它只在「前一个兄弟元素是段落」时生效,
204
- 标题 / 块 / 图 / 公式后的段落一律不缩进 ⇒ 改用行内 `#h(2em)`。
230
+ 标题 / 块 / 图 / 公式后的段落一律不缩进 ⇒ 正文改用行内 `#h(2em)` 顶首行;
231
+ 直觉块不缩进(块自身的左内边距已经分开)。
205
232
  - 块级公式的上下间距吃 `par.spacing`,压段间距会把公式压到下一段上 ⇒ 用
206
- `#show math.equation.where(block: true): set block(above: 1.6em, below: 1.6em)` 解耦。
207
- - 边注用 `box(width: 0pt, context { let p = here().position(); place(top + left, dx: page.width - p.x - 2.6cm - 0.6cm, …) })`:
208
- 直接 `context` + `place(top + right)` 会把边注甩到页面顶端。
233
+ `#show math.equation.where(block: true): set block(above: …, below: …)` 解耦
234
+ (数值见规范)。
235
+ - 行内公式的墨迹会溢出「行盒」:Typst 的行内数学盒子高度是**固定值**(11pt 下
236
+ ≈0.68em,`measure($frac(1,2)$)` 与 `measure($x$)` 都是 7.51pt),分式的分子/分母、
237
+ 大算子的上下限压到邻行上。解决办法是两处**显式**留白:模板里的
238
+ `#show math.equation.where(block: false): it => box(inset: (top: …, bottom: …), it)`
239
+ 给每个行内公式补一点;`study_notes.pad_inline_math()` 再给分式/根式/矩阵/大算子
240
+ 这类「结构上会撑高」的公式包一层 `#box(inset: (bottom: …))`。只按最大值统一给会把
241
+ 只有 `$x$` 的行也撑松,所以按结构分级(数值与实测见规范 §3.2)。
242
+ - 边注用 `box(width: 0pt, context { let p = here().position(); place(top + left, dx: page.width - p.x - note-width - right-pad, …) })`:
243
+ `note-width` / `right-pad` 的数值见规范;直接 `context` + `place(top + right)`
244
+ 会把边注甩到页面顶端。
209
245
  - **标记语法**(转义前处理;`____` 先于转义,否则会被变成 `#fillin` 后漏掉):
210
246
 
211
247
  | 标记 | 装置 |
212
248
  | :--- | :--- |
213
249
  | `[直觉]` | `#note`(青绿淡底) |
214
- | `[定义] 标题 —— 正文` / `[定理]` / `[命题]` / `[例]` | 带标签的方框 |
215
- | `[证明]` | 斜体 `Proof.` + qed |
250
+ | `[定义] 标题 —— 正文` / `[定理]` / `[命题]` / `[例]` | 带标签的方框(**跨段**) |
251
+ | `[证明]` | 斜体 `Proof.` + **块末** qed(**跨段**) |
216
252
  | `[练习]` | `#yourturn` + 3 行 `#workspace(n: 3)`(练习块里的短 `____` 一律丢弃) |
217
253
  | `[边注]` / `[边注!]` | 右侧留白边注(`[边注!]` 带强调) |
218
254
  | `[强调]` / `[易错]` / `[弱注]` / `[分隔]` | 行内高亮 / 提示 / 弱化 / 分隔线 |
255
+ | `---`(独占一行) | 同 `[分隔]` 的细分隔线(不再被智能标点排成孤立「–」) |
219
256
  | `____` | `#fillin(width: 2.2cm)`(灰色,提示留给读者写) |
220
257
  | `[缺口: …]` | `#gap` 留白 |
221
258
  | `<label>` / `@label` | 两遍扫描后生成原生交叉引用 |
222
259
 
260
+ **标记块的边界**:框类装置与 `[证明]` 是「块」而不是「一行」——从标记行一直收到
261
+ 下一个标记行 / 标题 / 整行粗体的伪标题(`**周期函数的处理** \`[00:22]\``)。
262
+ 块内的空行是段落分隔,`$$…$$`、列表、表格都留在装置里;`_render_block_sequence()`
263
+ 负责把它们排成装置内容(块内段落不加 `#h(2em)`)。单段装置(`[直觉]` / `[练习]` /
264
+ `[边注]` / `[强调]` …)仍只吃标记行那一句。
265
+ 这条规则同时修掉两个实地问题:定理陈述里的块级公式被甩到框外;`[证明]` 遇到空行就
266
+ 收尾,qed 方块停在一两行之后,读起来像「证明到这就结束了」。两条链路(
267
+ `handout.py` 与 `study_notes.py`)用同一套口径;块内段落仍计入「方框:正文」的分母,
268
+ 避免比例检查误报。
269
+
270
+ 块内正文在「题目 / 切入点 / 关键步骤 / 易错点」四个标签紧跟句末标点
271
+ (`。!?;`)时自动断段(`study_notes.split_review_labels()`):模型常把复习版例题的
272
+ 四段写进同一行,不断段的话框里就是一大坨(实地讲义实测)。
273
+
274
+ **自测题**(`**1.** 题干` + `<details><summary>答案</summary>…</details>`)在两条链路里
275
+ 分别排成 `#selftest`(琥珀框,标签「自测题 n」,手写的 `**1.**` 编号交给标签)与
276
+ `#answer`(框外,淡灰左线 + 「答案」标签)。题干是紧挨 `<details>` 的那一段;
277
+ `<summary>` 的文字当标签。这样题目与答案之间有一道清楚的边界,也不会再把
278
+ `<details>` 印成字面量(填空链路以前会)。两个装置分别定义在 `handout_prelude.typ`
279
+ 与 `zju_lecture/prelude.typ`。
280
+
223
281
  标题手写的编号(`1.` / `1.2` / `一、` / `(三)`)**一律剥掉**,编号只由 Typst 生成。
224
282
  - **数学**:与填空笔记共用 `study_notes.latex_to_typst`:`pmatrix` / `bmatrix` / `cases` / `aligned`
225
283
  机械转成 `mat` / `cases` / 对齐换行;多字母标识符(`AC`、`e^{-st}`、`BVP`)按规则转成
@@ -229,59 +287,47 @@ Skill 附录和系统提示;关掉就**不存在**,不占工具列表、不
229
287
 
230
288
  ### 配色
231
289
 
232
- 浅色 `soft-palette` 的**唯一权威来源**是 `zju_lecture/prelude.typ`:
233
-
234
- | role | 色值 | 对比度(对 `bg`) |
235
- | :--- | :--- | :--- |
236
- | `bg` | `#FDFDFB` | 1.00 |
237
- | `ink` | `#1A1A1C` | 17.06 |
238
- | `thm` | `#33609B` | 6.27 |
239
- | `def` / `tag` / `keyword` | `#20705F` | 5.82 |
240
- | `eg` | `#8F6218` | 5.25 |
241
- | `warn` | `#6350A8` | 6.36 |
242
- | `muted` | `#6F7683` | 4.49 |
243
- | `fillin` | `#8E97A3` | 2.90 |
244
- | `rule` | `#93A6C4` | 2.43 |
245
- | `hairline` | `#DBDFE6` | 1.31 |
290
+ 浅色 `soft-palette` 的**唯一权威来源**是 `zju_lecture/prelude.typ`;完整色表、
291
+ 对比度与「极差 1.11 是刻度跨度」的口径见
292
+ [`typography-spec.md`](../skills/scholia-notes/references/typography-spec.md) §7。
293
+ 这里只保留机制:
246
294
 
247
295
  - `handout_prelude.typ` 的 `#let palette` 与 `handout._PALETTE` 是**生成副本**:
248
296
  改色只改 `prelude.typ`,再跑 `python tools/sync_palette.py`,
249
297
  `--check` 校验三处逐角色一致(`tests/test_palette_sync.py` 也会跑)。
250
298
  - 页面 `fill: palette.bg`;`handout._tint` 混向 `bg` 而不是纯白,才与 Typst `tint()` 同算法。
251
299
  - 深色主题(slate)由上游 scholia 自带,本项目不注入 `use-palette`。
252
- - 「极差 1.11」是四个强调色在对比度刻度上的**跨度**(6.36 − 5.25),不是比值;目标 ≤ 1.2。
253
300
 
254
301
  ### 字体与可再分发性
255
302
 
256
- Typst 会把用到的字体子集内嵌进 PDF。两条 PDF 链路都优先使用**随包自带的 OFL 字体**:
257
-
258
- | role | 首选 | 回退 |
259
- | :--- | :--- | :--- |
260
- | body / heading | `STIX Two Text`(SIL OFL) | Typst 内嵌 `Libertinus Serif` |
261
- | math | `STIX Two Math` | `New Computer Modern Math` |
262
- | mono | `DejaVu Sans Mono` | `Consolas` |
263
- | 中文 | **`Notes Serif SC`(随包,OFL 子集)** | `Noto Serif SC` / `Source Han Serif SC`(OFL)→ `Songti SC` / `SimSun` |
264
-
265
- - `Notes Serif SC` 是 Noto Serif SC 的 GB2312 子集 + 常用符号(约 7.5k 字,5.7 MB),**保留了
266
- `wght` 变量轴**,所以标题的 `weight: "bold"` 有真正的粗体面;生僻字逐字回退到系统字体。
267
- - **改名是刻意的**:与用户本机完整版同名时 Typst 选哪个字体面不确定,也避免让人误以为是完整字体、
268
- 避开 Noto / Source / ZJU 商标。
269
- - 许可是 SIL OFL 1.1(无 Reserved Font Name):允许子集化与再分发,但必须随附 `OFL.txt` 与版权声明,
270
- 衍生字体继续以 OFL 分发,且不得单独售卖字体。相关文件在 `zju_lecture/fonts/`。
271
- - `Optima` / `Avenir Next` / `Menlo` 等专有字体**不在生效的字体栈里**,只以注释形式留在模板中
272
- 供本机还原上游观感;那种 PDF 不要再分发。
273
- - 填空笔记通过 `fonts: (cjk: (...))` 把随包字体插到首位;上游包的 `note` / `sidenote` / `label-it`
274
- 仍直接读包内字体表,改不到(已知限制)。
275
- - 对外分发 PDF 前用 `pdffonts out.pdf` 核对一次:若出现 `SimSun` / `Microsoft YaHei` 等系统商业字体,
276
- 说明生僻字回退到了它们,换一份完整 OFL 字体再排。
303
+ 完整的角色、回退链与许可列见
304
+ [`typography-spec.md`](../skills/scholia-notes/references/typography-spec.md) §1。
305
+ 这里只保留机制:
306
+
307
+ - 两条链路默认都只用可再分发字体:STIX Two / Libertinus / 随包 `Notes Kai SC` 与
308
+ `Notes Serif SC` / Noto / Source Han / DejaVu;商业字体不在生效栈里。
309
+ - `Notes Kai SC` 是 LXGW WenKai 的 GB2312 子集(OFL,上游有 Reserved Font Name,
310
+ 因此**改名**);`Notes Serif SC` 是 Noto Serif SC 的子集(OFL)。两者都随附
311
+ `OFL*.txt` 与 `FONT-NOTICE.md`。
312
+ - 填空笔记的 vendored `scholia` 已 patch `src/fonts.typ` 的 `default-fonts`,
313
+ 所以 `note` / `sidenote` / `label-it` 也跟随同一套字体;补丁由
314
+ `tools/vendor_typst_packages.py` 重放,记录在 `VENDORED.md`。
315
+ - 对外分发 PDF 前用 `pdffonts out.pdf` 核对一次:若出现 `Optima` / `Avenir Next` /
316
+ `Menlo` / `Songti SC` / `SimSun` / `Microsoft YaHei`,说明命中了系统商业字体,
317
+ 换一份完整 OFL 字体再排。
277
318
 
278
319
  ## 6. 填空笔记链路
279
320
 
280
321
  `zju_lecture/study_notes.py` 负责两段:
281
322
 
282
- - `mode=draft`:讲义 → 填空底稿(标题层级映射、标记位插入、LaTeX 数学 → Typst 数学)。
283
- 标记位只插 `[直觉]` / `[练习]` / `[边注]`——`[定义]` / `[定理]` / `[证明]` 该不该用是内容判断,
284
- 骨架不替使用者决定。
323
+ - `mode=draft`:讲义 → 填空底稿(标题层级映射、正文原样搬运)。
324
+ 骨架**不再逐节插 `[直觉]` / `[练习]` / `[边注]` 空占位**:文件头只有一条 HTML 注释
325
+ 说明这些装置可选,加不加、加在哪儿由内容判断。**公式、表格、列表、行内代码都原样保留成 Markdown**:
326
+ 底稿是给人/模型改的,转换只在 `mode=compile` 做一次。
327
+ - `mode=patch`:按 `edits=[{old, new}, …]` 一次写回底稿,逐条报告命中/未命中。
328
+ 挖空是十几处精确替换,逐条调用编辑工具就是十几次往返(实地会话 35 步里有 12 步
329
+ 花在这上面);这里是同一批修改的一次提交。`old` 默认必须唯一命中,重复时加
330
+ `"all": true` 或加长上下文。
285
331
  - `mode=compile`:底稿 → `main.typ` + `prelude.typ` → `out.pdf` + 逐页 `page-N.png`,
286
332
  并报告编译错误、方框预算与悬空回指。
287
333
 
@@ -289,8 +335,21 @@ Typst 会把用到的字体子集内嵌进 PDF。两条 PDF 链路都优先使
289
335
 
290
336
  - 骨架**不会**替使用者插 `[定义]/[定理]/[证明]`——那三个框该不该用是内容判断。
291
337
  - 底稿可以写 `<!-- … -->` 注释,转成 Typst 块注释,不渲染、也不计进正文段落。
292
- - 数学转换是**幂等**的(`_looks_like_typst_math`):`build_draft` 转一次、`render_typst` 再转一次
293
- 不会把 `sum` 拆成 `s u m`。
338
+ - 数学转换是**幂等**的:`_plain_word` 认识转换器自己会产出的名字(`frac` / `cal` / `sum` /
339
+ `quad` / `wide` / `slash` / `"Res"` …),所以 `latex_to_typst(latex_to_typst(x)) == latex_to_typst(x)`,
340
+ 不会被拆成 `s u m` / `f r a c`。引号串(`"Res"`)原样搬运,不再被二次加工。
341
+ - 间距命令走 Typst 的真实间距:`\quad` → `quad`(1em)、`\qquad` → `wide`(2em)、
342
+ `\,` → `thin`、`\;` → `med`。早先映射成空格,而 Typst 会折叠连续空格,
343
+ 于是「并排的两条公式」粘成 `0∇×H`(实地会话里 Agent 只能写脚本拆公式块)。
344
+ - 行内数学(`inline=True`)把 `/` 排成平排的 `slash`,块级公式仍排上下分式:
345
+ `$1/r$` 不再把行距顶高,不必手改成 `r^{-1}`。
346
+ - Markdown 的 `>` 引用块 → `#quoted[…]`(左侧细线 + 灰色小字)。Typst **没有** `>`
347
+ 引用语法,旧实现把 `>` 原样印进 PDF;多条 `> **字段**:…` 按行换行,不再粘成一句。
348
+ - 方框预算按**最小**小节统计:`## 二、分章详解` 下挂 7 个 `### 2.x` 时逐 `2.x` 计数,
349
+ 不会把整章的框算到同一节。
350
+ - GFM 表格 / `- ` 与 `1.` 列表 / 行内反引号在 `render_typst` 里有对应分支:表格 → `#table(…)`、
351
+ 列表 → Typst 列表、反引号 → raw(内容不转义)。以前表格只在 `build_draft` 转、`render_typst`
352
+ 不认,底稿里的 `#table(…)` 会被当正文转义成 `\[a\]`。
294
353
  - Typst markup 里 `_` / `\` / `[` / `#` / `@` 都要转义;转义顺序**先 `\` 再 `_`**,
295
354
  否则 `_` 刚加的反斜杠会被二次转义。
296
355
  - `dz` / `dx` 按微分约定拆成 `d z` / `d x`;`diag` 这类单词不拆。
@@ -502,7 +561,9 @@ PY
502
561
 
503
562
  其中与 PDF 模板直接相关的:
504
563
 
505
- - `@preview/scholia` 0.1.0(MIT,© Eric Yang)是填空笔记链路的排版引擎,
564
+ - `@preview/scholia` 0.1.0(MIT,© Eric Yang)是**基于 Typst scholia 模板排版的
565
+ 填空式学习笔记**的排版引擎;配色与段落规范由本项目定义,见 scholia-notes 规范
566
+ (`skills/scholia-notes/references/typography-spec.md`)。
506
567
  **已随本仓库分发(vendored)**在 `zju_lecture/typst-packages/`,逐包保留上游许可与 `typst.toml`;
507
568
  - 其余传递依赖(frame-it / marginalia / theoretic / showybox / noteworthy)同样随包分发,
508
569
  版本与许可见 `zju_lecture/typst-packages/VENDORED.md`;
package/lib/client.js CHANGED
@@ -1,10 +1,18 @@
1
1
  /**
2
2
  * Browser half of dsh-zju-lecture-note.
3
3
  *
4
- * One Settings section, not a row buried in General. The page is built around
5
- * the actual pipeline — 字幕 → 讲义 → PDF — and every optional module is a
6
- * separate switch with its own dependency and cost, so a user can see what
7
- * they are turning on before they turn it on.
4
+ * The same page is mounted twice, from two seats the shell owns:
5
+ *
6
+ * - `settings.section` — 设置 → 浙大智云课堂讲义 (the deep link), id `zju-lecture`;
7
+ * - `sidebar.panellist` + `main` — the left-column row 智云讲义, whose click
8
+ * selects the global panel registered under the same id.
9
+ *
10
+ * Both render one component over one `PipelineSettings` controller, so a switch
11
+ * moved in either place shows up in the other without a reload.
12
+ *
13
+ * The page is built around the actual pipeline — 字幕 → 讲义 → PDF — and every
14
+ * optional module is a separate switch with its own dependency and cost, so a
15
+ * user can see what they are turning on before they turn it on.
8
16
  *
9
17
  * - `renderPdf` auto-typeset the written note into a reading PDF
10
18
  * - `enableStudyNotes` fill-in study notes (+ scholia-notes Skill)
@@ -25,6 +33,12 @@ window.__ModuleLoader__.load({
25
33
  const h = React.createElement
26
34
 
27
35
  const NS = 'dsh-zju-lecture-note'
36
+ /**
37
+ * One id for both left-column seats: `sidebar.panellist` renders the row,
38
+ * `main` renders the page the row opens. The sidebar dispatches
39
+ * `ctx.layout.selectPanel(id)`, so the two registrations must agree.
40
+ */
41
+ const PANEL_ID = 'zju-lecture'
28
42
  const CANDIDATE_NAMESPACES = [
29
43
  'include:dsh-zju-lecture-note',
30
44
  'dsh-zju-lecture-note',
@@ -34,6 +48,9 @@ window.__ModuleLoader__.load({
34
48
  sectionTitle: 'ZJU classroom lecture notes',
35
49
  sectionDescription:
36
50
  'One pipeline: transcript → notes → PDF. Optional modules register their tools only while switched on, so off means no extra tool, Skill or login surface.',
51
+ panelLabel: 'ZJU notes',
52
+ panelNote:
53
+ 'The same switches also live in Settings → ZJU classroom lecture notes.',
37
54
  eyebrow: 'ZJU · CLASSROOM',
38
55
  heroTitle: 'Turn a replay into notes you actually re-read',
39
56
  heroBody:
@@ -42,7 +59,7 @@ window.__ModuleLoader__.load({
42
59
  pipelineNotes: 'Markdown notes',
43
60
  pipelinePdf: 'Reading PDF',
44
61
  toolCountLabel: 'tools',
45
- toolsNowPrefix: 'This session registers',
62
+ toolsNowPrefix: 'This config registers',
46
63
  toolsNowSuffix: 'tools',
47
64
  pdfOn: 'PDF on',
48
65
  pdfOff: 'PDF off',
@@ -99,7 +116,7 @@ window.__ModuleLoader__.load({
99
116
  loginHint:
100
117
  'Registers zju_get_video_url and zju_read_browser_cookie. Never echoes a cookie.',
101
118
  toolsNowHint:
102
- 'Changes are written back immediately; the plugin reloads with the new configuration.',
119
+ 'Saved immediately, but loaded when DeepSeek Harness restarts: the running host keeps the tools it started with, and a new session inherits them.',
103
120
  saveIdle: '',
104
121
  saveSaving: 'Saving…',
105
122
  saveDone: 'Saved',
@@ -116,6 +133,8 @@ window.__ModuleLoader__.load({
116
133
  sectionTitle: '浙大智云课堂讲义',
117
134
  sectionDescription:
118
135
  '一条链路:字幕 → 讲义 → PDF。可选模块只在打开时注册对应工具;关掉就没有多余工具、Skill 与登录面。',
136
+ panelLabel: '智云讲义',
137
+ panelNote: '同一份开关也出现在「设置 → 浙大智云课堂讲义」。',
119
138
  eyebrow: 'ZJU · 智云课堂',
120
139
  heroTitle: '把一节回放,变成会重读的讲义',
121
140
  heroBody:
@@ -124,7 +143,7 @@ window.__ModuleLoader__.load({
124
143
  pipelineNotes: 'Markdown 讲义',
125
144
  pipelinePdf: '阅读 PDF',
126
145
  toolCountLabel: '个工具',
127
- toolsNowPrefix: '本次会话注册',
146
+ toolsNowPrefix: '当前配置注册',
128
147
  toolsNowSuffix: '个工具',
129
148
  pdfOn: 'PDF 开',
130
149
  pdfOff: 'PDF 关',
@@ -176,7 +195,7 @@ window.__ModuleLoader__.load({
176
195
  loginBody: '只在下载视频或 Whisper 重识别时需要;投影抓取不依赖它。',
177
196
  loginHint:
178
197
  '注册 zju_get_video_url 与 zju_read_browser_cookie;不会回显 Cookie。',
179
- toolsNowHint: '修改会立即写回,插件按新配置重新加载。',
198
+ toolsNowHint: '保存后立即写回,但插件要完全重启 DeepSeek Harness 才按新配置加载:当前会话和新建会话都沿用启动时的工具集。',
180
199
  saveIdle: '',
181
200
  saveSaving: '正在保存…',
182
201
  saveDone: '已保存',
@@ -233,6 +252,8 @@ window.__ModuleLoader__.load({
233
252
  '.zju-save[data-state="saved"]{color:var(--dsw-alias-state-success-primary)}',
234
253
  '.zju-save[data-state="failed"]{color:var(--dsw-alias-state-error-primary)}',
235
254
  '.zju-note{font-size:11px;line-height:17px;color:var(--dsw-alias-label-tertiary)}',
255
+ '.zju-panel{box-sizing:border-box;height:100%;overflow:auto;display:flex;justify-content:center;align-items:flex-start;padding:0 clamp(16px,3vw,32px) 40px}',
256
+ '.zju-panel-inner{box-sizing:border-box;width:100%;max-width:760px;padding-top:calc(20px + var(--dsh-frame-top-clearance,0px))}',
236
257
  '@media (max-width:560px){.zju-hero-top{flex-direction:column}.zju-hero-badges{justify-content:flex-start}.zju-row{gap:12px}}',
237
258
  ].join('\n')
238
259
 
@@ -454,7 +475,7 @@ window.__ModuleLoader__.load({
454
475
  )
455
476
  }
456
477
 
457
- function PipelineSection({ t, settings }) {
478
+ function PipelineSection({ t, settings, asPage }) {
458
479
  const snapshot = useSettingsSnapshot(settings)
459
480
  const [saveState, runSave] = useSaveState()
460
481
  const value = snapshot.value || {}
@@ -504,7 +525,7 @@ window.__ModuleLoader__.load({
504
525
  h('div', { className: 'zju-hero-top' },
505
526
  h('div', null,
506
527
  h('div', { className: 'zju-eyebrow' }, t('eyebrow')),
507
- h('h2', { className: 'zju-hero-title' }, t('heroTitle')),
528
+ h(asPage ? 'h1' : 'h2', { className: 'zju-hero-title' }, t('heroTitle')),
508
529
  h('p', { className: 'zju-hero-body' }, t('heroBody')),
509
530
  ),
510
531
  h('div', { className: 'zju-hero-badges' },
@@ -646,6 +667,48 @@ window.__ModuleLoader__.load({
646
667
  'aria-live': 'polite',
647
668
  }, saveLabel),
648
669
  ),
670
+ asPage ? h('p', { className: 'zju-note' }, t('panelNote')) : null,
671
+ )
672
+ }
673
+
674
+ /**
675
+ * The left-column row's glyph. A `sidebar.panellist` entry draws its own
676
+ * icon — the slot hands it `size` and `active`, no icon field exists — and
677
+ * the row's own colour must come through, hence `currentColor`.
678
+ */
679
+ function PanelIcon({ size = 18 }) {
680
+ return h('svg', {
681
+ width: size,
682
+ height: size,
683
+ viewBox: '0 0 20 20',
684
+ fill: 'none',
685
+ stroke: 'currentColor',
686
+ strokeWidth: 1.5,
687
+ strokeLinecap: 'round',
688
+ strokeLinejoin: 'round',
689
+ 'aria-hidden': 'true',
690
+ focusable: 'false',
691
+ },
692
+ h('path', { d: 'M4.6 3.4h6.1l4.7 4.7v7.5a1 1 0 0 1-1 1H4.6a1 1 0 0 1-1-1V4.4a1 1 0 0 1 1-1Z' }),
693
+ h('path', { d: 'M10.6 3.5v4.7h4.7' }),
694
+ h('path', { d: 'M6.7 11.2h4.4' }),
695
+ h('path', { d: 'M6.7 13.7h6.2' }),
696
+ )
697
+ }
698
+
699
+ /**
700
+ * The page behind the left-column row.
701
+ *
702
+ * A `main` occupant is a full-height centre column, so it owns the page
703
+ * padding the shipped entry pages use: `--dsh-frame-top-clearance` keeps the
704
+ * first row below the window caption on Windows and under the traffic lights
705
+ * on macOS. The content itself is the settings section, unchanged.
706
+ */
707
+ function SettingsPanelPage(props) {
708
+ return h('div', { className: 'zju-panel', 'data-zju-panel': PANEL_ID },
709
+ h('div', { className: 'zju-panel-inner' },
710
+ h(PipelineSection, { ...props, asPage: true }),
711
+ ),
649
712
  )
650
713
  }
651
714
 
@@ -656,12 +719,34 @@ window.__ModuleLoader__.load({
656
719
  ctx.effect(() => () => settings.dispose(), 'zju-lecture: settings form')
657
720
  ctx.effect(() => ctx.slots.inject('settings.section', () => ctx.slots.register({
658
721
  name: 'settings.section',
659
- id: 'zju-lecture',
722
+ id: PANEL_ID,
660
723
  order: 25,
661
724
  label: () => t('sectionTitle'),
662
725
  locale: NS,
663
726
  inject: () => ({ settings }),
664
727
  }, PipelineSection)), 'zju-lecture: settings section')
728
+ // The left column: one `sidebar.panellist` row and the `main` page under
729
+ // the same id. Registered from the inner callback so the row and its page
730
+ // appear together or not at all, exactly as the shipped panels do.
731
+ ctx.effect(() => ctx.slots.inject('main', () => ctx.slots.inject('sidebar.panellist', () => {
732
+ const stopPage = ctx.slots.register({
733
+ name: 'main',
734
+ key: PANEL_ID,
735
+ locale: NS,
736
+ inject: () => ({ settings }),
737
+ }, SettingsPanelPage)
738
+ const stopRow = ctx.slots.register({
739
+ name: 'sidebar.panellist',
740
+ id: PANEL_ID,
741
+ order: 30,
742
+ label: () => t('panelLabel'),
743
+ locale: NS,
744
+ }, PanelIcon)
745
+ return () => {
746
+ stopRow()
747
+ stopPage()
748
+ }
749
+ })), 'zju-lecture: sidebar entry')
665
750
  }
666
751
 
667
752
  return {
package/lib/index.js CHANGED
@@ -179,6 +179,32 @@ const SLIDE_TOOL_NAMES = new Set(["zju_fetch_slides"]);
179
179
  const STUDY_TOOL_NAMES = new Set(["zju_build_study_notes"]);
180
180
  const LOGIN_TOOL_NAMES = new Set(["zju_get_video_url", "zju_read_browser_cookie"]);
181
181
 
182
+ /**
183
+ * Read one plugin setting.
184
+ *
185
+ * dsh projects every `Config` field marked `.volatile()` as a live reference
186
+ * (`{ get() }`) instead of a primitive, so the plugin can follow settings
187
+ * edits without a restart. Comparing that reference to `true` is always
188
+ * false — which silently turned every optional module off no matter what the
189
+ * user saved. Unwrap defensively because the same object is also built by
190
+ * tests and direct callers as a plain value.
191
+ *
192
+ * @param {object} config plugin config (or `{}`)
193
+ * @param {string} key field name
194
+ * @returns {unknown} the current value, or `undefined`
195
+ */
196
+ function readSetting(config, key) {
197
+ const raw = config?.[key];
198
+ if (raw && typeof raw === "object" && typeof raw.get === "function") {
199
+ try {
200
+ return raw.get();
201
+ } catch {
202
+ return undefined;
203
+ }
204
+ }
205
+ return raw;
206
+ }
207
+
182
208
  /**
183
209
  * Normalise one configuration into the booleans the rest of the plugin uses.
184
210
  *
@@ -188,14 +214,15 @@ const LOGIN_TOOL_NAMES = new Set(["zju_get_video_url", "zju_read_browser_cookie"
188
214
  * unless explicitly on.
189
215
  */
190
216
  function featureFlags(config = {}) {
191
- const enableSlides = config.enableSlides === true;
217
+ const value = (key) => readSetting(config, key);
218
+ const enableSlides = value("enableSlides") === true;
192
219
  return {
193
- renderPdf: config.renderPdf !== false,
194
- enableStudyNotes: config.enableStudyNotes === true,
220
+ renderPdf: value("renderPdf") !== false,
221
+ enableStudyNotes: value("enableStudyNotes") === true,
195
222
  enableSlides,
196
- embedSlideImages: enableSlides && config.embedSlideImages === true,
197
- enableLoginTools: config.enableLoginTools === true,
198
- typstAutoInstall: config.typstAutoInstall !== false,
223
+ embedSlideImages: enableSlides && value("embedSlideImages") === true,
224
+ enableLoginTools: value("enableLoginTools") === true,
225
+ typstAutoInstall: value("typstAutoInstall") !== false,
199
226
  };
200
227
  }
201
228
 
@@ -221,6 +248,10 @@ const COMPILE_TOOL_TIMEOUT_MS = 300000;
221
248
  const SYSTEM_PROMPT = [
222
249
  "适用范围:仅处理浙大智云课堂(classroom.zju.edu.cn)回放与讲义任务;其他任务请忽略本段。",
223
250
  "主链路:把链接或 sub_id 直接交给 zju_fetch_transcript(默认 per_minute;长课 chunked;同一节课只抓一次,per_segment 仅在确实需要秒级时间戳时用)→ 可选 zju_extract_courseware → zju_write_note 一次写入。write_note 会自动命名、拒绝静默覆盖、修公式、校验,并按设置自动排版同名 PDF;不要再调 zju_parse_url,也不要对同一份讲义重复调 zju_check_note。",
251
+ "讲义默认按「复习版」写:每节保留 [HH:MM];老师讲过的例题整理成「题目 → 切入点 → 关键步骤 → 易错点」,本节没有例题就写「本节无例题」,不要编题;文末给 3–5 道自测题(答案用多行 <details> 折叠)与 5–10 条考点预测。",
252
+ "例题/定理/定义/证明要写成行首标记([例] 标题 —— 正文 / [定理] … / [定义] … / [证明] …),"
253
+ + "不要写成 `#### 例 1:…` 或 `**证明**`——那种写法在 PDF 里只是小标题和粗体,排不出方框(工具会报 pseudo_box 警告)。",
254
+ "用户只说「整理这节课」时按完整链路一次做完,不要只交字幕摘要;只有明确说「只要速记 / 只要 Markdown」时才省略这些增强内容。",
224
255
  "ASR 可靠度低时按 Skill 的数学规范复算,并在讲义开头写明需要人工复核的时间点;公式必须符合 Skill 的「公式书写规范」。",
225
256
  "交付时给出 Markdown 路径;有 PDF 时一并给出 PDF 路径。不要声称看过自己无法查看的图片。",
226
257
  "隐私边界:登录 Cookie 只在 Python 进程内存里,工具不接受、也不回显 Cookie 明文;不要向用户索要 Cookie,或把它写进对话、文件、命令。",
@@ -234,13 +265,13 @@ const SYSTEM_PROMPT = [
234
265
  */
235
266
  function slideImageRule(enabled) {
236
267
  return enabled
237
- ? "讲义插图模式已开启:需要投影画面时调用 zju_fetch_slides(download=true),"
268
+ ? "讲义插图模式已开启:写讲义前默认抓一次投影(整节课只抓一次),"
238
269
  + "从返回的截图里挑 3–8 张关键页(定义、示意图、公式推导、例题),"
239
270
  + "按讲义所在目录的相对路径插入 Markdown(例如 ![第 12 页](../ppt-assets/<sub_id>/images/slide-0012.jpg));"
240
271
  + "如果宿主不能查看本地图片,不要把截图当作已读文字,只在文末列出截图索引。"
241
- + "整节课只下载一次,不要一次塞入全部截图或图片字节。"
242
- : "讲义插图模式关闭(默认,节省下载时间与 token):不要主动调用 zju_fetch_slides(download=true),"
243
- + "也不要插入截图;用户明确要求时再按需下载并在文末放截图索引。";
272
+ + "用户明确说不要投影时才跳过;不要一次塞入全部截图或图片字节。"
273
+ : "讲义插图模式关闭(默认,节省下载时间与 token):不要主动下载或插入截图;"
274
+ + "用户明确要求看图时再调用 zju_fetch_slides(download=true),并在文末列截图索引。";
244
275
  }
245
276
 
246
277
  /**
@@ -266,15 +297,19 @@ function pdfFeatureRule(enabled) {
266
297
  ? "讲义 PDF 自动排版已开启:zju_write_note 会在本地排好同名 PDF 并返回路径;"
267
298
  + "排版不需要额外工具、不增加模型 token,PDF 失败也不影响 Markdown。"
268
299
  + "返回「找不到 typst」时调用 zju_doctor(install=true) 自动安装后重试。"
300
+ + "返回「PDF 跳过」时先按它点名的公式错误改文件(多半是某条 LaTeX 命令没有 Typst 写法),"
301
+ + "再调用一次 zju_check_note(pdf=true) 重排——这是「不要重复检查」的唯一例外。"
269
302
  : "讲义 PDF 自动排版已关闭(插件设置 renderPdf=false):只交付 Markdown;"
270
303
  + "用户要 PDF 时提示他在插件设置里打开「自动排版 PDF 讲义」。";
271
304
  }
272
305
 
273
306
  function studyFeatureRule(enabled) {
274
307
  return enabled
275
- ? "填空笔记已开启:需要可动手填写的复习版时用 zju_build_study_notes"
276
- + "(draft 生成底稿 → 你补内容 → compile 出 PDF),排版规范交给 scholia-notes Skill;"
277
- + "只要普通讲义 PDF 则不必用这条链路。"
308
+ ? "填空笔记已开启:写完讲义后默认再出一份填空版(用户只要 Markdown/PDF 或明确说不用时跳过)——"
309
+ + "zju_build_study_notes(mode=draft) 先把讲义搬成底稿:底稿是**纯 Markdown**(公式保持 LaTeX,表格保持 Markdown),"
310
+ + "你只需补 [直觉]/[练习]/[边注] 占位符、正文该挖空的地方写 ____,**不要重写全文**;"
311
+ + "挖空别一处一处改:把所有 {old, new} 交给 mode=patch 一次写回(省掉十几次单条编辑);"
312
+ + "然后 mode=compile 一次性转 Typst 并出 PDF(PDF 会落在底稿同目录)。排版规范交给 scholia-notes Skill。"
278
313
  : "填空笔记已关闭(插件设置 enableStudyNotes=false):本会话没有注册 zju_build_study_notes,"
279
314
  + "不要调用或假装调用;用户需要时提示他在插件设置里打开「填空式学习笔记」。";
280
315
  }
@@ -481,15 +516,17 @@ function apply(ctx, config = {}) {
481
516
  // optional modules default to off, so the verified transcript path never
482
517
  // pays for a login/cookie/screenshot/typst dependency it did not ask for.
483
518
  const flags = featureFlags(config);
484
- const timeoutMs = Number(config.timeoutMs) > 0 ? Number(config.timeoutMs) : 120000;
519
+ const timeoutMs = Number(readSetting(config, "timeoutMs")) > 0
520
+ ? Number(readSetting(config, "timeoutMs"))
521
+ : 120000;
485
522
  const bridge = new ZjuBridge({
486
- python: config.python,
523
+ python: readSetting(config, "python"),
487
524
  timeoutMs,
488
525
  ...flags,
489
526
  });
490
527
  ctx.effect(() => () => bridge.dispose());
491
528
 
492
- if (config.registerSkill) {
529
+ if (readSetting(config, "registerSkill") !== false) {
493
530
  const skills = readBundledSkills(flags);
494
531
  if (skills.length) {
495
532
  // Registration is synchronous, so it lands during apply() as the skill
@@ -562,6 +599,7 @@ export {
562
599
  featureFlags,
563
600
  name,
564
601
  readBundledSkills,
602
+ readSetting,
565
603
  registerableTools,
566
604
  slideImageRule,
567
605
  slidesFeatureRule,