# OpenMentor 使用手册

> 老师 5 分钟搭出第一个 AI 导师的完整指南。
> 当前版本：**V2.2.0**

## 一、登录

浏览器打开 `http://你的IP:5001`，使用 `admin / openmentor` 登录（首次请修改密码）。

> 没安装好？看 [INSTALL.md](./INSTALL.md)。

顶栏右上角有 **🌗 主题切换** 按钮，可在浅色 / 深色模式间切换，自动保存偏好。

## 二、配置 AI 模型

第一次使用必须先配置一个国产大模型的 API Key。

1. 顶栏右上角你的用户名 → **个人设置**
2. 在 「AI 配置」标签页选择一家模型（推荐 **DeepSeek** —— 申请最快、对话快）
3. 把 API Key 粘贴到对应的输入框
4. 点「测试 API 密钥」验证有效性
5. 点「保存配置」

各模型 API Key 申请地址见 [INSTALL.md](./INSTALL.md#五配置-ai必做)。

## 三、（可选）班级花名册：管理学生班级数据

顶栏导航 → **班级花名册**

两套用途，按需使用：

### 1. 完整花名册（导入 Excel）

适用于：你想严格控制只有名单里的学生才能进入对话。

- 点「下载模板」拿到一个 4 列 Excel：`班级 / 姓名 / 学号 / 备注`
- 填好后「导入」，可选「合并」或「替换」模式
- 也可以单独「手动添加」一名学生
- 创建 AI 导师时把「学生身份验证」选成 **花名册校验**，学生进入页就只能从下拉中选自己的班级 + 姓名

### 2. 自由填写模式 - 班级选项配置

适用于：你不想做完整花名册，但又怕学生手填的班级名五花八门（"高一(3)班" / "高一三班" / "高一3班"），无法聚合统计。

在「自由填写模式 — 班级选项」区填一个 textarea，每行一组，例如：

```
高一: 1班, 2班, 3班, 4班
高二: 1班, 2班, 3班
```

或不带年级直接列班级：

```
三年(1)班
三年(2)班
三年(3)班
```

保存后，**所有 AI 导师在自由填写模式下**学生进入页就会变成「年级 → 班级」联动下拉 + 姓名手填，避免脏数据。

## 四、创建你的第一个 AI 导师

### Step 1 进入 AI 导师管理页

顶栏导航 → **AI 导师**

### Step 2 点击「创建 AI 导师」

填写以下字段：

| 字段 | 是否必填 | 示例 |
|---|---|---|
| 助学名称 | 必填 | `高中数学解题导师` |
| 简介 | 选填 | `面向高一学生的数学解题引导助手` |
| **AI 导师头像** | 选填 | 可上传图片，会显示在导师列表 / 学生扫码进入页 |
| 选择模型 | 必填 | DeepSeek（默认） |
| **系统提示词** | 必填 | 看下方 |
| 学生欢迎语 | 选填 | `你好！我是数学导师，遇到不会的题随时问～` |
| 多模态开关 | 选填 | 图片输入 / 文件上传 / AI 生图 默认开 |
| **学生身份验证** | 选填 | 自由填写（默认）/ 花名册校验 |
| 每生每日消息上限 | 默认 50 | |
| 链接有效期 | 默认 48h（最长 7 天）| |
| 关键词黑名单 | 默认 4 类 | |

### Step 3 系统提示词怎么写？

不会写没关系！点击右上角橙色按钮 **🪄 AI 帮我写提示词**。

在弹窗里回答 5 个问题：

1. **角色定位**：例 `高中数学解题导师`
2. **目标学生**：例 `高一基础薄弱学生`
3. **期望行为**：例 `先反问关键概念再讲解，不直接给答案`
4. **禁止行为**：例 `不抄袭、不评论同学`
5. **语气风格**：例 `耐心、用比喻`

可选：上传一份相关教材 PDF/Word，AI 会**自动提炼要点融入提示词**（不会把原文整段塞进去）。

点「🪄 生成草稿」 → 等约 5-30 秒 → 看到 800 字以内的专业提示词 → 点「✓ 采用到主表单」。

### Step 4 保存创建

点「创建 AI 导师」按钮，跳到详情页。

## 五、把链接分享给学生

详情页中央有：

- **学生访问链接**：复制按钮一键复制
- **二维码**：右侧自动生成，可投屏或截图发到班级群

> ⚠️ 学生设备必须与教师机在**同一局域网/校园网**。

学生使用流程：

1. 扫码 / 点链接
2. 填写「班级」+「姓名」（开了花名册校验或班级选项的 → 下拉选择；自由模式 → 自己输入）
3. 进入聊天界面，开始提问
4. 可以发文字、图片、文件，按"魔棒"按钮还能让 AI 生成图片
5. 每条 AI 回复下方有 **👍 有用 / 👎 没用** 评分按钮，学生可以反馈
6. 学生可"添加到主屏幕"把对话页当原生 App 用（PWA 化）

### 隐私小贴士（学生端自动启用）

- **设备 × 身份双重隔离**：同一个名字"张三"在 A 手机和 B 手机进入 → 后端是两段独立会话，互不可见。即使有同学拿别人手机登"张三"，也只看到刚开的空对话
- 老师后台仍能看到所有设备的所有内容

## 六、实时审计学生对话

详情页 → 点 **「对话审计」** 按钮（眼睛图标 👁）

### 顶部统计卡

- **已对话学生**（按班级 + 姓名去重，多设备会话不重复计数）
- **消息总数**
- **满意度**（基于学生👍/👎 评分）+ 阈值着色（≥70%绿、40-70%黄、<40%红）
- **黑名单触发次数**
- **助学状态**

### 学生会话列表

每行展示一名学生的班级 / 姓名 / 提问数 / 今日额度 / 最近活动 / 最后内容预览 / 状态

特殊徽章：
- 「📱 N 台」橙色徽章 → 该学生在 N 台设备上有独立会话
- 黄色 ⚠ → 触发过黑名单
- 红色 → 已被封禁

### 搜索 + 筛选

列表上方有搜索框 + 班级下拉 + 状态下拉，可按班级、姓名、最后内容、状态（活跃 / 已封禁 / 多设备）任意组合过滤。

### 单学生详情

点某行「查看对话」 → 进入该学生的完整消息流，每 5 秒自动更新。

- 多设备的学生，详情页头部会显示**设备切换条**，点对应设备 tab 看那个设备上的对话
- 老师可以"封禁该学生"立即停止其使用（多设备会一并封禁）

## 七、AI 学情报告（V1.1.3 新功能）

### 班级级报告

审计页头部 → **「✨ 生成 AI 学情报告」** → 二次确认（显示样本量）→ 等 AI 生成 → 弹出 6 段 Markdown 报告：

1. 整体使用情况
2. 共性知识盲点
3. 提问类型分布
4. AI 互动质量
5. 值得关注的学生（点名 3-5 名）
6. 教学改进建议

支持**按当前班级筛选**：你筛了"四年(3)班" → 报告就只针对这个班的学生；不筛 → 全部学生。

### 单学生级报告

进入某个学生的详情页 → 头部 **「✨ 生成 AI 学情报告」** → 5 段报告：

1. 学习画像
2. 知识盲点
3. AI 互动效果
4. 安全与态度
5. 给老师的建议

### 报告历史

每次生成的报告都自动入库永久保存。点 **「📚 报告历史」** 按钮：
- 班级级报告：审计页头部
- 学生级报告：学生详情页头部（自动只显示这位学生的）

历史报告支持：查看 / 复制 Markdown / 下载 .md / 删除。

## 八、学情大屏：班级数据可视化（V1.1.x 功能）

顶栏导航 → **学情大屏**

7 张 ECharts 图表 + 5 张概览卡：

- 每日消息趋势（堆叠柱：学生提问 vs AI 回答）
- 学生满意度分布（环形）
- 班级活跃度排行
- 学生参与排行 Top 10
- AI 导师使用分布
- 24 小时活跃时段
- 关键词命中 Top 10（红色，方便发现需关注学生）

支持三个维度筛选：AI 导师 / 班级 / 时间窗（7 / 30 / 90 / 180 天），每 60 秒后台静默刷新。

## 九、导出 / 分享 / 克隆

### 导出对话为 Excel

审计大屏 → 「导出全部对话 Excel」 → 下载 `.xlsx` 文件，可作为教研数据保存。

### 导出 AI 导师模板（与同事分享）

详情页 → 「导出模板」 → 下载 `.json` 文件 → 发给同事。

> 模板**仅包含配置**（系统提示词、欢迎语、多模态开关等），**不包含**：
> - API Key（同事需自己填）
> - 对话历史
> - 上传的附件

### 克隆已有助学

详情页 → 「克隆」 → 自动创建一份副本，可在副本基础上修改。

### 导入同事分享的模板

AI 导师列表 → 「导入模板」 → 上传 JSON 文件或粘贴 JSON 文本 → 确认。

## 十、紧急熔断

发现学生在滥用、出 bug 或 API 烧太快？

详情页 → **「禁用（紧急熔断）」** 按钮 → 立即禁用，所有学生显示「该 AI 导师已被老师暂时关闭」。

修好后再点同一按钮启用。

## 十一、安全策略调优

### 调整每日消息上限

编辑 AI 导师 → 「每生每日消息上限」 → 修改后保存。

> 默认 50 条。考试季可以调到 30 条防刷题，自由探索可以调到 100 条。

### 自定义关键词黑名单

编辑 AI 导师 → 「关键词黑名单」 → 4 类分组开关 + 自定义关键词。

四类默认黑名单：

- 暴力自残（默认开）
- 色情低俗（默认开）
- 越狱提示词（默认开）—— 防学生绕过设定
- 学习作弊（默认关）—— 比如「直接给我答案」

### 链接续期

编辑 AI 导师 → 勾选「重置有效期」 → 选时长（24h/48h/72h/168h）→ 保存。

## 十二、和 QuickForm 一起用（V1.1.3 增强：附件支持）

OpenMentor 保留了 QuickForm 全部原有功能（数据任务、HTML 表单收集、AI 报告等），并新增了**附件上传**能力。

顶栏 「**QuickForm**」下拉菜单 → 数据任务 / 导入任务 / 教程

### 1. 普通 JSON 数据采集（原 QuickForm 功能）

- 创建任务 → 拿到 API 地址 `http://你的IP:5001/api/<task_id>`
- 在任意 HTML 表单 / 网页中 POST 到该地址（JSON 或 form data）
- 任务详情页 → 「提交数据列表」实时看数据

### 2. 提交带附件的数据（V1.1.3 新增）

只要 HTML 表单加上 `enctype="multipart/form-data"` 和 `<input type="file">`，提交时自动支持图片/文档/音视频上传：

```html
<form action="http://你的IP:5001/api/abc123XYZ" method="post" enctype="multipart/form-data">
  <input name="student_name">
  <input type="file" name="screenshot" accept="image/*">
  <input type="file" name="paper">
  <button type="submit">提交</button>
</form>
```

服务端会：
- 保存到 `static/uploads/quickform/<日期>/<任务ID>/` 按日期分桶
- 在数据 JSON 中加 `_attachments` 字段
- POST 响应里返回每个附件的 URL，前端可立即显示

### 3. 老师后台「查看附件」

任务详情页或数据查看页 → 数据列表中带附件的行右侧有绿色 **📎 查看附件 (N)** 按钮 → 模态框预览：

- **图片**：直接显示，点击放大
- **PDF**：内嵌 PDF.js 阅读
- **视频**：内置播放器
- **音频**：内置播放器
- **文本类**（TXT / MD / CSV / JSON）：iframe 渲染
- **其他**：友好占位 + 一键下载

每个附件下方有 **3 个按钮**：
- **新窗口打开**
- **下载**
- **🟠 在本机打开文件夹**（V1.1.3 新）—— 在运行 OpenMentor 那台电脑的 Finder / 资源管理器中定位文件，**自部署场景免下载就能查看**

### 4. 学生 / 开发者读取数据

任何人调用 `GET http://你的IP:5001/api/<task_id>` 都能拿到该任务全部提交（含附件 URL），可以做自定义可视化页。

## 十三、常见问题

### 我的 API Key 会被泄露吗？

不会。API Key 仅存在你本地的 SQLite 数据库。OpenMentor 不上传任何数据到外部服务器（除非调用 LLM API 时本次消息）。

### 学生能看到其他学生的对话吗？

不能。每个学生的对话完全独立隔离。设备 × 身份双重隔离机制确保即使同名也只看自己设备上的记录。只有老师在审计大屏能看到所有学生。

### 如果一个学生发了不当内容怎么办？

3 个保护层：

1. **关键词黑名单**自动拦截 + 记录命中事件
2. **审计大屏**老师可看到完整对话
3. **封禁该学生**立即停止其使用

### 学生作弊怎么办（让 AI 直接做作业）？

- 系统提示词中明确写「先引导思考，不直接给答案」
- 启用「学习作弊」黑名单类别
- 审计大屏定期查看 + 用 **AI 学情报告**自动归纳"被 AI 帮了很多但没真正学会的"学生

### 一个老师能开多少个 AI 导师？

无上限。每个助学独立运作，互不影响。

### 数据怎么备份？

整个项目目录复制一份就行。核心数据在 `openmentor.db`（SQLite）+ `static/uploads/`（附件，按日期分桶）。

### 学生换手机后历史对话还在吗？

由于设备 × 身份隔离机制，**学生在新设备上是新对话**。如需让学生在旧设备的历史"导出"，建议老师从审计页代为下载 / 截图。

---

🎉 现在你已掌握全部 V1.1.3 功能！开始为你的学生设计 AI 导师吧。
