团队项目第一次作业

团队项目第一次作业：——「班小助」校园事务多智能体助手

项目	内容
作业所属课程	软件工程（计科24级78班）
班级的链接	计科24级78班 - 班级博客
作业要求	团队项目第一次作业 团队展示+选题报告+需求分析
作业要求的链接	作业详情
作业的目标	完成一次真实的产品立项：用智能体为传统校园事务场景赋予新体验
团队名称	智班工坊
团队成员学号-名字	3124004185-肖武阳、3124004175-刘旭波、3124004181-王梓瀚

一、团队展示

1. 队名与项目标志

队名：智班工坊　　项目名：班小助（BanXiaoZhu）

2. 团队项目的具体规划及描述

班小助是一个以智能体为核心的校园事务助手——把班级群里刷屏的通知，统一变成"结构化卡片 + 待办清单 + 按时提醒 + 有出处的答复"

为什么做这件事：我们班 40 多人的日常，被四类信息反复折磨——① 群消息刷屏导致漏看通知；② 截止日期靠脑子记；③ 办事流程要问三四个人；④ 班委成了人肉 FAQ。这四件事没有任何一个现有系统认真解决过，而这恰好是智能体最擅长的事：从非结构化文本里抽结构、跨源聚合、按人的语境给指引。

团队分工（3 人小队，每人一条主战场 + 一条交叉线）

成员	主要职责
3124004185-肖武阳	项目管理、需求与文档、后端接口、智能体提示词与数据结构
3124004175-刘旭波	前端页面与交互（原生 HTML/CSS/JS）、卡片渲染与原文高亮、可用性打磨
3124004181-王梓瀚	班级资料库与数据表设计、答疑检索质量、启动脚本与 Docker 打包

3. 队员风采

4. 团队项目的愿景

我们希望班小助成为每一个班级"默认打开的那一个入口"：新生入学第一天就知道今天该做什么，同学不再因为刷屏而错过一次报名，班委不再把同一句话回答一百遍。它不追求做大做全，只追求一件事——把散落的校园信息，变成你今天就该做的那几件事。三年后，它应该像课表一样理所当然地存在。

5. 已经跑起来的最小可运行程序

下面是本机真实运行的界面截图：

四个页签：通知解析 / 我的待办 / 班级问答 / 班委发布。右上角填昵称选角色即可，不需要注册。

一张真实通知粘贴进去后得到的卡片：整体置信度 95%，每个字段后面有可信度标签（95% / 88%），低于 75% 的字段标黄写"待确认"，右侧是原文并按字段做了黄色高亮。

---

二、选题报告

1. 选题背景：这些麻烦我们自己就有

怎么了解的：① 把三个人所在班级群、课程群最近两周的消息翻一遍，只看两类——通知类消息，和同一个人被反复问的问题；② 三个人各写一件最近真实踩的坑（漏看通知、材料不清楚白跑一趟、同一个问题被问第二遍）；③ 找同班同学聊 5～10 分钟，只问三件事：一周漏看几次通知、截止日期怎么记、办事流程从哪知道的。

看到的现象

现象	具体表现
通知被淹没	一天几十到上百条，通知夹在中间
关键信息分散	时间在一句、地点在下一句、材料在第三条；“下周三前”这类相对时间还得自己换算
靠人脑记账	截止日期基本没人记，默认“到时候总会有人说”，结果常常是最后一天才发现
班委重复劳动	同一个问题一周被问很多遍，答案其实几年没变过
流程知识不在群里	补办证件、报销、请假要交什么材料，只有老生和班委知道，新生只能到处问

问题定义：校园信息的生产是碎片化的（群聊、截图、教务系统、口头通知），消费却要求精确（时间、地点、对象、材料、截止）。中间这一层“翻译与追踪”的工作，现在由人（班委和自己的记性）承担——这就是我们的产品空间。

2. 目标用户与使用场景

用户角色	核心诉求	关键场景
普通同学（主要）	不漏事、不忘事、办事不跑空	群里丢一段通知文字 → 30 秒内得到"这张通知要我在 11 月 8 日 18:00 前把材料交到实验楼 A302"
班委（主要）	少重复答疑、通知能触达	发布通知 → 自动生成卡片 + 沉淀成 FAQ
辅导员/教师助理（次要）	通知能确认送达	查看触达率与未读名单（规划）

两条典型用户旅程

1. 通知进群：班委把通知文字粘贴进"通知解析" → 班小助返回结构化卡片（事项/截止/地点/材料/要做什么）→ 一键加入我的待办 → 提前 1 天、2 小时、10 分钟三级提醒。✅ 已实现
2. 办事：同学问"学生证丢了怎么补办" → 班小助检索班级资料库，回答里必须带"依据：班级资料第 N 条"，资料里没有的一律说不知道。✅ 已实现

3. 现有方案为什么不够

