QuickClass Agent · 宁创教学智能体 完整使用指南

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 位）：

这样编码后，学号在全校范围内天然唯一，学生凭「学号 + 密码」即可直接登录。班级较多或班额较大时可按需扩展位数，核心原则是：编码中包含班级属性，保证不与其他班的学号重复。

提示：若历史上已存在跨班重复学号，学生仍可登录——密码验证通过后系统会弹出班级列表，由学生选择自己的班级完成。但按上述规范编码可避免这一步。

课堂状态

2.3 对话活动管理

对话活动是学生与 AI 进行主题对话的核心载体。

编辑对话活动

1. 在课堂列表中展开目标课堂
2. 点击「活动管理」进入编辑模式
3. 可添加、编辑、删除对话活动

对话活动字段说明

启用/禁用对话活动

• 在课堂列表中，每个对话活动旁有开关按钮
• 禁用后学生端不再显示该对话活动
• 已有的学生对话记录不会删除

排序

• 使用上下箭头按钮调整对话活动顺序
• 学生端按此顺序显示

2.4 互动探究管理

互动探究是 HTML 交互式学习活动，支持学生操作和提交。

创建探究活动

1. 在课堂展开区域，点击「互动探究」面板
2. 点击「新建探究」
3. 填写标题、描述
4. 编辑 HTML 交互内容（支持直接编辑 HTML 代码）

AI 生成题目

1. 编辑探究内容后，点击「AI 生成题目」
2. 系统根据探究内容自动生成 4 道题目（1 单选 + 1 多选 + 1 填空 + 1 简答）
3. 生成后可手动调整

注意：已有学生提交后，点击「编辑」会提示「已有学生提交，请清除后编辑！」。清除方法见下方「编辑限制」。

提交功能

• 「启用提交」开关开启后，学生端页面左下角出现红色「提交」按钮
• 开启时系统自动分析页面，判定采集类别：有无评分环节（分数 / 闯关 / 对错）、有无可填控件（输入框 / 下拉框 / 文本域）、有无画布；无评分的页面不采分数，不会编造
• 若页面尚未接入采集（常见于导入的旧页面），开启提交时会自动进行「AI 接入采集」——在代码中插入上报调用，不改变任何视觉与交互
• 探究列表中显示「✓ 已接入采集 / △ 未接入采集」标记

数据采集机制（双轨）

学生点击「提交」时，系统同时采集两类数据：

完整教程：从 AI 生成交互页面、设计采集字段，到大屏生成、排布与常见问题排查，见文末 第 6 章「数据采集与大屏制作教程」。

AI 接入采集（自动补充采集）

导入的旧页面（或尚未接入采集的页面）往往没有上报代码，学生操作的关键数据——分数、关卡、滑杆最终值、开关状态、结论文字等——会漏采。开启「启用提交」时，系统会自动用 AI 分析页面，把需要采集的数据自动接入采集通道，全程不改变页面任何视觉、交互与文案。探究列表里的「✓ 已接入采集 / △ 未接入采集」标记显示的就是这个状态。

AI 先判断页面形态，再按形态接入：

注意：纯交互 / 探索型页面没有分数和答题，AI 不会虚构分数或答案，只采集页面里真实存在的关键状态。

示例：导入一个「单摆实验」旧页面——只有滑块调摆长、一个「开始摆动」按钮，没有表单、没有计分。开启「启用提交」时 AI 自动接入后：

• 学生拖动「摆长」滑块到 50cm → 采集到 摆长: 50
• 学生点「开始摆动」观察 → 采集到 完成环节: ["开始实验"]
• 学生在观察结论里写下「摆长越长周期越长」→ 采集到 我的发现: "摆长越长周期越长"
• 这些数据会像表单答案一样进入「统计信息」数据大屏与「提交详情 → 收集数据」，无需手写任何代码

若 AI 接入失败（网络等原因），系统会降级为基础采集（时长 / 操作 / 滚动），分数、关卡、作答暂无法上报，但页面仍可正常提交；此时探究列表保留「△ 未接入采集」标记，可再点一次重试。

如何把交互结果保存在表单框中（HTML 编写要点）

页面中的标准表单控件会被自动采集，无需额外代码：

1. 放置控件：文本框 / 下拉框 / 文本域 / 单选 / 多选（<input>、<select>、<textarea>）
2. 给控件配上题目文本，提交时以题目文本作为字段名。识别优先级：
   • aria-label / data-label / title 属性
   • <label for="控件id">题目</label>
   • 包裹控件的 <label>
   • 控件前方 40 字以内的短文本（如 <p>我的发现：</p><textarea>）
   • name / placeholder 属性
   • 都没有时按「字段1、字段2…」编号
