feat(agent): support file attachments and local file replies

app/modules/telegram/__init__.py

@@ -215,18 +215,20 @@ class TelegramModule(_ModuleBase, _MessageBase[Telegram]):
 
         images = self._extract_images(msg)
         audio_refs = self._extract_audio_refs(msg)
+        files = self._extract_files(msg)
 
         if user_id:
-            if not text and not images and not audio_refs:
+            if not text and not images and not audio_refs and not files:
                 logger.debug(
-                    f"收到来自 {client_config.name} 的Telegram消息无文本、图片和语音"
+                    f"收到来自 {client_config.name} 的Telegram消息无文本、图片、语音和文件"
                 )
                 return None
 
             logger.info(
                 f"收到来自 {client_config.name} 的Telegram消息："
                 f"userid={user_id}, username={user_name}, chat_id={chat_id}, text={text}, "
-                f"images={len(images) if images else 0}, audios={len(audio_refs) if audio_refs else 0}"
+                f"images={len(images) if images else 0}, audios={len(audio_refs) if audio_refs else 0}, "
+                f"files={len(files) if files else 0}"
             )
 
             cleaned_text = (
@@ -266,6 +268,7 @@ class TelegramModule(_ModuleBase, _MessageBase[Telegram]):
                 chat_id=str(chat_id) if chat_id else None,
                 images=images if images else None,
                 audio_refs=audio_refs if audio_refs else None,
+                files=files if files else None,
             )
         return None
 
@@ -311,6 +314,29 @@ class TelegramModule(_ModuleBase, _MessageBase[Telegram]):
 
         return audio_refs if audio_refs else None
 
+    @staticmethod
+    def _extract_files(msg: dict) -> Optional[List[CommingMessage.MessageAttachment]]:
+        """
+        从 Telegram 消息中提取非图片文件附件。
+        """
+        document = msg.get("document")
+        if not isinstance(document, dict):
+            return None
+
+        file_id = document.get("file_id")
+        mime_type = (document.get("mime_type") or "").lower()
+        if not file_id or mime_type.startswith("image/"):
+            return None
+
+        return [
+            CommingMessage.MessageAttachment(
+                ref=f"tg://document_file_id/{file_id}",
+                name=document.get("file_name"),
+                mime_type=document.get("mime_type"),
+                size=document.get("file_size"),
+            )
+        ]
+
     @staticmethod
     def _embed_entity_links(text: str, entities: Optional[List[dict]]) -> str:
         """
@@ -412,7 +438,16 @@ class TelegramModule(_ModuleBase, _MessageBase[Telegram]):
                     return
             client: Telegram = self.get_instance(conf.name)
             if client:
-                if message.voice_path:
+                if message.file_path:
+                    client.send_file(
+                        file_path=message.file_path,
+                        file_name=message.file_name,
+                        title=message.title,
+                        text=message.text,
+                        userid=userid,
+                        original_chat_id=message.original_chat_id,
+                    )
+                elif message.voice_path:
                     client.send_voice(
                         voice_path=message.voice_path,
                         userid=userid,

app/modules/telegram/telegram.py

@@ -507,6 +507,70 @@ class Telegram:
             except Exception as cleanup_err:
                 logger.debug(f"清理语音临时文件失败: {cleanup_err}")
 
+    def send_file(
+            self,
+            file_path: str,
+            userid: Optional[str] = None,
+            title: Optional[str] = None,
+            text: Optional[str] = None,
+            file_name: Optional[str] = None,
+            original_chat_id: Optional[str] = None,
+    ) -> Optional[dict]:
+        """
+        发送本地图片或文件给 Telegram 用户。
+        """
+        if not self._bot or not file_path:
+            return None
+
+        local_file = Path(file_path)
+        if not local_file.exists() or not local_file.is_file():
+            logger.error(f"附件文件不存在: {local_file}")
+            return {"success": False}
+
+        chat_id = self._determine_target_chat_id(userid, original_chat_id)
+        send_name = file_name or local_file.name
+        suffix = local_file.suffix.lower()
+        is_image = suffix in {".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp"}
+
+        try:
+            bold_title = (
+                f"**{standardize(title).removesuffix('\n')}**" if title else None
+            )
+            if bold_title and text:
+                caption = f"{bold_title}\n{text}"
+            elif bold_title:
+                caption = bold_title
+            else:
+                caption = text or ""
+
+            with local_file.open("rb") as fp:
+                if is_image:
+                    sent = self._bot.send_photo(
+                        chat_id=chat_id,
+                        photo=fp,
+                        caption=standardize(caption) if caption else None,
+                        parse_mode="MarkdownV2" if caption else None,
+                    )
+                else:
+                    sent = self._bot.send_document(
+                        chat_id=chat_id,
+                        document=(send_name, fp),
+                        caption=standardize(caption) if caption else None,
+                        parse_mode="MarkdownV2" if caption else None,
+                    )
+            self._stop_typing_task(chat_id)
+            if sent and hasattr(sent, "message_id"):
+                return {
+                    "success": True,
+                    "message_id": sent.message_id,
+                    "chat_id": sent.chat.id if hasattr(sent, "chat") else chat_id,
+                }
+            return {"success": bool(sent)}
+        except Exception as err:
+            logger.error(f"发送本地附件失败: {err}")
+            self._stop_typing_task(chat_id)
+            return {"success": False}
+
     def _determine_target_chat_id(
             self, userid: Optional[str] = None, original_chat_id: Optional[str] = None
     ) -> str: