# quickclass-release **Repository Path**: maoyouhui/quickclass-release ## Basic Information - **Project Name**: quickclass-release - **Description**: No description available - **Primary Language**: TypeScript - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 8 - **Forks**: 4 - **Created**: 2026-06-01 - **Last Updated**: 2026-10-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: 人工智能, 智慧教育 ## README # QuickClass 使用指南 ## 1. 系统概述 QuickClass 是一个 AI 驱动的课堂教学辅助平台，帮助教师创建互动式学习活动、管理课堂作业、分析学情数据。核心功能包括： - **对话活动**：学生与 AI 进行主题对话，深入理解知识点 - **互动探究**：HTML 交互式学习活动，支持提交和评分 - **项目提交**：学生提交作品，互看互评，支持置顶与下架 - **课堂作业**：在线答题，自动批改，即时反馈 - **学情分析**：AI 自动生成个人和全班分析报告 - **教学研究**：基于课堂数据（对话、作业、报告）一键生成研究论文 - **知识库**：上传教学资料，AI 对话时自动引用 - **图片仓库**：上传教学图片，AI 对话时智能发送给学生 > **配套工具**：WorkBuddy 技能市场提供「QuickClass 课堂转换器」和「作业转换器」，可把现有教案、试卷直接转成课堂 JSON 导入本平台；课堂建好后还能一键导出教学手册与学习手册。详见 **第 5 章** 与 **2.13 节**。 ### 适用场景 - 课堂教学中的个性化辅导 - 课后作业布置与批改 - 学情数据采集与分析 - 探究式学习活动设计 --- ## 2. 教师端 ### 2.1 登录与账号管理 #### 登录 1. 浏览器访问 `http://localhost:3000` 2. 输入手机号和密码 3. 点击「登录」 首次登录后，系统会检查用户信息是否完整。如不完整，会提示前往设置页面补充。 #### 注册 1. 在登录页面点击「注册」 2. 填写手机号、密码、姓名 3. 可选填写邮箱、学校 4. 点击「注册」 #### 忘记密码 1. 在登录页面点击「忘记密码」 2. 按提示通过密保问题重置密码 --- ### 2.2 创建课堂与班级管理 #### 创建课堂 1. 进入「课堂管理」页面 2. 点击「新建课堂」 3. 填写课堂信息： - **课堂标题**（必填）：如「一元一次方程」 - **课堂目标**（必填）：描述本课堂的学习目标 - **年级**（必填）：选择适用年级 - **学科**（必填）：选择学科 - **班级**（必填）：选择要分配的班级 4. 点击「保存」 创建成功后，课堂自动展开并进入对话活动编辑模式。 #### 班级管理 1. 进入「班级管理」页面 2. 可创建新班级，每个班级自动生成**邀请码** 3. 学生通过邀请码加入班级 4. 可设置是否开放邀请码注册（开启后学生可自助注册） #### 学生管理 1. 进入「学生管理」页面，查看所有班级的学生列表 2. **导入学生**：点击「导入学生」，每行一个学生，格式 `姓名,学号,密码`（学号、密码可选，密码留空默认 `123456`） 3. **重置密码**：点击学生右侧的「重置密码」，密码恢复为默认密码 `123456`，学生可用姓名/学号 + 密码登录 #### 学号编码规范（重要） 系统支持学生使用**学号 + 密码**登录（学号优先于姓名匹配）。因此学号**不要**使用 `1`、`2`、`3`、`4` 这样简单的数字——各班都用简单序号时，学号会在不同班级间重复，学生登录时系统无法直接定位到唯一账号。 请使用**带班级属性的组合编码**：`班级代码（2 位）+ 班内序号（2 位）`： | 学号 | 含义 | |------|------| | `0101` | 一班 1 号 | | `0115` | 一班 15 号 | | `0201` | 二班 1 号 | | `0328` | 三班 28 号 | 这样编码后，学号在全校范围内天然唯一，学生凭「学号 + 密码」即可直接登录。班级较多或班额较大时可按需扩展位数，核心原则是：**编码中包含班级属性，保证不与其他班的学号重复**。 > **提示**：若历史上已存在跨班重复学号，学生仍可登录——密码验证通过后系统会弹出班级列表，由学生选择自己的班级完成。但按上述规范编码可避免这一步。 #### 课堂状态 | 状态 | 说明 | |------|------| | 已停用 | 课堂未发布，学生不可见 | | 已启用 | 课堂已发布，学生可见可使用 | | 已归档 | 课堂已结束，学生不可见 | --- ### 2.3 对话活动管理 对话活动是学生与 AI 进行主题对话的核心载体。 #### 编辑对话活动 1. 在课堂列表中展开目标课堂 2. 点击「活动管理」进入编辑模式 3. 可添加、编辑、删除对话活动 #### 对话活动字段说明 | 字段 | 说明 | 是否必填 | |------|------|----------| | 对话活动名称 | 活动标题，如「什么是方程？」 | 是 | | 对话活动目标 | 活动描述和学习目标 | 是 | | 对话提示词 | 注入 AI 的系统提示词，决定 AI 的角色和行为 | 是 | | 个人学情分析提示词 | 生成学生个人分析时使用的提示词 | 是 | | 全班学情分析提示词 | 生成全班分析时使用的提示词 | 是 | #### 启用/禁用对话活动 - 在课堂列表中，每个对话活动旁有开关按钮 - 禁用后学生端不再显示该对话活动 - 已有的学生对话记录不会删除 #### 排序 - 使用上下箭头按钮调整对话活动顺序 - 学生端按此顺序显示 --- ### 2.4 互动探究管理 互动探究是 HTML 交互式学习活动，支持学生操作和提交。 #### 创建探究活动 1. 在课堂展开区域，点击「互动探究」面板 2. 点击「新建探究」 3. 填写标题、描述 4. 编辑 HTML 交互内容（支持直接编辑 HTML 代码） #### AI 生成题目 1. 编辑探究内容后，点击「AI 生成题目」 2. 系统根据探究内容自动生成 4 道题目（1 单选 + 1 多选 + 1 填空 + 1 简答） 3. 生成后可手动调整 > **注意**：已有学生提交后，点击「编辑」会提示「已有学生提交，请清除后编辑！」。清除方法见下方「编辑限制」。 #### 提交功能 - 「启用提交」开关开启后，学生端页面底部出现「提交」按钮 - 开启时系统自动分析页面，判定采集类别：有无评分环节（分数 / 闯关 / 对错）、有无可填控件（输入框 / 下拉框 / 文本域）、有无画布；无评分的页面不采分数，不会编造 - 若页面尚未接入采集（常见于导入的旧页面），开启提交时会自动进行「AI 接入采集」——在代码中插入上报调用，不改变任何视觉与交互 - 探究列表中显示「✓ 已接入采集 / △ 未接入采集」标记 #### 数据采集机制（双轨） 学生点击「提交」时，系统同时采集两类数据： | 数据轨 | 采集内容 | 查看位置 | |---|---|---| | 行为数据 | 得分、关卡、完成环节、停留时长、操作次数、操作日志 | 分析页「提交详情 → 行为数据」 | | 表单答案 | 学生在页面表单控件中填写的全部内容 | 分析页「提交详情 → 收集数据」及数据大屏 | #### AI 接入采集（自动补充采集） 导入的旧页面（或尚未接入采集的页面）往往没有上报代码，学生操作的关键数据——分数、关卡、滑杆最终值、开关状态、结论文字等——会漏采。开启「启用提交」时，系统会自动用 AI 分析页面，把需要采集的数据**自动接入采集通道**，全程不改变页面任何视觉、交互与文案。探究列表里的「✓ 已接入采集 / △ 未接入采集」标记显示的就是这个状态。 AI 先判断页面形态，再按形态接入： | 页面形态 | AI 自动做什么 | 接入后采集到 | |---|---|---| | 游戏 / 练习型（有得分、关卡、对错） | 找到记录分数 / 关卡 / 完成状态 / 答案的代码，在更新处插入上报调用 | `分数 80`、`关卡 第3关`、`完成环节 ["环节1","环节2"]` | | 纯交互 / 探索型（模拟实验、拖拽、概念可视化，无表单无分数） | 找出关键可观察状态（滑杆 / 参数最终值、开关 / 灯泡状态、学生输入的结论文字），以自定义键名接入 | `{ 摆长: 50, 灯泡状态: "亮", 我的发现: "..." }` | | 两者兼有 | 同时处理 | —— | > 注意：纯交互 / 探索型页面没有分数和答题，AI **不会虚构分数或答案**，只采集页面里真实存在的关键状态。 **示例**：导入一个「单摆实验」旧页面——只有滑块调摆长、一个「开始摆动」按钮，没有表单、没有计分。开启「启用提交」时 AI 自动接入后： - 学生拖动「摆长」滑块到 50cm → 采集到 `摆长: 50` - 学生点「开始摆动」观察 → 采集到 `完成环节: ["开始实验"]` - 学生在观察结论里写下「摆长越长周期越长」→ 采集到 `我的发现: "摆长越长周期越长"` - 这些数据会像表单答案一样进入「统计信息」数据大屏与「提交详情 → 收集数据」，无需手写任何代码 > 若 AI 接入失败（网络等原因），系统会降级为基础采集（时长 / 操作 / 滚动），分数、关卡、作答暂无法上报，但页面仍可正常提交；此时探究列表保留「△ 未接入采集」标记，可再点一次重试。 #### 如何把交互结果保存在表单框中（HTML 编写要点） 页面中的**标准表单控件**会被自动采集，无需额外代码： 1. 放置控件：文本框 / 下拉框 / 文本域 / 单选 / 多选（``、`