3. 单选 / 多选按 name 分组，提交的是选中项的文字
4. 不想采集的控件加 data-qf-skip 属性（隐藏域、按钮、禁用控件本身就不采）
5. 学生提交自动带上姓名与学号（页面未让填时用登录账号兜底）；同一学生重复提交会覆盖旧记录（一人一条）

示例——学生填写的「我的发现」与掌握程度会自动进入数据大屏：

<p>我的发现：</p>
<textarea aria-label="我的发现" style="width:100%;height:80px"></textarea>

<p>我觉得这个知识点：</p>
<label><input type="radio" name="level"> 已掌握</label>
<label><input type="radio" name="level"> 需巩固</label>

游戏 / 练习型页面（有分数、关卡）与纯交互 / 探索型页面（模拟实验、拖拽观察等，无表单无分数）：这类页面没有标准表单控件，需要采集的数据（得分、关卡、滑杆最终值、开关状态、结论文字等）由「AI 接入采集」自动接入上报通道，无需手写代码，详见上一节。

查看采集数据

1. 探究卡片上点击「分析」（绿色按钮，开启提交后显示），进入独立分析页
2. 分析页顶部有三大页签——统计信息、提交详情、AI 分析报告，右上角是「刷新」按钮（旁有「最后更新」时间；多班级时还有班级下拉框）

右上角「刷新」按钮

作用：轻量重拉最新提交列表与 QuickForm 收集记录，不整页加载。

操作步骤： 1. 学生陆续提交后，回到分析页 2. 点击右上角「刷新」按钮，按钮短暂转圈后，「最后更新」时间更新为当前时刻 3. 下方三大页签的数据同步变为最新

自动触发：切换页签、切换班级下拉框时也会自动刷新对应班级的提交 / 数据大屏 / 提交详情，无需手动点。

示例：上完课学生当场提交探究，你在大屏投屏。等大家交得差不多时点一下「刷新」→ 大屏上的柱状图、名单、KPI 数字立刻更新到最新，不用退出页面重进。

「统计信息」页签（数据大屏）

默认大屏（零 AI、秒开）：学生表单答案自动成图——数值→柱状图、选项→饼图 / 横条、姓名 / 学号直接列名单，顶部是「已提交 / 收集字段 / 名单人数 / 最近提交」四张 KPI 卡。

「AI 重排大屏 / AI 重新排布」按钮：让 AI 重新挑选字段、图型与强调色。

操作步骤： 1. 在按钮旁的输入框写自定义要求（可留空，留空则 AI 自动挑重点） 2. 点击「AI 重排大屏」按钮 3. 等待数秒，AI 生成图表配置并落库缓存，提示「已按 AI 配置重排大屏」 4. 之后每次打开都按此配置渲染；按钮变为「AI 重新排布」，旁边出现「恢复默认」按钮 5. 点「恢复默认」即可回到默认大屏

自定义要求示例：

KPI 提示：描述指标时用「平均 / 最高 / 最低 / 总和 / 提交人数 / 去重」等词，AI 会精准兑现——「平均」→ 均值、「最高」→ 最大值、「提交人数」→ 提交总人数、「去重」→ 去重计数。

布局提示（几行几列）：图表按栅格排列，「一行放 N 个」控制一行几列（可选 2 / 3 / 4），「通栏」让某张图占满整行做主视觉（最多 1 个通栏）。字段少（≤3 个）默认 2 列、中等（4~6 个）3~4 列；姓名 / 学号名单始终通栏展示。

安全说明：AI 只产出图表配置 JSON（不产出 HTML），前端按配置渲染，避免脚本注入风险。

采集数据如何展示（图型对照）

无论表单是「题目 + 总分」，还是投票、量表、接龙、模拟实验等任意形式，大屏都按字段名驱动：字段下拉 = 收集到的所有字段名 + 「提交时间」，画什么图由「字段值是数字还是文本」决定，跟字段本身是不是”题”无关。

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 汇总全班学生的对话数据，生成整体分析报告
• 报告包含两种呈现形式：
  • 文本分析：结构化的文字报告，包含班级整体掌握情况、共性问题、教学建议
  • HTML 大屏分析：可视化数据大屏，适合课堂投屏展示，包含：
    • 班级整体掌握度雷达图
    • 各知识点理解程度柱状图
    • 学生分布散点图
    • 关键指标统计卡片
• 支持多版本管理，可对比不同时间点的分析结果

互动探究分析

基于学生的探究提交数据（操作记录、得分、用时等），分析探究学习效果。

个人分析

• 选择具体学生，查看其探究提交详情：
  • 操作过程和交互记录
  • 得分和完成情况
  • AI 生成的个人学习建议
• 支持查看学生的操作日志（点击、滚动、输入等行为）

