dsh-aha-tutor 1.2.0 → 1.4.0

package/AGENTS.md

@@ -18,7 +18,9 @@ This file governs the entire `dsh-aha-tutor` repository.
   - `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.
+- 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.
 - 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.
@@ -38,7 +40,7 @@ The plugin runs inside DSH on both systems. Every change must keep working on bo
 
 ## Security requirements
 
-- Model output, uploads, course packs and fetched web pages are untrusted. 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`.
 - 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,57 @@
 
 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.4.0 - 2026-10-20
+
+### Added
+
+- **Web research before a course**: a new course can start by looking the subject up with DSH's web search (on by default, off when materials are attached, switchable on the home page). A few searches are made, and what comes back informs the questions and the blueprint. The course page lists the sources under **Sources**. When DSH cannot search, for example without a DeepSeek key, the course is designed as before and the questionnaire says why.
+- **Plan calendar with ticks**: the plan page shows a month calendar; past days keep what was planned and what came of it. Finishing a lesson or a review ticks it on its own, and today's or an earlier day's items can be ticked or unticked by hand, here and on the home page. A lesson ticked by hand counts as done, and the days ahead are planned again; time already studied today comes off today's list instead of pulling the next lesson in.
+- **Live lesson preparation**: when preparing a lesson takes more than three seconds, the board shows what the teacher is doing instead of a spinner: thinking the lesson through (for a model that thinks first, with how much it has thought), then writing step N with that step's heading appearing as it is written, how many steps are ready and the seconds so far. When the lesson catches up with the writing, it shows the step being written.
+- **Board export as PDF and pictures**: **Export board** in a lesson or a short now offers a PDF with one board page per page, a PNG picture per page (several pages come as a ZIP) and the Markdown text as before. The pages are drawn from the board itself, so they keep the handwriting font, formulas, highlights, marks and the questions asked in class, in the board look chosen in Settings.
+
+### Changed
+
+- **Lessons start in a second or two.** Lesson boards (prefetched ones too), re-explanations, instant answers and explainer shorts no longer wait for the model to think first: they ask for no reasoning where the model can turn it off (DeepSeek, for one) and for the model's lightest effort otherwise (low for Claude 5.5, minimal for GPT-5). With DeepSeek-V4.1-Flash, three lessons started 1–2 seconds after they were opened instead of 25–77 seconds, and their boards kept the same shape: hook, figures, a worked example, a written-working check and a recap.
+
+### Fixed
+
+- **The cloud voice works.** With **Cloud voice** chosen, opening a lesson left the plugin page blank, and it stayed blank on every return because the plugin reopens the last screen; **Test** in Settings did nothing. Lessons now play with the cloud voice, **Test** shows what went wrong (a missing key, for one), and a voice that fails to start lets the lesson go on silently instead of breaking the page.
+- **A lesson says why it has no voice.** When the cloud voice fails (no key saved, a rejected key, a wrong address or region, a refused request, a timeout) or the system voice cannot speak, a note above the controls gives the reason and the lesson goes on silently, instead of going quiet without a word and asking the service again at every step. A failure that may pass, such as a lost connection or a busy service, turns the voice off only when the next step fails too. **Retry** turns the voice back on and tells the step again, **Settings** opens the voice settings, and the sound button shows the lesson as muted until then. In Settings, a failed **Test** or key change is reported under its button instead of at the top of the page, where a narrow window hid it, and removing a key that fails now says so.
+- **Long formulas fit their board column.** A display formula wider than its column was cut off at the column's edge, the rest hidden behind a scroll bar macOS does not show (the overall equation of photosynthesis ended at "C₆H"). It now shrinks onto one line when that keeps at least 70 % of its size, and otherwise breaks after its =, + and → like a teacher carrying on below; only a piece that cannot break, such as a bracket or a matrix, shrinks further. A formula on several lines is written one line at a time. PDF and PNG pages follow the same rule at their own column width.
+- While a formula is written, the pencil follows the writing instead of waiting at the formula's end, which for a long formula was over the other column.
+- An equation number such as (1) follows its formula instead of covering the formula's last characters, on the board and in exports.
+- **Formulas are read as what they show.** Narration (system and cloud voices) and exported videos turned formulas into text that kept the LaTeX names the plugin did not know, such as "P(A mid B)", "xrightarrow光" or "frac6.63×10⁻³⁴…"; about one formula in nine that the model wrote in testing was affected. Every command now reads as what it shows: a condition over an arrow or an equals sign follows it in brackets ("→(光、叶绿体)", "=(点燃)"), marks stay on their letters (D̄, v⃗), the rows of a derivation, a system or a matrix are separated by semicolons, and a command the plugin does not know is left out instead of read out.
+- A board could stop in the middle of a step when the model's reasoning used up the output limit (DeepSeek at low effort once thought 40,000 characters before a lesson). A low effort now gets 16k tokens of room for its reasoning instead of 8k.
+- On a narrow board, the small "preparing" notice stays on one line instead of breaking after a few characters.
+- **Instant answers and shorts fit narrow windows.** In one column (a phone, or DSH at 1024 px with its sidebar open), the follow-up box squeezed an answer's classroom until its controls disappeared, and a short sat in a 16:9 frame that showed little more than its title. Both pages now scroll as a whole: the classroom keeps its full height, with the board at about 60% of the screen and the captions, controls and transcript under it, then the follow-up box and the history. Opening an item from the history, asking a follow-up or making a short scrolls up to the classroom. In wide windows a short now fills the space under its form, as a lesson does.
+- **Formulas render as KaTeX meant them again.** The plugin bundled KaTeX 0.16 while DSH 0.2.1 styles formulas with KaTeX 0.18.7's stylesheet, which renamed its layout classes, so superscripts and subscripts were drawn at full size and stacked symbols such as ≠ came apart. The bundled KaTeX is now 0.18.7, and a test keeps the two in step.
+- **A crash no longer blanks the plugin.** Anything that went wrong while showing a screen left the whole plugin page blank, and because the plugin reopens the last screen, it stayed blank after a reload, with no way to reach Settings. The screen now shows a short notice with **Retry** and **Back to home** while the navigation keeps working, and the next visit starts at home instead of reopening it. The board tab and the cards in a conversation show the notice with **Retry** in place of the part that failed, instead of DSH swapping them out until it reloads.
+- Dashed lines in board figures (guide lines, heights) stay dashed after they are drawn instead of turning solid.
+- A highlight may contain a single "=", so `==乘积 = 0==` is highlighted instead of showing its marks.
+- **Explain differently works while the board is still being written.** Choosing a style before a new lesson's board was saved showed "Nothing to re-explain yet"; it now re-explains the step on screen from the steps already written. The same goes for instant answers and explainer shorts, where re-explaining, raising a hand or a correction during the writing failed with "Not found". A raised hand and a correction now see the board written so far, a lesson being regenerated is asked about its new steps rather than the old saved ones, and a follow-up in instant help is asked about its own answer rather than the previous one.
+- **Every error shows in your language.** Messages that reached the Chinese interface in English ("出了点问题：…" followed by English) now have their own Chinese and English wording: empty inputs, files that cannot be imported, course packs, cloud voice settings and keys, missing items, a lost connection to DSH and others. Messages that only a bug could cause share one line. A test checks that every error the host can send has both.
+
+## 1.3.0 - 2026-10-19
+
+### Added
+
+- **Show your working**: a lesson with a calculation or derivation asks once for the whole working, typed with a live math preview. The grader finds the first line that goes wrong, and the teacher corrects it on the board, starting from that line. The correction stays with the lesson and appears in the transcript.
+- **Course size and a visible build**: the questionnaire asks how big the course should be (let the teacher decide, short 3–8, standard 10–20 or full 25–45 lessons). While the blueprint is written you see the steps and the outline growing unit by unit.
+- **Blueprint editing**: split a lesson in two or take it deeper with one click; deleting a unit, a chapter or a started lesson asks first; and **Edit outline** in a course's ⋯ menu reopens the editor after the course has started, with **Ask for one more unit**. Progress on lessons that stay is kept.
+- **Practice**: items can carry a figure (drawn through the SVG allow-list), a round ends with stars, accuracy, the best streak, how each concept moved and one next step, the current streak shows while you answer, and the keyboard works (1–4 to choose, Enter to submit or continue, H for a hint).
+- **Course page**: concepts show five stages (not started, weak, learning, proficient, mastered), and a **Next step** card suggests due reviews first, then the weakest concept, then the next lesson.
+
+### Fixed
+
+- **Reasoning models no longer cut lessons and shorts short.** At its default effort a reasoning model (DeepSeek through DSH or a relay, among others) could spend the whole output limit thinking, so a short stopped after two steps ("came back too short") or came back empty (`EMPTY_RESPONSE`). Boards, shorts, re-explanations and quick answers now ask for a low reasoning effort, every call leaves room for its reasoning within the model's limit, and an answer lost to reasoning is retried with more room. Model errors in the classroom and on checks now show in your language.
+
+### Changed
+
+- **AI changes to a blueprint are proposals**: the editor lists the lessons added, removed, renamed and changed, and nothing changes until you apply them.
+- Mastery meters stay empty until there is evidence; an untouched concept no longer lights a segment. **Start review** on a course page reviews that course only.
+- Plans and today's list name a course by its emoji and main title (the part before a colon), with the full title on hover.
+
 ## 1.2.0 - 2026-10-19
 
 ### Added

