面向高校自主学习场景的 Web 学习平台项目总结
项目链接 #
- 在线体验：https://www.example.sx.cn
- GitHub 项目仓库：https://github.com/zx539/CSC_LearnPlatform
- GitHub SSH 克隆地址：
git@github.com:zx539/CSC_LearnPlatform.git - GitCode 项目仓库：https://gitcode.com/linlongOS/CSC-LearningPlatform
说明：在线地址来自仓库部署记录；GitHub 地址由项目维护者确认。当前工作区的
origin仍指向 GitCode，GitHub 仓库可作为项目公开地址或镜像地址使用。
开场：学习资源不应该只有一种答案 #
很多在线学习产品能够回答“这个概念是什么”，却很难继续回答三个更具体的问题：
- 我现在的基础在哪里？
- 我应该先学什么、再练什么？
- 学完之后，系统如何判断我是否真的掌握？
本项目的目标，是把学生的一段自然语言需求，转化为一组与个人情况相关的学习资源、一条可执行的学习路径，以及后续的评估和辅导入口。它不是简单地把大模型接到聊天框里，而是围绕“画像、生成、规划、评估、辅导”组织了一条完整的学习闭环。
项目定位 #
项目面向高校学生的自主学习场景。用户输入课程、主题和背景对话后，系统会完成以下工作：
- 从对话中提取学习目标、知识基础、认知风格、薄弱点、学习节奏和资源偏好等画像信息；
- 协调多个职责型智能体生成六类学习资源；
- 根据画像和资源组合规划阶段化学习路径；
- 通过进度问卷、阶段测试和 Bloom 六维分数记录学习反馈；
- 提供独立 Chat、结果页 Tutor、QLosu 洛书工作台和 OSEdu 编译原理演示。
这里的“多智能体”是由主控编排器组织的职责集合，而不是多个自治进程。不同职责拥有独立提示词、输入和输出目标，共享统一的模型调用客户端和项目上下文。
一次学习项目如何运行 #
用户输入课程、主题与背景对话
│
▼
POST /api/generate
│
▼
创建异步任务 task_id
│
▼
主控编排学习生成流程
├─ 构建或更新学习画像
├─ 并发生成六类资源
├─ 规划阶段化学习路径
└─ 生成进度问卷与阶段测试
│
▼
保存 outputs/<run_name>/
│
▼
前端轮询任务状态并展示结果
│
▼
学习、提问、答题、复盘
│
▼
更新画像与 Bloom 认知记录
生成过程可能持续数分钟，因此系统采用“提交任务 + 状态轮询”模式。前端提交后立即获得 task_id，后端在后台执行完整流程，任务状态使用 queued、running、succeeded 和 failed 表示。用户即使离开页面，任务仍可继续运行，完成后的项目可以在项目列表中重新打开。
多智能体如何分工 #
1. 画像职责：先理解学习者 #
画像智能体根据学生对话、课程、主题和历史画像输出结构化数据，当前覆盖：
- 专业与课程；
- 学习目标；
- 知识基础；
- 认知风格；
- 薄弱点；
- 学习节奏；
- 偏好资源类型；
- 每周可投入时间。
系统还会保存置信度和待追问问题，避免把模型推测直接当成事实。
2. 资源职责：把同一主题拆成不同学习入口 #
资源生成职责受控并发，固定输出六类内容：
| 资源 | 主要用途 |
|---|---|
| 课程讲解文档 | 建立概念框架与完整讲解 |
| 知识点思维导图 | 展示知识结构、前置关系和易错点 |
| 分层练习题 | 提供基础、进阶、挑战三个层级的练习 |
| 拓展阅读材料 | 延伸概念、应用场景和相关阅读方向 |
| 实操案例 | 将知识转化为步骤、代码或实验 |
| 视频学习资料 | 按主题推荐检索关键词和观看顺序 |
资源输出统一经过 Markdown、数学公式、表格和思维导图格式归一化。视频资料的定位是学习推荐，不代表系统会自动生成视频文件；无法确认真实性的链接应使用搜索结果页，并标注“需核验”。
3. 路径职责：回答“下一步做什么” #
路径规划智能体读取画像和资源目录，输出阶段、目标、行动、检查点和推荐资源。这样学习结果不再是一堆孤立文档，而是一套有顺序、有反馈节点的学习方案。
4. 评估与辅导职责：让系统继续工作 #
用户完成进度问卷或阶段测试后，系统可以生成下一阶段问卷并更新学习记录。BloomScoringAgent 以记忆、理解、应用、分析、评价、创造六个维度记录认知层次变化，它是辅助指标，不应被解释为教育测量学认证结果。
结果页 Tutor 负责围绕当前主题进行短回答，独立 Chat 页面则通过 SSE 流式输出连续对话。两者保持独立业务边界，分别适配“针对当前资源提问”和“长期自由交流”这两类场景。
技术架构：边界清楚比堆功能更重要 #
浏览器
│
├── React 18 + TypeScript + Vite
│ ├── 学习项目、结果页、Chat、用户中心
│ ├── Cherry Markdown + KaTeX 富文本渲染
│ └── QLosu 工作台与个性化 UI
│
└── Nginx / Flask API
├── Flask 路由与 session 认证
├── MultiAgentLearningSystem
├── SparkClient（星火/豆包/OpenAI 兼容调用）
├── BloomScoringAgent
└── UserStore 文件系统持久化
独立教学服务
└── OSEdu：Node.js + Express + WebAssembly
后端使用 Flask，前端使用 React 18、TypeScript 和 Vite，Markdown 内容由 Cherry Markdown、Marked、KaTeX 和 highlight.js 协同渲染。模型接入统一收敛在 SparkClient，负责同步调用、SSE 流式调用、超时、重试、并发控制和模型切换。
项目数据采用文件系统持久化：用户资料和历史记录位于用户目录，生成项目位于 outputs/<run_name>/。这种方案部署简单、便于比赛演示，但在多节点一致性、复杂查询和持久化任务队列方面仍有明显边界。
三个值得记录的工程细节 #
异步任务解决长生成等待 #
六类资源、路径和问卷需要多次模型调用。同步请求容易遭遇网关超时，也会让用户误以为页面失去响应。任务快照和轮询接口把“等待”变成了可观察的状态，失败也能显式返回，而不是将错误文本伪装成成功结果。
流式 Markdown 需要专门的归一化层 #
大模型的流式输出可能把标题、表格、列表和 LaTeX 公式挤在同一行，甚至出现公式跨行和反斜杠命令粘连。前端 normalizeChatOutput 按规则修复这些结构，再交给 Cherry Markdown 和 KaTeX 渲染。它解决的是“内容如何稳定呈现”，不是“内容是否事实正确”。
教学扩展保持独立边界 #
QLosu 提供本地多文件项目、语法手册和受限解释器运行；OSEdu 提供词法分析、语法分析、语义分析、代码生成、内存、文件系统和线程调度演示。它们扩展了学习场景，但不与核心的画像、资源、路径和评估逻辑互相缠绕，便于独立测试和迭代。
测试与当前证据 #
仓库已经提供后端 pytest、前端 Vitest 和评委样例校验。现有测试报告记录了后端 29 个用例通过、前端 15 个测试文件共 153 个用例通过，以及生产构建成功。测试覆盖 Markdown 导出、流式输出归一化、QLosu 路径与资源限制、XML 解析防御、用户数据隔离和个性化 UI 等关键行为。
这些结果说明工程链路具备可回归基础，但不能替代最终提交版本上的全量测试，也不能证明学习效果、事实准确率或生产并发上限。提交前仍应补充 Spark Lite 用户端到端流程、桌面与移动端验收、压测、备份恢复和安全红队记录。
安全和内容边界 #
项目已经实现 session 认证、输入校验、上传限制、用户数据隔离、QLosu 资源限制和危险 XML 防御。用户自定义 UI 采用白名单 token，不执行上传的脚本、任意 CSS 或外链；用户提供的 OpenAI 兼容 API Key 仅保存在浏览器会话中。
仍需明确以下事实：
- 仓库中的历史密钥材料和用户/生成数据不能原样提交；
- 当前结构校验、重试和知识库上下文不能等同于完整防幻觉方案；
- 还缺少来源 ID、可点击引用、权威核验、敏感内容分类和教师人工审核闭环；
- QLosu 具备资源限制，但尚未达到容器或内核级强沙箱；
- 文件系统存储和进程内后台任务更适合当前规模，不应包装成分布式生产架构。
结语：把 AI 从答案生成器变成学习协作者 #
这个项目最核心的价值，不在于一次生成了多少字，而在于把一次学习需求拆成了可追踪的过程：先理解学习者，再准备多种资源，接着安排学习顺序，最后根据反馈调整下一步。模型负责生成和对话，系统负责编排、状态、持久化、渲染和边界控制。
下一阶段最值得投入的方向有三个：建设可检索、可引用的课程知识库；将后台任务和用户数据迁移到更可靠的持久化基础设施；建立事实准确率、引用可追溯率和真实学习增益的评估证据。只有这些证据补齐，个性化学习才会从“功能完整的演示”走向“可验证的学习产品”。