XW-AIOT/iot-device-management-service
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2dccb75dcbeaffe49cb12e929ee80c1417cde5f5
iot-device-management-service/docs/plans/2026-03-20-agent-multimodal-design.md

4.2 KiB
Raw Blame History

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