OneBot × EduMind：QQ 机器人、RAG 与实时课堂整合实战

本文整合了 OpenClaw/OneBot 接入、QQ 作业提醒、RAG 问答以及实时课堂两轮迭代，以一条完整消息链路说明最终方案。

消息与教学数据链路

flowchart LR
    A["QQ / 课堂事件"] --> B["OneBot 适配层"]
    B --> C["身份与课程映射"]
    C --> D["课堂业务服务"]
    C --> E["RAG / Agent"]
    D --> F["通知编排"]
    E --> F
    F --> G["群消息"]
    F --> H["学生私聊"]
    D --> I["备课学情仪表盘"]

概述

本次迭代围绕课中互动 → 课后反馈 → 课前备课三个环节，打通了课堂直播系统与 OneBot QQ 机器人的消息推送，并新建了备课学情仪表盘与预习任务系统，形成”备课 → 上课 → 复盘”的完整闭环。

一、OneBot QQ × 课堂直播整合

已实现功能

功能	触发时机	推送方式
🔔 未答题提醒	互动关闭时（手动/倒计时）	QQ 私聊未作答学生 + 群内汇总
📊 课堂总结	教师结束课堂	群消息（互动数/正确率/MVP/缺席名单）+ 私聊缺席学生
📢 开课通知	教师创建课堂	群消息（课堂码 + 加入方式）
📖 预习任务推送	教师发布预习任务	群消息（主题 + 知识点）

技术实现

新建 LiveNotificationService，注入已有的 OneBotHttpService（调 NapCat HTTP API）和 StudentQqBindingMapper（学号 → QQ 号映射），在以下切面织入：

LiveSessionService.createSession()    → notifySessionStart()
InteractionService.closeInteraction() → notifyUnanswered()
LiveSessionService.endSession()       → notifySessionSummary()
PreviewTaskServiceImpl.createPreviewTask() → notifyPreviewTaskPublished()

所有 QQ 发送通过 WebClient.subscribe() 异步发出，不阻塞主流程。

二、备课学情仪表盘

数据聚合

PreLessonService 聚合四个维度数据：

维度	数据来源
作业概览	`DashboardService`（均分/需关注学生数）
课堂互动	`ClassroomSession` + `Interaction` + `InteractionResponse`
分层分组	A层(80-100) / B层(60-79) / C层(<60) 人数 + AI 策略建议
AI 备课建议	独立端点 `GET /api/dashboard/pre-lesson/suggestion`，手动触发

关键设计决策

AI 建议独立端点：原来放在主接口里，OpenClaw 调用耗时 ~10 秒，超过 axios 默认 10s 超时导致前端白屏。拆分为独立端点后，主数据秒返，AI 建议异步加载。
手动触发：不自动调用 AI，老师点击”🔄 AI 深度分析”按钮才发起请求，避免每次切页面浪费 token。

三、预习任务推送

数据模型

新建 preview_task 表，字段设计：

CREATE TABLE preview_task (
    id BIGINT PRIMARY KEY,
    class_id BIGINT NOT NULL,
    teacher_id BIGINT NOT NULL,
    title VARCHAR(200),
    knowledge_point VARCHAR(200),
    guide_text TEXT,           -- AI 导读材料（Markdown）
    questions_json JSONB,      -- 3道自测题 [{question, options, correctKey, explanation}]
    discussion_question TEXT,  -- 课堂讨论题
    status VARCHAR(20) DEFAULT 'ACTIVE',
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);

生成流程

教师输入知识点 → Prompt 工程 → OpenClaw 生成：
  ├─ guide：5分钟导读材料（问题引导式，Markdown）
  ├─ questions[]：3道自测题（选择题/简答题混排，含解析）
  └─ discussion：1道课堂讨论题
→ 保存入库 → OneBot QQ 群推送 → 学生端公开页面查看

学生端页面

公开路由 /preview/:taskId，无需登录。交互设计：

导读区：Markdown 渲染
自测区：选择题点击选项即显示正误 + 解析；简答题直接展示参考答案
讨论区：课堂讨论题（带思考提示）

四、备课页面功能补全

教学进度时间线

聚合三表数据按时间倒序展示：

数据源	图标
`classroom_session`	🎓 课堂互动
`homework_task`	📝 作业
`preview_task`	📖 预习任务

新增端点 GET /api/dashboard/timeline?classId=&limit=15，前端以竖线时间线组件展示。

一键教案大纲

复用已有的 POST /api/dashboard/teaching-plan/generate 端点（之前只有后端无前端），在备课页增加入口：

1	点击"📝 生成教案" → 勾选目标 → 自动取薄弱知识点 → 生成 → 弹窗展示 + 📋 复制