全班分析

• 汇总全班探究提交数据，生成整体分析
• 报告包含两种呈现形式：
  • 文本分析：全班探究完成率、平均得分、得分分布、共性问题、教学建议
  • HTML 大屏分析：可视化展示：
    • 完成率和参与度统计
    • 得分分布直方图
    • 各探究环节完成情况热力图
    • 典型问题和高频错误分析
• 支持多版本管理和版本对比

作业分析

基于学生的作业答题数据，分析知识掌握情况。

个人分析

• 选择具体学生，查看其答题详情：
  • 各题答题情况和正误
  • 总分和各题型得分
  • AI 生成的错题分析和学习建议
• 支持查看学生的具体答案和批改结果

全班分析

• 汇总全班答题数据，生成整体分析
• 报告包含两种呈现形式：
  • 文本分析：全班正确率、平均分、得分分布、典型错误、教学建议
  • HTML 大屏分析：可视化展示：
    • 各题正确率柱状图
    • 得分分布直方图
    • 选项选择分布饼图
    • 高频错误和知识点薄弱环节分析
• 支持多版本管理和版本对比

分析提示词模板

• 系统内置多种分析提示词模板
• 教师可自定义模板，控制分析报告的格式和侧重点
• 支持 AI 自动生成提示词
• 发送前可预览完整 Prompt，确认后执行

进阶定制：想自定义分析报告的维度、等级标准与图表板块，请阅读《教师模板修改指南》。

2.11 系统配置

进入「系统设置」页面，包含以下配置：

AI 服务配置

AI 输出上限：系统所有 AI 调用（学情分析报告、互动探究 HTML 生成、AI 论文写作、AI 对话与伴学等）统一设置单次输出上限为 64K tokens（65536）。请确保所选模型支持 64K 输出长度（qwen、deepseek、agnes 等主流模型均支持）；若所接网关输出上限低于 64K，长报告可能被截断甚至输出为空。

用户信息设置

• 修改单位（学校）
• 设置老师座右铭（显示在工作台）
• 设置学生座右铭（统一显示在所有学生端）
• 修改密码

学情洞察配置

配置备份与导入

• 可导出当前配置为 JSON 文件
• 可导入 JSON 配置文件恢复设置

2.12 教学研究（AI 论文生成）

教学研究功能基于课堂数据（学生对话、课堂作业、学情分析报告）一键生成研究论文。其底层采用数据快照机制，理解以下两点有助于正确使用：

数据快照（冻结机制）

• 创建研究项目时，系统会实时扫描数据库，把所选的对话、作业、报告一次性打包成一份 JSON 快照，存入该项目记录中（字段名为 dataSnapshot）。
• 快照是原始教学数据的独立副本，而非实时引用。因此：
  • 你对数据库里学生对话、作业的后续增删改，不会影响已创建的研究项目。
  • 即使你删除了全部对话记录，已生成或重新生成的论文仍基于创建时冻结的那份快照（例如论文里仍会引用创建时统计到的”216 条对话”）。
• 重新生成论文：读取的是该项目创建时冻结的快照，不会回去重新扫描数据库。论文因此可复现——删除/改动学生数据不会让旧研究跟着变。

删除即删除快照

• 删除研究项目时，整条项目记录（含 dataSnapshot、已生成的论文、标题、数据范围等）从数据库物理删除，快照一并清除，无残留、无回收站。
• 删除项目只删这份副本，不会动数据库中学生真实的对话、作业、报告等原始教学数据。

想用新数据生成论文怎么办

• 由于重新生成仍用旧快照，若希望论文反映最新的教学数据，请新建一个研究项目（新建时会重新扫描数据库抓取最新数据），而不是在旧项目上重新生成。

2.13 教学手册与学习手册导出

教师端可为每个课堂一键导出两份 Word 手册，面向对象和用途完全不同：

入口：「课堂管理」页面 → 目标课堂卡片上的按钮（鼠标悬停显示「导出手册」「导出学习手册」）。

教学手册（教师教案）

按 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: 如何重置数据库？

npx prisma db push --force-reset
npx tsx prisma/seed-full.ts

警告：此操作会删除所有数据，不可恢复！

5. WorkBuddy 技能支持

WorkBuddy 是 AI 助手平台，其技能市场提供 QuickClass 专用技能，能把现成的教案、试卷直接转成 QuickClass 可导入的 JSON，省去逐条录入的功夫。

5.1 可用技能

5.2 安装与启用

1. 打开 WorkBuddy 左侧「专家 · 技能 · 连接器」
2. 在技能市场搜索 QuickClass
3. 点开技能卡片按提示安装
4. 在「我安装的」里确认技能在列，卡片右上角开关变绿即为启用

