抛砖引玉：教你扩展一个多 Agent 智能平台，并配套落地强风格化前端

项目名：大观园智学系统
技术关键词：Vue、FastAPI、LangGraph、多 Agent、RAG、Text2SQL、SSE 流式响应、Codex 前端落地

摘要

这篇文章适合想把普通业务系统改造成 AI 应用的同学阅读。项目的起点是一个学生管理系统，里面已经有学生、教师、班级、成绩、通知等教务数据。我的目标不是重新做一套管理页面，而是在这个系统的基础上，扩展出一个可以自动分流问题、调用不同 Agent、查询数据、检索知识库、生成文书并支持流式回复的智能教务平台。

文章会按照新手比较容易理解的顺序展开：先说明为什么要从学生管理系统切入，再用一张总图看懂整体结构，然后逐个拆解 SupervisorAgent、林黛玉 Agent、四大名著 RAG、教务助手和模拟面试 Agent。后半部分会讲前端怎么承载这些 AI 能力，包括页面怎么规划、路由怎么放、组件怎么拆、接口怎么调、素材怎么管理，以及移动端怎么适配。

这篇文章还会分享一个真实经验：强风格化前端并不是“生成一张设计图，再让模型写代码”就能自然落地。真正好用的方式，是让 Codex 参与素材生成、浏览器检查、截图反馈和代码修改，把设计和落地连成一个闭环。

读完这篇文章，你可以学到：

• 如何在已有业务系统上扩展 AI Agent 能力。
• 如何用 SupervisorAgent 做多 Agent 分流。
• 如何把 RAG、Text2SQL、函数工具和模板生成接入统一对话入口。
• 如何设计一个能展示 Agent 状态、流式回复和角色互动的前端界面。
• 如何用 Codex 降低风格化前端的落地难度。

文章导航

• 1. 扩展背景：为什么从学生管理系统切入
• 2. AI 扩展后的系统总架构
• 3. Supervisor：负责把问题分给合适的 Agent
• 4. 所有 Agent 与工具调用链路
• 5. 林黛玉 Agent：角色化智能体的完整拆分
• 6. 四大名著 RAG：让回答尽量有依据
• 7. 教务助手：把自然语言变成业务工具调用
• 8. 面试 Agent：做一个可连续追问的训练场景
• 9. 流式体验：让用户看到 AI 正在回答
• 10. 前端设计：让 Agent 能力被用户看见
• 11. 移动端适配：窄屏下保留核心 AI 体验
• 12. 联调与质量保障
• 13. 写在最后：从学生管理系统到 Agent 平台

技术栈速览

如果你是第一次接触这类项目，可以先不用纠结每个技术名词的细节。下面这张表的作用，是帮助你知道每一层大概负责什么。

层级	技术与能力
前端	Vue、Vue Router、Pinia、SSE 流式消费、响应式适配、国风视觉素材
后端	FastAPI、统一 AI 接口、权限认证、教务业务 API
Agent	LangGraph、SupervisorAgent、工具调用、会话记忆、情绪识别
RAG	Chroma、SQLite FTS5、多路召回、章节锚点、父子上下文、bge-reranker
数据	MySQL、Redis、四大名著本地语料、摘要缓存、embedding 缓存
工程化	全链路联调脚本、SSE 事件记录、路由与工具选择回归测试

1. 扩展背景：为什么从学生管理系统切入

很多 AI 项目一开始会做成一个独立聊天框：用户输入一句话，大模型返回一段文本。这样可以快速看到模型效果，但它有一个问题：系统本身没有业务上下文，也不知道用户的数据从哪里来。

学生管理系统正好适合作为 AI 扩展的起点，因为它已经有了三个很重要的基础：

• 数据基础：学生、教师、班级、成绩、通知等信息，可以用来做查询、统计、分析和解释。
• 场景基础：成绩波动、班级概况、学习建议、通知公告、评语生成等问题，本身就适合用自然语言来提问。
• 产品入口：系统已经有登录、导航和页面结构，AI 能力可以自然嵌入进去，而不是另做一个孤立工具。