现有方案	做了什么	缺什么
微信群/QQ 群公告	传递信息	只"发"不"追"，不结构化、不会提醒、无法检索历史
教务系统 / 超星 / 学习通	发布课程与作业	只管课内，班级事务、社团、竞赛全在外面；界面重、移动端体验差
课程表类 App（如课程格子）	课表展示	静态课表，不处理通知与事务，无智能体能力
通用 AI 助手（DeepSeek/豆包/ChatGPT）	通用问答	不知道我们班的上下文、不知道通知原文、给不出"依据第几条"，也不敢把结果写进待办
班级小助手类小程序	打卡、投票	功能单一，靠人填，不做信息抽取

我们的差异点：不做"另一个群"，也不做"另一个课表"，而是做信息与行动之间的那层智能体中间件——输入是脏的（群消息、长文本、截图），输出是干净的（卡片、待办、提醒、有出处的答复），并且结果要能被"核对"，而不是让用户盲信一个黑盒。

4. 创新点与"杀手级功能"

编号	功能	状态	为什么是杀手级
K1	通知文本 → 结构化卡片（事项、截止、地点、材料、要做什么）	✅ 已实现	把"读通知"这个动作的认知成本降到接近零
K2	字段级原文溯源 + 置信度：每个字段都能点回原文那句，抽不准的地方自己标黄认输	✅ 已实现	这是"敢不敢用"的分水岭——AI 承认自己不确定，用户才敢信

| K3 | 三级提醒：提前 1 天 / 2 小时 / 10 分钟，同一档不会重复打扰 | ✅ 已实现 | 从"整理信息"跨到"真的别忘" |
| K4 | 有依据的答疑：只允许依据班级资料作答，答案带出处编号，查不到就说查不到 | ✅ 已实现 | 消灭"AI 一本正经胡说"，班委敢把它挂在群里 |

5. 技术方案

智能体分工（提示词编排，2 个 Agent 角色 + 1 层规则兜底）

角色	职责	关键设计
通知解析 Agent	从通知原文抽取结构化字段	强制 JSON 输出 + 字段级置信度 + evidence 必须逐字出现在原文，否则该字段丢弃
答疑 Agent	依据班级资料库回答办事问题	先做检索（资料表按字符重合度打分取 Top-4），提示词里写死"只允许依据给定资料，答不上就说不确定"，回答必须带"依据：第 N 条"
规则兜底	模型不可用/超时/返回残缺时顶上	正则抽取日期、地点、材料关键词；保证页面永远不会白屏，最差也给用户一段高亮原文

一次解析在代码里怎么走

1. 前端 app.js 把文本框内容 POST 到 /api/parse；
2. main.py 校验入参 → 调 llm.py 的 parse_notice()；
3. prompts.py 拼提示词（要求 JSON、要求 evidence 逐字复制）；
4. 调 DeepSeek deepseek-chat（解析用 temperature=0.1 求稳、答疑用 0.3 求自然；解析时加 response_format=json_object）；
5. 回来后逐字段校验：evidence 不在原文里 → 丢弃该字段；deadline 解析失败 → 置空并标"待确认"；
6. 整体置信度 = 关键字段平均，低于 0.75 前端标黄；
7. 入库 notices 表，并返回一个“建议待办”（标题 + 截止时间）；这里不建待办，要不要加由用户点「加入我的待办」决定；
8. 后端 scheduler.py 的守护线程每 60 秒扫一遍未完成待办，到点写入 reminders 表，前端每 30 秒轮询取走提醒。

技术栈（真实使用的，不是计划中的）

• 前端：原生 HTML + CSS + JavaScript 单页，无框架、无打包、无 npm；fetch 调接口，30 秒轮询提醒，esc() 转义防 XSS。
• 后端：Python 3.12 + FastAPI + uvicorn，16 个 REST 接口，Pydantic 做入参校验；后台用 threading 守护线程做定时扫描（不引入 Celery/Redis）。
• 数据：SQLite 单文件（5 张表：users / notices / tasks / reminders / kb），零安装零配置，备份就是拷贝一个 .db 文件。
• 模型：DeepSeek API（deepseek-chat），Key 只存在 .env，不进数据库、不进 Git。
• 部署：启动.bat 一键（自动建 venv、装依赖、起 uvicorn、开浏览器）；另有 Dockerfile + docker-compose.yml 单容器版本，数据卷持久化。

6. 可行性分析

维度	判断	依据 / 应对
技术可行性	高	全栈已在本机跑通，四条主链路实测通过；难点（结构化抽取准确率）有"Schema 约束 + evidence 校验 + 规则兜底"三重保险
时间可行性	高	MVP 在阶段 0 内完成，后续每次迭代都是增量；硬件是独立增量，失败不影响主线
成本可行性	高	DeepSeek 按量付费，一次解析约几百 tokens，班级规模（<200 人）月成本预计 < 30 元；开发期全本地，零云成本
数据与合规	中	只处理班级群内已公开的通知文本；不采集个人隐私；学生数据仅本班可见，删掉 .db 即彻底删除