package/README.en.md

@@ -23,16 +23,16 @@
 
 | Feature | What you get |
 | --- | --- |
-| **A course made for you** | Say what you want to learn or drop in a textbook. The tutor first asks a few multiple-choice questions about your background, goal and time, then proposes a unit → chapter → lesson blueprint you can edit by hand or by asking. Confirming prepares the hands-on projects and the first unit's practice; later lectures get theirs when you reach them |
+| **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 |
-| **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, and a revisit lesson is added automatically for concepts that did not stick |
+| **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 |
-| **Practice, flashcards, reviews** | Every lesson has practice (open answers graded by the model); flashcards and concepts come back on a spaced-repetition schedule, and the study plan leaves time for them |
+| **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 |
-| **Explainer shorts and video export** | A two-minute whiteboard explainer from a topic or a link; any lesson exports to a video with the handwriting, captions and a watermark |
+| **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 |
-| **Study plan and learner profile** | Lessons are scheduled around your weekly time, study days and deadlines, with warnings when a deadline is at risk; the tutor remembers your background and weak spots, which you can view, edit or clear |
+| **Study plan and learner profile** | Lessons are scheduled around your weekly time, study days and deadlines, with warnings when a deadline is at risk; a month calendar ticks what you finish, takes ticks by hand and replans the days ahead; the tutor remembers your background and weak spots, which you can view, edit or clear |
 | **In conversations too** | A new conversation preset, "开窍 · AI 私人老师", lets the tutor explain on the whiteboard, run interactive quizzes, design a course or make a cheat sheet right from a DSH chat |
 
 Two sample courses ship with the plugin (harmonic motion and Bayesian thinking, in Chinese) so you can try the chalkboard classroom without spending tokens.