所以本文不会把重点放在学生管理系统的基础页面上，而是重点讲：如何在已有系统上接入统一 AI 入口、多 Agent 调度、知识库检索和工具调用，让它逐步变成一个智能教务平台。

2. AI 扩展后的系统总架构

先看整体结构。新手可以把它理解成三层：

• 第一层是前端入口，用户只需要在统一 AI 对话框里提问。
• 第二层是 Agent 调度层，负责判断这个问题应该交给谁处理。
• 第三层是工具和数据层，包括数据库、向量库、全文索引、模型服务和会话记忆。

这里最重要的设计点是：前端入口尽量简单，后端能力尽量分层。用户不用关心背后有多少 Agent，只要输入问题；系统会在后端判断问题类型，然后选择最合适的处理方式。

3. Supervisor：负责把问题分给合适的 Agent

新手做多 Agent 系统时，很容易一上来就写很多 Agent，但忽略了一个关键问题：用户的问题到底应该交给谁？

SupervisorAgent 就是用来解决这个问题的。它相当于一个“分诊台”，先看用户的问题属于哪一类，再把它交给对应的 Agent。

• 诗词、对联、作文点评、情绪疏导、林黛玉角色问答：进入林黛玉 Agent。
• 四大名著人物、情节、回目、原著事实：进入四大名著 RAG Agent。
• 面试模拟、HR 问答、岗位训练、项目追问：进入模拟面试 Agent。
• 教务数据、成绩查询、模板文书、学习建议：进入教务助手 Agent。

这样做的好处是，前端可以保留“智能路由”模式，用户不用先学习系统有哪些 Agent；而开发者也可以在后端不断优化分流规则。

4. 所有 Agent 与工具调用链路

下面这张图可以理解为系统的“能力地图”。你可以顺着箭头看：用户的问题先到统一聊天接口，再到 SupervisorAgent，然后被分到某个 Agent，最后才进入具体工具。

如果你是第一次做 Agent 系统，可以先记住一个简单原则：不要把所有能力都塞进一个大提示词里，而是尽量拆成清楚的 Agent 和工具。这样后面测试、调试和修复都会容易很多。

5. 林黛玉 Agent：角色化智能体的完整拆分

林黛玉 Agent 是这个项目里最有辨识度的一部分。它不是简单写一句“请你用林黛玉语气回答”，而是拆成了角色设定、状态流、工具调用、情绪识别、会话记忆和前端立绘联动。

5.1 林黛玉内部状态流

可以把林黛玉 Agent 的处理流程理解成这样：

1. 先检查用户输入是否安全、是否需要清洗。
2. 读取历史会话和摘要，保证角色不是每轮都“失忆”。
3. 注入林黛玉角色设定。
4. 判断是否需要调用工具。
5. 生成回复，并识别当前情绪。
6. 把回复和情绪通过 SSE 发给前端。

这条链路解决了三个问题：

• 角色稳定：不会每次回答都像一个全新的模型。
• 能力清晰：作诗、对联、作文点评、情绪疏导等能力可以分别测试。
• 体验完整：回复内容、情绪标签和前端立绘可以联动。

5.2 林黛玉 7 个工具拆分

这 7 个工具分别对应不同场景：

• compose_poetry：写诗、写词。
• match_couplet：对联。
• play_poetry_game：飞花令、诗词接龙、对对联。
• review_essay：作文点评。
• emotion_support：情绪安慰。
• detect_emotion：判断心境。
• tell_time：时辰问答。

对新手来说，这里最值得学习的是“拆工具”的思路。角色化 Agent 不应该只靠一个复杂提示词硬撑，能拆成工具的能力尽量拆出来。

5.3 前端联动

林黛玉模式下，前端会切换到“潇湘馆 · 听雨问诗”的视觉状态，右侧展示林黛玉立绘和近来会话。后端返回的情绪标签会影响角色状态，例如忧思、温柔、沉静等。

这一步很重要，因为用户感知到的不是“后端调用了哪个函数”，而是“这个角色真的在用一种稳定的方式和我交流”。

