dsh-aha-tutor 1.4.0 → 1.5.0

package/AGENTS.md

@@ -8,7 +8,7 @@ This file governs the entire `dsh-aha-tutor` repository.
 - npm package: `dsh-aha-tutor`
 - DSH plugin rows: `aha-tutor` (the plugin) and `preset-aha-tutor` (the conversation preset), both inserted by `cordis.patch.yml`
 - Product name: 「开窍 · AI 私人老师」, English "Aha Tutor"; mascot 「小窍」
-- RPC channel `/aha-tutor`; HTTP routes `/api/aha-tutor/upload`, `/api/aha-tutor/tts` and `/api/aha-tutor/font`
+- RPC channel `/aha-tutor`; HTTP routes `/api/aha-tutor/upload`, `/api/aha-tutor/tts`, `/api/aha-tutor/speech` and `/api/aha-tutor/font`
 - Data directory: `$DSH_HOME/aha-tutor/`; project folders: `~/AhaTutor/projects/`
 
 ## Project boundaries
@@ -21,6 +21,7 @@ This file governs the entire `dsh-aha-tutor` repository.
 - Formulas are rendered by the bundled KaTeX and styled by the KaTeX stylesheet and fonts DSH loads. The bundled version must be the stylesheet's version (0.18.7 in DSH 0.2.1); KaTeX renames layout classes between versions. `tests/package-contract.test.mjs` pins it; change both together when DSH moves.
 - Generation uses only the model the user chose: DSH's default model or the plugin's two overrides ("teach" and "quick"). Never fall back to another provider, model or credential source on a failure.
 - Web research before course design goes through DSH's own web service (`ctx.get('web')`) and whatever search provider DSH is configured with. The plugin never calls a search vendor or touches its credentials; when DSH cannot search, the course is designed without research and the reason is shown.
+- Voice questions go through DSH's own speech service (`ctx.get('speechToText')`, the experimental Voice input bundle with local SenseVoice) with DSH's provider and language choices. The plugin never prepares or downloads a recognizer, keeps no audio and sends it nowhere else; until Voice input is enabled and ready, the microphone explains how to set it up.
 - Generate on demand: course structure when the learner confirms the blueprint, a lesson's board when it is opened plus at most one prefetched next lesson. Never generate a whole course's boards in the background.
 - Cloud TTS keys live in DSH's credential store as records and are used host-side only. Never fall back to environment variables, and never return a key to the browser.
 - The in-plugin update installs an exact registry version with DSH's bundled pnpm in the owning profile, under the profile's own pnpm release-age policy. Never pass `--config.minimumReleaseAge`, never edit `minimumReleaseAgeExclude`, and never use `--force`: bypassing the policy leaves a lockfile entry pnpm later rejects, and the profile then refuses every plugin install until that version is 24 hours old. A version pnpm holds back is reported as pending with the time it becomes installable. Verify the installed version even on exit code 0. `link:` installs are never updated in place. After an update, tell the user to quit and reopen DSH.

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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.5.0 - 2026-10-21
+
+### Added
+
+- **The board is a canvas**: a lesson's pages sit top to bottom on one canvas that pans (drag, scroll wheel or trackpad) and zooms (Ctrl/⌘ with the wheel, a pinch, or the − and + buttons) from 5 % to 300 %. Double-click a page to fit it, and **All** shows every page. During a lesson the view follows the writing; moving it yourself stops that until **Back to the teacher**. **Settings → Board view → Pages** brings back one page at a time with page numbers. Exports are unchanged.
+- **Voice questions**: the ask box in a lesson and the instant-answer box have a microphone. Click it, say the question, click again to stop, and the words are filled into the box to check before asking; a lesson pauses while you speak. Recognition is DSH's experimental Voice input (local SenseVoice, in the language set there), so nothing leaves the computer and the plugin keeps no audio. Until Voice input is enabled in DSH's Plugins page and its model is prepared, the microphone is greyed out and says how to set it up. A recording is at most two minutes.
+
 ## 1.4.0 - 2026-10-20
 
 ### Added

package/README.en.md

@@ -24,9 +24,9 @@
 | Feature | What you get |
 | --- | --- |
 | **A course made for you** | Say what you want to learn or drop in a textbook. The tutor can look the subject up on the web first, then asks a few multiple-choice questions about your background, goal, time and the course size you want, then writes a unit → chapter → lesson blueprint while you watch. Edit it by hand, have a lesson split or deepened, or ask for changes and review them before they apply; a running course can still grow. Confirming prepares the hands-on projects and the first unit's practice; later lectures get theirs when you reach them |
-| **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, and a side panel shows the lesson's goals and a transcript; pause, rewind and change speed any time |
+| **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; 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 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 |
+| **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 |
 | **Practice, flashcards, reviews** | Every lesson has practice, with figures where they help, open answers graded by the model and keyboard answering; 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 |
 | **Cheat sheets, notes, quizzes** | Printable cheat sheets organized by theme (columns, font size and highlighting adjustable), plus notes, flashcard decks and quizzes |