@@ -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.2.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.4.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

@@ -23,16 +23,16 @@
 
 | 能力 | 体验 |
 | --- | --- |
-| **为你定制一门课** | 说一句想学什么，或者丢进一本教材。老师先用几道选择题了解你的基础、目标和时间，再给出「单元 → 章 → 讲」的课程蓝图。你可以直接改，也可以用一句话让它改，确认后生成实战项目和第一单元的练习，后面各讲的练习学到时再出 |
+| **为你定制一门课** | 说一句想学什么，或者丢进一本教材。老师可以先联网查一查这个主题，再用几道选择题了解你的基础、目标、时间和想要的课程规模，再一边写一边展示「单元 → 章 → 讲」的课程蓝图。你可以直接改，可以让老师把一讲拆开或讲深，也可以用一句话让它改（先看修改建议再应用）；开课后还能继续加讲、加单元。确认后生成实战项目和第一单元的练习，后面各讲的练习学到时再出 |
 | **手写黑板课堂** | 老师一边讲（语音 + 字幕），一边用手写体在黑板上逐字写下要点、公式、示意图和图表，讲到哪句写哪句，正在讲的内容用荧光笔划出；侧栏显示课堂要点进度和讲解记录；随时暂停、回放、变速 |
-| **随堂小测与自适应** | 讲到关键处会停下来考你一题，并问你「有多确定」。猜对、犹豫、自信地答错，会被区别对待；学完一讲后，薄弱的知识点会自动加一节巩固课 |
+| **随堂小测与自适应** | 讲到关键处会停下来考你一题，并问你「有多确定」。猜对、犹豫、自信地答错，会被区别对待；有计算的一讲会请你写出过程，写错了老师就在黑板上订正。学完一讲后，薄弱的知识点会自动加一节巩固课 |
 | **举手提问、换个讲法** | 没听懂就举手，老师在黑板上专门回答你，讲完回到原来的进度；也可以让它用打比方、画图、举例、讲简单点或讲深一点的方式重讲这一步 |
