一.项目1.1 项目定位EmailAgentMailFriend是一个基于LangGraph AgentMiddleware的智能邮件助手系统核心目标是通过自然语言对话完成邮箱认证、收件检查、邮件发送演示 LangGraph 中间件机制动态工具选择 动态提示词切换提供类 ChatGPT 的 SSE 流式交互体验1.2 技术栈层级技术选型版本/配置LLMDashScope qwen3.7-plusOpenAI 兼容模式Agent 框架LangGraph create_agent AgentMiddlewarelangchain1.3.14Web 框架FastAPI uvicornfastapi0.141.1前端原生 HTML/CSS/JS无框架SSE ReadableStream数据库SQLite 3sessions messages 两表CheckpointerInMemorySaver不跨重启持久化可观测性LangSmith Tracing已接入1.3 核心功能当前全为 mock#功能工具函数当前实现真实需要1邮箱认证authenticate(email, password)硬编码xxxqq.com/123456数据库查询 bcrypt 哈希2检查收件箱check_email()固定返回 No new emailsIMAP 协议拉取真实邮件3发送邮件send_email(email, subject, body)固定返回 Email sent successfullySMTP 协议真实发送1.4 项目效果二.问题解决汇总核心问题详解2.1 会话发起无响应SSE 无回应 — 后端三个叠加 Bug修改前 # Bug 1 — 错误 key event_type chunk.get(event_type) # 永远 None # Bug 2 — yield dict yield {event: message, data: payload} # Bug 3 — 路由内 new router.post(/stream) async def chat_stream(request): agent EmailAgent() return StreamingResponse(agent.generate_sse(...))2.1.1 chunk key 混淆LangGraph v2 的 stream chunk 结构为{type: messages|updates, ns: [...], data: ...}最初代码用chunk.get(event_type)取事件类型但正确的 key 是type。event_type永远返回None所有 chunk 都被跳过。2.1.2 yield 格式不符合 SSE 规范FastAPIStreamingResponse期望的是字符串/字节。yield dict 后被str()转成{event: message, ...}Python repr 格式前端JSON.parse全部失败。2.1.3 路由每次新建空实例EmailAgent()是空壳——self.agent和self.checkpointer都是None。虽然generate_sse内部有if not self.agent: await self.init()兜底但每次请求都重新初始化意味着 checkpointer 不共享、对话状态不保留。修改后 # Bug 1 — 正确 key event_type chunk.get(type) # messages | updates # Bug 2 — yield SSE 格式字符串 yield fdata: {json.dumps({event: message, data: payload}, ensure_asciiFalse)}\n\n # Bug 3 — 使用 lifespan 单例 from app.agents.email_agent import email_agent # 模块级单例 router.post(/stream) async def chat_stream(request: ChatRequest): return StreamingResponse( email_agent.generate_sse( thread_idrequest.thread_id, messagerequest.message or , interrupt_decisionrequest.interrupt_decision, ), media_typetext/event-stream, )2.2 电子邮件密码均正确但未收到回复原本使用thinking 模型延迟 40s → 首响应极慢模型首 token 延迟适用场景决策qwen3-vl-32b-thinking20-40s深度推理、代码生成❌ 不适合 SSE 聊天qwen3.7-plus~2s通用对话、指令跟随✅ 选定qwen-plus~1s轻量对话备选2.3 邮件显示成功发送但实际该邮箱并未收到架构机制是成品业务功能是空壳。Middleware 动态工具选择 动态提示词 SSE 流式三件套已跑通但 authenticate/check_email/send_email 三个核心工具全是 mock需要分别接入数据库认证、IMAP、SMTP 才能真正可用。