@@ -41,7 +41,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.4.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.5.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).
 

package/README.md

@@ -24,9 +24,9 @@
 | 能力 | 体验 |
 | --- | --- |
 | **为你定制一门课** | 说一句想学什么，或者丢进一本教材。老师可以先联网查一查这个主题，再用几道选择题了解你的基础、目标、时间和想要的课程规模，再一边写一边展示「单元 → 章 → 讲」的课程蓝图。你可以直接改，可以让老师把一讲拆开或讲深，也可以用一句话让它改（先看修改建议再应用）；开课后还能继续加讲、加单元。确认后生成实战项目和第一单元的练习，后面各讲的练习学到时再出 |
-| **手写黑板课堂** | 老师一边讲（语音 + 字幕），一边用手写体在黑板上逐字写下要点、公式、示意图和图表，讲到哪句写哪句，正在讲的内容用荧光笔划出；侧栏显示课堂要点进度和讲解记录；随时暂停、回放、变速 |
+| **手写黑板课堂** | 老师一边讲（语音 + 字幕），一边用手写体在黑板上逐字写下要点、公式、示意图和图表，讲到哪句写哪句，正在讲的内容用荧光笔划出；整讲的板书排在一张能拖动、缩放的画布上，镜头跟着老师走；侧栏显示课堂要点进度和讲解记录；随时暂停、回放、变速 |
 | **随堂小测与自适应** | 讲到关键处会停下来考你一题，并问你「有多确定」。猜对、犹豫、自信地答错，会被区别对待；有计算的一讲会请你写出过程，写错了老师就在黑板上订正。学完一讲后，薄弱的知识点会自动加一节巩固课 |
-| **举手提问、换个讲法** | 没听懂就举手，老师在黑板上专门回答你，讲完回到原来的进度；也可以让它用打比方、画图、举例、讲简单点或讲深一点的方式重讲这一步 |
+| **举手提问、换个讲法** | 没听懂就举手，老师在黑板上专门回答你，讲完回到原来的进度；问题可以打字，也可以直接说出来（用 DSH 的语音输入在本机识别）；也可以让它用打比方、画图、举例、讲简单点或讲深一点的方式重讲这一步 |
 | **练习、闪卡与复习** | 每讲都有练习，题目可以带示意图，简答题由 AI 批改，支持键盘作答；做完一组给出星级、掌握程度变化和下一步建议。闪卡和知识点按间隔重复安排复习，学习计划会自动给复习留出时间 |
 | **资料变课程** | 支持 PDF、Word、PPT、Markdown、网页链接和图片（图片需要支持识图的模型）。讲课和速查表会引用原文页码；长文档可以一键「消化」成结构、论点和术语表 |
 | **速查表、笔记、测验** | 按主题整理的可打印速查表（列数、字号、高亮可调），以及笔记、闪卡组和测验 |