五、文件清单

新增文件（11 个）

文件	说明
`live/service/LiveNotificationService.java`	OneBot 通知服务
`Service/PreLessonService.java`	备课学情接口
`Service/ServiceImpl/PreLessonServiceImpl.java`	备课学情实现
`Service/TimelineService.java`	时间线接口
`Service/ServiceImpl/TimelineServiceImpl.java`	时间线实现
`Entity/PreviewTask.java`	预习任务实体
`DTO/PreLessonDTO.java`	备课学情 DTO
`DTO/PreviewTaskDTO.java`	预习任务 DTO
`DTO/CreatePreviewRequest.java`	创建预习请求 DTO
`DTO/TimelineDTO.java`	时间线 DTO
`mapper/PreviewTaskMapper.java`	预习任务 Mapper
`Controller/PreviewTaskController.java`	预习任务控制器
`db/migration/V4__preview_task.sql`	预习任务表迁移
`vue-project/src/views/teacher/PreLessonDashboard.vue`	备课仪表盘页面
`vue-project/src/views/teacher/PreviewTaskCreate.vue`	预习任务创建页
`vue-project/src/views/PreviewTaskView.vue`	学生预习查看页
`vue-project/src/api/preview.ts`	预习任务 API

修改文件（5 个）

文件	改动
`InteractionService.java`	关闭互动后调用 `notifyUnanswered()`
`LiveSessionService.java`	创建/结束时调用通知
`DashboardController.java`	新增 pre-lesson / timeline / suggestion 端点
`SecurityConfig.java`	`/api/preview/**` 加入公开路径
`vue-project/src/App.vue`	侧边栏新增”备课仪表盘”入口
`vue-project/src/router/index.ts`	新增 3 条路由
`vue-project/src/api/dashboard.ts`	新增 pre-lesson / timeline / suggestion API

六、架构总览

                    ┌──────────────────────┐
                    │     OneBot QQ Bot     │
                    │   (NapCat HTTP API)   │
                    └──────────┬───────────┘
                               │ sendPrivateMessage / sendGroupMessage
                               │
┌─────────────┐     ┌──────────▼──────────┐     ┌─────────────┐
│ 课堂直播系统  │────▶│ LiveNotificationService │◀────│ 预习任务系统  │
│  - 开课/结课  │     │                      │     │  - AI 生成   │
│  - 互动关闭   │     └──────────────────────┘     │  - 学生查看   │
└─────────────┘                                   └─────────────┘
       │                                                  │
       ▼                                                  ▼
┌──────────────────────────────────────────────────────────┐
│                    备课学情仪表盘                          │
│  PreLessonService ←→ DashboardService + 互动数据 + AI    │
│  TimelineService  ←→ Session + Homework + Preview 聚合   │
└──────────────────────────────────────────────────────────┘

从”备课 → 上课 → 复盘”，每个环节都有数据支撑和自动化推送。

消息链路的演进

这个模块最初只是验证 OneBot 能否收发 QQ 消息，随后加入作业完成提醒和 RAG 问答，最后才进入实时课堂。功能增加后，消息链路被固定为：

QQ / 课堂事件
    ↓
OneBot 适配层
    ↓
身份与课程映射
    ↓
业务服务 / RAG / Agent
    ↓
通知编排与消息格式化
    ↓
群消息或私聊

OneBot 适配层只处理协议差异，不能根据字符串直接决定业务权限。教师、学生、课程和群聊的对应关系必须由应用数据库确认。

从“能发消息”到“可靠通知”

实时课堂比普通聊天多出几个约束：

幂等：互动关闭、课堂结束等事件可能重复触发，通知必须带业务事件键；
身份防冒用：学生身份由账号绑定关系确定，不能相信前端提交的 studentId；
顺序：先保存课堂结果，再发送总结，避免消息到达但页面没有数据；
降级：QQ 通道失败不能回滚课堂主事务，应记录待重试通知；
隐私：个人未完成情况发私聊，群内只发送汇总；
可追踪：记录事件、接收人、发送状态和失败原因，而不是只打印一行异常。

AI 生成材料的边界

课件转预习题和课堂材料适合异步生成：教师提交 PPT 后先解析文本，再由 RAG 提供课程上下文，模型生成候选内容，最终由教师确认发布。模型生成结果不能直接推送给学生，这一层人工确认既是质量控制，也是教学责任边界。

结论

QQ 机器人真正有价值的地方不是聊天，而是把原本散落在网页里的教学事件送到学生最常用的通道。要做到这一点，协议接入只是第一步，后面的身份、幂等、隐私和失败处理才决定它能否进入真实课堂。