---

三、需求分析

完整版《班小助 软件需求规格说明书》参照 GB/T 8567-2006 / GB/T 9385-2008 组织，包含迭代记录表、项目标志、思维导图、类图、功能描述、接口需求、数据字典与验收标准。
在线协作文档：【语雀/腾讯文档链接，待填】（团队协作区，含需求记录、迭代记录与验收记录）

1. 功能结构思维导图

2. 功能需求清单

编号	功能	所属端	优先级	状态	验收要点
FR-01	通知解析（长文本 → 结构化字段）	前后端	P0	✅	抽出事项、截止、地点、材料、要做什么；字段准确率 ≥ 90%
FR-02	通知卡片与字段级原文溯源	前端	P0	✅	每字段可查看原文出处；置信度 < 0.75 标"待确认"
FR-03	待办清单与完成打点（含编辑、删除）	前后端	P0	✅	卡片上点「加入我的待办」才创建（不想加就不加）；可编辑标题与时间、可删除、可勾选完成
FR-04	三级提醒	后端	P0	✅	提前 1 天 / 2 小时 / 10 分钟各一次；同一档不重复；可确认已读
FR-05	班级资料库维护（FAQ 增删改）	前后端	P0	✅	班委可新增/编辑/删除/查看资料；支持 seed 内置资料
FR-06	依据资料库的问答	后端	P0	✅	答案必须带出处；资料中没有时明确说"不确定"，不得编造
FR-07	截图 OCR 解析	前后端	P1	🔜 迭代 1	上传/粘贴截图，识别文字后走同一解析链路
FR-08	字段一键纠错并沉淀	前后端	P1	🔜 迭代 1	用户改正一个字段即生效，并计入纠错样本
FR-09	课表导入与周视图	前后端	P1	🔜 迭代 2	支持手动/导入课表，按周展示
FR-10	冲突检测与周计划	后端	P1	🔜 迭代 2	待办与课程冲突时提示；一句话生成本周安排
FR-11	事务办理引导（材料清单 + 申请文本）	前后端	P2	🔜 迭代 3	覆盖 5 个高频事务，产出可复制的申请文本

3. 核心领域模型（类图）

4. 关键流程时序图

主链路一共 11 步，全部已实现：粘贴文本 → 组装提示词 → 请求模型（JSON 模式）→ 逐字校验出处 → 入库（点一下才建待办）→ 卡片带置信度与原文高亮 → 守护线程每 60 秒写提醒 → 前端 30 秒轮询弹出三级提醒。答疑链路同理，只是把"解析提示词"换成"取资料库前 4 条再作答"。

5. 非功能需求

类别	要求
性能	单次解析 P95 ≤ 8s（实测 3～5s）；页面首屏 ≤ 1s；提醒扫描周期 60s，提醒可见延迟 ≤ 90s
可用性	模型超时/报错时自动降级到规则抽取，页面不白屏；数据库文件损坏可从备份恢复
安全	昵称+角色轻量身份（不存密码）；API Key 只在服务端 .env；全站 HTML 转义防 XSS；不做公网写入前需先做鉴权（已写入迭代 4 上线清单）
合规	仅处理班级群内公开通知；不采集个人隐私；删库即彻底删除
可维护	后端单文件职责清晰（config/db/prompts/llm/scheduler/main）；接口见文档《后端需求》；关键链路有日志
兼容	Chrome / Edge / Safari 最新两个大版本；移动端响应式（单列布局）

6. 验收标准

#	指标	目标值	验收方式	当前实测
1	通知字段抽取准确率	≥ 90%（时间/地点 ≥ 95%）	真实通知评测集逐条比对	样例通知整体置信度 0.95，字段 evidence 全部命中原文
2	卡片纠正率	≤ 10%	试点 2 周日志统计	待试点（当前 0 用户）
3	解析端到端耗时	P95 ≤ 8s	真实网络抽样	实测 3～5s
4	提醒生成延迟	≤ 90s（扫描周期 60s）	把待办截止时间改到 5 分钟后观察	✅ 60s 内生成 3 条提醒（1 天/2 小时/10 分钟）
5	提醒去重	同档提醒不重复	UNIQUE(task_id, level) + 重复扫描	✅ 多次扫描仍为 3 条
6	问答一次命中率	≥ 85%	多条真实提问评测	样例问题命中并给出"依据：班级资料第 1 条"
7	问答无出处率	0%（无依据必须说不知道）	抽查回答是否带出处	✅ 提示词强约束 + 检索为空时直接拒答
8	可运行性	双击 启动.bat 3 分钟内可用	助教现场检查	✅ 自动建 venv、装依赖、起服务、开浏览器

【腾讯文档】班小助-软件需求规格说明书
https://docs.qq.com/doc/DU25EeXJtaWRUTk93