6. 四大名著 RAG：让回答尽量有依据

RAG 可以简单理解为：不要只让大模型凭记忆回答，而是先从本地资料里找证据，再让模型根据证据组织答案。

在这个项目里，四大名著问答基于本地语料实现。简单说，就是先把《红楼梦》《西游记》《水浒传》《三国演义》整理成一段一段的小文本，再把这些文本写入向量库和全文索引。用户提问时，系统先找相关原文，再让模型根据原文组织答案。

6.1 最新 RAG 检索链路

6.2 为什么不能只靠向量检索

早期只靠向量召回时，像“林黛玉进贾府时，贾宝玉摔的是什么？”这类问题容易被相似情节干扰。因为《红楼梦》后文也有“摔玉”场景，向量检索会觉得它们语义很接近，最后可能召回到错误段落。

为了解决这个问题，我没有只调大向量召回数量，而是加入了多个“纠偏”信号：

• 先识别书籍范围，减少跨书误召回。
• 用多查询召回，不只搜原问题，也搜改写后的关键词组合。
• 用 FTS5 补足人物、物件、章节这些精确词命中。
• 用章节锚点把“林黛玉进贾府”关联到第三回。
• 用父子上下文扩展，避免只取到半段文本。
• 最后再交给 reranker 精排。

所以对于示例问题，系统应命中《红楼梦》第三回，并回答“贾宝玉摔的是通灵宝玉”。这个例子也说明，RAG 的关键不只是“接一个向量库”，而是要根据真实错误不断补检索策略。

7. 教务助手：把自然语言变成业务工具调用

教务助手是学生管理系统与 AI Agent 结合最直接的一条链路。它不是单纯聊天，而是会先判断用户想做什么，再选择合适的子能力。

举几个例子：

• “统计每个班级学生人数”走 text2sql，把自然语言转成数据库查询。
• “查询张三的成绩详情”走 function_call，调用受控函数查询学生成绩。
• “写一份家长会通知”走 template，生成规范文书。
• “如何提高课堂注意力”走 general，给出学习建议。

这里给新手的建议是：能用确定工具解决的问题，不一定要全部交给大模型自由发挥。比如成绩详情和班级统计，规则足够明确时可以先直接查库，再让模型负责解释结果。这样结果更稳，也更容易排查问题。

8. 面试 Agent：做一个可连续追问的训练场景

模拟面试 Agent 面向求职和答辩训练，支持岗位模拟、HR 问题、项目追问和表达反馈。它的重点不是查询数据库，而是把用户放入一个连续对话场景：每次只问一个问题，等待用户回答后继续追问或反馈。

在学生管理系统的扩展语境下，面试 Agent 更像一个独立训练空间。它不直接依赖教务数据，但丰富了平台的学习与成长场景，让系统从“记录学生信息”进一步延伸到“陪伴学生训练表达能力”。

9. 流式体验：让用户看到 AI 正在回答

如果 AI 回答要等待很久才一次性出现，用户会觉得系统卡住了。因此这个项目使用 SSE 流式响应，让前端可以一段一段展示内容。你可以把它理解成：后端不是等答案全部生成完再返回，而是边生成边把内容推给前端。

后端事件包含 meta/content/error/done/emotion 等字段：

• meta：告诉前端当前调用的是哪个 Agent。
• content：逐段返回回答内容。
• emotion：用于林黛玉立绘或状态切换。
• done：表示本轮回复结束。
• error：表示异常信息。

流式优化主要体现在三点：

• 林黛玉作诗走专用快路径，避免“整首诗生成完才显示”。
• RAG 流式接口只预先完成检索和重排，生成阶段逐 token 输出。
• function_call 能先返回工具查询结果，再流式补充自然语言解释。

10. 前端设计：让 Agent 能力被用户看见

如果前端只是一个普通表格后台，用户很难感受到多 Agent 的区别。所以前端设计的目标不是单纯美化页面，而是让用户看得见：当前是谁在回答、系统进入了什么场景、回复是否正在生成、角色状态有没有变化。

