dsh-aha-tutor 0.0.0-stage → 1.1.0

package/AGENTS.md

@@ -0,0 +1,139 @@
+# Repository agent guide
+
+This file governs the entire `dsh-aha-tutor` repository.
+
+## Repository identity
+
+- Canonical repository: `https://github.com/BaronCyrus/dsh-aha-tutor`
+- 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` and `/api/aha-tutor/tts`
+- Data directory: `$DSH_HOME/aha-tutor/`; project folders: `~/AhaTutor/projects/`
+
+## Project boundaries
+
+- This is a permanent DSH profile plugin, not a temporary dynamic Cordis plugin. It has three entries:
+  - `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.
+- 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.
+- 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.
+- Copy, prompts, sample courses and artwork are original to this project. Do not copy text, UI wording, names, logos or images from other learning products, and do not describe the plugin as a clone of one.
+- Artwork (`icon.png`, `docs/assets/*.png`, the sidebar icon in `src/ui/icons.jsx`) is made with ChatGPT image generation in the maintainer's browser. Do not substitute stock art or other generators.
+
+## macOS and Windows
+
+The plugin runs inside DSH on both systems. Every change must keep working on both:
+
+- Build paths with `node:path` (`join`, `relative`, `sep`) and `os.homedir()`; never concatenate with `/` or assume `~`. Store files under ids, not user-supplied names, and pass learner-visible names through `safeFileName`.
+- Write files with `writeFileAtomic` (it retries `EPERM`/`EBUSY` renames that Windows antivirus and indexers cause).
+- Spawn processes without a shell. The pnpm launcher prefers DSH's own `process.execPath` + `pnpm.mjs`; the Windows fallback `pnpm.cmd` is the only place a shell is allowed.
+- Text uploads decode as UTF-8 with a GB18030 fallback; normalize `\r\n`.
+- UI fonts and voices come from per-OS stacks; never hard-code a single system font or voice name.
+- Tests that need links use junctions on Windows. CI runs the tests on Ubuntu, macOS and Windows.
+
+## 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`.
+- 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.
+- Preserve unrelated DSH plugins, profiles, sessions, settings and credentials.
+- Do not start, stop or restart DSH without explicit user permission. Self-tests run in a separate `DSH_HOME` with a `link:` install, never in the user's desktop profile.
+
+## Source and generated files
+
+- Edit `src/`; never hand-edit `lib/`. `lib/` is tracked (`index.js`, `agent.js`, their shared runtime chunk and `client.js`) and must be regenerated with `pnpm run build` after source changes; CI fails when it differs from a fresh build. `lib/client.js.map` is ignored.
+- `samples/*.aha-course.json` are generated by `node scripts/build-samples.mjs` through the plugin's own normalizers; edit the script, not the JSON.
+- User-facing strings live in `src/ui/i18n.js` (zh and en, same keys) and `locale/*.json` (package metadata). `tests/package-contract.test.mjs` checks both languages and that every endpoint the browser calls is routed.
+- `docs/releases/v<version>.md` holds each version's GitHub Release notes. It is tracked and not packaged.
+- `.artifacts/` and `node_modules/` are ignored and must never be committed.
+- Add or update tests under `tests/` for behavior changes.
+
+## Required validation
+
+```sh
+pnpm install
+pnpm run check
+```
+
+`pnpm run check` must run every test, rebuild all bundles and produce the versioned tarball in `.artifacts/`.
+
+A UI change is verified in a running DSH, not by a passing build alone: link the repository into a scratch profile (`DSH_HOME=<scratch> dsh plugin --profile web add link:<repo>`), start that DSH and check the change in its web client, in both light and dark themes and at a narrow width. Flows that call a model consume the user's quota; ask before running them against the user's own models.
+
+## Release authorization
+
+`npm publish`, Git tags, GitHub Releases and version publication are externally visible and partially irreversible. Execute them only when the user explicitly asks to publish or release and confirms the target version. A request to modify, test or commit alone is not release authorization.
+
+Never reuse, move, delete or overwrite a published npm version or Git tag. If a published version needs a correction, create a new patch version.
+
+## Release cadence
+
+- Tags publish straight to npm's `latest`, which the in-plugin update button and DSH's Plugins page install.
+- DSH's pnpm holds a version back for 24 hours after it is published. The in-plugin update reports it as pending until then; the Plugins page accepts an exact version (`dsh-aha-tutor@<version>`) earlier. Prefer at least 24 hours between releases so users are not chasing versions they cannot install yet.
+- A broken release reaches `latest` at once: deprecate it on npm and publish a fixed patch version.
+
+## First release
+
+npm configures a trusted publisher only for a package that already exists, so 1.0.0 is published by the maintainer, not by CI:
+
+1. Finish the release checklist up to step 4 for 1.0.0.
+2. The maintainer runs `npm publish .artifacts/dsh-aha-tutor-1.0.0.tgz --access public` on their own machine, logged in to npm with 2FA. Never ask for a token, password or one-time code in chat.
+3. The maintainer adds the trusted publisher on npmjs.com: repository `BaronCyrus/dsh-aha-tutor`, workflow filename `publish.yml`, environment empty.
+4. Push the `v1.0.0` tag. The workflow finds 1.0.0 already on npm, skips publishing and creates the GitHub Release with the tarball npm serves.
+
+Every later version is published by its tag with GitHub OIDC.
+
+## Release checklist
+
+1. Synchronize and confirm a clean base:
+
+   ```sh
+   git fetch origin --tags --prune
+   git status --short --branch
+   git log --oneline HEAD..origin/main
+   ```
+
+   Fast-forward clean remote changes before editing. Never discard remote changes.
+
+2. Confirm the requested SemVer is unused:
+
+   ```sh
+   npm view dsh-aha-tutor@<version> version --json
+   git ls-remote --exit-code --tags origin refs/tags/v<version>
+   ```
+
+   For an unused npm version, `npm view` normally returns `E404`. An existing npm version or Git tag requires choosing a new version.
+
+3. Update all release metadata together: `package.json` version, `CHANGELOG.md`, `compatibility.json` when the tested DSH version changed, any version pinned in `README.md` / `README.en.md`, and the GitHub Release notes in `docs/releases/v<version>.md`. The notes are in Chinese:
+   - The first line is `# v<version>：<短标题>`, which becomes the release title.
+   - Then a one-sentence summary and bullets with bold labels.
+   - Then a `验证：…` paragraph.
+   - They close with `在 DSH 插件管理中更新至 **<version>**，然后重新打开 DSH 加载新版。`
+
+   `node scripts/release-notes.mjs <version>` checks the file, and `pnpm run check` fails while the current `package.json` version has no valid notes or changelog entry.
+
+4. Validate and inspect the exact release artifact:
+
+   ```sh
+   pnpm install --frozen-lockfile
+   pnpm run check
+   npm publish .artifacts/dsh-aha-tutor-<version>.tgz --access public --dry-run --json
+   ```
+
+5. Commit the release and push `main` without force. [`.github/workflows/publish.yml`](.github/workflows/publish.yml) must already be on the commit that will be tagged. Do not push the tag in this step.
+
+6. Confirm the package has its GitHub Actions trusted publisher (repository `BaronCyrus/dsh-aha-tutor`, workflow filename `publish.yml`, environment empty). `workflow_dispatch` on the Publish workflow prints the OIDC identity npm will match and does not publish.
+
+7. Create the annotated tag and push it. That push publishes to npm's `latest` with GitHub OIDC; the `release` job then creates the GitHub Release from `docs/releases/v<version>.md`, attaches the tarball npm published and marks it Latest. `release` is the only job with `contents: write`, and it runs no dependency code. Do not run `npm publish` locally after the first release, and do not set `NODE_AUTH_TOKEN` or a setup-node `registry-url` in the workflow; npm treats either as token auth and skips OIDC.
+
+   ```sh
+   git tag -a v<version> -m "dsh-aha-tutor v<version>"
+   git push origin v<version>
+   ```
+
+8. Confirm that both jobs of the tag's run succeeded, that npm's `latest` serves the version (`npm view dsh-aha-tutor dist-tags --prefer-online`; without `--prefer-online` a cached 404 can linger), and that `gh release view v<version>` shows the notes and the `dsh-aha-tutor-<version>.tgz` asset. On an OIDC `package not found` error, fix the trusted publisher and re-run the same workflow; a re-run finds the version already published and only finishes the release. If the tagged tree itself must change, publish a new patch version.

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+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.1.0 - 2026-10-19
+
+### Added
+
+- **About the author** page at the bottom of the navigation: author, a short note, links to the GitHub repository and issues, and the WeChat and Alipay tip codes (bundled as data URLs, so the page works offline).
+
+### Changed
+
+- The English label of 「我的画像」 is now "My profile", so it no longer reads like the new About page.
+
+## 1.0.0 - 2026-10-18
+
+First release.
+
+### Added
+
+- **Craft a course**: start from a sentence or uploaded materials; an intake of multiple-choice questions about background, goal, depth and time; an editable unit → chapter → lesson blueprint that can also be revised by request; confirming generates practice sets and hands-on projects for the whole course.
+- **Whiteboard classroom**: lessons are step scripts (headings, text, KaTeX math, lists, sanitized SVG diagrams, data charts, tables, code, notes, marks and sandboxed animations) played with handwriting reveal synchronized to narration and captions; play and pause (Space), step back and forward (← →), speed, resume from the saved position, a pencil that follows the handwriting and a Markdown export of the board.
+- **Adaptive checks**: in-lesson checks with a confidence prompt; a Bayesian knowledge-tracing mastery model that weighs confidence, hints and hesitation; remedial lessons inserted after a lesson for concepts below threshold; challenge suggestions for strong learners.
+- **Ask and re-explain**: questions mid-lesson are answered on the board right after the current step, then the lesson resumes; re-explain a step by analogy, drawing, example, simpler or deeper.
+- **Practice and review**: per-lesson practice with objective auto-grading and model-graded open answers against key points; flashcards and concepts on an SM-2 spaced-repetition schedule; a study planner that respects weekly time, study days and deadlines and flags deadline risk.
+- **Materials**: PDF (pdf.js, with CJK radical repair), Word (.docx), PowerPoint (.pptx), Markdown and text (UTF-8, with a GB18030 fallback), public web pages (Readability, with private-address refusal) and images for vision models; BM25 retrieval with CJK bigrams; page citations; reading digests.
+- **Studio**: explain a concept, solve with me, show me visually, topic cheat sheets (columns, font size, highlighting, print), notes, flashcard decks, quizzes and two-minute explainer shorts from a topic or a link.
+- **Video export**: any lesson or short renders to a 1280×720 WebM video in the board's theme, with handwriting, captions (no line starts with closing punctuation), a watermark and, with a cloud voice, narration audio. Animations carry an SVG poster frame that stands in for them in videos.
+- **Projects**: each project gets a folder with its brief and starter files under `~/AhaTutor/projects/` that opens as a DSH workspace session; existing files are never overwritten. Submissions (notes plus the folder's text files) get a rubric review.
+- **Learner profile**: background, goals, preferences and weak spots remembered across courses, with view, edit and clear.
+- **Conversation preset** "开窍 · AI 私人老师" with tools `aha_whiteboard`, `aha_quiz`, `aha_course`, `aha_cheatsheet` and `aha_learner`, rendered as cards in the chat; boards open in the right sidebar.
+- **Voices**: browser speech by default with per-language voice choice; optional cloud TTS from OpenAI-compatible APIs, Volcengine (Doubao), MiniMax and Azure Speech, with keys in DSH's credential store and a local audio cache.
+- **Models**: DSH's default model, with separate overrides for "course design & teaching" and "grading & questions"; vision detection for image materials.
+- **Course packs**: export and import `.aha-course.json` packs; two bundled sample courses (harmonic motion, Bayesian thinking).
+- **In-plugin update**: checks the registry and installs an exact version with DSH's bundled pnpm in the owning profile; versions inside pnpm's release-age window are reported as pending; `link:` installs are left alone.
+- Chinese and English interface; light and dark themes; macOS and Windows support.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BaronCyrus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,115 @@
+<div align="center">
+
+<img src="docs/assets/aha-tutor-mascot.png" width="200" height="200" alt="Aha's mascot Qiao: a friendly light bulb teacher with glasses and chalk">
+
+# Aha · AI tutor (开窍)
+
+[简体中文](README.md) · **English**
+
+**A private tutor for DeepSeek Harness: say what you want to understand, and it gets to know you, builds a course around you, and teaches it on a handwriting chalkboard while it speaks.**
+
+[![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)
+[![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)
+
+</div>
+
+<p align="center"><img src="docs/assets/aha-tutor-hero.png" alt="A laptop showing a chalkboard with formulas and a wave, with a glowing light bulb tutor beside it" width="860"></p>
+
+## What it does
+
+| 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 generates practice sets and hands-on projects |
+| **Handwriting chalkboard lessons** | Narration (voice + captions) while the board fills up with handwritten points, formulas, diagrams, charts and, when it helps, a small animation; 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 |
+| **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 |
+| **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 |
+| **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 |
+| **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.
+
+## Install
+
+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.1.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).
+
+Offline: download `dsh-aha-tutor-<version>.tgz` from [GitHub Releases](https://github.com/BaronCyrus/dsh-aha-tutor/releases/latest) and enter its absolute path instead. For your own profiles, `dsh plugin --profile <name> add dsh-aha-tutor@<version>` works; the desktop profile is managed by the app's Plugins page only.
+
+## Quick start
+
+1. Type what you want to learn on the home page (or attach a handout) and press **Start**.
+2. Answer a few questions and choose a pace, then **Design my course**. Edit the blueprint or ask for changes.
+3. **Confirm and build the course**, then **Continue learning**.
+
+For a single question, use "Explain a concept", "Solve with me" or "Show me visually" on the home page; no course needed.
+
+## Voices
+
+| Option | Notes |
+| --- | --- |
+| **System voice (default, free)** | macOS / Windows voices, selectable in settings; you are told when no voice matches the course language |
+| **Cloud voice (optional)** | OpenAI-compatible APIs (including SiliconFlow and others), Volcengine (Doubao), MiniMax and Azure Speech. Keys live in DSH's credential store, are used host-side only and never reach the browser; synthesized audio is cached locally so replays cost nothing |
+
+Only cloud voices can be recorded into exported videos; with a system voice the video has captions and no sound. Board animations appear in videos as a still frame.
+
+## Models
+
+Aha uses your DSH default model. In **Aha → Settings** you can pick separate models for "course design & teaching" and "grading & questions". The plugin never switches to another paid model on its own and never generates in bulk in the background: the course structure is made when you confirm it, and each lesson's board when you open it (plus the next one). Follow the terms of subscription-based models you use.
+
+## Privacy and data
+
+- Courses, progress, materials, profile and plan stay on this computer under `$DSH_HOME/aha-tutor/` (default `~/.dsh/aha-tutor/`, on Windows `C:\Users\<you>\.dsh\aha-tutor\`).
+- Project folders live under `~/AhaTutor/projects/`; files you changed are never overwritten.
+- Models receive only what the current task needs: your request, the course outline, relevant passages from your materials and a short learner profile.
+- Web import fetches public addresses only, never localhost or private networks.
+- Model-drawn diagrams pass an allow-list sanitizer; animations run in a sandbox without network access.
+
+See [SECURITY.md](SECURITY.md).
+
+## FAQ
+
+**No sound?** Open **Aha → Settings → Narration** and press **Test**. Install a system voice for your language, or use a cloud voice.
+
+**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.
+
+**Using the tutor in a chat?** Choose the "开窍 · AI 私人老师" preset when starting a session.
+
+## Development
+
+```bash
+pnpm install --frozen-lockfile
+pnpm run check
+```
+
+Runs every test, builds the host and browser bundles and packs a tarball into `.artifacts/`. For local iteration, add the repository's absolute path in the DSH Plugins page (installs as `link:`); host changes need a DSH restart. See [AGENTS.md](AGENTS.md).
+
+## License
+
+[MIT](LICENSE) © BaronCyrus. Third-party licenses: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+Aha Tutor (开窍) is an independent open-source project, not affiliated with DeepSeek or any other learning product.
+
+## Support the author
+
+Aha Tutor is free and open source, and tips are entirely optional. If it helped something finally click for you, a tip keeps Qiao growing.
+
+<table align="center">
+  <tr>
+    <td align="center"><img src="docs/assets/sponsor-wechat.png" width="200" alt="WeChat tip code"><br><b>WeChat</b></td>
+    <td align="center"><img src="docs/assets/sponsor-alipay.png" width="200" alt="Alipay payment code"><br><b>Alipay</b></td>
+  </tr>
+</table>

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="docs/assets/aha-tutor-mascot.png" width="200" height="200" alt="开窍的吉祥物小窍：戴眼镜、拿粉笔的灯泡小老师">
+
+# 开窍 · AI 私人老师
+
+**简体中文** · [English](README.en.md)
+
+**给 DeepSeek Harness 装一位私人老师：说出你想弄懂的东西，它先了解你，再为你做一门课，在手写黑板上边写边讲。**
+
+[![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)
+[![MIT](https://img.shields.io/badge/license-MIT-111111.svg)](LICENSE)
+
+[能做什么](#能做什么) · [安装](#安装) · [三分钟上手](#三分钟上手) · [界面预览](#界面预览) · [使用指南](docs/guide.zh-CN.md) · [隐私](#隐私与数据) · [常见问题](#常见问题) · [支持作者](#支持作者)
+
+</div>
+
+<p align="center"><img src="docs/assets/aha-tutor-hero.png" alt="开窍：笔记本电脑屏幕上是一块写着公式和波形的黑板，灯泡小老师在一旁发光" width="860"></p>
+
+## 能做什么
+
+| 能力 | 体验 |
+| --- | --- |
+| **为你定制一门课** | 说一句想学什么，或者丢进一本教材。老师先用几道选择题了解你的基础、目标和时间，再给出「单元 → 章 → 讲」的课程蓝图。你可以直接改，也可以用一句话让它改，确认后生成练习和实战项目 |
+| **手写黑板课堂** | 老师一边讲（语音 + 字幕），一边在黑板上逐字写下要点、公式、示意图和图表，需要时还会放一段小动画；随时暂停、回放、变速 |
+| **随堂小测与自适应** | 讲到关键处会停下来考你一题，并问你「有多确定」。猜对、犹豫、自信地答错，会被区别对待；学完一讲后，薄弱的知识点会自动加一节巩固课 |
+| **举手提问、换个讲法** | 没听懂就举手，老师在黑板上专门回答你，讲完回到原来的进度；也可以让它用打比方、画图、举例、讲简单点或讲深一点的方式重讲这一步 |
+| **练习、闪卡与复习** | 每讲都有练习，简答题由 AI 批改；闪卡和知识点按间隔重复安排复习，学习计划会自动给复习留出时间 |
+| **资料变课程** | 支持 PDF、Word、PPT、Markdown、网页链接和图片（图片需要支持识图的模型）。讲课和速查表会引用原文页码；长文档可以一键「消化」成结构、论点和术语表 |
+| **速查表、笔记、测验** | 按主题整理的可打印速查表（列数、字号、高亮可调），以及笔记、闪卡组和测验 |
+| **讲解短片 + 导出视频** | 输入一个主题或网址，得到一段约两分钟的白板讲解；任何一讲都能导出成带板书动画、字幕和水印的视频，适合分享 |
+| **实战项目** | 代码类项目一键生成项目文件夹和起始文件，并在 DSH 里打开一个会话，让编程 Agent 陪你做；做完回来提交，老师按评分标准逐项点评 |
+| **学习计划与画像** | 按每周时间、学习日和截止日期自动排课并提示进度风险；老师会记住你的背景和薄弱点，你可以随时查看、修改或清空 |
+| **对话里也能用** | 新增「开窍 · AI 私人老师」会话预设：在 DSH 对话中，老师可以上白板讲解、出互动小测、帮你建课、做速查表 |
+
+不想先花 token？首页自带两门示例课（「简谐运动」「贝叶斯思维」），打开就能体验完整的黑板课堂。
+
+## 安装
+
+先准备好 **DeepSeek Harness** 桌面版（0.2.1 及以上的 0.2.x 版本），并在 DSH 里配置好至少一个可用的模型。尚未安装 DSH，可查看 [DSH 官方说明](https://github.com/deepseek-ai/deepseek-harness#run)。
+
+1. 打开桌面应用的**插件**页，点击**添加插件**，在**包名或地址**中填入：
+
+   ```text
+   dsh-aha-tutor
+   ```
+
+   安装源选择**官方源**，点击**安装**。新版本刚发布的 24 小时内，DSH 的 pnpm 会因为发布冷却期暂缓安装，这时请填入精确版本，例如 `dsh-aha-tutor@1.1.0`。
+
+2. **完全退出并重新打开** DSH 桌面应用。只刷新页面不会加载 Host 端的新插件。
+
+3. 左侧栏出现 **「开窍 · AI 私人老师」**，点开即可使用。
+
+<details>
+<summary>离线安装 / 自建 profile</summary>
+
+- 从 [GitHub Releases](https://github.com/BaronCyrus/dsh-aha-tutor/releases/latest) 下载 `dsh-aha-tutor-<版本>.tgz`，在**包名或地址**中填入它的绝对路径。
+- 自建 profile 可以用 `dsh plugin --profile <name> add dsh-aha-tutor@<版本>`。不要对 `desktop` profile 使用这条命令，桌面版请走插件页。
+
+</details>
+
+## 三分钟上手
+
+1. **说出目标**：在首页输入「三周内搞懂线性代数里的特征值」，或附上一份讲义，点**开始**。
+2. **回答几个问题**：选一选你的基础、目的和节奏，点**生成课程蓝图**。不满意就直接改，或者写一句「多加一些编程练习」。
+3. **确认开课**：点**确认，生成整门课**，然后在课程页点**继续学习**，老师就会在黑板上开讲。
+
+想快速问一个概念、解一道题、看一张图？用首页的「讲个概念」「陪我解题」「画出来看看」，不用建课。
+
+## 界面预览
+
+| 首页 | 黑板课堂 |
+| --- | --- |
+| <img src="docs/assets/screenshot-home.png" alt="开窍首页：输入想学的内容并选择模式" width="420"> | <img src="docs/assets/screenshot-classroom.png" alt="黑板课堂：手写板书、示意图与字幕" width="420"> |
+| **随堂小测** | **导出的讲解视频** |
+| <img src="docs/assets/screenshot-check.png" alt="讲课中途弹出的小测，带信心选择" width="420"> | <img src="docs/assets/screenshot-video.png" alt="导出视频中的一帧：板书、字幕和水印" width="420"> |
+
+## 语音
+
+| 方式 | 说明 |
+| --- | --- |
+| **系统语音（默认，免费）** | 使用 macOS / Windows 自带的音色，可在设置中挑选；系统没有中文音色时会给出提示 |
+| **云端语音（可选）** | 支持 OpenAI 兼容接口（含硅基流动等）、火山引擎（豆包语音）、MiniMax、Azure 语音。密钥保存在 DSH 的凭据库中，只在 Host 端使用，不会传给浏览器；合成过的语音会缓存在本机，重播不再计费 |
+
+导出视频时，只有云端语音能被录进视频；用系统语音导出的视频带字幕、没有声音。黑板上的小动画在视频里以一帧静态画面出现。
+
+## 模型
+
+默认使用你在 DSH 里设置的默认模型。在 **开窍 → 设置** 里，可以分别为「出课与讲课」和「批改与问答」指定模型，例如出课用更强的模型、批改用更快的模型。
+
+插件不会自动切换到其它付费模型，也不会在后台批量消耗额度：课程结构在你确认时生成，每一讲的板书在你打开时才生成（同时预备下一讲）。使用订阅类模型时，请遵守对应服务的使用条款。
+
+## 隐私与数据
+
+- 课程、进度、资料、画像和学习计划都保存在本机：`$DSH_HOME/aha-tutor/`（默认 `~/.dsh/aha-tutor/`，Windows 为 `C:\Users\<用户名>\.dsh\aha-tutor\`）。
+- 实战项目的文件夹在 `~/AhaTutor/projects/` 下，插件不会覆盖你已经改过的文件。
+- 发给模型的内容只有完成当前任务所需的部分：你的问题、课程结构、相关的资料片段，以及简短的学习画像。
+- 网页导入只抓取公开地址，不访问本机或局域网地址。
+- 模型生成的示意图会经过白名单过滤；动画运行在无网络权限的沙箱里。
+
+详见 [SECURITY.md](SECURITY.md)。
+
+## 更新与卸载
+
+**开窍 → 设置 → 插件版本**可以检查更新，并用 DSH 自带的 pnpm 安装精确的新版本。新版本发布不满 24 小时时会显示「待更新」和可以更新的时间，这是 DSH 的供应链安全策略，不是失败。更新后需要完全退出并重新打开 DSH。
+
+在桌面应用的**插件**页可以停用或卸载插件。卸载不会删除 `~/.dsh/aha-tutor/` 里的学习数据；不再需要时可以手动删除这个文件夹。
+
+## 常见问题
+
+**老师没有声音？** 打开 **开窍 → 设置 → 语音讲解**，点**试听**。没有中文音色时，可在系统设置里安装中文语音，或改用云端语音。
+
+**生成失败或结果不理想？** 点**重试**，或在设置里为「出课与讲课」换一个更强的模型。
+
+**PDF 里读不出文字？** 扫描版 PDF 没有文字层，可以截图后以图片上传（需要支持识图的模型）。
+
+**会话里怎么用老师？** 新建会话时，在预设里选择 **「开窍 · AI 私人老师」**。
+
+## 开发
+
+```bash
+pnpm install --frozen-lockfile
+pnpm run check
+```
+
+`pnpm run check` 会依次运行全部测试、构建 Host 与浏览器端的包，并在 `.artifacts/` 下打出 tgz。本地开发时，可在 DSH 插件页填入仓库的绝对路径，以 `link:` 方式安装。改动 Host 代码后，需要重启 DSH 才能生效。仓库结构与约定见 [AGENTS.md](AGENTS.md)。
+
+## 许可
+
+[MIT](LICENSE) © BaronCyrus。第三方组件的许可见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
+
+「开窍 / Aha Tutor」是独立的开源项目，与 DeepSeek 或其他任何学习产品均无隶属关系。
+
+## 支持作者
+
+开窍免费开源，赞赏全凭心意。如果它帮你弄懂了某个卡了很久的知识点，欢迎扫码支持，让小窍继续长大。
+
+<table align="center">
+  <tr>
+    <td align="center"><img src="docs/assets/sponsor-wechat.png" width="200" alt="微信赞赏码"><br><b>微信赞赏</b></td>
+    <td align="center"><img src="docs/assets/sponsor-alipay.png" width="200" alt="支付宝收款码"><br><b>支付宝</b></td>
+  </tr>
+</table>

package/SECURITY.md

@@ -0,0 +1,34 @@
+# Security
+
+## Reporting
+
+Please report vulnerabilities privately through [GitHub security advisories](https://github.com/BaronCyrus/dsh-aha-tutor/security/advisories/new) rather than public issues. Never paste API keys, tokens or personal study data into an issue.
+
+## What the plugin trusts, and what it does not
+
+Model output, uploaded files and fetched web pages are all treated as untrusted input.
+
+| Surface | Protection |
+| --- | --- |
+| Board text and Markdown | Rendered by DSH's Markdown renderer (raw HTML disabled) or as plain text; KaTeX runs with `trust: false` |
+| Model-drawn SVG | Parsed and rebuilt through an allow-list of elements and attributes: no scripts, event handlers, `foreignObject`, external `href`, `url()` outside the document, or CSS that can fetch |
+| Animations | Run in `<iframe sandbox="allow-scripts">` without same-origin access and with a CSP of `default-src 'none'`, so they cannot reach DSH, cookies or the network |
+| Web import | `http(s)` only; localhost, private, link-local and metadata addresses are refused, redirects are followed by hand and re-checked; 20 s timeout and size limits |
+| Uploads | 60 MB per file, 10 MB per image; parsed host-side with pdf.js (no eval), mammoth and JSZip; text capped at 2 M characters per material |
+| Project folders | Starter-file paths are validated (relative, no `..`, no Windows reserved names); existing files are never overwritten; reviews read only text files, skip symlinks and cap the total size |
+| Course packs | Imports are fully re-normalized, get fresh ids and are size-limited; nothing in a pack executes on import |
+
+## Secrets
+
+- Cloud TTS keys are stored with DSH's credential store (record-style, no fallback to environment variables) and used host-side only. Settings responses report only whether a key exists.
+- TTS requests use `redirect: 'error'`, a 45 s timeout and a response size limit; plain `http` is accepted only for a TTS server on `localhost`.
+- The plugin never logs request bodies, keys or package-manager output to the browser.
+
+## Browser ↔ host
+
+- The RPC channel `/aha-tutor` and the routes `/api/aha-tutor/upload` and `/api/aha-tutor/tts` are served by DSH's connection layer, which requires an authenticated browser session (owner). The handler additionally rejects non-owner peers.
+- Every payload is validated (id formats, enums, sizes) before reaching a service; errors returned to the browser carry only messages written for users.
+
+## Plugin updates
+
+The in-app update installs an exact registry version with DSH's own pnpm inside the owning profile and never overrides pnpm's `minimumReleaseAge` (no `--config.minimumReleaseAge`, no edits to `minimumReleaseAgeExclude`, no `--force`). A version held back by the cooldown is reported as pending. Local `link:` installs are never updated in place.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,16 @@
+# Third-party notices
+
+The plugin depends on the following open-source software. Runtime dependencies are installed by DSH's package manager next to the plugin; KaTeX is bundled into `lib/client.js`.
+
+| Package | Use | License |
+| --- | --- | --- |
+| [pdfjs-dist](https://github.com/mozilla/pdf.js) | PDF text extraction (host) | Apache-2.0 |
+| [mammoth](https://github.com/mwilliamson/mammoth.js) | Word (.docx) text extraction (host) | BSD-2-Clause |
+| [JSZip](https://github.com/Stuk/jszip) | PowerPoint (.pptx) reading (host) | MIT (dual-licensed MIT or GPL-3.0-or-later; used under MIT) |
+| [@mozilla/readability](https://github.com/mozilla/readability) | Main-text extraction from web pages (host) | Apache-2.0 |
+| [linkedom](https://github.com/WebReflection/linkedom) | DOM for Readability on the host | ISC |
+| [KaTeX](https://github.com/KaTeX/KaTeX) | Math rendering on the board (bundled) | MIT |
+
+DeepSeek Harness packages (`@deepseek-ai/*`) and React are provided by the DSH runtime and are not redistributed.
+
+Artwork in `docs/assets/` and `icon.png` was created for this project with ChatGPT image generation. Sample courses in `samples/` were written for this project.

package/compatibility.json

@@ -0,0 +1,10 @@
+{
+  "latestTested": "0.2.1-rc.2",
+  "acceptedRuntimeRange": ">=0.2.1-rc.1 <0.3.0-0",
+  "supported": [
+    "0.2.1-rc.2"
+  ],
+  "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."
+  }
+}

package/cordis.patch.yml

@@ -0,0 +1,67 @@
+# 开窍 · AI 私人老师 (dsh-aha-tutor)
+#
+# 1. The plugin's host row: tutoring services, the browser channel and the
+#    upload / speech routes.
+# 2. A conversation preset "AI 私人老师": a patient tutor persona with
+#    read-only file tools, web search and the plugin's teaching tools
+#    (whiteboard, quiz, course, cheat sheet, learner profile). Compaction
+#    stays so long tutoring sessions keep working. No shell, no file writes.
+- insert:
+    - id: aha-tutor
+      name: 'dsh-aha-tutor'
+    - id: preset-aha-tutor
+      name: '@deepseek-ai/dsh-agent-preset'
+      config:
+        id: aha-tutor
+        name: 开窍 · AI 私人老师
+        description: 一对一讲解：白板板书与语音、随堂小测、定制课程与速查表。只读文件，可联网搜索。
+        order: 15
+        plugins:
+          - id: persona
+            name: '@deepseek-ai/dsh-persona'
+            config:
+              prefix: |-
+                You are Aha (开窍), a patient and brilliant private tutor powered by {{model}}.
+                Your goal is real understanding, not answers handed over.
+                - First find out what the learner already knows and why they want to learn it; ask briefly when unsure.
+                - Teach one idea at a time: intuition first, then precision, then a worked example.
+                - Check understanding often with a quick question, and adapt to the reply.
+                - Reply in the learner's language. Keep chat answers short when the whiteboard does the teaching.
+                - For homework, guide with hints and questions; give full solutions only after the learner has tried.
+          - id: time-context
+            name: '@deepseek-ai/dsh-time-context'
+          - id: tool-fs
+            name: '@deepseek-ai/dsh-tool-fs'
+            config:
+              read: true
+              readImage: true
+              write: false
+              edit: false
+          - id: tool-fs-search
+            name: '@deepseek-ai/dsh-tool-fs-search'
+          - id: tool-web
+            name: '@deepseek-ai/dsh-tool-web'
+            config:
+              search: true
+              fetch: true
+          - id: tool-ask-user
+            name: '@deepseek-ai/dsh-tool-ask-user'
+          - id: compaction
+            name: cordis:group
+            group: true
+            isolate:
+              compaction: true
+              toolResultPruner: true
+            config:
+              - id: compaction-basic
+                name: '@deepseek-ai/dsh-compaction-basic'
+              - id: command-compact
+                name: '@deepseek-ai/dsh-command-compact'
+              - id: tool-result-pruner
+                name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+                config:
+                  thresholdChars: 8192
+                  headChars: 4096
+                  tailChars: 1024
+          - id: aha-tutor-tools
+            name: 'dsh-aha-tutor/agent'