-| **练习、闪卡与复习** | 每讲都有练习，简答题由 AI 批改；闪卡和知识点按间隔重复安排复习，学习计划会自动给复习留出时间 |
+| **练习、闪卡与复习** | 每讲都有练习，题目可以带示意图，简答题由 AI 批改，支持键盘作答；做完一组给出星级、掌握程度变化和下一步建议。闪卡和知识点按间隔重复安排复习，学习计划会自动给复习留出时间 |
 | **资料变课程** | 支持 PDF、Word、PPT、Markdown、网页链接和图片（图片需要支持识图的模型）。讲课和速查表会引用原文页码；长文档可以一键「消化」成结构、论点和术语表 |
 | **速查表、笔记、测验** | 按主题整理的可打印速查表（列数、字号、高亮可调），以及笔记、闪卡组和测验 |
-| **讲解短片 + 导出视频** | 输入一个主题或网址，得到一段约两分钟的白板讲解；任何一讲都能导出成带板书动画、字幕和水印的视频，适合分享 |
+| **讲解短片 + 导出** | 输入一个主题或网址，得到一段约两分钟的白板讲解；任何一讲都能导出成带板书动画、字幕和水印的视频，也能把板书导出成 PDF（一页一张板书，带手写字体和公式）或每页一张的 PNG 图片 |
 | **实战项目** | 代码类项目一键生成项目文件夹和起始文件，并在 DSH 里打开一个会话，让编程 Agent 陪你做；做完回来提交，老师按评分标准逐项点评 |
-| **学习计划与画像** | 按每周时间、学习日和截止日期自动排课并提示进度风险；老师会记住你的背景和薄弱点，你可以随时查看、修改或清空 |
+| **学习计划与画像** | 按每周时间、学习日和截止日期自动排课并提示进度风险；月历里学完自动打勾，也能手动勾选，计划随之重排；老师会记住你的背景和薄弱点，你可以随时查看、修改或清空 |
 | **对话里也能用** | 新增「开窍 · AI 私人老师」会话预设：在 DSH 对话中，老师可以上白板讲解、出互动小测、帮你建课、做速查表 |
 
 不想先花 token？首页自带两门示例课（「简谐运动」「贝叶斯思维」），打开就能体验完整的黑板课堂。