10.1 真实实践：风格化前端不是只靠代码

一开始做前端设计时，我走了不少弯路。我之前设想过一种很理想的流程：先用 GPT-Image-2 生成设计图，再利用 Kimi K2.6 做多模块代码拆分和落地。这个方案听起来很顺，但真正实践后会发现，强风格化前端不只是“把设计图翻译成 Vue 和 CSS”。

难点在于，美术风格来自很多连续细节：背景纹理、纸张质感、卷轴边框、装饰素材、色彩层级、字体气质、按钮状态、动效节奏和移动端压缩后的观感。只靠一次设计图，很难覆盖后续页面、弹窗、表格、空状态、路由切换和响应式细节。

最后更可行的方法，是用 Codex 贯穿“设计、生成素材、落地、检查、再调整”这条流程：

• Codex 内置 GPT-Image-2，可以根据页面需求生成背景、卷轴、纹样、角色立绘状态等素材，并把素材命名、压缩和引用一起纳入项目结构。
• Codex 具备浏览器控制能力，可以登录本地前端页面，自行检查布局、动效、溢出、移动端表现和真实截图。
• 如果某些细节没有改到位，可以继续截图圈注，Codex 能识别问题区域，再回到代码里修改。

这对新手很有帮助，因为强风格 UI 最难的地方不是“写一个按钮”，而是让素材、样式、布局和浏览器里的真实效果最终对得上。

10.2 前端设计步骤

我最后把前端设计拆成 7 步。这个顺序很适合新手参考：

先做信息架构，是为了知道系统有哪些区域；再做页面清单，是为了知道每个能力放在哪里；接着做路由和组件拆分，保证项目结构不会乱；最后再整理 API、素材和 UI 规范。

10.3 信息架构

AI 扩展后的信息架构分成三层：

• 数据底座层：学生、教师、班级、成绩、通知等对象，为问数、分析和生成提供可信来源。
• 智能能力层：统一 AI 学伴、林黛玉、名著问答、模拟面试、Text2SQL、成绩诊断、批量评语、公告起草和智能分组。
• 体验支撑层：登录、个人资料、设置、会话记录等，用来支撑用户身份、权限和持续对话。

这样设计的好处是，已有系统负责提供数据和入口，AI 页面负责把数据、知识库和模型能力变成可操作的对话体验。

10.4 页面清单

模块	页面	在 AI 扩展中的作用
入口与概览	登录、系统概览	完成身份进入，展示系统整体状态
数据底座	学生、教师、班级、成绩、录取、通知、统计	为 AI 问数、分析和文书生成提供业务来源
AI 中心	统一 AI 学伴	承载自动分流、手动 Agent 切换和 SSE 流式回复
专项 AI	名著问答、模拟面试、Text2SQL、成绩诊断、批量评语、公告起草、智能分组	面向具体教务或训练任务提供独立工作台
账户系统	会话记录、个人资料、设置	支持持续使用、个人信息和系统配置

页面清单不是为了堆页面，而是为了让每个 AI 能力都有明确位置。

10.5 路由结构

路由采用一个主布局承载多个子页面。/ 下挂载 AppLayout，内部再通过 router-view 切换不同功能页面：

/login
/
  /dashboard
  /students
  /teachers
  /classes
  /grades
  /offers
  /statistics
  /notifications
  /sessions
  /profile
  /settings
  /ai/chat
  /ai/academic
  /ai/lindaiyu -> /ai/chat?agent=daiyu
  /ai/classics
  /ai/interview
  /ai/text2sql
  /ai/score-diagnosis
  /ai/batch-comments
  /ai/announcement
  /ai/grouping

其中 /ai/chat 是最重要的统一入口。林黛玉、名著问答、面试和教务助手都可以通过这个入口切换，也可以由自动模式交给 SupervisorAgent 判断。

10.6 组件拆分

组件拆分时，我遵循一个简单原则：布局归布局，页面归页面，接口归接口。

