feat: 添加附件上传中间件和管理功能

- 实现对话线程的附件上传、列出和删除功能
- 引入附件中间件以支持附件内容的上下文注入
- 更新智能体和对话管理器以处理附件元数据
- 增强前端组件以支持文件上传和显示附件状态
- 优化文档以反映新功能和使用示例

Author: xerrors

AGENTS.md

@@ -9,7 +9,7 @@ Yuxi-Know 是一个基于知识图谱和向量数据库的智能知识库系统
 
 本项目完全通过 Docker Compose 进行管理。所有开发和调试都应在运行的容器环境中进行。使用 `docker compose up -d` 命令进行构建和启动。
 
-核心原则: 由于 api-dev 和 web-dev 服务均配置了热重载 (hot-reloading)，本地修改代码后无需重启容器，服务会自动更新。应该先检查项目是否已经在后台启动（`docker ps`），具体的可以阅读 [docker-compose.yml](docker-compose.yml).
+核心原则: 由于 api-dev 和 web-dev 服务均配置了热重载 (hot-reloading)，本地修改代码后无需重启容器，服务会自动更新。应该先检查项目是否已经在后台启动（`docker ps`），查看日志（`docker logs api-dev --tail 100`）具体的可以阅读 [docker-compose.yml](docker-compose.yml).
 
 前端开发规范：
 
@@ -22,7 +22,7 @@ Yuxi-Know 是一个基于知识图谱和向量数据库的智能知识库系统
 后端开发规范：
 
 - 项目使用 uv 来管理依赖，所以需要使用 uv run 来调试。
-- Python 代码要符合 Python 的规范，尽量使用较新的语法，避免使用旧版本的语法（版本兼容到 3.12+），使用 make lint 检查 lint。使用 make format 来格式化代码。
+- Python 代码要符合 Python 的规范，符合 pythonic 风格，尽量使用较新的语法，避免使用旧版本的语法（版本兼容到 3.12+），使用 make lint 检查 lint。使用 make format 来格式化代码。
 
 其他：
 

docs/advanced/agents-config.md

@@ -52,7 +52,55 @@
 
 子智能体集中放在 `src/agents/common/subagents` 目录，典型例子是 `calc_agent`，它通过 LangChain 的 `create_agent` 构建计算器能力并以工具暴露给主图。新增子智能体时沿用这一结构：在目录内编写封装函数与 `@tool` 装饰器，导出后即可被任意智能体调用。
 
-中间件位于 `src/agents/common/middlewares`，包含上下文感知提示词、模型选择以及动态工具加载等实现。如果需要编写新的中间件，请遵循 LangChain 官方文档中对 `AgentMiddleware`、`ModelRequest`、`ModelResponse` 等接口的定义，完成后在该目录的 `__init__.py` 暴露入口，主智能体即可在 `middleware` 列表中引用。
+中间件位于 `src/agents/common/middlewares`，包含上下文感知提示词、模型选择、动态工具加载以及附件注入等实现。如果需要编写新的中间件，请遵循 LangChain 官方文档中对 `AgentMiddleware`、`ModelRequest`、`ModelResponse` 等接口的定义，完成后在该目录的 `__init__.py` 暴露入口，主智能体即可在 `middleware` 列表中引用。
+
+#### 文件上传中间件
+
+文件上传功能通过 `inject_attachment_context` 中间件实现（位于 `src/agents/common/middlewares/attachment_middleware.py`）。该中间件基于 LangChain 1.0 的 `AgentMiddleware` 标准实现，具有以下特点：
+
+1. **状态扩展**：定义 `AttachmentState` 扩展 `AgentState`，添加可选的 `attachments` 字段
+2. **自动注入**：在模型调用前，从 `request.state` 中读取附件并转换为 `SystemMessage`
+3. **向后兼容**：不使用文件上传的智能体不受影响
+
+##### 为智能体启用文件上传
+
+只需两步：
+
+**步骤 1：声明能力**（让前端显示上传按钮）
+
+```python
+class MyAgent(BaseAgent):
+    capabilities = ["file_upload"]
+```
+
+**步骤 2：添加中间件**（让智能体能够处理附件内容）
+
+```python
+from src.agents.common.middlewares import inject_attachment_context
+
+async def get_graph(self):
+    graph = create_agent(
+        model=load_chat_model("..."),
+        tools=get_tools(),
+        middleware=[
+            inject_attachment_context,  # 添加附件中间件
+            context_aware_prompt,       # 其他中间件...
+            # ...
+        ],
+        checkpointer=await self._get_checkpointer(),
+    )
+    return graph
+```
+
+##### 工作流程
+
+1. **前端上传**：用户在聊天界面上传文档（txt、md、docx、html）
+2. **API 解析**：后端将文档转换为 Markdown 格式并存储到数据库（超过 32k 会被截断）
+3. **自动加载**：API 层在调用 agent 前从数据库加载附件数据
+4. **中间件注入**：`inject_attachment_context` 自动将附件内容注入为系统消息
+5. **模型处理**：LLM 接收到附件内容和用户问题，进行综合回答
+
+这种设计确保了附件功能的可选性和可扩展性，任何智能体都可以通过添加中间件快速启用文件上传能力。
 
 ## 内置工具与 MCP 集成
 

docs/changelog/roadmap.md

@@ -18,6 +18,7 @@
 
 ### Bugs
 - 部分异常状态下，智能体的模型名称出现重叠[#279](https://github.com/xerrors/Yuxi-Know/issues/279)
+- 消息中断没有达到预期效果，看不到截断的消息
 
 ### 新增
 - 优化知识库详情页面，更加简洁清晰

server/routers/chat_router.py

@@ -2,9 +2,8 @@
 import json
 import traceback
 import uuid
-from pathlib import Path
 
-from fastapi import APIRouter, Body, Depends, HTTPException
+from fastapi import APIRouter, Body, Depends, HTTPException, UploadFile, File
 from fastapi.responses import StreamingResponse
 from langchain.messages import AIMessageChunk, HumanMessage
 from langgraph.types import Command
@@ -22,6 +21,12 @@
 from src.agents.common.tools import gen_tool_info, get_buildin_tools
 from src.models import select_model
 from src.plugins.guard import content_guard
+from src.services.doc_converter import (
+    ATTACHMENT_ALLOWED_EXTENSIONS,
+    MAX_ATTACHMENT_SIZE_BYTES,
+    convert_upload_to_markdown,
+)
+from src.utils.datetime_utils import utc_isoformat
 from src.utils.logging_config import logger
 
 chat = APIRouter(prefix="/chat", tags=["chat"])
@@ -156,6 +161,25 @@ def _save_tool_message(conv_mgr, msg_dict):
         logger.warning(f"Tool call {tool_call_id} not found for update")
 
 
+def _require_user_conversation(conv_mgr: ConversationManager, thread_id: str, user_id: str) -> Conversation:
+    conversation = conv_mgr.get_conversation_by_thread_id(thread_id)
+    if not conversation or conversation.user_id != str(user_id) or conversation.status == "deleted":
+        raise HTTPException(status_code=404, detail="对话线程不存在")
+    return conversation
+
+
+def _serialize_attachment(record: dict) -> dict:
+    return {
+        "file_id": record.get("file_id"),
+        "file_name": record.get("file_name"),
+        "file_type": record.get("file_type"),
+        "file_size": record.get("file_size", 0),
+        "status": record.get("status", "parsed"),
+        "uploaded_at": record.get("uploaded_at"),
+        "truncated": record.get("truncated", False),
+    }
+
+
 async def save_messages_from_langgraph_state(
     agent_instance,
     thread_id,
@@ -313,7 +337,8 @@ async def get_agent(current_user: User = Depends(get_required_user)):
             "description": agent_info.get("description", ""),
             "examples": agent_info.get("examples", []),
             "configurable_items": agent_info.get("configurable_items", []),
-            "has_checkpointer": agent_info.get("has_checkpointer", False)
+            "has_checkpointer": agent_info.get("has_checkpointer", False),
+            "capabilities": agent_info.get("capabilities", [])  # 智能体能力列表
         }
         for agent_info in agents_info
     ]
@@ -401,6 +426,15 @@ async def stream_messages():
         except Exception as e:
             logger.error(f"Error saving user message: {e}")
 
+        try:
+            assert thread_id, "thread_id is required"
+            attachments = conv_manager.get_attachments_by_thread_id(thread_id)
+            input_context["attachments"] = attachments
+            logger.debug(f"Loaded {len(attachments)} attachments for thread_id={thread_id}")
+        except Exception as e:
+            logger.error(f"Error loading attachments for thread_id={thread_id}: {e}")
+            input_context["attachments"] = []
+
         try:
             full_msg = None
             async for msg, metadata in agent.stream_messages(messages, input_context=input_context):
@@ -739,6 +773,26 @@ class ThreadResponse(BaseModel):
     updated_at: str
 
 
+class AttachmentResponse(BaseModel):
+    file_id: str
+    file_name: str
+    file_type: str | None = None
+    file_size: int
+    status: str
+    uploaded_at: str
+    truncated: bool | None = False
+
+
+class AttachmentLimits(BaseModel):
+    allowed_extensions: list[str]
+    max_size_bytes: int
+
+
+class AttachmentListResponse(BaseModel):
+    attachments: list[AttachmentResponse]
+    limits: AttachmentLimits
+
+
 # =============================================================================
 # > === 会话管理分组 ===
 # =============================================================================
@@ -859,6 +913,75 @@ async def update_thread(
     }
 
 
+@chat.post("/thread/{thread_id}/attachments", response_model=AttachmentResponse)
+async def upload_thread_attachment(
+    thread_id: str,
+    file: UploadFile = File(...),
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_required_user),
+):
+    """上传并解析附件为 Markdown，附加到指定对话线程。"""
+    conv_manager = ConversationManager(db)
+    conversation = _require_user_conversation(conv_manager, thread_id, str(current_user.id))
+
+    try:
+        conversion = await convert_upload_to_markdown(file)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except Exception as exc:  # noqa: BLE001
+        logger.error(f"附件解析失败: {exc}")
+        raise HTTPException(status_code=500, detail="附件解析失败，请稍后重试") from exc
+
+    attachment_record = {
+        "file_id": conversion.file_id,
+        "file_name": conversion.file_name,
+        "file_type": conversion.file_type,
+        "file_size": conversion.file_size,
+        "status": "parsed",
+        "markdown": conversion.markdown,
+        "uploaded_at": utc_isoformat(),
+        "truncated": conversion.truncated,
+    }
+    conv_manager.add_attachment(conversation.id, attachment_record)
+
+    return _serialize_attachment(attachment_record)
+
+
+@chat.get("/thread/{thread_id}/attachments", response_model=AttachmentListResponse)
+async def list_thread_attachments(
+    thread_id: str,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_required_user),
+):
+    """列出当前对话线程的所有附件元信息。"""
+    conv_manager = ConversationManager(db)
+    conversation = _require_user_conversation(conv_manager, thread_id, str(current_user.id))
+    attachments = conv_manager.get_attachments(conversation.id)
+    return {
+        "attachments": [_serialize_attachment(item) for item in attachments],
+        "limits": {
+            "allowed_extensions": sorted(ATTACHMENT_ALLOWED_EXTENSIONS),
+            "max_size_bytes": MAX_ATTACHMENT_SIZE_BYTES,
+        },
+    }
+
+
+@chat.delete("/thread/{thread_id}/attachments/{file_id}")
+async def delete_thread_attachment(
+    thread_id: str,
+    file_id: str,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_required_user),
+):
+    """移除指定附件。"""
+    conv_manager = ConversationManager(db)
+    conversation = _require_user_conversation(conv_manager, thread_id, str(current_user.id))
+    removed = conv_manager.remove_attachment(conversation.id, file_id)
+    if not removed:
+        raise HTTPException(status_code=404, detail="附件不存在或已被删除")
+    return {"message": "附件已删除"}
+
+
 # =============================================================================
 # > === 消息反馈分组 ===
 # =============================================================================

src/agents/chatbot/graph.py

@@ -2,7 +2,12 @@
 
 from src.agents.common import BaseAgent, load_chat_model
 from src.agents.common.mcp import MCP_SERVERS
-from src.agents.common.middlewares import DynamicToolMiddleware, context_aware_prompt, context_based_model
+from src.agents.common.middlewares import (
+    DynamicToolMiddleware,
+    context_aware_prompt,
+    context_based_model,
+    inject_attachment_context,
+)
 from src.agents.common.subagents import calc_agent_tool
 
 from .context import Context
@@ -12,6 +17,7 @@
 class ChatbotAgent(BaseAgent):
     name = "智能体助手"
     description = "基础的对话机器人，可以回答问题，默认不使用任何工具，可在配置中启用需要的工具。"
+    capabilities = ["file_upload"]  # 支持文件上传功能
 
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
@@ -44,6 +50,7 @@ async def get_graph(self, **kwargs):
             tools=get_tools(),  # 注册基础工具
             middleware=[
                 context_aware_prompt,  # 动态系统提示词
+                inject_attachment_context,  # 附件上下文注入（LangChain 标准中间件）
                 context_based_model,  # 动态模型选择
                 dynamic_tool_middleware,  # 动态工具选择（支持 MCP 工具注册）
             ],

src/agents/common/base.py

@@ -23,6 +23,7 @@ class BaseAgent:
 
     name = "base_agent"
     description = "base_agent"
+    capabilities: list[str] = []  # 智能体能力列表，如 ["file_upload", "web_search"] 等
 
     def __init__(self, **kwargs):
         self.graph = None  # will be covered by get_graph
@@ -54,6 +55,7 @@ async def get_info(self):
             "examples": metadata.get("examples", []),
             "configurable_items": self.context_schema.get_configurable_items(),
             "has_checkpointer": await self.check_checkpointer(),
+            "capabilities": getattr(self, "capabilities", []),  # 智能体能力列表
         }
 
     async def get_config(self):
@@ -70,18 +72,31 @@ async def stream_messages(self, messages: list[str], input_context=None, **kwarg
         context = self.context_schema.from_file(module_name=self.module_name, input_context=input_context)
         logger.debug(f"stream_messages: {context}")
         # TODO Checkpointer 似乎还没有适配最新的 1.0 Context API
+
+        # 从 input_context 中提取 attachments（如果有）
+        attachments = (input_context or {}).get("attachments", [])
         input_config = {"configurable": input_context, "recursion_limit": 100}
+
         async for msg, metadata in graph.astream(
-            {"messages": messages}, stream_mode="messages", context=context, config=input_config
+            {"messages": messages, "attachments": attachments},
+            stream_mode="messages",
+            context=context,
+            config=input_config,
         ):
             yield msg, metadata
 
     async def invoke_messages(self, messages: list[str], input_context=None, **kwargs):
         graph = await self.get_graph()
         context = self.context_schema.from_file(module_name=self.module_name, input_context=input_context)
         logger.debug(f"invoke_messages: {context}")
+
+        # 从 input_context 中提取 attachments（如果有）
+        attachments = (input_context or {}).get("attachments", [])
         input_config = {"configurable": input_context, "recursion_limit": 100}
-        msg = await graph.ainvoke({"messages": messages}, context=context, config=input_config)
+
+        msg = await graph.ainvoke(
+            {"messages": messages, "attachments": attachments}, context=context, config=input_config
+        )
         return msg
 
     async def check_checkpointer(self):
@@ -186,4 +201,4 @@ def load_metadata(self) -> dict:
         except Exception as e:
             logger.error(f"Error loading metadata for {self.module_name}: {e}")
             self._metadata_cache = {}
-            return {}
+            return {}

src/agents/common/middlewares/__init__.py

@@ -1,8 +1,10 @@
 from .context_middlewares import context_aware_prompt, context_based_model
 from .dynamic_tool_middleware import DynamicToolMiddleware
+from .attachment_middleware import inject_attachment_context
 
 __all__ = [
     "DynamicToolMiddleware",
     "context_aware_prompt",
     "context_based_model",
+    "inject_attachment_context",
 ]