摘要： 本周团队正式进入"交互与教学智能体"核心模块的代码落地阶段。本周的关键命题是：如何将前期设计的 5 个接口、3 条原则和"学—练—诊—反馈"教学闭环，高质量地转化为可运行、可测试、可维护的工程代码。三位组员分别聚焦于核心后端实现、全链路系统维护与智能体调试，最终完成了端到端闭环的代码级验证。

---

一、本周整体定位：从设计蓝图到代码落地

前两周团队已完成了基础设施搭建与最小可用闭环的骨架跑通。进入第三周，团队的核心任务已从"能否跑通"进阶为"代码质量与教学智能的工程化落地"。这一整块逻辑，即项目核心——交互与教学智能体的完整代码实现。

本周三位组员的分工与交付如下：

方向	负责人	本周交付
核心后端实现（AI 互动与教学）	我	交互与练习 5 大接口的代码落地、混合检索、三路批改等
全链路系统维护与部署	组员一	Nginx 代理调优、环境一致性与中间件监控、联调坑修复
智能体基础调试与评测	组员二	VLM、LLM 评分、诊断 Agent 初步调优与效果评测

三条线咬合成了一个完整的数据闭环：学生提问/练习 → AI 检索与生成 → 反馈与诊断 → 画像回流。下文将分方向详述本周成果。

二、核心后端实现：交互与教学智能体的代码落地（本人负责）

本周我专注将"智能互动与练习"模块的设计文档转化为工程代码，主要交付了 5 个接口的完整实现，并沉淀了几项关键技术决策。

2.1 整体包结构与 5 个接口的全貌

代码严格按照 controller → service → repository 的分层架构组织，清晰划分了职责。5 个接口的信息流向、流式策略与关键依赖关系如下，该表直接指导了后续的事务管理与异步化设计：

接口	流式	写表	关键依赖
/api/ai/chat	SSE	异步写 Redis 历史	RetrievalService、PromptBuilder
/api/ai/chat/multimodal	否	写 MinIO	ImagePreprocessor、VLM 模型
/api/exercises/next	否	不写	加权采样、画像服务
/api/exercises/submit	否	wrong_question + user_profile	GradingService
/api/exercises/targeted	否	不写	Neo4j 知识图谱

一个关键工程决策是将 LLM 调用严格置于数据库事务之外。由于 LLM 响应时间通常为 1~3 秒，若放入事务中会迅速耗尽数据库连接池。为此，submit 接口的批改逻辑被明确切分为两段：先调用 LLM 完成判分，再在事务内完成画像更新与错题记录写入。

2.2 关键技术实现细节

混合检索 (RetrievalService) 实现了自适应的 Top-K 召回与学科过滤。为避免向量数据库的 metadata filtering 损耗，采用"先召后过"的策略：扩召 topK * 3 条候选，在 Java 侧基于内存缓存进行课程过滤。这种设计利用了 pgvector 索引的高效性，同时规避了跨维过滤的性能问题。

提示词构建器 (PromptBuilder) 被设计为输入为数据、输出为字符串的纯函数。它不执行任何 IO 操作，极大地方便了单元测试和多模型灰度对比。Prompt 的最终结构严格包含五个段落：系统指令、学生画像、参考资料（为空时明确说明）、最近对话和当前问题。明确告知模型"未检索到资料"，能有效抑制其产生虚假引用。

SSE 流式事件设计 (AiChatServiceImpl) 基于 Spring MVC 的 SseEmitter 实现，针对 Nginx 反代缓冲问题，通过 SseEmitter(0L) 构造并立即发送 session 事件来强制 Http 流式头刷新。同时，定义了 session、references、delta、done、error 五种标准事件，前端能据此解耦引用卡片与回答内容的渲染逻辑。

三路批改 (GradingServiceImpl) 是保证"AI 不胡说"的核心。针对选择题采用 Set 相等比较，填空题优先精确匹配。对于主观题，通过将 LLM 的 temperature 参数调至 0.1，配合强约束的 Prompt，我们将同一份答案重复评分的一致性从 ±20 分大幅提升至 ±5 分以内（满分 100），AI 与人工抽检的一致率从约 60% 提升到了 88%。