• AppLayout：负责左侧导航、顶部牌匾、用户菜单、路由切换动效和页面预加载。
• AIChatView：负责统一 AI 对话体验，包括 Agent 模式切换、快捷提问、消息列表、输入区和 SSE 事件消费。
• 教务数据页面：如学生、教师、班级、成绩、通知等页面，为 AI 能力提供可用的数据场景。
• 专项 AI 页面：如名著问答、模拟面试、Text2SQL、成绩诊断等，保留独立工作流。
• API 模块：auth.ts、ai.ts、students.ts、grades.ts 等按业务域拆分，避免页面直接拼请求。

10.7 API 调用关系

前端 API 层分成普通 Axios 请求和 AI 流式请求两类。教务数据相关请求统一走 request.ts 封装，自动附带 token；AI 流式对话走 fetch + ReadableStream，以便逐段解析 SSE 事件。

新手可以重点看这里：普通接口和流式接口最好分开处理。普通数据请求用 Axios 很方便，但流式响应需要用 fetch 读取 ReadableStream，再把 SSE 事件一段一段解析出来。

10.8 素材清单

前端视觉素材围绕“东方古典书院”展开，主要分为几类：

类型	代表素材	用途
背景图	bg-dashboard-ink.webp、bg-chat-scroll-ink.webp、bg-management-ink.webp、bg-login-ink.webp	区分概览、AI 对话、数据页面和登录页氛围
纸张与卷轴	paper-texture-ink.webp、ui-scroll-panel-ink.webp、ui-scroll-ribbon-ink.webp	构造宣纸、卷轴、面板层级
建筑与装饰	ui-sidebar-pavilion-ink.webp、ui-palace-roof-plaque-ink.webp、ui-ornament-sheet-ink.webp	强化大观园式空间感
植物与纹样	deco-bamboo-ink.webp、deco-plum-ink.webp、deco-lotus-ink.webp、svg/cloud.svg、svg/bamboo.svg	用作边角、背景和轻量装饰
角色立绘	lindaiyu-wenrou-transparent.webp、lindaiyu-jingruo-transparent.webp、lindaiyu-duochou-transparent.webp、lindaiyu-caiqing-transparent.webp、avatar-daiyu.webp	支撑林黛玉 Agent 的情绪和角色状态
功能图标	icons/home.svg、icons/student.svg、icons/teacher.svg、icons/grade.svg、icons/ai.svg 等	左侧导航和功能入口

素材并不是简单铺背景，而是配合不同功能场景使用：数据页面保持清淡纸感，AI 对话页强化卷轴和角色氛围，林黛玉模式则通过立绘与情绪状态形成更强的角色识别。

10.9 UI 风格规范

UI 风格采用“淡水墨 + 宣纸 + 低饱和国风色”的方向。色彩上以纸白、米白、淡灰白做底，以浓墨和常墨承载正文，再用朱砂、竹青、藕荷、赤金作为强调色。

核心规范包括：

• 色彩：背景以 #FBF5E9、#F2E9DA 等纸色为主，文字使用墨色层级，强调状态使用朱砂和竹青。
• 字体：正文使用中文无衬线保证可读性，标题通过毛笔感字形、牌匾和淡墨线条增强古典气质。
• 布局：整体布局保留学生管理系统的稳定导航，AI 对话区强调消息阅读、输入连续性和 Agent 状态。
• 动效：页面切换使用水墨式过渡，路由 hover 会预加载组件，降低切换卡顿；动效服务节奏感，不做过量装饰。
• 组件：按钮、卡片、表格、输入框都保持宣纸边框、轻阴影和低对比背景，避免数据页面与古典主题割裂。

这套规范不是一次性设计出来的，而是通过“截图检查 - 圈注问题 - 修改代码 - 再截图”的循环逐步收敛。对这种东方古典风格的前端来说，不要只在脑子里想效果，一定要多看真实浏览器截图。

11. 移动端适配：窄屏下保留核心 AI 体验