5.3 调用方式

在 WorkBuddy 对话中直接 @ 技能并附上文件：

@skill:"QuickClass课堂转换器" @"D:/work/Quickclass/北京的春节教案.docx"

也可在新建任务时，从「技能」列表中直接选中。

5.4 课堂转换器会做什么

生成的 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 节）

6. 数据采集与大屏制作教程

本教程讲解互动探究中”数据采集 → 数据统计 → 数据大屏展示”的完整流程：如何用 AI 生成学生作答的交互页面、如何设计字段才能采集到可统计的数据、如何把数据排布成一块好看的课堂大屏（含 9 类图示的选用与布局规则）。是 2.4 节采集功能的展开说明。

全流程总览

① 设置交互页面          ② 开启提交           ③ 生成数据大屏
（AI 对话生成网页）  →  （学生登录作答）  →  （一键 AI 生成 / 手动微调）
     老师操作              学生操作              老师操作

第一步：设置交互页面

1.1 入口在哪里

进入老师端 「课堂管理」（课堂任务列表页），在任务里 新建 / 编辑探究，会打开一个 对话 + 预览 的弹窗：左边（或下方）是和 AI 的对话输入框，另一侧是页面预览与代码视图。

1.2 交互页面是怎么生成的

交互页面不是手动拖拽字段拼出来的，而是用自然语言让 AI 直接生成一个网页：

• 首轮：用一两句话描述你想要什么页面，AI 生成完整网页 + 预览；
• 多轮修改：继续对话说”把第 2 题改成下拉框”“加一个提交按钮”，AI 在原页面基础上改；
• AI 帮我写提示词：不知道怎么描述时点这个按钮——你已有想法它就帮你润色，没有想法它就根据课堂背景从零帮你设计。

生成的页面分两类，写提示词时可以先想清楚要哪类：

1.3 首轮提示词怎么写（举例）

反例（太笼统）：

做一个调查问卷。

正例（说清目的、内容、题型）：

做一个”睡眠情况小调查”表单页，包含： 1. 姓名（文本，必填） 2. 昨晚入睡时间点（数字，如 23.5 表示 23:30） 3. 昨晚睡眠时长（数字，小时） 4. 睡前最后一件事（单选：刷手机 / 阅读 / 运动 / 其他） 5. 常用助眠方法（多选，可空） 页面风格简洁、适合初中生，提交按钮放底部。

要点：目的 + 逐条字段 + 每个字段的题型 + 是否必填。写得越具体，AI 生成的表单越符合预期，后面的大屏也越好看。

更多可直接复制的完整示例（含自定义控件、模拟实验、游戏化闯关、画板创作），见本章末「附录：示例库」。

1.4 页面里怎么”确保采到数据”（先搞清两种”提交”）

⚠️ 系统里有两个”提交”，只有一个是真采集：

AI 生成的 HTML 里如果自带一个”提交”按钮，它只是页面的一部分，点了不会把数据传给系统（生成规范已禁止 AI 自己写上传逻辑）。学生真正要点击的是页面左下角的红色「提交」按钮（系统注入，浮在网页上）——它会把答案打包传给系统、落库、进入大屏统计。

对老师的影响就一条：数据能不能被采到，取决于页面有没有把答案”登记”好——

• 标准输入框、单选、下拉、文本域、多选：系统提交时自动采集，无需额外处理；
• 自定义控件（卡片选择、星级评分、拖拽连线、画板等）：需要 AI 按”数据上报规范”把结果同步到页面的状态对象（__gameState__.answers）。如果用了这类控件，在提示词里明确加一句：

请确保所有自定义控件（星级/卡片/拖拽等）的选择结果都实时同步到 gameState.answers，键名与题目一致。

其余照旧：

• 生成后自己先预览一遍：逐个填一遍、走完提交流程，确认没有漏采的字段；
• 表单里每个输入框（单选的每个选项、每个数字输入框）将来都会变成大屏上的一个字段，所以页面里放什么输入项，决定了大屏能展示什么——下一步的字段设计是整个流程的关键。

第二步：设计采集字段（决定大屏效果的关键）

2.1 先理解：系统是怎么”看”你的数据的

大屏 AI 并不会看学生的原始答卷，它拿到的是每个字段的统计摘要（条数、去重数、高频取值、最小/最大/平均等）。系统会把每个字段自动归入 4 种统计口径，大屏能画什么图完全由此决定：

⚠️ 注意分界线：选项字段取值 ≤ 8 种才算”选项”；超过 8 种就会被当成”文本”，只能出标签/词云，出不了饼图。所以单选题的选项数建议控制在 3~6 个。

2.2 字段设计六原则（每条都有正反例）

