# 开窍 · AI 私人老师 使用指南

这份指南按界面逐一说明开窍的用法。安装方法见 [README](../README.md#安装)。

- [开始之前](#开始之前)
- [首页：从一句话开始](#首页从一句话开始)
- [定制一门课](#定制一门课)
- [黑板课堂](#黑板课堂)
- [课程页](#课程页)
- [练习、闪卡与复习](#练习闪卡与复习)
- [资料库](#资料库)
- [学习工具、即时答疑与讲解短片](#学习工具即时答疑与讲解短片)
- [实战项目](#实战项目)
- [学习计划与我的画像](#学习计划与我的画像)
- [在 DSH 对话里使用](#在-dsh-对话里使用)
- [设置](#设置)
- [关于作者](#关于作者)
- [课程包：分享与备份](#课程包分享与备份)
- [数据保存在哪里](#数据保存在哪里)
- [遇到问题](#遇到问题)

## 开始之前

1. **模型**：开窍使用你在 DSH 里设置的默认模型。讲课质量主要取决于模型，建议「出课与讲课」用你手头最强的模型。要读图片资料，模型需要支持识图。
2. **语音**：默认用系统自带的音色朗读，不花钱。第一次使用时，到 **设置 → 语音讲解** 点**试听**，确认能听到声音。
3. **先看示例课**：首页下方的「示例课程」里有「简谐运动」「贝叶斯思维」两门现成的课，点**加入我的课程**就能体验完整的黑板课堂，不消耗模型额度。

## 首页：从一句话开始

在输入框里写下你想学的东西，然后选一种模式：

| 模式 | 适合 |
| --- | --- |
| **定制一门课** | 想系统地学一个主题，或者把一本教材、一份讲义变成课程 |
| **讲个概念** | 只想弄懂一个概念，不用建课 |
| **陪我解题** | 贴一道题，老师在白板上一步步带你解 |
| **画出来看看** | 用示意图、图表或动画把抽象的东西画出来 |
| **消化长文档** | 把一篇长文或论文整理成结构、核心观点、论点和术语表；长文档会分段读完全文再汇总 |
| **两分钟短片** | 生成一段约两分钟、适合分享的白板讲解 |

点**添加资料**可以附上文件，它们会进入资料库，并作为这次请求的依据。首页还会显示**继续学习**和**今天的安排**。

## 定制一门课

1. **先认识一下你**：老师会根据你的主题出几道选择题，问你的基础、目的、想学多深等。每题都可以选「其他」自己写，拿不准的可以跳过。下面先选**课程规模**：**让老师决定**（按目标定，一个小问题可能只要一两讲）、**精简**（3–8 讲）、**标准**（10–20 讲）或**完整**（25–45 讲）。选了规模，老师就按这个讲数出课。再选**学习节奏**（冲刺约 6 周 / 稳步约 3 个月 / 不设期限）、**每周大约能学多久**，以及可选的**截止日期**；节奏只影响每周怎么排。想省事可以点**跳过提问，直接出课**。
2. **课程蓝图**：点**生成课程蓝图**后，老师边写边展示：上面是进行到哪一步，下面是一个个单元逐渐长出来的大纲。写完后就是「单元 → 章 → 讲」的完整结构，每讲标有预计时长，末尾还有实战项目。你可以：
   - 直接改标题，**上移 / 下移**调整顺序，**删除**不要的部分，或者**加一讲 / 加一章 / 加一个单元**。删除单元、章或已经开始学的讲之前会先确认；
   - 点某一讲旁边的 **✦**，让老师把它**拆成两讲**或**讲深一些**。改好的内容先出现在编辑器里，保存后才生效；
   - 在**用一句话修改**里写下要求，例如「多加一些编程实战」「第二单元讲浅一点」，点**修改**。老师会先给出**修改建议**，列出新增、删除、改名和调整的讲，点**应用修改**才生效，不满意就**放弃**。
3. **确认开课**：点**确认，生成整门课**。老师会完善实战项目，并为第一单元准备练习；后面各讲的练习在你第一次打开这一讲（或它的练习）时准备。完成后进入课程页，点**继续学习**开始第一讲。

开课以后也能改：在课程页右上角的 **⋯** 里选**编辑课程大纲**，可以加讲、加单元、调整顺序，或点**让老师续写一个单元**。保留下来的讲，学习进度不变。

每一讲的板书在你打开它时才生成，同时会预备下一讲，所以不会一次性消耗大量额度。

生成蓝图、确认开课这类要等一会儿的步骤，可以先去别的页面，生成会在后台继续，回来就能看到结果；想停下来就点**取消**。

## 黑板课堂

老师一边讲（语音 + 字幕），一边在黑板上逐字写出要点，画出示意图、图表，需要时还会放一段小动画。一页写满后自动翻到下一页。板书用手写体，讲到哪一句才写哪一句对应的内容，正在讲的那一行会用荧光笔划出来；字幕跟着朗读一句一句出现，公式按数学排版显示。想换回普通字体，到**设置 → 板书字体**选**标准体**。

白板右侧是**课堂侧栏**：上面是这一讲的**课堂要点**，讲到哪一条就亮到哪一条，讲完打勾；下面是**讲解记录**，老师说过的话和你的提问都在里面，点一条就回到那里；最下面是提问框。侧栏可以收起，窄屏时会放到白板下方。

**播放控制**

| 操作 | 方法 |
| --- | --- |
| 播放 / 暂停 | 点**播放 / 暂停**，或按空格键 |
| 上一步 / 下一步 | 点按钮，或按 ← / → |
| 语速 | 语速下拉框（0.75× – 2×） |
| 声音、字幕 | **声音开 / 静音**、**字幕** |

退出后再回来，课堂会从上次的位置继续。

**举手提问**：没听懂就点**举手提问**（或直接在侧栏的提问框里写）。老师会把回答插在当前这一步之后，边写边讲给你听，讲完接着原来的内容继续。问过的问题和「换个讲法」都会留在这一讲里，下次打开还在原来的位置，也会出现在侧栏的讲解记录里。

**换个讲法**：对当前这一步不满意，点**换个讲法**，选择**打个比方 / 画图讲 / 举个例子 / 讲简单点 / 讲深一点**，新的讲解同样会插在这一步之后。

**随堂小测**：讲到关键处，老师会停下来出一道题，并问你**有多确定**（很确定 / 有点犹豫 / 猜的）。回答会影响掌握度：猜对不算完全掌握，自信地答错说明有误解，需要重点巩固。卡住时可以点**提示**，也可以**跳过**。

**写出过程**：有计算或推导的一讲，会有一道题请你把过程写出来：一步一行，公式写在 $…$ 里，下面会实时预览。老师会逐行看，找出第一处出错的地方；没写对时点**看老师订正**，老师会在黑板上框出那一步，写出正确的做法，再接着讲。订正会留在这一讲里，也会出现在讲解记录中。

**讲完之后**：给自己的掌握程度打个分（1–5）。如果某些知识点掌握得不好，老师会自动加一节**巩固课**；如果掌握得很好，后面会讲得更深一些。

课堂顶部还有：**练习**（去做这一讲的练习）、**导出板书**（Markdown 文件）、**导出视频**（见[讲解短片](#学习工具即时答疑与讲解短片)）和**重新备课**（重新生成这一讲的板书）。

## 课程页

| 标签 | 内容 |
| --- | --- |
| **大纲** | 全部单元、章和讲，带学习状态；自动加入的巩固课标有「巩固」。每个单元都有**单元速查表**和**单元测验** |
| **练习与测验** | 每讲的练习、单元测验和**开始复习**（只复习这门课） |
| **速查表** | 单元速查表，按主题整理公式、定义和要点 |
| **闪卡** | 这门课的闪卡，按复习计划出现 |
| **项目** | 实战项目，见[实战项目](#实战项目) |
| **进度** | 每个知识点的掌握程度（未开始、薄弱、学习中、熟练、掌握五级），以及老师发现的误解（⚠） |

标题旁边是学习进度和剩余时间；下面的**下一步**给出一个建议：有到期的复习就先复习，其次练一练最薄弱的知识点，再往下是下一讲。右上角的 **⋯** 菜单可以**编辑课程大纲**、**导出课程包**、**归档**和**删除课程**。大纲里每一讲的掌握度条在学过之前是空的。所有课程都在左侧的**我的课程**里，可以按学习中、已学完、已归档筛选和搜索。

## 练习、闪卡与复习

- **练习**：单选、多选、填空、数值计算和排序题会立即判分；简答题由老师按要点批改，告诉你答到了哪些、漏了哪些。做完可以**看解析**。需要图的题会附一张示意图。
  - 可以用键盘作答：1–4 选择，Enter 提交或继续，H 看提示；题号旁边会显示连对了几题。
  - 做完一组会看到星级、正确率、最长连对，以及这一轮之后各知识点的掌握程度，最后给出一个下一步建议，比如回到这一讲再听一遍、复习这门课，或者做单元测验。
- **闪卡**：点击翻面，然后按记忆情况选**忘了 / 困难 / 记得 / 简单**。开窍用间隔重复安排下次复习的时间，记得越牢，间隔越长。
- **复习**：学过的知识点也会按遗忘曲线回来。学习计划会提醒你**有 N 个知识点该复习了**，点**开始复习**即可。

## 资料库

支持的资料：

| 类型 | 说明 |
| --- | --- |
| PDF | 读取文字层，讲课和速查表会引用页码。扫描版 PDF 没有文字层，请截图后以图片上传 |
| Word（.docx）、PPT（.pptx） | 读取正文；PPT 按幻灯片编号引用 |
| Markdown、文本 | 自动识别 UTF-8 和 GB18030 编码 |
| 网页 | 点**添加网页**，填入公开网址，开窍会提取正文 |
| 图片 | 需要支持识图的模型 |

每份资料都可以一键**用它建课**，或者生成**速查表、闪卡、笔记、测验**，以及**消化**成概要、结构、核心观点、论点与论据、术语表和值得思考的问题。

## 学习工具、即时答疑与讲解短片

- **学习工具**：先**选择资料**，再生成速查表、笔记、闪卡组或测验。可以在**重点**里写上范围，例如「期中考试范围第 3–6 章」。速查表可以调**列数、字号**，开关**高亮重点**，隐藏某些部分，然后**打印**。
- **即时答疑**：不用建课，直接提问，老师在白板上讲给你听。可以**继续追问**，以前问过的问题都在**历史记录**里。
- **讲解短片**：输入一个主题，或者贴一个网址，点**生成短片**，得到一段约两分钟的白板讲解。

**导出视频**：短片和课程里的任意一讲都可以导出成 WebM 视频（1280×720），带手写板书、字幕和水印，并跟随白板外观（白板或黑板）。黑板上的小动画在视频里以一帧静态画面出现。浏览器的系统语音录不进视频，用系统语音导出的视频有字幕、没有声音；在设置里配置云端语音后，可以导出有声版。录制按实际时长进行，导出期间请保持页面打开。

## 实战项目

1. 在课程页的**项目**标签打开一个项目，查看**项目说明、里程碑**和**评分标准**。
2. 点**打开项目工作区**：开窍会在 `~/AhaTutor/projects/` 下创建项目文件夹，写入项目说明和起始文件，并在 DSH 里打开一个以它为工作区的会话，让编程 Agent 陪你一起做。文件夹里已有的文件不会被覆盖。
3. 做完后回到项目页，点**提交作品**：写几句说明（做了什么、遇到了什么问题），并勾选是否**同时提交项目文件夹里的文件**。老师会按评分标准逐项打分，指出**做得好的地方**和**可以改进的地方**。每次提交都记录在**历次提交**里。

## 学习计划与我的画像

- **学习计划**：设置**学习日**和**每周大约能学多久**，在**考试与截止日期**里添加重要日期。开窍会把所有在学课程的讲次和复习排进日程；按当前节奏赶不上截止日期时，会提醒你，并建议每周需要的学习时间。
- **我的画像**：老师会记住你的背景、目标、擅长和薄弱的地方、喜欢的讲解方式，以及它自己的备忘，让每门课都更贴合你。每一项都可以直接修改（每行一条），也可以**清空画像**。

## 在 DSH 对话里使用

新建会话时，在预设里选择 **「开窍 · AI 私人老师」**。在这个会话里，老师可以：

- 在白板上讲解：对话中出现一张白板卡片，点**打开白板**会在右侧栏播放；
- 出互动小测：直接在对话里作答；
- 帮你建课：把你们聊的内容变成一门课，之后在开窍里继续；
- 做速查表，查看你的学习画像。

这个预设可以读取你工作区里的文件和图片、搜索网页，但不会修改你的文件。

## 设置

- **模型**：分别为**出课与讲课**和**批改与问答**选择模型，或**跟随 DSH 默认模型**。
- **语音讲解**：
  - **语音来源**：系统语音（免费）/ 云端语音 / 不朗读。
  - **系统音色**：可以选**自动选择**，或指定一个音色。没有合适的中文音色时，可以在 macOS 的「系统设置 → 辅助功能 → 朗读内容」或 Windows 的「设置 → 时间和语言 → 语音」里添加。
  - **云端语音**：选择服务（OpenAI 兼容接口、火山引擎（豆包语音）、MiniMax、Azure 语音），填写接口地址、模型、音色等，再**保存密钥**。密钥保存在 DSH 的凭据库中，只在本机 Host 端使用。合成过的语音会缓存在本机，重播不再计费。
  - **默认语速**和**试听**。
- **白板外观**：跟随系统 / 白板 / 黑板。
- **板书字体**：手写体 / 标准体。
- **插件版本**：**检查更新**，有新版本时点**更新插件**，新版本刚发布也能直接装上。如果 DSH 的 pnpm 显式设置了发布冷却期，还没过冷却期的版本会显示可更新的时间，这不是失败。更新后请完全退出并重新打开 DSH。

## 关于作者

左侧导航最下方的**关于作者**里有作者信息、GitHub 仓库和**问题反馈**的链接。开窍免费开源，如果它帮到了你，也可以在这里扫码支持作者。

## 课程包：分享与备份

- 在课程页的 **⋯** 菜单里点**导出课程包**，再选**导出课程包**（只有课程内容）或**连同我的学习进度**，得到一个 `.aha-course.json` 文件。
- 别人在**我的课程**里点**导入课程包**，就能直接学这门课（已生成的板书和练习都在里面，不用重新生成）。
- 课程包只包含课程内容和可选的进度，不包含你的资料原文、画像和任何密钥。

## 数据保存在哪里

| 内容 | 位置 |
| --- | --- |
| 课程、进度、资料、画像、学习计划、语音缓存 | `$DSH_HOME/aha-tutor/`，默认 macOS 为 `~/.dsh/aha-tutor/`，Windows 为 `C:\Users\<用户名>\.dsh\aha-tutor\` |
| 实战项目文件夹 | `~/AhaTutor/projects/`，Windows 为 `C:\Users\<用户名>\AhaTutor\projects\` |
| 云端语音密钥 | DSH 的凭据库 |

想备份，复制 `aha-tutor` 文件夹即可；卸载插件不会删除这些数据。

## 遇到问题

| 现象 | 处理 |
| --- | --- |
| 左侧栏没有「开窍」 | 安装后需要完全退出并重新打开 DSH，只刷新页面不够 |
| 老师没有声音 | 到 **设置 → 语音讲解** 点**试听**；检查系统音量和音色，或改用云端语音 |
| 提示模型未登录或额度不足 | 在 DSH 设置里检查模型服务，或在开窍设置里换一个模型 |
| 资料太长超出上下文 | 少选几份资料，或换一个上下文更大的模型 |
| 生成结果不理想 | 点**重试**或**重新备课**；为「出课与讲课」换一个更强的模型 |
| PDF 读不出文字 | 扫描版没有文字层，截图后以图片上传 |
| 图片资料读不了 | 需要支持识图的模型 |
| 更新显示「待更新」 | DSH 的 pnpm 设置了发布冷却期，新版本还没过冷却期；到显示的时间后再更新 |

还有问题，欢迎到 [GitHub Issues](https://github.com/BaronCyrus/dsh-aha-tutor/issues) 反馈（请不要贴出密钥或个人学习数据）。