feat(multimodal): 完整实现多模态图片支持功能

1. 后端：
   - 添加图片上传接口 /api/chat/image/upload
   - 在消息处理中支持图片内容
   - 更新数据库模型和迁移脚本
   - 实现图片处理工具类

2. 前端：
   - 添加图片上传和预览组件
   - 支持多模态消息发送
   - 更新消息显示以支持图片
   - 集成图片上传API

3. 文档：
   - 更新agents-config.md添加多模态图片支持说明
   - 更新roadmap.md添加多模态支持计划

主要功能包括：
- 支持JPEG、PNG、WebP、GIF、BMP等格式
- 图片大小限制为10MB
- 自动处理图片格式转换和压缩
- 支持单图片上传
- 图片以base64编码存储在数据库

Author: xerrors

docs/latest/advanced/agents-config.md

@@ -123,3 +123,29 @@ MYSQL_CHARSET=utf8mb4
 ```
 
 所有查询限定在只读范围（SELECT、SHOW、DESCRIBE、EXPLAIN），请求会经过表名校验与超时控制，默认限制 60 秒与 100 行输出，并可通过配置调整上限。连接信息会反馈给 LangGraph，智能体可以自动陈述数据库用途并选择更准确的检索策略。
+
+### 多模态图片支持
+
+系统支持接收图片作为输入，与文本结合形成多模态查询。图片支持的核心特性如下：
+
+#### 1. 图片上传与处理
+- 通过 `/chat/image/upload` 接口上传图片
+- 自动处理图片格式转换和压缩
+- 返回 base64 编码的图片数据
+- 图片大小限制为 10MB
+- 支持的图片格式：JPEG、PNG、WebP、GIF、BMP
+- 自动压缩超过 5MB 的图片
+
+当发送包含图片的请求时，消息格式为：
+```json
+{
+  "query": "这张图片里有什么？",
+  "image_content": "<base64编码的图片数据>",
+  "config": {},
+  "meta": {}
+}
+```
+
+智能体会自动识别多模态消息并将其传递给支持图片的模型。如果模型不支持图片，会自动忽略图片内容，只处理文本部分。系统会将图片转换为符合模型要求的格式（通常是 base64 编码的 JPEG 或 PNG），确保与主流多模态模型兼容。
+
+目前仅支持上传单个图片，图片直接以 base64 存储在数据库

docs/latest/changelog/roadmap.md

@@ -22,6 +22,7 @@
 - 优化知识库详情页面，更加简洁清晰
 - 新增对于上传文件的智能体中间件
 - 增强文件下载功能
+- 新增多模态模型支持（当前仅支持图片，详见文档）
 
 ### 修复
 - 修复重排序模型实际未生效的问题

server/routers/chat_router.py

@@ -28,6 +28,21 @@
 )
 from src.utils.datetime_utils import utc_isoformat
 from src.utils.logging_config import logger
+from src.utils.image_processor import process_uploaded_image
+
+
+# 图片上传响应模型
+class ImageUploadResponse(BaseModel):
+    success: bool
+    image_content: str | None = None
+    thumbnail_content: str | None = None
+    width: int | None = None
+    height: int | None = None
+    format: str | None = None
+    mime_type: str | None = None
+    size_bytes: int | None = None
+    error: str | None = None
+
 
 chat = APIRouter(prefix="/chat", tags=["chat"])
 
@@ -391,13 +406,18 @@ async def chat_agent(
     query: str = Body(...),
     config: dict = Body({}),
     meta: dict = Body({}),
+    image_content: str | None = Body(None),
     current_user: User = Depends(get_required_user),
     db: Session = Depends(get_db),
 ):
     """使用特定智能体进行对话（需要登录）"""
     start_time = asyncio.get_event_loop().time()
 
     logger.info(f"agent_id: {agent_id}, query: {query}, config: {config}, meta: {meta}")
+    logger.info(f"image_content present: {image_content is not None}")
+    if image_content:
+        logger.info(f"image_content length: {len(image_content)}")
+        logger.info(f"image_content preview: {image_content[:50]}...")
 
     # 确保 request_id 存在
     if "request_id" not in meta or not meta.get("request_id"):
@@ -410,6 +430,7 @@ async def chat_agent(
             "server_model_name": config.get("model", agent_id),
             "thread_id": config.get("thread_id"),
             "user_id": current_user.id,
+            "has_image": bool(image_content),
         }
     )
 
@@ -423,8 +444,32 @@ def make_chunk(content=None, **kwargs):
         )
 
     async def stream_messages():
-        # 代表服务端已经收到了请求
-        yield make_chunk(status="init", meta=meta, msg=HumanMessage(content=query).model_dump())
+        # 构建多模态消息
+        if image_content:
+            # 多模态消息格式
+            human_message = HumanMessage(
+                content=[
+                    {"type": "text", "text": query},
+                    {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image_content}"}},
+                ]
+            )
+            message_type = "multimodal_image"
+        else:
+            # 普通文本消息
+            human_message = HumanMessage(content=query)
+            message_type = "text"
+
+        # 代表服务端已经收到了请求，发送前端友好的消息格式
+        init_msg = {"role": "user", "content": query, "type": "human"}
+
+        # 如果有图片，添加图片相关信息
+        if image_content:
+            init_msg["message_type"] = "multimodal_image"
+            init_msg["image_content"] = image_content
+        else:
+            init_msg["message_type"] = "text"
+
+        yield make_chunk(status="init", meta=meta, msg=init_msg)
 
         # Input guard
         if conf.enable_content_guard and await content_guard.check(query):
@@ -438,7 +483,7 @@ async def stream_messages():
             yield make_chunk(message=f"Error getting agent {agent_id}: {e}", status="error")
             return
 
-        messages = [{"role": "user", "content": query}]
+        messages = [human_message]
 
         # 构造运行时配置，如果没有thread_id则生成一个
         user_id = str(current_user.id)
@@ -458,8 +503,9 @@ async def stream_messages():
                 thread_id=thread_id,
                 role="user",
                 content=query,
-                message_type="text",
-                extra_metadata={"raw_message": HumanMessage(content=query).model_dump()},
+                message_type=message_type,
+                image_content=image_content,
+                extra_metadata={"raw_message": human_message.model_dump()},
             )
         except Exception as e:
             logger.error(f"Error saving user message: {e}")
@@ -543,6 +589,9 @@ async def stream_messages():
         except Exception as e:
             logger.error(f"Error streaming messages: {e}, {traceback.format_exc()}")
 
+            error_msg = f"Error streaming messages: {e}"
+            error_type = "unexpected_error"
+
             # 保存错误消息到数据库
             new_db = db_manager.get_session()
             try:
@@ -551,13 +600,13 @@ async def stream_messages():
                     new_conv_manager,
                     thread_id,
                     full_msg=full_msg,
-                    error_message=f"Error streaming messages: {e}" if not full_msg else None,
-                    error_type="unexpected_error",
+                    error_message=error_msg if not full_msg else None,
+                    error_type=error_type,
                 )
             finally:
                 new_db.close()
 
-            yield make_chunk(message=f"Error streaming messages: {e}", status="error")
+            yield make_chunk(message=error_msg, status="error")
 
     return StreamingResponse(stream_messages(), media_type="application/json")
 
@@ -766,6 +815,8 @@ async def get_agent_history(
                 "content": msg.content,
                 "created_at": msg.created_at.isoformat() if msg.created_at else None,
                 "error_type": msg.extra_metadata.get("error_type") if msg.extra_metadata else None,
+                "message_type": msg.message_type,  # 添加消息类型字段
+                "image_content": msg.image_content,  # 添加图片内容字段
             }
 
             # Add tool calls if present (for AI messages)
@@ -1143,3 +1194,47 @@ async def get_message_feedback(
     except Exception as e:
         logger.error(f"Error getting message feedback: {e}")
         raise HTTPException(status_code=500, detail=f"Failed to get feedback: {str(e)}")
+
+
+# =============================================================================
+# > === 多模态图片支持分组 ===
+# =============================================================================
+
+
+@chat.post("/image/upload", response_model=ImageUploadResponse)
+async def upload_image(file: UploadFile = File(...), current_user: User = Depends(get_required_user)):
+    """
+    上传并处理图片，返回base64编码的图片数据
+    """
+    try:
+        # 验证文件类型
+        if not file.content_type or not file.content_type.startswith("image/"):
+            raise HTTPException(status_code=400, detail="只支持图片文件上传")
+
+        # 读取文件内容
+        image_data = await file.read()
+
+        # 检查文件大小（10MB限制，超过后会压缩到5MB）
+        if len(image_data) > 10 * 1024 * 1024:
+            raise HTTPException(status_code=400, detail="图片文件过大，请上传小于10MB的图片")
+
+        # 处理图片
+        result = process_uploaded_image(image_data, file.filename)
+
+        if not result["success"]:
+            raise HTTPException(status_code=400, detail=f"图片处理失败: {result['error']}")
+
+        logger.info(
+            f"用户 {current_user.id} 成功上传图片: {file.filename}, "
+            f"尺寸: {result['width']}x{result['height']}, "
+            f"格式: {result['format']}, "
+            f"大小: {result['size_bytes']} bytes"
+        )
+
+        return ImageUploadResponse(**result)
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"图片上传处理失败: {str(e)}, {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=f"图片处理失败: {str(e)}")

server/utils/migrate.py

@@ -258,6 +258,14 @@ def get_migrations(self) -> list[tuple[int, str, list[str]]]:
 
         migrations.append((2, "为用户表添加软删除字段", v2_commands))
 
+        # 迁移 v3: 为 messages 表添加多模态图片支持
+        v3_commands: list[str] = []
+
+        if not self.check_column_exists("messages", "image_content"):
+            v3_commands.append("ALTER TABLE messages ADD COLUMN image_content TEXT")
+
+        migrations.append((3, "为消息表添加多模态图片支持字段", v3_commands))
+
         # 未来的迁移可以在这里添加
         # migrations.append((
         #     2,
@@ -305,6 +313,17 @@ def validate_database_schema(db_path: str) -> tuple[bool, list[str]]:
                 "deleted_at",
             ],
             "operation_logs": ["id", "user_id", "operation", "details", "ip_address", "timestamp"],
+            "messages": [
+                "id",
+                "conversation_id",
+                "role",
+                "content",
+                "message_type",
+                "created_at",
+                "token_count",
+                "extra_metadata",
+                "image_content",
+            ],
         }
 
         for table_name, fields in required_fields.items():

src/storage/conversation/manager.py

@@ -109,6 +109,7 @@ def add_message(
         content: str,
         message_type: str = "text",
         extra_metadata: dict | None = None,
+        image_content: str | None = None,
     ) -> Message:
         """
         Add a message to a conversation
@@ -117,8 +118,9 @@ def add_message(
             conversation_id: Conversation ID
             role: Message role (user/assistant/system/tool)
             content: Message content
-            message_type: Message type (text/tool_call/tool_result)
+            message_type: Message type (text/tool_call/tool_result/multimodal_image)
             extra_metadata: Additional metadata (complete message dump)
+            image_content: Base64 encoded image content for multimodal messages
 
         Returns:
             Created Message object
@@ -129,6 +131,7 @@ def add_message(
             content=content,
             message_type=message_type,
             extra_metadata=extra_metadata or {},
+            image_content=image_content,
         )
 
         self.db.add(message)
@@ -153,6 +156,7 @@ def add_message_by_thread_id(
         content: str,
         message_type: str = "text",
         extra_metadata: dict | None = None,
+        image_content: str | None = None,
     ) -> Message | None:
         """
         Add a message to a conversation by thread ID
@@ -161,8 +165,9 @@ def add_message_by_thread_id(
             thread_id: Thread ID
             role: Message role (user/assistant/system/tool)
             content: Message content
-            message_type: Message type (text/tool_call/tool_result)
+            message_type: Message type (text/tool_call/tool_result/multimodal_image)
             extra_metadata: Additional metadata (complete message dump)
+            image_content: Base64 encoded image content for multimodal messages
 
         Returns:
             Created Message object or None if conversation not found
@@ -178,6 +183,7 @@ def add_message_by_thread_id(
             content=content,
             message_type=message_type,
             extra_metadata=extra_metadata,
+            image_content=image_content,
         )
 
     def add_tool_call(

src/storage/db/models.py

@@ -69,6 +69,7 @@ class Message(Base):
     created_at = Column(DateTime, default=utc_now, comment="Creation time")
     token_count = Column(Integer, nullable=True, comment="Token count (optional)")
     extra_metadata = Column(JSON, nullable=True, comment="Additional metadata (complete message dump)")
+    image_content = Column(Text, nullable=True, comment="Base64 encoded image content for multimodal messages")
 
     # Relationships
     conversation = relationship("Conversation", back_populates="messages")
@@ -91,6 +92,7 @@ def format_utc_datetime(dt_value):
             "created_at": format_utc_datetime(self.created_at),
             "token_count": self.token_count,
             "metadata": self.extra_metadata or {},
+            "image_content": self.image_content,
             "tool_calls": [tc.to_dict() for tc in self.tool_calls] if self.tool_calls else [],
         }