原则 1：能用选择题就不用填空题。

• ❌ 反例：请描述你平时的放松方式（自由文本）→ 50 个学生 50 种答案，只能出词云，看不出明确占比。
• ✅ 正例：放松方式（单选：听音乐 / 运动 / 刷视频 / 聊天 / 其他）→ 直接出环形图，占比一目了然。

原则 2：想要均值、最值、排行榜的字段，答案必须是纯数字。

• ❌ 反例：睡眠时长：填"8小时30分" → 文本，算不了平均。
• ✅ 正例：睡眠时长（小时），学生填 8.5 → 可出”平均睡眠 7.6 小时” KPI、排行榜、散点图。

原则 3：想做名单和排行榜，必须有”姓名/学号”标识字段。

• 排行榜需要两个东西：排名依据（数值字段） + 显示谁（姓名字段）。缺了姓名，分数排出来也不知道是谁。
• ✅ 正例：字段里保留 姓名 + 测验得分，大屏就能出”得分排行榜”。

原则 4：选项数 3~6 个最佳。

• 3~4 种取值 → 环形图最清晰；5 种以上 → 横向条形图；超过 8 种 → 退化为”文本”。
• ❌ 反例：单选”你来自哪个省”（30+ 选项）→ 出不了占比图。
• ✅ 正例：把大类归成 4~5 组再让学生选。

原则 5：字段名要短而明确，它就是 AI 选图、起标题的唯一线索。

• ❌ 反例：第3题：请问你平均每天使用手机的时间大约是多久？（单位：分钟）
• ✅ 正例：手机时长(分钟) —— AI 更容易选中它、起出”他们熬夜在干什么”这类好标题。

原则 6：想看”走势/变化”，就加日期或轮次字段。

• 想出折线图（如每天单词听写正确率的变化），需要在多天/多轮采集中带上 日期 或 第几天 字段。

2.3 字段类型 ↔︎ 图表速查表

每一行怎么从提示词走到图表，见「附录：示例库」里的 4 个端到端示例。

第三步：开启提交，学生作答

3.1 开启与入口

• 在探究设置里 开启提交，系统会自动给这个页面绑定一个采集任务；
• 学生用自己的账号登录学生端，在会话页打开探究面板作答（无需扫码，系统按登录人自动归属）。

3.2 再强调一次：学生要点哪个”提交”

• ✅ 点页面左下角的红色「提交」按钮（系统注入，浮在网页上）→ 数据落库，进入大屏；
• ❌ 点 AI 网页内部的”提交/完成”按钮 → 只是页面内交互，系统不采集；
• 提交成功后学生端会显示绿色”✓ 已提交”和提交时间——这是判断是否真正采集成功的标志；
• 未提交前答案留在页面里，中途关闭不会自动保存，重新进入需重填（标准表单控件的数据在点击「提交」那一刻才统一收集）。

3.3 三条重要规则

1. 一人一条：同一个学生对同一个页面重复提交时，会覆盖上一次的答案，不会重复计数——可以放心让学生”改了再交”。
2. 双轨记录：系统同时记录两份数据——学生在页面里的作答数据（用于大屏统计）和行为数据（提交时间等）。
3. 提交即锁定：只要有任何一个人提交过，这个探究的页面内容和”启用提交”开关就会被锁定——此时你再让 AI 改页面、保存，改动会被静默丢弃（界面看起来保存成功，实际没生效）。想改页面：先在老师端清除提交（测试期数据可直接清），改完再开放提交。这是刻意设计：学生交到一半换页面，前后数据就对不上了。

3.4 数据量与匿名

• 大屏统计时最多取最近 500 条提交计算字段摘要，日常班级规模完全够用；
• 摘要里只有统计数字，没有任何学生的原始答卷内容，大屏 AI 看不到具体某个学生填了什么。

第四步：生成数据大屏

4.1 入口

老师端进入 任务 → 探究 → 「统计信息」 页。数据大屏分两种：

• 默认大屏：系统按固定规则自动排布，开箱即用；
• AI 大屏：按你的要求智能选图、排版，支持后续自然语言修改（推荐）。

4.2 一键 AI 生成

点「AI 设计」，在输入框里可以只描述风格或重点，也可以什么都不填直接生成。

指令示例（口语化即可）：

用青色，突出平均睡眠时长，排行榜放第一个，睡前活动用饼图。

系统会自动做三件事：

1. 把”平均”“最高”“多少人”等口语翻译成硬性指标约束（如”平均分”→ 必须出现均值 KPI）；
2. 把每个字段的统计摘要 + 你的要求一起交给 AI 排版；
3. AI 输出的配置经过白名单校验后生效（AI 只能选系统允许的字段和图型，不会输出危险内容）。