我觉得这个知识点：

``` **游戏 / 练习型页面**（有分数、关卡）与**纯交互 / 探索型页面**（模拟实验、拖拽观察等，无表单无分数）：这类页面没有标准表单控件，需要采集的数据（得分、关卡、滑杆最终值、开关状态、结论文字等）由「AI 接入采集」自动接入上报通道，无需手写代码，详见上一节。 #### 查看采集数据 1. 探究卡片上点击「分析」（绿色按钮，开启提交后显示），进入独立分析页 2. 分析页顶部有三大页签——**统计信息**、**提交详情**、**AI 分析报告**，右上角是「刷新」按钮（旁有「最后更新」时间；多班级时还有班级下拉框） ##### 右上角「刷新」按钮 **作用**：轻量重拉最新提交列表与 QuickForm 收集记录，不整页加载。 **操作步骤**： 1. 学生陆续提交后，回到分析页 2. 点击右上角「刷新」按钮，按钮短暂转圈后，「最后更新」时间更新为当前时刻 3. 下方三大页签的数据同步变为最新 **自动触发**：切换页签、切换班级下拉框时也会自动刷新对应班级的提交 / 数据大屏 / 提交详情，无需手动点。 **示例**：上完课学生当场提交探究，你在大屏投屏。等大家交得差不多时点一下「刷新」→ 大屏上的柱状图、名单、KPI 数字立刻更新到最新，不用退出页面重进。 ##### 「统计信息」页签（数据大屏） **默认大屏（零 AI、秒开）**：学生表单答案自动成图——数值→柱状图、选项→饼图 / 横条、姓名 / 学号直接列名单，顶部是「已提交 / 收集字段 / 名单人数 / 最近提交」四张 KPI 卡。 **「AI 重排大屏 / AI 重新排布」按钮**：让 AI 重新挑选字段、图型与强调色。 **操作步骤**： 1. 在按钮旁的输入框写自定义要求（可留空，留空则 AI 自动挑重点） 2. 点击「AI 重排大屏」按钮 3. 等待数秒，AI 生成图表配置并落库缓存，提示「已按 AI 配置重排大屏」 4. 之后每次打开都按此配置渲染；按钮变为「AI 重新排布」，旁边出现「恢复默认」按钮 5. 点「恢复默认」即可回到默认大屏 **自定义要求示例**： | 在输入框写 | 效果 | |---|---| | （留空） | AI 自动挑选字段、图型、强调色与布局 | | `清新绿色` | 绿色清新配色 | | `突出年龄分布` | 把「年龄分布」设为通栏主视觉图，放最显眼位置 | | `一行放四个图` | 图表栅格一行显示 4 张图 | | `一行两个，把得分分布通栏放最上面` | 2 列栅格，得分分布占整行通栏 | | `突出平均分和提交人数` | KPI 只突出平均分、提交人数两个指标 | | `突出最高分、最低分、平均分` | KPI 依次展示最高 / 最低 / 平均三个指标 | > KPI 提示：描述指标时用「平均 / 最高 / 最低 / 总和 / 提交人数 / 去重」等词，AI 会精准兑现——「平均」→ 均值、「最高」→ 最大值、「提交人数」→ 提交总人数、「去重」→ 去重计数。 > 布局提示（几行几列）：图表按栅格排列，「一行放 N 个」控制一行几列（可选 2 / 3 / 4），「通栏」让某张图占满整行做主视觉（最多 1 个通栏）。字段少（≤3 个）默认 2 列、中等（4~6 个）3~4 列；姓名 / 学号名单始终通栏展示。 **安全说明**：AI 只产出图表配置 JSON（不产出 HTML），前端按配置渲染，避免脚本注入风险。 ##### 采集数据如何展示（图型对照） 无论表单是「题目 + 总分」，还是投票、量表、接龙、模拟实验等任意形式，大屏都按**字段名驱动**：字段下拉 = 收集到的所有字段名 + 「提交时间」，画什么图由「字段值是数字还是文本」决定，跟字段本身是不是"题"无关。 | 字段类型 | 例子 | 推荐图型 | 可搭配 | |---|---|---|---| | 单选题（离散文本） | 最喜欢的季节 / 是否同意 | 环形图 / 柱状图 | 标签列表 | | 多选题（数组） | 选了哪些方法 | 柱状图（各选项被选次数） | 标签列表 | | 数字填空 | 估一周看几小时 / 年龄 | 柱状图（数值分桶） | 折线、排行榜 | | 评分 / 量表（1~5 分） | 课堂满意度 | 柱状图 + 均值 KPI | 折线、排行榜 | | 姓名 / 学号 | 接龙报名 | 名单（roster） | —— | | 提交时间 | 谁先交 / 交作业节奏 | 排行榜（升序=谁先交） | 折线（时间分布） | | 短标签 / 关键词 | 头脑风暴关键词 | 词云 | 标签列表 | | 两个数字字段 | 用时 vs 正确率 | 散点图 | —— | **KPI 指标卡**支持 6 种聚合：计数 / 去重 / 均值 / 求和 / 最大 / 最小。 **一句话规则**：值能转数字 → 柱状 / 折线 / 排行榜 / 散点；值是固定选项 → 环形 / 柱状 / 词云；值是唯一标识（姓名）→ 名单；值是时间 → 排行榜 / 折线。 > ⚠️ 开放简答长文本（每人答案都不同）不适合柱状 / 饼图（每段文字各出现 1 次、没有聚合意义），词云也仅按整句统计、不做分词；这类字段建议改用 KPI「去重 / 计数」或名单展示。 > ⚠️ 数值判断是「一票否决」：字段必须**所有值都能转成数字**才会走数值分桶 / 排行榜排名，混进一条文本就退回文本计数；散点图要求 X、Y 两个字段**都是纯数值**，否则整张图不渲染。 ##### 「提交详情」页签 **作用**：查看每位学生的提交明细。 **操作步骤**： 1. 进入「提交详情」页签 2. 若绑定了 QuickForm 收集任务，顶部有「收集数据 / 行为数据」切换按钮： - 「收集数据」：学生表单答案的名单表（姓名、学号、各题答案） - 「行为数据」：得分 / 关卡 / 完成环节 / 停留时长 / 操作次数 / 操作日志 3. 在「行为数据」视图点击某位学生，展开该生的完整提交数据、操作记录与 canvas 作品快照（快照按需拉取） **示例**：想快速核对「哪些学生还没交」→ 看「收集数据」名单表；想看某个学生作品的画布快照和操作轨迹 → 切到「行为数据」并点开该学生。 ##### 「AI 分析报告」页签 - 点击「生成报告」，AI 基于全部提交数据（行为 + 表单答案）生成班级分析报告与教学建议 #### 编辑限制 - 已有学生提交时，点击「编辑」会提示「已有学生提交，请清除后编辑！」，作业「快编」同理 - 清除流程：先关闭「启用提交」开关 → 卡片上出现「清除提交」按钮 → 点击清除 → 重新编辑发布 - 清除会删除全部提交记录与收集答案，操作前请确认数据不再需要 --- ### 2.5 项目提交管理 项目提交与对话活动、互动探究**并列**挂在学习活动（SubProject）下，是课堂内的第四类学生活动。 #### 新建项目 1. 在课堂的「项目提交」面板点击「新建项目」 2. 输入项目名称 3. 年级 / 学科自动从所属课堂带入，可修改 4. 设置项目类别：文本类 / 图片类 / 音视频类 5. 设置是否全班可见、是否允许点赞（开点赞自动开全班可见） 6. 设置文件大小限制（数字，单位 MB，默认 10） 7. 保存后出现在项目提交列表中，左侧显示「生效中/失效中」标签 #### 生效开关 Switch 控制项目是否对学生可见，卡片右侧末尾 #### 浏览全班提交 - 点击「浏览」按钮，在当前页面内打开照片墙视图（非独立页面） - 列数可调：顶部 [2列][3列][4列][6列] 按钮切换网格密度 - 点击图片弹出全屏灯箱查看原图（黑色半透明背景，点击关闭） - 非图片类显示占位区 + 查看文件链接 #### 置顶与下架 - 点击卡片上 ↑ 箭头将提交排到全班最前，红色表示已置顶，再次点击取消 - 点击卡片上 ↓ 箭头隐藏提交（仅学生本人可见），红色表示已下架，再次点击恢复 - 置顶和下架互斥：置顶状态下不可下架，需先取消置顶；反之亦然 - 下架项目教师端排最后且姓名显示「***」 #### 点赞 教师和学生均可点击爱心 ♥ 图标点赞/取消点赞，红色表示已点赞，数字实时更新，每人每个项目仅一次 #### 排序 生效中的项目支持 ↑↓ 拖动排序（在 Switch 右侧） #### 编辑与删除 - 编辑：修改项目任务（名称/类别/可见性/点赞/大小限制）不影响已提交学生的项目与附件，仅对后续提交与未提交者生效 - 删除：级联删除该任务下所有学生提交及附件记录，并物理删除磁盘附件文件 --- ### 2.6 课堂作业管理 #### 创建作业 1. 在课堂展开区域，点击「作业管理」 2. 点击「新建作业」 3. 填写作业标题和描述 #### 添加题目 1. 进入作业详情，点击「添加题目」 2. 选择题型：单选题、多选题、判断题 3. 填写题目内容、选项（选择题）、答案、分值、难度 4. 也可使用 AI 自动生成题目 > **注意**：课堂作业仅支持**单选题、多选题、判断题**三种题型，**不支持填空题和简答题**（填空、简答仅用于互动探究的 AI 生成题目）。 #### 作业状态 | 状态 | 说明 | |------|------| | 未生效 | 草稿状态，学生不可见。编辑保存后自动回到此状态 | | 已生效 | 已发布，学生可答题。需至少添加一道题目才能生效 | > **注意**：每次编辑保存作业后，状态会自动变为「未生效」，需重新发布。 #### 作业统计与报告 - **统计**：查看答题人数、平均分、正确率 - **报告**：AI 自动生成作业分析报告 --- ### 2.7 课堂导入与导出（含题目与出处） QuickClass 支持将整个课堂结构导出为 JSON 文件，分享给其他教师后由对方「导入课堂」一键重建。导出内容包含四类学生活动：对话活动、课堂作业（含全部题目）、互动探究、项目提交，以及被引用的知识库。 #### 导出课堂（生成"出处"文件） 1. 进入「课堂管理」页面 2. 在目标课堂卡片右上角点击「导出课堂」图标 3. 浏览器自动下载一个 JSON 文件 > **出处标记**：导出的课堂标题会自动追加 `_来源于_原教师姓名` 后缀（如 `一元一次方程_来源于_张老师`）。对方导入后，课堂名称保留该出处，便于追溯来源。 #### 导入课堂（含题目） 1. 在「课堂管理」页面顶部，点击「导入课堂」按钮 2. 选择本机上的课堂 JSON 文件（即他人导出的文件） 3. 系统自动重建课堂，并带出： - 所有对话活动及提示词 - 所有课堂作业及其题目（单选/多选/判断） - 所有互动探究活动 - 所有项目提交任务 4. 若原课堂引用了知识库，导入时会在你账号下自动创建或复用同名知识库并关联 #### 导入后的注意事项 | 项目 | 导入后状态 | 你需要做的 | |------|-----------|-----------| | 课堂 | 已停用（不可见） | 检查内容后手动启用 | | 课堂作业 | 未生效 | 检查题目后重新发布 | | 知识库 | 已创建并关联 | 可在知识库管理查看，名称含导入者+出处 | > **说明**：导入的课堂不会带入原教师、学生、班级及任何对话/答题记录，仅恢复教学结构本身。 --- ### 2.8 知识库管理 知识库是上传的 .md 或 .txt 教学资料。被课堂引用后，学生在该课堂的 AI 对话和教师的学情分析中，AI 会基于知识库内容来回答和生成报告。 #### 新建知识库 1. 进入「知识库管理」页面 2. 点击「新建知识库」 3. 输入名称，拖拽或选择上传 .md / .txt 文件（上限 50,000 字符） 4. 保存后自动启用 #### 编辑 - 可修改名称，重新上传文件替换内容 - 修改后立即生效，不影响已引用的课堂 #### 预览 - 点击知识库旁的「预览」，查看全文内容 #### 启用/禁用 - 禁用的知识库不会出现在课堂引用列表中 - 已引用该知识库的课堂不受影响 #### 删除 - 删除前弹出确认对话框，显示被哪些课堂引用 - 确认后级联删除，相关课堂的引用关联自动移除 #### 在课堂中引用 1. 创建或编辑课堂时，在「引用知识库」区域勾选目标知识库 2. 可同时引用多个，总计不超过 50,000 字符 3. 保存后，学生在该课堂的 AI 对话中会基于知识库内容回答 4. 展开课堂卡片可看到已引用的知识库名称和字符数 #### 导入课堂时知识库处理 - 若导入的课堂引用了知识库，会在你的账号下自动创建或复用同名知识库 - 自动创建的知识库命名格式：`导入者姓名_课堂标题_知识库名_导入日期` --- ### 2.9 对话记录查看与删除 1. 进入「对话记录」页面 2. 可按班级、课堂、对话活动筛选 3. 可按学生姓名搜索 4. 展开对话可查看完整聊天记录 5. 支持单个删除和批量删除 6. 支持清空某个班级的所有对话记录 --- ### 2.10 学情分析 学情分析是 QuickClass 的核心功能，基于学生的对话记录、AI 伴学对话、作业答题数据，AI 自动生成分析报告。分析分为**个人分析**和**全班分析**两个维度。 #### 进入学情分析 1. 在课堂列表中，点击课堂旁的「分析」按钮 2. 或进入「课堂管理」→ 展开课堂 → 点击对话活动旁的「分析」 #### 分析层级 - **对话活动层级**：选择具体对话活动，查看该活动下的分析（仅教师端可见） - **课堂层级**：查看整个课堂的综合分析，其中**个人分析**会同步展示给学生端 **课堂级分析数据来源：** | 数据类型 | 说明 | |----------|------| | 预设对话 | 学生在各对话活动中与 AI 的对话记录 | | AI 伴学对话 | 学生在互动探究中与 AI 伴学的对话记录，自动纳入课堂级分析 | | 课堂作业 | 答题得分、正确率及班级统计 | | 子分析报告（聚合模式） | 各对话活动已生成的分析摘要 | > **注意**：AI 伴学对话仅用于课堂级分析（班级/个人），对话活动级分析不含此类数据。 #### 对话学情分析 基于学生与 AI 的对话记录（含预设对话和 AI 伴学对话），分析学生对知识的理解程度。 **个人分析** - 选择具体学生，点击「生成分析」 - AI 根据该学生的对话内容，分析： - 知识理解程度和薄弱点 - 思维过程和表达特点 - 学习建议和改进方向 - 支持批量一键分析所有学生 - 分析结果按星级指数排序，快速定位需要关注的学生 **全班分析** - 点击「生成班级分析」 - AI 汇总全班学生的对话数据，生成整体分析报告 - 报告包含两种呈现形式： - **文本分析**：结构化的文字报告，包含班级整体掌握情况、共性问题、教学建议 - **HTML 大屏分析**：可视化数据大屏，适合课堂投屏展示，包含： - 班级整体掌握度雷达图 - 各知识点理解程度柱状图 - 学生分布散点图 - 关键指标统计卡片 - 支持多版本管理，可对比不同时间点的分析结果 #### 互动探究分析 基于学生的探究提交数据（操作记录、得分、用时等），分析探究学习效果。 **个人分析** - 选择具体学生，查看其探究提交详情： - 操作过程和交互记录 - 得分和完成情况 - AI 生成的个人学习建议 - 支持查看学生的操作日志（点击、滚动、输入等行为） **全班分析** - 汇总全班探究提交数据，生成整体分析 - 报告包含两种呈现形式： - **文本分析**：全班探究完成率、平均得分、得分分布、共性问题、教学建议 - **HTML 大屏分析**：可视化展示： - 完成率和参与度统计 - 得分分布直方图 - 各探究环节完成情况热力图 - 典型问题和高频错误分析 - 支持多版本管理和版本对比 #### 作业分析 基于学生的作业答题数据，分析知识掌握情况。 **个人分析** - 选择具体学生，查看其答题详情： - 各题答题情况和正误 - 总分和各题型得分 - AI 生成的错题分析和学习建议 - 支持查看学生的具体答案和批改结果 **全班分析** - 汇总全班答题数据，生成整体分析 - 报告包含两种呈现形式： - **文本分析**：全班正确率、平均分、得分分布、典型错误、教学建议 - **HTML 大屏分析**：可视化展示： - 各题正确率柱状图 - 得分分布直方图 - 选项选择分布饼图 - 高频错误和知识点薄弱环节分析 - 支持多版本管理和版本对比 #### 分析提示词模板 - 系统内置多种分析提示词模板 - 教师可自定义模板，控制分析报告的格式和侧重点 - 支持 AI 自动生成提示词 - 发送前可预览完整 Prompt，确认后执行 > **进阶定制**：想自定义分析报告的维度、等级标准与图表板块，请阅读《[教师模板修改指南](./教师模板修改指南.md)》。 --- ### 2.12 教学研究（AI 论文生成） 教学研究功能基于课堂数据（学生对话、课堂作业、学情分析报告）一键生成研究论文。其底层采用**数据快照**机制，理解以下两点有助于正确使用： #### 数据快照（冻结机制） - 创建研究项目时，系统会**实时扫描数据库**，把所选的对话、作业、报告**一次性打包成一份 JSON 快照**，存入该项目记录中（字段名为 `dataSnapshot`）。 - 快照是原始教学数据的**独立副本**，而非实时引用。因此： - 你对数据库里学生对话、作业的**后续增删改，不会影响已创建的研究项目**。 - 即使你删除了全部对话记录，已生成或重新生成的论文**仍基于创建时冻结的那份快照**（例如论文里仍会引用创建时统计到的"216 条对话"）。 - 重新生成论文：读取的是该项目创建时冻结的快照，**不会**回去重新扫描数据库。论文因此可复现——删除/改动学生数据不会让旧研究跟着变。 #### 删除即删除快照 - 删除研究项目时，整条项目记录（含 `dataSnapshot`、已生成的论文、标题、数据范围等）**从数据库物理删除，快照一并清除，无残留、无回收站**。 - 删除项目**只删这份副本，不会动数据库中学生真实的对话、作业、报告**等原始教学数据。 #### 想用新数据生成论文怎么办 - 由于重新生成仍用旧快照，若希望论文反映**最新的教学数据**，请**新建一个研究项目**（新建时会重新扫描数据库抓取最新数据），而不是在旧项目上重新生成。 --- ### 2.11 系统配置 进入「系统设置」页面，包含以下配置： #### AI 服务配置 | 配置项 | 说明 | |--------|------| | API Base URL | AI 服务地址，支持 OpenAI 兼容接口（通义千问、DeepSeek、智谱等） | | API Key | API 密钥，仅存储在本地数据库 | | AI 模型 | 模型名称，如 qwen-turbo、deepseek-chat | | 推理思考模式 | 仅 DeepSeek V4 系列支持，返回推理过程 | | AI 并发限制 | 同时处理的 AI 请求数，小班 10-20、中班 20-40、大班 40-100 | | 测试连接 | 验证 AI 服务是否可用 | > **AI 输出上限**：系统所有 AI 调用（学情分析报告、互动探究 HTML 生成、AI 论文写作、AI 对话与伴学等）统一设置单次输出上限为 **64K tokens（65536）**。请确保所选模型支持 64K 输出长度（qwen、deepseek、agnes 等主流模型均支持）；若所接网关输出上限低于 64K，长报告可能被截断甚至输出为空。 #### 用户信息设置 - 修改单位（学校） - 设置老师座右铭（显示在工作台） - 设置学生座右铭（统一显示在所有学生端） - 修改密码 #### 学情洞察配置 | 配置项 | 说明 | |--------|------| | 启动指数评价 | 开启后学生分析只输出星级评分（6-10 星），不显示文字 | | 个人分析字数上限 | 建议 100-5000 字，留空不限 | | 班级分析字数上限 | 建议 200-10000 字，留空不限 | #### 配置备份与导入 - 可导出当前配置为 JSON 文件 - 可导入 JSON 配置文件恢复设置 --- ### 2.13 教学手册与学习手册导出 教师端可为每个课堂一键导出两份 Word 手册，面向对象和用途完全不同： | 手册 | 按钮 | 文件名 | 面向对象 | 是否含答案 | |------|------|--------|----------|-----------| | 教学手册 | 导出手册 | `{课堂名}_教学手册.docx` | 教师（备课 / 教研 / 存档） | 含 | | 学习手册 | 导出学习手册 | `{课堂名}_学习手册.docx` | 学生（学案，可直接打印） | 不含 | **入口**：「课堂管理」页面 → 目标课堂卡片上的按钮（鼠标悬停显示「导出手册」「导出学习手册」）。 #### 教学手册（教师教案） 按 30 分钟课时组织，结构如下： - **封面**：教师姓名、单位、年级、学科、来源 - **一、教学目标**：按学科核心素养逐条列出具体目标 - **二、教学活动**：每个活动含活动目标、活动内容、教师指导、学生反馈应对、QuickClass 操作指导，并附活动之间的过渡语 - **三、课堂作业设计**：逐题列出题目内容、选项、答案与解析 - **四、教学反思**：课后自评记录框架 - **五、备用活动**：超出 30 分钟限时的活动自动移入此节，课时充裕时选用 适用于公开课教案、教研存档、校内分享、代课交接。 #### 学习手册（学生学案） 只收录**学生端可见且已启用**的活动，结构如下： - **封面**：班级 / 姓名 / 日期填写栏 - **一、我的学习目标**：逐条列出，供学生自评 - **二、课堂任务单**：对话 / 探究 / 作业 / 项目，每项带勾选框、学生要做的事与提示 - **三、随堂练习**：课堂作业题目 + 作答区，**不含参考答案**（答案由课堂讲解或平台反馈给出） - **四、我的学习小结**：自评填空 - **附录：本课知识点**：课堂引用的知识库与教学内容合并整理 空章节会自动跳过（如本课无作业则不出现「随堂练习」），导出后可直接打印发给学生。 > **注意**：学习手册只导出**已生效的作业**以及**已启用的对话、探究、项目**。某项活动未发布就不会出现在学案里，导出前请先确认活动状态。 --- ### 2.14 图片仓库管理 图片仓库用于存放教学图片，按「图片组」组织。被课堂引用后，学生在该课堂的 AI 对话与 AI 伴学中，AI 会根据学生问题与图片描述的匹配度，智能发送组内图片。 #### 新建图片组 1. 进入左侧菜单「图片仓库」页面 2. 点击「新建图片组」 3. 填写图片组名称（如「分数教学图组」），可填使用场景说明 4. 创建后点击「管理图片」上传图片 #### 上传图片 1. 打开图片组的「管理图片」对话框 2. 点击「上传图片」，选择本地图片（支持 jpg / png / gif / webp，单张不超过 10MB） 3. 上传时 AI 会自动生成图片描述；若当前 AI 模型不支持看图，则需手动填写描述 > **图片描述是 AI 判断何时发图的核心依据**：描述应准确说明图中展示的知识点/概念与关键视觉元素，AI 据此判断学生在讨论什么话题时适合展示此图。 #### 编辑描述 - 在「管理图片」中直接修改图片描述，失焦自动保存 - 描述不准确的图片，AI 无法在合适时机发送 #### 启用/禁用 - 禁用的图片组不会出现在课堂引用列表中 - 已引用该图片组的课堂，组被禁用后对话将不再发送组内图片 #### 删除 - 删除图片组会级联删除组内全部图片及磁盘文件，并提示被哪些课堂引用 - 单张图片可在「管理图片」中逐张删除 #### 在课堂中引用 1. 创建或编辑课堂时，在「引用图片组（选填）」区域勾选目标图片组 2. 可同时引用多个 3. 保存后，学生在该课堂的 AI 对话 / AI 伴学中，会由 AI 根据问题相关性智能发送组内图片 #### 学生端发图机制 - AI **不是随机发图**，而是「仅在图片与学生当前问题相关时才发送」 - 发图前后 AI 会用一两句话自然衔接，图片以 Markdown 图片语法渲染 - 想验证发图效果：用与图片描述高度相关的问题提问（如图片描述为「分数概念示意图」，就问「什么是分数、分子分母怎么理解」） --- ### 2.15 AI 示意图（Mermaid） 学生对话与 AI 伴学中，AI 除了推送图片仓库里的图片，还能**现画示意图**——讲解流程、关系、结构类内容时，用 Mermaid 代码块直接生成流程图、思维导图、时间轴、状态转换图等，无需任何外部图片素材。 #### 怎么触发 - **AI 自动判断**：当回答涉及流程、因果、层级结构、状态变化等内容时，AI 会主动配图，学生无需开口要求 - 学生也可以直接说「画个流程图」「给我画个思维导图」，AI 同样会响应 #### 学生端体验 AI 输出的示意图会以图形化方式直接渲染在对话里，学生看到的是清晰的图表，而非代码；渲染失败时自动回退为普通文本，不影响对话。 #### 适用场景 | 场景 | 示例 | |------|------| | 流程图 | 实验步骤、解题流程 | | 思维导图 | 知识点归纳、单元复习 | | 时间轴 | 历史事件、化学反应进程 | | 状态转换 | 物理状态变化、生物循环 | > **说明**：示意图由 AI 根据讲解内容按需生成，教师无需预先准备图片素材。与图片仓库不同，Mermaid 是「AI 现画」而非「从仓库推送」。 --- ## 3. 学生端 ### 3.1 登录与加入班级 #### 加入班级 1. 浏览器访问 `http://教师IP:3000/student` 2. 输入教师提供的**邀请码** 3. 输入姓名 4. 点击「加入」 系统会自动创建账号并加入对应班级。 #### 登录 - 已有账号的学生，输入**姓名或学号** + 密码登录 - 无密码的学生，输入姓名和邀请码登录 > **提示**：学号请按「班级代码 + 序号」组合编码（如 `0101` = 一班 1 号，详见 2.2 节学号编码规范），不要使用 `1`、`2`、`3` 等简单数字——跨班学号重复时，登录需先选择班级。 --- ### 3.2 对话活动学习 1. 登录后进入对话页面 2. 左侧显示当前课堂和对话活动列表 3. 点击对话活动名称，开始与 AI 对话 4. 对话内容会被记录，教师可查看和分析 --- ### 3.3 互动探究 1. 在对话页面右侧，点击「互动探究」标签 2. 选择探究活动 3. 在 HTML 交互界面中完成学习任务 4. 点击「提交」提交探究结果 --- ### 3.4 项目提交 「项目提交」与对话、互动探究、作业并列，位于课堂内。学生进入课堂后点「项目提交」查看教师布置的任务。 #### 提交与编辑自己的项目 1. 进入课堂，点击「项目提交」标签 2. 选择某一项任务，查看教师要求（类别、大小限制） 3. 点击「提交」，填写标题与说明，按类别上传**一个文件**（文本类 doc/pdf，图片类 jpg/png，音视频类 mp4 等） 4. 已提交后可编辑、删除、重新提交自己的项目 5. 附件：图片/视频直接预览，文本类下载 6. 可看到自己提交被「置顶」或「下架」的状态提示 #### 互看与点赞 - 若任务全班可见：可看到本班其他同学的项目，并看到各项目点赞数 - 若任务允许点赞：可给他人项目点赞/取消点赞（不可给自己点） - 被下架的项目不显示在他人列表中（仅自己和教师可见） - 范围仅限本课堂本班，不跨班 --- ### 3.5 课堂作业答题 1. 在对话页面右侧，点击「课堂作业」标签 2. 选择要完成的作业 3. 逐题作答，提交后自动批改 4. 可查看得分和正确答案 --- ### 3.6 我的学情分析 1. 登录后，点击顶部的「学情分析」 2. 查看教师在课堂层级为该学生生成的个人学情分析报告 > **说明**：学生端展示的学情分析是**课堂层级**的个人综合分析，涵盖该课堂下所有对话活动、作业和探究的数据，而非单个对话活动的分析。对话活动层级的分析仅供教师在管理端查看。 --- ## 4. 常见问题 ### Q: 学生用学号登录时要求选择班级？ 说明不同班级存在相同学号（如各班都用了 `1`、`2`、`3` 这类简单序号），系统无法确定登录哪个账号，需学生选择自己的班级。建议按「班级代码 + 序号」规范重新编码学号（如 `0101` = 一班 1 号，见 2.2 节），即可直接登录。 ### Q: 学生看不到课堂？ 检查以下几点： 1. 课堂状态是否为「已启用」 2. 课堂是否分配到了学生所在的班级 3. 对话活动是否已启用 ### Q: AI 对话无响应？ 1. 检查系统设置中的 AI 服务配置是否正确 2. 点击「测试连接」验证 AI 服务可用性 3. 检查 API Key 是否有效 4. 检查网络连接 ### Q: 安卓平板朗读无声 / 提示「没有可调用的中文音色」？ **原因**：网页语音朗读（浏览器 `speechSynthesis`）本身不合成声音，而是调用安卓系统里的**文字转语音（TTS）引擎**。国产平板出厂时往往精简掉了自带的中文 TTS 引擎，或没有下载中文语音数据，所以浏览器枚举不到任何中文音色，点朗读就没声。 **解决：安装离线中文 TTS 引擎 RHVoice（开源免费，推荐）** 1. 平板浏览器访问 **rhvoice.com**，下载 **Android 版 APK** 并安装 2. 打开 RHVoice，在语言列表中选择**中文 / 普通话**，下载对应的中文语音包 3. 进入 平板系统设置 → 无障碍 / 系统 → **文字转语音（TTS）输出**，把「默认引擎」切换为 **RHVoice** 4. 回到 QuickClass 学生页刷新，再点朗读即可发声 > **说明**：先检查平板是否已有自带引擎（如小米小爱 / 华为小艺语音），若只是缺少中文数据，直接在系统 TTS 设置里「安装语音数据」下载中文包即可，无需另装软件。 > **验证**：装好并设为默认后，可在浏览器控制台执行 `speechSynthesis.getVoices().filter(v => v.lang.startsWith('zh'))`，若返回结果且 `localService === true`，即表示本地中文离线音色可用。 ### Q: 学情分析生成失败？ 1. 确保学生已有对话记录或答题数据 2. 检查 AI 服务是否正常 3. 检查分析提示词是否为空 ### Q: 保存对话活动后，之前的对话记录丢失关联？ 此问题已在最新版本中修复。保存对话活动时，系统会自动保留学生对话记录与对话活动的关联。 ### Q: 如何重置数据库？ ```bash npx prisma db push --force-reset npx tsx prisma/seed-full.ts ``` > **警告**：此操作会删除所有数据，不可恢复！ --- ## 5. WorkBuddy 技能支持 WorkBuddy 是 AI 助手平台，其技能市场提供 QuickClass 专用技能，能把现成的教案、试卷直接转成 QuickClass 可导入的 JSON，省去逐条录入的功夫。 ### 5.1 可用技能 | 技能 | 输入 | 输出 | |------|------|------| | QuickClass 课堂转换器 | 教案 / 学习材料（Word、PDF、图片） | 完整课堂 JSON（对话活动 + 课堂作业 + 互动探究 + 项目提交 + 知识库） | | QuickClass 作业转换器 | 试卷（Word、PDF、图片） | 课堂作业 JSON（题目） | ### 5.2 安装与启用 1. 打开 WorkBuddy 左侧「专家 · 技能 · 连接器」 2. 在技能市场搜索 `QuickClass` 3. 点开技能卡片按提示安装 4. 在「我安装的」里确认技能在列，卡片右上角开关变绿即为启用 ### 5.3 调用方式 在 WorkBuddy 对话中直接 @ 技能并附上文件： ``` @skill:"QuickClass课堂转换器" @"D:/work/Quickclass/北京的春节教案.docx" ``` 也可在新建任务时，从「技能」列表中直接选中。 ### 5.4 课堂转换器会做什么 | 步骤 | 技能做的事 | 教案变成什么 | |------|-----------|-------------| | ① | 读取教案，提取课题、年级、学科、目标 | 课堂顶层信息 | | ② | 把教学环节拆成「导入 / 新授 / 练习总结」 | 2-3 个对话活动 | | ③ | 提取练习题并识别题型 | 课堂作业（单选 / 多选 / 判断） | | ④ | 识别探究任务或 HTML 资源 | 互动探究活动 | | ⑤ | 识别作品提交要求 | 项目提交配置 | | ⑥ | 封装知识库 + 学情分析提示词 | 完整课堂 JSON | 生成的 JSON 按规范命名，导入时能自动识别： ``` {教师}_{年级}_{学科}_{课堂标题}_{日期}_课堂.json ``` ### 5.5 导入 QuickClass 教师端 → **课堂管理** → 页面上方「**导入课堂**」→ 选择 JSON 文件。 > **别点错**：「导入作业」在课堂作业区域，「导入课堂」在课堂列表区域，两者不是一回事。 导入后课堂处于停用、作业处于未生效状态，检查无误后手动启用即可（详见 2.7 节）。 ### 5.6 三种使用姿势 - **教案进课堂**：已有现成教案，直接交给技能，几分钟得到完整课堂 JSON - **从零搭一节课**：没有教案时，告诉技能「X 年级 X 学科《课题》」，它会通过对话收集教材版本、核心知识点、能力侧重、学生水平等再生成。**务必说明教材版本**，不同版本知识点顺序与术语差异很大 - **改造旧课**：只有旧作业 JSON 时，把原教案交给技能，可补齐对话、探究、项目提交 ### 5.7 配套：导出教学手册与学习手册 课堂导入并调整好后，可在课堂管理页一键导出 Word 手册（见 2.13 节）： - **教学手册**：自己备课、教研存档、公开课教案 - **学习手册**：直接打印发给学生当学案 ### 5.8 注意事项 - AI 负责把教案「翻译」成结构，但**学科正确性、题目质量、探究难度必须教师亲自把关** - 导入后先自己走一遍：对话活动开场白是否场景化、作业题目数量与正确答案、探究 HTML 是否正常显示 - 课堂作业仅支持单选、多选、判断三种题型（见 2.6 节）