dsh-aha-tutor 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to this plugin are recorded here. Versions follow [SemVer](https://semver.org/); GitHub Release notes for each version live in `docs/releases/`.
 
+## 1.8.0 - 2026-10-26
+
+### Added
+
+- **Scanned pages and pictures are read**: a PDF page without text of its own (a scan, a photo, a full-page figure), a Word document made mostly of pictures, a slide that is only a picture, and an uploaded photo have their text read by a model chosen in Aha settings that can see images (marked 🖼; DeepSeek-V4.1-Flash can): the quick route first, else the teaching route, never another model. Pages are read three at a time; the upload shows how many are done and can be cancelled, and up to 200 pages or pictures of a file are read. The text keeps its page or slide, so courses, study tools, the library search and citations use it like any other. Pages that failed (and why), pages left over and pages a model without vision could not read are named under the material. A scan without a model that sees images is refused with a note on which model to pick, instead of "no text". A photo whose text was read works in the study tools too, and stays a picture for models that see images. Black-and-white scans (CCITT, JBIG2) and JPEG 2000 pages decode with pdf.js's own WebAssembly decoders.
+
+### Fixed
+
+- **DSH 0.2.1-rc.3 refused the tutor preset**: the plugin card said 加载失败 (`tool-fs-search … sampleOverCapGlobResults missing required value`), because rc.3 requires that setting and gives it no default. The preset now sets it as DSH's own presets do; DSH 0.2.1-rc.2 still loads it.
+- **A correction no longer stalls the lesson**: after **See the correction** on a written-out working, the classroom started the correction's first step twice in one go; Chromium dropped the second narration and held the system voice, so the lesson sat at "playing" until Pause and Play. The step now starts once, a sentence spoken right after a cancel waits for the next task, and a system voice that does not start (tried twice) or never reports an end is let go instead of holding the lesson; one that stalls twice in a row is turned off with a note.
+- **Multi-select questions take several answers**: a practice or quiz question with several right options could show 多选 and take one answer. The quiz prompt never gave the question format, and a question the model wrote as a single choice with several answers kept only the first. Practice and quiz prompts now give the format; such a question, one whose kind is named like "multi-select", or one whose prompt says to pick several becomes multi-select, answers like "A, C" are understood, and a multi-select question says **Select all that apply**.
+
+## 1.7.0 - 2026-10-22
+
+### Added
+
+- **How each lesson is taught**: every lesson of a new blueprint has a depth, one of building intuition, making the idea precise, deriving it, applying it and going further, shown beside the lesson on the course page and in the blueprint editor, where it can be changed. The teacher teaches the lesson that way. The sample courses show theirs.
+- **Your name in class**: the profile asks what the tutor should call you, and a lesson's opening says it once.
+- **A handout for every lesson**: **Handout** above a lesson (and **Handout of this lesson** when it ends) turns what its board taught into one printable page: what the lesson was about, the key points each with a line you could repeat to a friend, a worked example step by step, common mistakes with their fix, a glossary and three questions to check yourself. It is made on request (without the model thinking first) and kept; **Print** opens the answers.
+- **Add materials to a course**: **Add materials** in a course's ⋯ menu, or in the outline editor, takes materials from the library or uploaded there, with an optional note on how to use them. The teacher reads them and proposes changes to the outline, such as new lessons where they fit or lessons taken deeper, shown like any other proposal; applying it keeps the progress of lessons left alone and attaches the materials, so later lessons cite them. A course can use up to 12 materials (8 before).
+- **Search the library**: typing above the library filters it by title and topic; Enter searches the text of every material at once and lists the best passages with their material, page or slide and the matching words marked, and choosing one shows its material. It runs on this computer without the model; the index is kept until the library changes.
+- **A tour of the classroom**: the first classroom opened in a browser starts with a six-step tour (the board, the controls, raising a hand, explaining differently, challenging a step and the side panel), each part lit up in turn with a card saying what it does. The lesson starts when the tour ends; it can be skipped, stepped with the arrow keys, and seen again from **?** above the classroom. The narrow conversation board has none.
+- **Hold V to ask**: in a lesson, instant answers or an explainer short, hold V while you speak and let go, or tap V, speak and tap it again. The lesson pauses, the question box opens if the side panel was folded, and the question is recorded through DSH's Voice input like the microphone button; the words land in the box to check before asking. After a spoken question is sent, or Escape in the box, the keyboard is back with the lesson (space, arrows and V). The board beside a DSH conversation leaves V alone, so typing there never records. The tooltips of Raise hand and the microphone name the key, and the tour mentions it.
+- **The blueprint grows as a mind map**: while the teacher writes a blueprint, the outline is drawn as a map that grows to the right (course, units, lectures, lessons) and follows the newest lesson until you drag or zoom it; **Back to the newest** resumes. The editor shows a new blueprint as the map, with each lesson's depth and minutes, and switches to the list for editing; choosing a lesson on the map opens it in the list.
+
+### Changed
+
+- Printing a cheat sheet or a handout prints only it, across as many pages as it needs, instead of one clipped page beside the hidden app.
+- **Something wrong with this question?** also grades the earlier answers to a question it fixes: another round of practice, a review or the lesson's own check. Each recorded answer now keeps which question it answered and how, and when a check fixes the question, each earlier answer takes its grade against the fixed one, with mastery and the review schedule recomputed as for the answer checked. Under a wrong question a grade can go up or down; under an unclear one it only goes up, since the earlier answer may have been right under the other reading. Short and written-out answers go to the grader again, the latest three. The check says how many earlier answers it graded again. Answers recorded before this version, and those older than the latest 50, keep their grades.
+
+### Fixed
+
+- A microphone that finished opening after its question box had closed (the learner left the page meanwhile) stayed on; it is now closed at once.
+
 ## 1.6.0 - 2026-10-22
 
 ### Added

package/README.en.md

@@ -11,6 +11,7 @@
 [![CI](https://github.com/BaronCyrus/dsh-aha-tutor/actions/workflows/ci.yml/badge.svg)](https://github.com/BaronCyrus/dsh-aha-tutor/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/dsh-aha-tutor?logo=npm&label=npm)](https://www.npmjs.com/package/dsh-aha-tutor)
 [![Total npm downloads](https://img.shields.io/npm/d18m/dsh-aha-tutor?logo=npm&label=total%20downloads)](https://www.npmjs.com/package/dsh-aha-tutor)
+[![GitHub stars](https://img.shields.io/github/stars/BaronCyrus/dsh-aha-tutor?style=flat&logo=github&label=stars)](https://github.com/BaronCyrus/dsh-aha-tutor/stargazers)
 [![MIT](https://img.shields.io/badge/license-MIT-111111.svg)](LICENSE)
 
 [What it does](#what-it-does) · [Install](#install) · [Quick start](#quick-start) · [Voices](#voices) · [Privacy](#privacy-and-data) · [FAQ](#faq) · [Support](#support-the-author)
@@ -27,8 +28,8 @@
 | **Handwriting chalkboard lessons** | Narration (voice + captions) while the board fills up in a handwriting font with points, formulas, diagrams, charts and, when it helps, a small animation; each item is written as its sentence is spoken and highlighted while it is discussed; curves given by a formula are computed point by point, with sliders for their parameters; the lesson's pages sit on one canvas you can drag and zoom while the view follows the teacher, and a side panel shows the lesson's goals and a transcript; pause, rewind and change speed any time |
 | **Quick checks that adapt** | At key moments the lesson stops for a question and asks how sure you are. Lucky guesses, hesitation and confident mistakes count differently; a lesson with a calculation asks you to write out your working and corrects it on the board. A revisit lesson is added automatically for concepts that did not stick |
 | **Raise your hand, hear it again** | Ask anything mid-lesson, typed or spoken (recognized on your computer by DSH's Voice input), and the tutor answers on the board, then picks up where it left off; or have a step re-explained with an analogy, a drawing, an example, more simply or in more depth. Think a step is wrong? Ask the teacher to check it: a real mistake is corrected at the board and fixed in the lesson, and a step that is right is explained |
-| **Practice, flashcards, reviews** | Every lesson has practice, with figures where they help, open answers graded by the model and keyboard answering; think a question or its grading is wrong, and the teacher checks it, fixes a wrong question, grades your answer again and corrects your mastery; a round ends with stars, how your mastery moved and a next step. Flashcards and concepts come back on a spaced-repetition schedule, and the study plan leaves time for them |
-| **Your materials become courses** | PDF, Word, PowerPoint, Markdown, web links and images (images need a vision model). Lessons and cheat sheets cite pages; long readings can be digested into structure, claims and a glossary |
+| **Practice, flashcards, reviews** | Every lesson has practice, with figures where they help, open answers graded by the model and keyboard answering; think a question or its grading is wrong, and the teacher checks it, fixes a wrong question, grades your answers to it again (earlier ones too) and corrects your mastery; a round ends with stars, how your mastery moved and a next step. Flashcards and concepts come back on a spaced-repetition schedule, and the study plan leaves time for them |
+| **Your materials become courses** | PDF, Word, PowerPoint, Markdown, web links and images; a model that can see images reads scanned PDFs, documents made of pictures and photos. Lessons and cheat sheets cite pages; long readings can be digested into structure, claims and a glossary |
 | **Cheat sheets, notes, quizzes** | Printable cheat sheets organized by theme (columns, font size and highlighting adjustable), plus notes, flashcard decks and quizzes |
 | **Explainer shorts and exports** | A two-minute whiteboard explainer from a topic or a link; any lesson exports to a video with the handwriting, captions and a watermark, or its board to a PDF (one board page per page, handwriting and formulas included) or a PNG picture per page |
 | **Hands-on projects** | Code projects get a folder with starter files and a DSH session where a coding agent helps you build; submit it back for a rubric-based review |
@@ -41,7 +42,7 @@ Two sample courses ship with the plugin (harmonic motion and Bayesian thinking,
 
 You need the **DeepSeek Harness** desktop app (0.2.x, from 0.2.1) with at least one working model. See the [DSH instructions](https://github.com/deepseek-ai/deepseek-harness#run) if you do not have it yet.
 
-1. Open **Plugins** in the desktop app, click **Add plugin** and enter `dsh-aha-tutor` as the package, with the official registry as the source. Within 24 hours of a new release DSH's pnpm holds new versions back; enter an exact version such as `dsh-aha-tutor@1.6.0` then.
+1. Open **Plugins** in the desktop app, click **Add plugin** and enter `dsh-aha-tutor` as the package, with the official registry as the source. Within 24 hours of a new release DSH's pnpm holds new versions back; enter an exact version such as `dsh-aha-tutor@1.8.0` then.
 2. **Quit and reopen** the desktop app. Refreshing the page does not load the plugin's host side.
 3. Open **Aha · AI tutor** in the left sidebar (shown as 「开窍 · AI 私人老师」 in Chinese).
 
@@ -84,7 +85,7 @@ See [SECURITY.md](SECURITY.md).
 
 **A generation failed or looks weak?** Retry, or choose a stronger model for "course design & teaching".
 
-**No text from a PDF?** Scanned PDFs have no text layer; upload page photos as images with a vision model.
+**No text from a scanned PDF?** Scanned pages are read by the model you chose, which must be able to see images (marked 🖼 in Aha settings, such as DeepSeek-V4.1-Flash). The upload shows how many pages are done and can be cancelled; up to 200 pages of a file are read.
 
 **Using the tutor in a chat?** Choose the "开窍 · AI 私人老师" preset when starting a session.
 

package/README.md

@@ -11,6 +11,7 @@
 [![CI](https://github.com/BaronCyrus/dsh-aha-tutor/actions/workflows/ci.yml/badge.svg)](https://github.com/BaronCyrus/dsh-aha-tutor/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/dsh-aha-tutor?logo=npm&label=npm)](https://www.npmjs.com/package/dsh-aha-tutor)
 [![npm 总下载量](https://img.shields.io/npm/d18m/dsh-aha-tutor?logo=npm&label=%E6%80%BB%E4%B8%8B%E8%BD%BD%E9%87%8F)](https://www.npmjs.com/package/dsh-aha-tutor)
+[![GitHub Star 数](https://img.shields.io/github/stars/BaronCyrus/dsh-aha-tutor?style=flat&logo=github&label=Star%20%E6%95%B0)](https://github.com/BaronCyrus/dsh-aha-tutor/stargazers)
 [![MIT](https://img.shields.io/badge/license-MIT-111111.svg)](LICENSE)
 
 [能做什么](#能做什么) · [安装](#安装) · [三分钟上手](#三分钟上手) · [界面预览](#界面预览) · [使用指南](docs/guide.zh-CN.md) · [隐私](#隐私与数据) · [常见问题](#常见问题) · [支持作者](#支持作者)
@@ -27,8 +28,8 @@
 | **手写黑板课堂** | 老师一边讲（语音 + 字幕），一边用手写体在黑板上逐字写下要点、公式、示意图和图表，讲到哪句写哪句，正在讲的内容用荧光笔划出；由公式画的曲线按公式逐点算出，带参数的还能拖动滑块看它怎么变；整讲的板书排在一张能拖动、缩放的画布上，镜头跟着老师走；侧栏显示课堂要点进度和讲解记录；随时暂停、回放、变速 |
 | **随堂小测与自适应** | 讲到关键处会停下来考你一题，并问你「有多确定」。猜对、犹豫、自信地答错，会被区别对待；有计算的一讲会请你写出过程，写错了老师就在黑板上订正。学完一讲后，薄弱的知识点会自动加一节巩固课 |
 | **举手提问、换个讲法** | 没听懂就举手，老师在黑板上专门回答你，讲完回到原来的进度；问题可以打字，也可以直接说出来（用 DSH 的语音输入在本机识别）；也可以让它用打比方、画图、举例、讲简单点或讲深一点的方式重讲这一步。觉得讲错了就点「这一步不对？」：老师先仔细核对，真错了就在黑板上更正，并把这一讲改好；没错就讲清为什么 |
-| **练习、闪卡与复习** | 每讲都有练习，题目可以带示意图，简答题由 AI 批改，支持键盘作答；觉得题目或判分有问题就点「这题有问题？」，老师先仔细核对，题错了就改好、重新判分并修正掌握度；做完一组给出星级、掌握程度变化和下一步建议。闪卡和知识点按间隔重复安排复习，学习计划会自动给复习留出时间 |
-| **资料变课程** | 支持 PDF、Word、PPT、Markdown、网页链接和图片（图片需要支持识图的模型）。讲课和速查表会引用原文页码；长文档可以一键「消化」成结构、论点和术语表 |
+| **练习、闪卡与复习** | 每讲都有练习，题目可以带示意图，简答题由 AI 批改，支持键盘作答；觉得题目或判分有问题就点「这题有问题？」，老师先仔细核对，题错了就改好、重新判分（以前答过的也一起重判）并修正掌握度；做完一组给出星级、掌握程度变化和下一步建议。闪卡和知识点按间隔重复安排复习，学习计划会自动给复习留出时间 |
+| **资料变课程** | 支持 PDF、Word、PPT、Markdown、网页链接和图片；扫描版 PDF、全是图片的文档和拍的照片，由能看图的模型识别出文字。讲课和速查表会引用原文页码；长文档可以一键「消化」成结构、论点和术语表 |
 | **速查表、笔记、测验** | 按主题整理的可打印速查表（列数、字号、高亮可调），以及笔记、闪卡组和测验 |
 | **讲解短片 + 导出** | 输入一个主题或网址，得到一段约两分钟的白板讲解；任何一讲都能导出成带板书动画、字幕和水印的视频，也能把板书导出成 PDF（一页一张板书，带手写字体和公式）或每页一张的 PNG 图片 |
 | **实战项目** | 代码类项目一键生成项目文件夹和起始文件，并在 DSH 里打开一个会话，让编程 Agent 陪你做；做完回来提交，老师按评分标准逐项点评 |
@@ -47,7 +48,7 @@
    dsh-aha-tutor
    ```
 
-   安装源选择**官方源**，点击**安装**。新版本刚发布的 24 小时内，DSH 的 pnpm 会因为发布冷却期暂缓安装，这时请填入精确版本，例如 `dsh-aha-tutor@1.6.0`。
+   安装源选择**官方源**，点击**安装**。新版本刚发布的 24 小时内，DSH 的 pnpm 会因为发布冷却期暂缓安装，这时请填入精确版本，例如 `dsh-aha-tutor@1.8.0`。
 
 2. **完全退出并重新打开** DSH 桌面应用。只刷新页面不会加载 Host 端的新插件。
 
@@ -114,7 +115,7 @@
 
 **生成失败或结果不理想？** 点**重试**，或在设置里为「出课与讲课」换一个更强的模型。
 
-**PDF 里读不出文字？** 扫描版 PDF 没有文字层，可以截图后以图片上传（需要支持识图的模型）。
+**扫描版 PDF 读不出字？** 扫描页由你选的模型识别，需要能看图的模型（开窍设置里带 🖼 的，比如 DeepSeek-V4.1-Flash）。上传时会显示识别到第几页，可以随时取消；一个文件最多识别 200 页。
 
 **会话里怎么用老师？** 新建会话时，在预设里选择 **「开窍 · AI 私人老师」**。
 

package/compatibility.json

@@ -1,10 +1,12 @@
 {
-  "latestTested": "0.2.1-rc.2",
+  "latestTested": "0.2.1-rc.3",
   "acceptedRuntimeRange": ">=0.2.1-rc.1 <0.3.0-0",
   "supported": [
-    "0.2.1-rc.2"
+    "0.2.1-rc.2",
+    "0.2.1-rc.3"
   ],
   "validation": {
-    "0.2.1-rc.2": "Development baseline. Offline suite against the published 0.2.1-rc.2 packages; desktop verification is recorded in CHANGELOG.md."
+    "0.2.1-rc.2": "Development baseline. Offline suite against the published 0.2.1-rc.2 packages; desktop verification is recorded in CHANGELOG.md.",
+    "0.2.1-rc.3": "Desktop runtime since 2026-10-23. Verified 2026-10-26 in a scratch web profile with the bundled 0.2.1-rc.3 CLI: the tutor preset loads (rc.3 requires tool-fs-search sampleOverCapGlobResults), and classroom corrections, scanned materials and quizzes work with DeepSeek-V4.1-Flash."
   }
 }

package/cordis.patch.yml

@@ -37,8 +37,12 @@
               readImage: true
               write: false
               edit: false
+          # DSH 0.2.1-rc.3 requires this setting and gives it no default; its
+          # own presets keep the first paths, as rc.2 did.
           - id: tool-fs-search
             name: '@deepseek-ai/dsh-tool-fs-search'
+            config:
+              sampleOverCapGlobResults: false
           - id: tool-web
             name: '@deepseek-ai/dsh-tool-web'
             config:

package/docs/guide.zh-CN.md

@@ -21,7 +21,7 @@
 
 ## 开始之前
 
-1. **模型**：开窍使用你在 DSH 里设置的默认模型。讲课质量主要取决于模型，建议「出课与讲课」用你手头最强的模型。要读图片资料，模型需要支持识图。
+1. **模型**：开窍使用你在 DSH 里设置的默认模型。讲课质量主要取决于模型，建议「出课与讲课」用你手头最强的模型。扫描件、照片等图片资料里的字，要靠能看图的模型识别（开窍设置里带 🖼 的模型）。
 2. **语音**：默认用系统自带的音色朗读，不花钱。第一次使用时，到 **设置 → 语音讲解** 点**试听**，确认能听到声音。
 3. **先看示例课**：首页下方的「示例课程」里有「简谐运动」「贝叶斯思维」两门现成的课，点**加入我的课程**就能体验完整的黑板课堂，不消耗模型额度。
 
@@ -44,20 +44,25 @@
 
 1. **先查一查**：首页的 **🌐 联网查资料** 默认打开（选了资料时默认关闭，以资料为准）。老师会先用 DSH 的网页搜索查几次这个主题，出题和设计课程时都会参考；查到的来源列在问卷上方，开课后在课程页大纲最下方的**参考来源**里也能看到，点开就是原网页。没配置 DeepSeek 密钥等情况下没法搜索时，会照常建课，并在问卷上方说明原因。每次搜索会用掉一些 DeepSeek 额度。
 2. **先认识一下你**：老师会根据你的主题出几道选择题，问你的基础、目的、想学多深等。每题都可以选「其他」自己写，拿不准的可以跳过。下面先选**课程规模**：**让老师决定**（按目标定，一个小问题可能只要一两讲）、**精简**（3–8 讲）、**标准**（10–20 讲）或**完整**（25–45 讲）。选了规模，老师就按这个讲数出课。再选**学习节奏**（冲刺约 6 周 / 稳步约 3 个月 / 不设期限）、**每周大约能学多久**，以及可选的**截止日期**；节奏只影响每周怎么排。想省事可以点**跳过提问，直接出课**。
-3. **课程蓝图**：点**生成课程蓝图**后，老师边写边展示：上面是进行到哪一步，下面是一个个单元逐渐长出来的大纲。写完后就是「单元 → 章 → 讲」的完整结构，每讲标有预计时长，末尾还有实战项目。你可以：
-   - 直接改标题，**上移 / 下移**调整顺序，**删除**不要的部分，或者**加一讲 / 加一章 / 加一个单元**。删除单元、章或已经开始学的讲之前会先确认；
+3. **课程蓝图**：点**生成课程蓝图**后，老师边写边展示：上面是进行到哪一步，下面是一张不断长出来的思维导图，课程在最左边，往右依次是单元、章和讲，镜头跟着最新写出的那一讲走（拖动或缩放后会停下，点**回到最新**接着跟）。写完后就是「单元 → 章 → 讲」的完整结构，每讲标有预计时长和**讲法**，末尾还有实战项目。讲法说明这一讲怎么讲：**直观理解**（先用图和例子建立感觉）、**定义概念**（把概念说准确）、**推导证明**（一步步推出来）、**动手应用**（用它解题）、**深入拓展**（边界情况和延伸）。老师讲课时会照着它来。你可以：
+   - 蓝图上方可以在**列表**和**导图**之间切换：导图看整体结构，点其中一讲就回到列表里编辑它；修改都在列表里做。
+   - 直接改标题，改每一讲的讲法，**上移 / 下移**调整顺序，**删除**不要的部分，或者**加一讲 / 加一章 / 加一个单元**。删除单元、章或已经开始学的讲之前会先确认；
    - 点某一讲旁边的 **✦**，让老师把它**拆成两讲**或**讲深一些**。改好的内容先出现在编辑器里，保存后才生效；
    - 在**用一句话修改**里写下要求，例如「多加一些编程实战」「第二单元讲浅一点」，点**修改**。老师会先给出**修改建议**，列出新增、删除、改名和调整的讲，点**应用修改**才生效，不满意就**放弃**。
 4. **确认开课**：点**确认，生成整门课**。老师会完善实战项目，并为第一单元准备练习；后面各讲的练习在你第一次打开这一讲（或它的练习）时准备。完成后进入课程页，点**继续学习**开始第一讲。
 
 开课以后也能改：在课程页右上角的 **⋯** 里选**编辑课程大纲**，可以加讲、加单元、调整顺序，或点**让老师续写一个单元**。保留下来的讲，学习进度不变。
 
+**补充资料**：后来找到了更好的教材或讲义，在 **⋯** 里选**补充资料**（编辑大纲时也有这个按钮），从资料库里勾选或当场上传，还可以写一句想怎么用，比如「重点补上第 5 章的例题」，再点**请老师看看怎么加**。老师会读这些资料，给出修改建议：新增哪些讲、哪些讲要讲深；点**应用修改**后才生效，资料也会关联到这门课，以后讲课时会引用它们。一门课最多关联 12 份资料。
+
 每一讲的板书在你打开它时才生成，同时会预备下一讲，所以不会一次性消耗大量额度。
 
 生成蓝图、确认开课这类要等一会儿的步骤，可以先去别的页面，生成会在后台继续，回来就能看到结果；想停下来就点**取消**。
 
 ## 黑板课堂
 
+第一次进课堂时，会有一段 6 步的**课堂导览**，依次介绍黑板、播放控制、举手提问、换个讲法、这一步不对？和课堂侧栏，导览结束后才开讲；可以随时**跳过**，也可以用方向键翻页。想再看一遍，点课堂顶部的 **?**。
+
 老师一边讲（语音 + 字幕），一边在黑板上逐字写出要点，画出示意图、图表，需要时还会放一段小动画。一页写满后接着写下一页。板书用手写体，讲到哪一句才写哪一句对应的内容，正在讲的那一行会用荧光笔划出来；字幕跟着朗读一句一句出现，公式按数学排版显示。想换回普通字体，到**设置 → 板书字体**选**标准体**。
 
 **画布**：整讲的板书一页接一页从上到下排在一张画布上，讲课时镜头自动跟着老师写的地方走。
@@ -95,6 +100,8 @@
 2. 在它的详情里点**下载并准备**，下载本地识别模型（约 240 MB）；
 3. 准备好后回到课堂点麦克风。没准备好时麦克风是灰的，点它会提示还差哪一步。识别的语言跟随语音输入详情里的设置（默认自动）。
 
+**按 V 说话**：讲课时也可以不碰鼠标。按住 **V** 说话，松开就结束；或者按一下 **V** 开始，说完再按一下。课会自动暂停，侧栏收着时提问框会自动打开。识别出的文字一样先填进提问框，检查后按回车提问。用 V 问完一个问题后，键盘会回到课堂，空格、方向键和 V 又能直接用；在提问框里按 **Esc** 也能回到课堂。即时答疑和讲解短片里同样能用。DSH 对话旁边的白板不响应 V，免得在对话里打字时误开录音。鼠标停在**举手提问**或麦克风按钮上，会显示这个快捷键。
+
 录音用的麦克风跟随语音输入详情里选的**输入设备**（默认跟随系统）；选了具体设备时，鼠标停在麦克风按钮上会显示它的名字。选的那个拔掉了或用不了时，开窍会提示，不会悄悄换成别的麦克风：插上它，或在语音输入详情里换一个。
 
 **换个讲法**：对当前这一步不满意，点**换个讲法**，选择**打个比方 / 画图讲 / 举个例子 / 讲简单点 / 讲深一点**，新的讲解同样会插在这一步之后。
@@ -111,7 +118,7 @@
 
 **讲完之后**：给自己的掌握程度打个分（1–5）。如果某些知识点掌握得不好，老师会自动加一节**巩固课**；如果掌握得很好，后面会讲得更深一些。
 
-课堂顶部还有：**练习**（去做这一讲的练习）、**导出板书**、**导出视频**（见[讲解短片](#学习工具即时答疑与讲解短片)）和**重新备课**（重新生成这一讲的板书）。
+课堂顶部还有：**练习**（去做这一讲的练习）、**讲义**（见下）、**导出板书**、**导出视频**（见[讲解短片](#学习工具即时答疑与讲解短片)）和**重新备课**（重新生成这一讲的板书）。
 
 **导出板书**有三种格式：
 
@@ -121,11 +128,13 @@
 
 讲解短片顶部也有同样的**导出板书**。
 
+**讲义**：点课堂顶部的**讲义**（或学完一讲后弹窗里的**本讲讲义**），老师会把这一讲整理成一页讲义：这一讲讲了什么、每个要点配一句能讲给别人听的话、一道带步骤的例题、常见错误、术语表和三道自测题。讲义按这一讲的板书来写，生成一次就保存下来；点**打印**可以打印或存成 PDF（自测题的答案在屏幕上折叠，打印时会展开），想重写就点**重新生成**。
+
 ## 课程页
 
 | 标签 | 内容 |
 | --- | --- |
-| **大纲** | 全部单元、章和讲，带学习状态；自动加入的巩固课标有「巩固」。每个单元都有**单元速查表**和**单元测验** |
+| **大纲** | 全部单元、章和讲，带学习状态和讲法（直观理解、定义概念等）；自动加入的巩固课标有「巩固」。每个单元都有**单元速查表**和**单元测验** |
 | **练习与测验** | 每讲的练习、单元测验和**开始复习**（只复习这门课） |
 | **速查表** | 单元速查表，按主题整理公式、定义和要点 |
 | **闪卡** | 这门课的闪卡，按复习计划出现 |
@@ -146,6 +155,8 @@
     - **其实没错**：老师会针对你的疑问讲清楚为什么，成绩和掌握度都不变。
 
     重新判分后，掌握度和复习时间会按新的分数重新算，就像当初判对了一样：这次作答留下的「误解」标记也会去掉，这一轮的星级、正确率和连对也按新结果算。每讲的练习、单元测验、学习工具里的测验和复习里的题都可以这样核对。
+
+    题目改好后，你以前对同一道题的作答（上一轮练习、复习里，或课上的小测）也会按改好的题重新判，结果框里会说重判了几次。题目确实有错时，按改好的答案判，分数可能升也可能降；题目没说清楚时，只会往上调，因为你当时按另一种理解答的可能也对。简答题和写过程的题由 AI 重新批改最近 3 次。只有最近 50 次作答留有记录，更早的不再重判。
 - **闪卡**：点击翻面，然后按记忆情况选**忘了 / 困难 / 记得 / 简单**。开窍用间隔重复安排下次复习的时间，记得越牢，间隔越长。
 - **复习**：学过的知识点也会按遗忘曲线回来。学习计划会提醒你**有 N 个知识点该复习了**，点**开始复习**即可。
 
@@ -155,14 +166,16 @@
 
 | 类型 | 说明 |
 | --- | --- |
-| PDF | 读取文字层，讲课和速查表会引用页码。扫描版 PDF 没有文字层，请截图后以图片上传 |
-| Word（.docx）、PPT（.pptx） | 读取正文；PPT 按幻灯片编号引用 |
+| PDF | 读取文字层，讲课和速查表会引用页码。没有文字层的页（扫描页、整页图片）由能看图的模型逐页识别，上传时显示进度、可以取消，一个文件最多识别 200 页 |
+| Word（.docx）、PPT（.pptx） | 读取正文；PPT 按幻灯片编号引用。几乎全是图片的文档、只有图片的幻灯片，图里的字也会识别 |
 | Markdown、文本 | 自动识别 UTF-8 和 GB18030 编码 |
 | 网页 | 点**添加网页**，填入公开网址，开窍会提取正文 |
-| 图片 | 需要支持识图的模型 |
+| 图片 | 能看图的模型会识别图里的字，之后和其他资料一样能建课、做速查表和测验；图片本身也会交给能看图的模型 |
 
 每份资料都可以一键**用它建课**，或者生成**速查表、闪卡、笔记、测验**，以及**消化**成概要、结构、核心观点、论点与论据、术语表和值得思考的问题。
 
+**找资料**：资料多了，在资料列表上方的搜索框里输入，会按标题和主题即时筛选；按回车（或点**搜正文**）会在所有资料的正文里搜，列出最相关的段落，带资料名、页码和高亮的上下文，点一条就跳到那份资料。搜索在本机进行，不调用模型。
+
 ## 学习工具、即时答疑与讲解短片
 
 - **学习工具**：先**选择资料**，再生成速查表、笔记、闪卡组或测验。可以在**重点**里写上范围，例如「期中考试范围第 3–6 章」。速查表可以调**列数、字号**，开关**高亮重点**，隐藏某些部分，然后**打印**。
@@ -183,7 +196,7 @@
 
 - **学习计划**：设置**学习日**和**每周大约能学多久**，在**考试与截止日期**里添加重要日期。开窍会把所有在学课程的讲次和复习排进日程；按当前节奏赶不上截止日期时，会提醒你，并建议每周需要的学习时间。
 - **月历和打勾**：学习计划页是一张月历，点某一天就能看到那天的安排。学完一讲、做完一次复习会自动打勾；今天和之前的事项也可以手动勾上或取消（比如那一讲你在别处学过了），首页的**今天的安排**里同样可以勾。手动勾掉的讲次算作学完，后面的日子会重新排；今天已经学过的时间会从今天的安排里扣掉，不会越学越多。过去的日子保留当天的安排和完成情况，没完成的会自动顺延到之后。
-- **我的画像**：老师会记住你的背景、目标、擅长和薄弱的地方、喜欢的讲解方式，以及它自己的备忘，让每门课都更贴合你。每一项都可以直接修改（每行一条），也可以**清空画像**。
+- **我的画像**：老师会记住你的背景、目标、擅长和薄弱的地方、喜欢的讲解方式，以及它自己的备忘，让每门课都更贴合你。每一项都可以直接修改（每行一条），也可以**清空画像**。在**怎么称呼你**里填上称呼，老师每讲开课时会这样叫你一次。
 
 ## 在 DSH 对话里使用
 
@@ -238,8 +251,8 @@
 | 提示模型未登录或额度不足 | 在 DSH 设置里检查模型服务，或在开窍设置里换一个模型 |
 | 资料太长超出上下文 | 少选几份资料，或换一个上下文更大的模型 |
 | 生成结果不理想 | 点**重试**或**重新备课**；为「出课与讲课」换一个更强的模型 |
-| PDF 读不出文字 | 扫描版没有文字层，截图后以图片上传 |
-| 图片资料读不了 | 需要支持识图的模型 |
+| 扫描版 PDF 读不出文字 | 在开窍设置里选一个带 🖼（能看图）的模型，比如 DeepSeek-V4.1-Flash，再重新上传 |
+| 资料下面写着有些页没识别出来 | 按提示处理：额度不足就稍后再传；超过 200 页就把文件拆开上传 |
 | 更新显示「待更新」 | DSH 的 pnpm 设置了发布冷却期，新版本还没过冷却期；到显示的时间后再更新 |
 
 还有问题，欢迎到 [GitHub Issues](https://github.com/BaronCyrus/dsh-aha-tutor/issues) 反馈（请不要贴出密钥或个人学习数据）。

package/lib/agent.js

@@ -1,4 +1,4 @@
-import { Ct as text, Et as newId, H as readProfile, j as generateJson, l as detectLanguage, t as getRuntime, vt as normalizePractice, x as quizPrompt } from "./runtime-B6zUpJjA.js";
+import { Et as normalizePractice, F as generateJson, K as readProfile, Pt as newId, jt as text, t as getRuntime, u as detectLanguage, w as quizPrompt } from "./runtime-C3yJfJTT.js";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 //#region src/agent.js
 const name = "aha-tutor-agent";