团队项目第一次作业
作业所属课程：https://edu.cnblogs.com/campus/gdgy/Class56-Grade2024-CS
作业要求：https://edu.cnblogs.com/campus/gdgy/Class56-Grade2024-CS/homework/16766
仓库地址：https://github.com/dredgeship/dredgeship/tree/main/3124004048/assignment5
成员： 车俊贤3124004048 钟志浩3124004076
作业的目标：
本次作业要求我们自选一个真实、有价值的场景，开发一个"智能体 / 多智能体"驱动的软件，
并把智能体真正嵌入到软件系统内部，而不是做成一个聊天窗口套壳；最终要上线运行、可被检查，
并通过课上答辩 + 博客两部分呈现"团队展示 + 选题报告 + 需求分析"。
我们理解的重点有三个：
① 选题要来自真实调研（有真实用户、真实痛点），不能是自己臆想的"伪需求"；
② 智能体要成为系统的能力内核，具备"感知—规划—调用工具—反馈"的闭环，而不是单次问答；
③ 要有杀手级功能 —— 让人看一眼就记住的那个东西。
团队名称：【书脉 BookPulse】
团队成员学号-名字：【3124004048 车俊贤 3124004076 钟志浩】
一、团队展示
1. 队名
【书脉 BookPulse】
取名含义：知识像血脉一样在书里流动，"脉"也指脉络——把一本书的章节、知识点、学习进度串成一条可触摸的脉络。
2. 团队项目的具体规划及描述
项目定位：AI 专注伴读助手。
面向阅读专业教材、技术文档时容易走神、难以持续理解内容的大学生，把一本书转化为有明确目标、循序渐进、可交互的学习过程。
- 知识梳理工具解决的是：内容太多，我怎么整理？
- 我们解决的是：内容太多，我怎么持续读下去，并真正理解？
我们不宣称软件能让人进入心流（心流受环境、兴趣、难度影响，不是应用能保证的）。我们只做四件可控的事：
降低开始的门槛、降低一次需要处理的信息量、明确当前该干什么、及时给出反馈。
杀手级功能：互动式专注伴读模式。 一轮 15–25 分钟，一条线走完五步：
① 规划本轮目标 选中"二叉树"一章 → 系统只说本轮只需读懂这 4 个知识点（约 20 分钟）
② 一屏一个知识点 只展示：知识点名 + 3 行简释 + 教材原文片段（带页码）
底部只有两个按钮：[我懂了] [我不确定]
（"我不确定"只会换一种讲法，不给答案，防止用户偷懒跳过）
③ 用自己的话讲 不展示标准答案，先要求用户"讲给一个没学过的人听"
④ 按缺口追问 系统指出"你提到了 A、B，漏了 C（教材 P87 第 2 段）"，
然后只针对最基础的那个缺口追问，最多三层；三层仍讲不出则降级为直接讲解
⑤ 留下学习状态 汇总本轮学了什么、哪几个概念"还讲不清"、下次从哪个知识点继续
这条流程把三个原本分离的问题连了起来：不知道怎么开始 → 读的过程中失去思路 → 读完无法判断是否真的理解。
围绕主流程的四项支撑能力：
| 能力 | 做什么 | 关键设计 |
|---|---|---|
| 文档解析与规划 | 导入 PDF / txt，识别章节结构，抽取知识点与参考要点 | 层级优先取书本 TOC，回退到标题正则 + 模型补全；每个知识点带页码锚点 |
| 章节结构导图 | 按章节层级生成结构图，作为知识导航 | 只做"可信的结构图"，不做模型臆测的概念关系图；节点可点回原文 |
| 选择题变式出题 | 依据书中例题与知识点生成变式题，判分并给解析 | 变式算子：改数值、改条件、反向提问；每题带原文依据页码 |
| 学习状态持久化 | 每本书独立保存章节、进度、复述记录、作答记录、断点 | 中断后重开，直接回到上次的知识点继续，不需要重新规划路线 |
关于"理解程度"的判断，我们的态度是克制的：
系统不给用户打"掌握度分数"。模型判断一个人是否真懂并不可靠。我们只保存三个独立维度，UI 上分开显示：
| 维度 | 含义 | 显示 |
|---|---|---|
| 阅读进度 | 读到哪了 | 章节进度条 |
| 讲清度 | 能不能用自己的话讲清 | 三档：没读过 / 讲不清 / 讲得清 |
| 作答表现 | 题做对没 | 对错率（不做推断） |
复述判定也不靠模型自由打分：知识点抽取时先生成 3–5 个"参考要点"，复述时只判定"这句话有没有提到第 N 个要点"，输出的是缺失项和教材页码，不是分数。用户可以点回去自己核对，AI 的判断只是提示，不是判决。
多书隔离：每本书是独立工作区，章节、进度、复述与作答记录互不干扰。
团队项目的愿景
一本好教材配一位肯问"你懂了吗"的人，本该是标配，但现实中它是稀缺资源。
我们希望把"陪读、复述、追问、指出遗漏"这件事智能体化：让只有一本书、没人督促的学生，
也能有一个记得住他上次卡在哪、会针对他反问的伴读者。知识不该因为没人陪着读完而停在纸面上。
二、需求分析
1. 迭代记录表
| 迭代 | 时间 | 目标 | 主要交付物 | 状态 |
|---|---|---|---|---|
| Sprint 0 | 10/27 - 10/29 | 调研 + 解析管线 | 用户访谈记录、PDF/txt 解析、章节树、数据库 schema | ✅ 完成 |
| Sprint 1 | 10/30 - 11/02 | 伴读主流程 | 知识点抽取（含参考要点+页码）、会话状态机（读→复述→追问）、前端骨架、EPUB 按小节解析 | ✅ 完成（EPUB 提前到这一阶段） |
| Sprint 2 | 11/03 - 11/05 | 检验与导航 | 章节结构导图、变式出题、学习进度与两类证据、知识点编辑 | ✅ 完成 |
| Sprint 3 | 11/06 - 11/08 | 闭环 + 上线 | 本轮小结与断点续读、内网穿透上线、演示录屏、博客 | 🔄 进行中 |
| Sprint 4 | 11/09 - 11/15 | 答辩后补齐 | 变式题多题缓存、总览页状态筛选、全书视图、复习提醒 | ⏳ 待开始 |
调整说明：原计划把 EPUB 放到 Sprint 4，实际提前到 Sprint 1。原因是章节切分效果太差（PDF 转 txt 后正则猜标题，一章被切得七零八落），而 EPUB 自带 spine 和目录结构，用它验证"按原文结构切分"这个假设成本最低。这个决定后来成了整个项目的转折点——见下方「质量验证」。
2. 项目标志（Logo）
【放 Logo 图】设计说明：一本书的书脊弯曲成脉搏线（心电波形），寓意"书的脉络"与"读活知识"。
3. 思维导图
4. 类图
5. 功能描述
| 用例 | Actor | 前置条件 | 主流程 | 异常流 |
|---|---|---|---|---|
| UC-01 导入书籍 | 学生 | 已选择文件 | 上传 → 格式校验 → 解析 → 生成章节树 → 落库 | 加密 PDF / 扫描件 → 提示需 OCR，进入降级模式 |
| UC-02 开始伴读会话 | 学生 | 书籍解析完成 | 选章节 → 系统生成"本轮 N 个知识点 / 预估时长" → 进入第一个知识点 | 该章未抽取知识点 → 先按需抽取，展示进度 |
| UC-03 逐屏阅读 | 学生 | 会话进行中 | 展示知识点名 + 简释 + 原文片段(页码) → 学生点[我懂了] 或 [我不确定] | 连续 2 次[我不确定] → 降级为最小步骤讲解 |
| UC-04 换一种讲法 | 学生 | 点了[我不确定] | 用类比/反例/更小的一步重讲，不直接给答案 | 3 次仍不确定 → 提示"先跳过，本轮结束再回看" |
| UC-05 复述并判定 | 学生 | 点[我懂了] | 学生用自己话复述 → 系统判要点覆盖 → 输出"提到/遗漏"清单 + 页码 | 复述为空或无关 → 提示重新组织，不计入判定 |
| UC-06 缺口追问 | 学生 | 存在遗漏要点 | 挑最基础的缺口追问 → 学生回答 → 最多 3 层 | 3 层仍不足 → 降级为直接讲解并标记"待澄清" |
| UC-07 查看原文溯源 | 学生 | 存在锚点 | 点页码/要点 → 定位原文 → 高亮片段 | 原文抽取失败 → 展示文本片段并标注"原文不可用" |
| UC-08 本轮小结与断点 | 学生 | 会话结束 | 汇总本轮知识点、讲清度、下次起点 → 落库 | 会话中断 → 下次打开从最后一步恢复 |
| UC-09 章节结构导图 | 学生 | 章节树存在 | 选范围 → 渲染结构图 → 点节点回到对应知识点 | 章节识别失败 → 提示手动校正章节 |
| UC-10 变式出题与判分 | 学生 | 该章有知识点/例题 | 选题型数量 → 生成 → 作答 → 判分 + 解析(带页码) | 生成内容无原文依据 → 丢弃重生成 |
| UC-11 多书切换 | 学生 | 多本书 | 切换工作区 → 数据隔离展示 | — |
6. 验收标准
| 编号 | 验收项 | 标准 | 实测 |
|---|---|---|---|
| A1 | 解析性能 | 300 页 PDF 解析 + 章节树生成 ≤ 90 秒 | ✅ 19 万字 EPUB 全量解析 12 秒 |
| A2 | 章节识别准确率 | 对 5 本测试教材，章节标题召回 ≥ 90% | ✅ 《智能计算系统》19 节全部识别，其中 9 节带完整小节路径 |
| A3 | 单轮会话时长 | 一轮完整会话（4 个知识点）可控制在 15–25 分钟内完成 | ✅ 按预计耗时切分，实测 18~22 分钟 |
| A4 | 同屏信息量 | 阅读态每屏只呈现 1 个知识点 | ✅ |
| A5 | 要点判定可解释 | 输出"提到 / 遗漏"要点清单 + 教材原文，不允许只输出分数 | ✅ 且每条判断带 evidence 引文 |
| A6 | 溯源覆盖率 | 核心知识点 100% 带可点击原文锚点 | ✅ 399 个核心知识点全部带引文（另有 69 个辅助材料不进伴读） |
| A7 | 追问深度 | 至少能连续追问 3 层；3 层失败降级为讲解 | ✅ 程序层硬校验追问靶子必须是当前缺口 |
| A8 | 断点续读 | 关闭后重开，自动恢复到上次未完成的知识点 | ✅ |
| A9 | 多书隔离 | 3 本书并行，数据零串扰 | ✅ |
| A10 | 可用性 | 首次使用者 3 分钟内完成"导入→会话→复述一次" | ⚠️ 未做用户测试，待补 |
| A11 | 部署 | 提供可访问地址 + 本地一键启动脚本 | ✅ python run.py + cloudflared 隧道 |
| A12 | 判定质量（新增） | 不把"没讲清"判成"讲清" | ✅ 56 条样本上假阳性 0 例 |
7. 质量验证
7.1 为什么单独做评测
这个产品只有一件事不能错：把"没讲清"判成"讲清"。
判错一次，用户就跳过这个知识点，漏洞被永久放过，而他还以为自己懂了。其他环节出错都只是体验问题，只有这一处出错会让产品失去意义。
所以我们没有停在"看着挺准"，而是做了一套可复现的评测。
7.2 样本怎么来的
纯人工写 56 条复述，成本太高且容易写成"标准答案腔"；纯模型生成，又控制不住"到底漏了哪一条"。
采用的分工是：规则定意图，模型写措辞，人工定标签。
| 步骤 | 谁做 |
|---|---|
| 决定这条样本覆盖哪些要点、漏哪条、把哪条讲错 | 程序（从 key_points 里选） |
| 把要点清单变成学生口吻的复述 | 大模型 |
| 检查生成的复述是否符合预设意图 | 程序初筛 + 人工逐条审核 |
| 最终标签 | 人工 |
覆盖六类真实表达：
| 类型 | 例子 | 期望 |
|---|---|---|
| 完整 | 要点讲全 | complete |
| 含糊但正确 | 用自己的话说，措辞和教材完全不同 | complete |
| 只念术语 | "就是 MFU、VFU、SFU 这三个，嗯，就这些" | partial |
| 长篇缺因果 | 铺垫很多，就是没讲那层因果 | partial |
| 因果讲反 | 把"A 决定 B"说成"B 决定 A" | incorrect |
| 答非所问 / 太短 | "就是卷一下" | off_topic / too_short |
7.3 怎么防止"自己调参自己报"
36 条开发集（第 3 章 + 第 7 章，14 个知识点）
→ 允许反复跑、反复改 prompt
↓ prompt 定稿
20 条独立测试集（第 2 章，5 个全新知识点，零重叠）
→ 只跑一次，不改参数，不回头修样本
知识点用脚本校验过交集为 0。
7.4 结果
| 指标 | 开发集（36 条） | 独立测试集（20 条） |
|---|---|---|
| 假阳性（没讲清判成讲清） | 0.0% | 0.0% |
| 假阴性（讲清判成没讲清） | 0.0% | 0.0% |
| 二分类准确率（通过 / 没通过） | 100% | 100% |
| 四分类完全一致 | 91.2% | 88.9% |
| 要点级缺口定位 F1 | 93.6% | 92.3% |
off_topic 检出 |
2/2 | 2/2 |
两批差距只有 1.3 个百分点，说明开发集的数字不是调出来的。
四分类不一致的那几条，全部是"漏了要点"被判成"说得太少"——两条路都会触发追问，用户不会被跳过，所以二分类是 100%。
7.5 一个没预料到的发现
56 条样本里，出现过 3 次"模型判对、人工标错"：
| 样本 | 人工标 | 实际 | 为什么标错 |
|---|---|---|---|
| 卷积运算 | partial，漏"矩阵内积" | complete | 复述说"对应位置乘起来再加到一起"，人没认成"内积" |
| 矩阵乘向量单元 | partial，漏"内积单元叠加" | complete | 复述说"把内积单元堆起来"，人没认成"叠加构成" |
| 感知机损失函数 | incorrect，公式讲错 | complete | 复述公式与原文逐字一致，内容太长没细看 |
三次都是人在找原文措辞，找不到就判漏。
这反过来说明模型的判法是可靠的：它不是"猜"，而是逐条引用用户原话作为证据（evidence 字段）。人反而容易被措辞差异骗。
这个发现让我们确认了一件事：评定标准必须写成判据，而不是凭感觉。现在每道判定都会输出"引用了你哪句话"，用户可以自己核对。
浙公网安备 33010602011771号