@@ -47,7 +47,7 @@
    dsh-aha-tutor
    ```
 
-   安装源选择**官方源**，点击**安装**。新版本刚发布的 24 小时内，DSH 的 pnpm 会因为发布冷却期暂缓安装，这时请填入精确版本，例如 `dsh-aha-tutor@1.2.0`。
+   安装源选择**官方源**，点击**安装**。新版本刚发布的 24 小时内，DSH 的 pnpm 会因为发布冷却期暂缓安装，这时请填入精确版本，例如 `dsh-aha-tutor@1.4.0`。
 
 2. **完全退出并重新打开** DSH 桌面应用。只刷新页面不会加载 Host 端的新插件。
 

package/docs/guide.zh-CN.md

@@ -42,11 +42,15 @@
 
 ## 定制一门课
 
-1. **先认识一下你**：老师会根据你的主题出几道选择题，问你的基础、目的、想学多深等。每题都可以选「其他」自己写，拿不准的可以跳过。下面再选**学习节奏**（冲刺约 6 周 / 稳步约 3 个月 / 不设期限）、**每周大约能学多久**，以及可选的**截止日期**。想省事可以点**跳过提问，直接出课**。
-2. **课程蓝图**：点**生成课程蓝图**后，老师会给出「单元 → 章 → 讲」的结构，每讲标有预计时长，末尾还有实战项目。你可以：
-   - 直接改标题，**上移 / 下移**调整顺序，**删除**不要的部分，或者**加一讲 / 加一章 / 加一个单元**；
-   - 在**用一句话修改**里写下要求，例如「多加一些编程实战」「第二单元讲浅一点」，点**修改**。
-3. **确认开课**：点**确认，生成整门课**。老师会完善实战项目，并为第一单元准备练习；后面各讲的练习在你第一次打开这一讲（或它的练习）时准备。完成后进入课程页，点**继续学习**开始第一讲。
+1. **先查一查**：首页的 **🌐 联网查资料** 默认打开（选了资料时默认关闭，以资料为准）。老师会先用 DSH 的网页搜索查几次这个主题，出题和设计课程时都会参考；查到的来源列在问卷上方，开课后在课程页大纲最下方的**参考来源**里也能看到，点开就是原网页。没配置 DeepSeek 密钥等情况下没法搜索时，会照常建课，并在问卷上方说明原因。每次搜索会用掉一些 DeepSeek 额度。
+2. **先认识一下你**：老师会根据你的主题出几道选择题，问你的基础、目的、想学多深等。每题都可以选「其他」自己写，拿不准的可以跳过。下面先选**课程规模**：**让老师决定**（按目标定，一个小问题可能只要一两讲）、**精简**（3–8 讲）、**标准**（10–20 讲）或**完整**（25–45 讲）。选了规模，老师就按这个讲数出课。再选**学习节奏**（冲刺约 6 周 / 稳步约 3 个月 / 不设期限）、**每周大约能学多久**，以及可选的**截止日期**；节奏只影响每周怎么排。想省事可以点**跳过提问，直接出课**。
+3. **课程蓝图**：点**生成课程蓝图**后，老师边写边展示：上面是进行到哪一步，下面是一个个单元逐渐长出来的大纲。写完后就是「单元 → 章 → 讲」的完整结构，每讲标有预计时长，末尾还有实战项目。你可以：
+   - 直接改标题，**上移 / 下移**调整顺序，**删除**不要的部分，或者**加一讲 / 加一章 / 加一个单元**。删除单元、章或已经开始学的讲之前会先确认；
+   - 点某一讲旁边的 **✦**，让老师把它**拆成两讲**或**讲深一些**。改好的内容先出现在编辑器里，保存后才生效；
+   - 在**用一句话修改**里写下要求，例如「多加一些编程实战」「第二单元讲浅一点」，点**修改**。老师会先给出**修改建议**，列出新增、删除、改名和调整的讲，点**应用修改**才生效，不满意就**放弃**。
+4. **确认开课**：点**确认，生成整门课**。老师会完善实战项目，并为第一单元准备练习；后面各讲的练习在你第一次打开这一讲（或它的练习）时准备。完成后进入课程页，点**继续学习**开始第一讲。
+
+开课以后也能改：在课程页右上角的 **⋯** 里选**编辑课程大纲**，可以加讲、加单元、调整顺序，或点**让老师续写一个单元**。保留下来的讲，学习进度不变。
 
 每一讲的板书在你打开它时才生成，同时会预备下一讲，所以不会一次性消耗大量额度。
 
@@ -56,6 +60,8 @@
 
 老师一边讲（语音 + 字幕），一边在黑板上逐字写出要点，画出示意图、图表，需要时还会放一段小动画。一页写满后自动翻到下一页。板书用手写体，讲到哪一句才写哪一句对应的内容，正在讲的那一行会用荧光笔划出来；字幕跟着朗读一句一句出现，公式按数学排版显示。想换回普通字体，到**设置 → 板书字体**选**标准体**。
 
+**备课中**：一讲第一次打开时，老师要先备课。能关掉推理的模型（比如 DeepSeek）不先构思、直接写板书，一两秒就开讲；关不掉推理的模型会用它最轻的一档先想一想。备课超过 3 秒时，黑板中间会显示备课进度：先是**构思**（只在模型先想的时候出现，显示已构思的字数），然后是**写板书**，写到第几步、这一步讲什么（小标题边写边出现），以及已用的时间。第一步一写好就开讲，后面的内容边讲边写；如果讲得比写得快，黑板上会显示老师正在写的那一步。下一讲会在你上这一讲时提前备好，通常打开就能直接上。
+
 白板右侧是**课堂侧栏**：上面是这一讲的**课堂要点**，讲到哪一条就亮到哪一条，讲完打勾；下面是**讲解记录**，老师说过的话和你的提问都在里面，点一条就回到那里；最下面是提问框。侧栏可以收起，窄屏时会放到白板下方。
 
 **播放控制**
@@ -69,32 +75,46 @@
 
 退出后再回来，课堂会从上次的位置继续。
 
+**朗读用不了时**：云端语音没保存密钥、密钥被拒、地址或区域填错、服务拒绝请求或超时，或者系统音色没法出声，控制栏上方会写明原因，这节课先静音往下讲，不再一步一步地重试；连不上、限流这类可能很快恢复的问题，连续两步失败才停用。点**重试**重新打开语音，并从这一步开头重讲；点**去设置**修改语音设置。停用期间**声音开 / 静音**显示为静音，点它也能重新打开语音。
+
 **举手提问**：没听懂就点**举手提问**（或直接在侧栏的提问框里写）。老师会把回答插在当前这一步之后，边写边讲给你听，讲完接着原来的内容继续。问过的问题和「换个讲法」都会留在这一讲里，下次打开还在原来的位置，也会出现在侧栏的讲解记录里。
 
 **换个讲法**：对当前这一步不满意，点**换个讲法**，选择**打个比方 / 画图讲 / 举个例子 / 讲简单点 / 讲深一点**，新的讲解同样会插在这一步之后。
 
 **随堂小测**：讲到关键处，老师会停下来出一道题，并问你**有多确定**（很确定 / 有点犹豫 / 猜的）。回答会影响掌握度：猜对不算完全掌握，自信地答错说明有误解，需要重点巩固。卡住时可以点**提示**，也可以**跳过**。
 
+**写出过程**：有计算或推导的一讲，会有一道题请你把过程写出来：一步一行，公式写在 $…$ 里，下面会实时预览。老师会逐行看，找出第一处出错的地方；没写对时点**看老师订正**，老师会在黑板上框出那一步，写出正确的做法，再接着讲。订正会留在这一讲里，也会出现在讲解记录中。
+
 **讲完之后**：给自己的掌握程度打个分（1–5）。如果某些知识点掌握得不好，老师会自动加一节**巩固课**；如果掌握得很好，后面会讲得更深一些。
 
-课堂顶部还有：**练习**（去做这一讲的练习）、**导出板书**（Markdown 文件）、**导出视频**（见[讲解短片](#学习工具即时答疑与讲解短片)）和**重新备课**（重新生成这一讲的板书）。
+课堂顶部还有：**练习**（去做这一讲的练习）、**导出板书**、**导出视频**（见[讲解短片](#学习工具即时答疑与讲解短片)）和**重新备课**（重新生成这一讲的板书）。
+
+**导出板书**有三种格式：
+
+- **PDF 文档**：一页放一页板书，手写字体、公式、荧光笔、圈画和课上的提问都在，外观跟随设置里的白板外观（白板或黑板）。想打印就先把白板外观切到白板。
+- **PNG 图片**：每页板书一张图片；不止一页时打包成一个 ZIP 文件。
+- **Markdown 文本**：板书的文字和公式源码，方便粘贴到笔记软件里。
+
+讲解短片顶部也有同样的**导出板书**。
 
 ## 课程页
 
 | 标签 | 内容 |
 | --- | --- |
 | **大纲** | 全部单元、章和讲，带学习状态；自动加入的巩固课标有「巩固」。每个单元都有**单元速查表**和**单元测验** |
-| **练习与测验** | 每讲的练习、单元测验和**开始复习** |
+| **练习与测验** | 每讲的练习、单元测验和**开始复习**（只复习这门课） |
 | **速查表** | 单元速查表，按主题整理公式、定义和要点 |
 | **闪卡** | 这门课的闪卡，按复习计划出现 |
 | **项目** | 实战项目，见[实战项目](#实战项目) |
-| **进度** | 每个知识点的掌握度，以及老师发现的误解（⚠） |
+| **进度** | 每个知识点的掌握程度（未开始、薄弱、学习中、熟练、掌握五级），以及老师发现的误解（⚠） |
 
-标题旁边是学习进度和剩余时间；右上角的 **⋯** 菜单可以**导出课程包**、**归档**和**删除课程**。所有课程都在左侧的**我的课程**里，可以按学习中、已学完、已归档筛选和搜索。
+标题旁边是学习进度和剩余时间；下面的**下一步**给出一个建议：有到期的复习就先复习，其次练一练最薄弱的知识点，再往下是下一讲。右上角的 **⋯** 菜单可以**编辑课程大纲**、**导出课程包**、**归档**和**删除课程**。大纲里每一讲的掌握度条在学过之前是空的。所有课程都在左侧的**我的课程**里，可以按学习中、已学完、已归档筛选和搜索。
 
 ## 练习、闪卡与复习
 
-- **练习**：单选、多选、填空、数值计算和排序题会立即判分；简答题由老师按要点批改，告诉你答到了哪些、漏了哪些。做完可以**看解析**。
+- **练习**：单选、多选、填空、数值计算和排序题会立即判分；简答题由老师按要点批改，告诉你答到了哪些、漏了哪些。做完可以**看解析**。需要图的题会附一张示意图。
+  - 可以用键盘作答：1–4 选择，Enter 提交或继续，H 看提示；题号旁边会显示连对了几题。
+  - 做完一组会看到星级、正确率、最长连对，以及这一轮之后各知识点的掌握程度，最后给出一个下一步建议，比如回到这一讲再听一遍、复习这门课，或者做单元测验。
 - **闪卡**：点击翻面，然后按记忆情况选**忘了 / 困难 / 记得 / 简单**。开窍用间隔重复安排下次复习的时间，记得越牢，间隔越长。
 - **复习**：学过的知识点也会按遗忘曲线回来。学习计划会提醒你**有 N 个知识点该复习了**，点**开始复习**即可。
 
@@ -118,6 +138,8 @@
 - **即时答疑**：不用建课，直接提问，老师在白板上讲给你听。可以**继续追问**，以前问过的问题都在**历史记录**里。
 - **讲解短片**：输入一个主题，或者贴一个网址，点**生成短片**，得到一段约两分钟的白板讲解。
 
+窄屏时（手机，或者 DSH 侧栏展开、窗口不够宽时），即时答疑和讲解短片整页上下滚动：课堂在上，板书约占屏幕高度的 60%，下面依次是字幕、播放控制和讲解记录，再往下是追问框和历史记录。从历史记录打开、继续追问或生成短片后，页面会自动滚回课堂。
+
 **导出视频**：短片和课程里的任意一讲都可以导出成 WebM 视频（1280×720），带手写板书、字幕和水印，并跟随白板外观（白板或黑板）。黑板上的小动画在视频里以一帧静态画面出现。浏览器的系统语音录不进视频，用系统语音导出的视频有字幕、没有声音；在设置里配置云端语音后，可以导出有声版。录制按实际时长进行，导出期间请保持页面打开。
 
 ## 实战项目
@@ -129,6 +151,7 @@
 ## 学习计划与我的画像
 
 - **学习计划**：设置**学习日**和**每周大约能学多久**，在**考试与截止日期**里添加重要日期。开窍会把所有在学课程的讲次和复习排进日程；按当前节奏赶不上截止日期时，会提醒你，并建议每周需要的学习时间。
+- **月历和打勾**：学习计划页是一张月历，点某一天就能看到那天的安排。学完一讲、做完一次复习会自动打勾；今天和之前的事项也可以手动勾上或取消（比如那一讲你在别处学过了），首页的**今天的安排**里同样可以勾。手动勾掉的讲次算作学完，后面的日子会重新排；今天已经学过的时间会从今天的安排里扣掉，不会越学越多。过去的日子保留当天的安排和完成情况，没完成的会自动顺延到之后。
 - **我的画像**：老师会记住你的背景、目标、擅长和薄弱的地方、喜欢的讲解方式，以及它自己的备忘，让每门课都更贴合你。每一项都可以直接修改（每行一条），也可以**清空画像**。
 
 ## 在 DSH 对话里使用
@@ -149,7 +172,7 @@
   - **语音来源**：系统语音（免费）/ 云端语音 / 不朗读。
   - **系统音色**：可以选**自动选择**，或指定一个音色。没有合适的中文音色时，可以在 macOS 的「系统设置 → 辅助功能 → 朗读内容」或 Windows 的「设置 → 时间和语言 → 语音」里添加。
   - **云端语音**：选择服务（OpenAI 兼容接口、火山引擎（豆包语音）、MiniMax、Azure 语音），填写接口地址、模型、音色等，再**保存密钥**。密钥保存在 DSH 的凭据库中，只在本机 Host 端使用。合成过的语音会缓存在本机，重播不再计费。
-  - **默认语速**和**试听**。
+  - **默认语速**和**试听**。试听、保存或清除密钥失败时，原因显示在对应按钮下方。
 - **白板外观**：跟随系统 / 白板 / 黑板。
 - **板书字体**：手写体 / 标准体。
 - **插件版本**：**检查更新**，有新版本时点**更新插件**，新版本刚发布也能直接装上。如果 DSH 的 pnpm 显式设置了发布冷却期，还没过冷却期的版本会显示可更新的时间，这不是失败。更新后请完全退出并重新打开 DSH。
@@ -179,7 +202,7 @@
 | 现象 | 处理 |
 | --- | --- |
 | 左侧栏没有「开窍」 | 安装后需要完全退出并重新打开 DSH，只刷新页面不够 |
-| 老师没有声音 | 到 **设置 → 语音讲解** 点**试听**；检查系统音量和音色，或改用云端语音 |
+| 老师没有声音 | 课堂控制栏上方会写明原因；也可以到 **设置 → 语音讲解** 点**试听**，检查系统音量和音色，或改用云端语音 |
 | 提示模型未登录或额度不足 | 在 DSH 设置里检查模型服务，或在开窍设置里换一个模型 |
 | 资料太长超出上下文 | 少选几份资料，或换一个上下文更大的模型 |
 | 生成结果不理想 | 点**重试**或**重新备课**；为「出课与讲课」换一个更强的模型 |

package/lib/agent.js

@@ -1,4 +1,4 @@
-import { I as readProfile, T as generateJson, at as normalizePractice, ft as newId, s as detectLanguage, t as getRuntime, ut as text, y as quizPrompt } from "./runtime-ywaTyu56.js";
+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 { defineTool } from "@deepseek-ai/dsh-tools";
 //#region src/agent.js
 const name = "aha-tutor-agent";