@@ -47,7 +47,7 @@
    dsh-aha-tutor
    ```
 
-   安装源选择**官方源**，点击**安装**。新版本刚发布的 24 小时内，DSH 的 pnpm 会因为发布冷却期暂缓安装，这时请填入精确版本，例如 `dsh-aha-tutor@1.4.0`。
+   安装源选择**官方源**，点击**安装**。新版本刚发布的 24 小时内，DSH 的 pnpm 会因为发布冷却期暂缓安装，这时请填入精确版本，例如 `dsh-aha-tutor@1.5.0`。
 
 2. **完全退出并重新打开** DSH 桌面应用。只刷新页面不会加载 Host 端的新插件。
 

package/docs/guide.zh-CN.md

@@ -58,7 +58,16 @@
 
 ## 黑板课堂
 
-老师一边讲（语音 + 字幕），一边在黑板上逐字写出要点，画出示意图、图表，需要时还会放一段小动画。一页写满后自动翻到下一页。板书用手写体，讲到哪一句才写哪一句对应的内容，正在讲的那一行会用荧光笔划出来；字幕跟着朗读一句一句出现，公式按数学排版显示。想换回普通字体，到**设置 → 板书字体**选**标准体**。
+老师一边讲（语音 + 字幕），一边在黑板上逐字写出要点，画出示意图、图表，需要时还会放一段小动画。一页写满后接着写下一页。板书用手写体，讲到哪一句才写哪一句对应的内容，正在讲的那一行会用荧光笔划出来；字幕跟着朗读一句一句出现，公式按数学排版显示。想换回普通字体，到**设置 → 板书字体**选**标准体**。
+
+**画布**：整讲的板书一页接一页从上到下排在一张画布上，讲课时镜头自动跟着老师写的地方走。
+- **移动**：用鼠标拖动，或用滚轮、触控板滚动。
+- **缩放**：按住 Ctrl（Mac 上是 ⌘）滚动，或在触控板上双指捏合；右上角也有 **−**、**+** 按钮。
+- **看一页**：双击某一页，就放大到这一页。
+- **看全貌**：点右上角的**全貌**，缩小到能看到所有页；点百分比回到 100%（铺满宽度）。
+- **回到老师这里**：你一拖动或缩放，镜头就不再自动跟随，右上角会出现**回到老师这里**，点一下回到正在写的地方并继续跟随。
+
+习惯一次看一页的话，到**设置 → 板书视图**选**分页**，用右上角的页码翻页。
 
 **备课中**：一讲第一次打开时，老师要先备课。能关掉推理的模型（比如 DeepSeek）不先构思、直接写板书，一两秒就开讲；关不掉推理的模型会用它最轻的一档先想一想。备课超过 3 秒时，黑板中间会显示备课进度：先是**构思**（只在模型先想的时候出现，显示已构思的字数），然后是**写板书**，写到第几步、这一步讲什么（小标题边写边出现），以及已用的时间。第一步一写好就开讲，后面的内容边讲边写；如果讲得比写得快，黑板上会显示老师正在写的那一步。下一讲会在你上这一讲时提前备好，通常打开就能直接上。
 
@@ -79,6 +88,11 @@
 
 **举手提问**：没听懂就点**举手提问**（或直接在侧栏的提问框里写）。老师会把回答插在当前这一步之后，边写边讲给你听，讲完接着原来的内容继续。问过的问题和「换个讲法」都会留在这一讲里，下次打开还在原来的位置，也会出现在侧栏的讲解记录里。
 
+**语音提问**：提问框旁边有个麦克风。点一下开始说，说完再点一下停止，识别出的文字会填进提问框，检查一下再点**提问**；说话时课堂会自动暂停。一次最多录 2 分钟。语音识别用的是 DSH 的实验功能**语音输入**，在本机识别、不上传录音，开窍也不保存录音。第一次用之前：
+1. 在 DSH 的**插件管理**里启用**语音输入**；
+2. 在它的详情里点**下载并准备**，下载本地识别模型（约 240 MB）；
+3. 准备好后回到课堂点麦克风。没准备好时麦克风是灰的，点它会提示还差哪一步。识别的语言跟随语音输入详情里的设置（默认自动）。
+
 **换个讲法**：对当前这一步不满意，点**换个讲法**，选择**打个比方 / 画图讲 / 举个例子 / 讲简单点 / 讲深一点**，新的讲解同样会插在这一步之后。
 
 **随堂小测**：讲到关键处，老师会停下来出一道题，并问你**有多确定**（很确定 / 有点犹豫 / 猜的）。回答会影响掌握度：猜对不算完全掌握，自信地答错说明有误解，需要重点巩固。卡住时可以点**提示**，也可以**跳过**。
@@ -135,7 +149,7 @@
 ## 学习工具、即时答疑与讲解短片
 
 - **学习工具**：先**选择资料**，再生成速查表、笔记、闪卡组或测验。可以在**重点**里写上范围，例如「期中考试范围第 3–6 章」。速查表可以调**列数、字号**，开关**高亮重点**，隐藏某些部分，然后**打印**。
-- **即时答疑**：不用建课，直接提问，老师在白板上讲给你听。可以**继续追问**，以前问过的问题都在**历史记录**里。
+- **即时答疑**：不用建课，直接提问，老师在白板上讲给你听。可以**继续追问**，以前问过的问题都在**历史记录**里。问题也可以点麦克风说出来（见[黑板课堂](#黑板课堂)里的「语音提问」）。
 - **讲解短片**：输入一个主题，或者贴一个网址，点**生成短片**，得到一段约两分钟的白板讲解。
 
 窄屏时（手机，或者 DSH 侧栏展开、窗口不够宽时），即时答疑和讲解短片整页上下滚动：课堂在上，板书约占屏幕高度的 60%，下面依次是字幕、播放控制和讲解记录，再往下是追问框和历史记录。从历史记录打开、继续追问或生成短片后，页面会自动滚回课堂。
@@ -175,6 +189,7 @@
   - **默认语速**和**试听**。试听、保存或清除密钥失败时，原因显示在对应按钮下方。
 - **白板外观**：跟随系统 / 白板 / 黑板。
 - **板书字体**：手写体 / 标准体。
+- **板书视图**：画布（整讲排在一张可拖动、缩放的画布上）/ 分页（一次看一页）。
 - **插件版本**：**检查更新**，有新版本时点**更新插件**，新版本刚发布也能直接装上。如果 DSH 的 pnpm 显式设置了发布冷却期，还没过冷却期的版本会显示可更新的时间，这不是失败。更新后请完全退出并重新打开 DSH。
 
 ## 关于作者