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