# 企微交互 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 控制，代码中无硬编码密钥/模型名