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/lib/tools.js CHANGED
@@ -201,23 +201,46 @@ export const ZJU_TOOLS = [
201
201
  },
202
202
  {
203
203
  "name": "zju_build_study_notes",
204
- "description": "把讲义变成 scholia 填空式学习笔记(Typst → PDF)。mode=draft 生成填空底稿(你补内容);mode=compile 编译成 out.pdf + 逐页 PNG,并报告编译错误、方框预算与改不动的数学。需要本机 Typst(≥0.13)。只写工作区内的文件。",
204
+ "description": "把讲义变成 scholia 填空式学习笔记(Typst → PDF)。mode=draft 生成填空底稿(你补内容);mode=patch 用 edits 一次写回多处挖空/标记;mode=compile 编译成 out.pdf + 逐页 PNG,并报告编译错误、方框预算与改不动的数学。需要本机 Typst(≥0.13)。只写工作区内的文件。",
205
205
  "parameters": {
206
206
  "mode": {
207
- "description": "draft=讲义转填空底稿(只搬运与改公式,不做内容判断);compile=底稿转 Typst 并编译成 PDF",
207
+ "description": "draft=讲义转填空底稿(只搬运与改公式,不做内容判断);patch=按 edits 一次写回底稿(批量挖空,省掉十几次单条编辑);compile=底稿转 Typst 并编译成 PDF",
208
208
  "default": "draft",
209
209
  "type": "string",
210
210
  "enum": [
211
211
  "draft",
212
+ "patch",
212
213
  "compile"
213
214
  ]
214
215
  },
216
+ "edits": {
217
+ "description": "mode=patch 的修改列表:每项 {old, new},old 必须在底稿里恰好出现一次(重复时加长上下文,或加 all=true 全部替换)。一次最多 80 条",
218
+ "type": "array",
219
+ "items": {
220
+ "type": "object",
221
+ "properties": {
222
+ "old": {
223
+ "description": "原文(精确匹配,含标点)",
224
+ "type": "string"
225
+ },
226
+ "new": {
227
+ "description": "替换成的新文本",
228
+ "type": "string"
229
+ },
230
+ "all": {
231
+ "description": "原文出现多次时是否全部替换(默认 false)",
232
+ "type": "boolean"
233
+ }
234
+ },
235
+ "additionalProperties": false
236
+ }
237
+ },
215
238
  "note_path": {
216
239
  "description": "讲义 Markdown 的路径(mode=draft 必填)",
217
240
  "type": "string"
218
241
  },
219
242
  "draft_path": {
220
- "description": "填空底稿 Markdown 的路径(mode=compile 必填)",
243
+ "description": "填空底稿 Markdown 的路径(mode=patch / compile 必填)",
221
244
  "type": "string"
222
245
  },
223
246
  "output_dir": {
@@ -198,23 +198,46 @@
198
198
  },
199
199
  {
200
200
  "name": "zju_build_study_notes",
201
- "description": "把讲义变成 scholia 填空式学习笔记(Typst → PDF)。mode=draft 生成填空底稿(你补内容);mode=compile 编译成 out.pdf + 逐页 PNG,并报告编译错误、方框预算与改不动的数学。需要本机 Typst(≥0.13)。只写工作区内的文件。",
201
+ "description": "把讲义变成 scholia 填空式学习笔记(Typst → PDF)。mode=draft 生成填空底稿(你补内容);mode=patch 用 edits 一次写回多处挖空/标记;mode=compile 编译成 out.pdf + 逐页 PNG,并报告编译错误、方框预算与改不动的数学。需要本机 Typst(≥0.13)。只写工作区内的文件。",
202
202
  "parameters": {
203
203
  "mode": {
204
- "description": "draft=讲义转填空底稿(只搬运与改公式,不做内容判断);compile=底稿转 Typst 并编译成 PDF",
204
+ "description": "draft=讲义转填空底稿(只搬运与改公式,不做内容判断);patch=按 edits 一次写回底稿(批量挖空,省掉十几次单条编辑);compile=底稿转 Typst 并编译成 PDF",
205
205
  "default": "draft",
206
206
  "type": "string",
207
207
  "enum": [
208
208
  "draft",
209
+ "patch",
209
210
  "compile"
210
211
  ]
211
212
  },
213
+ "edits": {
214
+ "description": "mode=patch 的修改列表:每项 {old, new},old 必须在底稿里恰好出现一次(重复时加长上下文,或加 all=true 全部替换)。一次最多 80 条",
215
+ "type": "array",
216
+ "items": {
217
+ "type": "object",
218
+ "properties": {
219
+ "old": {
220
+ "description": "原文(精确匹配,含标点)",
221
+ "type": "string"
222
+ },
223
+ "new": {
224
+ "description": "替换成的新文本",
225
+ "type": "string"
226
+ },
227
+ "all": {
228
+ "description": "原文出现多次时是否全部替换(默认 false)",
229
+ "type": "boolean"
230
+ }
231
+ },
232
+ "additionalProperties": false
233
+ }
234
+ },
212
235
  "note_path": {
213
236
  "description": "讲义 Markdown 的路径(mode=draft 必填)",
214
237
  "type": "string"
215
238
  },
216
239
  "draft_path": {
217
- "description": "填空底稿 Markdown 的路径(mode=compile 必填)",
240
+ "description": "填空底稿 Markdown 的路径(mode=patch / compile 必填)",
218
241
  "type": "string"
219
242
  },
220
243
  "output_dir": {
package/mcp_server.py CHANGED
@@ -22,6 +22,7 @@ Design notes:
22
22
  import json
23
23
  import os
24
24
  import re
25
+ import shutil
25
26
  import sys
26
27
  import time
27
28
  import traceback
@@ -78,6 +79,7 @@ from zju_lecture.study_notes import (
78
79
  KNOT_RATIO_TARGET,
79
80
  KNOT_RATIO_TOO_MANY,
80
81
  StudyNotesError,
82
+ apply_draft_edits,
81
83
  build_draft,
82
84
  compile_project,
83
85
  find_typst,
@@ -85,7 +87,7 @@ from zju_lecture.study_notes import (
85
87
  )
86
88
 
87
89
  SERVER_NAME = "zju-lecture-mcp"
88
- SERVER_VERSION = "2.1.0"
90
+ SERVER_VERSION = "2.2.4"
89
91
  DEFAULT_TENANT = "112"
90
92
  DEFAULT_DOMAIN = "classroom.zju.edu.cn"
91
93
 
@@ -204,7 +206,7 @@ def slide_image_mode_text() -> str:
204
206
  return "投影抓取已关闭,讲义只使用字幕与本地课件。"
205
207
  if embed_slides_enabled():
206
208
  return (
207
- "讲义插图模式:开启。需要投影画面时调用 zju_fetch_slides(download=true),"
209
+ "讲义插图模式:开启。写讲义前默认抓一次投影(整节课只抓一次),"
208
210
  "从返回的截图里挑 3–8 张关键页,按讲义所在目录的相对路径插入 Markdown;"
209
211
  "模型不能查看本地图片时,只在文末列截图索引,不要臆造截图内容。"
210
212
  )
@@ -234,6 +236,9 @@ def server_instructions() -> str:
234
236
  "写前修正、写后校验)。zju_write_note 已包含检查,不要为同一份讲义再调 "
235
237
  "zju_check_note;它只用于修复已有文件。相对路径按 ZJU_WORKSPACE 解析。"
236
238
  + _pdf_mode_text(),
239
+ "讲义默认按「复习版」写:每节保留 [HH:MM];老师讲过的例题整理成"
240
+ "「题目 → 切入点 → 关键步骤 → 易错点」,本节没有例题就写「本节无例题」;"
241
+ "文末给 3–5 道自测题(答案用 <details> 折叠)与 5–10 条考点预测。",
237
242
  ]
238
243
  if slides_enabled():
239
244
  parts.append(
@@ -248,8 +253,8 @@ def server_instructions() -> str:
248
253
  )
249
254
  if study_notes_enabled():
250
255
  parts.append(
251
- "要把 STEM 讲义变成可填空的复习笔记,用 zju_build_study_notes:"
252
- "mode=draft 生成填空底稿(你补内容),mode=compile 编译成 PDF。"
256
+ "填空笔记已开启:写完讲义后默认再出一份填空版(用户只要 Markdown/PDF 时跳过)——"
257
+ "zju_build_study_notes 先 mode=draft 生成填空底稿(你补内容),再 mode=compile 编译成 PDF。"
253
258
  )
254
259
  else:
255
260
  parts.append(
@@ -340,7 +345,12 @@ def _resolve_cookie() -> Tuple[Optional[str], Optional[str], Optional[str], Opti
340
345
  return _remember_cookie(cookie), None, "edge", None
341
346
  if error is None:
342
347
  return None, f"未能从本机 Microsoft Edge 读取到 {DEFAULT_DOMAIN} 的登录 Cookie。", None, "no_credentials"
343
- return None, str(error), None, error.reason
348
+ # 只回「是什么问题」这一句:修复办法由下面的 COOKIE_FAILURE_ACTIONS 给出。
349
+ # 以前把 ``str(error)``(message + hint)整段塞进「说明」,再跟一行
350
+ # 「唯一可行动作」——同一句 ZJU_COOKIE_FILE 在一段 5 行的报错里出现两次,
351
+ # 模型只能照抄给用户(实地会话 session-5415d8a5)。
352
+ message = getattr(error, "message", "") or str(error)
353
+ return None, message, None, error.reason
344
354
 
345
355
 
346
356
  #: One concrete next step per cookie-failure reason.
@@ -673,9 +683,9 @@ TOOLS: List[Dict[str, Any]] = [
673
683
  "name": "zju_build_study_notes",
674
684
  "description": (
675
685
  "把讲义变成 scholia 填空式学习笔记(Typst → PDF)。"
676
- "mode=draft 生成填空底稿(你补内容);mode=compile 编译成 out.pdf + 逐页 PNG,"
677
- "并报告编译错误、方框预算与改不动的数学。需要本机 Typst(≥0.13)。"
678
- "只写工作区内的文件。"
686
+ "mode=draft 生成填空底稿(你补内容);mode=patch 用 edits 一次写回多处挖空/标记;"
687
+ "mode=compile 编译成 out.pdf + 逐页 PNG,并报告编译错误、方框预算与改不动的数学。"
688
+ "需要本机 Typst(≥0.13)。只写工作区内的文件。"
679
689
  ),
680
690
  "inputSchema": {
681
691
  "type": "object",
@@ -683,20 +693,42 @@ TOOLS: List[Dict[str, Any]] = [
683
693
  "properties": {
684
694
  "mode": {
685
695
  "type": "string",
686
- "enum": ["draft", "compile"],
696
+ "enum": ["draft", "patch", "compile"],
687
697
  "description": (
688
698
  "draft=讲义转填空底稿(只搬运与改公式,不做内容判断);"
699
+ "patch=按 edits 一次写回底稿(批量挖空,省掉十几次单条编辑);"
689
700
  "compile=底稿转 Typst 并编译成 PDF"
690
701
  ),
691
702
  "default": "draft",
692
703
  },
704
+ "edits": {
705
+ "type": "array",
706
+ "description": (
707
+ "mode=patch 的修改列表:每项 {old, new},old 必须在底稿里"
708
+ "恰好出现一次(重复时加长上下文,或加 all=true 全部替换)。"
709
+ "一次最多 80 条"
710
+ ),
711
+ "items": {
712
+ "type": "object",
713
+ "additionalProperties": False,
714
+ "properties": {
715
+ "old": {"type": "string", "description": "原文(精确匹配,含标点)"},
716
+ "new": {"type": "string", "description": "替换成的新文本"},
717
+ "all": {
718
+ "type": "boolean",
719
+ "description": "原文出现多次时是否全部替换(默认 false)",
720
+ },
721
+ },
722
+ "required": ["old", "new"],
723
+ },
724
+ },
693
725
  "note_path": {
694
726
  "type": "string",
695
727
  "description": "讲义 Markdown 的路径(mode=draft 必填)",
696
728
  },
697
729
  "draft_path": {
698
730
  "type": "string",
699
- "description": "填空底稿 Markdown 的路径(mode=compile 必填)",
731
+ "description": "填空底稿 Markdown 的路径(mode=patch / compile 必填)",
700
732
  },
701
733
  "output_dir": {
702
734
  "type": "string",
@@ -974,6 +1006,15 @@ def _doctor_report(install: bool) -> str:
974
1006
  )
975
1007
  lines.append(f"汇编缓存: {info['compile_cache'] or '(未指定工作区)'}")
976
1008
  lines.append(f"自动安装: {'开' if auto else '关'}(ZJU_TYPST_AUTO_INSTALL)")
1009
+ lines.append(
1010
+ "模块: 投影=%s / 填空=%s / 登录=%s / PDF=%s(本进程启动时的设置)"
1011
+ % (
1012
+ "开" if slides_enabled() else "关",
1013
+ "开" if study_notes_enabled() else "关",
1014
+ "开" if login_tools_enabled() else "关",
1015
+ "开" if render_pdf_enabled() else "关",
1016
+ )
1017
+ )
977
1018
  if info["mirror"]:
978
1019
  lines.append(f"下载镜像: {info['mirror']}")
979
1020
  if not info["typst_ok"]:
@@ -1013,14 +1054,79 @@ def _render_note_pdf(note_path: str, note_text: str) -> List[str]:
1013
1054
  detail = "未找到 typst(Markdown 已保存;运行 zju_doctor(install=true) 自动安装,或在设置里关 renderPdf)"
1014
1055
  if len(detail) > 220:
1015
1056
  detail = detail[:219] + "…"
1016
- return [f"PDF 跳过: {detail}"]
1057
+ # 这是「同一份讲义要不要再查一次」的唯一例外:上面报的是渲染错误,
1058
+ # 不改文件永远好不了。给一句可执行的下一步,Agent 就不必自己猜。
1059
+ return [
1060
+ f"PDF 跳过: {detail}",
1061
+ "Markdown 已写好;按上面的错误改掉对应公式后,调用 zju_check_note(pdf=true) 重排一次。",
1062
+ ]
1063
+
1064
+
1065
+ def _patch_draft(arguments: Dict[str, Any]) -> str:
1066
+ """``mode=patch``:按 ``edits`` 一次写回底稿(批量挖空 / 补标记)。"""
1067
+ draft_path = str(arguments.get("draft_path") or "").strip()
1068
+ if not draft_path:
1069
+ return "错误: mode=patch 需要 draft_path(填空底稿的路径)"
1070
+ raw_edits = arguments.get("edits")
1071
+ if not isinstance(raw_edits, list) or not raw_edits:
1072
+ return "错误: mode=patch 需要非空的 edits(每项 {old, new})"
1073
+
1074
+ resolved, tried = resolve_path(draft_path)
1075
+ if resolved is None:
1076
+ return f"错误: 找不到填空底稿: {draft_path}{describe_attempts(tried)}"
1077
+ try:
1078
+ resolved = guard_local_file(resolved, NOTE_EXTENSIONS, kind="填空底稿")
1079
+ except LocalFileError as exc:
1080
+ return f"错误: {exc}"
1081
+ try:
1082
+ with open(resolved, "r", encoding="utf-8") as handle:
1083
+ draft_text = handle.read()
1084
+ except UnicodeDecodeError:
1085
+ return f"错误: 填空底稿不是 UTF-8 编码: {resolved}"
1086
+ except OSError as exc:
1087
+ return f"错误: 读取填空底稿失败: {exc}"
1088
+
1089
+ try:
1090
+ result = apply_draft_edits(draft_text, raw_edits)
1091
+ except StudyNotesError as exc:
1092
+ return f"错误: {exc}"
1093
+
1094
+ if result.applied:
1095
+ try:
1096
+ write_atomic(resolved, result.text)
1097
+ except OSError as exc:
1098
+ return f"错误: 写入填空底稿失败: {resolved}({exc})"
1099
+
1100
+ summary = f"应用: {result.applied}/{len(raw_edits)} 处"
1101
+ if result.skipped:
1102
+ summary += f"(跳过 {result.skipped} 处 old 与 new 相同)"
1103
+ lines = ["=== 已修改填空底稿 ===", f"路径: {resolved}", summary]
1104
+ if result.failures:
1105
+ lines.append("")
1106
+ lines.append(f"未应用 {len(result.failures)} 处:")
1107
+ lines.extend(f"- {item}" for item in result.failures[:12])
1108
+ if len(result.failures) > 12:
1109
+ lines.append(f"- …另有 {len(result.failures) - 12} 处")
1110
+ lines.append("")
1111
+ lines.append("已应用的部分已经写回文件,不必重发;修正上面几条后再 compile。")
1112
+ lines.append(
1113
+ f'下一步: zju_build_study_notes(mode="compile", draft_path="{resolved}")'
1114
+ )
1115
+ else:
1116
+ lines.append(
1117
+ f'下一步: zju_build_study_notes(mode="compile", draft_path="{resolved}")'
1118
+ )
1119
+ return "\n".join(lines)
1017
1120
 
1018
1121
 
1019
1122
  def _build_study_notes(arguments: Dict[str, Any]) -> str:
1020
1123
  """Handle ``zju_build_study_notes``: 讲义 → 填空底稿 → Typst → PDF."""
1021
1124
  mode = str(arguments.get("mode") or "draft").strip().lower()
1022
- if mode not in ("draft", "compile"):
1023
- return "错误: mode 只能是 draft 或 compile"
1125
+ if mode not in ("draft", "patch", "compile"):
1126
+ return "错误: mode 只能是 draft / patch / compile"
1127
+
1128
+ if mode == "patch":
1129
+ return _patch_draft(arguments)
1024
1130
 
1025
1131
  if mode == "draft":
1026
1132
  note_path = str(arguments.get("note_path") or "").strip()
@@ -1067,10 +1173,12 @@ def _build_study_notes(arguments: Dict[str, Any]) -> str:
1067
1173
  f"路径: {target}",
1068
1174
  f"来源: {resolved} | 章节: {draft.sections} | 字数: {len(draft.text)}",
1069
1175
  "",
1070
- "请编辑底稿:把 [直觉]/[练习]/[边注] 补成内容;[定义]/[定理]/[证明] "
1071
- "只在「后面会被回引」时才用(每节框合计 ≤ "
1072
- f"{KNOT_BUDGET_PER_SECTION} 个),其余写成普通段落。",
1176
+ "底稿已搬运完成:按内容补 [直觉]/[练习]/[边注](可选,不需要就别加)"
1177
+ "与正文里的 ____ 挖空;[定义]/[定理]/[证明] 只在「后面会被回引」时才用"
1178
+ f"(每节框合计 ≤ {KNOT_BUDGET_PER_SECTION} 个),其余写成普通段落。",
1073
1179
  "公式直接写 LaTeX,工具会转成 Typst;转不动的会点名。",
1180
+ "挖空别一处一处改:把全部 {old, new} 交给 "
1181
+ 'zju_build_study_notes(mode="patch", draft_path=…, edits=[…]) 一次写回。',
1074
1182
  f'下一步: zju_build_study_notes(mode="compile", draft_path="{target}")',
1075
1183
  ]
1076
1184
  if draft.warnings:
@@ -1137,11 +1245,35 @@ def _build_study_notes(arguments: Dict[str, Any]) -> str:
1137
1245
  "格式规范: skills/scholia-notes/references/format-spec.md(规范性文件)",
1138
1246
  ]
1139
1247
  if result.ok:
1140
- lines.append(f"PDF: {result.pdf_path}")
1248
+ # Typst 工程目录里的 `out.pdf` 不是「交付物位置」:讲义链路的 PDF
1249
+ # 一直和 .md 同目录,填空笔记却落在 `<stem>-typst/out.pdf` 里,
1250
+ # Agent 每次都得再 `cp` 一次才交得出来。这里直接放一份到同目录。
1251
+ #
1252
+ # 命名要避开**阅读版**那份 `<讲义名>.pdf`:自动生成的底稿叫
1253
+ # `<讲义名>-填空底稿.md`,去掉后缀正好等于讲义名,直接落 `<stem>.pdf`
1254
+ # 会把刚排好的阅读版 PDF 覆盖掉(实测覆盖过)。所以自动底稿统一叫
1255
+ # `<讲义名>-填空.pdf`;手写底稿(如 `填空笔记-XXX.md`)保持同名。
1256
+ deliverable_pdf = result.pdf_path
1257
+ if stem.endswith("-填空底稿"):
1258
+ public_stem = stem[: -len("-填空底稿")] + "-填空"
1259
+ else:
1260
+ public_stem = stem
1261
+ sibling = os.path.join(target_dir, f"{public_stem}.pdf")
1262
+ try:
1263
+ if os.path.abspath(sibling) != os.path.abspath(result.pdf_path):
1264
+ shutil.copyfile(result.pdf_path, sibling)
1265
+ deliverable_pdf = sibling
1266
+ except OSError:
1267
+ pass
1268
+ lines.append(f"PDF: {deliverable_pdf}")
1269
+ if deliverable_pdf != result.pdf_path:
1270
+ lines.append(f"Typst 工程: {project_dir}(out.pdf 是同一份)")
1141
1271
  if result.png_paths:
1142
- lines.append(
1143
- "逐页 PNG: " + ", ".join(os.path.basename(path) for path in result.png_paths)
1144
- )
1272
+ names = ", ".join(os.path.basename(path) for path in result.png_paths)
1273
+ lines.append("逐页 PNG: " + names)
1274
+ # 直接给一条完整路径:Agent 就能把这张图原样交给看图工具,
1275
+ # 不必再 glob 一次去拼目录(实地会话为此多花了一次调用)。
1276
+ lines.append("例(可直接看): " + result.png_paths[0])
1145
1277
  lines.append(
1146
1278
  "请抽查 PNG:knot 内容块错位不会让编译报错(退出码仍是 0)。"
1147
1279
  "只看与内容块/图相关的页,不必逐页全看。"
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "dsh-zju-lecture-note",
3
- "version": "2.1.0",
4
- "description": "浙大智云课堂回放讲义插件(DeepSeek Harness 原生插件):以「语音字幕 + 本地课件」为主链路,写完讲义自动排版同名 PDF;可选启用投影 PPT 截图抓取、填空式学习笔记与登录辅助工具;Cookie 只在本地内存中使用,不回显、不落盘",
3
+ "version": "2.2.4",
4
+ "description": "浙大智云课堂回放讲义插件(DeepSeek Harness 原生插件):以「语音字幕 + 本地课件」为主链路,写完讲义自动排版同名 PDF;可选启用投影 PPT 截图抓取、基于 Typst scholia 模板排版的填空式学习笔记与登录辅助工具;Cookie 只在本地内存中使用,不回显、不落盘",
5
5
  "license": "MIT",
6
6
  "author": "chenqianyu486",
7
7
  "icon": "icon.png",
@@ -2,7 +2,8 @@
2
2
 
3
3
  把 STEM 内容做成**填空式学习笔记**的 Agent Skill:先用 Markdown 把内容和结构写完整,
4
4
  再套 Typst 的 [scholia](https://typst.app/universe/package/scholia) 模板排版,
5
- 本地编译校验为 PDF / PNG。
5
+ 本地编译校验为 PDF / PNG。**配色与段落规范由本项目定义**,见
6
+ [`references/typography-spec.md`](references/typography-spec.md)。
6
7
 
7
8
  > 本 skill 与 `scholia` 包的作者、发行方无关,也未获其背书。
8
9
 
@@ -15,6 +15,10 @@ descriptions:
15
15
 
16
16
  # Scholia Notes
17
17
 
18
+ > **口径**:本 Skill 产出的是**基于 Typst scholia 模板排版的填空式学习笔记**;
19
+ > 配色与段落规范由本项目定义,见
20
+ > [`references/typography-spec.md`](references/typography-spec.md)。
21
+ >
18
22
  > **先分清两份 PDF**:普通讲义(知识总结)的阅读版 PDF 由 `zju_write_note` 自动生成,
19
23
  > 不需要本 Skill;本 Skill 只负责「可动手填写的复习笔记」这一种更重的产物。
20
24
  > 用户只是要一份好读的讲义时,直接走 `zju_write_note`,不要启动这条填空链路。
@@ -73,14 +77,30 @@ prelude 已内置四色体系,**照着用,不要另挑颜色**:
73
77
 
74
78
  | 步骤 | 工具 | 做什么 |
75
79
  |---|---|---|
76
- | 1 | `zju_build_study_notes(mode="draft", note_path=…)` | 讲义 → 填空底稿 `*-填空底稿.md`(标题层级映射、标记位插入、LaTeX 数学改写为 Typst 数学) |
77
- | 2 | 人工/Agent 填底稿 | 把标记位补成真正的定义、定理、练习;**正文写成普通段落,框只给会被引用的那几条** |
78
- | 3 | `zju_build_study_notes(mode="compile", draft_path=…)` | 底稿 → `main.typ` + `prelude.typ` → `out.pdf` + 逐页 `page-N.png` |
80
+ | 1 | `zju_build_study_notes(mode="draft", note_path=…)` | 讲义 → 填空底稿 `*-填空底稿.md`(标题层级映射、正文原样搬运;**公式保持 LaTeX、表格保持 Markdown**,不写任何 Typst 语法,也**不逐节塞空占位**) |
81
+ | 2 | 人工/Agent 填底稿 | 按内容补 `[直觉]`/`[练习]`/`[边注]`(可选,不需要就别加)、该挖空的地方写 `____`;**不要重写全文**,也别把公式改成 Typst |
82
+ | 3 | `zju_build_study_notes(mode="patch", draft_path=…, edits=[{old,new}, …])` | 把第 2 步的全部改动**一次**写回底稿(每处 `old` 必须唯一命中;命中结果逐条报出来)。**不要一处一处调用编辑工具**——一次课的挖空有十几处 |
83
+ | 4 | `zju_build_study_notes(mode="compile", draft_path=…)` | 底稿 → `main.typ` + `prelude.typ` → `out.pdf` + 逐页 `page-N.png`(PDF 同时落在底稿同目录,无需再拷) |
79
84
 
80
85
  工具只做**搬运与排版**:哪些是定理、哪里该挖空,是内容判断,仍由你(Agent)完成。
86
+ LaTeX → Typst 的数学转换**只在 compile 这一步做一次**:底稿里保持 LaTeX,
87
+ 工具会统一改写,转不动的会点名。反过来(把底稿改写成 Typst)会被二次转换拆坏。
81
88
  工具会把「无法机械转换的数学」「超出视觉预算的方框」「方框 : 正文段落比值」
82
89
  「编译错误」原样报出来,别自行吞掉。
83
90
 
91
+ **`mode=patch` 的用法**:第 2 步读完底稿后,把十几处 `{old, new}` 攒成一个数组一次提交:
92
+
93
+ ```json
94
+ {"mode": "patch", "draft_path": "…-填空底稿.md",
95
+ "edits": [
96
+ {"old": "**总电流连续**", "new": "**总电流____**"},
97
+ {"old": "这就是电磁波的直接来源。", "new": "…。\n\n[边注] …"}
98
+ ]}
99
+ ```
100
+
101
+ `old` 在底稿里必须**恰好出现一次**(重复时加长上下文,或加 `"all": true`)。
102
+ 没命中的几条会逐条点名,已命中的照常写回,不必重发。
103
+
84
104
  **格式规范(规范性文件)在 [`references/format-spec.md`](references/format-spec.md)** ——
85
105
  语义对应关系、预算、禁止事项、校验清单都在那里。
86
106
 
@@ -154,27 +174,19 @@ prelude 已内置四色体系,**照着用,不要另挑颜色**:
154
174
 
155
175
  原因:方框是这套模板最重的视觉元素,堆多了整页就糊;正文保持黑白,
156
176
  强调用行内淡色加粗,视觉负担小一个数量级。knot 只为「可编号、可回指」而存在。
157
- 口径以 `references/style.md` 第 3 节为准。
177
+ 口径以 `references/format-spec.md` §2.2 为准。
158
178
 
159
- **中文正文额外加这几行**(放在 `#show: use-palette` 之后):
179
+ **中文正文额外加这两行**(放在 `#show: use-palette` 之后):
160
180
 
161
181
  ```typst
162
182
  #set text(lang: "zh")
163
- #set par(
164
- justify: false,
165
- leading: 0.72em,
166
- first-line-indent: 0pt,
167
- spacing: 0.95em,
168
- )
169
- #show math.equation.where(block: true): set block(above: 1.6em, below: 1.6em)
183
+ #set par(justify: false)
170
184
  ```
171
185
 
172
186
  原因:scholia 包装器写死 `lang: "en"` 且 `justify: true`;
173
187
  前者影响断行规则,后者会让两端对齐把中文字距拉得很松(实测 `justify: false` 才是关键)。
174
- `spacing` 略大于 `leading`,段落看得出来但不夸张。
175
- 块级公式的上下间距**必须显式给** —— 它一旦跟着 `par.spacing` 走,
176
- 公式就会压到下一段文字上(实测重叠)。
177
- 完整口径见 [`references/format-spec.md`](references/format-spec.md) §1.2。
188
+ 行距、段距、缩进、公式间距等**数值**见
189
+ [`references/typography-spec.md`](references/typography-spec.md) §3,不要在这里重复。
178
190
 
179
191
  5. 编译并肉眼验版(**两道关,缺一不可**):
180
192
 
@@ -206,7 +218,7 @@ prelude 已内置四色体系,**照着用,不要另挑颜色**:
206
218
  | `[直觉]` | `#note[…]` | 带底色,每节≤1 |
207
219
  | `[定义]` | `#definition[术语][…] <def:x>` | 方框(≤2/节) |
208
220
  | `[定理]/[引理]/[推论]` | `#theorem[标题][来源标签][…] <thm:x>` | 方框(≤2/节) |
209
- | `[证明]` | `#proof[… #TODO[缺口] …]` | 无框 + qed |
221
+ | `[证明]` | `#proof[… #TODO[缺口] …]` | 无框 + **块末** qed |
210
222
  | `[例]` | `#example[标题][…]` | 方框(≤2/节) |
211
223
  | `[练习]` | `#yourturn[…] #workspace(n: 3)` | 方框 + 留白 |
212
224
  | `[边注]` | `#recall[…]` | 右栏,最省空间 |
@@ -215,6 +227,13 @@ prelude 已内置四色体系,**照着用,不要另挑颜色**:
215
227
  | `____` 填空 | `#fillin(width: 2.2cm)`(灰色;**练习块里不画**,那里已有书写横线) | — |
216
228
  | `@def:xxx` 回指 | 原生 `@def:xxx`,label 写在 knot 后 | — |
217
229
 
230
+ > **框与证明是「块」,不是「一行」**:`[定义]` / `[定理]` / `[例]` / `[证明]` 从标记行开始,
231
+ > 一直排到下一个标记、标题或整行粗体的伪标题为止。块里的空行是段落分隔,
232
+ > `$$…$$`、列表、表格都留在装置里。`[证明]` 的 qed 方块因此排在**块内最后一行** ——
233
+ > 证明要一直写到最后一段,不要把结论另起一段写在标记外面(方块会停在半路,误导读者的
234
+ > 正是这个)。`[直觉]` / `[练习]` / `[边注]` / `[强调]` 只吃标记行那一句。
235
+ > 完整规则见 [`references/format-spec.md`](references/format-spec.md) §2.4。
236
+
218
237
  ## 内容出处:自己的话 + 可核对的来源
219
238
 
220
239
  模板只管排版,**内容归属是你要负责的事**:
@@ -248,6 +267,15 @@ prelude 已内置四色体系,**照着用,不要另挑颜色**:
248
267
  **退出码是 0,grep `error:` 抓不到**,只能靠看 PNG 发现。
249
268
  - 公式报 `unknown variable` 或渲染出字面量:`$a_(ij)$`、`$rank(A)$`、`$\prod_…$`、`$\overline{A}$`
250
269
  在 Typst 里全是错的;正确写法见 `references/troubleshooting.md`。这类错应在 Markdown 阶段就改掉。
270
+ - **几条公式并排写成 `a \qquad b`**:工具会把 `\qquad` 映射成 2em 的 `wide`、`\quad` 映射成
271
+ 1em 的 `quad`,直接排就对了。**不要**再写脚本把它们拆成多个公式块(实测那会多跑两轮排版)。
272
+ 一行真的放不下时,再拆成独立 `$$` 块。
273
+ - **行内 `$1/r$`**:工具在行内把 `/` 排成平排的斜杠(`1 slash r`),只有独占一行的 `$$` 才排
274
+ 上下分式。看到 `1/r` 不必手改成 `r^{-1}`。
275
+ - **讲义抬头的多行引用块**(`> **来源**:…`)在两条 PDF 链路里都会排成左侧细线的灰色小字块,
276
+ 字段之间自动换行。不要为了「排版」把它改成普通段落。
277
+ - 方框预算按**最小**小节统计:`## 二、分章详解` 下面挂 7 个 `### 2.x` 时,每个 `2.x` 各自
278
+ ≤2 就行,不会因为整章合计超 2 就报警。
251
279
  - `sidenote` 的 `symbol` 必须圆括号:`#sidenote([正文], symbol: [!])`,方括号写法直接报 `unexpected argument`。
252
280
  - 首次编译卡住无输出(包注册表不通):重试一次,仍不行就把依赖名报给用户,别空等。
253
281
  - 用户要的是中文论文/长文排版而非填空笔记:这个 skill 不适用,转 `typst-author-chinese`。
@@ -274,45 +302,31 @@ typst fonts # 看本机可用字体名
274
302
  ```
275
303
 
276
304
  - 用 Read/Write 工具写 `.md`/`.typ`,不要用 `Set-Content`(PowerShell 5.1 默认 ANSI 会破坏 UTF-8 中文)。
277
- - 本机缺 `STIX Two` / `Optima` / `Avenir Next` / `Songti SC`,编译会刷一串
278
- `warning: unknown font family`。**无害**,Typst 自动回退,中文照样出字。
279
- - 想要接近官方的字体观感就装 STIX Two(免费/OFL)。
280
- - 想指定中文字形:`#show: scholia.with(fonts: (cjk: ("Noto Serif SC",), heading: ("Microsoft YaHei",)))`,
281
- 但它进不了 `note`/`sidenote`/`label-it`(这三个直接读包内 default-fonts)。
305
+ - 两条链路的默认字体栈已经统一:`STIX Two` / `Libertinus` / 随包 `Notes Kai SC` 与
306
+ `Notes Serif SC` / `Noto` / `Source Han`。本机缺 `STIX Two` 时会刷
307
+ `warning: unknown font family`,**无害**,Typst 自动回退到 Libertinus / 随包字体。
308
+ - 不需要再手工覆盖字体:vendored `scholia` 的 `default-fonts` 已 patch,
309
+ `note` / `sidenote` / `label-it` 也跟随同一套字体。实际字体表见
310
+ [`references/typography-spec.md`](references/typography-spec.md) §1。
282
311
 
283
312
  ### 字体与分发(对外分享 PDF 前必读)
284
313
 
285
- Typst 编译 PDF 时会**内嵌并子集化**用到的字体。上游 `scholia` 的默认字体表里
286
- `Optima` / `Avenir Next` / `Menlo` / `Songti SC` 都是**商业专有字体**,
287
- 一旦本机装了并被用上,这些字体的子集就会进入 PDF;把该 PDF 再分发出去,
288
- 就属于字体分发,多数商业字体 EULA 明确限制。
289
-
290
- | 场景 | 建议 |
291
- |---|---|
292
- | 自己复习、存档 | 直接用默认字体,回退到 Typst 内嵌的 Libertinus 即可 |
293
- | 要把 PDF 发给别人 / 公开分发 | 把 `body` / `math` / `heading` / `sans` 覆盖成 **STIX Two(OFL)** 或 Typst 内嵌字体,确保 PDF 里只有可再分发的字体 |
294
-
295
- ```typst
296
- #show: scholia.with(
297
- theme: "light",
298
- fonts: (
299
- body: ("STIX Two Text", "Libertinus Serif"),
300
- math: ("STIX Two Math", "New Computer Modern Math"),
301
- heading: ("STIX Two Text", "Libertinus Serif"),
302
- sans: ("STIX Two Text", "Libertinus Serif"),
303
- ),
304
- )
305
- ```
314
+ 两条链路的默认字体栈只包含**可再分发**字体(STIX Two / Libertinus / 随包
315
+ `Notes Kai SC` 与 `Notes Serif SC` / Noto / Source Han / DejaVu)。商业专有字体
316
+ (Optima / Avenir Next / Menlo / Songti SC / SimSun / Microsoft YaHei / Consolas)
317
+ 不在生效列表里;模板里即使出现,也只以注释形式保留。
306
318
 
307
- > 注意 `fonts:` 覆盖**进不了** `note` / `sidenote` / `label-it`(这三个直接读包内 default-fonts),
308
- > 所以只覆盖 `body` 并不彻底;要彻底可控就 vendor 包改 `src/fonts.typ`(保留上游 MIT 声明,见
309
- > `THIRD_PARTY_NOTICES.md`)。
319
+ 对外分发前跑一次 `pdffonts out.pdf`:看到上述商业字体,说明生僻字回退到了系统字体,
320
+ 换一份完整 OFL 字体再排。完整口径见
321
+ [`references/typography-spec.md`](references/typography-spec.md) §1 与 §8。
310
322
 
311
323
  ## 许可与致谢
312
324
 
313
325
  - 本 skill(工作流说明、配色方案、`prelude.typ` 扩展、`mapping` / `style` / `troubleshooting` 文档)
314
326
  以 **MIT** 授权发布,见 [`LICENSE`](LICENSE)。
315
327
  - 排版引擎 [`@preview/scholia`](https://typst.app/universe/package/scholia)(MIT © Eric Yang)
316
- 及其依赖 `@preview/frame-it`(MIT)、`@preview/marginalia`(UNLICENSE)均为宽松授权,
317
- 在编译期由 Typst 包注册表拉取,**未随本仓库分发**。
328
+ 及其依赖 `@preview/frame-it`(MIT)、`@preview/marginalia`(UNLICENSE)等已
329
+ **vendor 进 `zju_lecture/typst-packages/`**(保留各自许可文件),编译时离线解析;
330
+ 本项目对 `scholia` 的 `src/fonts.typ` / `src/lib.typ` 打了补丁,记录在
331
+ `zju_lecture/typst-packages/VENDORED.md`。
318
332
  - 逐条归属见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。