4.3 自然语言修订（增量修改）

大屏生成后，继续用自然语言只改你想改的部分，其余卡片原样保留：

• 「把词云放大到整行」→ 只调整那张卡片的宽度；
• 「换成绿色，删掉标签列表」→ 本地直接执行，不耗 AI；
• 「把排行榜移到第二位」→ 本地直接执行；
• 「重新设计」→ 整屏重新排布（等同重新生成）。

4.4 手动编辑器（精确微调）

点「编辑」打开编辑器，每个控件的含义：

第五步：9 类图示详解（每类都有例子）

① 柱状图（bar） —— 各组数量高矮对比。例：各小组提交数量；“睡眠时长”数值分段后的分布。数值字段会被自动分段（约 6 档，如”7–8”“8–9”）；取值去重后 ≤ 10 种时按原值一值一柱，不做分段。

② 折线图（line） —— 随时间的变化趋势。例：连续 5 天”单词听写正确率”的走势；每轮测验平均分变化。

③ 条形图（hbar） —— 横向条形，选项多时比饼图清晰。例：最喜欢的科目（单选 6 种） 的占比；多选题各选项被选次数 Top 8。

④ 环形图（pie） —— 3~4 种取值的占比。例：睡前最后一件事（刷手机/阅读/运动/其他）；走读/住宿 比例。⚠️ 取值超过 4~5 种请改用条形图。

⑤ 名单（roster） —— 不做统计，就是”谁交了”的名单。例：今日作业已完成名单。永远整行通栏展示，无需设置宽度。

⑥ 标签列表（list） —— 自由文本的高频取值标签。例：“我的新年愿望”里出现最多的关键词及次数。

⑦ 排行榜（ranking） —— 按数值字段排名次。例：测验得分排行榜（按分数排，显示姓名）。需要”排序字段（数值）+ 显示字段（姓名）“两个都配好。⚠️ 涉及个体排名时注意课堂氛围，考虑是否匿名化（如用学号/昵称）。

⑧ 词云（wordcloud） —— 词越大出现越多。例：多选题”常用助眠方法”的视觉化；“用一个词形容今天这节课”。⚠️ 3~4 种取值的单选题优先用饼图/条形图，不要用词云。

⑨ 散点图（scatter） —— 看两组数值是否相关。例：练习时长 × 测验得分——点越靠右上，“练得久得分高”的关系越直观。需要两个不同的数值字段，可选配 hover 显示姓名。⚠️ 每个点 = 一个人的提交：至少要 2 人提交（且两人的 X/Y 字段都得是数字）才会出图——只有 1 条提交时卡片会直接隐藏（无任何提示），不是配置坏了。自己反复提交没用：同一人再提交只是替换自己的旧数据，点数不会变多。

第六步：排布设计

6.1 三个核心概念

1. KPI 行：大屏底部一行统计数字卡（提交人数、平均分等），固定一行 4 个位置，给 3~4 个最合适；
2. 每行列数：把一行切成 2 / 3 / 4 等份格子（全局设置）；
3. 卡片占几格（span）：每张图表卡横着占几个格子，占满即整行通栏（主视觉），最多 1 张通栏。

排布规则：从左到右放卡片，当前行的格子占满后自动换行；窗口宽度 ≥ 1024px 才按多列排布，更窄时自动变单列（手机/半屏兼容）。

6.2 三个完整布局示例

例 A · 课堂小调查（5 个字段，选项为主） 字段：姓名、放松方式（单选 5 项）、助眠方法（多选）、睡眠时长（数值）、新年愿望（文本）

每行列数 = 3
┌─────────────┬──────┬──────┐
│ 放松方式 hbar │ 助眠词云│ 睡眠柱状│
├─────────────┼──────┴──────┤
│ 新年愿望 list │  他们的睡眠  │
└─────────────┴─────────────┘
KPI：提交人数 42 ｜ 平均睡眠 7.6h ｜ 最多人选：刷视频

例 B · 随堂测验（分数场景，数值为主） 字段：姓名、测验得分、练习时长、错题数

每行列数 = 4
┌─────────────────────────────────┐
│        得分排行榜（通栏主视觉）      │
├────────┬────────┬───────┬───────┤
│ 得分柱状 │ 时长柱状 │ 错题环形│ 时长×得分│
└────────┴────────┴───────┴───────┘
KPI：提交人数 45 ｜ 平均分 82.3 ｜ 最高分 98 ｜ 总错题 56

例 C · 头脑风暴（文本为主）

每行列数 = 2
┌───────────────────┬───────────────────┐
│   一句话创意（词云）  │   高频关键词（标签列表）│
├───────────────────┴───────────────────┤
│            参与名单（通栏）              │
└───────────────────────────────────────┘
KPI：提交人数 40 ｜ 创意关键词 23 种

