dsh-aha-tutor 1.5.0 → 1.7.0

package/AGENTS.md

@@ -17,7 +17,7 @@ This file governs the entire `dsh-aha-tutor` repository.
   - `src/index.js` (host): storage, generation, materials, voices, jobs and the RPC handler, built from `src/host/` and `src/core/`.
   - `src/agent.js` (`dsh-aha-tutor/agent`): the conversation preset's tools and system-prompt section.
   - `src/client.jsx` (browser): the full-page app, sidebar entry, right-sidebar board tab and tool cards, built from `src/ui/` through the client wrapper in `tsdown.config.mjs`.
-- `src/core/` is pure logic shared by host and browser (mastery, SRS, planner, grading, board scripts, course model, retrieval, JSON extraction). Keep it free of Node and DOM APIs.
+- `src/core/` is pure logic shared by host and browser (mastery, SRS, planner, grading, board scripts and their fixes, plot formulas, course model, retrieval, JSON extraction). Keep it free of Node and DOM APIs.
 - 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.
@@ -41,7 +41,7 @@ The plugin runs inside DSH on both systems. Every change must keep working on bo
 
 ## Security requirements
 
-- Model output, uploads, course packs, fetched web pages and web search results are untrusted. Search results keep http(s) links only, are length-capped, reach prompts as reference material (never as instructions) and open outside the app. Keep `src/ui/sanitize.js`'s SVG allow-list, the sandboxed animation iframe (`sandbox="allow-scripts"`, no same-origin, `default-src 'none'` CSP), Markdown without raw HTML and KaTeX with `trust: false`.
+- Model output, uploads, course packs, fetched web pages and web search results are untrusted. Search results keep http(s) links only, are length-capped, reach prompts as reference material (never as instructions) and open outside the app. Keep `src/ui/sanitize.js`'s SVG allow-list, the sandboxed animation iframe (`sandbox="allow-scripts"`, no same-origin, `default-src 'none'` CSP), Markdown without raw HTML and KaTeX with `trust: false`. Plot formulas are read by `src/core/expr.js` and evaluated over numbers only, never as code (no `eval`, `Function` or iframe).
 - Web import refuses non-`http(s)` URLs and localhost, private, link-local and metadata addresses, follows redirects by hand and re-checks each hop.
 - Project files: starter paths go through `safeRelativePath`; existing files are never overwritten; reviews read text files only, skip symlinks and cap the total size.
 - Browser RPC validates every payload and returns only user-facing error messages. Never print, log, commit or return to the browser any API key, token or package-manager output.

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 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.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
+
+- **Is this step wrong?**: a learner who thinks the teacher made a mistake can say so, from the classroom controls (the step on screen) or from any line of the transcript (an earlier step). An optional note, typed or spoken, says what looks wrong. The teacher model checks the step with thinking on (recomputing numbers, re-deriving formulas, checking facts, units and answer keys), which takes a few seconds to half a minute, then answers at the board. A real mistake is boxed and corrected there, and the lesson itself is fixed where it is kept: the wrong ops, later steps that carried the mistake forward, the narration and check answers. Each fixed op shows **✎ Corrected**, with the original on hover, also in PDF and PNG exports. A step that is right is explained, aimed at the learner's doubt. Either answer stays with the lesson and in the transcript, and neither changes mastery. It works in lessons (answers to raised hands included), instant answers, explainer shorts and the conversation board.
+- **Something wrong with this question?**: after a practice, unit-quiz, library-quiz or review question is graded, the learner can ask the teacher to check it, with an optional note, typed or spoken. The teacher model checks the question, its answer key and the grading with thinking on, and the answer appears under the question: a verdict, then a few sentences aimed at the learner's doubt. A question that is wrong is fixed where it is kept (prompt, options, answer, explanation and hints; a review question from a lesson check fixes that check), and it shows **✎ Corrected**, with the original on hover. A question that depends on an unstated convention gets the convention written in, and an answer that is right under another reasonable reading counts as right. A short or written-out answer graded wrongly is graded again. The answer is then graded again against the fixed question, and mastery and the review schedule are recomputed as if it had been graded right the first time: the concept goes back to before that answer, takes the new score, then takes every later answer again in order, and a misconception the misgrade left is dropped. The round's stars, accuracy and streaks follow. The learner can go on while the check runs; a line at the top of the page reports what it found.
+- **Exact function plots**: a new board element draws curves from formulas the app computes point by point, so a sine wave or a parabola is never drawn wrong. It takes y = f(x), parametric and polar curves; labelled points (on a curve from their x alone), dashed guides such as asymptotes, shaded areas and tangents; and textbook axes through the origin with arrows, ticks in π for angles and an optional equal scale. Up to four parameters become sliders under the plot; moving one pauses the lesson. Exports and videos show the plot at its default values. Practice and quiz items can use a plot as their figure. Formulas are read in calculator syntax by the plugin's own parser and evaluated over numbers only, never run as code.
+
+### Changed
+
+- The first lesson of the harmonic-motion sample shows its wave as a plot with sliders for the amplitude and the angular frequency.
+
+### Fixed
+
+- **A cloud voice that stops answering is noticed in seconds.** A voice service that took a request and then sent nothing held the first step of a lesson for the full 45-second limit before the note about the missing voice appeared. Now a service that sends nothing for 10 seconds, or stops sending half way, counts as not responding: the note says so and the lesson goes on silently. A long step gets more time to start, up to the old 45 seconds, since Volcengine, MiniMax and many local servers answer only once the whole text is synthesized, and a slow service that is still sending is waited for as before. **Test** in Settings gives up just as quickly.
+- **A changed cloud voice is heard at once.** After another voice, model, service or address was chosen in Settings, **Test** and every sentence heard before in the same page still played the old voice until the page was reloaded, because the browser kept audio by its words alone. Audio is now kept per voice, so going back to a voice still finds its audio. **Test** waits for a field just left to be saved. Other open views of the plugin pick up changed settings, the system voice included, without being reopened: the side-panel board, the cards in a conversation, and the plugin in another window or tab of the same browser.
+- **Replaying a cloud voice no longer pays for it twice.** Synthesized audio was meant to be kept on this computer so that hearing a lesson again calls the service no more, but the folder for it was never created, so every replay was synthesized and paid for again. The folder is now made with the first audio.
+- **The microphone's note fits a narrow window.** Beside the microphone, a note (how to set up Voice input, a refused or missing microphone) was cut off on the left in a narrow window. It now narrows and moves inward to stay on the page.
+- **Voice questions use the microphone chosen in DSH.** The microphone followed the system default instead of the input device chosen in the details of DSH's Voice input. It now records from that device, and the button's tooltip names it. When the chosen one is unplugged, the plugin says so instead of switching to another microphone, as DSH does. DSH's speech service does not report the device; the plugin reads the choice where DSH's Voice input keeps it in the browser, and falls back to the system default if it cannot.
+
 ## 1.5.0 - 2026-10-21
 
 ### 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)
