文档：企微交互 Agent 多模态升级实施计划

docs/plans/2026-03-20-agent-multimodal-design.md

@@ -0,0 +1,129 @@
+# 企微交互 Agent 多模态升级实施计划
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 升级企微私聊 Agent，统一使用 VLM 模型处理文字+图片，支持图片上报工单、多轮对话、结单图片分析。
+
+**Architecture:** 在现有 AgentDispatcher 基础上：(1) 统一使用 VLM 替代 LLM+VLM 双模型；(2) 新增 SessionManager 管理每用户独立上下文（内存，10轮，10分钟TTL）；(3) 回调层增加图片消息处理；(4) 多轮状态机引导补充信息。
+
+**Tech Stack:** Python/FastAPI, OpenAI SDK (qwen3-vl-flash), httpx, 企微消息 API
+
+---
+
+## 改动范围
+
+| 文件 | 操作 | 说明 |
+|------|------|------|
+| `app/services/session_manager.py` | 新建 | 会话记忆管理器 |
+| `app/services/agent_dispatcher.py` | 重写 | 统一 VLM + 图片处理 + 状态机 |
+| `app/services/wechat_service.py` | 新增方法 | download_media 下载企微图片 |
+| `app/routers/wechat_callback.py` | 修改 | 增加图片消息路由 |
+| `app/config.py` | 修改 | AgentConfig 统一为 VLM |
+| `.env.example` | 修改 | 更新配置说明 |
+
+---
+
+### Task 1: 会话记忆管理器
+
+**Files:**
+- Create: `app/services/session_manager.py`
+
+每个用户独立会话，10 轮对话上限，10 分钟无活动自动过期。
+状态机支持：idle / waiting_location / waiting_confirm / waiting_close_photo
+
+---
+
+### Task 2: AgentConfig 统一为 VLM
+
+**Files:**
+- Modify: `app/config.py`
+- Modify: `.env.example`
+
+AgentConfig 改为：
+- `vlm_api_key`: API Key（从 DASHSCOPE_API_KEY 复用）
+- `vlm_base_url`: 接口地址
+- `vlm_model`: 统一模型名，默认 qwen3-vl-flash-2026-01-22
+- `vlm_timeout`: 超时时间
+- `enabled`: 是否启用
+
+去掉 llm_model / llm_base_url / llm_api_key，统一用 vlm 前缀。
+
+---
+
+### Task 3: 图片下载方法
+
+**Files:**
+- Modify: `app/services/wechat_service.py`
+
+新增 `download_media(media_id)` 方法：
+- 通过企微临时素材 API 下载图片
+- 返回 bytes，失败返回 None
+
+---
+
+### Task 4: AgentDispatcher 多模态重写
+
+**Files:**
+- Modify: `app/services/agent_dispatcher.py`
+
+核心改动：
+1. 使用 SessionManager 管理上下文
+2. 统一使用 VLM 模型（文字+图片都走同一个模型）
+3. handle_message 增加状态机检查
+4. 新增 handle_image 处理图片消息
+5. VLM 调用时传入完整 history（最近10轮）
+6. 图片分析、位置回复、结单分析等多轮流程
+
+VLM System Prompt:
+```
+你是物业安防AI助手。你可以：
+1. 分析用户上传的现场图片，识别异常情况
+2. 帮助创建安保工单
+3. 查询告警统计数据
+4. 分析处理结果图片，确认异常是否消除
+
+当用户发送图片时，分析图片内容并判断是否有安全隐患。
+如果有异常，描述异常情况并询问具体位置。
+回复简洁专业，不超过100字。
+```
+
+---
+
+### Task 5: 回调层支持图片消息
+
+**Files:**
+- Modify: `app/routers/wechat_callback.py`
+
+在 wechat_agent_message 中增加：
+- MsgType=image 时提取 MediaId，路由到 handle_image
+- 先回复"正在分析图片..."，再异步处理
+- 处理完成后主动发送分析结果
+
+---
+
+### Task 6: notify_dispatch 中的硬编码 VLM 模型名修复
+
+**Files:**
+- Modify: `app/services/notify_dispatch.py`
+
+第208行 `llm_model="qwen3-vl-flash"` 改为使用 config 中的 VLM_MODEL。
+
+---
+
+## 注意事项
+
+1. **企微回调 5 秒超时**：必须先返回 success，业务异步处理（已有此模式）
+2. **图片下载需 access_token**：通过 media/get API 下载临时素材
+3. **VLM 调用耗时 3-8 秒**：先回复"正在分析"让用户等待
+4. **图片 3 天过期**：下载后立即上传 COS 持久化
+5. **VLM 降级**：不可用时回复"图片分析暂不可用，请描述具体情况"
+6. **并发安全**：状态机防止同一用户重复处理
+
+## 验证清单
+
+- [ ] 员工私聊发图片 → 收到"正在分析"→ 收到分析结果 + 追问位置
+- [ ] 回复位置 → 工单创建成功
+- [ ] 纯文字"查询今日告警" → 返回统计（已有功能不受影响）
+- [ ] 10 分钟不操作 → 会话过期，下次从头开始
+- [ ] VLM 不可用 → 降级提示
+- [ ] 所有配置通过 .env 控制，代码中无硬编码密钥/模型名