6.3 排布审美口诀

• 一张通栏 + 一群小卡：最重要的图占整行，其余小卡错落；
• 图型要混搭：柱、饼、条、词云交替，避免一屏全是同一种图；
• 6 张卡正好两行：每行 3 列时最整齐；每行 4 列适合”5~6 张 + 1 张通栏”的错落感；
• 图表卡片总数上限 12 张，超出的会被自动截断。

附录：示例库（提示词 → 网页 → 采集 → 大屏 全对照）

每个示例都按三段写成，保证三者对得上：提示词（可直接复制到 AI 对话框）→ 网页效果（学生看到什么、怎么操作）→ 采集与大屏效果（提交后采到哪些字段、每个字段在大屏上变成什么图）。

先记住一条总规律：

页面上的每个输入项/交互结果  =  一个采集字段
字段的数据形态              =  决定统计口径（数值/选项/多选/文本）
统计口径                    =  决定大屏能画什么图

示例 1 · 随堂小测：睡眠情况调查（表单型 · 标准控件）

提示词（可直接复制）：

做一个”睡眠情况小调查”表单页，包含： 1. 姓名（文本，必填） 2. 昨晚入睡时间点（数字，如 23.5 表示 23:30） 3. 昨晚睡眠时长（数字，小时，可填一位小数） 4. 睡前最后一件事（单选：刷手机 / 阅读 / 运动 / 其他） 5. 常用助眠方法（多选：听音乐 / 泡脚 / 看书 / 数羊 / 其他，可空） 页面风格简洁、适合初中生，提交按钮放底部。

网页效果： 学生打开就是一张卡片式表单——5 个输入项从上到下排开，第 4 题是四个圆点单选、第 5 题是五个方框多选，其余是输入框。逐项填写后点页面底部”提交”按钮（页面内的），最后点左下角红色「提交」交给系统。

采集与大屏效果（全程零附加设置，标准控件自动扫描）：

每行列数 = 3
┌─────────────┬──────┬──────┐
│ 睡前活动 环形 │ 助眠词云│ 时长柱状│
├─────────────┼──────┴──────┤
│ 提交名单(通栏) │ 入睡时间柱状  │
└─────────────┴─────────────┘
KPI：提交人数 42 ｜ 平均睡眠 7.6h ｜ 平均入睡 23.4 ｜ 最高 9.5h

对 AI 大屏说「用青色，突出平均睡眠，睡前活动用饼图」即可得到类似排版。

示例 2 · 探究型：单摆周期模拟实验（自定义控件 · 散点图）

提示词（可直接复制）：

做一个”单摆周期模拟实验”页： 1. 页面中央是一个单摆动画； 2. 学生用滑块调整摆长（0.2 米 ~ 2.5 米），点”开始摆动”后动画摆动并显示测得周期（秒）； 3. 下方让学生调 3 组不同摆长做实验，每组的结果自动记录到一张”实验记录表”里； 4. 最后一个文本框让学生填写”我发现摆长越长，周期______“的结论； 5. 请把最后一组测得的摆长（纯数字，米）、周期（纯数字，秒）和结论文字，实时同步到 gameState.answers，键名分别用”摆长(米)“、”周期(秒)“、”我的结论”。注意：answers 里每个键只能存一个数值或一段文字，不要存成数组，3 组明细只显示在记录表里即可。 页面是模拟实验，不需要计分。风格清爽，适合初中物理课。

网页效果： 学生看到的是一个可操作的实验台——拖动滑块改变摆长，动画里摆的长度跟着变；点”开始摆动”后显示”摆长 1.0 米 → 周期 2.0 秒”，同时记录表里新增一行。做完 3 组，填一句结论。

采集与大屏效果：

⚠️ 这是自定义控件的关键示例：滑块、记录表都不是标准表单控件，系统自动扫描扫不到——数据全靠提示词第 5 条里那句”同步到 gameState.answers”让 AI 写进页面代码。删掉这句，提交后这些字段就是空的。

每行列数 = 3
┌──────────────────────────────┐
│   摆长 × 周期 散点图（通栏主视觉） │
├──────────┬──────────┬────────┤
│ 摆长柱状  │ 周期柱状  │ 结论标签 │
└──────────┴──────────┴────────┘
KPI：实验人数 45 ｜ 平均摆长 1.2m ｜ 平均周期 2.2s

“页面是模拟实验，不需要计分”这句也有用：系统会按它关闭分数采集，老师端不会出现一列无意义的 0 分。

⚠️ 测试提醒：这里的散点图每个点对应一个学生的提交，至少 2 人提交才会显示。自己一个人测试时散点图不会出现（卡片直接隐藏，不留提示）——想先看到效果，用两个账号各提交一次即可。