@@ -24,10 +25,10 @@
 | 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; 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 |
+| **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 |
-| **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 |
+| **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 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 (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 |
 | **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 |
@@ -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.5.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.7.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

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

package/docs/guide.zh-CN.md

@@ -44,20 +44,25 @@
 
 1. **先查一查**：首页的 **🌐 联网查资料** 默认打开（选了资料时默认关闭，以资料为准）。老师会先用 DSH 的网页搜索查几次这个主题，出题和设计课程时都会参考；查到的来源列在问卷上方，开课后在课程页大纲最下方的**参考来源**里也能看到，点开就是原网页。没配置 DeepSeek 密钥等情况下没法搜索时，会照常建课，并在问卷上方说明原因。每次搜索会用掉一些 DeepSeek 额度。
 2. **先认识一下你**：老师会根据你的主题出几道选择题，问你的基础、目的、想学多深等。每题都可以选「其他」自己写，拿不准的可以跳过。下面先选**课程规模**：**让老师决定**（按目标定，一个小问题可能只要一两讲）、**精简**（3–8 讲）、**标准**（10–20 讲）或**完整**（25–45 讲）。选了规模，老师就按这个讲数出课。再选**学习节奏**（冲刺约 6 周 / 稳步约 3 个月 / 不设期限）、**每周大约能学多久**，以及可选的**截止日期**；节奏只影响每周怎么排。想省事可以点**跳过提问，直接出课**。
-3. **课程蓝图**：点**生成课程蓝图**后，老师边写边展示：上面是进行到哪一步，下面是一个个单元逐渐长出来的大纲。写完后就是「单元 → 章 → 讲」的完整结构，每讲标有预计时长，末尾还有实战项目。你可以：
-   - 直接改标题，**上移 / 下移**调整顺序，**删除**不要的部分，或者**加一讲 / 加一章 / 加一个单元**。删除单元、章或已经开始学的讲之前会先确认；
+3. **课程蓝图**：点**生成课程蓝图**后，老师边写边展示：上面是进行到哪一步，下面是一张不断长出来的思维导图，课程在最左边，往右依次是单元、章和讲，镜头跟着最新写出的那一讲走（拖动或缩放后会停下，点**回到最新**接着跟）。写完后就是「单元 → 章 → 讲」的完整结构，每讲标有预计时长和**讲法**，末尾还有实战项目。讲法说明这一讲怎么讲：**直观理解**（先用图和例子建立感觉）、**定义概念**（把概念说准确）、**推导证明**（一步步推出来）、**动手应用**（用它解题）、**深入拓展**（边界情况和延伸）。老师讲课时会照着它来。你可以：
+   - 蓝图上方可以在**列表**和**导图**之间切换：导图看整体结构，点其中一讲就回到列表里编辑它；修改都在列表里做。
+   - 直接改标题，改每一讲的讲法，**上移 / 下移**调整顺序，**删除**不要的部分，或者**加一讲 / 加一章 / 加一个单元**。删除单元、章或已经开始学的讲之前会先确认；
    - 点某一讲旁边的 **✦**，让老师把它**拆成两讲**或**讲深一些**。改好的内容先出现在编辑器里，保存后才生效；
    - 在**用一句话修改**里写下要求，例如「多加一些编程实战」「第二单元讲浅一点」，点**修改**。老师会先给出**修改建议**，列出新增、删除、改名和调整的讲，点**应用修改**才生效，不满意就**放弃**。
 4. **确认开课**：点**确认，生成整门课**。老师会完善实战项目，并为第一单元准备练习；后面各讲的练习在你第一次打开这一讲（或它的练习）时准备。完成后进入课程页，点**继续学习**开始第一讲。
 
 开课以后也能改：在课程页右上角的 **⋯** 里选**编辑课程大纲**，可以加讲、加单元、调整顺序，或点**让老师续写一个单元**。保留下来的讲，学习进度不变。
 
+**补充资料**：后来找到了更好的教材或讲义，在 **⋯** 里选**补充资料**（编辑大纲时也有这个按钮），从资料库里勾选或当场上传，还可以写一句想怎么用，比如「重点补上第 5 章的例题」，再点**请老师看看怎么加**。老师会读这些资料，给出修改建议：新增哪些讲、哪些讲要讲深；点**应用修改**后才生效，资料也会关联到这门课，以后讲课时会引用它们。一门课最多关联 12 份资料。
+
 每一讲的板书在你打开它时才生成，同时会预备下一讲，所以不会一次性消耗大量额度。
 
 生成蓝图、确认开课这类要等一会儿的步骤，可以先去别的页面，生成会在后台继续，回来就能看到结果；想停下来就点**取消**。
 
 ## 黑板课堂
 
+第一次进课堂时，会有一段 6 步的**课堂导览**，依次介绍黑板、播放控制、举手提问、换个讲法、这一步不对？和课堂侧栏，导览结束后才开讲；可以随时**跳过**，也可以用方向键翻页。想再看一遍，点课堂顶部的 **?**。
+
 老师一边讲（语音 + 字幕），一边在黑板上逐字写出要点，画出示意图、图表，需要时还会放一段小动画。一页写满后接着写下一页。板书用手写体，讲到哪一句才写哪一句对应的内容，正在讲的那一行会用荧光笔划出来；字幕跟着朗读一句一句出现，公式按数学排版显示。想换回普通字体，到**设置 → 板书字体**选**标准体**。
 
 **画布**：整讲的板书一页接一页从上到下排在一张画布上，讲课时镜头自动跟着老师写的地方走。
@@ -69,6 +74,8 @@
 
 习惯一次看一页的话，到**设置 → 板书视图**选**分页**，用右上角的页码翻页。
 
+**函数图**：由公式画出的曲线，比如 y = A·sin(ωx)、圆、心形线，都由开窍按公式逐点算出来，不会画歪。坐标轴按课本的样子画：穿过原点、带箭头，三角函数按 π/2 标刻度，曲线旁写着它的公式；需要时还有标出的点、虚线（渐近线、对称轴）、阴影面积和切线。公式里有参数时，图下面有滑块，拖一拖就能看到曲线怎么变。一拖滑块课堂就暂停，看够了再点**播放**。导出的 PDF、PNG 和视频按默认值画成静态图。
+
 **备课中**：一讲第一次打开时，老师要先备课。能关掉推理的模型（比如 DeepSeek）不先构思、直接写板书，一两秒就开讲；关不掉推理的模型会用它最轻的一档先想一想。备课超过 3 秒时，黑板中间会显示备课进度：先是**构思**（只在模型先想的时候出现，显示已构思的字数），然后是**写板书**，写到第几步、这一步讲什么（小标题边写边出现），以及已用的时间。第一步一写好就开讲，后面的内容边讲边写；如果讲得比写得快，黑板上会显示老师正在写的那一步。下一讲会在你上这一讲时提前备好，通常打开就能直接上。
 
 白板右侧是**课堂侧栏**：上面是这一讲的**课堂要点**，讲到哪一条就亮到哪一条，讲完打勾；下面是**讲解记录**，老师说过的话和你的提问都在里面，点一条就回到那里；最下面是提问框。侧栏可以收起，窄屏时会放到白板下方。
@@ -84,7 +91,7 @@
 
 退出后再回来，课堂会从上次的位置继续。
 
-**朗读用不了时**：云端语音没保存密钥、密钥被拒、地址或区域填错、服务拒绝请求或超时，或者系统音色没法出声，控制栏上方会写明原因，这节课先静音往下讲，不再一步一步地重试；连不上、限流这类可能很快恢复的问题，连续两步失败才停用。点**重试**重新打开语音，并从这一步开头重讲；点**去设置**修改语音设置。停用期间**声音开 / 静音**显示为静音，点它也能重新打开语音。
+**朗读用不了时**：云端语音没保存密钥、密钥被拒、地址或区域填错、服务拒绝请求、一直没有回应或超时，或者系统音色没法出声，控制栏上方会写明原因，这节课先静音往下讲，不再一步一步地重试。服务 10 秒没有任何回应（一步讲得长时多等一会儿，最多 45 秒），或者音频传到一半停住 10 秒，就算没有回应；还在陆续传音频的慢服务会照常等完。连不上、限流这类可能很快恢复的问题，连续两步失败才停用。点**重试**重新打开语音，并从这一步开头重讲；点**去设置**修改语音设置。停用期间**声音开 / 静音**显示为静音，点它也能重新打开语音。
 
 **举手提问**：没听懂就点**举手提问**（或直接在侧栏的提问框里写）。老师会把回答插在当前这一步之后，边写边讲给你听，讲完接着原来的内容继续。问过的问题和「换个讲法」都会留在这一讲里，下次打开还在原来的位置，也会出现在侧栏的讲解记录里。
 
@@ -93,15 +100,25 @@
 2. 在它的详情里点**下载并准备**，下载本地识别模型（约 240 MB）；
 3. 准备好后回到课堂点麦克风。没准备好时麦克风是灰的，点它会提示还差哪一步。识别的语言跟随语音输入详情里的设置（默认自动）。
 
+**按 V 说话**：讲课时也可以不碰鼠标。按住 **V** 说话，松开就结束；或者按一下 **V** 开始，说完再按一下。课会自动暂停，侧栏收着时提问框会自动打开。识别出的文字一样先填进提问框，检查后按回车提问。用 V 问完一个问题后，键盘会回到课堂，空格、方向键和 V 又能直接用；在提问框里按 **Esc** 也能回到课堂。即时答疑和讲解短片里同样能用。DSH 对话旁边的白板不响应 V，免得在对话里打字时误开录音。鼠标停在**举手提问**或麦克风按钮上，会显示这个快捷键。
+
+录音用的麦克风跟随语音输入详情里选的**输入设备**（默认跟随系统）；选了具体设备时，鼠标停在麦克风按钮上会显示它的名字。选的那个拔掉了或用不了时，开窍会提示，不会悄悄换成别的麦克风：插上它，或在语音输入详情里换一个。
+
 **换个讲法**：对当前这一步不满意，点**换个讲法**，选择**打个比方 / 画图讲 / 举个例子 / 讲简单点 / 讲深一点**，新的讲解同样会插在这一步之后。
 
+**这一步不对？**：觉得老师讲错了（算错、写错、说法不对），点控制栏的**这一步不对？**。想质疑前面讲过的某一步，就把鼠标移到讲解记录里那一行上，点旁边的**不对？**。可以写一句（或点麦克风说）哪里不对，也可以不写，然后点**请老师核对**。老师会先仔细算一遍、想清楚，要等十几秒到半分钟，然后在黑板上回答：
+- **确实讲错了**：老师会框出错处、写出正确的内容并讲清楚原因。这一讲存档里的错处也会一起改正，包括后面沿用了这个错误的地方、旁白和随堂小测的答案。改过的地方旁边有红色的**✎ 已更正**，鼠标停在上面能看到原来写的内容。以后回放、导出 PDF 和 PNG 时都是改好的。
+- **其实没错**：老师会针对你的疑问讲清楚为什么是对的。
+
+核对的结果会留在这一讲里，也会出现在讲解记录中（标着 🧐）。质疑不会影响掌握度，可以放心问。即时答疑、讲解短片和对话里的白板也能这样核对。
+
 **随堂小测**：讲到关键处，老师会停下来出一道题，并问你**有多确定**（很确定 / 有点犹豫 / 猜的）。回答会影响掌握度：猜对不算完全掌握，自信地答错说明有误解，需要重点巩固。卡住时可以点**提示**，也可以**跳过**。
 
 **写出过程**：有计算或推导的一讲，会有一道题请你把过程写出来：一步一行，公式写在 $…$ 里，下面会实时预览。老师会逐行看，找出第一处出错的地方；没写对时点**看老师订正**，老师会在黑板上框出那一步，写出正确的做法，再接着讲。订正会留在这一讲里，也会出现在讲解记录中。
 
 **讲完之后**：给自己的掌握程度打个分（1–5）。如果某些知识点掌握得不好，老师会自动加一节**巩固课**；如果掌握得很好，后面会讲得更深一些。
 
-课堂顶部还有：**练习**（去做这一讲的练习）、**导出板书**、**导出视频**（见[讲解短片](#学习工具即时答疑与讲解短片)）和**重新备课**（重新生成这一讲的板书）。
+课堂顶部还有：**练习**（去做这一讲的练习）、**讲义**（见下）、**导出板书**、**导出视频**（见[讲解短片](#学习工具即时答疑与讲解短片)）和**重新备课**（重新生成这一讲的板书）。
 
 **导出板书**有三种格式：
 
@@ -111,11 +128,13 @@
 
 讲解短片顶部也有同样的**导出板书**。
 
+**讲义**：点课堂顶部的**讲义**（或学完一讲后弹窗里的**本讲讲义**），老师会把这一讲整理成一页讲义：这一讲讲了什么、每个要点配一句能讲给别人听的话、一道带步骤的例题、常见错误、术语表和三道自测题。讲义按这一讲的板书来写，生成一次就保存下来；点**打印**可以打印或存成 PDF（自测题的答案在屏幕上折叠，打印时会展开），想重写就点**重新生成**。
+
 ## 课程页
 
 | 标签 | 内容 |
 | --- | --- |
-| **大纲** | 全部单元、章和讲，带学习状态；自动加入的巩固课标有「巩固」。每个单元都有**单元速查表**和**单元测验** |
+| **大纲** | 全部单元、章和讲，带学习状态和讲法（直观理解、定义概念等）；自动加入的巩固课标有「巩固」。每个单元都有**单元速查表**和**单元测验** |
 | **练习与测验** | 每讲的练习、单元测验和**开始复习**（只复习这门课） |
 | **速查表** | 单元速查表，按主题整理公式、定义和要点 |
 | **闪卡** | 这门课的闪卡，按复习计划出现 |
@@ -126,9 +145,18 @@
 
 ## 练习、闪卡与复习
 
-- **练习**：单选、多选、填空、数值计算和排序题会立即判分；简答题由老师按要点批改，告诉你答到了哪些、漏了哪些。做完可以**看解析**。需要图的题会附一张示意图。
+- **练习**：单选、多选、填空、数值计算和排序题会立即判分；简答题由老师按要点批改，告诉你答到了哪些、漏了哪些。做完可以**看解析**。需要图的题会附一张示意图，或一张按公式算出的函数图。
   - 可以用键盘作答：1–4 选择，Enter 提交或继续，H 看提示；题号旁边会显示连对了几题。
   - 做完一组会看到星级、正确率、最长连对，以及这一轮之后各知识点的掌握程度，最后给出一个下一步建议，比如回到这一讲再听一遍、复习这门课，或者做单元测验。
+  - **这题有问题？**：判完分后，觉得题目、答案或判分不对（答案标错了、选项有两个对的、单位错了、简答题判得太严），点结果框里的**这题有问题？**。可以写一句（或点麦克风说）哪里不对，也可以不写，然后点**请老师核对**。老师会先自己把题做一遍、仔细核对，要等几秒到半分钟；这期间可以先做下一题，核对完会在页面顶部提示。结果显示在这道题下面的**老师核对**里：
+    - **确实有错**：老师会把存档里的这道题改好（题目、选项、答案、解析、提示里错的地方），题上出现红色的**✎ 已更正**，鼠标停在上面能看到原来写的内容。然后按改好的题重新判你这次的作答。
+    - **题目没说清楚**（比如没说 g 取 9.8 还是 10）：老师会把约定写进题目；你按另一种合理理解答对的，这次算对。
+    - **判分有误**（简答题、写过程的题）：题目不动，只重新判这次的作答。
+    - **其实没错**：老师会针对你的疑问讲清楚为什么，成绩和掌握度都不变。
+
+    重新判分后，掌握度和复习时间会按新的分数重新算，就像当初判对了一样：这次作答留下的「误解」标记也会去掉，这一轮的星级、正确率和连对也按新结果算。每讲的练习、单元测验、学习工具里的测验和复习里的题都可以这样核对。
+
+    题目改好后，你以前对同一道题的作答（上一轮练习、复习里，或课上的小测）也会按改好的题重新判，结果框里会说重判了几次。题目确实有错时，按改好的答案判，分数可能升也可能降；题目没说清楚时，只会往上调，因为你当时按另一种理解答的可能也对。简答题和写过程的题由 AI 重新批改最近 3 次。只有最近 50 次作答留有记录，更早的不再重判。
 - **闪卡**：点击翻面，然后按记忆情况选**忘了 / 困难 / 记得 / 简单**。开窍用间隔重复安排下次复习的时间，记得越牢，间隔越长。
 - **复习**：学过的知识点也会按遗忘曲线回来。学习计划会提醒你**有 N 个知识点该复习了**，点**开始复习**即可。
 
@@ -146,6 +174,8 @@
 
 每份资料都可以一键**用它建课**，或者生成**速查表、闪卡、笔记、测验**，以及**消化**成概要、结构、核心观点、论点与论据、术语表和值得思考的问题。
 
+**找资料**：资料多了，在资料列表上方的搜索框里输入，会按标题和主题即时筛选；按回车（或点**搜正文**）会在所有资料的正文里搜，列出最相关的段落，带资料名、页码和高亮的上下文，点一条就跳到那份资料。搜索在本机进行，不调用模型。
+
 ## 学习工具、即时答疑与讲解短片
 
 - **学习工具**：先**选择资料**，再生成速查表、笔记、闪卡组或测验。可以在**重点**里写上范围，例如「期中考试范围第 3–6 章」。速查表可以调**列数、字号**，开关**高亮重点**，隐藏某些部分，然后**打印**。
@@ -166,7 +196,7 @@
 
 - **学习计划**：设置**学习日**和**每周大约能学多久**，在**考试与截止日期**里添加重要日期。开窍会把所有在学课程的讲次和复习排进日程；按当前节奏赶不上截止日期时，会提醒你，并建议每周需要的学习时间。
 - **月历和打勾**：学习计划页是一张月历，点某一天就能看到那天的安排。学完一讲、做完一次复习会自动打勾；今天和之前的事项也可以手动勾上或取消（比如那一讲你在别处学过了），首页的**今天的安排**里同样可以勾。手动勾掉的讲次算作学完，后面的日子会重新排；今天已经学过的时间会从今天的安排里扣掉，不会越学越多。过去的日子保留当天的安排和完成情况，没完成的会自动顺延到之后。
-- **我的画像**：老师会记住你的背景、目标、擅长和薄弱的地方、喜欢的讲解方式，以及它自己的备忘，让每门课都更贴合你。每一项都可以直接修改（每行一条），也可以**清空画像**。
+- **我的画像**：老师会记住你的背景、目标、擅长和薄弱的地方、喜欢的讲解方式，以及它自己的备忘，让每门课都更贴合你。每一项都可以直接修改（每行一条），也可以**清空画像**。在**怎么称呼你**里填上称呼，老师每讲开课时会这样叫你一次。
 
 ## 在 DSH 对话里使用
 
@@ -185,7 +215,7 @@
 - **语音讲解**：
   - **语音来源**：系统语音（免费）/ 云端语音 / 不朗读。
   - **系统音色**：可以选**自动选择**，或指定一个音色。没有合适的中文音色时，可以在 macOS 的「系统设置 → 辅助功能 → 朗读内容」或 Windows 的「设置 → 时间和语言 → 语音」里添加。
-  - **云端语音**：选择服务（OpenAI 兼容接口、火山引擎（豆包语音）、MiniMax、Azure 语音），填写接口地址、模型、音色等，再**保存密钥**。密钥保存在 DSH 的凭据库中，只在本机 Host 端使用。合成过的语音会缓存在本机，重播不再计费。
+  - **云端语音**：选择服务（OpenAI 兼容接口、火山引擎（豆包语音）、MiniMax、Azure 语音），填写接口地址、模型、音色等，再**保存密钥**。密钥保存在 DSH 的凭据库中，只在本机 Host 端使用。合成过的语音按服务和音色缓存在本机，重播不再计费；换了服务或音色后，听过的句子会用新的声音重新合成。
   - **默认语速**和**试听**。试听、保存或清除密钥失败时，原因显示在对应按钮下方。
 - **白板外观**：跟随系统 / 白板 / 黑板。
 - **板书字体**：手写体 / 标准体。

package/lib/agent.js

@@ -1,4 +1,4 @@
-import { O as generateJson, b as quizPrompt, c as detectLanguage, dt as normalizePractice, gt as text, t as getRuntime, vt as newId, z as readProfile } from "./runtime-DqCjJ0yL.js";
+import { C as quizPrompt, Mt as newId, N as generateJson, W as readProfile, kt as text, l as detectLanguage, t as getRuntime, wt as normalizePractice } from "./runtime-DfoeKFPj.js";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 //#region src/agent.js
 const name = "aha-tutor-agent";