除了桌面端的大屏展示，前端也针对移动视口做了适配。移动端不再强调完整教务页面的横向信息密度，而是优先保留“导航、Agent 当前状态、对话内容、输入区”这条最重要的使用链路，让用户在手机上也能完成提问、切换 Agent 和查看流式回复。

移动端适配主要体现在几个细节：

• 左侧导航压缩为图标栏，保留系统主功能入口，同时减少文字导航对横向空间的占用。
• AI 对话页以纵向阅读为主，角色标题、说明、会话内容和输入区按上下顺序组织，保证核心对话不被其他信息挤占。
• Agent 模式和快捷提问使用紧凑按钮承载，适合在窄屏上横向滑动或局部露出，避免一次性堆满屏幕。
• 输入区固定在底部附近，方便连续提问；上传、发送等操作保留独立按钮，降低误触概率。
• 古典背景、纸张质感、毛笔标题和林黛玉立绘元素在移动端仍被保留，保证手机端不是“降级版页面”，而是同一套东方视觉风格的延展。

这部分适配的取舍很明确：移动端不追求把所有数据表完整搬到手机屏幕里，而是优先服务 AI 对话和 Agent 展示。

12. 联调与质量保障

多 Agent 系统最容易出错的地方，不一定是模型回答得不好，而是“问题被分给了错误的 Agent”。所以做这类项目时，不能只靠手动点几下页面，需要写脚本把常见问题批量跑一遍。

这个项目配套了 AI 全链路联调脚本，覆盖本地分类器、3000 前端代理、SSE 流式事件和独立接口。

测试矩阵按“每个 Agent、每个工具多样本”设计，覆盖诗词、对联、情绪、作文、RAG、面试、问数、成绩查询、模板生成、通用建议和边界冲突问题。

记录内容包括：

• 测试问题。
• 预期 Agent 和工具。
• 实际 Agent 和工具。
• 返回摘要。
• 回复耗时。
• 是否通过。
• 失败原因和修复说明。

对新手来说，这一步很容易被忽略。但只要系统里有自动分流，就一定要做路由测试，否则问题会很难排查。

13. 写在最后：从学生管理系统到 Agent 平台

多 Agent 应用并不是“多接几个模型接口”这么简单，也不是写一个很长的万能 Prompt 就能解决所有问题。对新手来说，可以先把它理解成一个分工明确的系统：先判断问题类型，再交给合适的 Agent，Agent 需要工具时再去调用工具，最后把结果用用户能理解的方式展示出来。

如果用一句话总结大观园智学系统，它其实做了这几件事：

• 先基于学生管理系统已有的数据和业务场景接入 AI，而不是单独做一个脱离业务的聊天页面。
• 用 SupervisorAgent 做统一分流，让不同问题进入不同智能体。
• 把林黛玉 Agent 拆成角色设定、工具、情绪、记忆和前端立绘联动，而不是只写一句角色提示词。
• 做 RAG 时不只依赖 Chroma 向量检索，还加入 FTS5、章节锚点、父子上下文和重排序，让答案更容易找到原文依据。
• 教务助手负责把自然语言连接到数据库查询、函数工具和模板文书，体现业务系统接入 AI 的价值。
• 用 SSE 流式接口让回答逐步出现，减少用户等待时的“卡住感”。
• 前端先设计信息架构、路由、组件和 API 调用关系，再去做古典视觉风格，这样页面不会越做越乱。
• 使用 Codex 把素材生成、浏览器检查、截图圈注和代码修改连成闭环，降低强风格化前端的落地难度。
• 移动端保留最核心的 AI 对话链路，方便展示和轻量使用。
• 最后用全链路测试反复检查 Agent 分流和工具调用，避免问题被分到错误的智能体。

如果你也想在自己的项目里接入 AI，不建议一开始就追求“大而全”。更稳的做法是按这条路线慢慢来：第一步，先做一个统一 AI 入口；第二步，加上最简单的分流规则；第三步，接入一个最有价值的工具或知识库；第四步，再根据真实问题逐步扩展更多 Agent。这样每一步都能验证效果，也更容易发现问题出在哪里。