专项练习图谱编排 (TargetedPracticeServiceImpl) 利用 Neo4j 中 PREREQUISITE_OF 关系的反向遍历，为每位学生构建出薄弱知识点的前置学习路径，并通过拓扑排序生成科学的学习顺序。

2.3 代码联调中的三个"坑"及级修复

坑一：SSE 在 Nginx 后被缓冲。 Nginx 默认开启代理缓冲，会导致流式信息被截断等待，需要显式关闭 proxy_buffering 并设置 HTTP/1.1 长连接头。

坑二：多模态成本失控。 通过 ImagePreprocessor 强制将图片长边压缩至 1280px 并重编码为 JPEG，在保持识别准确率的同时，图像 Token 消耗降低了约 60%。

坑三：知识点别名导致跨库联查失败。 引入 KnowledgePointNormalizer，将所有模型输出或用户输入的别名（如“快排”、“QuickSort”）统一归一化为图谱中的标准名称（如“快速排序”）。

三、全链路系统维护与智能体调试（组员负责）

本周另外两位组员的工作，是核心模块能够稳定、高性能运行的关键保障。

3.1 系统维护与稳定性建设（组员一负责）

组员一本周负责维护开发、测试与生产镜像环境的统一性，并重点解决了线上部署的性能瓶颈。

• Nginx 反代与 SSE 协议适配：定位并解决了上述 SSE 缓冲问题，为 AI 流式对话的流畅体验打下了基础。

• 中间件监控与调优：对 PostgreSQL、Redis、Neo4j 的连接池与慢查询进行了基线监控。尤其针对 Redis 的异步历史写入，确保了高并发下连接不被耗尽。

• CI/CD 流水线优化：将新增模块的构建纳入了自动化流水线。

3.2 智能体初步调试与效果评测（组员二负责）

组员二本周的工作重心，是确保"智能"部分的输出质量，为后续 Agent 能力升级积累基准数据。

• VLM 多模态识别调试：针对印刷体公式、图表等核心场景，对 VLM 的 Prompt 进行调优，并编写了解析结果的"剥壳"降级逻辑，确保在模型返回格式不标准时系统依然可用。当前印刷体识别置信度平均值达到 0.87。

• AI 批改一致性评测：构建了包含 50 组标准答案的学生作答数据集，系统性地评测了不同 temperature 参数下的评分稳定性，得出了 temperature=0.1 为最佳实践的结论。

• 诊断 Agent 基线跑通：初步接入了能识别错误类型的基础诊断逻辑，为下周升级做准备。

四、阶段成果自检与数据汇总

本周代码落地工作结束后，团队对照需求进行了严格自检：

指标	需求	第三周实际
接口数	5 个	5 个 ✅
文本问答首字延迟	< 1 秒	约 0.6 秒
RAG 召回切片数	≥ 3 个	3~8 个自适应 ✅
多模态识别置信度（印刷体）	≥ 0.7	平均 0.87
AI 批改与人工抽检一致率	≥ 80%	88%
接口对原项目侵入性	越小越好	0 改动（仅新增模块） ✅

五、共性问题与心得

本周的共性问题依然是模块边界的"协议错位"，尤其在 SSE 流式输出、画像缓存清理、知识点别名等方面。根因与上两周一致：双方技术细节的默认行为不一致。

为此，团队进一步强化了"契约优先"的原则。所有组员在开发联调前，必须就将要调用的接口的请求/响应体、SSE 事件类型、错误码、知识点标准名等写入文档中进行对齐。这是项目能高效推进最宝贵的工程经验。

六、下周计划

代码闭环已完整跑通，下周我们将把重心从"稳固基础"转向"注入智慧"。

1. 诊断 Agent 正式接入：将本周粗粒度的掌握度更新，升级为“识别错误类型 → 定位错因知识点 → 生成结构化诊断报告”的完整路径。

2. 规划 Agent 开发：基于沉淀的练习数据，实现每日学习计划的自动生成。

3. 前端能力地图升级：利用更丰富的画像数据，让首页的能力趋势图与学习热力图实时反映真实学情。