dsh-zju-lecture-note 2.2.6 → 2.2.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/index.js CHANGED
@@ -148,9 +148,29 @@ function skillDir(skillName) {
148
148
  }
149
149
 
150
150
  const Config = Schema.object({
151
- python: Schema.string().default(""),
152
- timeoutMs: Schema.number().min(1000).max(900000).default(120000),
153
- registerSkill: Schema.boolean().default(true),
151
+ python: Schema.string()
152
+ .description(
153
+ "Python 解释器路径(默认留空):留空时依次尝试 DeepSeek Harness 自带的 Python、"
154
+ + "py -3、python、python3。只有自带解释器不可用,或你要固定某个虚拟环境时才填写绝对路径。",
155
+ )
156
+ .default("")
157
+ .volatile(),
158
+ timeoutMs: Schema.number()
159
+ .min(1000)
160
+ .max(900000)
161
+ .description(
162
+ "普通工具超时(毫秒,默认 120000):PDF / Typst 类工具至少 300000,"
163
+ + "投影下载与登录窗口至少 600000,改小不会绕过这些下限。",
164
+ )
165
+ .default(120000)
166
+ .volatile(),
167
+ registerSkill: Schema.boolean()
168
+ .description(
169
+ "注册随包 Skill(默认开启):关闭后 Agent 不再看到智云课堂讲义工作流与用户命令,"
170
+ + "但工具仍可调用;适合你自己已有一份同类 Skill 的情况。",
171
+ )
172
+ .default(true)
173
+ .volatile(),
154
174
  renderPdf: Schema.boolean()
155
175
  .description(
156
176
  "写入讲义后自动排成同名 PDF(默认开启):让阅读体验从 Markdown 提升到可打印的讲义。"
@@ -169,14 +189,25 @@ const Config = Schema.object({
169
189
  enableSlides: Schema.boolean()
170
190
  .description(
171
191
  "启用「PPT 投影抓取」可选模块(默认关闭):开启后注册 zju_fetch_slides,"
172
- + "可从课堂回放抓取投影截图并合成 PDF。关闭时不注册投影工具、不下载截图;"
192
+ + "写讲义前会抓取投影截图清单;是否下载图片、是否把投影当作内容来源,"
193
+ + "分别由 slidesAsSource / embedSlideImages 决定。关闭时不注册投影工具、不下载截图;"
173
194
  + "字幕鉴权由核心链路自动完成,与投影独立。",
174
195
  )
175
196
  .default(false)
176
197
  .volatile(),
198
+ slidesAsSource: Schema.boolean()
199
+ .description(
200
+ "把课堂投影截图作为讲义内容来源(默认关闭;需先开启「PPT 投影抓取」):"
201
+ + "开启后写讲义前会抓取并下载一次投影截图,把幻灯片上的定义、公式、图例与例题"
202
+ + "同字幕对照写入讲义;模型看不到本地图片时不得臆造幻灯片文字,只在文末列出截图索引。"
203
+ + "只需要插图、不需要以投影为内容来源时保持关闭。",
204
+ )
205
+ .default(false)
206
+ .volatile(),
177
207
  embedSlideImages: Schema.boolean()
178
208
  .description(
179
- "把投影截图引用进讲义(需先开启「PPT 投影抓取」;默认关闭,节省下载时间与视觉 token)",
209
+ "把投影截图引用进讲义(需先开启「PPT 投影抓取」;默认关闭,节省下载时间与视觉 token):"
210
+ + "只控制是否插入 3–8 张关键页,不改变「投影是否作为内容来源」。",
180
211
  )
181
212
  .default(false)
182
213
  .volatile(),
@@ -196,6 +227,20 @@ const Config = Schema.object({
196
227
  )
197
228
  .default(true)
198
229
  .volatile(),
230
+ typstPath: Schema.string()
231
+ .description(
232
+ "Typst 可执行文件(默认留空):留空时依次查找插件缓存、PATH 与常见安装目录;"
233
+ + "填写绝对路径可固定版本或使用自建二进制。",
234
+ )
235
+ .default("")
236
+ .volatile(),
237
+ typstMirror: Schema.string()
238
+ .description(
239
+ "Typst 下载镜像前缀(默认留空):例如 https://ghfast.top/;自动安装 Typst 时加在"
240
+ + " GitHub Release URL 前,留空直连 GitHub。",
241
+ )
242
+ .default("")
243
+ .volatile(),
199
244
  });
200
245
 
201
246
  /** Optional tool groups; every other tool belongs to the always-on transcript core. */
@@ -244,9 +289,40 @@ function featureFlags(config = {}) {
244
289
  renderPdf: value("renderPdf") !== false,
245
290
  enableStudyNotes: value("enableStudyNotes") === true,
246
291
  enableSlides,
292
+ slidesAsSource: enableSlides && value("slidesAsSource") === true,
247
293
  embedSlideImages: enableSlides && value("embedSlideImages") === true,
248
294
  enableLoginTools: value("enableLoginTools") === true,
249
295
  typstAutoInstall: value("typstAutoInstall") !== false,
296
+ registerSkill: value("registerSkill") !== false,
297
+ };
298
+ }
299
+
300
+ /**
301
+ * Project the plugin configuration onto the Python bridge options.
302
+ *
303
+ * This runs once at start-up and again on every live settings edit, so the
304
+ * agent never keeps talking to a child process configured by a stale value.
305
+ * Strings are read through `readSetting` as well because `.volatile()` fields
306
+ * are `{ get() }` references too.
307
+ *
308
+ * @param {object} config plugin config (or `{}`)
309
+ * @returns {object} options accepted by {@link ZjuBridge}
310
+ */
311
+ function bridgeOptions(config = {}) {
312
+ const flags = featureFlags(config);
313
+ const timeout = Number(readSetting(config, "timeoutMs"));
314
+ return {
315
+ python: String(readSetting(config, "python") ?? ""),
316
+ timeoutMs: Number.isFinite(timeout) && timeout > 0 ? timeout : 120000,
317
+ enableSlides: flags.enableSlides,
318
+ slidesAsSource: flags.slidesAsSource,
319
+ embedSlideImages: flags.embedSlideImages,
320
+ enableStudyNotes: flags.enableStudyNotes,
321
+ enableLoginTools: flags.enableLoginTools,
322
+ renderPdf: flags.renderPdf,
323
+ typstAutoInstall: flags.typstAutoInstall,
324
+ typstPath: String(readSetting(config, "typstPath") ?? ""),
325
+ typstMirror: String(readSetting(config, "typstMirror") ?? ""),
250
326
  };
251
327
  }
252
328
 
@@ -269,14 +345,32 @@ const SLOW_TOOL_TIMEOUT_MS = 600000;
269
345
  /** Typst compiles a notebook and renders every page to PNG: also slow. */
270
346
  const COMPILE_TOOL_TIMEOUT_MS = 300000;
271
347
 
348
+ /** PDF-capable tools may trigger a one-time Typst download/compile. */
349
+ const PDF_TOOL_NAMES = new Set([
350
+ "zju_write_note",
351
+ "zju_check_note",
352
+ "zju_build_study_notes",
353
+ "zju_doctor",
354
+ ]);
355
+
356
+ /** Resolve one tool's effective timeout from the user setting and its floor. */
357
+ function toolTimeoutFor(toolName, timeoutMs) {
358
+ if (toolName === "zju_fetch_slides" || toolName === "zju_login") {
359
+ return Math.max(timeoutMs, SLOW_TOOL_TIMEOUT_MS);
360
+ }
361
+ if (PDF_TOOL_NAMES.has(toolName)) {
362
+ return Math.max(timeoutMs, COMPILE_TOOL_TIMEOUT_MS);
363
+ }
364
+ return timeoutMs;
365
+ }
366
+
272
367
  const SYSTEM_PROMPT = [
273
368
  "适用范围:仅处理浙大智云课堂(classroom.zju.edu.cn)回放与讲义任务;其他任务请忽略本段。",
274
- "主链路:把链接或 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。",
369
+ "主链路:把链接或 sub_id 直接交给 zju_fetch_transcript(默认 per_minute;长课 chunked;同一节课只抓一次,per_segment 仅在确实需要秒级时间戳时用)→ 按下面的材料规则补齐投影或课件 → zju_write_note 一次写入。write_note 会自动命名、拒绝静默覆盖、修公式、校验,并按设置自动排版同名 PDF;不要再调 zju_parse_url,也不要对同一份讲义重复调 zju_check_note。",
275
370
  "讲义默认按「复习版」写:每节保留 [HH:MM];老师讲过的例题整理成「题目 → 切入点 → 关键步骤 → 易错点」,本节没有例题就写「本节无例题」,不要编题;文末给 3–5 道自测题(答案用多行 <details> 折叠)与 5–10 条考点预测。",
276
371
  "例题/定理/定义/证明要写成行首标记([例] 标题 —— 正文 / [定理] … / [定义] … / [证明] …),"
277
372
  + "不要写成 `#### 例 1:…` 或 `**证明**`——那种写法在 PDF 里只是小标题和粗体,排不出方框(工具会报 pseudo_box 警告)。",
278
373
  "用户只说「整理这节课」时按完整链路一次做完,不要只交字幕摘要;只有明确说「只要速记 / 只要 Markdown」时才省略这些增强内容。",
279
- "ASR 可靠度低时按 Skill 的数学规范复算,并在讲义开头写明需要人工复核的时间点;公式必须符合 Skill 的「公式书写规范」。",
280
374
  "交付时给出 Markdown 路径;有 PDF 时一并给出 PDF 路径。不要声称看过自己无法查看的图片。",
281
375
  "隐私边界:登录态只在本机安全保存或进程内存中使用;工具不接受、也不回显 Cookie / 密码 / token 明文;不要向用户索要 Cookie,或把它写进对话、文件、命令。",
282
376
  "字幕先匿名;401/403 时先自动使用本机登录态;仍失败就调用 zju_login(url=<这节课链接>) 打开独立登录窗口,让用户在窗口里正常登录(成功后自动关闭并安全保存),然后重试字幕一次。不要让用户开开发者工具、手工配置 Cookie 文件,也不要把 401/403 直接归因校园网。",
@@ -285,18 +379,20 @@ const SYSTEM_PROMPT = [
285
379
  /**
286
380
  * The note-writing instruction for projected-slide images.
287
381
  *
288
- * Off by default: downloading a deck and feeding screenshots to a vision
289
- * model is materially slower and more expensive than a transcript-only note.
382
+ * `embedSlideImages` only decides whether screenshots go into the Markdown;
383
+ * whether the projection is a *content source* is `slidesAsSource`. Keeping
384
+ * the two apart matters because "read the slides" and "paste the slides" have
385
+ * different failure modes: a host without vision can still use the list as an
386
+ * index, but it must not pretend to have read an image.
290
387
  */
291
388
  function slideImageRule(enabled) {
292
389
  return enabled
293
- ? "讲义插图模式已开启:写讲义前默认抓一次投影(整节课只抓一次),"
294
- + "从返回的截图里挑 3–8 张关键页(定义、示意图、公式推导、例题),"
390
+ ? "讲义插图模式已开启:从下载结果里挑 3–8 张关键页(定义、示意图、公式推导、例题),"
295
391
  + "按讲义所在目录的相对路径插入 Markdown(例如 ![第 12 页](../ppt-assets/<sub_id>/images/slide-0012.jpg));"
296
392
  + "如果宿主不能查看本地图片,不要把截图当作已读文字,只在文末列出截图索引。"
297
- + "用户明确说不要投影时才跳过;不要一次塞入全部截图或图片字节。"
298
- : "讲义插图模式关闭(默认,节省下载时间与 token):不要主动下载或插入截图;"
299
- + "用户明确要求看图时再调用 zju_fetch_slides(download=true),并在文末列截图索引。";
393
+ + "不要一次塞入全部截图或图片字节。"
394
+ : "讲义插图模式关闭(节省下载时间与 token):不要插入截图;"
395
+ + "用户明确要求看图时再调用 zju_fetch_slides(download=true, confirm=true),并在文末列截图索引。";
300
396
  }
301
397
 
302
398
  /**
@@ -306,15 +402,65 @@ function slideImageRule(enabled) {
306
402
  * registered, so the prompt must not lead the model into calling them (or
307
403
  * reading browser cookies "just in case"). The transcript path never depends
308
404
  * on any of this.
405
+ *
406
+ * When the module is on, the prompt always names the projected-slide step in
407
+ * the material order. The previous wording only asked for a call when
408
+ * `embedSlideImages` was on, so a user who enabled "抓取投影截图" alone saw the
409
+ * agent skip the tool entirely. That is a configuration inconsistency, not a
410
+ * model preference: the switch promised capture and the prompt forbade it.
309
411
  */
310
- function slidesFeatureRule(enableSlides, embedSlideImages) {
412
+ function slidesFeatureRule(enableSlides, embedSlideImages, slidesAsSource = false) {
311
413
  if (!enableSlides) {
312
414
  return "PPT 投影抓取已关闭(插件设置 enableSlides=false):本会话没有注册 zju_fetch_slides,"
313
415
  + "不要尝试抓取或引用投影截图,也不要为了投影额外读取浏览器 Cookie;"
314
416
  + "字幕鉴权由字幕工具自行处理,需要登录时用 zju_login。只用语音字幕与本地课件生成讲义。"
315
417
  + "用户明确要投影画面时,告诉他在插件设置里打开「启用 PPT 投影抓取」后重试。";
316
418
  }
317
- return "PPT 投影抓取已开启(插件设置 enableSlides=true):" + slideImageRule(embedSlideImages);
419
+ if (slidesAsSource) {
420
+ return "PPT 投影抓取已开启(enableSlides=true),投影作为讲义来源已开启(slidesAsSource=true):"
421
+ + "写讲义前必须先调用一次 zju_fetch_slides(url_or_sub_id=<回放链接>, download=true, confirm=true),"
422
+ + "整节课只抓一次,不要因为一次失败就反复重试或更换后端。"
423
+ + "把投影当作与字幕并列的内容来源:定义、公式、图例、例题按幻灯片与字幕互相校正,写进对应小节。"
424
+ + "如果当前宿主能读取本地图片,逐页查看关键截图后再写;不能读图时不要臆造幻灯片文字,"
425
+ + "只在文末列「课堂投影截图索引」并说明哪些内容未核对。"
426
+ + "登录失败时按工具返回调用 zju_login 后重试一次;仍失败就降级为纯字幕,并在讲义开头注明投影未使用。"
427
+ + (embedSlideImages
428
+ ? "讲义插图模式已开启:再挑 3–8 张关键页按相对路径插入。"
429
+ : "本次不插入截图(embedSlideImages=false),但投影内容仍必须用于正文。");
430
+ }
431
+ if (embedSlideImages) {
432
+ return "PPT 投影抓取已开启(enableSlides=true,讲义插图模式已开启):"
433
+ + "写讲义前先调用一次 zju_fetch_slides(download=true, confirm=true)(整节课只抓一次),"
434
+ + "从返回的截图里挑 3–8 张关键页插入对应小节;"
435
+ + "如果宿主不能查看本地图片,只把截图当作索引,不要臆造幻灯片文字。"
436
+ + "用户明确说不要投影时才跳过。";
437
+ }
438
+ return "PPT 投影抓取已开启(enableSlides=true,slidesAsSource=false、embedSlideImages=false):"
439
+ + "写讲义前调用一次 zju_fetch_slides(download=false) 核对投影清单(整节课只抓一次);"
440
+ + "不要下载截图、不要插入图片,也不要把截图当作内容来源。"
441
+ + "如果只是登录态不可用,跳过投影并用字幕照常生成讲义,不要为了投影打断用户。"
442
+ + "用户明确要看投影时再传 download=true, confirm=true 并列出截图索引。";
443
+ }
444
+
445
+ /**
446
+ * The material order for this session, stated once and before the generic
447
+ * pipeline. It is what makes "投影讲义" presets behave like a real pipeline
448
+ * step instead of an optional appendix the model may or may not read.
449
+ */
450
+ function materialRule(flags) {
451
+ if (!flags.enableSlides) return "";
452
+ if (flags.slidesAsSource) {
453
+ return "材料顺序(投影讲义模式):zju_fetch_transcript 抓字幕 → "
454
+ + "zju_fetch_slides(download=true, confirm=true) 抓一次投影 →"
455
+ + "(可选 zju_extract_courseware)→ zju_write_note。投影是必做材料,不是可选项;整节课只抓一次。";
456
+ }
457
+ if (flags.embedSlideImages) {
458
+ return "材料顺序:zju_fetch_transcript 抓字幕 → "
459
+ + "zju_fetch_slides(download=true, confirm=true) 抓一次投影 →"
460
+ + "(可选 zju_extract_courseware)→ zju_write_note。投影截图用于插图,整节课只抓一次。";
461
+ }
462
+ return "材料顺序:zju_fetch_transcript 抓字幕 → zju_fetch_slides(download=false) 核对一次投影清单 →"
463
+ + "(可选 zju_extract_courseware)→ zju_write_note。投影清单不下载、不插图。";
318
464
  }
319
465
 
320
466
  function pdfFeatureRule(enabled) {
@@ -328,15 +474,27 @@ function pdfFeatureRule(enabled) {
328
474
  + "用户要 PDF 时提示他在插件设置里打开「自动排版 PDF 讲义」。";
329
475
  }
330
476
 
331
- function studyFeatureRule(enabled) {
332
- return enabled
333
- ? "填空笔记已开启:写完讲义后默认再出一份填空版(用户只要 Markdown/PDF 或明确说不用时跳过)——"
334
- + "zju_build_study_notes(mode=draft) 先把讲义搬成底稿:底稿是**纯 Markdown**(公式保持 LaTeX,表格保持 Markdown),"
335
- + "你只需补 [直觉]/[练习]/[边注] 占位符、正文该挖空的地方写 ____,**不要重写全文**;"
336
- + "挖空别一处一处改:把所有 {old, new} 交给 mode=patch 一次写回(省掉十几次单条编辑);"
337
- + "然后 mode=compile 一次性转 Typst 并出 PDF(PDF 会落在底稿同目录)。排版规范交给 scholia-notes Skill。"
338
- : "填空笔记已关闭(插件设置 enableStudyNotes=false):本会话没有注册 zju_build_study_notes,"
477
+ function studyFeatureRule(enabled, skillEnabled = true) {
478
+ if (!enabled) {
479
+ return "填空笔记已关闭(插件设置 enableStudyNotes=false):本会话没有注册 zju_build_study_notes,"
339
480
  + "不要调用或假装调用;用户需要时提示他在插件设置里打开「填空式学习笔记」。";
481
+ }
482
+ const tail = skillEnabled
483
+ ? "排版规范交给 scholia-notes Skill。"
484
+ : "排版规范按工具说明与通用排版规范执行(随包 Skill 已关闭)。";
485
+ return "填空笔记已开启:写完讲义后默认再出一份填空版(用户只要 Markdown/PDF 或明确说不用时跳过)——"
486
+ + "zju_build_study_notes(mode=draft) 先把讲义搬成底稿:底稿是**纯 Markdown**(公式保持 LaTeX,表格保持 Markdown),"
487
+ + "你只需补 [直觉]/[练习]/[边注] 占位符、正文该挖空的地方写 ____,**不要重写全文**;"
488
+ + "挖空别一处一处改:把所有 {old, new} 交给 mode=patch 一次写回(省掉十几次单条编辑);"
489
+ + "然后 mode=compile 一次性转 Typst 并出 PDF(PDF 会落在底稿同目录)。" + tail;
490
+ }
491
+
492
+ function formulaFeatureRule(skillEnabled) {
493
+ return skillEnabled
494
+ ? "ASR 可靠度低时按 Skill 的数学规范复算,并在讲义开头写明需要人工复核的时间点;"
495
+ + "公式必须符合 Skill 的「公式书写规范」。"
496
+ : "ASR 可靠度低时按通用数学规范复算,并在讲义开头写明需要人工复核的时间点;"
497
+ + "公式使用标准 LaTeX,不臆造符号。";
340
498
  }
341
499
 
342
500
  function loginFeatureRule(enabled) {
@@ -352,15 +510,25 @@ function loginFeatureRule(enabled) {
352
510
  + "zju_read_browser_cookie,不要调用。" + core + "投影抓取也会自行解析登录态。";
353
511
  }
354
512
 
513
+ function skillFeatureRule(enabled) {
514
+ if (enabled) return "";
515
+ return "随包 Skill 未注册(插件设置 registerSkill=false):不要假设 zju-lecture-summarizer "
516
+ + "的详细规范可用,按本条提示与工具说明完成字幕 → 讲义链路;"
517
+ + "用户需要工作流说明时,告诉他可在设置里打开「注册随包 Skill」。";
518
+ }
519
+
355
520
  /** Build the (short) task prompt for one configuration. */
356
521
  function buildSystemPrompt(flags) {
357
522
  return [
358
523
  SYSTEM_PROMPT,
359
- slidesFeatureRule(flags.enableSlides, flags.embedSlideImages),
524
+ materialRule(flags),
525
+ slidesFeatureRule(flags.enableSlides, flags.embedSlideImages, flags.slidesAsSource),
360
526
  pdfFeatureRule(flags.renderPdf),
361
- studyFeatureRule(flags.enableStudyNotes),
527
+ studyFeatureRule(flags.enableStudyNotes, flags.registerSkill),
528
+ formulaFeatureRule(flags.registerSkill),
362
529
  loginFeatureRule(flags.enableLoginTools),
363
- ].join("\n");
530
+ skillFeatureRule(flags.registerSkill),
531
+ ].filter(Boolean).join("\n");
364
532
  }
365
533
 
366
534
  const jsonOutput = {
@@ -429,13 +597,41 @@ function splitFrontmatter(raw) {
429
597
  return { description, body };
430
598
  }
431
599
 
600
+ /**
601
+ * The mode-specific paragraph appended to the transcript Skill.
602
+ *
603
+ * `SLIDES.md` documents every projection mode, but the model reads a Skill
604
+ * selectively. Stating this session's mode at the end keeps "仅注册 / 插图 /
605
+ * 讲义素材" from being confused with one another, and it is regenerated when
606
+ * the settings change (`syncSkills` includes `slidesAsSource` in its signature).
607
+ */
608
+ function slidesModeAppendix(flags) {
609
+ if (!flags.enableSlides) return "";
610
+ if (flags.slidesAsSource) {
611
+ return "## 本次会话:投影作为讲义来源\n"
612
+ + "系统提示已开启 slidesAsSource。写讲义前必须先调用一次 "
613
+ + "zju_fetch_slides(download=true, confirm=true),整节课只抓一次;"
614
+ + "把幻灯片上的定义、公式、图例、例题与字幕对照写进正文。"
615
+ + "宿主不能读图时不要臆造幻灯片文字,只在文末列截图索引并说明哪些内容未核对。"
616
+ + "登录失败按提示调用 zju_login 后重试一次,仍失败则降级为纯字幕并在讲义开头注明。";
617
+ }
618
+ if (flags.embedSlideImages) {
619
+ return "## 本次会话:投影插图\n"
620
+ + "系统提示已开启 embedSlideImages。写讲义前抓一次投影(download=true, confirm=true),"
621
+ + "挑 3–8 张关键页插入对应小节;宿主不能读图时不要臆造幻灯片文字,只在文末列索引。";
622
+ }
623
+ return "## 本次会话:投影清单\n"
624
+ + "系统提示已开启 enableSlides。写讲义前调用一次 zju_fetch_slides(download=false) 核对清单;"
625
+ + "不下载、不插图、不把截图当内容来源;登录态不可用时直接跳过投影,用字幕照常生成讲义。";
626
+ }
627
+
432
628
  /**
433
629
  * Read the bundled skills for in-memory registration.
434
630
  *
435
631
  * The plugin is installed under a pnpm store path, so the skill files ship
436
632
  * inside the package and are read from there; nothing is copied into the user's
437
633
  * home directory. The projection appendix is concatenated only when the
438
- * optional module is enabled.
634
+ * optional module is enabled, followed by this session's projection mode.
439
635
  *
440
636
  * @param {object|boolean} configOrSlides plugin config (or a bare slides flag)
441
637
  * @returns {Array<object>} skill descriptors ready for the registry
@@ -456,6 +652,7 @@ function readBundledSkills(configOrSlides = {}) {
456
652
  const raw = readFileSync(file, "utf8");
457
653
  const { description, body } = splitFrontmatter(raw);
458
654
  let content = body;
655
+ const carriesSlides = spec.appendices.some((appendix) => appendix.when === "slides");
459
656
  for (const appendix of spec.appendices) {
460
657
  if (appendix.when === "slides" && !flags.enableSlides) continue;
461
658
  const appendixFile = appendix.path;
@@ -466,6 +663,10 @@ function readBundledSkills(configOrSlides = {}) {
466
663
  const text = splitFrontmatter(readFileSync(appendixFile, "utf8")).body.trim();
467
664
  if (text) content = `${body.trimEnd()}\n\n---\n\n${text}\n`;
468
665
  }
666
+ if (carriesSlides && flags.enableSlides) {
667
+ const modeNote = slidesModeAppendix(flags);
668
+ if (modeNote) content = `${content.trimEnd()}\n\n---\n\n${modeNote}\n`;
669
+ }
469
670
  const descriptor = {
470
671
  name: spec.name,
471
672
  description: description || spec.fallbackDescription,
@@ -516,12 +717,14 @@ function findShadowingSkillCopy(skillName) {
516
717
  *
517
718
  * @returns {void}
518
719
  */
519
- function warnOnShadowingSkillCopy(flags = featureFlags({})) {
720
+ function warnOnShadowingSkillCopy(flags = featureFlags({}), warned = new Set()) {
520
721
  for (const spec of SKILL_SPECS) {
521
722
  if (spec.when === "slides" && !flags.enableSlides) continue;
522
723
  if (spec.when === "study" && !flags.enableStudyNotes) continue;
724
+ if (warned.has(spec.name)) continue;
523
725
  const shadow = findShadowingSkillCopy(spec.name);
524
726
  if (!shadow) continue;
727
+ warned.add(spec.name);
525
728
  let stale = true;
526
729
  let bundledHash = "?";
527
730
  let shadowHash = "?";
@@ -545,52 +748,51 @@ function warnOnShadowingSkillCopy(flags = featureFlags({})) {
545
748
  }
546
749
 
547
750
  function apply(ctx, config = {}) {
548
- // One normalised feature object drives tools, skills and the prompt. The
549
- // optional modules default to off, so the verified transcript path never
550
- // pays for a login/cookie/screenshot/typst dependency it did not ask for.
551
- const flags = featureFlags(config);
552
- const timeoutMs = Number(readSetting(config, "timeoutMs")) > 0
553
- ? Number(readSetting(config, "timeoutMs"))
554
- : 120000;
555
- const bridge = new ZjuBridge({
556
- python: readSetting(config, "python"),
557
- timeoutMs,
558
- ...flags,
559
- });
751
+ // One normalised configuration drives tools, skills, prompt and Python
752
+ // child processes. `.volatile()` fields are live references, so the same
753
+ // reader is used at start-up and again after every settings edit.
754
+ const bridge = new ZjuBridge(bridgeOptions(config));
560
755
  ctx.effect(() => () => bridge.dispose());
561
756
 
562
- if (readSetting(config, "registerSkill") !== false) {
563
- const skills = readBundledSkills(flags);
564
- if (skills.length) {
565
- // Registration is synchronous, so it lands during apply() as the skill
566
- // registry expects. Disposal is owned by the plugin fiber.
567
- ctx.inject(["skills"], (ctx) => {
568
- for (const skill of skills) {
569
- ctx.skills.register(skill);
570
- }
571
- });
572
- warnOnShadowingSkillCopy(flags);
573
- } else {
574
- process.stderr.write("[zju-lecture] 未找到随包 Skill(skills/ 目录为空)\n");
757
+ let toolsScope = null;
758
+ let toolDisposers = [];
759
+ let toolSignature = "";
760
+ let skillsScope = null;
761
+ let skillDisposers = [];
762
+ let skillSignature = "";
763
+ const warnedShadowing = new Set();
764
+
765
+ /**
766
+ * Reconcile the registered tool set with the current configuration.
767
+ *
768
+ * dsh applies a volatile-only settings edit in place: it updates the refs
769
+ * and emits `loader/volatile-update` instead of re-running `apply()`. Without
770
+ * this listener a switch flipped in the GUI would only take effect after a
771
+ * full restart, even though the settings page says it was saved.
772
+ */
773
+ const syncTools = () => {
774
+ if (!toolsScope) return;
775
+ const tools = registerableTools(featureFlags(config));
776
+ const timeoutMs = bridge.timeoutMs;
777
+ // Only tool identity and timeout are baked into a registration; prompt-only
778
+ // switches must not churn the registry on every save.
779
+ const signature = JSON.stringify({
780
+ timeoutMs,
781
+ names: tools.map((tool) => tool.name),
782
+ });
783
+ if (signature === toolSignature) return;
784
+ toolSignature = signature;
785
+ for (const dispose of toolDisposers.splice(0).reverse()) {
786
+ try {
787
+ dispose();
788
+ } catch {
789
+ /* a tool may already have been unregistered with its scope */
790
+ }
575
791
  }
576
- }
577
-
578
- ctx.inject(["tools"], (ctx) => {
579
- for (const tool of registerableTools(flags)) {
792
+ for (const tool of tools) {
580
793
  const present = TOOL_PRESENT[tool.name] || { title: tool.name, kind: "read" };
581
- // PDF 链路可能先触发一次 Typst 下载(约 20 MB),所以写讲义 / 补排版与
582
- // 编译、安装一样给足时间;否则慢网下会把一次正常安装误判成超时。
583
- const pdfCapable = tool.name === "zju_write_note"
584
- || tool.name === "zju_check_note"
585
- || tool.name === "zju_build_study_notes"
586
- || tool.name === "zju_doctor";
587
- const slowTool = tool.name === "zju_fetch_slides" || tool.name === "zju_login";
588
- const toolTimeoutMs = slowTool
589
- ? Math.max(timeoutMs, SLOW_TOOL_TIMEOUT_MS)
590
- : pdfCapable
591
- ? Math.max(timeoutMs, COMPILE_TOOL_TIMEOUT_MS)
592
- : timeoutMs;
593
- ctx.tools.register(defineTool({
794
+ const toolTimeoutMs = toolTimeoutFor(tool.name, timeoutMs);
795
+ toolDisposers.push(toolsScope.tools.register(defineTool({
594
796
  name: tool.name,
595
797
  description: tool.description,
596
798
  parameters: tool.parameters,
@@ -606,17 +808,86 @@ function apply(ctx, config = {}) {
606
808
  const text = await bridge.call(tool.name, args ?? {}, { timeoutMs: toolTimeoutMs });
607
809
  return { text };
608
810
  },
609
- }));
811
+ })));
812
+ }
813
+ };
814
+
815
+ /** Reconcile the in-memory Skill set with the projection / study switches. */
816
+ const syncSkills = () => {
817
+ if (!skillsScope) return;
818
+ const flags = featureFlags(config);
819
+ const signature = JSON.stringify({
820
+ registerSkill: flags.registerSkill,
821
+ enableSlides: flags.enableSlides,
822
+ slidesAsSource: flags.slidesAsSource,
823
+ embedSlideImages: flags.embedSlideImages,
824
+ enableStudyNotes: flags.enableStudyNotes,
825
+ });
826
+ if (signature === skillSignature) return;
827
+ skillSignature = signature;
828
+ for (const dispose of skillDisposers.splice(0).reverse()) {
829
+ try {
830
+ dispose();
831
+ } catch {
832
+ /* the scope may already be torn down */
833
+ }
834
+ }
835
+ if (!flags.registerSkill) return;
836
+ const skills = readBundledSkills(flags);
837
+ if (!skills.length) {
838
+ process.stderr.write("[zju-lecture] 未找到随包 Skill(skills/ 目录为空)\n");
839
+ return;
610
840
  }
841
+ // Registration is synchronous, so it lands during apply() as the skill
842
+ // registry expects. Disposal is owned by this plugin's fiber.
843
+ for (const skill of skills) {
844
+ skillDisposers.push(skillsScope.skills.register(skill));
845
+ }
846
+ warnOnShadowingSkillCopy(flags, warnedShadowing);
847
+ };
848
+
849
+ /**
850
+ * Apply a live settings edit to everything the agent can observe.
851
+ *
852
+ * The prompt reads the refs through a thunk on every assembly, so it needs
853
+ * no re-registration; tools, skills and the Python child environment do.
854
+ */
855
+ const resync = () => {
856
+ bridge.configure(bridgeOptions(config));
857
+ syncTools();
858
+ syncSkills();
859
+ };
860
+ if (typeof ctx.on === "function") {
861
+ ctx.on("loader/volatile-update", resync);
862
+ }
863
+
864
+ ctx.inject(["skills"], (scoped) => {
865
+ skillsScope = scoped;
866
+ syncSkills();
867
+ ctx.effect(() => () => {
868
+ skillsScope = null;
869
+ for (const dispose of skillDisposers.splice(0).reverse()) dispose?.();
870
+ });
871
+ });
872
+
873
+ ctx.inject(["tools"], (scoped) => {
874
+ toolsScope = scoped;
875
+ syncTools();
876
+ ctx.effect(() => () => {
877
+ toolsScope = null;
878
+ for (const dispose of toolDisposers.splice(0).reverse()) dispose?.();
879
+ });
611
880
  });
612
881
 
613
- ctx.inject(["systemPrompt"], (ctx) => {
882
+ ctx.inject(["systemPrompt"], (scoped) => {
614
883
  ctx.effect(() => {
615
- const dispose = ctx.systemPrompt.section({
884
+ const dispose = scoped.systemPrompt.section({
616
885
  name,
617
886
  order: 72,
618
887
  interpolate: false,
619
- text: buildSystemPrompt(flags),
888
+ // A thunk, not a string: dsh assembles the prompt for every request,
889
+ // so the model reads the settings that are current at that moment.
890
+ text: () => buildSystemPrompt(featureFlags(config)),
620
891
  });
621
892
  return () => {
622
893
  if (typeof dispose === "function") dispose();
@@ -629,13 +900,16 @@ export {
629
900
  Config,
630
901
  SYSTEM_PROMPT,
631
902
  apply,
903
+ bridgeOptions,
632
904
  buildSystemPrompt,
633
905
  featureFlags,
906
+ materialRule,
634
907
  name,
635
908
  readBundledSkills,
636
909
  readSetting,
637
910
  registerableTools,
638
911
  slideImageRule,
639
912
  slidesFeatureRule,
913
+ slidesModeAppendix,
640
914
  splitFrontmatter,
641
915
  };