示例 3 · 游戏化：古诗闯关练习（自定义控件 · 分数 + 多选）

提示词（可直接复制）：

做一个”古诗闯关”练习页，共 5 题单选（诗句填空、作者、朝代、意象各 1~2 题），逐题作答，答对得分、答错显示正确答案；做完显示总分和 1~3 星评价。计分逻辑同步到 gameState.score（满分 100）。 结束页加两个问题： 1. “这次闯关你觉得难在哪”（多选：朝代记混 / 意象理解难 / 作者记不住 / 审题失误）； 2. “给自己下次的建议”（一句话文本）。 请把星级（数值 1~3）、错题原因（数组）、我的建议（文本）实时同步到 gameState.answers，键名分别用”获得星级”、“困难原因”、“给我的建议”。

网页效果： 学生闯关式答题——每题一张卡片，选完立即反馈对错，页面上有得分跳动和进度条；通关后是结算页：总分、星级、两个复盘问题。

采集与大屏效果：

每行列数 = 4
┌─────────────────────────────────┐
│       古诗闯关排行榜（通栏主视觉）    │
├────────┬────────┬───────┬───────┤
│ 得分柱状 │ 星级环形 │ 难点词云│ 建议标签│
└────────┴────────┴───────┴───────┘
KPI：参与 45 人 ｜ 平均分 82.3 ｜ 最高分 100 ｜ 三星人数 28

闯关练习的”姓名”字段照常放在题目里（或直接用大屏排行榜的”显示字段”选提交人）；对比示例 2 会发现：游戏要 score，实验要 hasScoring 关闭——提示词里一句话就能切换。

示例 4 · 画板创作：轴对称图形设计（canvas 快照 · 能与不能）

提示词（可直接复制）：

做一个”轴对称图形设计”页： 1. 一块方格画板（canvas），提供直线/三角形/颜色选择工具，学生画出含 1 条对称轴的图形，有”撤销”和”清空”； 2. 画板下方两个表单项： - “我用的对称轴方向”（单选：竖直 / 水平 / 斜向）； - “作品名称”（一句话文本）； 3. 把这两个表单项的结果实时同步到 gameState.answers，键名用”对称轴方向”、“作品名称”。

网页效果： 学生在画板上画图（可用撤销/清空反复改），给作品起名，选一下对称轴方向。

采集与大屏效果——这个示例的重点是”能”与”不能”：

大屏（统计部分）：            老师端提交记录（看作品）：
┌──────────┬──────────┐    ┌─────────────────────┐
│ 方向 环形图 │ 名称标签列表 │    │ 张三 · 画板快照 ①      │
├──────────┴──────────┤    │ [图片]  作品名称:蝴蝶   │
│    参与名单（通栏）     │    │ 李四 · 画板快照 ①      │
└─────────────────────┘    │ [图片]  作品名称:小房子  │
                           └─────────────────────┘

通则：凡是”画/拼/搭”类创作任务，作品本身进不了大屏。想让这类任务也有大屏效果，就像本例一样在提示词里配 1~2 个统计字段（单选/文本），用”方法统计 + 参与名单”撑起大屏，作品图留到提交记录里逐个点评。

自定义控件采集三要素（示例 2/3/4 的共同规律）

1. 提示词里点名控件：写清”滑块 / 卡片选择 / 拖拽 / 画板”，让 AI 知道要造自定义控件；

2. 必加同步句（缺了它数据必丢）：

   请把……（字段列表）实时同步到 gameState.answers，键名分别用”XXX”、“YYY”。

3. 键名按”字段名”起：它就是大屏上图表的标题来源——用”摆长(米)“而不是”第 1 步的值”，用”困难原因”而不是”answer2”。

另外三条暗规则，示例里已用到：

• 数值答案保持纯数字，且一人都不能脏（示例 2 的”周期(秒)“存 2.0 而不是”2.0 秒”）。⚠️ 判定规则是全班所有答案都是数字才算数值字段——只要有一个学生填了”8.5小时”或”忘了填”，整个字段就掉进文本口径，均值 KPI、柱状分布、散点图全部作废（不是差一条数据，是整列全废）。页面上用 number 输入框/滑块能从源头杜绝；
• 一个键只能存一个值，禁止存数组：系统的落库规则是只收单个数字/文字，数组会被直接丢弃（不报错）。多组数据只能在页面记录表里展示，同步时只存最后一组或平均值——存了数组，字段会整个消失；
• 选项答案控制在 ≤8 种（示例 1 的 4 项、示例 3 的 4 项），超过会退化成文本，出不了占比图。

常见问题排查