软件杯参赛复盘：用多智能体搭建一个真正懂你的AI学习系统

软件杯参赛复盘：用多智能体搭建一个"真懂你"的AI学习系统

写在前面

今年参加了中国软件杯，我们选的赛题方向是基于大语言模型构建个性化学习系统。核心要求是：利用多智能体协同，动态建模学生画像，自动生成多种学习资源，提供个性化学习路径。

两个月时间，从零到一，最终交付了一个完整的系统——AI智学。这篇博客算是参赛复盘，聊聊赛题理解、架构设计、踩过的坑，以及一些个人思考。

赛题拆解

拿到赛题后，我们梳理出了几个关键需求：

1. 动态学生画像：不能是静态问卷，必须从对话中自动提取和持续更新
2. 多智能体协作：不同资源由不同专业智能体生成，各司其职
3. 多种资源类型：不止是文字讲解，还要有练习题、思维导图、视频脚本、实操案例
4. 流式输出：回复要实时逐字推送，不能等生成完再一次性返回
5. 内容安全：输入输出双向敏感词过滤

我们选择《数据结构与算法》作为教学内容载体，构建了完整的课程知识库（8章60+知识点），系统架构上可以扩展到任意学科。

系统设计

整体架构

用户界面 (原生HTML/CSS/JS)
    ↕ SSE 流式推送
FastAPI 服务层
    ↕
LangGraph 多智能体工作流 (12个智能体节点)
    ↕
DeepSeek 大模型 + PostgreSQL + 课程知识库

五种意图路由

用户输入进来，首先经过画像分析和意图识别两个前置节点，然后按意图分发：

意图	处理方式
问候	简短打招呼，表明AI智学身份
普通对话	结合画像+课程知识库回复，可附加学习路径推荐
资源生成	5个智能体协作生成完整学习资源包
智能辅导	概念解释 + ASCII图解 + 学习建议
效果评估	分析对话记录，生成结构化评估报告

资源生成管线（核心亮点）

这是系统最复杂的部分。用户说"帮我生成二叉树的学习资源"，背后实际是5个智能体在接力：

资源规划智能体 → 内容生成智能体(讲解文档+练习题)
               → 多模态设计智能体(思维导图+视频脚本)
               → 案例生成智能体(实操案例+代码)
               → 资源合并智能体(校验完整性+缺失补充)

最后合并智能体会检查前4种资源标题是否齐全，缺哪个就自动调用LLM补上——这个"补漏"机制在测试中救了无数次场，因为LLM确实会时不时漏掉某个资源。

十维学生画像

初始设计是6维，后来扩展到10维：

知识基础 | 学习风格 | 认知风格 | 薄弱点 | 易错模式
兴趣方向 | 学习节奏 | 学习目标 | 动机水平 | 交互摘要

画像从每次对话中自动抽取，采用智能合并策略：数组字段取并集去重，标量字段"新值为空不覆盖旧值"。这个策略专门解决LLM偶尔输出空值导致画像被"冲掉"的问题。

技术选型

层	选择	原因
Web框架	FastAPI	原生支持SSE，异步性能好
多智能体	LangGraph StateGraph	有向图工作流，状态共享机制成熟
大模型	DeepSeek (deepseek-chat)	OpenAI兼容格式，性价比高
数据库	PostgreSQL	持久化会话、消息、画像、评估
前端	原生HTML/CSS/JS	轻量，无框架依赖，部署简单
Markdown渲染	marked.js + mermaid.js	思维导图实时渲染
文生图	豆包 Seedream	配合学习资源生成配图
搜索	open-webSearch / Bing / DuckDuckGo	四级降级保证可用性

几个有意思的技术细节

1. 生成器驱动的流式架构

所有LLM调用都用Python生成器（yield），而不是等完整响应。每个token一出来就通过SSE推给前端，用户感知延迟极低。

# 核心模式
def call_llm_stream(messages):
    for chunk in api.chat(messages, stream=True):
        yield ("chunk", chunk.content)
    yield ("done", "")

断连处理也靠这个——try/finally 块里确保 gen.close() 被调用，消息一定持久化到数据库，不会因为客户端关了浏览器就丢回复。

2. JSON解析的三阶容错

大模型输出的JSON经常不老实——裹在解释文字里、多了个逗号、少了个括号。搞了个三阶容错：

1. 直接 json.loads() —— 理想情况
2. 括号追踪提取片段再解析 —— 混在文字里
3. 正则松散匹配 + 修复尾随逗号 —— 格式有瑕疵

实测第三阶是救命稻草。比赛答辩时评委也问了这个问题，算是LLM应用开发里的共性痛点。

3. 搜索的四级降级

联网搜索对学习助手是刚需。但比赛环境网络不一定稳定，所以做了降级链：

本地 open-webSearch MCP → Bing API → Bing网页抓取 → DuckDuckGo

另外还发现一个细节问题：用户说"昨天有什么新进展"，搜索引擎可能把"昨天"当成电影名。处理方式是在构造搜索query时把时间词替换成具体日期。

4. 深度思考模式

前端加了个开关，开启后在Prompt最前面注入高优先级元指令，强制模型先输出 <深度思考>...</深度思考> 再给答案。本质是让模型"自言自语"想一遍，复杂问题上效果明显。

踩过的坑

画像降级：最早画像合并是简单覆盖。LLM有时候对新对话返回空字符串，直接把积累的画像冲没了。改成"新值为空保留旧值"才解决。

资源内容污染：让模型"只生成练习题"，它还是会热情地附带讲解。只能对单资源输出做后处理，用正则把不属于当前类型的章节剥掉。

SSE生命周期管理：生成器没正确关闭会内存泄漏。finally + pre_msg_count 追踪确保消息不丢不漏。

最大的感受：用LLM做应用，难点不在"调API"，而在容错和工程化。JSON不稳定怎么办、生成器断了怎么办、搜索结果为空怎么办、画像被污染怎么办——这些边界情况才是吃掉时间的地方。

比赛心得

1. 赛题审题很重要：多智能体、动态画像、流式输出这些加分项，我们在方案设计阶段就全部纳入了，答辩时评委明显对这些感兴趣
2. 文档和测试不能省：我们写了完整的设计说明书、测试报告、AI工具使用说明，答辩时有据可依
3. 善用AI工具提效：整个项目用Claude Code辅助开发，代码生成、多文件协调修改、文档撰写都大幅提速
4. 先跑通再优化：第一版只用了两天就出了能跑的原型，之后在原型上不断迭代，比一开始就追求完美架构效率高得多

写在最后

从最开始一个单文件Python脚本，到最终12个智能体节点、SSE流式推送、PostgreSQL持久化、完整前端界面的系统，中间重构了不下十次。虽然过程很累，但把一个想法从零到落地，尤其是在比赛中拿到好成绩，这种感觉真的很棒。

项目还在继续优化，后续打算加入语音交互、更细粒度的知识图谱、以及自适应的学习节奏调节。如果你也在做类似方向，或者准备参加软件杯，欢迎交流！

---

项目：AI智学 (a3 v0.2.0)

技术栈：Python / FastAPI / LangGraph / DeepSeek / PostgreSQL

开发辅助：Claude Code (Anthropic)