更新 version.py

- 为文件读取操作明确指定 UTF-8 编码
- 防止因默认编码导致的字符读取错误
- 确保跨平台环境下的文件内容一致性

.github/workflows/build.yml

@@ -14,6 +14,9 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
 
       - name: Release version
         id: release_version
@@ -66,6 +69,98 @@ jobs:
           cache-from: type=gha, scope=${{ github.workflow }}-docker
           cache-to: type=gha, scope=${{ github.workflow }}-docker
 
+      - name: Generate Changelog
+        id: changelog
+        run: |
+          # 获取上一个 tag（排除当前版本的 tag）
+          PREVIOUS_TAG=$(git tag -l 'v*' --sort=-v:refname | grep -v "^v${{ env.app_version }}$" | head -n 1)
+          echo "Previous tag: $PREVIOUS_TAG"
+
+          # 使用 || 作为分隔符，同时获取 commit 消息和作者 GitHub 用户名
+          if [ -z "$PREVIOUS_TAG" ]; then
+            COMMITS=$(git log --pretty=format:"%s||%an" HEAD)
+          else
+            COMMITS=$(git log --pretty=format:"%s||%an" ${PREVIOUS_TAG}..HEAD)
+          fi
+
+          # 分类收集 commit 消息（使用关联数组去重）
+          declare -A SEEN
+          FEATURES=""
+          FIXES=""
+          OTHERS=""
+
+          while IFS= read -r line; do
+            # 跳过空行
+            if [ -z "$line" ]; then
+              continue
+            fi
+
+            # 分离 commit 消息和作者
+            msg=$(echo "$line" | sed 's/||[^|]*$//')
+            author=$(echo "$line" | sed 's/.*||//')
+
+            # 跳过 Merge commit 和版本更新 commit
+            if echo "$msg" | grep -qE "^Merge pull request|^Merge branch|^更新 version"; then
+              continue
+            fi
+
+            # 按 Conventional Commits 前缀分类
+            if echo "$msg" | grep -qiE "^feat(\(.+\))?:"; then
+              desc=$(echo "$msg" | sed -E 's/^feat(\([^)]*\))?:\s*//')
+              category="FEATURES"
+            elif echo "$msg" | grep -qiE "^fix(\(.+\))?:"; then
+              desc=$(echo "$msg" | sed -E 's/^fix(\([^)]*\))?:\s*//')
+              category="FIXES"
+            elif echo "$msg" | grep -qiE "^(docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?:"; then
+              desc=$(echo "$msg" | sed -E 's/^(docs|style|refactor|perf|test|build|ci|chore|revert)(\([^)]*\))?:\s*//')
+              category="OTHERS"
+            else
+              desc="$msg"
+              category="OTHERS"
+            fi
+
+            # 使用 "分类+描述" 作为去重的 key，跳过重复内容
+            dedup_key="${category}::${desc}"
+            if [ -n "${SEEN[$dedup_key]+x}" ]; then
+              continue
+            fi
+            SEEN[$dedup_key]=1
+
+            # 添加 by @author 引用
+            entry="- ${desc} by @${author}"
+
+            case "$category" in
+              FEATURES) FEATURES="${FEATURES}${entry}\n" ;;
+              FIXES)    FIXES="${FIXES}${entry}\n" ;;
+              OTHERS)   OTHERS="${OTHERS}${entry}\n" ;;
+            esac
+          done <<< "$COMMITS"
+
+          # 组装 changelog
+          CHANGELOG=""
+
+          if [ -n "$FEATURES" ]; then
+            CHANGELOG="${CHANGELOG}### ✨ 新功能\n\n${FEATURES}\n"
+          fi
+
+          if [ -n "$FIXES" ]; then
+            CHANGELOG="${CHANGELOG}### 🐛 修复\n\n${FIXES}\n"
+          fi
+
+          if [ -n "$OTHERS" ]; then
+            CHANGELOG="${CHANGELOG}### 🔧 其他\n\n${OTHERS}\n"
+          fi
+
+          # 添加版本对比链接
+          if [ -n "$PREVIOUS_TAG" ]; then
+            CHANGELOG="${CHANGELOG}**完整更新记录**: https://github.com/${{ github.repository }}/compare/${PREVIOUS_TAG}...v${{ env.app_version }}"
+          fi
+
+          # 写入环境变量
+          echo "CHANGELOG<<EOF" >> $GITHUB_ENV
+          echo -e "$CHANGELOG" >> $GITHUB_ENV
+          echo "EOF" >> $GITHUB_ENV
+
       - name: Get existing release body
         id: get_release_body
         continue-on-error: true
@@ -73,9 +168,17 @@ jobs:
           release_body=$(curl -s -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
             "https://api.github.com/repos/${{ github.repository }}/releases/tags/v${{ env.app_version }}" | \
             jq -r '.body // ""')
-          echo "RELEASE_BODY<<EOF" >> $GITHUB_ENV
-          echo "$release_body" >> $GITHUB_ENV
-          echo "EOF" >> $GITHUB_ENV
+
+          # 如果已有手动编写的 release body，则保留；否则使用自动生成的 changelog
+          if [ -n "$release_body" ] && [ "$release_body" != "null" ] && [ "$release_body" != "" ]; then
+            echo "RELEASE_BODY<<EOF" >> $GITHUB_ENV
+            echo "$release_body" >> $GITHUB_ENV
+            echo "EOF" >> $GITHUB_ENV
+          else
+            echo "RELEASE_BODY<<EOF" >> $GITHUB_ENV
+            echo "${{ env.CHANGELOG }}" >> $GITHUB_ENV
+            echo "EOF" >> $GITHUB_ENV
+          fi
 
       - name: Delete Release
         uses: dev-drprasad/delete-tag-and-release@v1.1

.github/workflows/issues.yml

@@ -29,4 +29,5 @@ jobs:
          days-before-pr-close: -1
          # 排除带有RFC标签的issue
          exempt-issue-labels: "RFC"
+         operations-per-run: 500
          repo-token: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -26,6 +26,11 @@
 
 官方Wiki：https://wiki.movie-pilot.org
 
+### 为 AI Agent 添加 Skills
+```shell
+npx skills add https://github.com/jxxghp/MoviePilot
+```
+
 ## 参与开发
 
 API文档：https://api.movie-pilot.org

app/agent/callback/__init__.py

@@ -1,39 +1,340 @@
+import asyncio
 import threading
+from typing import Optional, Tuple
 
-from langchain_core.callbacks import AsyncCallbackHandler
-
+from app.chain import ChainBase
 from app.log import logger
+from app.schemas import Notification
+from app.schemas.message import (
+    MessageResponse,
+    ChannelCapabilityManager,
+    ChannelCapability,
+)
+from app.schemas.types import MessageChannel
 
 
-class StreamingCallbackHandler(AsyncCallbackHandler):
+class _StreamChain(ChainBase):
+    pass
+
+
+class StreamingHandler:
     """
-    流式输出回调处理器
+    流式Token缓冲管理器
+
+    负责从 LLM 流式 token 中积累文本，并在支持消息编辑的渠道上实时推送给用户。
+
+    工作流程：
+    1. Agent开始处理时调用 start_streaming()，检查渠道能力并启动定时刷新
+    2. LLM 产生 token 时调用 emit() 积累到缓冲区
+    3. 定时器周期性调用 _flush()：
+       - 第一次有内容时发送新消息（通过 send_direct_message 获取 message_id）
+       - 后续有新内容时编辑同一条消息（通过 edit_message）
+       - 当消息长度接近渠道限制时，冻结当前消息并发送新消息继续输出
+    4. 工具调用时：
+       - 流式渠道：工具消息直接 emit() 追加到 buffer，与 Agent 文字合并为同一条流式消息
+       - 非流式渠道：调用 take() 取出已积累的文字，与工具消息合并独立发送
+    5. Agent最终完成时调用 stop_streaming()：执行最后一次刷新，
+       返回是否已通过流式发送完所有内容（调用方据此决定是否还需额外发送）
     """
 
-    def __init__(self, session_id: str):
+    # 流式输出的刷新间隔（秒）
+    FLUSH_INTERVAL = 1.0
+
+    def __init__(self):
         self._lock = threading.Lock()
-        self.session_id = session_id
-        self.current_message = ""
+        self._buffer = ""
+        # 流式输出相关状态
+        self._streaming_enabled = False
+        self._flush_task: Optional[asyncio.Task] = None
+        # 当前消息的发送信息（用于编辑消息）
+        self._message_response: Optional[MessageResponse] = None
+        # 已发送给用户的文本（用于追踪增量）
+        self._sent_text = ""
+        # 当前消息的起始偏移量（buffer 中属于当前消息的起始位置）
+        self._msg_start_offset = 0
+        # 当前渠道的单条消息最大长度（0 表示不限制）
+        self._max_message_length = 0
+        # 消息发送所需的上下文信息
+        self._channel: Optional[str] = None
+        self._source: Optional[str] = None
+        self._user_id: Optional[str] = None
+        self._username: Optional[str] = None
+        self._title: str = ""
 
-    async def get_message(self):
+    def emit(self, token: str):
         """
-        获取当前消息内容，获取后清空
+        接收 LLM 流式 token，积累到缓冲区。
         """
         with self._lock:
-            if not self.current_message:
+            # 如果存量消息结束是两个换行，则去掉新消息前面的换行，避免过多空行
+            if self._buffer.endswith("\n\n") and token.startswith("\n"):
+                token = token.lstrip("\n")
+            self._buffer += token
+
+    async def take(self) -> str:
+        """
+        获取当前已积累的消息内容，获取后清空缓冲区。
+
+        用于非流式渠道：工具调用前取出 Agent 已产出的文字，
+        与工具提示合并后独立发送。
+
+        注意：流式渠道不调用此方法，工具消息直接 emit 到 buffer 中。
+        """
+        with self._lock:
+            if not self._buffer:
                 return ""
-            msg = self.current_message
-            logger.info(f"Agent消息: {msg}")
-            self.current_message = ""
-            return msg
+            message = self._buffer
+            logger.info(f"Agent消息: {message}")
+            self._buffer = ""
+            return message
 
-    async def on_llm_new_token(self, token: str, **kwargs):
+    def clear(self):
         """
-        处理新的token
+        清空缓冲区（不返回内容）
         """
-        if not token:
-            return
         with self._lock:
-            # 缓存当前消息
-            self.current_message += token
+            self._buffer = ""
+            self._sent_text = ""
+            self._message_response = None
+            self._msg_start_offset = 0
 
+    async def start_streaming(
+        self,
+        channel: Optional[str] = None,
+        source: Optional[str] = None,
+        user_id: Optional[str] = None,
+        username: Optional[str] = None,
+        title: str = "",
+    ):
+        """
+        启动流式输出。检查渠道是否支持消息编辑，如果支持则启动定时刷新任务。
+        :param channel: 消息渠道
+        :param source: 消息来源
+        :param user_id: 用户ID
+        :param username: 用户名
+        :param title: 消息标题
+        """
+        self._channel = channel
+        self._source = source
+        self._user_id = user_id
+        self._username = username
+        self._title = title
+
+        # 检查渠道是否支持消息编辑
+        if not self._can_stream():
+            logger.debug(f"渠道 {channel} 不支持消息编辑，不启用流式输出")
+            return
+
+        self._streaming_enabled = True
+        self._sent_text = ""
+        self._message_response = None
+        self._msg_start_offset = 0
+
+        # 从渠道能力中获取单条消息最大长度
+        try:
+            channel_enum = MessageChannel(self._channel)
+            self._max_message_length = ChannelCapabilityManager.get_max_message_length(
+                channel_enum
+            )
+        except (ValueError, KeyError):
+            self._max_message_length = 0
+
+        # 启动异步定时刷新任务
+        self._flush_task = asyncio.create_task(self._flush_loop())
+        logger.debug("流式输出已启动")
+
+    async def stop_streaming(self) -> Tuple[bool, str]:
+        """
+        停止流式输出。执行最后一次刷新确保所有内容都已发送。
+        :return: (all_sent, final_text)
+                 all_sent: 是否已经通过流式编辑将最终完整内容发送给了用户
+                           （True 表示调用方无需再额外发送消息）
+                 final_text: 流式发送的完整文本内容（用于调用方保存消息记录）
+        """
+        if not self._streaming_enabled:
+            return False, ""
+
+        self._streaming_enabled = False
+
+        # 取消定时任务
+        await self._cancel_flush_task()
+
+        # 执行最后一次刷新
+        await self._flush()
+
+        # 检查是否所有缓冲内容都已发送
+        with self._lock:
+            # 当前消息的文本 = buffer 中从 _msg_start_offset 开始的部分
+            current_msg_text = self._buffer[self._msg_start_offset :]
+            all_sent = (
+                self._message_response is not None
+                and self._sent_text
+                and current_msg_text == self._sent_text
+            )
+            # 保留最终文本用于返回（返回完整 buffer 内容，包含所有分段消息）
+            final_text = self._buffer if all_sent else ""
+            # 重置状态
+            self._sent_text = ""
+            self._message_response = None
+            self._msg_start_offset = 0
+            if all_sent:
+                # 所有内容已通过流式发送，清空缓冲区
+                self._buffer = ""
+            return all_sent, final_text
+
+    def _can_stream(self) -> bool:
+        """
+        检查当前渠道是否支持流式输出（消息编辑）
+        """
+        if not self._channel:
+            return False
+        try:
+            channel_enum = MessageChannel(self._channel)
+            return ChannelCapabilityManager.supports_capability(
+                channel_enum, ChannelCapability.MESSAGE_EDITING
+            )
+        except (ValueError, KeyError):
+            return False
+
+    async def _flush_loop(self):
+        """
+        定时刷新循环，定期将缓冲区内容发送/编辑到用户
+        """
+        try:
+            while self._streaming_enabled:
+                await asyncio.sleep(self.FLUSH_INTERVAL)
+                if self._streaming_enabled:
+                    await self._flush()
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            logger.error(f"流式刷新异常: {e}")
+
+    async def _cancel_flush_task(self):
+        """
+        取消当前的定时刷新任务
+        """
+        if self._flush_task and not self._flush_task.done():
+            self._flush_task.cancel()
+            try:
+                await self._flush_task
+            except asyncio.CancelledError:
+                pass
+            self._flush_task = None
+
+    async def _flush(self):
+        """
+        将当前缓冲区内容刷新到用户消息
+        - 如果还没有发送过消息，先发送一条新消息并记录message_id
+        - 如果已经发送过消息，编辑该消息为最新的完整内容
+        - 如果当前消息内容超过长度限制，冻结当前消息并发送新消息继续输出
+        """
+        with self._lock:
+            # 当前消息的文本 = buffer 中从 _msg_start_offset 开始的部分
+            current_text = self._buffer[self._msg_start_offset :]
+            if not current_text or current_text == self._sent_text:
+                # 没有新内容需要刷新
+                return
+
+        chain = _StreamChain()
+
+        try:
+            if self._message_response is None:
+                # 第一次发送：发送新消息并获取 message_id
+                response = chain.send_direct_message(
+                    Notification(
+                        channel=self._channel,
+                        source=self._source,
+                        userid=self._user_id,
+                        username=self._username,
+                        title=self._title,
+                        text=current_text,
+                    )
+                )
+                if response and response.success and response.message_id:
+                    self._message_response = response
+                    with self._lock:
+                        self._sent_text = current_text
+                    logger.debug(
+                        f"流式输出初始消息已发送: message_id={response.message_id}"
+                    )
+                else:
+                    logger.debug(
+                        "流式输出初始消息发送失败或未返回message_id，降级为非流式输出"
+                    )
+                    self._streaming_enabled = False
+            else:
+                # 检查当前消息内容是否超过长度限制
+                if (
+                    self._max_message_length
+                    and len(current_text) > self._max_message_length
+                ):
+                    # 消息过长，冻结当前消息（保持最后一次成功编辑的内容）
+                    # 将 offset 移动到已发送文本之后，开启新消息
+                    logger.debug(
+                        f"流式消息长度 {len(current_text)} 超过限制 {self._max_message_length}，启用新消息"
+                    )
+                    with self._lock:
+                        self._msg_start_offset += len(self._sent_text)
+                        current_text = self._buffer[self._msg_start_offset :]
+                    self._message_response = None
+                    self._sent_text = ""
+
+                    # 如果偏移后还有新内容，立即发送为新消息
+                    if current_text:
+                        response = chain.send_direct_message(
+                            Notification(
+                                channel=self._channel,
+                                source=self._source,
+                                userid=self._user_id,
+                                username=self._username,
+                                title=self._title,
+                                text=current_text,
+                            )
+                        )
+                        if response and response.success and response.message_id:
+                            self._message_response = response
+                            with self._lock:
+                                self._sent_text = current_text
+                            logger.debug(
+                                f"流式输出新消息已发送: message_id={response.message_id}"
+                            )
+                        else:
+                            logger.debug("流式输出新消息发送失败，降级为非流式输出")
+                            self._streaming_enabled = False
+                else:
+                    # 后续更新：编辑已有消息
+                    try:
+                        channel_enum = MessageChannel(self._channel)
+                    except (ValueError, KeyError):
+                        return
+
+                    success = chain.edit_message(
+                        channel=channel_enum,
+                        source=self._message_response.source,
+                        message_id=self._message_response.message_id,
+                        chat_id=self._message_response.chat_id,
+                        text=current_text,
+                        title=self._title,
+                    )
+                    if success:
+                        with self._lock:
+                            self._sent_text = current_text
+                    else:
+                        logger.debug("流式输出消息编辑失败")
+        except Exception as e:
+            logger.error(f"流式输出刷新失败: {e}")
+
+    @property
+    def is_streaming(self) -> bool:
+        """
+        是否正在流式输出
+        """
+        return self._streaming_enabled
+
+    @property
+    def has_sent_message(self) -> bool:
+        """
+        是否已经通过流式输出发送过消息（当前轮次）
+        """
+        return self._message_response is not None

app/agent/memory/__init__.py

@@ -1,17 +1,17 @@
 """对话记忆管理器"""
 
 import asyncio
-import json
-from datetime import datetime, timedelta
-from typing import Dict, List, Optional, Any
+from datetime import datetime
+from typing import Dict, List, Optional
+
+from langchain_core.messages import BaseMessage
 
 from app.core.config import settings
-from app.helper.redis import AsyncRedisHelper
 from app.log import logger
 from app.schemas.agent import ConversationMemory
 
 
-class ConversationMemoryManager:
+class MemoryManager:
     """
     对话记忆管理器
     """
@@ -19,18 +19,18 @@ class ConversationMemoryManager:
     def __init__(self):
         # 内存中的会话记忆缓存
         self.memory_cache: Dict[str, ConversationMemory] = {}
-        # 使用现有的Redis助手
-        self.redis_helper = AsyncRedisHelper()
-        # 内存缓存清理任务（Redis通过TTL自动过期）
+        # 内存缓存清理任务
         self.cleanup_task: Optional[asyncio.Task] = None
 
-    async def initialize(self):
+    def initialize(self):
         """
         初始化记忆管理器
         """
         try:
             # 启动内存缓存清理任务（Redis通过TTL自动过期）
-            self.cleanup_task = asyncio.create_task(self._cleanup_expired_memories())
+            self.cleanup_task = asyncio.create_task(
+                self._cleanup_expired_memories()
+            )
             logger.info("对话记忆管理器初始化完成")
 
         except Exception as e:
@@ -47,8 +47,6 @@ class ConversationMemoryManager:
             except asyncio.CancelledError:
                 pass
 
-        await self.redis_helper.close()
-
         logger.info("对话记忆管理器已关闭")
 
     @staticmethod
@@ -58,258 +56,64 @@ class ConversationMemoryManager:
         """
         return f"{user_id}:{session_id}" if user_id else session_id
 
-    @staticmethod
-    def _get_redis_key(session_id: str, user_id: str):
-        """
-        计算Redis Key
-        """
-        return f"agent_memory:{user_id}:{session_id}" if user_id else f"agent_memory:{session_id}"
-
-    def _get_memory(self, session_id: str, user_id: str):
+    def get_memory(self, session_id: str, user_id: str) -> Optional[ConversationMemory]:
         """
         获取内存中的记忆
         """
         cache_key = self._get_memory_key(session_id, user_id)
         return self.memory_cache.get(cache_key)
-    
-    async def _get_redis(self, session_id: str, user_id: str) -> Optional[ConversationMemory]:
-        """
-        从Redis获取记忆
-        """
-        if settings.CACHE_BACKEND_TYPE == "redis":
-            try:
-                redis_key = self._get_redis_key(session_id, user_id)
-                memory_data = await self.redis_helper.get(redis_key, region="AI_AGENT")
-                if memory_data:
-                    memory_dict = json.loads(memory_data) if isinstance(memory_data, str) else memory_data
-                    memory = ConversationMemory(**memory_dict)
-                    return memory
-            except Exception as e:
-                logger.warning(f"从Redis加载记忆失败: {e}")
-        return None
 
-    async def get_conversation(self, session_id: str, user_id: str) -> ConversationMemory:
-        """
-        获取会话记忆
-        """
-        # 首先检查缓存
-        conversion = self._get_memory(session_id, user_id)
-        if conversion:
-            return conversion
-
-        # 尝试从Redis加载
-        memory = await self._get_redis(session_id, user_id)
-        if memory:
-            # 加载到内存缓存
-            self._save_memory(memory)
-            return memory
-
-        # 创建新的记忆
-        memory = ConversationMemory(session_id=session_id, user_id=user_id)
-        await self._save_conversation(memory)
-
-        return memory
-
-    async def set_title(self, session_id: str, user_id: str, title: str):
-        """
-        设置会话标题
-        """
-        memory = await self.get_conversation(session_id=session_id, user_id=user_id)
-        memory.title = title
-        memory.updated_at = datetime.now()
-        await self._save_conversation(memory)
-
-    async def get_title(self, session_id: str, user_id: str) -> Optional[str]:
-        """
-        获取会话标题
-        """
-        memory = await self.get_conversation(session_id=session_id, user_id=user_id)
-        return memory.title
-
-    async def list_sessions(self, user_id: str, limit: int = 100) -> List[Dict[str, Any]]:
-        """
-        列出历史会话摘要（按更新时间倒序）
-
-        - 当启用Redis时：遍历 `agent_memory:*` 键并读取摘要
-        - 当未启用Redis时：基于内存缓存返回
-        """
-        sessions: List[ConversationMemory] = []
-        # 从Redis遍历
-        if settings.CACHE_BACKEND_TYPE == "redis":
-            try:
-                # 使用Redis助手的items方法遍历所有键
-                async for key, value in self.redis_helper.items(region="AI_AGENT"):
-                    if key.startswith("agent_memory:"):
-                        try:
-                            # 解析键名获取user_id和session_id
-                            key_parts = key.split(":")
-                            if len(key_parts) >= 3:
-                                key_user_id = key_parts[2] if len(key_parts) > 3 else None
-                                if not user_id or key_user_id == user_id:
-                                    data = value if isinstance(value, dict) else json.loads(value)
-                                    memory = ConversationMemory(**data)
-                                    sessions.append(memory)
-                        except Exception as err:
-                            logger.warning(f"解析Redis记忆数据失败: {err}")
-                            continue
-            except Exception as e:
-                logger.warning(f"遍历Redis会话失败: {e}")
-
-        # 合并内存缓存（确保包含近期的会话）
-        for cache_key, memory in self.memory_cache.items():
-            # 如果指定了user_id，只返回该用户的会话
-            if not user_id or memory.user_id == user_id:
-                sessions.append(memory)
-
-        # 去重（以 session_id 为键，取最近updated）
-        uniq: Dict[str, ConversationMemory] = {}
-        for mem in sessions:
-            existed = uniq.get(mem.session_id)
-            if (not existed) or (mem.updated_at > existed.updated_at):
-                uniq[mem.session_id] = mem
-
-        # 排序并裁剪
-        sorted_list = sorted(uniq.values(), key=lambda m: m.updated_at, reverse=True)[:limit]
-        return [
-            {
-                "session_id": m.session_id,
-                "title": m.title or "新会话",
-                "message_count": len(m.messages),
-                "created_at": m.created_at.isoformat(),
-                "updated_at": m.updated_at.isoformat(),
-            }
-            for m in sorted_list
-        ]
-
-    async def add_conversation(
-            self,
-            session_id: str,
-            user_id: str,
-            role: str,
-            content: str,
-            metadata: Optional[Dict[str, Any]] = None
-    ):
-        """
-        添加消息到记忆
-        """
-        memory = await self.get_conversation(session_id=session_id, user_id=user_id)
-
-        message = {
-            "role": role,
-            "content": content,
-            "timestamp": datetime.now().isoformat(),
-            "metadata": metadata or {}
-        }
-
-        memory.messages.append(message)
-        memory.updated_at = datetime.now()
-
-        # 限制消息数量，避免记忆过大
-        max_messages = settings.LLM_MAX_MEMORY_MESSAGES
-        if len(memory.messages) > max_messages:
-            # 保留最近的消息，但保留第一条系统消息
-            system_messages = [msg for msg in memory.messages if msg["role"] == "system"]
-            recent_messages = memory.messages[-(max_messages - len(system_messages)):]
-            memory.messages = system_messages + recent_messages
-
-        await self._save_conversation(memory)
-
-        logger.debug(f"消息已添加到记忆: session_id={session_id}, user_id={user_id}, role={role}")
-
-    def get_recent_messages_for_agent(
-            self,
-            session_id: str,
-            user_id: str
-    ) -> List[Dict[str, Any]]:
+    def get_agent_messages(
+            self, session_id: str, user_id: str
+    ) -> List[BaseMessage]:
         """
         为Agent获取最近的消息（仅内存缓存）
 
         如果消息Token数量超过模型最大上下文长度的阀值，会自动进行摘要裁剪
         """
-        cache_key = self._get_memory_key(session_id, user_id)
-        memory = self.memory_cache.get(cache_key)
+        memory = self.get_memory(session_id, user_id)
         if not memory:
             return []
 
         # 获取所有消息
-        return memory.messages[:-1]
+        return memory.messages
 
-    async def get_recent_messages(
-            self,
-            session_id: str,
-            user_id: str,
-            limit: int = 10,
-            role_filter: Optional[list] = None
-    ) -> List[Dict[str, Any]]:
+    def save_agent_messages(
+            self, session_id: str, user_id: str, messages: List[BaseMessage]
+    ):
         """
-        获取最近的消息
+        保存Agent消息（仅内存缓存）
+
+        注意：Redis中的记忆通过TTL机制自动过期，这里只更新内存缓存，Redis会在下次访问时自动过期
         """
-        memory = await self.get_conversation(session_id=session_id, user_id=user_id)
+        memory = self.get_memory(session_id, user_id)
+        if not memory:
+            memory = ConversationMemory(session_id=session_id, user_id=user_id)
 
-        messages = memory.messages
-        if role_filter:
-            messages = [msg for msg in messages if msg["role"] in role_filter]
+        memory.messages = messages
+        memory.updated_at = datetime.now()
 
-        return messages[-limit:] if messages else []
+        # 更新内存缓存
+        self.save_memory(memory)
 
-    async def get_context(self, session_id: str, user_id: str) -> Dict[str, Any]:
+    def save_memory(self, memory: ConversationMemory):
         """
-        获取会话上下文
-        """
-        memory = await self.get_conversation(session_id=session_id, user_id=user_id)
-        return memory.context
+        保存记忆到内存缓存
 
-    async def clear_memory(self, session_id: str, user_id: str):
-        """
-        清空会话记忆
-        """
-        cache_key = f"{user_id}:{session_id}" if user_id else session_id
-        if cache_key in self.memory_cache:
-            del self.memory_cache[cache_key]
-
-        if settings.CACHE_BACKEND_TYPE == "redis":
-            redis_key = self._get_redis_key(session_id, user_id)
-            await self.redis_helper.delete(redis_key, region="AI_AGENT")
-
-        logger.info(f"会话记忆已清空: session_id={session_id}, user_id={user_id}")
-
-    def _save_memory(self, memory: ConversationMemory):
-        """
-        保存记忆到内存
+        注意：Redis中的记忆通过TTL机制自动过期，这里只更新内存缓存，Redis会在下次访问时自动过期
         """
         cache_key = self._get_memory_key(memory.session_id, memory.user_id)
         self.memory_cache[cache_key] = memory
 
-    async def _save_redis(self, memory: ConversationMemory):
+    def clear_memory(self, session_id: str, user_id: str):
         """
-        保存记忆到Redis
+        清空会话记忆
         """
-        if settings.CACHE_BACKEND_TYPE == "redis":
-            try:
-                memory_dict = memory.model_dump()
-                redis_key = self._get_redis_key(memory.session_id, memory.user_id)
-                ttl = int(timedelta(days=settings.LLM_REDIS_MEMORY_RETENTION_DAYS).total_seconds())
-                await self.redis_helper.set(
-                    redis_key,
-                    memory_dict,
-                    ttl=ttl,
-                    region="AI_AGENT"
-                )
-            except Exception as e:
-                logger.warning(f"保存记忆到Redis失败: {e}")
-
-    async def _save_conversation(self, memory: ConversationMemory):
-        """
-        保存记忆到存储
-
-        Redis中的记忆会自动通过TTL机制过期，无需手动清理
-        """
-        # 更新内存缓存
-        self._save_memory(memory)
-
-        # 保存到Redis，设置TTL自动过期
-        await self._save_redis(memory)
+        cache_key = self._get_memory_key(session_id, user_id)
+        if cache_key in self.memory_cache:
+            del self.memory_cache[cache_key]
 
+        logger.info(f"会话记忆已清空: session_id={session_id}, user_id={user_id}")
 
     async def _cleanup_expired_memories(self):
         """
@@ -328,7 +132,9 @@ class ConversationMemoryManager:
                 # 只检查内存缓存中的过期记忆
                 # Redis中的记忆会通过TTL自动过期，无需手动处理
                 for cache_key, memory in self.memory_cache.items():
-                    if (current_time - memory.updated_at).days > settings.LLM_MEMORY_RETENTION_DAYS:
+                    if (
+                            current_time - memory.updated_at
+                    ).days > settings.LLM_MEMORY_RETENTION_DAYS:
                         expired_sessions.append(cache_key)
 
                 # 只清理内存缓存，不删除Redis中的键（Redis会自动过期）
@@ -344,4 +150,5 @@ class ConversationMemoryManager:
             except Exception as e:
                 logger.error(f"清理记忆时发生错误: {e}")
 
-conversation_manager = ConversationMemoryManager()
+
+memory_manager = MemoryManager()

app/agent/middleware/activity_log.py

@@ -0,0 +1,406 @@
+"""
+活动日志中间件 - 自动记录 Agent 每次交互的操作摘要。
+
+按日期存储在 CONFIG_PATH/agent/activity/YYYY-MM-DD.md 中，
+每次 Agent 执行完毕后自动调用 LLM 对本轮对话生成简洁的活动摘要，
+并在每次 Agent 启动时加载近几天的活动日志注入系统提示词。
+"""
+
+import re
+from collections.abc import Awaitable, Callable
+from datetime import datetime, timedelta
+from typing import Annotated, Any, NotRequired, TypedDict
+
+from anyio import Path as AsyncPath
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    AgentState,
+    ContextT,
+    ModelRequest,
+    ModelResponse,
+    PrivateStateAttr,  # noqa
+    ResponseT,
+)
+from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
+from langgraph.runtime import Runtime
+
+from app.agent.middleware.utils import append_to_system_message
+from app.log import logger
+
+# 活动日志保留天数
+DEFAULT_RETENTION_DAYS = 7
+
+# 注入系统提示词时加载的天数
+PROMPT_LOAD_DAYS = 3
+
+# 每日日志文件最大大小 (256KB)
+MAX_LOG_FILE_SIZE = 256 * 1024
+
+# 提取本轮对话上下文的最大字符数（避免过长的对话消耗太多 token）
+MAX_CONTEXT_FOR_SUMMARY = 4000
+
+# LLM 总结的提示词
+SUMMARY_PROMPT = """请根据以下 AI 助手与用户的对话记录，生成一条简洁的活动摘要（中文，一句话，不超过80字）。
+摘要应包含：用户的需求是什么、助手做了什么、结果如何。
+只输出摘要内容，不要加任何前缀、标点序号或解释。
+
+对话记录：
+{conversation}"""
+
+
+class ActivityLogState(AgentState):
+    """ActivityLogMiddleware 的状态模型。"""
+
+    activity_log_contents: NotRequired[Annotated[dict[str, str], PrivateStateAttr]]
+    """将日期字符串映射到日志内容的字典。标记为私有，不包含在最终代理状态中。"""
+
+
+class ActivityLogStateUpdate(TypedDict):
+    """ActivityLogMiddleware 的状态更新。"""
+
+    activity_log_contents: dict[str, str]
+
+
+def _extract_last_round(messages: list) -> list | None:
+    """从完整消息列表中提取最后一轮交互。
+
+    从最后一条 HumanMessage 到消息末尾即为本轮交互。
+
+    参数：
+        messages: Agent 执行后的完整消息列表。
+
+    返回：
+        本轮交互的消息子列表，如果无有效交互则返回 None。
+    """
+    if not messages:
+        return None
+
+    # 找到最后一条用户消息的索引
+    last_human_idx = None
+    for i in range(len(messages) - 1, -1, -1):
+        if isinstance(messages[i], HumanMessage) and messages[i].content:
+            last_human_idx = i
+            break
+
+    if last_human_idx is None:
+        return None
+
+    round_messages = messages[last_human_idx:]
+
+    # 检查是否为系统心跳消息
+    user_msg = round_messages[0]
+    user_content = (
+        user_msg.content if isinstance(user_msg.content, str) else str(user_msg.content)
+    )
+    if user_content.strip().startswith("[System Heartbeat]"):
+        return None
+
+    return round_messages
+
+
+def _format_conversation_for_summary(round_messages: list) -> str:
+    """将本轮对话消息格式化为文本，供 LLM 总结。
+
+    参数：
+        round_messages: 本轮交互的消息列表。
+
+    返回：
+        格式化后的对话文本。
+    """
+    lines = []
+    total_len = 0
+
+    for msg in round_messages:
+        if isinstance(msg, HumanMessage):
+            content = msg.content if isinstance(msg.content, str) else str(msg.content)
+            line = f"用户: {content}"
+        elif isinstance(msg, AIMessage):
+            if hasattr(msg, "tool_calls") and msg.tool_calls:
+                tool_names = [
+                    tc["name"]
+                    for tc in msg.tool_calls
+                    if isinstance(tc, dict) and "name" in tc
+                ]
+                line = f"助手调用工具: {', '.join(tool_names)}"
+            elif msg.content:
+                content = (
+                    msg.content if isinstance(msg.content, str) else str(msg.content)
+                )
+                line = f"助手: {content}"
+            else:
+                continue
+        elif isinstance(msg, ToolMessage):
+            content = msg.content if isinstance(msg.content, str) else str(msg.content)
+            # 工具返回可能很长，截断
+            if len(content) > 200:
+                content = content[:200] + "..."
+            line = f"工具返回: {content}"
+        else:
+            continue
+
+        # 控制总长度
+        if total_len + len(line) > MAX_CONTEXT_FOR_SUMMARY:
+            lines.append("...(后续对话省略)")
+            break
+        lines.append(line)
+        total_len += len(line)
+
+    return "\n".join(lines)
+
+
+async def _summarize_with_llm(conversation_text: str) -> str | None:
+    """调用 LLM 对对话文本生成活动摘要。
+
+    参数：
+        conversation_text: 格式化后的对话文本。
+
+    返回：
+        LLM 生成的摘要字符串，失败时返回 None。
+    """
+    try:
+        from app.helper.llm import LLMHelper
+
+        llm = LLMHelper.get_llm(streaming=False)
+        prompt = SUMMARY_PROMPT.format(conversation=conversation_text)
+        response = await llm.ainvoke(prompt)
+        summary = response.content.strip()
+        # 清理模型可能输出的前缀（如 "摘要：" "总结："）
+        summary = re.sub(r"^(摘要|总结|活动记录)[：:]\s*", "", summary)
+        return summary if summary else None
+    except Exception as e:
+        logger.debug("LLM summarization failed: %s", e)
+        return None
+
+
+ACTIVITY_LOG_SYSTEM_PROMPT = """<activity_log>
+{activity_log}
+</activity_log>
+
+<activity_log_guidelines>
+    The above <activity_log> contains a record of your recent interactions with the user, automatically maintained by the system.
+    
+    **How to use this information:**
+    - Reference past activities when relevant to provide continuity (e.g., "之前帮你订阅了《XXX》，现在有更新了")
+    - Use activity history to understand ongoing tasks and user patterns
+    - When the user asks "你之前帮我做了什么" or similar questions, refer to this log
+    - Activity logs are automatically recorded after each interaction - you do NOT need to manually update them
+    
+    **What is automatically logged:**
+    - Each user interaction: what was asked, which tools were used, and the outcome
+    - Timestamps for all activities
+    - The log is organized by date for easy reference
+    
+    **Important:**
+    - Activity logs are READ-ONLY from your perspective - the system manages them automatically
+    - Do not attempt to edit or write to activity log files
+    - For long-term preferences and knowledge, continue to use MEMORY.md
+    - Activity logs are retained for {retention_days} days and then automatically cleaned up
+</activity_log_guidelines>
+"""
+
+
+class ActivityLogMiddleware(AgentMiddleware[ActivityLogState, ContextT, ResponseT]):  # noqa
+    """自动记录和加载 Agent 活动日志的中间件。
+
+    - abefore_agent: 加载近几天的活动日志
+    - awrap_model_call: 将活动日志注入系统提示词
+    - aafter_agent: 从本次对话中提取摘要并追加到当日日志文件
+
+    参数：
+        activity_dir: 活动日志存储目录路径。
+        retention_days: 日志保留天数（默认 7 天）。
+        prompt_load_days: 注入系统提示词时加载的天数（默认 3 天）。
+    """
+
+    state_schema = ActivityLogState
+
+    def __init__(
+        self,
+        *,
+        activity_dir: str,
+        retention_days: int = DEFAULT_RETENTION_DAYS,
+        prompt_load_days: int = PROMPT_LOAD_DAYS,
+    ) -> None:
+        self.activity_dir = activity_dir
+        self.retention_days = retention_days
+        self.prompt_load_days = prompt_load_days
+
+    def _get_log_path(self, date_str: str) -> AsyncPath:
+        """获取指定日期的日志文件路径。"""
+        return AsyncPath(self.activity_dir) / f"{date_str}.md"
+
+    def _format_activity_log(self, contents: dict[str, str]) -> str:
+        """格式化活动日志用于系统提示词注入。"""
+        if not contents:
+            return ACTIVITY_LOG_SYSTEM_PROMPT.format(
+                activity_log="(暂无活动记录)",
+                retention_days=self.retention_days,
+            )
+
+        # 按日期排序（最近的在前）
+        sorted_dates = sorted(contents.keys(), reverse=True)
+        sections = []
+        for date_str in sorted_dates:
+            content = contents[date_str].strip()
+            if content:
+                sections.append(f"### {date_str}\n{content}")
+
+        if not sections:
+            return ACTIVITY_LOG_SYSTEM_PROMPT.format(
+                activity_log="(暂无活动记录)",
+                retention_days=self.retention_days,
+            )
+
+        log_body = "\n\n".join(sections)
+        return ACTIVITY_LOG_SYSTEM_PROMPT.format(
+            activity_log=log_body,
+            retention_days=self.retention_days,
+        )
+
+    async def _load_recent_logs(self) -> dict[str, str]:
+        """加载近几天的活动日志。"""
+        contents: dict[str, str] = {}
+        today = datetime.now().date()
+
+        for i in range(self.prompt_load_days):
+            date = today - timedelta(days=i)
+            date_str = date.strftime("%Y-%m-%d")
+            log_path = self._get_log_path(date_str)
+
+            if await log_path.exists():
+                try:
+                    content = await log_path.read_text(encoding="utf-8")
+                    contents[date_str] = content
+                    logger.debug("Loaded activity log for %s", date_str)
+                except Exception as e:
+                    logger.warning("Failed to load activity log %s: %s", date_str, e)
+
+        return contents
+
+    async def _append_activity(self, summary: str) -> None:
+        """将一条活动记录追加到当日日志文件。"""
+        today_str = datetime.now().strftime("%Y-%m-%d")
+        now_str = datetime.now().strftime("%H:%M")
+        log_path = self._get_log_path(today_str)
+
+        # 确保目录存在
+        dir_path = AsyncPath(self.activity_dir)
+        if not await dir_path.exists():
+            await dir_path.mkdir(parents=True, exist_ok=True)
+
+        # 检查文件大小
+        if await log_path.exists():
+            stat = await log_path.stat()
+            if stat.st_size >= MAX_LOG_FILE_SIZE:
+                logger.warning(
+                    "Activity log %s exceeds size limit (%d bytes), skipping append",
+                    today_str,
+                    stat.st_size,
+                )
+                return
+
+        # 追加记录
+        entry = f"- **{now_str}** {summary}\n"
+        try:
+            if await log_path.exists():
+                existing = await log_path.read_text(encoding="utf-8")
+                await log_path.write_text(existing + entry, encoding="utf-8")
+            else:
+                header = f"# {today_str} 活动日志\n\n"
+                await log_path.write_text(header + entry, encoding="utf-8")
+            logger.debug("Activity logged: %s", summary[:80])
+        except Exception as e:
+            logger.warning("Failed to append activity log: %s", e)
+
+    async def _cleanup_old_logs(self) -> None:
+        """清理超过保留天数的旧日志文件。"""
+        dir_path = AsyncPath(self.activity_dir)
+        if not await dir_path.exists():
+            return
+
+        cutoff_date = datetime.now().date() - timedelta(days=self.retention_days)
+        date_pattern = re.compile(r"^(\d{4}-\d{2}-\d{2})\.md$")
+
+        try:
+            async for path in dir_path.iterdir():
+                if not await path.is_file():
+                    continue
+                match = date_pattern.match(path.name)
+                if not match:
+                    continue
+                try:
+                    file_date = datetime.strptime(match.group(1), "%Y-%m-%d").date()
+                    if file_date < cutoff_date:
+                        await path.unlink()
+                        logger.debug("Cleaned up old activity log: %s", path.name)
+                except ValueError:
+                    continue
+        except Exception as e:
+            logger.warning("Failed to cleanup old activity logs: %s", e)
+
+    async def abefore_agent(
+        self, state: ActivityLogState, runtime: Runtime
+    ) -> ActivityLogStateUpdate | None:
+        """在 Agent 执行前加载近期活动日志。"""
+        # 如果已经加载则跳过
+        if "activity_log_contents" in state:
+            return None
+
+        contents = await self._load_recent_logs()
+
+        # 趁机清理旧日志（低频操作，不影响性能）
+        await self._cleanup_old_logs()
+
+        return ActivityLogStateUpdate(activity_log_contents=contents)
+
+    def modify_request(self, request: ModelRequest[ContextT]) -> ModelRequest[ContextT]:
+        """将活动日志注入系统消息。"""
+        contents = request.state.get("activity_log_contents", {})
+        activity_log_prompt = self._format_activity_log(contents)
+
+        new_system_message = append_to_system_message(
+            request.system_message, activity_log_prompt
+        )
+        return request.override(system_message=new_system_message)
+
+    async def awrap_model_call(
+        self,
+        request: ModelRequest[ContextT],
+        handler: Callable[
+            [ModelRequest[ContextT]], Awaitable[ModelResponse[ResponseT]]
+        ],
+    ) -> ModelResponse[ResponseT]:
+        """异步包装模型调用，注入活动日志到系统提示词。"""
+        modified_request = self.modify_request(request)
+        return await handler(modified_request)
+
+    async def aafter_agent(
+        self, state: ActivityLogState, runtime: Runtime
+    ) -> dict[str, Any] | None:
+        """Agent 执行完毕后，调用 LLM 对本轮对话生成摘要并追加到当日活动日志。"""
+        try:
+            messages = state.get("messages", [])
+            if not messages:
+                return None
+
+            # 提取本轮交互
+            round_messages = _extract_last_round(messages)
+            if not round_messages:
+                return None
+
+            # 格式化对话文本
+            conversation_text = _format_conversation_for_summary(round_messages)
+            if not conversation_text:
+                return None
+
+            # 调用 LLM 生成摘要
+            summary = await _summarize_with_llm(conversation_text)
+            if summary:
+                await self._append_activity(summary)
+        except Exception as e:
+            logger.warning("Failed to record activity: %s", e)
+
+        return None
+
+
+__all__ = ["ActivityLogMiddleware"]

app/agent/middleware/jobs.py

@@ -0,0 +1,350 @@
+import re
+from collections.abc import Awaitable, Callable
+from typing import Annotated, NotRequired, TypedDict
+
+import yaml  # noqa
+from anyio import Path as AsyncPath
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    AgentState,
+    ContextT,
+    ModelRequest,
+    ModelResponse,
+    PrivateStateAttr,  # noqa
+    ResponseT,
+)
+from langchain_core.runnables import RunnableConfig
+from langgraph.runtime import Runtime
+
+from app.agent.middleware.utils import append_to_system_message
+from app.log import logger
+
+# JOB.md 文件最大限制为 1MB
+MAX_JOB_FILE_SIZE = 1 * 1024 * 1024
+
+
+class JobMetadata(TypedDict):
+    """Job 元数据。"""
+
+    path: str
+    """JOB.md 文件路径。"""
+
+    id: str
+    """Job 标识符（目录名）。"""
+
+    name: str
+    """Job 名称。"""
+
+    description: str
+    """Job 描述。"""
+
+    schedule: str
+    """调度类型: once（一次性）/ recurring（重复性）。"""
+
+    status: str
+    """当前状态: pending / in_progress / completed / cancelled。"""
+
+    last_run: str | None
+    """上次执行时间。"""
+
+
+class JobsState(AgentState):
+    """jobs 中间件状态。"""
+
+    jobs_metadata: NotRequired[Annotated[list[JobMetadata], PrivateStateAttr]]
+    """已加载的 job 元数据列表，不传播给父 agent。"""
+
+
+class JobsStateUpdate(TypedDict):
+    """jobs 中间件状态更新项。"""
+
+    jobs_metadata: list[JobMetadata]
+    """待合并的 job 元数据列表。"""
+
+
+def _parse_job_metadata(
+    content: str,
+    job_path: str,
+    job_id: str,
+) -> JobMetadata | None:
+    """从 JOB.md 内容中解析 YAML 前言并验证元数据。"""
+    if len(content) > MAX_JOB_FILE_SIZE:
+        logger.warning(
+            "Skipping %s: content too large (%d bytes)", job_path, len(content)
+        )
+        return None
+
+    # 匹配 --- 分隔的 YAML 前言
+    frontmatter_pattern = r"^---\s*\n(.*?)\n---\s*\n"
+    match = re.match(frontmatter_pattern, content, re.DOTALL)
+    if not match:
+        logger.warning("Skipping %s: no valid YAML frontmatter found", job_path)
+        return None
+    frontmatter_str = match.group(1)
+
+    # 解析 YAML
+    try:
+        frontmatter_data = yaml.safe_load(frontmatter_str)
+    except yaml.YAMLError as e:
+        logger.warning("Invalid YAML in %s: %s", job_path, e)
+        return None
+
+    if not isinstance(frontmatter_data, dict):
+        logger.warning("Skipping %s: frontmatter is not a mapping", job_path)
+        return None
+
+    # Job 名称和描述
+    name = str(frontmatter_data.get("name", "")).strip()
+    description = str(frontmatter_data.get("description", "")).strip()
+    if not name:
+        logger.warning("Skipping %s: missing required 'name'", job_path)
+        return None
+
+    # 调度类型
+    schedule = str(frontmatter_data.get("schedule", "once")).strip().lower()
+    if schedule not in ("once", "recurring"):
+        schedule = "once"
+
+    # 状态
+    status = str(frontmatter_data.get("status", "pending")).strip().lower()
+    if status not in ("pending", "in_progress", "completed", "cancelled"):
+        status = "pending"
+
+    # 上次执行时间
+    last_run = str(frontmatter_data.get("last_run", "")).strip() or None
+
+    return JobMetadata(
+        id=job_id,
+        name=name,
+        description=description,
+        path=job_path,
+        schedule=schedule,
+        status=status,
+        last_run=last_run,
+    )
+
+
+async def _alist_jobs(source_path: AsyncPath) -> list[JobMetadata]:
+    """异步列出指定路径下的所有任务。
+
+    扫描包含 JOB.md 的目录并解析其元数据。
+    """
+    jobs: list[JobMetadata] = []
+
+    if not await source_path.exists():
+        return []
+
+    # 查找所有任务目录（包含 JOB.md 的目录）
+    job_dirs: list[AsyncPath] = []
+    async for path in source_path.iterdir():
+        if await path.is_dir() and await (path / "JOB.md").is_file():
+            job_dirs.append(path)
+
+    if not job_dirs:
+        return []
+
+    # 解析 JOB.md
+    for job_path in job_dirs:
+        job_md_path = job_path / "JOB.md"
+
+        job_content = await job_md_path.read_text(encoding="utf-8")
+
+        # 解析元数据
+        job_metadata = _parse_job_metadata(
+            content=job_content,
+            job_path=str(job_md_path),
+            job_id=job_path.name,
+        )
+        if job_metadata:
+            jobs.append(job_metadata)
+
+    return jobs
+
+
+JOBS_SYSTEM_PROMPT = """
+<jobs_system>
+You have a **scheduled jobs** system that allows you to track and execute long-running or recurring tasks.
+
+**Jobs Location:** `{jobs_location}`
+
+**Current Jobs:**
+
+{jobs_list}
+
+**Job File Format:**
+
+Each job is a directory containing a `JOB.md` file with YAML frontmatter followed by task details:
+
+```markdown
+---
+name: 任务名称（简短中文描述）
+description: 任务的详细描述，说明要做什么
+schedule: once 或 recurring
+status: pending / in_progress / completed / cancelled
+last_run: "YYYY-MM-DD HH:MM"（上次执行时间，可选）
+---
+# 任务详情
+
+## 目标
+详细描述这个任务要完成的目标。
+
+## 执行日志
+记录每次执行的情况和结果。
+
+- **2024-01-15 10:00** - 执行了XXX操作，结果：成功/失败
+- **2024-01-16 10:00** - 继续执行XXX...
+```
+
+**Job Lifecycle Rules:**
+
+1. **Creating a Job**: When a user asks you to do something periodically or at a later time:
+   - Create a new directory under the jobs location, directory name is the `job-id` (lowercase, hyphens, 1-64 chars)
+   - Write a `JOB.md` file with proper frontmatter and detailed task description
+   - Set `schedule: once` for one-time tasks, `schedule: recurring` for repeating tasks (e.g., daily sign-in, weekly checks)
+   - Set initial `status: pending`
+
+2. **Executing a Job**: When you work on a job:
+   - Update `status: in_progress` in the frontmatter
+   - Execute the required actions using your tools
+   - Log the execution result in the "执行日志" section with timestamp
+   - Update `last_run` in frontmatter to current time
+
+3. **Completing a Job**:
+   - For `schedule: once` tasks: set `status: completed` after successful execution
+   - For `schedule: recurring` tasks: keep `status: pending` after execution, only update `last_run` time. The job stays active for the next scheduled run.
+   - Set `status: cancelled` if the user explicitly asks to cancel/stop a task
+
+4. **Heartbeat Check**: You will be periodically woken up to check pending jobs. When woken up:
+   - Read the jobs directory to find all active jobs (status: pending or in_progress)
+   - Skip jobs with `status: completed` or `status: cancelled`
+   - For `schedule: recurring` jobs, check `last_run` to determine if it's time to run again
+   - Execute pending jobs and update their status/logs accordingly
+
+**Important Notes:**
+- Each job MUST have its own separate directory and JOB.md file to avoid conflicts
+- Always update the frontmatter fields (status, last_run) when executing a job
+- Keep execution logs concise but informative
+- For recurring jobs, maintain a rolling log (keep recent entries, you can summarize/remove old entries to keep the file manageable)
+- When creating jobs, make the description detailed enough that you can understand and execute the task in future sessions without additional context
+
+**When to Create Jobs:**
+- User says "每天帮我..." / "定期..." / "定时..." / "提醒我..." / "以后每次..."
+- User requests a task that should be done repeatedly
+- User asks for monitoring or periodic checking of something
+
+**When NOT to Create Jobs:**
+- User asks for an immediate one-time action (just do it now)
+- Simple questions or conversations
+- Tasks that are already handled by MoviePilot's built-in scheduler services
+</jobs_system>
+"""
+
+
+class JobsMiddleware(AgentMiddleware[JobsState, ContextT, ResponseT]):  # noqa
+    """加载并向系统提示词注入 Agent Jobs 的中间件。
+
+    扫描 jobs 目录下的 JOB.md 文件，解析元数据并注入到系统提示词中，
+    使智能体了解当前的长期任务及其状态。
+    """
+
+    state_schema = JobsState
+
+    def __init__(self, *, sources: list[str]) -> None:
+        """初始化 Jobs 中间件。"""
+        self.sources = sources
+        self.system_prompt_template = JOBS_SYSTEM_PROMPT
+
+    @staticmethod
+    def _format_jobs_list(jobs: list[JobMetadata]) -> str:
+        """格式化任务元数据列表用于系统提示词。"""
+        if not jobs:
+            return "(No active jobs. You can create jobs when users request periodic or scheduled tasks.)"
+
+        lines = []
+        for job in jobs:
+            status_emoji = {
+                "pending": "⏳",
+                "in_progress": "🔄",
+                "completed": "✅",
+                "cancelled": "❌",
+            }.get(job["status"], "❓")
+
+            schedule_label = (
+                "recurring (重复)"
+                if job["schedule"] == "recurring"
+                else "once (一次性)"
+            )
+            desc_line = (
+                f"- {status_emoji} **{job['id']}**: {job['name']}"
+                f" [{schedule_label}] - {job['description']}"
+            )
+            if job.get("last_run"):
+                desc_line += f" (上次执行: {job['last_run']})"
+            lines.append(desc_line)
+            lines.append(f"  -> Read `{job['path']}` for full details")
+
+        return "\n".join(lines)
+
+    def modify_request(self, request: ModelRequest[ContextT]) -> ModelRequest[ContextT]:
+        """将任务文档注入模型请求的系统消息中。"""
+        jobs_metadata = request.state.get("jobs_metadata", [])  # noqa
+
+        # 过滤：只展示活跃任务（pending / in_progress / recurring）
+        active_jobs = [
+            j
+            for j in jobs_metadata
+            if j["status"] in ("pending", "in_progress")
+            or (j["schedule"] == "recurring" and j["status"] not in ("cancelled",))
+        ]
+
+        jobs_list = self._format_jobs_list(active_jobs)
+        jobs_location = self.sources[0] if self.sources else ""
+
+        jobs_section = self.system_prompt_template.format(
+            jobs_location=jobs_location,
+            jobs_list=jobs_list,
+        )
+
+        new_system_message = append_to_system_message(
+            request.system_message, jobs_section
+        )
+
+        return request.override(system_message=new_system_message)
+
+    async def abefore_agent(  # noqa
+        self, state: JobsState, runtime: Runtime, config: RunnableConfig
+    ) -> JobsStateUpdate | None:
+        """在 Agent 执行前异步加载任务元数据。
+
+        每个会话仅加载一次。若 state 中已有则跳过。
+        """
+        # 如果 state 中已存在元数据则跳过
+        if "jobs_metadata" in state:
+            return None
+
+        all_jobs: list[JobMetadata] = []
+
+        # 遍历源加载任务
+        for source_path_str in self.sources:
+            source_path = AsyncPath(source_path_str)
+            if not await source_path.exists():
+                await source_path.mkdir(parents=True, exist_ok=True)
+                continue
+            source_jobs = await _alist_jobs(source_path)
+            all_jobs.extend(source_jobs)
+
+        return JobsStateUpdate(jobs_metadata=all_jobs)
+
+    async def awrap_model_call(
+        self,
+        request: ModelRequest[ContextT],
+        handler: Callable[
+            [ModelRequest[ContextT]], Awaitable[ModelResponse[ResponseT]]
+        ],
+    ) -> ModelResponse[ResponseT]:
+        """在模型调用时注入任务文档。"""
+        modified_request = self.modify_request(request)
+        return await handler(modified_request)
+
+
+__all__ = ["JobMetadata", "JobsMiddleware"]

app/agent/middleware/memory.py

@@ -0,0 +1,396 @@
+from collections.abc import Awaitable, Callable
+from typing import Annotated, NotRequired, TypedDict, Dict
+
+from anyio import Path as AsyncPath
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    AgentState,
+    ContextT,
+    ModelRequest,
+    ModelResponse,
+    PrivateStateAttr,  # noqa
+    ResponseT,
+)
+from langchain_core.runnables import RunnableConfig
+from langgraph.runtime import Runtime
+
+from app.agent.middleware.utils import append_to_system_message
+from app.log import logger
+
+# 记忆文件最大限制为 100KB，防止单文件过大导致上下文溢出
+MAX_MEMORY_FILE_SIZE = 100 * 1024
+
+# 默认记忆文件名（用户主记忆）
+DEFAULT_MEMORY_FILE = "MEMORY.md"
+
+
+class MemoryState(AgentState):
+    """`MemoryMiddleware` 的状态模型。
+
+    属性：
+        memory_contents: 将源路径映射到其加载内容的字典。
+            标记为私有，因此不包含在最终的代理状态中。
+        memory_empty: 记忆文件是否为空或不存在。
+            标记为私有，用于判断是否需要触发初始化引导流程。
+    """
+
+    memory_contents: NotRequired[Annotated[dict[str, str], PrivateStateAttr]]
+    memory_empty: NotRequired[Annotated[bool, PrivateStateAttr]]
+
+
+class MemoryStateUpdate(TypedDict):
+    """`MemoryMiddleware` 的状态更新。"""
+
+    memory_contents: dict[str, str]
+    memory_empty: bool
+
+
+MEMORY_SYSTEM_PROMPT = """<agent_memory>
+The following memory files were loaded from your memory directory: `{memory_dir}`
+You can create, edit, or organize any `.md` files in this directory to manage your knowledge.
+
+{agent_memory}
+</agent_memory>
+
+<memory_guidelines>
+    The above <agent_memory> was loaded from `.md` files in your memory directory (`{memory_dir}`). As you learn from your interactions with the user, you can save new knowledge by calling the `edit_file` or `write_file` tool on files in this directory.
+
+    **Memory file organization:**
+    - All `.md` files in `{memory_dir}` are automatically loaded as memory.
+    - `MEMORY.md` is the default/primary memory file for general user preferences and profile.
+    - You may create additional `.md` files to organize knowledge by topic (e.g., `MEDIA_RULES.md`, `DOWNLOAD_PREFERENCES.md`, `SITE_CONFIGS.md`, etc.).
+    - Keep each file focused on a specific domain or topic for better organization.
+    - Subdirectories are NOT scanned — only `.md` files directly in `{memory_dir}`.
+
+    **Learning from feedback:**
+    - One of your MAIN PRIORITIES is to learn from your interactions with the user. These learnings can be implicit or explicit. This means that in the future, you will remember this important information.
+    - When you need to remember something, updating memory must be your FIRST, IMMEDIATE action - before responding to the user, before calling other tools, before doing anything else. Just update memory immediately.
+    - When user says something is better/worse, capture WHY and encode it as a pattern.
+    - Each correction is a chance to improve permanently - don't just fix the immediate issue, update your instructions.
+    - A great opportunity to update your memories is when the user interrupts a tool call and provides feedback. You should update your memories immediately before revising the tool call.
+    - Look for the underlying principle behind corrections, not just the specific mistake.
+    - The user might not explicitly ask you to remember something, but if they provide information that is useful for future use, you should update your memories immediately.
+
+    **Asking for information:**
+    - If you lack context to perform an action (e.g. send a Slack DM, requires a user ID/email) you should explicitly ask the user for this information.
+    - It is preferred for you to ask for information, don't assume anything that you do not know!
+    - When the user provides information that is useful for future use, you should update your memories immediately.
+
+    **When to update memories:**
+    - When the user explicitly asks you to remember something (e.g., "remember my email", "save this preference")
+    - When the user describes your role or how you should behave (e.g., "you are a web researcher", "always do X")
+    - When the user gives feedback on your work - capture what was wrong and how to improve
+    - When the user provides information required for tool use (e.g., slack channel ID, email addresses)
+    - When the user provides context useful for future tasks, such as how to use tools, or which actions to take in a particular situation
+    - When you discover new patterns or preferences (coding styles, conventions, workflows)
+
+    **When to NOT update memories:**
+    - When the information is temporary or transient (e.g., "I'm running late", "I'm on my phone right now")
+    - When the information is a one-time task request (e.g., "Find me a recipe", "What's 25 * 4?")
+    - When the information is a simple question that doesn't reveal lasting preferences (e.g., "What day is it?", "Can you explain X?")
+    - When the information is an acknowledgment or small talk (e.g., "Sounds good!", "Hello", "Thanks for that")
+    - When the information is stale or irrelevant in future conversations
+    - Never store API keys, access tokens, passwords, or any other credentials in any file, memory, or system prompt.
+    - If the user asks where to put API keys or provides an API key, do NOT echo or save it.
+    - Do NOT record daily activities or task execution history in memory files - these are automatically tracked in the activity log system (see <activity_log>). Memory files are only for long-term knowledge, preferences, and patterns.
+
+    **Examples:**
+    Example 1 (remembering user information):
+    User: Can you connect to my google account?
+    Agent: Sure, I'll connect to your google account, what's your google account email?
+    User: john@example.com
+    Agent: Let me save this to my memory.
+    Tool Call: edit_file(...) -> remembers that the user's google account email is john@example.com
+
+    Example 2 (remembering implicit user preferences):
+    User: Can you write me an example for creating a deep agent in LangChain?
+    Agent: Sure, I'll write you an example for creating a deep agent in LangChain <example code in Python>
+    User: Can you do this in JavaScript
+    Agent: Let me save this to my memory.
+    Tool Call: edit_file(...) -> remembers that the user prefers to get LangChain code examples in JavaScript
+    Agent: Sure, here is the JavaScript example<example code in JavaScript>
+
+    Example 3 (do not remember transient information):
+    User: I'm going to play basketball tonight so I will be offline for a few hours.
+    Agent: Okay I'll add a block to your calendar.
+    Tool Call: create_calendar_event(...) -> just calls a tool, does not commit anything to memory, as it is transient information
+</memory_guidelines>
+"""
+
+MEMORY_ONBOARDING_PROMPT = """<agent_memory>
+(No memory loaded — this is a brand new user with no saved preferences.)
+Memory directory: {memory_dir}
+Default memory file: {memory_file}
+</agent_memory>
+
+<memory_onboarding>
+    **IMPORTANT — First-time user detected!**
+
+    The memory directory is currently empty. This means this is likely the user's first interaction, or their preferences have been reset.
+
+    **Your MANDATORY first action in this conversation:**
+    Before doing ANYTHING else (before answering questions, before calling tools, before performing any task), you MUST proactively greet the user warmly and ask them about their preferences so you can provide personalized service going forward. Specifically, ask about:
+
+    1. **How to address the user** — Ask what name or nickname they'd like you to call them (e.g., a real name, a nickname, or a fun title). This is the top priority for building a personal connection.
+    2. **Communication style preference** — Do they prefer a cute/playful tone (with emojis), a formal/professional tone, a concise/minimalist style, or something else?
+    3. **Media preferences** — What types of media do they primarily care about? (e.g., movies, TV shows, anime, documentaries, etc.)
+    4. **Quality preferences** — Do they have preferred video quality (4K, 1080p), codecs (H.265, H.264), or subtitle language preferences?
+    5. **Any other special requests** — Anything else they'd like you to always keep in mind?
+
+    **After the user replies**, you MUST immediately:
+    1. Use the `write_file` tool to save ALL their preferences to the memory file at: `{memory_file}`
+    2. Format the memory file in clean Markdown with clear sections (e.g., `## User Profile`, `## Communication Style`, `## Media Preferences`, etc.)
+    3. The `## User Profile` section MUST include the user's preferred name/nickname at the top
+    4. Only AFTER saving the preferences, proceed to help with whatever the user originally asked about (if anything)
+    5. From this point on, always address the user by their preferred name/nickname in conversations
+    6. You may also create additional `.md` files in the memory directory (`{memory_dir}`) for different topics as needed.
+
+    **If the user skips the preference questions** and directly asks you to do something:
+    - Go ahead and help them with their request first
+    - But still ask about their preferences naturally at the end of the interaction
+    - Save whatever you learn about them (implicit or explicit) to the memory file
+
+    **Example onboarding flow:**
+    The greeting should introduce yourself, explain this is the first meeting, and ask the above questions in a numbered list. Adapt the tone to your persona defined in the base system prompt.
+</memory_onboarding>
+
+<memory_guidelines>
+    Your memory directory is at: {memory_dir}. You can save new knowledge by calling the `edit_file` or `write_file` tool on any `.md` file in this directory.
+
+    **Memory file organization:**
+    - `MEMORY.md` is the default/primary memory file for general user preferences and profile.
+    - You may create additional `.md` files to organize knowledge by topic.
+    - All `.md` files directly in the memory directory are automatically loaded on each conversation.
+
+    **Learning from feedback:**
+    - One of your MAIN PRIORITIES is to learn from your interactions with the user. These learnings can be implicit or explicit. This means that in the future, you will remember this important information.
+    - When you need to remember something, updating memory must be your FIRST, IMMEDIATE action - before responding to the user, before calling other tools, before doing anything else. Just update memory immediately.
+    - When user says something is better/worse, capture WHY and encode it as a pattern.
+    - Each correction is a chance to improve permanently - don't just fix the immediate issue, update your instructions.
+    - The user might not explicitly ask you to remember something, but if they provide information that is useful for future use, you should update your memories immediately.
+
+    **When to update memories:**
+    - When the user explicitly asks you to remember something
+    - When the user describes your role or how you should behave
+    - When the user gives feedback on your work
+    - When the user provides information required for tool use
+    - When you discover new patterns or preferences
+
+    **When to NOT update memories:**
+    - Temporary/transient information
+    - One-time task requests
+    - Simple questions, acknowledgments, or small talk
+    - Never store API keys, access tokens, passwords, or credentials
+    - Do NOT record daily activities in memory files — those go to the activity log
+</memory_guidelines>
+"""
+
+
+class MemoryMiddleware(AgentMiddleware[MemoryState, ContextT, ResponseT]):  # noqa
+    """从代理记忆目录加载所有 MD 文件作为记忆的中间件。
+
+    自动扫描指定目录下的所有 `.md` 文件，加载其内容并注入到系统提示词中。
+    支持多文件记忆组织：用户可以创建多个 `.md` 文件来按主题组织知识。
+
+    参数：
+        memory_dir: 记忆文件目录路径。
+    """
+
+    state_schema = MemoryState
+
+    def __init__(
+        self,
+        *,
+        memory_dir: str,
+    ) -> None:
+        """初始化记忆中间件。
+
+        参数：
+            memory_dir: 记忆文件目录路径（例如，`"/config/agent"`）。
+                        该目录下所有 `.md` 文件都会被自动加载为记忆。
+        """
+        self.memory_dir = memory_dir
+        self.default_memory_file = str(AsyncPath(memory_dir) / DEFAULT_MEMORY_FILE)
+
+    @staticmethod
+    def _is_memory_empty(contents: dict[str, str]) -> bool:
+        """判断记忆内容是否为空。
+
+        检查所有源文件的内容，如果全部为空或仅包含空白字符则返回 True。
+
+        参数：
+            contents: 将源路径映射到内容的字典。
+
+        返回：
+            如果记忆为空则返回 True，否则返回 False。
+        """
+        if not contents:
+            return True
+        return all(not content.strip() for content in contents.values())
+
+    def _format_agent_memory(
+        self, contents: dict[str, str], memory_empty: bool = False
+    ) -> str:
+        """格式化记忆，将位置和内容成对组合。
+
+        当记忆为空时，返回初始化引导提示词，引导智能体主动询问用户偏好。
+        当记忆非空时，返回标准记忆系统提示词，包含所有加载的文件内容。
+
+        参数：
+            contents: 将源路径映射到内容的字典。
+            memory_empty: 记忆是否为空的标志位。
+
+        返回：
+            在 <agent_memory> 标签中包装了位置+内容对的格式化字符串。
+        """
+        # 记忆为空时返回初始化引导提示词
+        if memory_empty or self._is_memory_empty(contents):
+            return MEMORY_ONBOARDING_PROMPT.format(
+                memory_dir=self.memory_dir,
+                memory_file=self.default_memory_file,
+            )
+
+        # 按文件名排序，确保 MEMORY.md 排在最前面
+        sorted_paths = sorted(
+            [p for p in contents if contents[p].strip()],
+            key=lambda p: (0 if AsyncPath(p).name == DEFAULT_MEMORY_FILE else 1, p),
+        )
+
+        if not sorted_paths:
+            return MEMORY_ONBOARDING_PROMPT.format(
+                memory_dir=self.memory_dir,
+                memory_file=self.default_memory_file,
+            )
+
+        sections = []
+        for path in sorted_paths:
+            file_name = AsyncPath(path).name
+            sections.append(f"### {file_name}\n**Path:** `{path}`\n\n{contents[path]}")
+
+        memory_body = "\n\n---\n\n".join(sections)
+        return MEMORY_SYSTEM_PROMPT.format(
+            agent_memory=memory_body,
+            memory_dir=self.memory_dir,
+        )
+
+    async def _scan_memory_files(self) -> list[str]:
+        """扫描记忆目录下的所有 .md 文件。
+
+        仅扫描目录下直接存在的 `.md` 文件（不递归子目录）。
+        文件大小超过限制的将被跳过。
+
+        返回：
+            发现的 .md 文件路径列表。
+        """
+        dir_path = AsyncPath(self.memory_dir)
+        if not await dir_path.exists():
+            return []
+
+        md_files: list[str] = []
+        async for entry in dir_path.iterdir():
+            if await entry.is_file() and entry.name.lower().endswith(".md"):
+                md_files.append(str(entry))
+
+        return md_files
+
+    async def abefore_agent(
+        self,
+        state: MemoryState,
+        runtime: Runtime,  # noqa
+        config: RunnableConfig,
+    ) -> MemoryStateUpdate | None:
+        """在代理执行前扫描记忆目录并加载所有 .md 文件的内容。
+
+        自动发现目录下所有 `.md` 文件并加载其内容到状态中。
+        如果状态中尚未存在则进行加载。
+        同时检测记忆文件是否为空，设置 memory_empty 标志位，
+        以便在系统提示词中触发初始化引导流程。
+
+        参数：
+            state: 当前代理状态。
+            runtime: 运行时上下文。
+            config: Runnable 配置。
+
+        返回：
+            填充了 memory_contents 和 memory_empty 的状态更新。
+        """
+        # 如果已经加载则跳过
+        if "memory_contents" in state:
+            return None
+
+        # 扫描目录下所有 .md 文件
+        md_files = await self._scan_memory_files()
+
+        contents: Dict[str, str] = {}
+        for path in md_files:
+            file_path = AsyncPath(path)
+            try:
+                # 检查文件大小
+                stat = await file_path.stat()
+                if stat.st_size > MAX_MEMORY_FILE_SIZE:
+                    logger.warning(
+                        "Skipping memory file %s: too large (%d bytes, max %d)",
+                        path,
+                        stat.st_size,
+                        MAX_MEMORY_FILE_SIZE,
+                    )
+                    continue
+                contents[path] = await file_path.read_text(encoding="utf-8")
+                logger.debug("Loaded memory from: %s", path)
+            except Exception as e:
+                logger.warning("Failed to read memory file %s: %s", path, e)
+
+        if contents:
+            logger.info(
+                "Loaded %d memory file(s) from %s: %s",
+                len(contents),
+                self.memory_dir,
+                [AsyncPath(p).name for p in contents],
+            )
+
+        # 检测记忆是否为空（文件不存在、文件内容为空白）
+        is_empty = self._is_memory_empty(contents)
+        if is_empty:
+            logger.info(
+                "Memory is empty, onboarding prompt will be activated for user preference collection."
+            )
+
+        return MemoryStateUpdate(memory_contents=contents, memory_empty=is_empty)
+
+    def modify_request(self, request: ModelRequest[ContextT]) -> ModelRequest[ContextT]:
+        """将记忆内容注入系统消息。
+
+        参数：
+            request: 要修改的模型请求。
+
+        返回：
+            将记忆注入系统消息后的修改后请求。
+        """
+        contents = request.state.get("memory_contents", {})  # noqa
+        memory_empty = request.state.get("memory_empty", False)  # noqa
+        agent_memory = self._format_agent_memory(contents, memory_empty=memory_empty)
+
+        new_system_message = append_to_system_message(
+            request.system_message, agent_memory
+        )
+
+        return request.override(system_message=new_system_message)
+
+    async def awrap_model_call(
+        self,
+        request: ModelRequest[ContextT],
+        handler: Callable[
+            [ModelRequest[ContextT]], Awaitable[ModelResponse[ResponseT]]
+        ],
+    ) -> ModelResponse[ResponseT]:
+        """异步包装模型调用，将记忆注入系统提示词。
+
+        参数：
+            request: 正在处理的模型请求。
+            handler: 使用修改后的请求进行调用的异步处理函数。
+
+        返回：
+            来自处理函数的模型响应。
+        """
+        modified_request = self.modify_request(request)
+        return await handler(modified_request)

app/agent/middleware/patch_tool_calls.py

@@ -0,0 +1,43 @@
+from typing import Any
+
+from langchain.agents.middleware import AgentMiddleware, AgentState
+from langchain_core.messages import AIMessage, ToolMessage
+from langgraph.runtime import Runtime
+from langgraph.types import Overwrite
+
+
+class PatchToolCallsMiddleware(AgentMiddleware):
+    """修复消息历史中悬空工具调用的中间件。"""
+
+    def before_agent(self, state: AgentState, runtime: Runtime[Any]) -> dict[str, Any] | None:  # noqa: ARG002
+        """在代理运行之前，处理任何 AIMessage 中悬空的工具调用。"""
+        messages = state["messages"]
+        if not messages or len(messages) == 0:
+            return None
+
+        patched_messages = []
+        # 遍历消息并添加任何悬空的工具调用
+        for i, msg in enumerate(messages):
+            patched_messages.append(msg)
+            if isinstance(msg, AIMessage) and msg.tool_calls:
+                for tool_call in msg.tool_calls:
+                    corresponding_tool_msg = next(
+                        (msg for msg in messages[i:] if msg.type == "tool" and msg.tool_call_id == tool_call["id"]),
+                        # ty: ignore[unresolved-attribute]
+                        None,
+                    )
+                    if corresponding_tool_msg is None:
+                        # 我们有一个悬空的工具调用，需要一个 ToolMessage
+                        tool_msg = (
+                            f"Tool call {tool_call['name']} with id {tool_call['id']} was "
+                            "cancelled - another message came in before it could be completed."
+                        )
+                        patched_messages.append(
+                            ToolMessage(
+                                content=tool_msg,
+                                name=tool_call["name"],
+                                tool_call_id=tool_call["id"],
+                            )
+                        )
+
+        return {"messages": Overwrite(patched_messages)}

app/agent/middleware/skills.py

@@ -0,0 +1,449 @@
+import re
+import shutil
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+from typing import Annotated, List
+from typing import NotRequired, TypedDict
+
+import yaml  # noqa
+from anyio import Path as AsyncPath
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    AgentState,
+    ContextT,
+    ModelRequest,
+    ModelResponse,
+    ResponseT,
+)
+from langchain.agents.middleware.types import PrivateStateAttr  # noqa
+from langchain_core.runnables import RunnableConfig
+from langgraph.runtime import Runtime
+
+from app.agent.middleware.utils import append_to_system_message
+from app.log import logger
+
+# 安全提示: SKILL.md 文件最大限制为 10MB，防止 DoS 攻击
+MAX_SKILL_FILE_SIZE = 10 * 1024 * 1024
+
+# Agent Skills 规范约束 (https://agentskills.io/specification)
+MAX_SKILL_NAME_LENGTH = 64
+MAX_SKILL_DESCRIPTION_LENGTH = 1024
+MAX_SKILL_COMPATIBILITY_LENGTH = 500
+
+
+class SkillMetadata(TypedDict):
+    """Skill 元数据，符合 Agent Skills 规范。"""
+
+    path: str
+    """SKILL.md 文件路径。"""
+
+    id: str
+    """Skill 标识符。
+    约束: 1-64 字符，仅限小写字母/数字/连字符，不能以连字符开头或结尾，无连续连字符，需与父目录名一致。
+    """
+
+    name: str
+    """Skill 名称。
+    约束: Skill中文描述。
+    """
+
+    description: str
+    """Skill 功能描述。
+    约束: 1-1024 字符，应说明功能及适用场景。
+    """
+
+    license: str | None
+    """许可证信息。"""
+
+    compatibility: str | None
+    """环境依赖或兼容性要求 (最多 500 字符)。"""
+
+    metadata: dict[str, str]
+    """附加元数据。"""
+
+    allowed_tools: list[str]
+    """(实验性) Skill 建议使用的工具列表。"""
+
+
+class SkillsState(AgentState):
+    """skills 中间件状态。"""
+
+    skills_metadata: NotRequired[Annotated[list[SkillMetadata], PrivateStateAttr]]
+    """已加载的 skill 元数据列表，不传播给父 agent。"""
+
+
+class SkillsStateUpdate(TypedDict):
+    """skills 中间件状态更新项。"""
+
+    skills_metadata: list[SkillMetadata]
+    """待合并的 skill 元数据列表。"""
+
+
+def _parse_skill_metadata(  # noqa: C901
+    content: str,
+    skill_path: str,
+    skill_id: str,
+) -> SkillMetadata | None:
+    """从 SKILL.md 内容中解析 YAML 前言并验证元数据。"""
+    if len(content) > MAX_SKILL_FILE_SIZE:
+        logger.warning(
+            "Skipping %s: content too large (%d bytes)", skill_path, len(content)
+        )
+        return None
+
+    # 匹配 --- 分隔的 YAML 前言
+    frontmatter_pattern = r"^---\s*\n(.*?)\n---\s*\n"
+    match = re.match(frontmatter_pattern, content, re.DOTALL)
+    if not match:
+        logger.warning("Skipping %s: no valid YAML frontmatter found", skill_path)
+        return None
+    frontmatter_str = match.group(1)
+
+    # 解析 YAML
+    try:
+        frontmatter_data = yaml.safe_load(frontmatter_str)
+    except yaml.YAMLError as e:
+        logger.warning("Invalid YAML in %s: %s", skill_path, e)
+        return None
+
+    if not isinstance(frontmatter_data, dict):
+        logger.warning("Skipping %s: frontmatter is not a mapping", skill_path)
+        return None
+
+    # SKill名称和描述
+    name = str(frontmatter_data.get("name", "")).strip()
+    description = str(frontmatter_data.get("description", "")).strip()
+    if not name or not description:
+        logger.warning(
+            "Skipping %s: missing required 'name' or 'description'", skill_path
+        )
+        return None
+    description_str = description
+    if len(description_str) > MAX_SKILL_DESCRIPTION_LENGTH:
+        logger.warning(
+            "Description exceeds %d characters in %s, truncating",
+            MAX_SKILL_DESCRIPTION_LENGTH,
+            skill_path,
+        )
+        description_str = description_str[:MAX_SKILL_DESCRIPTION_LENGTH]
+
+    # 可选的工具列表，支持空格或逗号分隔
+    raw_tools = frontmatter_data.get("allowed-tools")
+    if isinstance(raw_tools, str):
+        allowed_tools = [
+            t.strip(",")  # 兼容 Claude Code 风格的逗号分隔
+            for t in raw_tools.split()
+            if t.strip(",")
+        ]
+    else:
+        if raw_tools is not None:
+            logger.warning(
+                "Ignoring non-string 'allowed-tools' in %s (got %s)",
+                skill_path,
+                type(raw_tools).__name__,
+            )
+        allowed_tools = []
+
+    # 能力或环境兼容性说明，最多 500 字符
+    compatibility_str = str(frontmatter_data.get("compatibility", "")).strip() or None
+    if compatibility_str and len(compatibility_str) > MAX_SKILL_COMPATIBILITY_LENGTH:
+        logger.warning(
+            "Compatibility exceeds %d characters in %s, truncating",
+            MAX_SKILL_COMPATIBILITY_LENGTH,
+            skill_path,
+        )
+        compatibility_str = compatibility_str[:MAX_SKILL_COMPATIBILITY_LENGTH]
+
+    return SkillMetadata(
+        id=skill_id,
+        name=name,
+        description=description_str,
+        path=skill_path,
+        metadata=_validate_metadata(frontmatter_data.get("metadata", {}), skill_path),
+        license=str(frontmatter_data.get("license", "")).strip() or None,
+        compatibility=compatibility_str,
+        allowed_tools=allowed_tools,
+    )
+
+
+def _validate_metadata(
+    raw: object,
+    skill_path: str,
+) -> dict[str, str]:
+    """验证并规范化 YAML 前言中的元数据字段，确保为 dict[str, str] 类型。"""
+    if not isinstance(raw, dict):
+        if raw:
+            logger.warning(
+                "Ignoring non-dict metadata in %s (got %s)",
+                skill_path,
+                type(raw).__name__,
+            )
+        return {}
+    return {str(k): str(v) for k, v in raw.items()}
+
+
+def _format_skill_annotations(skill: SkillMetadata) -> str:
+    """构建许可证和兼容性说明字符串。"""
+    parts: list[str] = []
+    if skill.get("license"):
+        parts.append(f"License: {skill['license']}")
+    if skill.get("compatibility"):
+        parts.append(f"Compatibility: {skill['compatibility']}")
+    return ", ".join(parts)
+
+
+async def _alist_skills(source_path: AsyncPath) -> list[SkillMetadata]:
+    """异步列出指定路径下的所有技能。
+
+    扫描包含 SKILL.md 的目录并解析其元数据。
+    """
+    skills: list[SkillMetadata] = []
+
+    # 查找所有技能目录 (包含 SKILL.md 的目录)
+    skill_dirs: List[AsyncPath] = []
+    async for path in source_path.iterdir():
+        if await path.is_dir() and await (path / "SKILL.md").is_file():
+            skill_dirs.append(path)
+
+    if not skill_dirs:
+        return []
+
+    # 解析已下载的 SKILL.md
+    for skill_path in skill_dirs:
+        skill_md_path = skill_path / "SKILL.md"
+
+        skill_content = await skill_md_path.read_text(encoding="utf-8")
+
+        # 解析元数据
+        skill_metadata = _parse_skill_metadata(
+            content=skill_content,
+            skill_path=str(skill_md_path),
+            skill_id=skill_path.name,
+        )
+        if skill_metadata:
+            skills.append(skill_metadata)
+
+    return skills
+
+
+SKILLS_SYSTEM_PROMPT = """
+<skills_system>
+You have access to a skills library that provides specialized capabilities and domain knowledge.
+
+{skills_locations}
+
+**Available Skills:**
+
+{skills_list}
+
+**How to Use Skills (Progressive Disclosure):**
+
+Skills follow a **progressive disclosure** pattern - you see their name and description above, but only read full instructions when needed:
+
+1. **Recognize when a skill applies**: Check if the user's task matches a skill's description
+2. **Read the skill's full instructions**: Use the path shown in the skill list above
+3. **Follow the skill's instructions**: SKILL.md contains step-by-step workflows, best practices, and examples
+4. **Access supporting files**: Skills may include helper scripts, configs, or reference docs - use absolute paths
+
+**Creating New Skills:**
+
+When you identify a repetitive complex workflow or specialized task that would benefit from being a skill, you can create one:
+
+1. **Directory Structure**: Create a new directory in one of the skills locations. The directory name is the `skill-id`.
+   - Path format: `<skills_location>/<skill-id>/SKILL.md`
+   - `skill-id` constraints: 1-64 characters, lowercase letters, numbers, and hyphens only.
+2. **SKILL.md Format**: Must start with a YAML frontmatter followed by markdown instructions.
+   ```markdown
+   ---
+   name: Brief tool name (Chinese)
+   description: Detailed functional description and use cases (1-1024 chars)
+   allowed-tools: "tool1 tool2" (optional, space-separated list of recommended tools)
+   compatibility: "Environment requirements" (optional, max 500 chars)
+   ---
+   # Skill Instructions
+   Step-by-step workflows, best practices, and examples go here.
+   ```
+3. **Supporting Files**: You can add `.py` scripts, `.yaml` configs, or other files within the same skill directory. Reference them using absolute paths in `SKILL.md`.
+
+**When to Use Skills:**
+- User's request matches a skill's domain (e.g., "research X" -> web-research skill)
+- You need specialized knowledge or structured workflows
+- A skill provides proven patterns for complex tasks
+
+**Executing Skill Scripts:**
+Skills may contain Python scripts or other executable files. Always use absolute paths from the skill list.
+
+**Example Workflow:**
+
+User: "Can you research the latest developments in quantum computing?"
+
+1. Check available skills -> See "web-research" skill with its path
+2. Read the skill using the path shown
+3. Follow the skill's research workflow (search -> organize -> synthesize)
+4. Use any helper scripts with absolute paths
+
+Remember: Skills make you more capable and consistent. When in doubt, check if a skill exists for the task!
+</skills_system>
+"""
+
+
+def _sync_bundled_skills(bundled_dir: Path, target_dir: Path) -> None:
+    """将项目自带的技能同步到用户目录。
+
+    仅当目标目录中不存在对应技能子目录时才复制，已存在则跳过（不覆盖用户修改）。
+
+    Parameters
+    ----------
+    bundled_dir : Path
+        项目内置技能目录（如 ``ROOT_PATH / "skills"``）。
+    target_dir : Path
+        用户配置技能目录（如 ``CONFIG_PATH / "agent" / "skills"``）。
+    """
+    if not bundled_dir.is_dir():
+        return
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    for skill_src in bundled_dir.iterdir():
+        if not skill_src.is_dir():
+            continue
+        skill_md = skill_src / "SKILL.md"
+        if not skill_md.is_file():
+            continue
+
+        skill_dst = target_dir / skill_src.name
+        if skill_dst.exists():
+            # 目标已存在，跳过（不覆盖用户自定义修改）
+            continue
+
+        try:
+            shutil.copytree(str(skill_src), str(skill_dst))
+            logger.info("已自动复制内置技能 '%s' -> '%s'", skill_src.name, skill_dst)
+        except Exception as e:
+            logger.warning("复制内置技能 '%s' 失败: %s", skill_src.name, e)
+
+
+class SkillsMiddleware(AgentMiddleware[SkillsState, ContextT, ResponseT]):  # noqa
+    """加载并向系统提示词注入 Agent Skill 的中间件。
+
+    按源顺序加载 Skill，后加载的会覆盖重名的。
+    启动时自动将项目内置技能（bundled_skills_dir）同步到用户技能目录。
+    """
+
+    state_schema = SkillsState
+
+    def __init__(
+        self,
+        *,
+        sources: list[str],
+        bundled_skills_dir: str | None = None,
+    ) -> None:
+        """初始化 Skill 中间件。
+
+        Parameters
+        ----------
+        sources : list[str]
+            用户技能目录列表。
+        bundled_skills_dir : str | None
+            项目内置技能目录路径。若提供，在首次加载前会将其中不存在于
+            sources 首个目录的技能自动复制过去。
+        """
+        self.sources = sources
+        self.bundled_skills_dir = bundled_skills_dir
+        self.system_prompt_template = SKILLS_SYSTEM_PROMPT
+
+    def _format_skills_locations(self) -> str:
+        """格式化技能位置信息用于系统提示词。"""
+        locations = []
+
+        for i, source_path in enumerate(self.sources):
+            suffix = " (higher priority)" if i == len(self.sources) - 1 else ""
+            locations.append(f"**MoviePilot Skills**: `{source_path}`{suffix}")
+
+        return "\n".join(locations)
+
+    def _format_skills_list(self, skills: list[SkillMetadata]) -> str:
+        """格式化技能元数据列表用于系统提示词。"""
+        if not skills:
+            paths = [f"{source_path}" for source_path in self.sources]
+            return f"(No skills available yet. You can create skills in {' or '.join(paths)})"
+
+        lines = []
+        for skill in skills:
+            annotations = _format_skill_annotations(skill)
+            desc_line = f"- **{skill['id']}**: {skill['name']} - {skill['description']}"
+            if annotations:
+                desc_line += f" ({annotations})"
+            lines.append(desc_line)
+            if skill["allowed_tools"]:
+                lines.append(f"  -> Allowed tools: {', '.join(skill['allowed_tools'])}")
+            lines.append(f"  -> Read `{skill['path']}` for full instructions")
+
+        return "\n".join(lines)
+
+    def modify_request(self, request: ModelRequest[ContextT]) -> ModelRequest[ContextT]:
+        """将技能文档注入模型请求的系统消息中。"""
+        skills_metadata = request.state.get("skills_metadata", [])  # noqa
+        skills_locations = self._format_skills_locations()
+        skills_list = self._format_skills_list(skills_metadata)
+
+        skills_section = self.system_prompt_template.format(
+            skills_locations=skills_locations,
+            skills_list=skills_list,
+        )
+
+        new_system_message = append_to_system_message(
+            request.system_message, skills_section
+        )
+
+        return request.override(system_message=new_system_message)
+
+    async def abefore_agent(  # noqa
+        self, state: SkillsState, runtime: Runtime, config: RunnableConfig
+    ) -> SkillsStateUpdate | None:  # ty: ignore[invalid-method-override]
+        """在 Agent 执行前异步加载技能元数据。
+
+        每个会话仅加载一次。若 state 中已有则跳过。
+        首次加载时，会先将内置技能同步到用户目录（如不存在）。
+        """
+        # 如果 state 中已存在元数据则跳过
+        if "skills_metadata" in state:
+            return None
+
+        # 自动同步内置技能到首个用户技能目录
+        if self.bundled_skills_dir and self.sources:
+            bundled = Path(self.bundled_skills_dir)
+            target = Path(self.sources[0])
+            try:
+                _sync_bundled_skills(bundled, target)
+            except Exception as e:
+                logger.warning("同步内置技能失败: %s", e)
+
+        all_skills: dict[str, SkillMetadata] = {}
+
+        # 遍历源按顺序加载技能，重名时后者覆盖前者
+        for source_path in self.sources:
+            skill_source_path = AsyncPath(source_path)
+            if not await skill_source_path.exists():
+                await skill_source_path.mkdir(parents=True, exist_ok=True)
+                continue
+            source_skills = await _alist_skills(skill_source_path)
+            for skill in source_skills:
+                all_skills[skill["name"]] = skill
+
+        skills = list(all_skills.values())
+        return SkillsStateUpdate(skills_metadata=skills)
+
+    async def awrap_model_call(
+        self,
+        request: ModelRequest[ContextT],
+        handler: Callable[
+            [ModelRequest[ContextT]], Awaitable[ModelResponse[ResponseT]]
+        ],
+    ) -> ModelResponse[ResponseT]:
+        """在模型调用时注入技能文档。"""
+        modified_request = self.modify_request(request)
+        return await handler(modified_request)
+
+
+__all__ = ["SkillMetadata", "SkillsMiddleware"]

app/agent/middleware/utils.py

@@ -0,0 +1,21 @@
+from langchain_core.messages import SystemMessage, ContentBlock
+
+
+def append_to_system_message(
+        system_message: SystemMessage | None,
+        text: str,
+) -> SystemMessage:
+    """将文本追加到系统消息。
+
+    参数：
+        system_message: 现有的系统消息或 None。
+        text: 要添加到系统消息的文本。
+
+    返回：
+        追加了文本的新 SystemMessage。
+    """
+    new_content: list[ContentBlock] = list(system_message.content_blocks) if system_message else []  # noqa
+    if new_content:
+        text = f"\n\n{text}"
+    new_content.append({"type": "text", "text": text})
+    return SystemMessage(content_blocks=new_content)

app/agent/prompt/Agent Prompt.txt

@@ -1,72 +1,58 @@
-You are an AI media assistant powered by MoviePilot, specialized in managing home media ecosystems. Your expertise covers searching for movies/TV shows, managing subscriptions, overseeing downloads, and organizing media libraries.
+You are an AI media assistant powered by MoviePilot. You specialize in managing home media ecosystems: searching for movies/TV shows, managing subscriptions, overseeing downloads, and organizing media libraries.
 
 All your responses must be in **Chinese (中文)**.
 
 You act as a proactive agent. Your goal is to fully resolve the user's media-related requests autonomously. Do not end your turn until the task is complete or you are blocked and require user feedback.
 
 Core Capabilities:
-1. Media Search & Recognition
-- Identify movies, TV shows, and anime across various metadata providers.
-- Recognize media info from fuzzy filenames or incomplete titles.
-2. Subscription Management
-- Create complex rules for automated downloading of new episodes.
-- Monitor trending movies/shows for automated suggestions.
-3. Download Control
-- Intelligent torrent searching across private/public trackers.
-- Filter resources by quality (4K/1080p), codec (H265/H264), and release groups.
-4. System Status & Organization
-- Monitor download progress and server health.
-- Manage file transfers, renaming, and library cleanup.
+1. Media Search & Recognition — Identify movies, TV shows, and anime; recognize media from fuzzy filenames or incomplete titles.
+2. Subscription Management — Create rules for automated downloading; monitor trending content.
+3. Download Control — Search torrents across trackers; filter by quality, codec, and release group.
+4. System Status & Organization — Monitor downloads, server health, file transfers, renaming, and library cleanup.
 
 <communication>
-- Use Markdown for structured data like movie lists, download statuses, or technical details.
-- Avoid wrapping the entire response in a single code block. Use `inline code` for titles or parameters and ```code blocks``` for structured logs or data only when necessary.
-- ALWAYS use backticks for media titles (e.g., `Interstellar`), file paths, or specific parameters.
-- Optimize your writing for clarity and readability, using bold text for key information.
-- Provide comprehensive details for media (year, rating, resolution) to help users make informed decisions.
-- Do not stop for approval for read-only operations. Only stop for critical actions like starting a download or deleting a subscription.
-
-Important Notes:
-- User-Centric: Your tone should be helpful, professional, and media-savvy. 
-- No Coding Hallucinations: You are NOT a coding assistant. Do not offer code snippets, IDE tips, or programming help. Focus entirely on the MoviePilot media ecosystem.
-- Contextual Memory: Remember if the user preferred a specific version previously and prioritize similar results in future searches.
+- Default tone: friendly, concise, and slightly playful. Sound like a knowledgeable friend who genuinely enjoys media, not a corporate bot.
+- Use emojis sparingly but naturally to add personality (1-3 per response is enough). Good places for emojis: greetings, task completions, error messages, and emotional reactions to great/bad media.
+- Be direct. Give the user what they need without unnecessary preamble or recap, but don't be cold — a touch of warmth goes a long way.
+- Use Markdown for structured data (lists, tables). Use `inline code` for media titles, file paths, or parameters.
+- Include key details for media (year, rating, resolution) to help users decide, but do not over-explain.
+- Do not stop for approval on read-only operations. Only confirm before critical actions (starting downloads, deleting subscriptions).
+- You are NOT a coding assistant. Do not offer code snippets or programming help.
+- If the user has set a preferred communication style in memory, follow that style strictly instead of the defaults above.
 </communication>
 
-<status_update_spec>
-Definition: Provide a brief progress narrative (1-3 sentences) explaining what you have searched, what you found, and what you are about to execute.
-- **Immediate Execution**: If you state an intention to perform an action (e.g., "I'll search for the movie"), execute the corresponding tool call in the same turn.
-- Use natural tenses: "I've found...", "I'm checking...", "I will now add...".
-- Skip redundant updates if no significant progress has been made since the last message.
-</status_update_spec>
-
-<summary_spec>
-At the end of your session/turn, provide a concise summary of your actions.
-- Highlight key results: "Subscribed to `Stranger Things`", "Added `Avatar` 4K to download queue".
-- Use bullet points for multiple actions.
-- Do not repeat the internal execution steps; focus on the outcome for the user.
-</summary_spec>
+<response_format>
+- Keep responses short and punchy. One or two sentences for simple confirmations; a brief structured list for search results.
+- Do NOT repeat what the user just said back to them.
+- Do NOT narrate your internal reasoning or tool-calling process unless the user asks.
+- When reporting results, go straight to the data. Skip filler phrases like "let me help you" or "I found the following results for you".
+- After completing a task, summarize the outcome in one line. Do not list every step you took.
+- When something goes wrong, keep it light and brief — acknowledge the issue, suggest an alternative, move on.
+</response_format>
 
 <flow>
-1. Media Discovery: Start by identifying the exact media metadata (TMDB ID, Season/Episode) using search tools.
-2. Context Checking: Verify current status (Is it already in the library? Is it already subscribed?).
-3. Action Execution: Perform the requested task (Subscribe, Search Torrents, etc.) with a brief status update.
-4. Final Confirmation: Summarize the final state and wait for the next user command.
+1. Media Discovery: Identify exact media metadata (TMDB ID, Season/Episode) using search tools.
+2. Context Checking: Verify current status (already in library? already subscribed?).
+3. Action Execution: Perform the task with a brief status update only if the operation takes time.
+4. Final Confirmation: State the result concisely.
 </flow>
 
 <tool_calling_strategy>
-- Parallel Execution: You MUST call independent tools in parallel. For example, search for torrents on multiple sites or check both subscription and download status at once.
-- Information Depth: If a search returns ambiguous results, use `query_media_detail` or `recognize_media` to resolve the ambiguity before proceeding.
-- Proactive Fallback: If `search_media` fails, try `search_web` or fuzzy search with `recognize_media`. Do not ask the user for help unless all automated search methods are exhausted.
+- Call independent tools in parallel whenever possible.
+- If search results are ambiguous, use `query_media_detail` or `recognize_media` to clarify before proceeding.
+- If `search_media` fails, fall back to `search_web` or `recognize_media`. Only ask the user when all automated methods are exhausted.
 </tool_calling_strategy>
 
 <media_management_rules>
-1. Download Safety: You MUST present a list of found torrents (including size, seeds, and quality) and obtain the user's explicit consent before initiating any download.
-2. Subscription Logic: When adding a subscription, always check for the best matching quality profile based on user history or the default settings.
-3. Library Awareness: Always check if the user already has the content in their library to avoid duplicate downloads.
-4. Error Handling: If a site is down or a tool returns an error, explain the situation in plain Chinese (e.g., "站点响应超时") and suggest an alternative (e.g., "尝试从其他站点进行搜索").
+1. Download Safety: Present found torrents (size, seeds, quality) and get explicit consent before downloading.
+2. Subscription Logic: Check for the best matching quality profile based on user history or defaults.
+3. Library Awareness: Check if content already exists in the library to avoid duplicates.
+4. Error Handling: If a tool or site fails, briefly explain what went wrong and suggest an alternative.
 </media_management_rules>
 
 <markdown_spec>
 Specific markdown rules:
 {markdown_spec}
-</markdown_spec>
+</markdown_spec>
+
+Today's date: {current_date}

app/agent/prompt/__init__.py

@@ -1,9 +1,15 @@
 """提示词管理器"""
+
 from pathlib import Path
 from typing import Dict
 
 from app.log import logger
-from app.schemas import ChannelCapability, ChannelCapabilities, MessageChannel, ChannelCapabilityManager
+from app.schemas import (
+    ChannelCapability,
+    ChannelCapabilities,
+    MessageChannel,
+    ChannelCapabilityManager,
+)
 
 
 class PromptManager:
@@ -27,7 +33,7 @@ class PromptManager:
 
         prompt_file = self.prompts_dir / prompt_name
         try:
-            with open(prompt_file, 'r', encoding='utf-8') as f:
+            with open(prompt_file, "r", encoding="utf-8") as f:
                 content = f.read().strip()
             # 缓存提示词
             self.prompts_cache[prompt_name] = content
@@ -50,15 +56,22 @@ class PromptManager:
         base_prompt = self.load_prompt("Agent Prompt.txt")
 
         # 识别渠道
-        msg_channel = next((c for c in MessageChannel if c.value.lower() == channel.lower()), None) if channel else None
+        markdown_spec = ""
+        msg_channel = (
+            next(
+                (c for c in MessageChannel if c.value.lower() == channel.lower()), None
+            )
+            if channel
+            else None
+        )
         if msg_channel:
             # 获取渠道能力说明
             caps = ChannelCapabilityManager.get_capabilities(msg_channel)
             if caps:
-                base_prompt = base_prompt.replace(
-                    "{markdown_spec}",
-                    self._generate_formatting_instructions(caps)
-                )
+                markdown_spec = self._generate_formatting_instructions(caps)
+
+        # 始终替换占位符，避免后续 .format() 时因残留花括号报 KeyError
+        base_prompt = base_prompt.replace("{markdown_spec}", markdown_spec)
 
         return base_prompt
 
@@ -69,11 +82,15 @@ class PromptManager:
         """
         instructions = []
         if ChannelCapability.RICH_TEXT not in caps.capabilities:
-            instructions.append("- Formatting: Use **Plain Text ONLY**. The channel does NOT support Markdown.")
             instructions.append(
-                "- No Markdown Symbols: NEVER use `**`, `*`, `__`, or `[` blocks. Use natural text to emphasize (e.g., using ALL CAPS or separators).")
+                "- Formatting: Use **Plain Text ONLY**. The channel does NOT support Markdown."
+            )
             instructions.append(
-                "- Lists: Use plain text symbols like `>` or `*` at the start of lines, followed by manual line breaks.")
+                "- No Markdown Symbols: NEVER use `**`, `*`, `__`, or `[` blocks. Use natural text to emphasize (e.g., using ALL CAPS or separators)."
+            )
+            instructions.append(
+                "- Lists: Use plain text symbols like `>` or `*` at the start of lines, followed by manual line breaks."
+            )
             instructions.append("- Links: Paste URLs directly as text.")
         return "\n".join(instructions)
 

app/agent/tools/base.py

@@ -1,12 +1,11 @@
 import json
-import uuid
 from abc import ABCMeta, abstractmethod
 from typing import Any, Optional
 
-from langchain.tools import BaseTool
+from langchain_core.tools import BaseTool
 from pydantic import PrivateAttr
 
-from app.agent import StreamingCallbackHandler, conversation_manager
+from app.agent import StreamingHandler
 from app.chain import ChainBase
 from app.log import logger
 from app.schemas import Notification
@@ -18,15 +17,15 @@ class ToolChain(ChainBase):
 
 class MoviePilotTool(BaseTool, metaclass=ABCMeta):
     """
-    MoviePilot专用工具基类
+    MoviePilot专用工具基类（LangChain v1 / langchain_core）
     """
 
     _session_id: str = PrivateAttr()
     _user_id: str = PrivateAttr()
-    _channel: str = PrivateAttr(default=None)
-    _source: str = PrivateAttr(default=None)
-    _username: str = PrivateAttr(default=None)
-    _callback_handler: StreamingCallbackHandler = PrivateAttr(default=None)
+    _channel: Optional[str] = PrivateAttr(default=None)
+    _source: Optional[str] = PrivateAttr(default=None)
+    _username: Optional[str] = PrivateAttr(default=None)
+    _stream_handler: Optional[StreamingHandler] = PrivateAttr(default=None)
 
     def __init__(self, session_id: str, user_id: str, **kwargs):
         super().__init__(**kwargs)
@@ -34,93 +33,79 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
         self._user_id = user_id
 
     def _run(self, *args: Any, **kwargs: Any) -> Any:
-        pass
+        raise NotImplementedError("MoviePilotTool 只支持异步调用，请使用 _arun")
 
-    async def _arun(self, **kwargs) -> str:
+    async def _arun(self, *args: Any, **kwargs: Any) -> str:
         """
-        异步运行工具
+        异步运行工具，负责：
+        1. 在工具调用前将流式消息推送给用户
+        2. 持久化工具调用记录到会话记忆
+        3. 调用具体工具逻辑（子类实现的 execute 方法）
+        4. 持久化工具结果到会话记忆
         """
-        # 获取工具调用前的agent消息
-        agent_message = await self._callback_handler.get_message()
+        # 判断是否为后台任务模式（无渠道信息，如定时唤醒）
+        is_background = not self._channel and not self._source
 
-        # 生成唯一的工具调用ID
-        call_id = f"call_{str(uuid.uuid4())[:16]}"
-
-        # 记忆工具调用
-        await conversation_manager.add_conversation(
-            session_id=self._session_id,
-            user_id=self._user_id,
-            role="tool_call",
-            content=agent_message,
-            metadata={
-                "call_id": call_id,
-                "tool_name": self.name,
-                "parameters": kwargs
-            }
-        )
-
-        # 获取执行工具说明,优先使用工具自定义的提示消息，如果没有则使用 explanation
+        # 获取工具执行提示消息
         tool_message = self.get_tool_message(**kwargs)
         if not tool_message:
             explanation = kwargs.get("explanation")
             if explanation:
                 tool_message = explanation
 
-        # 合并agent消息和工具执行消息，一起发送
-        messages = []
-        if agent_message:
-            messages.append(agent_message)
-        if tool_message:
-            messages.append(f"⚙️ => {tool_message}")
+        if not is_background:
+            # 非后台模式：发送工具执行过程消息
+            if self._stream_handler and self._stream_handler.is_streaming:
+                # 流式渠道：工具消息直接追加到 buffer 中，与 Agent 文字合并为同一条流式消息
+                if tool_message:
+                    self._stream_handler.emit(f"\n\n⚙️ => {tool_message}\n\n")
+            else:
+                # 非流式渠道：保持原有行为，取出 Agent 文字 + 工具消息合并独立发送
+                agent_message = (
+                    await self._stream_handler.take() if self._stream_handler else ""
+                )
 
-        # 发送合并后的消息
-        if messages:
-            merged_message = "\n\n".join(messages)
-            await self.send_tool_message(merged_message, title="MoviePilot助手")
+                messages = []
+                if agent_message:
+                    messages.append(agent_message)
+                if tool_message:
+                    messages.append(f"⚙️ => {tool_message}")
 
-        logger.debug(f'Executing tool {self.name} with args: {kwargs}')
+                if messages:
+                    merged_message = "\n\n".join(messages)
+                    await self.send_tool_message(merged_message)
 
-        # 执行工具，捕获异常确保结果总是被存储到记忆中
+        logger.debug(f"Executing tool {self.name} with args: {kwargs}")
+
+        # 执行具体工具逻辑
         try:
             result = await self.run(**kwargs)
-            logger.debug(f'Tool {self.name} executed with result: {result}')
+            logger.debug(f"Tool {self.name} executed with result: {result}")
         except Exception as e:
-            # 记录异常详情
             error_message = f"工具执行异常 ({type(e).__name__}): {str(e)}"
-            logger.error(f'Tool {self.name} execution failed: {e}', exc_info=True)
+            logger.error(f"Tool {self.name} execution failed: {e}", exc_info=True)
             result = error_message
 
-        # 记忆工具调用结果
+        # 格式化结果
         if isinstance(result, str):
-            formated_result = result
+            formatted_result = result
         elif isinstance(result, (int, float)):
-            formated_result = str(result)
+            formatted_result = str(result)
         else:
-            formated_result = json.dumps(result, ensure_ascii=False, indent=2)
+            formatted_result = json.dumps(result, ensure_ascii=False, indent=2)
 
-        await conversation_manager.add_conversation(
-            session_id=self._session_id,
-            user_id=self._user_id,
-            role="tool_result",
-            content=formated_result,
-            metadata={
-                "call_id": call_id,
-                "tool_name": self.name,
-            }
-        )
-
-        return result
+        return formatted_result
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
         """
-        获取工具执行时的友好提示消息
-        
+        获取工具执行时的友好提示消息。
+
         子类可以重写此方法，根据实际参数生成个性化的提示消息。
         如果返回 None 或空字符串，将回退使用 explanation 参数。
-        
+
         Args:
             **kwargs: 工具的所有参数（包括 explanation）
-            
+
         Returns:
             str: 友好的提示消息，如果返回 None 或空字符串则使用 explanation
         """
@@ -128,6 +113,7 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
 
     @abstractmethod
     async def run(self, **kwargs) -> str:
+        """子类实现具体的工具执行逻辑"""
         raise NotImplementedError
 
     def set_message_attr(self, channel: str, source: str, username: str):
@@ -138,11 +124,11 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
         self._source = source
         self._username = username
 
-    def set_callback_handler(self, callback_handler: StreamingCallbackHandler):
+    def set_stream_handler(self, stream_handler: StreamingHandler):
         """
         设置回调处理器
         """
-        self._callback_handler = callback_handler
+        self._stream_handler = stream_handler
 
     async def send_tool_message(self, message: str, title: str = ""):
         """
@@ -155,6 +141,6 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
                 userid=self._user_id,
                 username=self._username,
                 title=title,
-                text=message
+                text=message,
             )
         )

app/agent/tools/factory.py

@@ -27,6 +27,7 @@ from app.agent.tools.impl.scrape_metadata import ScrapeMetadataTool
 from app.agent.tools.impl.query_episode_schedule import QueryEpisodeScheduleTool
 from app.agent.tools.impl.query_media_detail import QueryMediaDetailTool
 from app.agent.tools.impl.search_torrents import SearchTorrentsTool
+from app.agent.tools.impl.get_search_results import GetSearchResultsTool
 from app.agent.tools.impl.search_web import SearchWebTool
 from app.agent.tools.impl.send_message import SendMessageTool
 from app.agent.tools.impl.query_schedulers import QuerySchedulersTool
@@ -35,11 +36,20 @@ from app.agent.tools.impl.query_workflows import QueryWorkflowsTool
 from app.agent.tools.impl.run_workflow import RunWorkflowTool
 from app.agent.tools.impl.update_site_cookie import UpdateSiteCookieTool
 from app.agent.tools.impl.delete_download import DeleteDownloadTool
+from app.agent.tools.impl.delete_download_history import DeleteDownloadHistoryTool
+from app.agent.tools.impl.modify_download import ModifyDownloadTool
 from app.agent.tools.impl.query_directory_settings import QueryDirectorySettingsTool
 from app.agent.tools.impl.list_directory import ListDirectoryTool
 from app.agent.tools.impl.query_transfer_history import QueryTransferHistoryTool
 from app.agent.tools.impl.transfer_file import TransferFileTool
 from app.agent.tools.impl.execute_command import ExecuteCommandTool
+from app.agent.tools.impl.edit_file import EditFileTool
+from app.agent.tools.impl.write_file import WriteFileTool
+from app.agent.tools.impl.read_file import ReadFileTool
+from app.agent.tools.impl.browse_webpage import BrowseWebpageTool
+from app.agent.tools.impl.query_installed_plugins import QueryInstalledPluginsTool
+from app.agent.tools.impl.query_plugin_capabilities import QueryPluginCapabilitiesTool
+from app.agent.tools.impl.run_plugin_command import RunPluginCommandTool
 from app.core.plugin import PluginManager
 from app.log import logger
 from .base import MoviePilotTool
@@ -51,9 +61,14 @@ class MoviePilotToolFactory:
     """
 
     @staticmethod
-    def create_tools(session_id: str, user_id: str,
-                     channel: str = None, source: str = None, username: str = None,
-                     callback_handler: Callable = None) -> List[MoviePilotTool]:
+    def create_tools(
+        session_id: str,
+        user_id: str,
+        channel: str = None,
+        source: str = None,
+        username: str = None,
+        stream_handler: Callable = None,
+    ) -> List[MoviePilotTool]:
         """
         创建MoviePilot工具列表
         """
@@ -70,6 +85,7 @@ class MoviePilotToolFactory:
             UpdateSubscribeTool,
             SearchSubscribeTool,
             SearchTorrentsTool,
+            GetSearchResultsTool,
             SearchWebTool,
             AddDownloadTool,
             QuerySubscribesTool,
@@ -80,6 +96,8 @@ class MoviePilotToolFactory:
             DeleteSubscribeTool,
             QueryDownloadTasksTool,
             DeleteDownloadTool,
+            DeleteDownloadHistoryTool,
+            ModifyDownloadTool,
             QueryDownloadersTool,
             QuerySitesTool,
             UpdateSiteTool,
@@ -98,18 +116,22 @@ class MoviePilotToolFactory:
             RunSchedulerTool,
             QueryWorkflowsTool,
             RunWorkflowTool,
-            ExecuteCommandTool
+            ExecuteCommandTool,
+            EditFileTool,
+            WriteFileTool,
+            ReadFileTool,
+            BrowseWebpageTool,
+            QueryInstalledPluginsTool,
+            QueryPluginCapabilitiesTool,
+            RunPluginCommandTool,
         ]
         # 创建内置工具
         for ToolClass in tool_definitions:
-            tool = ToolClass(
-                session_id=session_id,
-                user_id=user_id
-            )
+            tool = ToolClass(session_id=session_id, user_id=user_id)
             tool.set_message_attr(channel=channel, source=source, username=username)
-            tool.set_callback_handler(callback_handler=callback_handler)
+            tool.set_stream_handler(stream_handler=stream_handler)
             tools.append(tool)
-        
+
         # 加载插件提供的工具
         plugin_tools_count = 0
         plugin_tools_info = PluginManager().get_plugin_agent_tools()
@@ -121,24 +143,31 @@ class MoviePilotToolFactory:
                 try:
                     # 验证工具类是否继承自 MoviePilotTool
                     if not issubclass(ToolClass, MoviePilotTool):
-                        logger.warning(f"插件 {plugin_name}({plugin_id}) 提供的工具类 {ToolClass.__name__} 未继承自 MoviePilotTool，已跳过")
+                        logger.warning(
+                            f"插件 {plugin_name}({plugin_id}) 提供的工具类 {ToolClass.__name__} 未继承自 MoviePilotTool，已跳过"
+                        )
                         continue
                     # 创建工具实例
-                    tool = ToolClass(
-                        session_id=session_id,
-                        user_id=user_id
+                    tool = ToolClass(session_id=session_id, user_id=user_id)
+                    tool.set_message_attr(
+                        channel=channel, source=source, username=username
                     )
-                    tool.set_message_attr(channel=channel, source=source, username=username)
-                    tool.set_callback_handler(callback_handler=callback_handler)
+                    tool.set_stream_handler(stream_handler=stream_handler)
                     tools.append(tool)
                     plugin_tools_count += 1
-                    logger.debug(f"成功加载插件 {plugin_name}({plugin_id}) 的工具: {ToolClass.__name__}")
+                    logger.debug(
+                        f"成功加载插件 {plugin_name}({plugin_id}) 的工具: {ToolClass.__name__}"
+                    )
                 except Exception as e:
-                    logger.error(f"加载插件 {plugin_name}({plugin_id}) 的工具 {ToolClass.__name__} 失败: {str(e)}")
-        
+                    logger.error(
+                        f"加载插件 {plugin_name}({plugin_id}) 的工具 {ToolClass.__name__} 失败: {str(e)}"
+                    )
+
         builtin_tools_count = len(tool_definitions)
         if plugin_tools_count > 0:
-            logger.info(f"成功创建 {len(tools)} 个MoviePilot工具（内置工具: {builtin_tools_count} 个，插件工具: {plugin_tools_count} 个）")
+            logger.info(
+                f"成功创建 {len(tools)} 个MoviePilot工具（内置工具: {builtin_tools_count} 个，插件工具: {plugin_tools_count} 个）"
+            )
         else:
             logger.info(f"成功创建 {len(tools)} 个MoviePilot工具")
         return tools

app/agent/tools/impl/_torrent_search_utils.py

@@ -0,0 +1,176 @@
+"""种子搜索工具辅助函数"""
+
+import re
+from typing import List, Optional
+
+from app.core.context import Context
+from app.utils.crypto import HashUtils
+from app.utils.string import StringUtils
+
+SEARCH_RESULT_CACHE_FILE = "__search_result__"
+TORRENT_RESULT_LIMIT = 50
+
+
+def build_torrent_ref(context: Optional[Context]) -> str:
+    """生成用于下载校验的短引用"""
+    if not context or not context.torrent_info:
+        return ""
+    return HashUtils.sha1(context.torrent_info.enclosure or "")[:7]
+
+
+def sort_season_options(options: List[str]) -> List[str]:
+    """按前端逻辑排序季集选项"""
+    if len(options) <= 1:
+        return options
+
+    parsed_options = []
+    for index, option in enumerate(options):
+        match = re.match(r"^S(\d+)(?:-S(\d+))?\s*(?:E(\d+)(?:-E(\d+))?)?$", option or "")
+        if not match:
+            parsed_options.append({
+                "original": option,
+                "season_num": 0,
+                "episode_num": 0,
+                "max_episode_num": 0,
+                "is_whole_season": False,
+                "index": index,
+            })
+            continue
+
+        episode_num = int(match.group(3)) if match.group(3) else 0
+        max_episode_num = int(match.group(4)) if match.group(4) else episode_num
+        parsed_options.append({
+            "original": option,
+            "season_num": int(match.group(1)),
+            "episode_num": episode_num,
+            "max_episode_num": max_episode_num,
+            "is_whole_season": not match.group(3),
+            "index": index,
+        })
+
+    whole_seasons = [item for item in parsed_options if item["is_whole_season"]]
+    episodes = [item for item in parsed_options if not item["is_whole_season"]]
+
+    whole_seasons.sort(key=lambda item: (-item["season_num"], item["index"]))
+    episodes.sort(
+        key=lambda item: (
+            -item["season_num"],
+            -(item["max_episode_num"] or item["episode_num"]),
+            -item["episode_num"],
+            item["index"],
+        )
+    )
+    return [item["original"] for item in whole_seasons + episodes]
+
+
+def append_option(options: List[str], value: Optional[str]) -> None:
+    """按前端逻辑收集去重后的筛选项"""
+    if value and value not in options:
+        options.append(value)
+
+
+def build_filter_options(items: List[Context]) -> dict:
+    """从搜索结果中构建筛选项汇总"""
+    filter_options = {
+        "site": [],
+        "season": [],
+        "freeState": [],
+        "edition": [],
+        "resolution": [],
+        "videoCode": [],
+        "releaseGroup": [],
+    }
+
+    for item in items:
+        torrent_info = item.torrent_info
+        meta_info = item.meta_info
+        append_option(filter_options["site"], getattr(torrent_info, "site_name", None))
+        append_option(filter_options["season"], getattr(meta_info, "season_episode", None))
+        append_option(filter_options["freeState"], getattr(torrent_info, "volume_factor", None))
+        append_option(filter_options["edition"], getattr(meta_info, "edition", None))
+        append_option(filter_options["resolution"], getattr(meta_info, "resource_pix", None))
+        append_option(filter_options["videoCode"], getattr(meta_info, "video_encode", None))
+        append_option(filter_options["releaseGroup"], getattr(meta_info, "resource_team", None))
+
+    filter_options["season"] = sort_season_options(filter_options["season"])
+    return filter_options
+
+
+def match_filter(filter_values: Optional[List[str]], value: Optional[str]) -> bool:
+    """匹配前端同款多选筛选规则"""
+    return not filter_values or bool(value and value in filter_values)
+
+
+def filter_contexts(items: List[Context],
+                    site: Optional[List[str]] = None,
+                    season: Optional[List[str]] = None,
+                    free_state: Optional[List[str]] = None,
+                    video_code: Optional[List[str]] = None,
+                    edition: Optional[List[str]] = None,
+                    resolution: Optional[List[str]] = None,
+                    release_group: Optional[List[str]] = None) -> List[Context]:
+    """按前端同款维度筛选结果"""
+    filtered_items = []
+    for item in items:
+        torrent_info = item.torrent_info
+        meta_info = item.meta_info
+        if (
+            match_filter(site, getattr(torrent_info, "site_name", None))
+            and match_filter(free_state, getattr(torrent_info, "volume_factor", None))
+            and match_filter(season, getattr(meta_info, "season_episode", None))
+            and match_filter(release_group, getattr(meta_info, "resource_team", None))
+            and match_filter(video_code, getattr(meta_info, "video_encode", None))
+            and match_filter(resolution, getattr(meta_info, "resource_pix", None))
+            and match_filter(edition, getattr(meta_info, "edition", None))
+        ):
+            filtered_items.append(item)
+    return filtered_items
+
+
+def simplify_search_result(context: Context, index: int) -> dict:
+    """精简单条搜索结果"""
+    simplified = {}
+    torrent_info = context.torrent_info
+    meta_info = context.meta_info
+    media_info = context.media_info
+
+    if torrent_info:
+        simplified["torrent_info"] = {
+            "title": torrent_info.title,
+            "size": StringUtils.format_size(torrent_info.size),
+            "seeders": torrent_info.seeders,
+            "peers": torrent_info.peers,
+            "site_name": torrent_info.site_name,
+            "torrent_url": f"{build_torrent_ref(context)}:{index}",
+            "page_url": torrent_info.page_url,
+            "volume_factor": torrent_info.volume_factor,
+            "freedate_diff": torrent_info.freedate_diff,
+            "pubdate": torrent_info.pubdate,
+        }
+
+    if media_info:
+        simplified["media_info"] = {
+            "title": media_info.title,
+            "en_title": media_info.en_title,
+            "year": media_info.year,
+            "type": media_info.type.value if media_info.type else None,
+            "season": media_info.season,
+            "tmdb_id": media_info.tmdb_id,
+        }
+
+    if meta_info:
+        simplified["meta_info"] = {
+            "name": meta_info.name,
+            "cn_name": meta_info.cn_name,
+            "en_name": meta_info.en_name,
+            "year": meta_info.year,
+            "type": meta_info.type.value if meta_info.type else None,
+            "begin_season": meta_info.begin_season,
+            "season_episode": meta_info.season_episode,
+            "resource_team": meta_info.resource_team,
+            "video_encode": meta_info.video_encode,
+            "edition": meta_info.edition,
+            "resource_pix": meta_info.resource_pix,
+        }
+
+    return simplified

app/agent/tools/impl/add_download.py

@@ -1,27 +1,31 @@
 """添加下载工具"""
 
-from typing import Optional, Type
+import re
+from pathlib import Path
+from typing import List, Optional, Type
 
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool, ToolChain
+from app.chain.search import SearchChain
 from app.chain.download import DownloadChain
+from app.core.config import settings
 from app.core.context import Context
 from app.core.metainfo import MetaInfo
 from app.db.site_oper import SiteOper
+from app.helper.directory import DirectoryHelper
 from app.log import logger
-from app.schemas import TorrentInfo
+from app.schemas import TorrentInfo, FileURI
+from app.utils.crypto import HashUtils
 
 
 class AddDownloadInput(BaseModel):
     """添加下载工具的输入参数模型"""
     explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
-    site_name: str = Field(..., description="Name of the torrent site/source (e.g., 'The Pirate Bay')")
-    torrent_title: str = Field(...,
-                               description="The display name/title of the torrent (e.g., 'The.Matrix.1999.1080p.BluRay.x264')")
-    torrent_url: str = Field(..., description="Direct URL to the torrent file (.torrent) or magnet link")
-    torrent_description: Optional[str] = Field(None,
-                                                  description="Brief description of the torrent content (optional)")
+    torrent_url: List[str] = Field(
+        ...,
+        description="One or more torrent_url values. Supports refs from get_search_results (`hash:id`) and magnet links."
+    )
     downloader: Optional[str] = Field(None,
                                       description="Name of the downloader to use (optional, uses default if not specified)")
     save_path: Optional[str] = Field(None,
@@ -32,75 +36,242 @@ class AddDownloadInput(BaseModel):
 
 class AddDownloadTool(MoviePilotTool):
     name: str = "add_download"
-    description: str = "Add torrent download task to the configured downloader (qBittorrent, Transmission, etc.). Downloads the torrent file and starts the download process with specified settings."
+    description: str = "Add torrent download tasks using refs from get_search_results or magnet links."
     args_schema: Type[BaseModel] = AddDownloadInput
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
         """根据下载参数生成友好的提示消息"""
-        torrent_title = kwargs.get("torrent_title", "")
-        site_name = kwargs.get("site_name", "")
+        torrent_urls = self._normalize_torrent_urls(kwargs.get("torrent_url"))
         downloader = kwargs.get("downloader")
-        
-        message = f"正在添加下载任务: {torrent_title}"
-        if site_name:
-            message += f" (来源: {site_name})"
+
+        if torrent_urls:
+            if len(torrent_urls) == 1:
+                if self._is_torrent_ref(torrent_urls[0]):
+                    message = f"正在添加下载任务: 资源 {torrent_urls[0]}"
+                else:
+                    message = "正在添加下载任务: 磁力链接"
+            else:
+                message = f"正在批量添加下载任务: 共 {len(torrent_urls)} 个资源"
+        else:
+            message = "正在添加下载任务"
         if downloader:
             message += f" [下载器: {downloader}]"
-        
+
         return message
 
-    async def run(self, site_name: str, torrent_title: str, torrent_url: str, torrent_description: Optional[str] = None,
+    @staticmethod
+    def _build_torrent_ref(context: Context) -> str:
+        """生成用于校验缓存项的短引用"""
+        if not context or not context.torrent_info:
+            return ""
+        return HashUtils.sha1(context.torrent_info.enclosure or "")[:7]
+
+    @staticmethod
+    def _is_torrent_ref(torrent_ref: Optional[str]) -> bool:
+        """判断是否为内部搜索结果引用"""
+        if not torrent_ref:
+            return False
+        return bool(re.fullmatch(r"[0-9a-f]{7}:\d+", str(torrent_ref).strip()))
+
+    @staticmethod
+    def _is_magnet_link_input(torrent_url: Optional[str]) -> bool:
+        """判断输入是否为允许直接添加的磁力链接"""
+        if not torrent_url:
+            return False
+        value = str(torrent_url).strip()
+        return value.startswith("magnet:")
+
+    @classmethod
+    def _resolve_cached_context(cls, torrent_ref: str) -> Optional[Context]:
+        """从最近一次搜索缓存中解析种子上下文，仅支持 hash:id 格式"""
+        ref = str(torrent_ref).strip()
+        if ":" not in ref:
+            return None
+        try:
+            ref_hash, ref_index = ref.split(":", 1)
+            index = int(ref_index)
+        except (TypeError, ValueError):
+            return None
+
+        if index < 1:
+            return None
+
+        results = SearchChain().last_search_results() or []
+        if index > len(results):
+            return None
+        context = results[index - 1]
+        if not ref_hash or cls._build_torrent_ref(context) != ref_hash:
+            return None
+        return context
+
+    @staticmethod
+    def _merge_labels_with_system_tag(labels: Optional[str]) -> Optional[str]:
+        """合并用户标签与系统默认标签，确保任务可被系统管理"""
+        system_tag = (settings.TORRENT_TAG or "").strip()
+        user_labels = [item.strip() for item in (labels or "").split(",") if item.strip()]
+
+        if system_tag and system_tag not in user_labels:
+            user_labels.append(system_tag)
+
+        return ",".join(user_labels) if user_labels else None
+
+    @staticmethod
+    def _format_failed_result(failed_messages: List[str]) -> str:
+        """统一格式化失败结果"""
+        return ", ".join([message for message in failed_messages if message])
+
+    @staticmethod
+    def _build_failure_message(torrent_ref: str, error_msg: Optional[str] = None) -> str:
+        """构造失败提示"""
+        normalized_error = (error_msg or "").strip()
+        prefix = "添加种子任务失败："
+        if normalized_error.startswith(prefix):
+            normalized_error = normalized_error[len(prefix):].lstrip()
+        if AddDownloadTool._is_magnet_link_input(normalized_error):
+            normalized_error = ""
+        if normalized_error:
+            return f"{torrent_ref} {normalized_error}"
+        if AddDownloadTool._is_torrent_ref(torrent_ref):
+            return torrent_ref
+        return ""
+
+    @classmethod
+    def _normalize_torrent_urls(cls, torrent_url: Optional[List[str] | str]) -> List[str]:
+        """统一规范 torrent_url 输入，保留所有非空值"""
+        if torrent_url is None:
+            return []
+
+        if isinstance(torrent_url, str):
+            candidates = torrent_url.split(",")
+        else:
+            candidates = torrent_url
+
+        return [str(item).strip() for item in candidates if item and str(item).strip()]
+
+    @staticmethod
+    def _resolve_direct_download_dir(save_path: Optional[str]) -> Optional[Path]:
+        """解析直接下载使用的目录，优先使用 save_path，其次使用默认下载目录"""
+        if save_path:
+            return Path(save_path)
+
+        download_dirs = DirectoryHelper().get_download_dirs()
+        if not download_dirs:
+            return None
+
+        dir_conf = download_dirs[0]
+        if not dir_conf.download_path:
+            return None
+
+        return Path(FileURI(storage=dir_conf.storage or "local", path=dir_conf.download_path).uri)
+
+    async def run(self, torrent_url: Optional[List[str]] = None,
                   downloader: Optional[str] = None, save_path: Optional[str] = None,
                   labels: Optional[str] = None, **kwargs) -> str:
         logger.info(
-            f"执行工具: {self.name}, 参数: site_name={site_name}, torrent_title={torrent_title}, torrent_url={torrent_url}, downloader={downloader}, save_path={save_path}, labels={labels}")
+            f"执行工具: {self.name}, 参数: torrent_url={torrent_url}, downloader={downloader}, save_path={save_path}, labels={labels}")
 
         try:
-            if not torrent_title or not torrent_url:
-                return "错误：必须提供种子标题和下载链接"
+            torrent_inputs = self._normalize_torrent_urls(torrent_url)
+            if not torrent_inputs:
+                return "错误：torrent_url 不能为空。"
 
-            # 使用DownloadChain添加下载
             download_chain = DownloadChain()
+            merged_labels = self._merge_labels_with_system_tag(labels)
+            success_count = 0
+            failed_messages = []
 
-            # 根据站点名称查询站点cookie
-            if not site_name:
-                return "错误：必须提供站点名称，请从搜索资源结果信息中获取"
-            siteinfo = await SiteOper().async_get_by_name(site_name)
-            if not siteinfo:
-                return f"错误：未找到站点信息：{site_name}"
+            for torrent_input in torrent_inputs:
+                if self._is_torrent_ref(torrent_input):
+                    cached_context = self._resolve_cached_context(torrent_input)
+                    if not cached_context or not cached_context.torrent_info:
+                        failed_messages.append(f"{torrent_input} 引用无效，请重新使用 get_search_results 查看搜索结果")
+                        continue
 
-            # 创建下载上下文
-            torrent_info = TorrentInfo(
-                title=torrent_title,
-                description=torrent_description,
-                enclosure=torrent_url,
-                site_name=site_name,
-                site_ua=siteinfo.ua,
-                site_cookie=siteinfo.cookie,
-                site_proxy=siteinfo.proxy,
-                site_order=siteinfo.pri,
-                site_downloader=siteinfo.downloader
-            )
-            meta_info = MetaInfo(title=torrent_title, subtitle=torrent_description)
-            media_info = await ToolChain().async_recognize_media(meta=meta_info)
-            if not media_info:
-                return "错误：无法识别媒体信息，无法添加下载任务"
-            context = Context(
-                torrent_info=torrent_info,
-                meta_info=meta_info,
-                media_info=media_info
-            )
+                    cached_torrent = cached_context.torrent_info
+                    site_name = cached_torrent.site_name
+                    torrent_title = cached_torrent.title or torrent_input
+                    torrent_description = cached_torrent.description
+                    enclosure = cached_torrent.enclosure
 
-            did = download_chain.download_single(
-                context=context,
-                downloader=downloader,
-                save_path=save_path,
-                label=labels
-            )
-            if did:
-                return f"成功添加下载任务：{torrent_title}"
-            else:
-                return "添加下载任务失败"
+                    if not site_name:
+                        failed_messages.append(f"{torrent_input} 缺少站点名称")
+                        continue
+
+                    siteinfo = await SiteOper().async_get_by_name(site_name)
+                    if not siteinfo:
+                        failed_messages.append(f"{torrent_input} 未找到站点信息 {site_name}")
+                        continue
+
+                    torrent_info = TorrentInfo(
+                        title=torrent_title,
+                        description=torrent_description,
+                        enclosure=enclosure,
+                        site_name=site_name,
+                        site_ua=siteinfo.ua,
+                        site_cookie=siteinfo.cookie,
+                        site_proxy=siteinfo.proxy,
+                        site_order=siteinfo.pri,
+                        site_downloader=siteinfo.downloader
+                    )
+                    meta_info = MetaInfo(title=torrent_title, subtitle=torrent_description)
+                    media_info = cached_context.media_info if cached_context.media_info else None
+                    if not media_info:
+                        media_info = await ToolChain().async_recognize_media(meta=meta_info)
+                    if not media_info:
+                        failed_messages.append(f"{torrent_input} 无法识别媒体信息")
+                        continue
+
+                    context = Context(
+                        torrent_info=torrent_info,
+                        meta_info=meta_info,
+                        media_info=media_info
+                    )
+                else:
+                    if not self._is_magnet_link_input(torrent_input):
+                        failed_messages.append(
+                            f"{torrent_input} 不是有效的下载内容，非 hash:id 时仅支持 magnet: 开头"
+                        )
+                        continue
+                    download_dir = self._resolve_direct_download_dir(save_path)
+                    if not download_dir:
+                        failed_messages.append(f"{torrent_input} 缺少保存路径，且系统未配置可用下载目录")
+                        continue
+                    result = download_chain.download(
+                        content=torrent_input,
+                        download_dir=download_dir,
+                        cookie=None,
+                        label=merged_labels,
+                        downloader=downloader
+                    )
+                    if result:
+                        _, did, _, error_msg = result
+                    else:
+                        did, error_msg = None, "未找到下载器"
+                    if did:
+                        success_count += 1
+                    else:
+                        failed_messages.append(self._build_failure_message(torrent_input, error_msg))
+                    continue
+
+                did, error_msg = download_chain.download_single(
+                    context=context,
+                    downloader=downloader,
+                    save_path=save_path,
+                    label=merged_labels,
+                    return_detail=True
+                )
+                if did:
+                    success_count += 1
+                else:
+                    failed_messages.append(self._build_failure_message(torrent_input, error_msg))
+
+            if success_count and not failed_messages:
+                return "任务添加成功"
+
+            if success_count:
+                return f"部分任务添加失败：{self._format_failed_result(failed_messages)}"
+
+            return f"任务添加失败：{self._format_failed_result(failed_messages)}"
         except Exception as e:
             logger.error(f"添加下载任务失败: {e}", exc_info=True)
             return f"添加下载任务时发生错误: {str(e)}"

app/agent/tools/impl/add_subscribe.py

@@ -16,11 +16,13 @@ class AddSubscribeInput(BaseModel):
     title: str = Field(..., description="The title of the media to subscribe to (e.g., 'The Matrix', 'Breaking Bad')")
     year: str = Field(..., description="Release year of the media (required for accurate identification)")
     media_type: str = Field(...,
-                            description="Type of media content: '电影' for films, '电视剧' for television series or anime series")
+                            description="Allowed values: movie, tv")
     season: Optional[int] = Field(None,
                                   description="Season number for TV shows (optional, if not specified will subscribe to all seasons)")
-    tmdb_id: Optional[str] = Field(None,
-                                   description="TMDB database ID for precise media identification (optional but recommended for accuracy)")
+    tmdb_id: Optional[int] = Field(None,
+                                   description="TMDB database ID for precise media identification (optional, can be obtained from search_media tool)")
+    douban_id: Optional[str] = Field(None,
+                                     description="Douban ID for precise media identification (optional, alternative to tmdb_id)")
     start_episode: Optional[int] = Field(None,
                                           description="Starting episode number for TV shows (optional, defaults to 1 if not specified)")
     total_episode: Optional[int] = Field(None,
@@ -32,9 +34,9 @@ class AddSubscribeInput(BaseModel):
     effect: Optional[str] = Field(None,
                                   description="Effect filter as regular expression (optional, e.g., 'HDR|DV|SDR')")
     filter_groups: Optional[List[str]] = Field(None,
-                                               description="List of filter rule group names to apply (optional, use query_rule_groups tool to get available rule groups)")
+                               description="List of filter rule group names to apply (optional, can be obtained from query_rule_groups tool)")
     sites: Optional[List[int]] = Field(None,
-                                       description="List of site IDs to search from (optional, use query_sites tool to get available site IDs)")
+                           description="List of site IDs to search from (optional, can be obtained from query_sites tool)")
 
 
 class AddSubscribeTool(MoviePilotTool):
@@ -60,26 +62,23 @@ class AddSubscribeTool(MoviePilotTool):
         return message
 
     async def run(self, title: str, year: str, media_type: str,
-                  season: Optional[int] = None, tmdb_id: Optional[str] = None,
+                  season: Optional[int] = None, tmdb_id: Optional[int] = None,
+                  douban_id: Optional[str] = None,
                   start_episode: Optional[int] = None, total_episode: Optional[int] = None,
                   quality: Optional[str] = None, resolution: Optional[str] = None,
                   effect: Optional[str] = None, filter_groups: Optional[List[str]] = None,
                   sites: Optional[List[int]] = None, **kwargs) -> str:
         logger.info(
             f"执行工具: {self.name}, 参数: title={title}, year={year}, media_type={media_type}, "
-            f"season={season}, tmdb_id={tmdb_id}, start_episode={start_episode}, "
+            f"season={season}, tmdb_id={tmdb_id}, douban_id={douban_id}, start_episode={start_episode}, "
             f"total_episode={total_episode}, quality={quality}, resolution={resolution}, "
             f"effect={effect}, filter_groups={filter_groups}, sites={sites}")
 
         try:
             subscribe_chain = SubscribeChain()
-            # 转换 tmdb_id 为整数
-            tmdbid_int = None
-            if tmdb_id:
-                try:
-                    tmdbid_int = int(tmdb_id)
-                except (ValueError, TypeError):
-                    logger.warning(f"无效的 tmdb_id: {tmdb_id}，将忽略")
+            media_type_enum = MediaType.from_agent(media_type)
+            if not media_type_enum:
+                return f"错误：无效的媒体类型 '{media_type}'，支持的类型：'movie', 'tv'"
 
             # 构建额外的订阅参数
             subscribe_kwargs = {}
@@ -99,10 +98,11 @@ class AddSubscribeTool(MoviePilotTool):
                 subscribe_kwargs['sites'] = sites
 
             sid, message = await subscribe_chain.async_add(
-                mtype=MediaType(media_type),
+                mtype=media_type_enum,
                 title=title,
                 year=year,
-                tmdbid=tmdbid_int,
+                tmdbid=tmdb_id,
+                doubanid=douban_id,
                 season=season,
                 username=self._user_id,
                 **subscribe_kwargs

app/agent/tools/impl/browse_webpage.py

@@ -0,0 +1,539 @@
+"""浏览器操作工具 - 让Agent能够通过Playwright控制浏览器进行网页交互"""
+
+import asyncio
+import base64
+import json
+from enum import Enum
+from typing import Optional, Type, List
+
+from pydantic import BaseModel, Field
+
+from app.agent.tools.base import MoviePilotTool
+from app.core.config import settings
+from app.log import logger
+
+# 页面内容最大长度
+MAX_CONTENT_LENGTH = 8000
+# 默认超时时间（秒）
+DEFAULT_TIMEOUT = 30
+# 截图最大宽度
+SCREENSHOT_MAX_WIDTH = 1280
+# 截图最大高度
+SCREENSHOT_MAX_HEIGHT = 720
+
+
+class BrowserAction(str, Enum):
+    """浏览器操作类型"""
+
+    GOTO = "goto"
+    GET_CONTENT = "get_content"
+    SCREENSHOT = "screenshot"
+    CLICK = "click"
+    FILL = "fill"
+    SELECT = "select"
+    EVALUATE = "evaluate"
+    WAIT = "wait"
+
+
+class BrowseWebpageInput(BaseModel):
+    """浏览器操作工具的输入参数模型"""
+
+    explanation: str = Field(
+        ...,
+        description="Clear explanation of why this browser action is being performed",
+    )
+    action: str = Field(
+        ...,
+        description=(
+            "The browser action to perform. Available actions:\n"
+            "- 'goto': Navigate to a URL, returns page title and text summary\n"
+            "- 'get_content': Get current page content (text or HTML)\n"
+            "- 'screenshot': Take a screenshot of the current page, returns base64 image\n"
+            "- 'click': Click on an element specified by selector\n"
+            "- 'fill': Fill text into an input element specified by selector\n"
+            "- 'select': Select an option from a dropdown element\n"
+            "- 'evaluate': Execute JavaScript code on the page and return the result\n"
+            "- 'wait': Wait for an element to appear on the page"
+        ),
+    )
+    url: Optional[str] = Field(
+        None, description="URL to navigate to (required for 'goto' action)"
+    )
+    selector: Optional[str] = Field(
+        None,
+        description="CSS selector or text selector for the target element (for 'click', 'fill', 'select', 'wait' actions). "
+        "Supports CSS selectors like '#id', '.class', 'tag', and Playwright text selectors like 'text=Click me'",
+    )
+    value: Optional[str] = Field(
+        None,
+        description="Value to fill into input or option value to select (for 'fill' and 'select' actions)",
+    )
+    script: Optional[str] = Field(
+        None,
+        description="JavaScript code to execute on the page (for 'evaluate' action). "
+        "The script should return a value that can be serialized to JSON.",
+    )
+    content_type: Optional[str] = Field(
+        "text",
+        description="Content type for 'get_content' action: 'text' for readable text, 'html' for raw HTML",
+    )
+    timeout: Optional[int] = Field(
+        DEFAULT_TIMEOUT, description="Timeout in seconds for the action (default: 30)"
+    )
+    cookies: Optional[str] = Field(
+        None,
+        description="Cookies to set for the browser context, format: 'name1=value1; name2=value2'",
+    )
+    user_agent: Optional[str] = Field(
+        None, description="Custom User-Agent string for the browser context"
+    )
+
+
+class BrowseWebpageTool(MoviePilotTool):
+    name: str = "browse_webpage"
+    description: str = (
+        "Control a real browser (Playwright) to interact with web pages. "
+        "Supports navigating to URLs, reading page content, taking screenshots, "
+        "clicking elements, filling forms, selecting dropdown options, executing JavaScript, and waiting for elements. "
+        "Use this tool when you need to interact with dynamic web pages, "
+        "fill in forms, click buttons, or extract content from JavaScript-rendered pages. "
+        "The browser session persists across multiple calls within the same conversation - "
+        "first call 'goto' to open a page, then use other actions to interact with it."
+    )
+    args_schema: Type[BaseModel] = BrowseWebpageInput
+
+    def get_tool_message(self, **kwargs) -> Optional[str]:
+        """根据操作类型生成友好的提示消息"""
+        action = kwargs.get("action", "")
+        url = kwargs.get("url", "")
+        selector = kwargs.get("selector", "")
+        action_messages = {
+            "goto": f"正在打开网页: {url}",
+            "get_content": "正在获取页面内容",
+            "screenshot": "正在截取页面截图",
+            "click": f"正在点击元素: {selector}",
+            "fill": f"正在填写表单: {selector}",
+            "select": f"正在选择选项: {selector}",
+            "evaluate": "正在执行 JavaScript",
+            "wait": f"正在等待元素: {selector}",
+        }
+        return action_messages.get(action, f"正在执行浏览器操作: {action}")
+
+    async def run(
+        self,
+        action: str,
+        url: Optional[str] = None,
+        selector: Optional[str] = None,
+        value: Optional[str] = None,
+        script: Optional[str] = None,
+        content_type: Optional[str] = "text",
+        timeout: Optional[int] = DEFAULT_TIMEOUT,
+        cookies: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        **kwargs,
+    ) -> str:
+        """执行浏览器操作"""
+        logger.info(
+            f"执行工具: {self.name}, 动作: {action}, URL: {url}, 选择器: {selector}"
+        )
+
+        try:
+            # 验证操作类型
+            try:
+                browser_action = BrowserAction(action)
+            except ValueError:
+                valid_actions = ", ".join([a.value for a in BrowserAction])
+                return f"错误: 不支持的操作类型 '{action}'，支持的操作: {valid_actions}"
+
+            # 参数校验
+            if browser_action == BrowserAction.GOTO and not url:
+                return "错误: 'goto' 操作需要提供 url 参数"
+            if (
+                browser_action
+                in (
+                    BrowserAction.CLICK,
+                    BrowserAction.FILL,
+                    BrowserAction.SELECT,
+                    BrowserAction.WAIT,
+                )
+                and not selector
+            ):
+                return f"错误: '{action}' 操作需要提供 selector 参数"
+            if browser_action == BrowserAction.FILL and value is None:
+                return "错误: 'fill' 操作需要提供 value 参数"
+            if browser_action == BrowserAction.EVALUATE and not script:
+                return "错误: 'evaluate' 操作需要提供 script 参数"
+
+            # 在线程池中运行同步的 Playwright 操作
+            loop = asyncio.get_running_loop()
+            result = await loop.run_in_executor(
+                None,
+                lambda: self._execute_browser_action(
+                    browser_action=browser_action,
+                    url=url,
+                    selector=selector,
+                    value=value,
+                    script=script,
+                    content_type=content_type,
+                    timeout=timeout,
+                    cookies=cookies,
+                    user_agent=user_agent,
+                ),
+            )
+            return result
+
+        except Exception as e:
+            logger.error(f"浏览器操作失败: {e}", exc_info=True)
+            return f"浏览器操作失败: {str(e)}"
+
+    def _execute_browser_action(
+        self,
+        browser_action: BrowserAction,
+        url: Optional[str],
+        selector: Optional[str],
+        value: Optional[str],
+        script: Optional[str],
+        content_type: Optional[str],
+        timeout: int,
+        cookies: Optional[str],
+        user_agent: Optional[str],
+    ) -> str:
+        """在同步上下文中执行 Playwright 浏览器操作"""
+        from playwright.sync_api import sync_playwright
+
+        try:
+            with sync_playwright() as playwright:
+                browser = None
+                context = None
+                page = None
+                try:
+                    # 启动浏览器
+                    browser_type = settings.PLAYWRIGHT_BROWSER_TYPE or "chromium"
+                    browser = playwright[browser_type].launch(headless=True)
+
+                    # 创建上下文
+                    context_kwargs = {}
+                    if user_agent:
+                        context_kwargs["user_agent"] = user_agent
+                    # 设置视口大小
+                    context_kwargs["viewport"] = {
+                        "width": SCREENSHOT_MAX_WIDTH,
+                        "height": SCREENSHOT_MAX_HEIGHT,
+                    }
+
+                    context = browser.new_context(**context_kwargs)
+                    page = context.new_page()
+                    page.set_default_timeout(timeout * 1000)
+
+                    # 设置 cookies
+                    if cookies:
+                        page.set_extra_http_headers({"cookie": cookies})
+
+                    # 对于非 goto 操作，如果提供了 url 先导航
+                    if url and browser_action != BrowserAction.GOTO:
+                        page.goto(
+                            url, wait_until="domcontentloaded", timeout=timeout * 1000
+                        )
+                        page.wait_for_load_state("networkidle", timeout=timeout * 1000)
+
+                    # 执行具体操作
+                    result = self._do_action(
+                        page,
+                        browser_action,
+                        url,
+                        selector,
+                        value,
+                        script,
+                        content_type,
+                        timeout,
+                    )
+                    return result
+
+                finally:
+                    if page:
+                        page.close()
+                    if context:
+                        context.close()
+                    if browser:
+                        browser.close()
+
+        except Exception as e:
+            logger.error(f"Playwright 执行失败: {e}", exc_info=True)
+            return f"Playwright 执行失败: {str(e)}"
+
+    def _do_action(
+        self,
+        page,
+        browser_action: BrowserAction,
+        url: Optional[str],
+        selector: Optional[str],
+        value: Optional[str],
+        script: Optional[str],
+        content_type: Optional[str],
+        timeout: int,
+    ) -> str:
+        """执行具体的浏览器操作"""
+
+        if browser_action == BrowserAction.GOTO:
+            return self._action_goto(page, url, timeout)
+
+        elif browser_action == BrowserAction.GET_CONTENT:
+            return self._action_get_content(page, content_type)
+
+        elif browser_action == BrowserAction.SCREENSHOT:
+            return self._action_screenshot(page)
+
+        elif browser_action == BrowserAction.CLICK:
+            return self._action_click(page, selector, timeout)
+
+        elif browser_action == BrowserAction.FILL:
+            return self._action_fill(page, selector, value, timeout)
+
+        elif browser_action == BrowserAction.SELECT:
+            return self._action_select(page, selector, value, timeout)
+
+        elif browser_action == BrowserAction.EVALUATE:
+            return self._action_evaluate(page, script)
+
+        elif browser_action == BrowserAction.WAIT:
+            return self._action_wait(page, selector, timeout)
+
+        return f"未知操作: {browser_action}"
+
+    @staticmethod
+    def _action_goto(page, url: str, timeout: int) -> str:
+        """导航到URL"""
+        response = page.goto(url, wait_until="domcontentloaded", timeout=timeout * 1000)
+        try:
+            page.wait_for_load_state("networkidle", timeout=min(timeout, 15) * 1000)
+        except Exception:
+            # networkidle 超时不是致命错误，页面可能已经可用
+            pass
+
+        status = response.status if response else "unknown"
+        title = page.title()
+        page_url = page.url
+
+        # 提取页面可读文本摘要
+        text_content = page.inner_text("body")
+        if text_content and len(text_content) > MAX_CONTENT_LENGTH:
+            text_content = text_content[:MAX_CONTENT_LENGTH] + "\n\n...(内容已截断)"
+
+        # 提取页面链接
+        links = page.evaluate("""
+            () => {
+                const links = [];
+                document.querySelectorAll('a[href]').forEach(a => {
+                    const text = a.innerText.trim();
+                    const href = a.href;
+                    if (text && href && !href.startsWith('javascript:')) {
+                        links.push({text: text.substring(0, 80), href: href});
+                    }
+                });
+                return links.slice(0, 30);
+            }
+        """)
+
+        # 提取表单信息
+        forms = page.evaluate("""
+            () => {
+                const forms = [];
+                document.querySelectorAll('input, textarea, select, button').forEach(el => {
+                    const info = {
+                        tag: el.tagName.toLowerCase(),
+                        type: el.type || '',
+                        name: el.name || '',
+                        id: el.id || '',
+                        placeholder: el.placeholder || '',
+                        value: el.tagName.toLowerCase() === 'select' ? '' : (el.value || '').substring(0, 50),
+                        text: el.innerText ? el.innerText.trim().substring(0, 50) : ''
+                    };
+                    // 只保留有标识信息的元素
+                    if (info.name || info.id || info.placeholder || info.text) {
+                        forms.push(info);
+                    }
+                });
+                return forms.slice(0, 30);
+            }
+        """)
+
+        result = {
+            "status": status,
+            "url": page_url,
+            "title": title,
+            "text_content": text_content,
+        }
+        if links:
+            result["links"] = links
+        if forms:
+            result["form_elements"] = forms
+
+        return json.dumps(result, ensure_ascii=False, indent=2)
+
+    @staticmethod
+    def _action_get_content(page, content_type: Optional[str]) -> str:
+        """获取页面内容"""
+        title = page.title()
+        page_url = page.url
+
+        if content_type == "html":
+            content = page.content()
+        else:
+            content = page.inner_text("body")
+
+        if content and len(content) > MAX_CONTENT_LENGTH:
+            content = content[:MAX_CONTENT_LENGTH] + "\n\n...(内容已截断)"
+
+        result = {
+            "url": page_url,
+            "title": title,
+            "content_type": content_type,
+            "content": content,
+        }
+        return json.dumps(result, ensure_ascii=False, indent=2)
+
+    @staticmethod
+    def _action_screenshot(page) -> str:
+        """截取页面截图"""
+        screenshot_bytes = page.screenshot(
+            full_page=False,
+            type="jpeg",
+            quality=60,
+        )
+        screenshot_b64 = base64.b64encode(screenshot_bytes).decode("utf-8")
+
+        # 限制截图大小（base64编码后大约增大33%）
+        max_b64_size = 200 * 1024  # ~150KB 原始图片
+        if len(screenshot_b64) > max_b64_size:
+            # 降低质量重新截图
+            screenshot_bytes = page.screenshot(
+                full_page=False,
+                type="jpeg",
+                quality=30,
+            )
+            screenshot_b64 = base64.b64encode(screenshot_bytes).decode("utf-8")
+
+        title = page.title()
+        page_url = page.url
+
+        result = {
+            "url": page_url,
+            "title": title,
+            "screenshot_base64": screenshot_b64,
+            "format": "jpeg",
+            "note": "截图已以 base64 编码返回",
+        }
+        return json.dumps(result, ensure_ascii=False, indent=2)
+
+    @staticmethod
+    def _action_click(page, selector: str, timeout: int) -> str:
+        """点击元素"""
+        page.click(selector, timeout=timeout * 1000)
+
+        # 等待可能的页面变化
+        try:
+            page.wait_for_load_state("networkidle", timeout=5000)
+        except Exception:
+            pass
+
+        title = page.title()
+        page_url = page.url
+
+        return json.dumps(
+            {
+                "success": True,
+                "message": f"成功点击元素: {selector}",
+                "current_url": page_url,
+                "current_title": title,
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+
+    @staticmethod
+    def _action_fill(page, selector: str, value: str, timeout: int) -> str:
+        """填写表单"""
+        page.fill(selector, value, timeout=timeout * 1000)
+
+        return json.dumps(
+            {
+                "success": True,
+                "message": f"成功填写元素 '{selector}' 的值为 '{value}'",
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+
+    @staticmethod
+    def _action_select(page, selector: str, value: Optional[str], timeout: int) -> str:
+        """选择下拉选项"""
+        if value:
+            page.select_option(selector, value=value, timeout=timeout * 1000)
+        else:
+            return "错误: 'select' 操作需要提供 value 参数"
+
+        return json.dumps(
+            {
+                "success": True,
+                "message": f"成功选择元素 '{selector}' 的选项 '{value}'",
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+
+    @staticmethod
+    def _action_evaluate(page, script: str) -> str:
+        """执行 JavaScript"""
+        result = page.evaluate(script)
+
+        # 格式化结果
+        if result is None:
+            formatted = "null"
+        elif isinstance(result, (dict, list)):
+            formatted = json.dumps(result, ensure_ascii=False, indent=2)
+        else:
+            formatted = str(result)
+
+        # 限制结果长度
+        if len(formatted) > MAX_CONTENT_LENGTH:
+            formatted = formatted[:MAX_CONTENT_LENGTH] + "\n\n...(结果已截断)"
+
+        return json.dumps(
+            {
+                "success": True,
+                "result": formatted,
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+
+    @staticmethod
+    def _action_wait(page, selector: str, timeout: int) -> str:
+        """等待元素出现"""
+        element = page.wait_for_selector(selector, timeout=timeout * 1000)
+
+        if element:
+            visible = element.is_visible()
+            text = element.inner_text()
+            if text and len(text) > 200:
+                text = text[:200] + "..."
+
+            return json.dumps(
+                {
+                    "success": True,
+                    "message": f"元素 '{selector}' 已出现",
+                    "visible": visible,
+                    "text": text,
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+        else:
+            return json.dumps(
+                {
+                    "success": False,
+                    "message": f"等待元素 '{selector}' 超时",
+                },
+                ensure_ascii=False,
+                indent=2,
+            )

app/agent/tools/impl/delete_download.py

@@ -12,23 +12,23 @@ from app.log import logger
 class DeleteDownloadInput(BaseModel):
     """删除下载任务工具的输入参数模型"""
     explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
-    task_identifier: str = Field(..., description="Task identifier: can be task hash (unique identifier) or task title/name")
+    hash: str = Field(..., description="Task hash (can be obtained from query_download_tasks tool)")
     downloader: Optional[str] = Field(None, description="Name of specific downloader (optional, if not provided will search all downloaders)")
     delete_files: Optional[bool] = Field(False, description="Whether to delete downloaded files along with the task (default: False, only removes the task from downloader)")
 
 
 class DeleteDownloadTool(MoviePilotTool):
     name: str = "delete_download"
-    description: str = "Delete a download task from the downloader. Can delete by task hash (unique identifier) or task title/name. Optionally specify the downloader name and whether to delete downloaded files."
+    description: str = "Delete a download task from the downloader by task hash only. Optionally specify the downloader name and whether to delete downloaded files."
     args_schema: Type[BaseModel] = DeleteDownloadInput
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
         """根据删除参数生成友好的提示消息"""
-        task_identifier = kwargs.get("task_identifier", "")
+        hash_value = kwargs.get("hash", "")
         downloader = kwargs.get("downloader")
         delete_files = kwargs.get("delete_files", False)
         
-        message = f"正在删除下载任务: {task_identifier}"
+        message = f"正在删除下载任务: {hash_value}"
         if downloader:
             message += f" [下载器: {downloader}]"
         if delete_files:
@@ -36,40 +36,26 @@ class DeleteDownloadTool(MoviePilotTool):
         
         return message
 
-    async def run(self, task_identifier: str, downloader: Optional[str] = None,
+    async def run(self, hash: str, downloader: Optional[str] = None,
                   delete_files: Optional[bool] = False, **kwargs) -> str:
-        logger.info(f"执行工具: {self.name}, 参数: task_identifier={task_identifier}, downloader={downloader}, delete_files={delete_files}")
+        logger.info(f"执行工具: {self.name}, 参数: hash={hash}, downloader={downloader}, delete_files={delete_files}")
 
         try:
             download_chain = DownloadChain()
-            
-            # 如果task_identifier看起来像hash（通常是40个字符的十六进制字符串）
-            task_hash = None
-            if len(task_identifier) == 40 and all(c in '0123456789abcdefABCDEF' for c in task_identifier):
-                # 直接使用hash
-                task_hash = task_identifier
-            else:
-                # 通过标题查找任务
-                downloads = download_chain.downloading(name=downloader)
-                for dl in downloads:
-                    # 检查标题或名称是否匹配
-                    if (task_identifier.lower() in (dl.title or "").lower()) or \
-                       (task_identifier.lower() in (dl.name or "").lower()):
-                        task_hash = dl.hash
-                        break
-                
-                if not task_hash:
-                    return f"未找到匹配的下载任务：{task_identifier}，请使用 query_downloads 工具查询可用的下载任务"
+
+            # 仅支持通过hash删除任务
+            if len(hash) != 40 or not all(c in '0123456789abcdefABCDEF' for c in hash):
+                return "参数错误：hash 格式无效，请先使用 query_download_tasks 工具获取正确的 hash。"
             
             # 删除下载任务
             # remove_torrents 支持 delete_file 参数，可以控制是否删除文件
-            result = download_chain.remove_torrents(hashs=[task_hash], downloader=downloader, delete_file=delete_files)
+            result = download_chain.remove_torrents(hashs=[hash], downloader=downloader, delete_file=delete_files)
             
             if result:
                 files_info = "（包含文件）" if delete_files else "（不包含文件）"
-                return f"成功删除下载任务：{task_identifier} {files_info}"
+                return f"成功删除下载任务：{hash} {files_info}"
             else:
-                return f"删除下载任务失败：{task_identifier}，请检查任务是否存在或下载器是否可用"
+                return f"删除下载任务失败：{hash}，请检查任务是否存在或下载器是否可用"
         except Exception as e:
             logger.error(f"删除下载任务失败: {e}", exc_info=True)
             return f"删除下载任务时发生错误: {str(e)}"

app/agent/tools/impl/delete_download_history.py

@@ -0,0 +1,43 @@
+"""删除下载历史记录工具"""
+
+from typing import Optional, Type
+
+from pydantic import BaseModel, Field
+
+from app.agent.tools.base import MoviePilotTool
+from app.db import AsyncSessionFactory
+from app.db.models.downloadhistory import DownloadHistory
+from app.log import logger
+
+
+class DeleteDownloadHistoryInput(BaseModel):
+    """删除下载历史记录工具的输入参数模型"""
+
+    explanation: str = Field(
+        ...,
+        description="Clear explanation of why this tool is being used in the current context",
+    )
+    history_id: int = Field(
+        ..., description="The ID of the download history record to delete"
+    )
+
+
+class DeleteDownloadHistoryTool(MoviePilotTool):
+    name: str = "delete_download_history"
+    description: str = "Delete a download history record by ID. This only removes the record from the database, does not delete any actual files."
+    args_schema: Type[BaseModel] = DeleteDownloadHistoryInput
+
+    def get_tool_message(self, **kwargs) -> Optional[str]:
+        history_id = kwargs.get("history_id")
+        return f"正在删除下载历史记录 ID: {history_id}"
+
+    async def run(self, history_id: int, **kwargs) -> str:
+        logger.info(f"执行工具: {self.name}, 参数: history_id={history_id}")
+
+        try:
+            async with AsyncSessionFactory() as db:
+                await DownloadHistory.async_delete(db, history_id)
+                return f"下载历史记录 ID: {history_id} 已成功删除"
+        except Exception as e:
+            logger.error(f"删除下载历史记录失败: {e}", exc_info=True)
+            return f"删除下载历史记录时发生错误: {str(e)}"

app/agent/tools/impl/edit_file.py

@@ -0,0 +1,75 @@
+"""文件编辑工具"""
+
+from pathlib import Path
+from typing import Optional, Type
+
+from anyio import Path as AsyncPath
+from pydantic import BaseModel, Field
+
+from app.agent.tools.base import MoviePilotTool
+from app.log import logger
+
+
+class EditFileInput(BaseModel):
+    """Input parameters for edit file tool"""
+    file_path: str = Field(..., description="The absolute path of the file to edit")
+    old_text: str = Field(..., description="The exact old text to be replaced")
+    new_text: str = Field(..., description="The new text to replace with")
+
+
+class EditFileTool(MoviePilotTool):
+    name: str = "edit_file"
+    description: str = "Edit a file by replacing specific old text with new text. Useful for modifying configuration files, code, or scripts."
+    args_schema: Type[BaseModel] = EditFileInput
+
+    def get_tool_message(self, **kwargs) -> Optional[str]:
+        """根据参数生成友好的提示消息"""
+        file_path = kwargs.get("file_path", "")
+        file_name = Path(file_path).name if file_path else "未知文件"
+        return f"正在编辑文件: {file_name}"
+
+    async def run(self, file_path: str, old_text: str, new_text: str, **kwargs) -> str:
+        logger.info(f"执行工具: {self.name}, 参数: file_path={file_path}")
+
+        try:
+            path = AsyncPath(file_path)
+            # 校验逻辑：如果要替换特定文本，文件必须存在且包含该文本
+            if not await path.exists():
+                # 如果 old_text 为空，可能用户想直接创建文件，但通常 edit_file 需要匹配旧内容
+                if old_text:
+                    return f"错误：文件 {file_path} 不存在，无法进行内容替换。"
+                
+            if await path.exists() and not await path.is_file():
+                return f"错误：{file_path} 不是一个文件"
+
+            if await path.exists():
+                content = await path.read_text(encoding="utf-8")
+                if old_text not in content:
+                    logger.warning(f"编辑文件 {file_path} 失败：未找到指定的旧文本块")
+                    return f"错误：在文件 {file_path} 中未找到指定的旧文本。请确保包含所有的空格、缩进 and 换行符。"
+                occurrences = content.count(old_text)
+                new_content = content.replace(old_text, new_text)
+            else:
+                # 文件不存在且 old_text 为空的情形（初始化新文件）
+                new_content = new_text
+                occurrences = 1
+
+            # 自动创建父目录
+            await path.parent.mkdir(parents=True, exist_ok=True)
+            
+            # 写入文件
+            await path.write_text(new_content, encoding="utf-8")
+                
+            logger.info(f"成功编辑文件 {file_path}，替换了 {occurrences} 处内容")
+            return f"成功编辑文件 {file_path} (替换了 {occurrences} 处匹配内容)"
+
+
+        except PermissionError:
+            return f"错误：没有访问/修改 {file_path} 的权限"
+        except UnicodeDecodeError:
+            return f"错误：{file_path} 不是文本文件，无法编辑"
+        except Exception as e:
+            logger.error(f"编辑文件 {file_path} 时发生错误: {str(e)}", exc_info=True)
+            return f"操作失败: {str(e)}"
+
+

app/agent/tools/impl/get_recommendations.py

@@ -8,6 +8,7 @@ from pydantic import BaseModel, Field
 from app.agent.tools.base import MoviePilotTool
 from app.chain.recommend import RecommendChain
 from app.log import logger
+from app.schemas.types import MediaType, media_type_to_agent
 
 
 class GetRecommendationsInput(BaseModel):
@@ -30,7 +31,7 @@ class GetRecommendationsInput(BaseModel):
                                   "'douban_tv_animation' for Douban popular animation, "
                                   "'bangumi_calendar' for Bangumi anime calendar")
     media_type: Optional[str] = Field("all",
-                                      description="Type of media content: '电影' for films, '电视剧' for television series or anime series, 'all' for all types")
+                                      description="Allowed values: movie, tv, all")
     limit: Optional[int] = Field(20,
                                  description="Maximum number of recommendations to return (default: 20, maximum: 100)")
 
@@ -75,6 +76,12 @@ class GetRecommendationsTool(MoviePilotTool):
                   media_type: Optional[str] = "all", limit: Optional[int] = 20, **kwargs) -> str:
         logger.info(f"执行工具: {self.name}, 参数: source={source}, media_type={media_type}, limit={limit}")
         try:
+            if media_type != "all":
+                media_type_enum = MediaType.from_agent(media_type)
+                if not media_type_enum:
+                    return f"错误：无效的媒体类型 '{media_type}'，支持的类型：'movie', 'tv', 'all'"
+                media_type = media_type_enum.to_agent()  # 归一化为 "movie"/"tv"
+
             recommend_chain = RecommendChain()
             results = []
             if source == "tmdb_trending":
@@ -149,7 +156,7 @@ class GetRecommendationsTool(MoviePilotTool):
                         "title": r.get("title"),
                         "en_title": r.get("en_title"),
                         "year": r.get("year"),
-                        "type": r.get("type"),
+                        "type": media_type_to_agent(r.get("type")),
                         "season": r.get("season"),
                         "tmdb_id": r.get("tmdb_id"),
                         "imdb_id": r.get("imdb_id"),

app/agent/tools/impl/get_search_results.py

@@ -0,0 +1,108 @@
+"""获取搜索结果工具"""
+
+import json
+import re
+from typing import List, Optional, Type
+
+from pydantic import BaseModel, Field
+
+from app.agent.tools.base import MoviePilotTool
+from app.chain.search import SearchChain
+from app.log import logger
+from ._torrent_search_utils import (
+    TORRENT_RESULT_LIMIT,
+    build_filter_options,
+    filter_contexts,
+    simplify_search_result,
+)
+
+
+class GetSearchResultsInput(BaseModel):
+    """获取搜索结果工具的输入参数模型"""
+    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    site: Optional[List[str]] = Field(None, description="Site name filters")
+    season: Optional[List[str]] = Field(None, description="Season or episode filters")
+    free_state: Optional[List[str]] = Field(None, description="Promotion state filters")
+    video_code: Optional[List[str]] = Field(None, description="Video codec filters")
+    edition: Optional[List[str]] = Field(None, description="Edition filters")
+    resolution: Optional[List[str]] = Field(None, description="Resolution filters")
+    release_group: Optional[List[str]] = Field(None, description="Release group filters")
+    title_pattern: Optional[str] = Field(None, description="Regular expression pattern to filter torrent titles (e.g., '4K|2160p|UHD', '1080p.*BluRay')")
+    show_filter_options: Optional[bool] = Field(False, description="Whether to return only optional filter options for re-checking available conditions")
+
+class GetSearchResultsTool(MoviePilotTool):
+    name: str = "get_search_results"
+    description: str = "Get cached torrent search results from search_torrents with optional filters. Returns at most the first 50 matches."
+    args_schema: Type[BaseModel] = GetSearchResultsInput
+
+    def get_tool_message(self, **kwargs) -> Optional[str]:
+        return "正在获取搜索结果"
+
+    async def run(self, site: Optional[List[str]] = None, season: Optional[List[str]] = None,
+                  free_state: Optional[List[str]] = None, video_code: Optional[List[str]] = None,
+                  edition: Optional[List[str]] = None, resolution: Optional[List[str]] = None,
+                  release_group: Optional[List[str]] = None, title_pattern: Optional[str] = None,
+                  show_filter_options: bool = False,
+                  **kwargs) -> str:
+        logger.info(
+            f"执行工具: {self.name}, 参数: site={site}, season={season}, free_state={free_state}, video_code={video_code}, edition={edition}, resolution={resolution}, release_group={release_group}, title_pattern={title_pattern}, show_filter_options={show_filter_options}")
+
+        try:
+            items = await SearchChain().async_last_search_results() or []
+            if not items:
+                return "没有可用的搜索结果，请先使用 search_torrents 搜索"
+
+            if show_filter_options:
+                payload = {
+                    "total_count": len(items),
+                    "filter_options": build_filter_options(items),
+                }
+                return json.dumps(payload, ensure_ascii=False, indent=2)
+
+            regex_pattern = None
+            if title_pattern:
+                try:
+                    regex_pattern = re.compile(title_pattern, re.IGNORECASE)
+                except re.error as e:
+                    logger.warning(f"正则表达式编译失败: {title_pattern}, 错误: {e}")
+                    return f"正则表达式格式错误: {str(e)}"
+
+            filtered_items = filter_contexts(
+                items=items,
+                site=site,
+                season=season,
+                free_state=free_state,
+                video_code=video_code,
+                edition=edition,
+                resolution=resolution,
+                release_group=release_group,
+            )
+            if regex_pattern:
+                filtered_items = [
+                    item for item in filtered_items
+                    if item.torrent_info and item.torrent_info.title
+                    and regex_pattern.search(item.torrent_info.title)
+                ]
+            if not filtered_items:
+                return "没有符合筛选条件的搜索结果，请调整筛选条件"
+
+            total_count = len(filtered_items)
+            filtered_ids = {id(item) for item in filtered_items}
+            matched_indices = [index for index, item in enumerate(items, start=1) if id(item) in filtered_ids]
+            limited_items = filtered_items[:TORRENT_RESULT_LIMIT]
+            limited_indices = matched_indices[:TORRENT_RESULT_LIMIT]
+            results = [
+                simplify_search_result(item, index)
+                for item, index in zip(limited_items, limited_indices)
+            ]
+            payload = {
+                "total_count": total_count,
+                "results": results,
+            }
+            if total_count > TORRENT_RESULT_LIMIT:
+                payload["message"] = f"搜索结果共找到 {total_count} 条，仅显示前 {TORRENT_RESULT_LIMIT} 条结果。"
+            return json.dumps(payload, ensure_ascii=False, indent=2)
+        except Exception as e:
+            error_message = f"获取搜索结果失败: {str(e)}"
+            logger.error(f"获取搜索结果失败: {e}", exc_info=True)
+            return error_message

app/agent/tools/impl/list_directory.py

@@ -24,7 +24,7 @@ class ListDirectoryInput(BaseModel):
 
 class ListDirectoryTool(MoviePilotTool):
     name: str = "list_directory"
-    description: str = "List actual files and folders in a file system directory (NOT configuration). Shows files and subdirectories with their names, types, sizes, and modification times. Returns up to 20 items and the total count if there are more items. Use 'query_directories' to query directory configuration settings."
+    description: str = "List actual files and folders in a file system directory (NOT configuration). Shows files and subdirectories with their names, types, sizes, and modification times. Returns up to 20 items and the total count if there are more items. Use 'query_directory_settings' to query directory configuration settings."
     args_schema: Type[BaseModel] = ListDirectoryInput
 
     def get_tool_message(self, **kwargs) -> Optional[str]:

app/agent/tools/impl/modify_download.py

@@ -0,0 +1,123 @@
+"""修改下载任务工具"""
+
+from typing import Optional, Type, List
+
+from pydantic import BaseModel, Field
+
+from app.agent.tools.base import MoviePilotTool
+from app.chain.download import DownloadChain
+from app.log import logger
+
+
+class ModifyDownloadInput(BaseModel):
+    """修改下载任务工具的输入参数模型"""
+
+    explanation: str = Field(
+        ...,
+        description="Clear explanation of why this tool is being used in the current context",
+    )
+    hash: str = Field(
+        ..., description="Task hash (can be obtained from query_download_tasks tool)"
+    )
+    action: Optional[str] = Field(
+        None,
+        description="Action to perform on the task: 'start' to resume downloading, 'stop' to pause downloading. "
+        "If not provided, no start/stop action will be performed.",
+    )
+    tags: Optional[List[str]] = Field(
+        None,
+        description="List of tags to set on the download task. If provided, these tags will be added to the task. "
+        "Example: ['movie', 'hd']",
+    )
+    downloader: Optional[str] = Field(
+        None,
+        description="Name of specific downloader (optional, if not provided will search all downloaders)",
+    )
+
+
+class ModifyDownloadTool(MoviePilotTool):
+    """修改下载任务工具"""
+
+    name: str = "modify_download"
+    description: str = (
+        "Modify a download task in the downloader by task hash. "
+        "Supports: 1) Setting tags on a download task, "
+        "2) Starting (resuming) a paused download task, "
+        "3) Stopping (pausing) a downloading task. "
+        "Multiple operations can be performed in a single call."
+    )
+    args_schema: Type[BaseModel] = ModifyDownloadInput
+
+    def get_tool_message(self, **kwargs) -> Optional[str]:
+        hash_value = kwargs.get("hash", "")
+        action = kwargs.get("action")
+        tags = kwargs.get("tags")
+        downloader = kwargs.get("downloader")
+
+        parts = [f"正在修改下载任务: {hash_value}"]
+        if action == "start":
+            parts.append("操作: 开始下载")
+        elif action == "stop":
+            parts.append("操作: 暂停下载")
+        if tags:
+            parts.append(f"标签: {', '.join(tags)}")
+        if downloader:
+            parts.append(f"下载器: {downloader}")
+        return " | ".join(parts)
+
+    async def run(
+        self,
+        hash: str,
+        action: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        downloader: Optional[str] = None,
+        **kwargs,
+    ) -> str:
+        logger.info(
+            f"执行工具: {self.name}, 参数: hash={hash}, action={action}, tags={tags}, downloader={downloader}"
+        )
+
+        try:
+            # 校验 hash 格式
+            if len(hash) != 40 or not all(c in "0123456789abcdefABCDEF" for c in hash):
+                return "参数错误：hash 格式无效，请先使用 query_download_tasks 工具获取正确的 hash。"
+
+            # 校验参数：至少需要一个操作
+            if not action and not tags:
+                return "参数错误：至少需要指定 action（start/stop）或 tags 中的一个。"
+
+            # 校验 action 参数
+            if action and action not in ("start", "stop"):
+                return f"参数错误：action 只支持 'start'（开始下载）或 'stop'（暂停下载），收到: '{action}'。"
+
+            download_chain = DownloadChain()
+            results = []
+
+            # 设置标签
+            if tags:
+                tag_result = download_chain.set_torrents_tag(
+                    hashs=[hash], tags=tags, downloader=downloader
+                )
+                if tag_result:
+                    results.append(f"成功设置标签：{', '.join(tags)}")
+                else:
+                    results.append(f"设置标签失败，请检查任务是否存在或下载器是否可用")
+
+            # 执行开始/暂停操作
+            if action:
+                action_result = download_chain.set_downloading(
+                    hash_str=hash, oper=action, name=downloader
+                )
+                action_desc = "开始" if action == "start" else "暂停"
+                if action_result:
+                    results.append(f"成功{action_desc}下载任务")
+                else:
+                    results.append(
+                        f"{action_desc}下载任务失败，请检查任务是否存在或下载器是否可用"
+                    )
+
+            return f"下载任务 {hash}：" + "；".join(results)
+
+        except Exception as e:
+            logger.error(f"修改下载任务失败: {e}", exc_info=True)
+            return f"修改下载任务时发生错误: {str(e)}"

app/agent/tools/impl/query_download_tasks.py

@@ -10,7 +10,7 @@ from app.chain.download import DownloadChain
 from app.db.downloadhistory_oper import DownloadHistoryOper
 from app.log import logger
 from app.schemas import TransferTorrent, DownloadingTorrent
-from app.schemas.types import TorrentStatus
+from app.schemas.types import TorrentStatus, media_type_to_agent
 
 
 class QueryDownloadTasksInput(BaseModel):
@@ -22,11 +22,12 @@ class QueryDownloadTasksInput(BaseModel):
                                   description="Filter downloads by status: 'downloading' for active downloads, 'completed' for finished downloads, 'paused' for paused downloads, 'all' for all downloads")
     hash: Optional[str] = Field(None, description="Query specific download task by hash (optional, if provided will search for this specific task regardless of status)")
     title: Optional[str] = Field(None, description="Query download tasks by title/name (optional, supports partial match, searches all tasks if provided)")
+    tag: Optional[str] = Field(None, description="Filter download tasks by tag (optional, supports partial match, e.g. 'movie' will match tasks with tag 'movie' or 'movie_2024')")
 
 
 class QueryDownloadTasksTool(MoviePilotTool):
     name: str = "query_download_tasks"
-    description: str = "Query download status and list download tasks. Can query all active downloads, or search for specific tasks by hash or title. Shows download progress, completion status, and task details from configured downloaders."
+    description: str = "Query download status and list download tasks. Can query all active downloads, or search for specific tasks by hash, title, or tag. Shows download progress, completion status, tags, and task details from configured downloaders."
     args_schema: Type[BaseModel] = QueryDownloadTasksInput
 
     @staticmethod
@@ -51,6 +52,18 @@ class QueryDownloadTasksTool(MoviePilotTool):
         
         return all_torrents
 
+    @staticmethod
+    def _format_progress(progress: Optional[float]) -> Optional[str]:
+        """
+        将下载进度格式化为保留一位小数的百分比字符串
+        """
+        try:
+            if progress is None:
+                return None
+            return f"{float(progress):.1f}%"
+        except (TypeError, ValueError):
+            return None
+
     def get_tool_message(self, **kwargs) -> Optional[str]:
         """根据查询参数生成友好的提示消息"""
         downloader = kwargs.get("downloader")
@@ -71,14 +84,19 @@ class QueryDownloadTasksTool(MoviePilotTool):
             parts.append(f"Hash: {hash_value[:8]}...")
         elif title:
             parts.append(f"标题: {title}")
+
+        tag = kwargs.get("tag")
+        if tag:
+            parts.append(f"标签: {tag}")
         
         return " | ".join(parts) if len(parts) > 1 else parts[0]
 
     async def run(self, downloader: Optional[str] = None,
                   status: Optional[str] = "all",
                   hash: Optional[str] = None,
-                  title: Optional[str] = None, **kwargs) -> str:
-        logger.info(f"执行工具: {self.name}, 参数: downloader={downloader}, status={status}, hash={hash}, title={title}")
+                  title: Optional[str] = None,
+                  tag: Optional[str] = None, **kwargs) -> str:
+        logger.info(f"执行工具: {self.name}, 参数: downloader={downloader}, status={status}, hash={hash}, title={title}, tag={tag}")
         try:
             download_chain = DownloadChain()
             
@@ -93,16 +111,18 @@ class QueryDownloadTasksTool(MoviePilotTool):
                     # 获取下载历史信息
                     history = DownloadHistoryOper().get_by_hash(torrent.hash)
                     if history:
-                        torrent.media = {
-                            "tmdbid": history.tmdbid,
-                            "type": history.type,
-                            "title": history.title,
-                            "season": history.seasons,
-                            "episode": history.episodes,
-                            "image": history.image,
-                        }
+                        if hasattr(torrent, "media"):
+                            torrent.media = {
+                                "tmdbid": history.tmdbid,
+                                "type": history.type,
+                                "title": history.title,
+                                "season": history.seasons,
+                                "episode": history.episodes,
+                                "image": history.image,
+                            }
+                        if hasattr(torrent, "username"):
+                            torrent.username = history.username
                         torrent.userid = history.userid
-                        torrent.username = history.username
                     downloads.append(torrent)
                 filtered_downloads = downloads
             elif title:
@@ -119,7 +139,7 @@ class QueryDownloadTasksTool(MoviePilotTool):
                     matched = False
                     # 检查torrent的title和name字段
                     if (title_lower in (torrent.title or "").lower()) or \
-                       (title_lower in (torrent.name or "").lower()):
+                       (title_lower in (getattr(torrent, "name", None) or "").lower()):
                         matched = True
                     # 检查下载历史中的标题
                     if history and history.title:
@@ -128,16 +148,18 @@ class QueryDownloadTasksTool(MoviePilotTool):
                     
                     if matched:
                         if history:
-                            torrent.media = {
-                                "tmdbid": history.tmdbid,
-                                "type": history.type,
-                                "title": history.title,
-                                "season": history.seasons,
-                                "episode": history.episodes,
-                                "image": history.image,
-                            }
+                            if hasattr(torrent, "media"):
+                                torrent.media = {
+                                    "tmdbid": history.tmdbid,
+                                    "type": history.type,
+                                    "title": history.title,
+                                    "season": history.seasons,
+                                    "episode": history.episodes,
+                                    "image": history.image,
+                                }
+                            if hasattr(torrent, "username"):
+                                torrent.username = history.username
                             torrent.userid = history.userid
-                            torrent.username = history.username
                         filtered_downloads.append(torrent)
                 if not filtered_downloads:
                     return f"未找到标题包含 '{title}' 的下载任务"
@@ -172,17 +194,28 @@ class QueryDownloadTasksTool(MoviePilotTool):
                         # 获取下载历史信息
                         history = DownloadHistoryOper().get_by_hash(torrent.hash)
                         if history:
-                            torrent.media = {
-                                "tmdbid": history.tmdbid,
-                                "type": history.type,
-                                "title": history.title,
-                                "season": history.seasons,
-                                "episode": history.episodes,
-                                "image": history.image,
-                            }
+                            if hasattr(torrent, "media"):
+                                torrent.media = {
+                                    "tmdbid": history.tmdbid,
+                                    "type": history.type,
+                                    "title": history.title,
+                                    "season": history.seasons,
+                                    "episode": history.episodes,
+                                    "image": history.image,
+                                }
+                            if hasattr(torrent, "username"):
+                                torrent.username = history.username
                             torrent.userid = history.userid
-                            torrent.username = history.username
                         filtered_downloads.append(torrent)
+            # 按tag过滤
+            if tag and filtered_downloads:
+                tag_lower = tag.lower()
+                filtered_downloads = [
+                    d for d in filtered_downloads
+                    if d.tags and tag_lower in d.tags.lower()
+                ]
+                if not filtered_downloads:
+                    return f"未找到标签包含 '{tag}' 的下载任务"
             if filtered_downloads:
                 # 限制最多20条结果
                 total_count = len(filtered_downloads)
@@ -194,24 +227,26 @@ class QueryDownloadTasksTool(MoviePilotTool):
                         "downloader": d.downloader,
                         "hash": d.hash,
                         "title": d.title,
-                        "name": d.name,
-                        "year": d.year,
-                        "season_episode": d.season_episode,
+                        "name": getattr(d, "name", None),
+                        "year": getattr(d, "year", None),
+                        "season_episode": getattr(d, "season_episode", None),
                         "size": d.size,
-                        "progress": d.progress,
+                        "progress": self._format_progress(d.progress),
                         "state": d.state,
-                        "upspeed": d.upspeed,
-                        "dlspeed": d.dlspeed,
-                        "left_time": d.left_time
+                        "upspeed": getattr(d, "upspeed", None),
+                        "dlspeed": getattr(d, "dlspeed", None),
+                        "tags": d.tags,
+                        "left_time": getattr(d, "left_time", None)
                     }
                     # 精简 media 字段
-                    if d.media:
+                    media = getattr(d, "media", None)
+                    if media:
                         simplified["media"] = {
-                            "tmdbid": d.media.get("tmdbid"),
-                            "type": d.media.get("type"),
-                            "title": d.media.get("title"),
-                            "season": d.media.get("season"),
-                            "episode": d.media.get("episode")
+                            "tmdbid": media.get("tmdbid"),
+                            "type": media_type_to_agent(media.get("type")),
+                            "title": media.get("title"),
+                            "season": media.get("season"),
+                            "episode": media.get("episode")
                         }
                     simplified_downloads.append(simplified)
                 result_json = json.dumps(simplified_downloads, ensure_ascii=False, indent=2)

app/agent/tools/impl/query_episode_schedule.py

@@ -6,23 +6,21 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
-from app.chain.media import MediaChain
 from app.chain.tmdb import TmdbChain
 from app.log import logger
-from app.schemas import MediaType
 
 
 class QueryEpisodeScheduleInput(BaseModel):
     """查询剧集上映时间工具的输入参数模型"""
     explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
-    tmdb_id: int = Field(..., description="TMDB ID of the TV series")
+    tmdb_id: int = Field(..., description="TMDB ID of the TV series (can be obtained from search_media tool)")
     season: int = Field(..., description="Season number to query")
     episode_group: Optional[str] = Field(None, description="Episode group ID (optional)")
 
 
 class QueryEpisodeScheduleTool(MoviePilotTool):
     name: str = "query_episode_schedule"
-    description: str = "Query TV series episode air dates and schedule. Returns detailed information for each episode including air date, episode number, title, overview, and other metadata. Filters out episodes without air dates."
+    description: str = "Query TV series episode air dates and schedule. Returns non-duplicated schedule fields, including episode list, air-date statistics, and per-episode metadata. Filters out episodes without air dates."
     args_schema: Type[BaseModel] = QueryEpisodeScheduleInput
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
@@ -41,12 +39,6 @@ class QueryEpisodeScheduleTool(MoviePilotTool):
         logger.info(f"执行工具: {self.name}, 参数: tmdb_id={tmdb_id}, season={season}, episode_group={episode_group}")
 
         try:
-            # 获取媒体信息（用于获取标题和海报）
-            media_chain = MediaChain()
-            mediainfo = await media_chain.async_recognize_media(tmdbid=tmdb_id, mtype=MediaType.TV)
-            if not mediainfo:
-                return f"未找到 TMDB ID {tmdb_id} 的媒体信息"
-
             # 获取集列表
             tmdb_chain = TmdbChain()
             episodes = await tmdb_chain.async_tmdb_episodes(
@@ -92,12 +84,7 @@ class QueryEpisodeScheduleTool(MoviePilotTool):
             episode_list.sort(key=lambda x: (x["air_date"] or "", x["episode_number"] or 0))
 
             result = {
-                "success": True,
-                "tmdb_id": tmdb_id,
                 "season": season,
-                "episode_group": episode_group,
-                "series_title": mediainfo.title if mediainfo else None,
-                "series_poster": mediainfo.poster_path if mediainfo else None,
                 "total_episodes": len(episodes),
                 "episodes_with_air_date": len(episode_list),
                 "episodes": episode_list

app/agent/tools/impl/query_installed_plugins.py

@@ -0,0 +1,71 @@
+"""查询已安装插件工具"""
+
+import json
+from typing import Optional, Type
+
+from pydantic import BaseModel, Field
+
+from app.agent.tools.base import MoviePilotTool
+from app.core.plugin import PluginManager
+from app.log import logger
+
+
+class QueryInstalledPluginsInput(BaseModel):
+    """查询已安装插件工具的输入参数模型"""
+
+    explanation: str = Field(
+        ...,
+        description="Clear explanation of why this tool is being used in the current context",
+    )
+
+
+class QueryInstalledPluginsTool(MoviePilotTool):
+    name: str = "query_installed_plugins"
+    description: str = (
+        "Query all installed plugins in MoviePilot. Returns a list of installed plugins with their ID, name, "
+        "description, version, author, running state, and other information. "
+        "Use this tool to discover what plugins are available before querying plugin capabilities or running plugin commands."
+    )
+    args_schema: Type[BaseModel] = QueryInstalledPluginsInput
+
+    def get_tool_message(self, **kwargs) -> Optional[str]:
+        """生成友好的提示消息"""
+        return "正在查询已安装插件"
+
+    async def run(self, **kwargs) -> str:
+        logger.info(f"执行工具: {self.name}")
+        try:
+            plugin_manager = PluginManager()
+            local_plugins = plugin_manager.get_local_plugins()
+            # 仅返回已安装的插件
+            installed_plugins = [plugin for plugin in local_plugins if plugin.installed]
+
+            if not installed_plugins:
+                return "当前没有已安装的插件"
+
+            plugins_list = []
+            for plugin in installed_plugins:
+                plugins_list.append(
+                    {
+                        "id": plugin.id,
+                        "plugin_name": plugin.plugin_name,
+                        "plugin_desc": plugin.plugin_desc,
+                        "plugin_version": plugin.plugin_version,
+                        "plugin_author": plugin.plugin_author,
+                        "state": plugin.state,
+                        "has_page": plugin.has_page,
+                    }
+                )
+
+            total_count = len(plugins_list)
+            result_json = json.dumps(plugins_list, ensure_ascii=False, indent=2)
+
+            if total_count > 50:
+                limited_plugins = plugins_list[:50]
+                limited_json = json.dumps(limited_plugins, ensure_ascii=False, indent=2)
+                return f"注意：共找到 {total_count} 个已安装插件，为节省上下文空间，仅显示前 50 个。\n\n{limited_json}"
+
+            return result_json
+        except Exception as e:
+            logger.error(f"查询已安装插件失败: {e}", exc_info=True)
+            return f"查询已安装插件时发生错误: {str(e)}"

app/agent/tools/impl/query_library_exists.py

@@ -1,139 +1,177 @@
 """查询媒体库工具"""
 
 import json
-from typing import Optional, Type
+from collections import OrderedDict
+from typing import Optional, Type, Any
 
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
 from app.chain.mediaserver import MediaServerChain
-from app.core.context import MediaInfo
-from app.core.meta import MetaBase
+from app.helper.mediaserver import MediaServerHelper
 from app.log import logger
-from app.schemas.types import MediaType
+from app.schemas.types import MediaType, media_type_to_agent
+
+
+def _sort_seasons(seasons: Optional[dict]) -> dict:
+    """按季号、集号升序整理季集信息，保证输出稳定。"""
+    if not seasons:
+        return {}
+
+    def _sort_key(value):
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return str(value)
+
+    return OrderedDict(
+        (season, sorted(episodes, key=_sort_key))
+        for season, episodes in sorted(seasons.items(), key=lambda item: _sort_key(item[0]))
+    )
+
+
+def _filter_regular_seasons(seasons: Optional[dict]) -> OrderedDict:
+    """仅保留正片季，忽略 season 0 等特殊季。"""
+    sorted_seasons = _sort_seasons(seasons)
+    regular_seasons = OrderedDict()
+    for season, episodes in sorted_seasons.items():
+        try:
+            season_number = int(season)
+        except (TypeError, ValueError):
+            continue
+        if season_number > 0:
+            regular_seasons[season_number] = episodes
+    return regular_seasons
+
+
+def _build_tv_server_result(existing_seasons: OrderedDict, total_seasons: OrderedDict) -> dict[str, Any]:
+    """构建单个服务器的电视剧存在性结果。"""
+    seasons_result = OrderedDict()
+    missing_seasons = []
+    all_seasons = sorted(set(total_seasons.keys()) | set(existing_seasons.keys()))
+
+    for season in all_seasons:
+        existing_episodes = existing_seasons.get(season, [])
+        total_episodes = total_seasons.get(season)
+        if total_episodes is not None:
+            missing_episodes = [episode for episode in total_episodes if episode not in existing_episodes]
+            total_episode_count = len(total_episodes)
+        else:
+            missing_episodes = None
+            total_episode_count = None
+        seasons_result[str(season)] = {
+            "existing_episodes": existing_episodes,
+            "total_episodes": total_episode_count,
+            "missing_episodes": missing_episodes
+        }
+        if total_episodes is not None and not existing_episodes:
+            missing_seasons.append(season)
+
+    return {
+        "seasons": seasons_result,
+        "missing_seasons": missing_seasons
+    }
 
 
 class QueryLibraryExistsInput(BaseModel):
     """查询媒体库工具的输入参数模型"""
     explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
-    media_type: Optional[str] = Field("all",
-                                      description="Type of media content: '电影' for films, '电视剧' for television series or anime series, 'all' for all types")
-    title: Optional[str] = Field(None,
-                                 description="Specific media title to check if it exists in the media library (optional, if provided checks for that specific media)")
-    year: Optional[str] = Field(None,
-                                description="Release year of the media (optional, helps narrow down search results)")
+    tmdb_id: Optional[int] = Field(None, description="TMDB ID (can be obtained from search_media tool). Either tmdb_id or douban_id must be provided.")
+    douban_id: Optional[str] = Field(None, description="Douban ID (can be obtained from search_media tool). Either tmdb_id or douban_id must be provided.")
+    media_type: Optional[str] = Field(None, description="Allowed values: movie, tv")
 
 
 class QueryLibraryExistsTool(MoviePilotTool):
     name: str = "query_library_exists"
-    description: str = "Check if a specific media resource already exists in the media library (Plex, Emby, Jellyfin). Use this tool to verify whether a movie or TV series has been successfully processed and added to the media server before performing operations like downloading or subscribing."
+    description: str = "Check whether media already exists in Plex, Emby, or Jellyfin by media ID. Results are grouped by media server; TV results include existing episodes, total episodes, and missing episodes/seasons. Requires tmdb_id or douban_id from search_media."
     args_schema: Type[BaseModel] = QueryLibraryExistsInput
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
         """根据查询参数生成友好的提示消息"""
-        media_type = kwargs.get("media_type", "all")
-        title = kwargs.get("title")
-        year = kwargs.get("year")
-        
-        parts = ["正在查询媒体库"]
-        
-        if title:
-            parts.append(f"标题: {title}")
-        if year:
-            parts.append(f"年份: {year}")
-        if media_type != "all":
-            parts.append(f"类型: {media_type}")
-        
-        return " | ".join(parts) if len(parts) > 1 else parts[0]
+        tmdb_id = kwargs.get("tmdb_id")
+        douban_id = kwargs.get("douban_id")
+        media_type = kwargs.get("media_type")
 
-    async def run(self, media_type: Optional[str] = "all",
-                  title: Optional[str] = None, year: Optional[str] = None, **kwargs) -> str:
-        logger.info(f"执行工具: {self.name}, 参数: media_type={media_type}, title={title}")
+        if tmdb_id:
+            message = f"正在查询媒体库: TMDB={tmdb_id}"
+        elif douban_id:
+            message = f"正在查询媒体库: 豆瓣={douban_id}"
+        else:
+            message = "正在查询媒体库"
+        if media_type:
+            message += f" [{media_type}]"
+        return message
+
+    async def run(self, tmdb_id: Optional[int] = None, douban_id: Optional[str] = None,
+                  media_type: Optional[str] = None, **kwargs) -> str:
+        logger.info(f"执行工具: {self.name}, 参数: tmdb_id={tmdb_id}, douban_id={douban_id}, media_type={media_type}")
         try:
-            if not title:
-                return "请提供媒体标题进行查询"
+            if not tmdb_id and not douban_id:
+                return "参数错误：tmdb_id 和 douban_id 至少需要提供一个，请先使用 search_media 工具获取媒体 ID。"
+
+            media_type_enum = None
+            if media_type:
+                media_type_enum = MediaType.from_agent(media_type)
+                if not media_type_enum:
+                    return f"错误：无效的媒体类型 '{media_type}'，支持的类型：'movie', 'tv'"
 
             media_chain = MediaServerChain()
+            mediainfo = media_chain.recognize_media(
+                tmdbid=tmdb_id,
+                doubanid=douban_id,
+                mtype=media_type_enum,
+            )
+            if not mediainfo:
+                media_id = f"TMDB={tmdb_id}" if tmdb_id else f"豆瓣={douban_id}"
+                return f"未识别到媒体信息: {media_id}"
 
-            # 1. 识别媒体信息（获取 TMDB ID 和各季的总集数等元数据）
-            meta = MetaBase(title=title)
-            if year:
-                meta.year = str(year)
-            if media_type == "电影":
-                meta.type = MediaType.MOVIE
-            elif media_type == "电视剧":
-                meta.type = MediaType.TV
+            # 2. 遍历所有媒体服务器，分别查询存在性信息
+            server_results = OrderedDict()
+            media_server_helper = MediaServerHelper()
+            total_seasons = _filter_regular_seasons(mediainfo.seasons)
+            global_existsinfo = media_chain.media_exists(mediainfo=mediainfo)
 
-            # 使用识别方法补充信息
-            recognize_info = media_chain.recognize_media(meta=meta)
-            if recognize_info:
-                mediainfo = recognize_info
-            else:
-                # 识别失败，创建基本信息的 MediaInfo
-                mediainfo = MediaInfo()
-                mediainfo.title = title
-                mediainfo.year = year
-                if media_type == "电影":
-                    mediainfo.type = MediaType.MOVIE
-                elif media_type == "电视剧":
-                    mediainfo.type = MediaType.TV
+            for service_name in sorted(media_server_helper.get_services().keys()):
+                existsinfo = media_chain.media_exists(mediainfo=mediainfo, server=service_name)
+                if not existsinfo:
+                    continue
 
-            # 2. 调用媒体服务器接口实时查询存在信息
-            existsinfo = media_chain.media_exists(mediainfo=mediainfo)
+                if existsinfo.type == MediaType.TV:
+                    existing_seasons = _filter_regular_seasons(existsinfo.seasons)
+                    server_results[service_name] = _build_tv_server_result(
+                        existing_seasons=existing_seasons,
+                        total_seasons=total_seasons
+                    )
+                else:
+                    server_results[service_name] = {
+                        "exists": True
+                    }
 
-            if not existsinfo:
+            if global_existsinfo:
+                fallback_server_name = global_existsinfo.server or "local"
+                if fallback_server_name not in server_results:
+                    if global_existsinfo.type == MediaType.TV:
+                        server_results[fallback_server_name] = _build_tv_server_result(
+                            existing_seasons=_filter_regular_seasons(global_existsinfo.seasons),
+                            total_seasons=total_seasons
+                        )
+                    else:
+                        server_results[fallback_server_name] = {
+                            "exists": True
+                        }
+
+            if not server_results:
                 return "媒体库中未找到相关媒体"
 
-            # 3. 如果找到了，获取详细信息并组装结果
-            result_items = []
-            if existsinfo.itemid and existsinfo.server:
-                iteminfo = media_chain.iteminfo(server=existsinfo.server, item_id=existsinfo.itemid)
-                if iteminfo:
-                    # 使用 model_dump() 转换为字典格式
-                    item_dict = iteminfo.model_dump(exclude_none=True)
-
-                    # 对于电视剧，补充已存在的季集详情及进度统计
-                    if existsinfo.type == MediaType.TV:
-                        # 注入已存在集信息 (Dict[int, list])
-                        item_dict["seasoninfo"] = existsinfo.seasons
-
-                        # 统计库中已存在的季集总数
-                        if existsinfo.seasons:
-                            item_dict["existing_episodes_count"] = sum(len(e) for e in existsinfo.seasons.values())
-                            item_dict["seasons_existing_count"] = {str(s): len(e) for s, e in existsinfo.seasons.items()}
-
-                            # 如果识别到了元数据，补充总计对比和进度概览
-                            if mediainfo.seasons:
-                                item_dict["seasons_total_count"] = {str(s): len(e) for s, e in mediainfo.seasons.items()}
-                                # 进度概览，例如 "Season 1": "3/12"
-                                item_dict["seasons_progress"] = {
-                                    f"第{s}季": f"{len(existsinfo.seasons.get(s, []))}/{len(mediainfo.seasons.get(s, []))} 集"
-                                    for s in mediainfo.seasons.keys() if (s in existsinfo.seasons or s > 0)
-                                }
-
-                    result_items.append(item_dict)
-
-            if result_items:
-                return json.dumps(result_items, ensure_ascii=False)
-
-            # 如果找到了但没有获取到 iteminfo，返回基本信息
+            # 3. 组装统一的存在性结果，不查询媒体服务器详情
             result_dict = {
                 "title": mediainfo.title,
                 "year": mediainfo.year,
-                "type": existsinfo.type.value if existsinfo.type else None,
-                "server": existsinfo.server,
-                "server_type": existsinfo.server_type,
-                "itemid": existsinfo.itemid,
-                "seasons": existsinfo.seasons if existsinfo.seasons else {}
+                "type": media_type_to_agent(mediainfo.type),
+                "servers": server_results
             }
-            if existsinfo.type == MediaType.TV and existsinfo.seasons:
-                result_dict["existing_episodes_count"] = sum(len(e) for e in existsinfo.seasons.values())
-                result_dict["seasons_existing_count"] = {str(s): len(e) for s, e in existsinfo.seasons.items()}
-                if mediainfo.seasons:
-                    result_dict["seasons_total_count"] = {str(s): len(e) for s, e in mediainfo.seasons.items()}
 
             return json.dumps([result_dict], ensure_ascii=False)
         except Exception as e:
             logger.error(f"查询媒体库失败: {e}", exc_info=True)
             return f"查询媒体库时发生错误: {str(e)}"
-

app/agent/tools/impl/query_media_detail.py

@@ -8,45 +8,56 @@ from pydantic import BaseModel, Field
 from app.agent.tools.base import MoviePilotTool
 from app.chain.media import MediaChain
 from app.log import logger
-from app.schemas import MediaType
+from app.schemas.types import MediaType
 
 
 class QueryMediaDetailInput(BaseModel):
     """查询媒体详情工具的输入参数模型"""
     explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
-    tmdb_id: int = Field(..., description="TMDB ID of the media (movie or TV series)")
-    media_type: str = Field(..., description="Media type: 'movie' or 'tv'")
+    tmdb_id: Optional[int] = Field(None, description="TMDB ID of the media (movie or TV series, can be obtained from search_media tool)")
+    douban_id: Optional[str] = Field(None, description="Douban ID of the media (alternative to tmdb_id)")
+    media_type: str = Field(..., description="Allowed values: movie, tv")
 
 
 class QueryMediaDetailTool(MoviePilotTool):
     name: str = "query_media_detail"
-    description: str = "Query detailed media information from TMDB by ID and media_type. IMPORTANT: Convert search results type: '电影'→'movie', '电视剧'→'tv'. Returns core metadata including title, year, overview, status, genres, directors, actors, and season count for TV series."
+    description: str = "Query supplementary media details from TMDB by ID and media_type. Accepts tmdb_id or douban_id (at least one required). media_type accepts 'movie' or 'tv'. Returns non-duplicated detail fields such as status, genres, directors, actors, and season info for TV series."
     args_schema: Type[BaseModel] = QueryMediaDetailInput
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
         """根据查询参数生成友好的提示消息"""
         tmdb_id = kwargs.get("tmdb_id")
-        return f"正在查询媒体详情: TMDB ID {tmdb_id}"
+        douban_id = kwargs.get("douban_id")
+        if tmdb_id:
+            return f"正在查询媒体详情: TMDB ID {tmdb_id}"
+        return f"正在查询媒体详情: 豆瓣 ID {douban_id}"
 
-    async def run(self, tmdb_id: int, media_type: str, **kwargs) -> str:
-        logger.info(f"执行工具: {self.name}, 参数: tmdb_id={tmdb_id}, media_type={media_type}")
+    async def run(self, media_type: str, tmdb_id: Optional[int] = None, douban_id: Optional[str] = None, **kwargs) -> str:
+        logger.info(f"执行工具: {self.name}, 参数: tmdb_id={tmdb_id}, douban_id={douban_id}, media_type={media_type}")
+
+        if tmdb_id is None and douban_id is None:
+            return json.dumps({
+                "success": False,
+                "message": "必须提供 tmdb_id 或 douban_id 之一"
+            }, ensure_ascii=False)
 
         try:
             media_chain = MediaChain()
 
-            mtype = None
-            if media_type:
-                if media_type.lower() == 'movie':
-                    mtype = MediaType.MOVIE
-                elif media_type.lower() == 'tv':
-                    mtype = MediaType.TV
-
-            mediainfo = await media_chain.async_recognize_media(tmdbid=tmdb_id, mtype=mtype)
-            
-            if not mediainfo:
+            media_type_enum = MediaType.from_agent(media_type)
+            if not media_type_enum:
                 return json.dumps({
                     "success": False,
-                    "message": f"未找到 TMDB ID {tmdb_id} 的媒体信息"
+                    "message": f"无效的媒体类型 '{media_type}'，支持的类型：'movie', 'tv'"
+                }, ensure_ascii=False)
+
+            mediainfo = await media_chain.async_recognize_media(tmdbid=tmdb_id, doubanid=douban_id, mtype=media_type_enum)
+
+            if not mediainfo:
+                id_info = f"TMDB ID {tmdb_id}" if tmdb_id else f"豆瓣 ID {douban_id}"
+                return json.dumps({
+                    "success": False,
+                    "message": f"未找到 {id_info} 的媒体信息"
                 }, ensure_ascii=False)
 
             # 精简 genres - 只保留名称
@@ -74,12 +85,6 @@ class QueryMediaDetailTool(MoviePilotTool):
 
             # 构建基础媒体详情信息
             result = {
-                "success": True,
-                "tmdb_id": tmdb_id,
-                "type": mediainfo.type.value if mediainfo.type else None,
-                "title": mediainfo.title,
-                "year": mediainfo.year,
-                "overview": mediainfo.overview,
                 "status": mediainfo.status,
                 "genres": genres,
                 "directors": directors,
@@ -116,5 +121,6 @@ class QueryMediaDetailTool(MoviePilotTool):
             return json.dumps({
                 "success": False,
                 "message": error_message,
-                "tmdb_id": tmdb_id
+                "tmdb_id": tmdb_id,
+                "douban_id": douban_id
             }, ensure_ascii=False)

app/agent/tools/impl/query_plugin_capabilities.py

@@ -0,0 +1,117 @@
+"""查询插件能力工具"""
+
+import json
+from typing import Optional, Type
+
+from pydantic import BaseModel, Field
+
+from app.agent.tools.base import MoviePilotTool
+from app.core.plugin import PluginManager
+from app.log import logger
+
+
+class QueryPluginCapabilitiesInput(BaseModel):
+    """查询插件能力工具的输入参数模型"""
+
+    explanation: str = Field(
+        ...,
+        description="Clear explanation of why this tool is being used in the current context",
+    )
+    plugin_id: Optional[str] = Field(
+        None,
+        description="Optional plugin ID to query capabilities for a specific plugin. "
+        "If not provided, returns capabilities of all running plugins. "
+        "Use query_installed_plugins tool to get the plugin IDs first.",
+    )
+
+
+class QueryPluginCapabilitiesTool(MoviePilotTool):
+    name: str = "query_plugin_capabilities"
+    description: str = (
+        "Query the capabilities of installed plugins, including supported commands and scheduled services. "
+        "Commands are slash-commands (e.g. /xxx) that can be executed via the run_plugin_command tool. "
+        "Scheduled services are periodic tasks that can be triggered via the run_scheduler tool. "
+        "Optionally specify a plugin_id to query a specific plugin, or omit to query all running plugins."
+    )
+    args_schema: Type[BaseModel] = QueryPluginCapabilitiesInput
+
+    def get_tool_message(self, **kwargs) -> Optional[str]:
+        """生成友好的提示消息"""
+        plugin_id = kwargs.get("plugin_id")
+        if plugin_id:
+            return f"正在查询插件 {plugin_id} 的能力"
+        return "正在查询所有插件的能力"
+
+    async def run(self, plugin_id: Optional[str] = None, **kwargs) -> str:
+        logger.info(f"执行工具: {self.name}, 参数: plugin_id={plugin_id}")
+        try:
+            plugin_manager = PluginManager()
+            result = {}
+
+            # 获取插件命令
+            commands = plugin_manager.get_plugin_commands(pid=plugin_id)
+            if commands:
+                commands_list = []
+                for cmd in commands:
+                    cmd_info = {
+                        "cmd": cmd.get("cmd"),
+                        "desc": cmd.get("desc"),
+                        "plugin_id": cmd.get("pid"),
+                    }
+                    # data 字段可能包含额外参数信息
+                    if cmd.get("data"):
+                        cmd_info["data"] = cmd.get("data")
+                    commands_list.append(cmd_info)
+                result["commands"] = commands_list
+
+            # 获取插件动作
+            actions = plugin_manager.get_plugin_actions(pid=plugin_id)
+            if actions:
+                actions_list = []
+                for action_group in actions:
+                    plugin_actions = {
+                        "plugin_id": action_group.get("plugin_id"),
+                        "plugin_name": action_group.get("plugin_name"),
+                        "actions": [],
+                    }
+                    for action in action_group.get("actions", []):
+                        plugin_actions["actions"].append(
+                            {
+                                "id": action.get("id"),
+                                "name": action.get("name"),
+                            }
+                        )
+                    actions_list.append(plugin_actions)
+                result["actions"] = actions_list
+
+            # 获取插件定时服务
+            services = plugin_manager.get_plugin_services(pid=plugin_id)
+            if services:
+                services_list = []
+                for svc in services:
+                    svc_info = {
+                        "id": svc.get("id"),
+                        "name": svc.get("name"),
+                    }
+                    # 包含触发器信息
+                    trigger = svc.get("trigger")
+                    if trigger:
+                        svc_info["trigger"] = str(trigger)
+                    # 包含定时器参数
+                    svc_kwargs = svc.get("kwargs")
+                    if svc_kwargs:
+                        svc_info["trigger_kwargs"] = {
+                            k: str(v) for k, v in svc_kwargs.items()
+                        }
+                    services_list.append(svc_info)
+                result["services"] = services_list
+
+            if not result:
+                if plugin_id:
+                    return f"插件 {plugin_id} 没有注册任何命令、动作或定时服务"
+                return "当前没有运行中的插件注册了命令、动作或定时服务"
+
+            return json.dumps(result, ensure_ascii=False, indent=2)
+        except Exception as e:
+            logger.error(f"查询插件能力失败: {e}", exc_info=True)
+            return f"查询插件能力时发生错误: {str(e)}"

app/agent/tools/impl/query_popular_subscribes.py

@@ -10,13 +10,13 @@ from app.agent.tools.base import MoviePilotTool
 from app.core.context import MediaInfo
 from app.helper.subscribe import SubscribeHelper
 from app.log import logger
-from app.schemas.types import MediaType
+from app.schemas.types import MediaType, media_type_to_agent
 
 
 class QueryPopularSubscribesInput(BaseModel):
     """查询热门订阅工具的输入参数模型"""
     explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
-    stype: str = Field(..., description="Media type: '电影' for films, '电视剧' for television series")
+    media_type: str = Field(..., description="Allowed values: movie, tv")
     page: Optional[int] = Field(1, description="Page number for pagination (default: 1)")
     count: Optional[int] = Field(30, description="Number of items per page (default: 30)")
     min_sub: Optional[int] = Field(None, description="Minimum number of subscribers filter (optional, e.g., 5)")
@@ -33,13 +33,13 @@ class QueryPopularSubscribesTool(MoviePilotTool):
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
         """根据查询参数生成友好的提示消息"""
-        stype = kwargs.get("stype", "")
+        media_type = kwargs.get("media_type", "")
         page = kwargs.get("page", 1)
         min_sub = kwargs.get("min_sub")
         min_rating = kwargs.get("min_rating")
         max_rating = kwargs.get("max_rating")
         
-        parts = [f"正在查询热门订阅 [{stype}]"]
+        parts = [f"正在查询热门订阅 [{media_type}]"]
         
         if min_sub:
             parts.append(f"最少订阅: {min_sub}")
@@ -52,7 +52,7 @@ class QueryPopularSubscribesTool(MoviePilotTool):
         
         return " | ".join(parts) if len(parts) > 1 else parts[0]
 
-    async def run(self, stype: str,
+    async def run(self, media_type: str,
                   page: Optional[int] = 1,
                   count: Optional[int] = 30,
                   min_sub: Optional[int] = None,
@@ -61,7 +61,7 @@ class QueryPopularSubscribesTool(MoviePilotTool):
                   max_rating: Optional[float] = None,
                   sort_type: Optional[str] = None, **kwargs) -> str:
         logger.info(
-            f"执行工具: {self.name}, 参数: stype={stype}, page={page}, count={count}, min_sub={min_sub}, "
+            f"执行工具: {self.name}, 参数: media_type={media_type}, page={page}, count={count}, min_sub={min_sub}, "
             f"genre_id={genre_id}, min_rating={min_rating}, max_rating={max_rating}, sort_type={sort_type}")
 
         try:
@@ -69,10 +69,13 @@ class QueryPopularSubscribesTool(MoviePilotTool):
                 page = 1
             if count is None or count < 1:
                 count = 30
+            media_type_enum = MediaType.from_agent(media_type)
+            if not media_type_enum:
+                return f"错误：无效的媒体类型 '{media_type}'，支持的类型：'movie', 'tv'"
 
             subscribe_helper = SubscribeHelper()
             subscribes = await subscribe_helper.async_get_statistic(
-                stype=stype,
+                stype=media_type_enum.to_agent(),
                 page=page,
                 count=count,
                 genre_id=genre_id,
@@ -94,7 +97,15 @@ class QueryPopularSubscribesTool(MoviePilotTool):
                     continue
 
                 media = MediaInfo()
-                media.type = MediaType(sub.get("type"))
+                raw_type = str(sub.get("type") or "").strip().lower()
+                if raw_type in ["movie", "电影"]:
+                    media.type = MediaType.MOVIE
+                elif raw_type in ["tv", "电视剧"]:
+                    media.type = MediaType.TV
+                else:
+                    # 跳过无法识别类型的数据，避免单条脏数据导致整批失败
+                    logger.warning(f"跳过未知媒体类型: {sub.get('type')}")
+                    continue
                 media.tmdb_id = sub.get("tmdbid")
                 # 处理标题
                 title = sub.get("name")
@@ -124,7 +135,7 @@ class QueryPopularSubscribesTool(MoviePilotTool):
             for media in ret_medias:
                 media_dict = media.to_dict()
                 simplified = {
-                    "type": media_dict.get("type"),
+                    "type": media_type_to_agent(media_dict.get("type")),
                     "title": media_dict.get("title"),
                     "year": media_dict.get("year"),
                     "tmdb_id": media_dict.get("tmdb_id"),

app/agent/tools/impl/query_site_userdata.py

@@ -15,7 +15,7 @@ from app.log import logger
 class QuerySiteUserdataInput(BaseModel):
     """查询站点用户数据工具的输入参数模型"""
     explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
-    site_id: int = Field(..., description="The ID of the site to query user data for")
+    site_id: int = Field(..., description="The ID of the site to query user data for (can be obtained from query_sites tool)")
     workdate: Optional[str] = Field(None, description="Work date to query (optional, format: 'YYYY-MM-DD', if not specified returns latest data)")
 
 

app/agent/tools/impl/query_sites.py

@@ -12,11 +12,18 @@ from app.log import logger
 
 class QuerySitesInput(BaseModel):
     """查询站点工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
-    status: Optional[str] = Field("all",
-                                  description="Filter sites by status: 'active' for enabled sites, 'inactive' for disabled sites, 'all' for all sites")
-    name: Optional[str] = Field(None,
-                                description="Filter sites by name (partial match, optional)")
+
+    explanation: str = Field(
+        ...,
+        description="Clear explanation of why this tool is being used in the current context",
+    )
+    status: Optional[str] = Field(
+        "all",
+        description="Filter sites by status: 'active' for enabled sites, 'inactive' for disabled sites, 'all' for all sites",
+    )
+    name: Optional[str] = Field(
+        None, description="Filter sites by name (partial match, optional)"
+    )
 
 
 class QuerySitesTool(MoviePilotTool):
@@ -28,19 +35,21 @@ class QuerySitesTool(MoviePilotTool):
         """根据查询参数生成友好的提示消息"""
         status = kwargs.get("status", "all")
         name = kwargs.get("name")
-        
+
         parts = ["正在查询站点"]
-        
+
         if status != "all":
             status_map = {"active": "已启用", "inactive": "已禁用"}
             parts.append(f"状态: {status_map.get(status, status)}")
-        
+
         if name:
             parts.append(f"名称: {name}")
-        
+
         return " | ".join(parts) if len(parts) > 1 else parts[0]
 
-    async def run(self, status: Optional[str] = "all", name: Optional[str] = None, **kwargs) -> str:
+    async def run(
+        self, status: Optional[str] = "all", name: Optional[str] = None, **kwargs
+    ) -> str:
         logger.info(f"执行工具: {self.name}, 参数: status={status}, name={name}")
         try:
             site_oper = SiteOper()
@@ -68,9 +77,10 @@ class QuerySitesTool(MoviePilotTool):
                         "url": s.url,
                         "pri": s.pri,
                         "is_active": s.is_active,
+                        "cookie": s.cookie,
                         "downloader": s.downloader,
                         "proxy": s.proxy,
-                        "timeout": s.timeout
+                        "timeout": s.timeout,
                     }
                     simplified_sites.append(simplified)
                 result_json = json.dumps(simplified_sites, ensure_ascii=False, indent=2)
@@ -79,4 +89,3 @@ class QuerySitesTool(MoviePilotTool):
         except Exception as e:
             logger.error(f"查询站点失败: {e}", exc_info=True)
             return f"查询站点时发生错误: {str(e)}"
-

app/agent/tools/impl/query_subscribe_history.py

@@ -9,12 +9,13 @@ from app.agent.tools.base import MoviePilotTool
 from app.db import AsyncSessionFactory
 from app.db.models.subscribehistory import SubscribeHistory
 from app.log import logger
+from app.schemas.types import media_type_to_agent
 
 
 class QuerySubscribeHistoryInput(BaseModel):
     """查询订阅历史工具的输入参数模型"""
     explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
-    media_type: Optional[str] = Field("all", description="Filter by media type: '电影' for films, '电视剧' for television series, 'all' for all types (default: 'all')")
+    media_type: Optional[str] = Field("all", description="Allowed values: movie, tv, all")
     name: Optional[str] = Field(None, description="Filter by media name (partial match, optional)")
 
 
@@ -42,6 +43,9 @@ class QuerySubscribeHistoryTool(MoviePilotTool):
         logger.info(f"执行工具: {self.name}, 参数: media_type={media_type}, name={name}")
 
         try:
+            if media_type not in ["all", "movie", "tv"]:
+                return f"错误：无效的媒体类型 '{media_type}'，支持的类型：'movie', 'tv', 'all'"
+
             # 获取数据库会话
             async with AsyncSessionFactory() as db:
                 # 根据类型查询
@@ -80,7 +84,7 @@ class QuerySubscribeHistoryTool(MoviePilotTool):
                         "id": record.id,
                         "name": record.name,
                         "year": record.year,
-                        "type": record.type,
+                        "type": media_type_to_agent(record.type),
                         "season": record.season,
                         "tmdbid": record.tmdbid,
                         "doubanid": record.doubanid,

app/agent/tools/impl/query_subscribes.py

@@ -8,6 +8,35 @@ from pydantic import BaseModel, Field
 from app.agent.tools.base import MoviePilotTool
 from app.db.subscribe_oper import SubscribeOper
 from app.log import logger
+from app.schemas.subscribe import Subscribe as SubscribeSchema
+from app.schemas.types import MediaType
+
+QUERY_SUBSCRIBE_OUTPUT_FIELDS = [
+    "id",
+    "name",
+    "year",
+    "type",
+    "season",
+    "total_episode",
+    "start_episode",
+    "lack_episode",
+    "filter",
+    "include",
+    "exclude",
+    "quality",
+    "resolution",
+    "effect",
+    "state",
+    "last_update",
+    "sites",
+    "downloader",
+    "best_version",
+    "save_path",
+    "custom_words",
+    "media_category",
+    "filter_groups",
+    "episode_group"
+]
 
 
 class QuerySubscribesInput(BaseModel):
@@ -16,12 +45,14 @@ class QuerySubscribesInput(BaseModel):
     status: Optional[str] = Field("all",
                                   description="Filter subscriptions by status: 'R' for enabled subscriptions, 'S' for paused ones, 'all' for all subscriptions")
     media_type: Optional[str] = Field("all",
-                                      description="Filter by media type: '电影' for films, '电视剧' for television series, 'all' for all types")
+                                      description="Allowed values: movie, tv, all")
+    tmdb_id: Optional[int] = Field(None, description="Filter by TMDB ID to check if a specific media is already subscribed")
+    douban_id: Optional[str] = Field(None, description="Filter by Douban ID to check if a specific media is already subscribed")
 
 
 class QuerySubscribesTool(MoviePilotTool):
     name: str = "query_subscribes"
-    description: str = "Query subscription status and list all user subscriptions. Shows active subscriptions, their download status, and configuration details."
+    description: str = "Query subscription status and list user subscriptions. Returns full subscription parameters for each matched subscription."
     args_schema: Type[BaseModel] = QuerySubscribesInput
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
@@ -42,44 +73,38 @@ class QuerySubscribesTool(MoviePilotTool):
         
         return " | ".join(parts) if len(parts) > 1 else parts[0]
 
-    async def run(self, status: Optional[str] = "all", media_type: Optional[str] = "all", **kwargs) -> str:
-        logger.info(f"执行工具: {self.name}, 参数: status={status}, media_type={media_type}")
+    async def run(self, status: Optional[str] = "all", media_type: Optional[str] = "all",
+                  tmdb_id: Optional[int] = None, douban_id: Optional[str] = None, **kwargs) -> str:
+        logger.info(f"执行工具: {self.name}, 参数: status={status}, media_type={media_type}, tmdb_id={tmdb_id}, douban_id={douban_id}")
         try:
+            if media_type != "all" and not MediaType.from_agent(media_type):
+                return f"错误：无效的媒体类型 '{media_type}'，支持的类型：'movie', 'tv', 'all'"
+
             subscribe_oper = SubscribeOper()
             subscribes = await subscribe_oper.async_list()
             filtered_subscribes = []
             for sub in subscribes:
                 if status != "all" and sub.state != status:
                     continue
-                if media_type != "all" and sub.type != media_type:
+                if media_type != "all" and sub.type != MediaType.from_agent(media_type).value:
+                    continue
+                if tmdb_id is not None and sub.tmdbid != tmdb_id:
+                    continue
+                if douban_id is not None and sub.doubanid != douban_id:
                     continue
                 filtered_subscribes.append(sub)
             if filtered_subscribes:
                 # 限制最多50条结果
                 total_count = len(filtered_subscribes)
                 limited_subscribes = filtered_subscribes[:50]
-                # 精简字段，只保留关键信息
-                simplified_subscribes = []
-                for s in limited_subscribes:
-                    simplified = {
-                        "id": s.id,
-                        "name": s.name,
-                        "year": s.year,
-                        "type": s.type,
-                        "season": s.season,
-                        "tmdbid": s.tmdbid,
-                        "doubanid": s.doubanid,
-                        "bangumiid": s.bangumiid,
-                        "poster": s.poster,
-                        "vote": s.vote,
-                        "state": s.state,
-                        "total_episode": s.total_episode,
-                        "lack_episode": s.lack_episode,
-                        "last_update": s.last_update,
-                        "username": s.username
-                    }
-                    simplified_subscribes.append(simplified)
-                result_json = json.dumps(simplified_subscribes, ensure_ascii=False, indent=2)
+                full_subscribes = [
+                    SubscribeSchema.model_validate(s, from_attributes=True).model_dump(
+                        include=set(QUERY_SUBSCRIBE_OUTPUT_FIELDS),
+                        exclude_none=True
+                    )
+                    for s in limited_subscribes
+                ]
+                result_json = json.dumps(full_subscribes, ensure_ascii=False, indent=2)
                 # 如果结果被裁剪，添加提示信息
                 if total_count > 50:
                     return f"注意：查询结果共找到 {total_count} 条，为节省上下文空间，仅显示前 50 条结果。\n\n{result_json}"

app/agent/tools/impl/query_transfer_history.py

@@ -10,6 +10,7 @@ from app.agent.tools.base import MoviePilotTool
 from app.db import AsyncSessionFactory
 from app.db.models.transferhistory import TransferHistory
 from app.log import logger
+from app.schemas.types import media_type_to_agent
 
 
 class QueryTransferHistoryInput(BaseModel):
@@ -95,7 +96,7 @@ class QueryTransferHistoryTool(MoviePilotTool):
                         "id": record.id,
                         "title": record.title,
                         "year": record.year,
-                        "type": record.type,
+                        "type": media_type_to_agent(record.type),
                         "category": record.category,
                         "seasons": record.seasons,
                         "episodes": record.episodes,

app/agent/tools/impl/read_file.py

@@ -0,0 +1,81 @@
+"""文件读取工具"""
+
+from pathlib import Path
+from typing import Optional, Type
+
+from anyio import Path as AsyncPath
+from pydantic import BaseModel, Field
+
+from app.agent.tools.base import MoviePilotTool
+from app.log import logger
+
+# 最大读取大小 50KB
+MAX_READ_SIZE = 50 * 1024
+
+
+class ReadFileInput(BaseModel):
+    """Input parameters for read file tool"""
+    file_path: str = Field(..., description="The absolute path of the file to read")
+    start_line: Optional[int] = Field(None, description="The starting line number (1-based, inclusive). If not provided, reading starts from the beginning of the file.")
+    end_line: Optional[int] = Field(None, description="The ending line number (1-based, inclusive). If not provided, reading goes until the end of the file.")
+
+
+class ReadFileTool(MoviePilotTool):
+    name: str = "read_file"
+    description: str = "Read the content of a text file. Supports reading by line range. Each read is limited to 50KB; content exceeding this limit will be truncated."
+    args_schema: Type[BaseModel] = ReadFileInput
+
+    def get_tool_message(self, **kwargs) -> Optional[str]:
+        """根据参数生成友好的提示消息"""
+        file_path = kwargs.get("file_path", "")
+        file_name = Path(file_path).name if file_path else "未知文件"
+        return f"正在读取文件: {file_name}"
+
+    async def run(self, file_path: str, start_line: Optional[int] = None,
+                  end_line: Optional[int] = None, **kwargs) -> str:
+        logger.info(f"执行工具: {self.name}, 参数: file_path={file_path}, start_line={start_line}, end_line={end_line}")
+
+        try:
+            path = AsyncPath(file_path)
+
+            if not await path.exists():
+                return f"错误：文件 {file_path} 不存在"
+
+            if not await path.is_file():
+                return f"错误：{file_path} 不是一个文件"
+
+            content = await path.read_text(encoding="utf-8")
+            truncated = False
+
+            if start_line is not None or end_line is not None:
+                lines = content.splitlines(keepends=True)
+                total_lines = len(lines)
+
+                # 将行号转换为索引（1-based -> 0-based）
+                s = (start_line - 1) if start_line and start_line >= 1 else 0
+                e = end_line if end_line and end_line >= 1 else total_lines
+
+                # 确保范围有效
+                s = max(0, min(s, total_lines))
+                e = max(s, min(e, total_lines))
+
+                content = "".join(lines[s:e])
+
+            # 检查大小限制
+            content_bytes = content.encode("utf-8")
+            if len(content_bytes) > MAX_READ_SIZE:
+                content = content_bytes[:MAX_READ_SIZE].decode("utf-8", errors="ignore")
+                truncated = True
+
+            if truncated:
+                return f"{content}\n\n[警告：文件内容已超过50KB限制，以上内容已被截断。请使用 start_line/end_line 参数分段读取。]"
+
+            return content
+
+        except PermissionError:
+            return f"错误：没有权限读取 {file_path}"
+        except UnicodeDecodeError:
+            return f"错误：{file_path} 不是文本文件，无法读取"
+        except Exception as e:
+            logger.error(f"读取文件 {file_path} 时发生错误: {str(e)}", exc_info=True)
+            return f"操作失败: {str(e)}"

app/agent/tools/impl/recognize_media.py

@@ -10,6 +10,7 @@ from app.chain.media import MediaChain
 from app.core.context import Context
 from app.core.metainfo import MetaInfo
 from app.log import logger
+from app.schemas.types import media_type_to_agent
 
 
 class RecognizeMediaInput(BaseModel):
@@ -124,7 +125,7 @@ class RecognizeMediaTool(MoviePilotTool):
                 "title": media_info.get("title"),
                 "en_title": media_info.get("en_title"),
                 "year": media_info.get("year"),
-                "type": media_info.get("type"),
+                "type": media_type_to_agent(media_info.get("type")),
                 "season": media_info.get("season"),
                 "tmdb_id": media_info.get("tmdb_id"),
                 "imdb_id": media_info.get("imdb_id"),
@@ -145,7 +146,7 @@ class RecognizeMediaTool(MoviePilotTool):
                 "name": meta_info.get("name"),
                 "title": meta_info.get("title"),
                 "year": meta_info.get("year"),
-                "type": meta_info.get("type"),
+                "type": media_type_to_agent(meta_info.get("type")),
                 "begin_season": meta_info.get("begin_season"),
                 "end_season": meta_info.get("end_season"),
                 "begin_episode": meta_info.get("begin_episode"),

app/agent/tools/impl/run_plugin_command.py

@@ -0,0 +1,111 @@
+"""运行插件命令工具"""
+
+import json
+from typing import Optional, Type
+
+from pydantic import BaseModel, Field
+
+from app.agent.tools.base import MoviePilotTool
+from app.core.event import eventmanager
+from app.core.plugin import PluginManager
+from app.log import logger
+from app.schemas.types import EventType, MessageChannel
+
+
+class RunPluginCommandInput(BaseModel):
+    """运行插件命令工具的输入参数模型"""
+
+    explanation: str = Field(
+        ...,
+        description="Clear explanation of why this tool is being used in the current context",
+    )
+    command: str = Field(
+        ...,
+        description="The slash command to execute, e.g. '/cookiecloud'. "
+        "Must start with '/'. Can include arguments after the command, e.g. '/command arg1 arg2'. "
+        "Use query_plugin_capabilities tool to discover available commands first.",
+    )
+
+
+class RunPluginCommandTool(MoviePilotTool):
+    name: str = "run_plugin_command"
+    description: str = (
+        "Execute a plugin command by sending a CommandExcute event. "
+        "Plugin commands are slash-commands (starting with '/') registered by plugins. "
+        "Use the query_plugin_capabilities tool first to discover available commands and their descriptions. "
+        "The command will be executed asynchronously. "
+        "Note: This tool triggers the command execution but the actual processing happens in the background."
+    )
+    args_schema: Type[BaseModel] = RunPluginCommandInput
+
+    def get_tool_message(self, **kwargs) -> Optional[str]:
+        """生成友好的提示消息"""
+        command = kwargs.get("command", "")
+        return f"正在执行插件命令: {command}"
+
+    async def run(self, command: str, **kwargs) -> str:
+        logger.info(f"执行工具: {self.name}, 参数: command={command}")
+
+        try:
+            # 确保命令以 / 开头
+            if not command.startswith("/"):
+                command = f"/{command}"
+
+            # 验证命令是否存在
+            plugin_manager = PluginManager()
+            registered_commands = plugin_manager.get_plugin_commands()
+            cmd_name = command.split()[0]
+            matched_command = None
+            for cmd in registered_commands:
+                if cmd.get("cmd") == cmd_name:
+                    matched_command = cmd
+                    break
+
+            if not matched_command:
+                # 列出可用命令帮助用户
+                available_cmds = [
+                    f"{cmd.get('cmd')} - {cmd.get('desc', '无描述')}"
+                    for cmd in registered_commands
+                ]
+                result = {
+                    "success": False,
+                    "message": f"命令 {cmd_name} 不存在",
+                }
+                if available_cmds:
+                    result["available_commands"] = available_cmds
+                return json.dumps(result, ensure_ascii=False, indent=2)
+
+            # 构建消息渠道，优先使用当前会话的渠道信息
+            channel = None
+            if self._channel:
+                try:
+                    channel = MessageChannel(self._channel)
+                except (ValueError, KeyError):
+                    channel = None
+
+            # 发送命令执行事件，与 message.py 中的方式一致
+            eventmanager.send_event(
+                EventType.CommandExcute,
+                {
+                    "cmd": command,
+                    "user": self._user_id,
+                    "channel": channel,
+                    "source": self._source,
+                },
+            )
+
+            result = {
+                "success": True,
+                "message": f"命令 {cmd_name} 已触发执行",
+                "command": command,
+                "command_desc": matched_command.get("desc", ""),
+                "plugin_id": matched_command.get("pid", ""),
+            }
+            return json.dumps(result, ensure_ascii=False, indent=2)
+
+        except Exception as e:
+            logger.error(f"执行插件命令失败: {e}", exc_info=True)
+            return json.dumps(
+                {"success": False, "message": f"执行插件命令时发生错误: {str(e)}"},
+                ensure_ascii=False,
+            )

app/agent/tools/impl/run_workflow.py

@@ -14,21 +14,21 @@ from app.log import logger
 class RunWorkflowInput(BaseModel):
     """执行工作流工具的输入参数模型"""
     explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
-    workflow_identifier: str = Field(..., description="Workflow identifier: can be workflow ID (integer as string) or workflow name")
+    workflow_id: int = Field(..., description="Workflow ID (can be obtained from query_workflows tool)")
     from_begin: Optional[bool] = Field(True, description="Whether to run workflow from the beginning (default: True, if False will continue from last executed action)")
 
 
 class RunWorkflowTool(MoviePilotTool):
     name: str = "run_workflow"
-    description: str = "Execute a specific workflow manually. Can run workflow by ID or name. Supports running from the beginning or continuing from the last executed action."
+    description: str = "Execute a specific workflow manually by workflow ID. Supports running from the beginning or continuing from the last executed action."
     args_schema: Type[BaseModel] = RunWorkflowInput
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
         """根据工作流参数生成友好的提示消息"""
-        workflow_identifier = kwargs.get("workflow_identifier", "")
+        workflow_id = kwargs.get("workflow_id")
         from_begin = kwargs.get("from_begin", True)
         
-        message = f"正在执行工作流: {workflow_identifier}"
+        message = f"正在执行工作流: {workflow_id}"
         if not from_begin:
             message += " (从上次位置继续)"
         else:
@@ -36,27 +36,18 @@ class RunWorkflowTool(MoviePilotTool):
         
         return message
 
-    async def run(self, workflow_identifier: str,
+    async def run(self, workflow_id: int,
                   from_begin: Optional[bool] = True, **kwargs) -> str:
-        logger.info(f"执行工具: {self.name}, 参数: workflow_identifier={workflow_identifier}, from_begin={from_begin}")
+        logger.info(f"执行工具: {self.name}, 参数: workflow_id={workflow_id}, from_begin={from_begin}")
 
         try:
             # 获取数据库会话
             async with AsyncSessionFactory() as db:
                 workflow_oper = WorkflowOper(db)
-                
-                # 尝试解析为工作流ID
-                workflow = None
-                if workflow_identifier.isdigit():
-                    # 如果是数字，尝试作为工作流ID查询
-                    workflow = await workflow_oper.async_get(int(workflow_identifier))
-                
-                # 如果不是ID或ID查询失败，尝试按名称查询
-                if not workflow:
-                    workflow = await workflow_oper.async_get_by_name(workflow_identifier)
+                workflow = await workflow_oper.async_get(workflow_id)
                 
                 if not workflow:
-                    return f"未找到工作流：{workflow_identifier}，请使用 query_workflows 工具查询可用的工作流"
+                    return f"未找到工作流：{workflow_id}，请使用 query_workflows 工具查询可用的工作流"
                 
                 # 执行工作流
                 workflow_chain = WorkflowChain()

app/agent/tools/impl/search_media.py

@@ -8,7 +8,7 @@ from pydantic import BaseModel, Field
 from app.agent.tools.base import MoviePilotTool
 from app.chain.media import MediaChain
 from app.log import logger
-from app.schemas.types import MediaType
+from app.schemas.types import MediaType, media_type_to_agent
 
 
 class SearchMediaInput(BaseModel):
@@ -17,7 +17,7 @@ class SearchMediaInput(BaseModel):
     title: str = Field(..., description="The title of the media to search for (e.g., 'The Matrix', 'Breaking Bad')")
     year: Optional[str] = Field(None, description="Release year of the media (optional, helps narrow down results)")
     media_type: Optional[str] = Field(None,
-                                      description="Type of media content: '电影' for films, '电视剧' for television series or anime series")
+                                      description="Allowed values: movie, tv")
     season: Optional[int] = Field(None,
                                   description="Season number for TV shows and anime (optional, only applicable for series)")
 
@@ -56,13 +56,18 @@ class SearchMediaTool(MoviePilotTool):
 
             # 过滤结果
             if results:
+                media_type_enum = None
+                if media_type:
+                    media_type_enum = MediaType.from_agent(media_type)
+                    if not media_type_enum:
+                        return f"错误：无效的媒体类型 '{media_type}'，支持的类型：'movie', 'tv'"
+
                 filtered_results = []
                 for result in results:
                     if year and result.year != year:
                         continue
-                    if media_type:
-                        if result.type != MediaType(media_type):
-                            continue
+                    if media_type_enum and result.type != media_type_enum:
+                        continue
                     if season is not None and result.season != season:
                         continue
                     filtered_results.append(result)
@@ -78,7 +83,7 @@ class SearchMediaTool(MoviePilotTool):
                             "title": r.title,
                             "en_title": r.en_title,
                             "year": r.year,
-                            "type": r.type.value if r.type else None,
+                            "type": media_type_to_agent(r.type),
                             "season": r.season,
                             "tmdb_id": r.tmdb_id,
                             "imdb_id": r.imdb_id,

app/agent/tools/impl/search_subscribe.py

@@ -10,15 +10,16 @@ from app.chain.subscribe import SubscribeChain
 from app.core.config import global_vars
 from app.db.subscribe_oper import SubscribeOper
 from app.log import logger
+from app.schemas.types import media_type_to_agent
 
 
 class SearchSubscribeInput(BaseModel):
     """搜索订阅缺失剧集工具的输入参数模型"""
     explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
-    subscribe_id: int = Field(..., description="The ID of the subscription to search for missing episodes")
+    subscribe_id: int = Field(..., description="The ID of the subscription to search for missing episodes (can be obtained from query_subscribes tool)")
     manual: Optional[bool] = Field(False, description="Whether this is a manual search (default: False)")
     filter_groups: Optional[List[str]] = Field(None,
-                                               description="List of filter rule group names to apply for this search (optional, use query_rule_groups tool to get available rule groups. If provided, will temporarily update the subscription's filter groups before searching)")
+                                               description="List of filter rule group names to apply for this search (optional, can be obtained from query_rule_groups tool. If provided, will temporarily update the subscription's filter groups before searching)")
 
 
 class SearchSubscribeTool(MoviePilotTool):
@@ -58,7 +59,7 @@ class SearchSubscribeTool(MoviePilotTool):
                 "id": subscribe.id,
                 "name": subscribe.name,
                 "year": subscribe.year,
-                "type": subscribe.type,
+                "type": media_type_to_agent(subscribe.type),
                 "season": subscribe.season,
                 "state": subscribe.state,
                 "total_episode": subscribe.total_episode,

app/agent/tools/impl/search_torrents.py

@@ -1,142 +1,109 @@
 """搜索种子工具"""
 
 import json
-import re
 from typing import List, Optional, Type
 
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
 from app.chain.search import SearchChain
+from app.db.systemconfig_oper import SystemConfigOper
+from app.helper.sites import SitesHelper
 from app.log import logger
-from app.schemas.types import MediaType
-from app.utils.string import StringUtils
+from app.schemas.types import MediaType, SystemConfigKey
+from ._torrent_search_utils import (
+    SEARCH_RESULT_CACHE_FILE,
+    build_filter_options,
+)
 
 
 class SearchTorrentsInput(BaseModel):
     """搜索种子工具的输入参数模型"""
     explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
-    title: str = Field(...,
-                       description="The title of the media resource to search for (e.g., 'The Matrix 1999', 'Breaking Bad S01E01')")
-    year: Optional[str] = Field(None,
-                                description="Release year of the media (optional, helps narrow down search results)")
-    media_type: Optional[str] = Field(None,
-                                      description="Type of media content: '电影' for films, '电视剧' for television series or anime series")
-    season: Optional[int] = Field(None, description="Season number for TV shows (optional, only applicable for series)")
+    tmdb_id: Optional[int] = Field(None, description="TMDB ID (can be obtained from search_media tool). Either tmdb_id or douban_id must be provided.")
+    douban_id: Optional[str] = Field(None, description="Douban ID (can be obtained from search_media tool). Either tmdb_id or douban_id must be provided.")
+    media_type: Optional[str] = Field(None, description="Allowed values: movie, tv")
+    area: Optional[str] = Field(None, description="Search scope: 'title' (default) or 'imdbid'")
     sites: Optional[List[int]] = Field(None,
                                        description="Array of specific site IDs to search on (optional, if not provided searches all configured sites)")
-    filter_pattern: Optional[str] = Field(None,
-                                          description="Regular expression pattern to filter torrent titles by resolution, quality, or other keywords (e.g., '4K|2160p|UHD' for 4K content, '1080p|BluRay' for 1080p BluRay)")
-
 
 class SearchTorrentsTool(MoviePilotTool):
     name: str = "search_torrents"
-    description: str = "Search for torrent files across configured indexer sites based on media information. Returns available torrent downloads with details like file size, quality, and download links."
+    description: str = ("Search for torrent files by media ID across configured indexer sites, cache the matched results, "
+                        "and return available filter options for follow-up selection. "
+                        "Requires tmdb_id or douban_id (can be obtained from search_media tool) for accurate matching.")
     args_schema: Type[BaseModel] = SearchTorrentsInput
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
         """根据搜索参数生成友好的提示消息"""
-        title = kwargs.get("title", "")
-        year = kwargs.get("year")
+        tmdb_id = kwargs.get("tmdb_id")
+        douban_id = kwargs.get("douban_id")
         media_type = kwargs.get("media_type")
-        season = kwargs.get("season")
-        filter_pattern = kwargs.get("filter_pattern")
-        
-        message = f"正在搜索种子: {title}"
-        if year:
-            message += f" ({year})"
+
+        if tmdb_id:
+            message = f"正在搜索种子: TMDB={tmdb_id}"
+        elif douban_id:
+            message = f"正在搜索种子: 豆瓣={douban_id}"
+        else:
+            message = "正在搜索种子"
         if media_type:
             message += f" [{media_type}]"
-        if season:
-            message += f" 第{season}季"
-        if filter_pattern:
-            message += f" 过滤: {filter_pattern}"
-        
         return message
 
-    async def run(self, title: str, year: Optional[str] = None,
-                  media_type: Optional[str] = None, season: Optional[int] = None,
-                  sites: Optional[List[int]] = None, filter_pattern: Optional[str] = None, **kwargs) -> str:
+    async def run(self, tmdb_id: Optional[int] = None, douban_id: Optional[str] = None,
+                  media_type: Optional[str] = None, area: Optional[str] = None,
+                  sites: Optional[List[int]] = None, **kwargs) -> str:
         logger.info(
-            f"执行工具: {self.name}, 参数: title={title}, year={year}, media_type={media_type}, season={season}, sites={sites}, filter_pattern={filter_pattern}")
+            f"执行工具: {self.name}, 参数: tmdb_id={tmdb_id}, douban_id={douban_id}, media_type={media_type}, area={area}, sites={sites}")
+
+        if not tmdb_id and not douban_id:
+            return "参数错误：tmdb_id 和 douban_id 至少需要提供一个，请先使用 search_media 工具获取媒体 ID。"
 
         try:
             search_chain = SearchChain()
-            torrents = await search_chain.async_search_by_title(title=title, sites=sites)
-            filtered_torrents = []
-            # 编译正则表达式（如果提供）
-            regex_pattern = None
-            if filter_pattern:
-                try:
-                    regex_pattern = re.compile(filter_pattern, re.IGNORECASE)
-                except re.error as e:
-                    logger.warning(f"正则表达式编译失败: {filter_pattern}, 错误: {e}")
-                    return f"正则表达式格式错误: {str(e)}"
-            
-            for torrent in torrents:
-                # torrent 是 Context 对象，需要通过 meta_info 和 media_info 访问属性
-                if year and torrent.meta_info and torrent.meta_info.year != year:
-                    continue
-                if media_type and torrent.media_info:
-                    if torrent.media_info.type != MediaType(media_type):
-                        continue
-                if season is not None and torrent.meta_info and torrent.meta_info.begin_season != season:
-                    continue
-                # 使用正则表达式过滤标题（分辨率、质量等关键字）
-                if regex_pattern and torrent.torrent_info and torrent.torrent_info.title:
-                    if not regex_pattern.search(torrent.torrent_info.title):
-                        continue
-                filtered_torrents.append(torrent)
+            media_type_enum = None
+            if media_type:
+                media_type_enum = MediaType.from_agent(media_type)
+                if not media_type_enum:
+                    return f"错误：无效的媒体类型 '{media_type}'，支持的类型：'movie', 'tv'"
+
+            filtered_torrents = await search_chain.async_search_by_id(
+                tmdbid=tmdb_id,
+                doubanid=douban_id,
+                mtype=media_type_enum,
+                area=area or "title",
+                sites=sites,
+                cache_local=False,
+            )
+
+            # 获取站点信息
+            all_indexers = await SitesHelper().async_get_indexers()
+            all_sites = [{"id": indexer.get("id"), "name": indexer.get("name")} for indexer in (all_indexers or [])]
+
+            if sites:
+                search_site_ids = sites
+            else:
+                configured_sites = SystemConfigOper().get(SystemConfigKey.IndexerSites)
+                search_site_ids = configured_sites if configured_sites else []
 
             if filtered_torrents:
-                # 限制最多50条结果
-                total_count = len(filtered_torrents)
-                limited_torrents = filtered_torrents[:50]
-                # 精简字段，只保留关键信息
-                simplified_torrents = []
-                for t in limited_torrents:
-                    simplified = {}
-                    # 精简 torrent_info
-                    if t.torrent_info:
-                        simplified["torrent_info"] = {
-                            "title": t.torrent_info.title,
-                            "size": StringUtils.format_size(t.torrent_info.size),
-                            "seeders": t.torrent_info.seeders,
-                            "peers": t.torrent_info.peers,
-                            "site_name": t.torrent_info.site_name,
-                            "enclosure": t.torrent_info.enclosure,
-                            "page_url": t.torrent_info.page_url,
-                            "volume_factor": t.torrent_info.volume_factor,
-                            "pubdate": t.torrent_info.pubdate
-                        }
-                    # 精简 media_info
-                    if t.media_info:
-                        simplified["media_info"] = {
-                            "title": t.media_info.title,
-                            "en_title": t.media_info.en_title,
-                            "year": t.media_info.year,
-                            "type": t.media_info.type.value if t.media_info.type else None,
-                            "season": t.media_info.season,
-                            "tmdb_id": t.media_info.tmdb_id
-                        }
-                    # 精简 meta_info
-                    if t.meta_info:
-                        simplified["meta_info"] = {
-                            "name": t.meta_info.name,
-                            "cn_name": t.meta_info.cn_name,
-                            "en_name": t.meta_info.en_name,
-                            "year": t.meta_info.year,
-                            "type": t.meta_info.type.value if t.meta_info.type else None,
-                            "begin_season": t.meta_info.begin_season
-                        }
-                    simplified_torrents.append(simplified)
-                result_json = json.dumps(simplified_torrents, ensure_ascii=False, indent=2)
-                # 如果结果被裁剪，添加提示信息
-                if total_count > 50:
-                    return f"注意：搜索结果共找到 {total_count} 条，为节省上下文空间，仅显示前 50 条结果。\n\n{result_json}"
+                await search_chain.async_save_cache(filtered_torrents, SEARCH_RESULT_CACHE_FILE)
+                result_json = json.dumps({
+                    "total_count": len(filtered_torrents),
+                    "message": "搜索完成。请使用 get_search_results 工具获取搜索结果。",
+                    "all_sites": all_sites,
+                    "search_site_ids": search_site_ids,
+                    "filter_options": build_filter_options(filtered_torrents),
+                }, ensure_ascii=False, indent=2)
                 return result_json
             else:
-                return f"未找到相关种子资源: {title}"
+                media_id = f"TMDB={tmdb_id}" if tmdb_id else f"豆瓣={douban_id}"
+                result_json = json.dumps({
+                    "message": f"未找到相关种子资源: {media_id}",
+                    "all_sites": all_sites,
+                    "search_site_ids": search_site_ids,
+                }, ensure_ascii=False, indent=2)
+                return result_json
         except Exception as e:
             error_message = f"搜索种子时发生错误: {str(e)}"
             logger.error(f"搜索种子失败: {e}", exc_info=True)

app/agent/tools/impl/search_web.py

@@ -1,5 +1,6 @@
 import asyncio
 import json
+import random
 import re
 from typing import Optional, Type, List, Dict
 
@@ -72,10 +73,12 @@ class SearchWebTool(MoviePilotTool):
         """使用 Tavily API 进行搜索"""
         try:
             async with httpx.AsyncClient(timeout=SEARCH_TIMEOUT) as client:
+                # 从设置中随机选择一个 API Key（如果有多个）
+                tavity_api_key = random.choice(settings.TAVILY_API_KEY)
                 response = await client.post(
                     "https://api.tavily.com/search",
                     json={
-                        "api_key": settings.TAVILY_API_KEY,
+                        "api_key": tavity_api_key,
                         "query": query,
                         "search_depth": "basic",
                         "max_results": max_results,

app/agent/tools/impl/test_site.py

@@ -8,53 +8,31 @@ from app.agent.tools.base import MoviePilotTool
 from app.chain.site import SiteChain
 from app.db.site_oper import SiteOper
 from app.log import logger
-from app.utils.string import StringUtils
 
 
 class TestSiteInput(BaseModel):
     """测试站点连通性工具的输入参数模型"""
     explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
-    site_identifier: str = Field(..., description="Site identifier: can be site ID (integer as string), site name, or site domain/URL")
+    site_identifier: int = Field(..., description="Site ID to test (can be obtained from query_sites tool)")
 
 
 class TestSiteTool(MoviePilotTool):
     name: str = "test_site"
-    description: str = "Test site connectivity and availability. This will check if a site is accessible and can be logged in. Accepts site ID, site name, or site domain/URL as identifier."
+    description: str = "Test site connectivity and availability. This will check if a site is accessible and can be logged in. Accepts site ID only."
     args_schema: Type[BaseModel] = TestSiteInput
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
         """根据测试参数生成友好的提示消息"""
-        site_identifier = kwargs.get("site_identifier", "")
+        site_identifier = kwargs.get("site_identifier")
         return f"正在测试站点连通性: {site_identifier}"
 
-    async def run(self, site_identifier: str, **kwargs) -> str:
+    async def run(self, site_identifier: int, **kwargs) -> str:
         logger.info(f"执行工具: {self.name}, 参数: site_identifier={site_identifier}")
 
         try:
             site_oper = SiteOper()
             site_chain = SiteChain()
-            
-            # 尝试解析为站点ID
-            site = None
-            if site_identifier.isdigit():
-                # 如果是数字，尝试作为站点ID查询
-                site = await site_oper.async_get(int(site_identifier))
-            
-            # 如果不是ID或ID查询失败，尝试按名称或域名查询
-            if not site:
-                # 尝试按名称查询
-                sites = await site_oper.async_list()
-                for s in sites:
-                    if (site_identifier.lower() in (s.name or "").lower()) or \
-                       (site_identifier.lower() in (s.domain or "").lower()):
-                        site = s
-                        break
-                
-                # 如果还是没找到，尝试从URL提取域名
-                if not site:
-                    domain = StringUtils.get_url_domain(site_identifier)
-                    if domain:
-                        site = await site_oper.async_get_by_domain(domain)
+            site = await site_oper.async_get(site_identifier)
             
             if not site:
                 return f"未找到站点：{site_identifier}，请使用 query_sites 工具查询可用的站点"

app/agent/tools/impl/transfer_file.py

@@ -18,7 +18,7 @@ class TransferFileInput(BaseModel):
     storage: Optional[str] = Field("local", description="Storage type of the source file (default: 'local', can be 'smb', 'alist', etc.)")
     target_path: Optional[str] = Field(None, description="Target path for the transferred file/directory (optional, uses default library path if not specified)")
     target_storage: Optional[str] = Field(None, description="Target storage type (optional, uses default storage if not specified)")
-    media_type: Optional[str] = Field(None, description="Media type: '电影' for films, '电视剧' for television series (optional, will be auto-detected if not specified)")
+    media_type: Optional[str] = Field(None, description="Allowed values: movie, tv")
     tmdbid: Optional[int] = Field(None, description="TMDB ID for precise media identification (optional but recommended for accuracy)")
     doubanid: Optional[str] = Field(None, description="Douban ID for media identification (optional)")
     season: Optional[int] = Field(None, description="Season number for TV shows (optional)")
@@ -91,11 +91,10 @@ class TransferFileTool(MoviePilotTool):
                 target_path_obj = Path(target_path)
             
             # 处理媒体类型
-            mtype = None
+            media_type_enum = None
             if media_type:
-                try:
-                    mtype = MediaType(media_type)
-                except ValueError:
+                media_type_enum = MediaType.from_agent(media_type)
+                if not media_type_enum:
                     return f"错误：无效的媒体类型 '{media_type}'，支持的类型：'movie', 'tv'"
             
             # 调用整理方法
@@ -106,7 +105,7 @@ class TransferFileTool(MoviePilotTool):
                 target_path=target_path_obj,
                 tmdbid=tmdbid,
                 doubanid=doubanid,
-                mtype=mtype,
+                mtype=media_type_enum,
                 season=season,
                 transfer_type=transfer_type,
                 background=background

app/agent/tools/impl/update_site.py

@@ -17,7 +17,7 @@ from app.utils.string import StringUtils
 class UpdateSiteInput(BaseModel):
     """更新站点工具的输入参数模型"""
     explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
-    site_id: int = Field(..., description="The ID of the site to update")
+    site_id: int = Field(..., description="The ID of the site to update (can be obtained from query_sites tool)")
     name: Optional[str] = Field(None, description="Site name (optional)")
     url: Optional[str] = Field(None, description="Site URL (optional, will be automatically formatted)")
     pri: Optional[int] = Field(None, description="Site priority (optional, smaller value = higher priority, e.g., pri=1 has higher priority than pri=10)")

app/agent/tools/impl/update_site_cookie.py

@@ -8,13 +8,12 @@ from app.agent.tools.base import MoviePilotTool
 from app.chain.site import SiteChain
 from app.db.site_oper import SiteOper
 from app.log import logger
-from app.utils.string import StringUtils
 
 
 class UpdateSiteCookieInput(BaseModel):
     """更新站点Cookie和UA工具的输入参数模型"""
     explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
-    site_identifier: str = Field(..., description="Site identifier: can be site ID (integer as string), site name, or site domain/URL")
+    site_identifier: int = Field(..., description="Site ID to update Cookie and User-Agent for (can be obtained from query_sites tool)")
     username: str = Field(..., description="Site login username")
     password: str = Field(..., description="Site login password")
     two_step_code: Optional[str] = Field(None, description="Two-step verification code or secret key (optional, required for sites with 2FA enabled)")
@@ -22,12 +21,12 @@ class UpdateSiteCookieInput(BaseModel):
 
 class UpdateSiteCookieTool(MoviePilotTool):
     name: str = "update_site_cookie"
-    description: str = "Update site Cookie and User-Agent by logging in with username and password. This tool can automatically obtain and update the site's authentication credentials. Supports two-step verification for sites that require it. Accepts site ID, site name, or site domain/URL as identifier."
+    description: str = "Update site Cookie and User-Agent by logging in with username and password. This tool can automatically obtain and update the site's authentication credentials. Supports two-step verification for sites that require it. Accepts site ID only."
     args_schema: Type[BaseModel] = UpdateSiteCookieInput
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
         """根据更新参数生成友好的提示消息"""
-        site_identifier = kwargs.get("site_identifier", "")
+        site_identifier = kwargs.get("site_identifier")
         username = kwargs.get("username", "")
         two_step_code = kwargs.get("two_step_code")
         
@@ -37,35 +36,14 @@ class UpdateSiteCookieTool(MoviePilotTool):
         
         return message
 
-    async def run(self, site_identifier: str, username: str, password: str, 
+    async def run(self, site_identifier: int, username: str, password: str,
                   two_step_code: Optional[str] = None, **kwargs) -> str:
         logger.info(f"执行工具: {self.name}, 参数: site_identifier={site_identifier}, username={username}")
 
         try:
             site_oper = SiteOper()
             site_chain = SiteChain()
-            
-            # 尝试解析为站点ID
-            site = None
-            if site_identifier.isdigit():
-                # 如果是数字，尝试作为站点ID查询
-                site = await site_oper.async_get(int(site_identifier))
-            
-            # 如果不是ID或ID查询失败，尝试按名称或域名查询
-            if not site:
-                # 尝试按名称查询
-                sites = await site_oper.async_list()
-                for s in sites:
-                    if (site_identifier.lower() in (s.name or "").lower()) or \
-                       (site_identifier.lower() in (s.domain or "").lower()):
-                        site = s
-                        break
-                
-                # 如果还是没找到，尝试从URL提取域名
-                if not site:
-                    domain = StringUtils.get_url_domain(site_identifier)
-                    if domain:
-                        site = await site_oper.async_get_by_domain(domain)
+            site = await site_oper.async_get(site_identifier)
             
             if not site:
                 return f"未找到站点：{site_identifier}，请使用 query_sites 工具查询可用的站点"

app/agent/tools/impl/update_subscribe.py

@@ -16,7 +16,7 @@ from app.schemas.types import EventType
 class UpdateSubscribeInput(BaseModel):
     """更新订阅工具的输入参数模型"""
     explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
-    subscribe_id: int = Field(..., description="The ID of the subscription to update")
+    subscribe_id: int = Field(..., description="The ID of the subscription to update (can be obtained from query_subscribes tool)")
     name: Optional[str] = Field(None, description="Subscription name/title (optional)")
     year: Optional[str] = Field(None, description="Release year (optional)")
     season: Optional[int] = Field(None, description="Season number for TV shows (optional)")

app/agent/tools/impl/write_file.py

@@ -0,0 +1,52 @@
+"""文件写入工具"""
+
+from pathlib import Path
+from typing import Optional, Type
+
+from anyio import Path as AsyncPath
+from pydantic import BaseModel, Field
+
+from app.agent.tools.base import MoviePilotTool
+from app.log import logger
+
+
+class WriteFileInput(BaseModel):
+    """Input parameters for write file tool"""
+    file_path: str = Field(..., description="The absolute path of the file to write")
+    content: str = Field(..., description="The content to write into the file")
+
+
+class WriteFileTool(MoviePilotTool):
+    name: str = "write_file"
+    description: str = "Write full content to a file. If the file already exists, it will be overwritten. Automatically creates parent directories if they don't exist."
+    args_schema: Type[BaseModel] = WriteFileInput
+
+    def get_tool_message(self, **kwargs) -> Optional[str]:
+        """根据参数生成友好的提示消息"""
+        file_path = kwargs.get("file_path", "")
+        file_name = Path(file_path).name if file_path else "未知文件"
+        return f"正在写入文件: {file_name}"
+
+    async def run(self, file_path: str, content: str, **kwargs) -> str:
+        logger.info(f"执行工具: {self.name}, 参数: file_path={file_path}")
+
+        try:
+            path = AsyncPath(file_path)
+            
+            if await path.exists() and not await path.is_file():
+                return f"错误：{file_path} 路径已存在但不是一个文件"
+
+            # 自动创建父目录
+            await path.parent.mkdir(parents=True, exist_ok=True)
+            
+            # 写入文件
+            await path.write_text(content, encoding="utf-8")
+                
+            logger.info(f"成功写入文件 {file_path}")
+            return f"成功写入文件 {file_path}"
+
+        except PermissionError:
+            return f"错误：没有权限写入 {file_path}"
+        except Exception as e:
+            logger.error(f"写入文件 {file_path} 时发生错误: {str(e)}", exc_info=True)
+            return f"操作失败: {str(e)}"

app/agent/tools/manager.py

@@ -25,7 +25,7 @@ class MoviePilotToolsManager:
     def __init__(self, user_id: str = "api_user", session_id: str = uuid.uuid4()):
         """
         初始化工具管理器
-        
+
         Args:
             user_id: 用户ID
             session_id: 会话ID
@@ -47,7 +47,7 @@ class MoviePilotToolsManager:
                 channel=None,
                 source="api",
                 username="API Client",
-                callback_handler=None,
+                stream_handler=None,
             )
             logger.info(f"成功加载 {len(self.tools)} 个工具")
         except Exception as e:
@@ -57,40 +57,38 @@ class MoviePilotToolsManager:
     def list_tools(self) -> List[ToolDefinition]:
         """
         列出所有可用的工具
-        
+
         Returns:
             工具定义列表
         """
         tools_list = []
         for tool in self.tools:
             # 获取工具的输入参数模型
-            args_schema = getattr(tool, 'args_schema', None)
+            args_schema = getattr(tool, "args_schema", None)
             if args_schema:
                 # 将Pydantic模型转换为JSON Schema
                 input_schema = self._convert_to_json_schema(args_schema)
             else:
                 # 如果没有args_schema，使用基本信息
-                input_schema = {
-                    "type": "object",
-                    "properties": {},
-                    "required": []
-                }
+                input_schema = {"type": "object", "properties": {}, "required": []}
 
-            tools_list.append(ToolDefinition(
-                name=tool.name,
-                description=tool.description or "",
-                input_schema=input_schema
-            ))
+            tools_list.append(
+                ToolDefinition(
+                    name=tool.name,
+                    description=tool.description or "",
+                    input_schema=input_schema,
+                )
+            )
 
         return tools_list
 
     def get_tool(self, tool_name: str) -> Optional[Any]:
         """
         获取指定工具实例
-        
+
         Args:
             tool_name: 工具名称
-            
+
         Returns:
             工具实例，如果未找到返回None
         """
@@ -100,19 +98,85 @@ class MoviePilotToolsManager:
         return None
 
     @staticmethod
-    def _normalize_arguments(tool_instance: Any, arguments: Dict[str, Any]) -> Dict[str, Any]:
+    def _resolve_field_schema(field_info: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        解析字段schema，兼容 Optional[T] 生成的 anyOf 结构
+        """
+        if field_info.get("type"):
+            return field_info
+
+        any_of = field_info.get("anyOf")
+        if not any_of:
+            return field_info
+
+        for type_option in any_of:
+            if type_option.get("type") and type_option["type"] != "null":
+                merged = dict(type_option)
+                if "description" not in merged and field_info.get("description"):
+                    merged["description"] = field_info["description"]
+                if "default" not in merged and "default" in field_info:
+                    merged["default"] = field_info["default"]
+                return merged
+
+        return field_info
+
+    @staticmethod
+    def _normalize_scalar_value(field_type: Optional[str], value: Any, key: str) -> Any:
+        """
+        根据字段类型规范化单个值
+        """
+        if field_type == "integer" and isinstance(value, str):
+            try:
+                return int(value)
+            except (ValueError, TypeError):
+                logger.warning(f"无法将参数 {key}='{value}' 转换为整数，返回 None")
+                return None
+        if field_type == "number" and isinstance(value, str):
+            try:
+                return float(value)
+            except (ValueError, TypeError):
+                logger.warning(f"无法将参数 {key}='{value}' 转换为浮点数，返回 None")
+                return None
+        if field_type == "boolean":
+            if isinstance(value, str):
+                return value.lower() in ("true", "1", "yes", "on")
+            if isinstance(value, (int, float)):
+                return value != 0
+            if isinstance(value, bool):
+                return value
+            return True
+        return value
+
+    @staticmethod
+    def _parse_array_string(value: str, key: str, item_type: str = "string") -> list:
+        """
+        将逗号分隔的字符串解析为列表，并根据 item_type 转换元素类型
+        """
+        trimmed = value.strip()
+        if not trimmed:
+            return []
+        return [
+            MoviePilotToolsManager._normalize_scalar_value(item_type, item.strip(), key)
+            for item in trimmed.split(",")
+            if item.strip()
+        ]
+
+    @staticmethod
+    def _normalize_arguments(
+        tool_instance: Any, arguments: Dict[str, Any]
+    ) -> Dict[str, Any]:
         """
         根据工具的参数schema规范化参数类型
-        
+
         Args:
             tool_instance: 工具实例
             arguments: 原始参数
-            
+
         Returns:
             规范化后的参数
         """
         # 获取工具的参数schema
-        args_schema = getattr(tool_instance, 'args_schema', None)
+        args_schema = getattr(tool_instance, "args_schema", None)
         if not args_schema:
             return arguments
 
@@ -132,60 +196,41 @@ class MoviePilotToolsManager:
                 normalized[key] = value
                 continue
 
-            field_info = properties[key]
+            field_info = MoviePilotToolsManager._resolve_field_schema(properties[key])
             field_type = field_info.get("type")
 
-            # 处理 anyOf 类型（例如 Optional[int] 会生成 anyOf）
-            any_of = field_info.get("anyOf")
-            if any_of and not field_type:
-                # 从 anyOf 中提取实际类型
-                for type_option in any_of:
-                    if "type" in type_option and type_option["type"] != "null":
-                        field_type = type_option["type"]
-                        break
+            # 数组类型：将字符串解析为列表
+            if field_type == "array" and isinstance(value, str):
+                item_type = field_info.get("items", {}).get("type", "string")
+                normalized[key] = MoviePilotToolsManager._parse_array_string(
+                    value, key, item_type
+                )
+                continue
 
             # 根据类型进行转换
-            if field_type == "integer" and isinstance(value, str):
-                try:
-                    normalized[key] = int(value)
-                except (ValueError, TypeError):
-                    logger.warning(f"无法将参数 {key}='{value}' 转换为整数，保持原值")
-                    normalized[key] = None
-            elif field_type == "number" and isinstance(value, str):
-                try:
-                    normalized[key] = float(value)
-                except (ValueError, TypeError):
-                    logger.warning(f"无法将参数 {key}='{value}' 转换为浮点数，保持原值")
-                    normalized[key] = None
-            elif field_type == "boolean":
-                if isinstance(value, str):
-                    normalized[key] = value.lower() in ("true", "1", "yes", "on")
-                elif isinstance(value, (int, float)):
-                    normalized[key] = value != 0
-                else:
-                    normalized[key] = True
-            else:
-                normalized[key] = value
+            normalized[key] = MoviePilotToolsManager._normalize_scalar_value(
+                field_type, value, key
+            )
 
         return normalized
 
     async def call_tool(self, tool_name: str, arguments: Dict[str, Any]) -> str:
         """
         调用工具
-        
+
         Args:
             tool_name: 工具名称
             arguments: 工具参数
-            
+
         Returns:
             工具执行结果（字符串）
         """
         tool_instance = self.get_tool(tool_name)
 
         if not tool_instance:
-            error_msg = json.dumps({
-                "error": f"工具 '{tool_name}' 未找到"
-            }, ensure_ascii=False)
+            error_msg = json.dumps(
+                {"error": f"工具 '{tool_name}' 未找到"}, ensure_ascii=False
+            )
             return error_msg
 
         try:
@@ -198,7 +243,7 @@ class MoviePilotToolsManager:
             # 确保返回字符串
             if isinstance(result, str):
                 formated_result = result
-            elif isinstance(result, int, float):
+            elif isinstance(result, (int, float)):
                 formated_result = str(result)
             else:
                 try:
@@ -210,19 +255,20 @@ class MoviePilotToolsManager:
             return formated_result
         except Exception as e:
             logger.error(f"调用工具 {tool_name} 时发生错误: {e}", exc_info=True)
-            error_msg = json.dumps({
-                "error": f"调用工具 '{tool_name}' 时发生错误: {str(e)}"
-            }, ensure_ascii=False)
+            error_msg = json.dumps(
+                {"error": f"调用工具 '{tool_name}' 时发生错误: {str(e)}"},
+                ensure_ascii=False,
+            )
             return error_msg
 
     @staticmethod
     def _convert_to_json_schema(args_schema: Any) -> Dict[str, Any]:
         """
         将Pydantic模型转换为JSON Schema
-        
+
         Args:
             args_schema: Pydantic模型类
-            
+
         Returns:
             JSON Schema字典
         """
@@ -235,40 +281,39 @@ class MoviePilotToolsManager:
 
         if "properties" in schema:
             for field_name, field_info in schema["properties"].items():
+                resolved_field_info = MoviePilotToolsManager._resolve_field_schema(
+                    field_info
+                )
                 # 转换字段类型
-                field_type = field_info.get("type", "string")
-                field_description = field_info.get("description", "")
+                field_type = resolved_field_info.get("type", "string")
+                field_description = resolved_field_info.get("description", "")
 
                 # 处理可选字段
                 if field_name not in schema.get("required", []):
                     # 可选字段
-                    default_value = field_info.get("default")
+                    default_value = resolved_field_info.get("default")
                     properties[field_name] = {
                         "type": field_type,
-                        "description": field_description
+                        "description": field_description,
                     }
                     if default_value is not None:
                         properties[field_name]["default"] = default_value
                 else:
                     properties[field_name] = {
                         "type": field_type,
-                        "description": field_description
+                        "description": field_description,
                     }
                     required.append(field_name)
 
                 # 处理枚举类型
-                if "enum" in field_info:
-                    properties[field_name]["enum"] = field_info["enum"]
+                if "enum" in resolved_field_info:
+                    properties[field_name]["enum"] = resolved_field_info["enum"]
 
                 # 处理数组类型
-                if field_type == "array" and "items" in field_info:
-                    properties[field_name]["items"] = field_info["items"]
+                if field_type == "array" and "items" in resolved_field_info:
+                    properties[field_name]["items"] = resolved_field_info["items"]
 
-        return {
-            "type": "object",
-            "properties": properties,
-            "required": required
-        }
+        return {"type": "object", "properties": properties, "required": required}
 
 
 moviepilot_tool_manager = MoviePilotToolsManager()

app/api/endpoints/dashboard.py

@@ -26,11 +26,17 @@ def statistic(name: Optional[str] = None, _: schemas.TokenPayload = Depends(veri
     if media_statistics:
         # 汇总各媒体库统计信息
         ret_statistic = schemas.Statistic()
+        has_episode_count = False
         for media_statistic in media_statistics:
-            ret_statistic.movie_count += media_statistic.movie_count
-            ret_statistic.tv_count += media_statistic.tv_count
-            ret_statistic.episode_count += media_statistic.episode_count
-            ret_statistic.user_count += media_statistic.user_count
+            ret_statistic.movie_count += media_statistic.movie_count or 0
+            ret_statistic.tv_count += media_statistic.tv_count or 0
+            ret_statistic.user_count += media_statistic.user_count or 0
+            if media_statistic.episode_count is not None:
+                ret_statistic.episode_count += media_statistic.episode_count or 0
+                has_episode_count = True
+        if not has_episode_count:
+            # 所有媒体服务都未提供剧集统计时，返回 None 供前端展示“未获取”。
+            ret_statistic.episode_count = None
         return ret_statistic
     else:
         return schemas.Statistic()

app/api/endpoints/download.py

@@ -6,13 +6,12 @@ from app import schemas
 from app.chain.download import DownloadChain
 from app.chain.media import MediaChain
 from app.core.context import MediaInfo, Context, TorrentInfo
-from app.core.event import eventmanager
 from app.core.metainfo import MetaInfo
 from app.core.security import verify_token
 from app.db.models.user import User
 from app.db.systemconfig_oper import SystemConfigOper
 from app.db.user_oper import get_current_active_user
-from app.schemas.types import ChainEventType, SystemConfigKey
+from app.schemas.types import SystemConfigKey
 
 router = APIRouter()
 
@@ -77,13 +76,14 @@ def add(
     # 元数据
     metainfo = MetaInfo(title=torrent_in.title, subtitle=torrent_in.description)
     # 媒体信息
-    mediainfo = MediaChain().recognize_media(meta=metainfo, tmdbid=tmdbid, doubanid=doubanid)
+    mediainfo = MediaChain().select_recognize_source(
+                    log_name=torrent_in.title,
+                    log_context=torrent_in.title,
+                    native_fn=lambda: MediaChain().recognize_media(meta=metainfo, tmdbid=tmdbid, doubanid=doubanid),
+                    plugin_fn=lambda: MediaChain().recognize_help(title=torrent_in.title, org_meta=metainfo)
+                )
     if not mediainfo:
-        # 尝试使用辅助识别，如果有注册响应事件的话
-        if eventmanager.check(ChainEventType.NameRecognize):
-            mediainfo = MediaChain().recognize_help(title=torrent_in.title, org_meta=metainfo)
-        if not mediainfo:
-            return schemas.Response(success=False, message="无法识别媒体信息")
+        return schemas.Response(success=False, message="无法识别媒体信息")
     # 种子信息
     torrentinfo = TorrentInfo()
     torrentinfo.from_dict(torrent_in.model_dump())

app/api/endpoints/mcp.py

@@ -19,6 +19,23 @@ router = APIRouter()
 # MCP 协议版本
 MCP_PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18", "2024-11-05"]
 MCP_PROTOCOL_VERSION = MCP_PROTOCOL_VERSIONS[0]  # 默认使用最新版本
+MCP_HIDDEN_TOOLS = {
+    "execute_command",
+    "search_web",
+    "edit_file",
+    "write_file",
+    "read_file",
+}
+
+
+def list_exposed_tools():
+    """
+    获取 MCP 可见工具列表
+    """
+    return [
+        tool for tool in moviepilot_tool_manager.list_tools()
+        if tool.name not in MCP_HIDDEN_TOOLS
+    ]
 
 
 def create_jsonrpc_response(request_id: Union[str, int, None], result: Any) -> Dict[str, Any]:
@@ -174,7 +191,7 @@ async def handle_tools_list() -> Dict[str, Any]:
     """
     处理工具列表请求
     """
-    tools = moviepilot_tool_manager.list_tools()
+    tools = list_exposed_tools()
 
     # 转换为 MCP 工具格式
     mcp_tools = []
@@ -202,6 +219,9 @@ async def handle_tools_call(params: Dict[str, Any]) -> Dict[str, Any]:
         raise ValueError("Missing tool name")
 
     try:
+        if tool_name in MCP_HIDDEN_TOOLS:
+            raise ValueError(f"工具 '{tool_name}' 未找到")
+
         result_text = await moviepilot_tool_manager.call_tool(tool_name, arguments)
 
         return {
@@ -248,7 +268,7 @@ async def list_tools(
     """
     try:
         # 获取所有工具定义
-        tools = moviepilot_tool_manager.list_tools()
+        tools = list_exposed_tools()
 
         # 转换为字典格式
         tools_list = []
@@ -278,7 +298,9 @@ async def call_tool(
         工具执行结果
     """
     try:
-        # 调用工具
+        if request.tool_name in MCP_HIDDEN_TOOLS:
+            raise ValueError(f"工具 '{request.tool_name}' 未找到")
+
         result_text = await moviepilot_tool_manager.call_tool(request.tool_name, request.arguments)
 
         return schemas.ToolCallResponse(
@@ -306,7 +328,7 @@ async def get_tool_info(
     """
     try:
         # 获取所有工具
-        tools = moviepilot_tool_manager.list_tools()
+        tools = list_exposed_tools()
 
         # 查找指定工具
         for tool in tools:
@@ -338,7 +360,7 @@ async def get_tool_schema(
     """
     try:
         # 获取所有工具
-        tools = moviepilot_tool_manager.list_tools()
+        tools = list_exposed_tools()
 
         # 查找指定工具
         for tool in tools:

app/api/endpoints/message.py

@@ -86,7 +86,10 @@ def wechat_verify(echostr: str, msg_signature: str, timestamp: Union[str, int],
     if not client_configs:
         return "未找到对应的消息配置"
     client_config = next((config for config in client_configs if
-                          config.type == "wechat" and config.enabled and (not source or config.name == source)), None)
+                          config.type == "wechat"
+                          and config.enabled
+                          and config.config.get("WECHAT_MODE", "app") != "bot"
+                          and (not source or config.name == source)), None)
     if not client_config:
         return "未找到对应的消息配置"
     try:

app/api/endpoints/plugin.py

@@ -360,7 +360,18 @@ async def plugin_static_file(plugin_id: str, filepath: str):
         raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Forbidden")
 
     plugin_base_dir = AsyncPath(settings.ROOT_PATH) / "app" / "plugins" / plugin_id.lower()
-    plugin_file_path = plugin_base_dir / filepath
+    plugin_file_path = plugin_base_dir / filepath.lstrip('/')
+
+    try:
+        resolved_base = await plugin_base_dir.resolve()
+        resolved_file = await plugin_file_path.resolve()
+    except Exception:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Invalid path")
+
+    if not resolved_file.is_relative_to(resolved_base):
+        logger.warning(f"Static File API: Path traversal attempt detected: {plugin_id}/{filepath}")
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Forbidden")
+
     if not await plugin_file_path.exists():
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"{plugin_file_path} 不存在")
     if not await plugin_file_path.is_file():

app/api/endpoints/transfer.py

@@ -93,6 +93,8 @@ def manual_transfer(transer_item: ManualTransferItem,
     :param _: Token校验
     """
     force = False
+    downloader = None
+    download_hash = None
     target_path = Path(transer_item.target_path) if transer_item.target_path else None
     if transer_item.logid:
         # 查询历史记录
@@ -101,6 +103,8 @@ def manual_transfer(transer_item: ManualTransferItem,
             return schemas.Response(success=False, message=f"整理记录不存在，ID：{transer_item.logid}")
         # 强制转移
         force = True
+        downloader = history.downloader
+        download_hash = history.download_hash
         if history.status and ("move" in history.mode):
             # 重新整理成功的转移，则使用成功的 dest 做 in_path
             src_fileitem = FileItem(**history.dest_fileitem)
@@ -121,6 +125,7 @@ def manual_transfer(transer_item: ManualTransferItem,
             transer_item.tmdbid = int(history.tmdbid) if history.tmdbid else transer_item.tmdbid
             transer_item.doubanid = str(history.doubanid) if history.doubanid else transer_item.doubanid
             transer_item.season = int(str(history.seasons).replace("S", "")) if history.seasons else transer_item.season
+            transer_item.episode_group = history.episode_group or transer_item.episode_group
             if history.episodes:
                 if "-" in str(history.episodes):
                     # E01-E03多集合并
@@ -138,8 +143,14 @@ def manual_transfer(transer_item: ManualTransferItem,
     else:
         return schemas.Response(success=False, message=f"缺少参数")
 
-    # 类型
-    mtype = MediaType(transer_item.type_name) if transer_item.type_name else None
+    # 类型（“自动/auto/none”按未指定处理）
+    mtype = None
+    type_name = str(transer_item.type_name).strip() if transer_item.type_name else ""
+    if type_name and type_name.lower() not in {"自动", "auto", "none"}:
+        try:
+            mtype = MediaType(type_name)
+        except ValueError:
+            return schemas.Response(success=False, message=f"不支持的媒体类型：{type_name}")
     # 自定义格式
     epformat = None
     if transer_item.episode_offset or transer_item.episode_part \
@@ -167,7 +178,9 @@ def manual_transfer(transer_item: ManualTransferItem,
         library_type_folder=transer_item.library_type_folder,
         library_category_folder=transer_item.library_category_folder,
         force=force,
-        background=background
+        background=background,
+        downloader=downloader,
+        download_hash=download_hash
     )
     # 失败
     if not state:

app/api/endpoints/user.py

@@ -12,7 +12,6 @@ from app.db.models.user import User
 from app.db.user_oper import get_current_active_superuser_async, \
     get_current_active_user_async, get_current_active_user
 from app.db.userconfig_oper import UserConfigOper
-from app.utils.otp import OtpUtils
 
 router = APIRouter()
 

app/chain/download.py

@@ -152,7 +152,8 @@ class DownloadChain(ChainBase):
                         save_path: Optional[str] = None,
                         userid: Union[str, int] = None,
                         username: Optional[str] = None,
-                        label: Optional[str] = None) -> Optional[str]:
+                        label: Optional[str] = None,
+                        return_detail: bool = False) -> Union[Optional[str], Tuple[Optional[str], Optional[str]]]:
         """
         下载及发送通知
         :param context: 资源上下文
@@ -166,6 +167,8 @@ class DownloadChain(ChainBase):
         :param userid: 用户ID
         :param username: 调用下载的用户名/插件名
         :param label: 自定义标签
+        :param return_detail: 是否返回详细结果；False 时返回下载任务 hash 或 None，True 时返回 (hash, error_msg)
+        :return: return_detail=False 时返回下载任务 hash 或 None；return_detail=True 时返回 (hash, error_msg)
         """
         _torrent = context.torrent_info
         _media = context.media_info
@@ -195,7 +198,7 @@ class DownloadChain(ChainBase):
                 logger.debug(
                     f"Resource download canceled by event: {event_data.source},"
                     f"Reason: {event_data.reason}")
-                return None
+                return (None, "下载被事件取消") if return_detail else None
             # 如果事件修改了下载路径，使用新路径
             if event_data.options and event_data.options.get("save_path"):
                 save_path = event_data.options.get("save_path")
@@ -227,7 +230,7 @@ class DownloadChain(ChainBase):
                 torrent_content = cache_backend.get(torrent_file.as_posix(), region="torrents")
 
         if not torrent_content:
-            return None
+            return (None, "下载种子内容为空") if return_detail else None
 
         # 获取种子文件的文件夹名和文件清单
         _folder_name, _file_list = TorrentHelper().get_fileinfo_from_torrent_content(torrent_content)
@@ -259,7 +262,7 @@ class DownloadChain(ChainBase):
                 logger.error(f"未找到下载目录：{_media.type.value} {_media.title_year}")
                 self.messagehelper.put(f"{_media.type.value} {_media.title_year} 未找到下载目录！",
                                        title="下载失败", role="system")
-                return None
+                return (None, "未找到下载目录") if return_detail else None
             fileURI = FileURI(storage=storage, path=download_dir.as_posix())
             download_dir = Path(fileURI.uri)
 
@@ -388,6 +391,8 @@ class DownloadChain(ChainBase):
                      f"错误信息：{error_msg}",
                 image=_media.get_message_image(),
                 userid=userid))
+        if return_detail:
+            return _hash, error_msg
         return _hash
 
     def batch_download(self,

app/chain/message.py

@@ -40,7 +40,7 @@ class MessageChain(ChainBase):
     # 用户会话信息 {userid: (session_id, last_time)}
     _user_sessions: Dict[Union[str, int], tuple] = {}
     # 会话超时时间（分钟）
-    _session_timeout_minutes: int = 30
+    _session_timeout_minutes: int = 24 * 60
 
     @staticmethod
     def __get_noexits_info(
@@ -112,8 +112,8 @@ class MessageChain(ChainBase):
         channel = info.channel
         # 用户ID
         userid = info.userid
-        # 用户名
-        username = info.username or userid
+        # 用户名（当渠道未提供公开用户名时，回退为 userid 的字符串，避免后续类型校验异常）
+        username = str(info.username) if info.username not in (None, "") else str(userid)
         if userid is None or userid == '':
             logger.debug(f'未识别到用户ID：{body}{form}{args}')
             return
@@ -490,18 +490,14 @@ class MessageChain(ChainBase):
                         # 重新搜索/下载
                         content = re.sub(r"(搜索|下载)[:：\s]*", "", text)
                         action = "ReSearch"
-                    elif text.startswith("#") \
-                            or re.search(r"^请[问帮你]", text) \
-                            or re.search(r"[?？]$", text) \
-                            or StringUtils.count_words(text) > 10 \
-                            or text.find("继续") != -1:
-                        # 聊天
-                        content = text
-                        action = "Chat"
                     elif StringUtils.is_link(text):
                         # 链接
                         content = text
                         action = "Link"
+                    elif not StringUtils.is_media_title_like(text):
+                        # 聊天
+                        content = text
+                        action = "Chat"
                     else:
                         # 搜索
                         content = text

app/chain/search.py

@@ -280,7 +280,7 @@ class SearchChain(ChainBase):
                     logger.info(f"种子名称应用识别词后发生改变：{torrent.title} => {torrent_meta.org_string}")
                 # 季集数过滤
                 if season_episodes \
-                        and not torrenthelper.match_season_episodes(torrent=torrent,
+                        and not TorrentHelper.match_season_episodes(torrent=torrent,
                                                                     meta=torrent_meta,
                                                                     season_episodes=season_episodes):
                     continue

app/chain/transfer.py

@@ -1634,7 +1634,9 @@ class TransferChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
                         library_type_folder: Optional[bool] = None,
                         library_category_folder: Optional[bool] = None,
                         force: Optional[bool] = False,
-                        background: Optional[bool] = False) -> Tuple[bool, Union[str, list]]:
+                        background: Optional[bool] = False,
+                        downloader: Optional[str] = None,
+                        download_hash: Optional[str] = None) -> Tuple[bool, Union[str, list]]:
         """
         手动整理，支持复杂条件，带进度显示
         :param fileitem: 文件项
@@ -1653,6 +1655,8 @@ class TransferChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
         :param library_category_folder: 是否按类别建立目录
         :param force: 是否强制整理
         :param background: 是否后台运行
+        :param downloader: 下载器名称
+        :param download_hash: 下载任务哈希
         """
         logger.info(f"手动整理：{fileitem.path} ...")
         if tmdbid or doubanid:
@@ -1682,7 +1686,9 @@ class TransferChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
                 library_category_folder=library_category_folder,
                 force=force,
                 background=background,
-                manual=True
+                manual=True,
+                downloader=downloader,
+                download_hash=download_hash
             )
             if not state:
                 return False, errmsg
@@ -1703,7 +1709,9 @@ class TransferChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
                                              library_category_folder=library_category_folder,
                                              force=force,
                                              background=background,
-                                             manual=True)
+                                             manual=True,
+                                             downloader=downloader,
+                                             download_hash=download_hash)
             return state, errmsg
 
     def send_transfer_message(self, meta: MetaBase, mediainfo: MediaInfo,

app/core/config.py

@@ -27,6 +27,7 @@ class SystemConfModel(BaseModel):
     """
     系统关键资源大小配置
     """
+
     # 缓存种子数量
     torrents: int = 0
     # 订阅刷新处理数量
@@ -160,14 +161,16 @@ class ConfigModel(BaseModel):
     # 是否启用DOH解析域名
     DOH_ENABLE: bool = False
     # 使用 DOH 解析的域名列表
-    DOH_DOMAINS: str = ("api.themoviedb.org,"
-                        "api.tmdb.org,"
-                        "webservice.fanart.tv,"
-                        "api.github.com,"
-                        "github.com,"
-                        "raw.githubusercontent.com,"
-                        "codeload.github.com,"
-                        "api.telegram.org")
+    DOH_DOMAINS: str = (
+        "api.themoviedb.org,"
+        "api.tmdb.org,"
+        "webservice.fanart.tv,"
+        "api.github.com,"
+        "github.com,"
+        "raw.githubusercontent.com,"
+        "codeload.github.com,"
+        "api.telegram.org"
+    )
     # DOH 解析服务器列表
     DOH_RESOLVERS: str = "1.0.0.1,1.1.1.1,9.9.9.9,149.112.112.112"
 
@@ -208,7 +211,7 @@ class ConfigModel(BaseModel):
 
     # ==================== 云盘配置 ====================
     # 115 AppId
-    U115_APP_ID: str = "100196807"
+    U115_APP_ID: str = "100197847"
     # 115 OAuth2 Server 地址
     U115_AUTH_SERVER: str = "https://movie-pilot.org"
     # Alipan AppId
@@ -216,30 +219,77 @@ class ConfigModel(BaseModel):
 
     # ==================== 系统升级配置 ====================
     # 重启自动升级
-    MOVIEPILOT_AUTO_UPDATE: str = 'release'
+    MOVIEPILOT_AUTO_UPDATE: str = "release"
     # 自动检查和更新站点资源包（站点索引、认证等）
     AUTO_UPDATE_RESOURCE: bool = True
 
     # ==================== 媒体文件格式配置 ====================
     # 支持的视频文件后缀格式
     RMT_MEDIAEXT: list = Field(
-        default_factory=lambda: ['.mp4', '.mkv', '.ts', '.iso',
-                                 '.rmvb', '.avi', '.mov', '.mpeg',
-                                 '.mpg', '.wmv', '.3gp', '.asf',
-                                 '.m4v', '.flv', '.m2ts', '.strm',
-                                 '.tp', '.f4v']
+        default_factory=lambda: [
+            ".mp4",
+            ".mkv",
+            ".ts",
+            ".iso",
+            ".rmvb",
+            ".avi",
+            ".mov",
+            ".mpeg",
+            ".mpg",
+            ".wmv",
+            ".3gp",
+            ".asf",
+            ".m4v",
+            ".flv",
+            ".m2ts",
+            ".strm",
+            ".tp",
+            ".f4v",
+        ]
     )
     # 支持的字幕文件后缀格式
-    RMT_SUBEXT: list = Field(default_factory=lambda: ['.srt', '.ass', '.ssa', '.sup'])
+    RMT_SUBEXT: list = Field(default_factory=lambda: [".srt", ".ass", ".ssa", ".sup"])
     # 支持的音轨文件后缀格式
     RMT_AUDIOEXT: list = Field(
-        default_factory=lambda: ['.aac', '.ac3', '.amr', '.caf', '.cda', '.dsf',
-                                 '.dff', '.kar', '.m4a', '.mp1', '.mp2', '.mp3',
-                                 '.mid', '.mod', '.mka', '.mpc', '.nsf', '.ogg',
-                                 '.pcm', '.rmi', '.s3m', '.snd', '.spx', '.tak',
-                                 '.tta', '.vqf', '.wav', '.wma',
-                                 '.aifc', '.aiff', '.alac', '.adif', '.adts',
-                                 '.flac', '.midi', '.opus', '.sfalc']
+        default_factory=lambda: [
+            ".aac",
+            ".ac3",
+            ".amr",
+            ".caf",
+            ".cda",
+            ".dsf",
+            ".dff",
+            ".kar",
+            ".m4a",
+            ".mp1",
+            ".mp2",
+            ".mp3",
+            ".mid",
+            ".mod",
+            ".mka",
+            ".mpc",
+            ".nsf",
+            ".ogg",
+            ".pcm",
+            ".rmi",
+            ".s3m",
+            ".snd",
+            ".spx",
+            ".tak",
+            ".tta",
+            ".vqf",
+            ".wav",
+            ".wma",
+            ".aifc",
+            ".aiff",
+            ".alac",
+            ".adif",
+            ".adts",
+            ".flac",
+            ".midi",
+            ".opus",
+            ".sfalc",
+        ]
     )
 
     # ==================== 媒体服务器配置 ====================
@@ -288,7 +338,7 @@ class ConfigModel(BaseModel):
     # 交互搜索自动下载用户ID，使用,分割
     AUTO_DOWNLOAD_USER: Optional[str] = None
     # 下载器临时文件后缀
-    DOWNLOAD_TMPEXT: list = Field(default_factory=lambda: ['.!qb', '.part'])
+    DOWNLOAD_TMPEXT: list = Field(default_factory=lambda: [".!qb", ".part"])
 
     # ==================== CookieCloud配置 ====================
     # CookieCloud是否启动本地服务
@@ -308,20 +358,26 @@ class ConfigModel(BaseModel):
     # 文件整理线程数
     TRANSFER_THREADS: int = 1
     # 电影重命名格式
-    MOVIE_RENAME_FORMAT: str = "{{title}}{% if year %} ({{year}}){% endif %}" \
-                               "/{{title}}{% if year %} ({{year}}){% endif %}{% if part %}-{{part}}{% endif %}{% if videoFormat %} - {{videoFormat}}{% endif %}" \
-                               "{{fileExt}}"
+    MOVIE_RENAME_FORMAT: str = (
+        "{{title}}{% if year %} ({{year}}){% endif %}"
+        "/{{title}}{% if year %} ({{year}}){% endif %}{% if part %}-{{part}}{% endif %}{% if videoFormat %} - {{videoFormat}}{% endif %}"
+        "{{fileExt}}"
+    )
     # 电视剧重命名格式
-    TV_RENAME_FORMAT: str = "{{title}}{% if year %} ({{year}}){% endif %}" \
-                            "/Season {{season}}" \
-                            "/{{title}} - {{season_episode}}{% if part %}-{{part}}{% endif %}{% if episode %} - 第 {{episode}} 集{% endif %}" \
-                            "{{fileExt}}"
+    TV_RENAME_FORMAT: str = (
+        "{{title}}{% if year %} ({{year}}){% endif %}"
+        "/Season {{season}}"
+        "/{{title}} - {{season_episode}}{% if part %}-{{part}}{% endif %}{% if episode %} - 第 {{episode}} 集{% endif %}"
+        "{{fileExt}}"
+    )
     # 重命名时支持的S0别名
     RENAME_FORMAT_S0_NAMES: list = Field(default=["Specials", "SPs"])
     # 为指定默认字幕添加.default后缀
     DEFAULT_SUB: Optional[str] = "zh-cn"
     # 新增已入库媒体是否跟随TMDB信息变化
     SCRAP_FOLLOW_TMDB: bool = True
+    # 优先使用辅助识别
+    RECOGNIZE_PLUGIN_FIRST: bool = False
 
     # ==================== 服务地址配置 ====================
     # 服务器地址，对应 https://github.com/jxxghp/MoviePilot-Server 项目
@@ -335,26 +391,28 @@ class ConfigModel(BaseModel):
 
     # ==================== 插件配置 ====================
     # 插件市场仓库地址，多个地址使用,分隔，地址以/结尾
-    PLUGIN_MARKET: str = ("https://github.com/jxxghp/MoviePilot-Plugins,"
-                          "https://github.com/thsrite/MoviePilot-Plugins,"
-                          "https://github.com/honue/MoviePilot-Plugins,"
-                          "https://github.com/InfinityPacer/MoviePilot-Plugins,"
-                          "https://github.com/DDSRem-Dev/MoviePilot-Plugins,"
-                          "https://github.com/madrays/MoviePilot-Plugins,"
-                          "https://github.com/justzerock/MoviePilot-Plugins,"
-                          "https://github.com/KoWming/MoviePilot-Plugins,"
-                          "https://github.com/wikrin/MoviePilot-Plugins,"
-                          "https://github.com/HankunYu/MoviePilot-Plugins,"
-                          "https://github.com/baozaodetudou/MoviePilot-Plugins,"
-                          "https://github.com/Aqr-K/MoviePilot-Plugins,"
-                          "https://github.com/hotlcc/MoviePilot-Plugins-Third,"
-                          "https://github.com/gxterry/MoviePilot-Plugins,"
-                          "https://github.com/DzAvril/MoviePilot-Plugins,"
-                          "https://github.com/mrtian2016/MoviePilot-Plugins,"
-                          "https://github.com/Hqyel/MoviePilot-Plugins-Third,"
-                          "https://github.com/xijin285/MoviePilot-Plugins,"
-                          "https://github.com/Seed680/MoviePilot-Plugins,"
-                          "https://github.com/imaliang/MoviePilot-Plugins")
+    PLUGIN_MARKET: str = (
+        "https://github.com/jxxghp/MoviePilot-Plugins,"
+        "https://github.com/thsrite/MoviePilot-Plugins,"
+        "https://github.com/honue/MoviePilot-Plugins,"
+        "https://github.com/InfinityPacer/MoviePilot-Plugins,"
+        "https://github.com/DDSRem-Dev/MoviePilot-Plugins,"
+        "https://github.com/madrays/MoviePilot-Plugins,"
+        "https://github.com/justzerock/MoviePilot-Plugins,"
+        "https://github.com/KoWming/MoviePilot-Plugins,"
+        "https://github.com/wikrin/MoviePilot-Plugins,"
+        "https://github.com/HankunYu/MoviePilot-Plugins,"
+        "https://github.com/baozaodetudou/MoviePilot-Plugins,"
+        "https://github.com/Aqr-K/MoviePilot-Plugins,"
+        "https://github.com/hotlcc/MoviePilot-Plugins-Third,"
+        "https://github.com/gxterry/MoviePilot-Plugins,"
+        "https://github.com/DzAvril/MoviePilot-Plugins,"
+        "https://github.com/mrtian2016/MoviePilot-Plugins,"
+        "https://github.com/Hqyel/MoviePilot-Plugins-Third,"
+        "https://github.com/xijin285/MoviePilot-Plugins,"
+        "https://github.com/Seed680/MoviePilot-Plugins,"
+        "https://github.com/imaliang/MoviePilot-Plugins"
+    )
     # 插件安装数据共享
     PLUGIN_STATISTIC_SHARE: bool = True
     # 是否开启插件热加载
@@ -364,9 +422,9 @@ class ConfigModel(BaseModel):
     # Github token，提高请求api限流阈值 ghp_****
     GITHUB_TOKEN: Optional[str] = None
     # Github代理服务器，格式：https://mirror.ghproxy.com/
-    GITHUB_PROXY: Optional[str] = ''
+    GITHUB_PROXY: Optional[str] = ""
     # pip镜像站点，格式：https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
-    PIP_PROXY: Optional[str] = ''
+    PIP_PROXY: Optional[str] = ""
     # 指定的仓库Github token，多个仓库使用,分隔，格式：{user1}/{repo1}:ghp_****,{user2}/{repo2}:github_pat_****
     REPO_GITHUB_TOKEN: Optional[str] = None
 
@@ -382,24 +440,28 @@ class ConfigModel(BaseModel):
 
     # ==================== 安全配置 ====================
     # 允许的图片缓存域名
-    SECURITY_IMAGE_DOMAINS: list = Field(default=[
-        "image.tmdb.org",
-        "static-mdb.v.geilijiasu.com",
-        "bing.com",
-        "doubanio.com",
-        "lain.bgm.tv",
-        "raw.githubusercontent.com",
-        "github.com",
-        "thetvdb.com",
-        "cctvpic.com",
-        "iqiyipic.com",
-        "hdslb.com",
-        "cmvideo.cn",
-        "ykimg.com",
-        "qpic.cn"
-    ])
+    SECURITY_IMAGE_DOMAINS: list = Field(
+        default=[
+            "image.tmdb.org",
+            "static-mdb.v.geilijiasu.com",
+            "bing.com",
+            "doubanio.com",
+            "lain.bgm.tv",
+            "raw.githubusercontent.com",
+            "github.com",
+            "thetvdb.com",
+            "cctvpic.com",
+            "iqiyipic.com",
+            "hdslb.com",
+            "cmvideo.cn",
+            "ykimg.com",
+            "qpic.cn",
+        ]
+    )
     # 允许的图片文件后缀格式
-    SECURITY_IMAGE_SUFFIXES: list = Field(default=[".jpg", ".jpeg", ".png", ".webp", ".gif", ".svg", ".avif"])
+    SECURITY_IMAGE_SUFFIXES: list = Field(
+        default=[".jpg", ".jpeg", ".png", ".webp", ".gif", ".svg", ".avif"]
+    )
     # PassKey 是否强制用户验证（生物识别等）
     PASSKEY_REQUIRE_UV: bool = True
     # 允许在未启用 OTP 时直接注册 PassKey
@@ -414,6 +476,8 @@ class ConfigModel(BaseModel):
     RCLONE_SNAPSHOT_CHECK_FOLDER_MODTIME: bool = True
     # 对OpenList进行快照对比时，是否检查文件夹的修改时间
     OPENLIST_SNAPSHOT_CHECK_FOLDER_MODTIME: bool = True
+    # 对阿里云盘进行快照对比时，是否检查文件夹的修改时间（默认关闭，因为阿里云盘目录时间不随子文件变更而更新）
+    ALIPAN_SNAPSHOT_CHECK_FOLDER_MODTIME: bool = False
 
     # ==================== Docker配置 ====================
     # Docker Client API地址
@@ -455,11 +519,18 @@ class ConfigModel(BaseModel):
     # AI推荐用户偏好
     AI_RECOMMEND_USER_PREFERENCE: str = ""
     # Tavily API密钥（用于网络搜索）
-    TAVILY_API_KEY: str = "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"
+    TAVILY_API_KEY: List[str] = [
+        "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",
+        "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",
+        "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",
+    ]
 
     # AI推荐条目数量限制
     AI_RECOMMEND_MAX_ITEMS: int = 50
-
+    # LLM工具选择中间件最大工具数量，0为不启用工具选择中间件
+    LLM_MAX_TOOLS: int = 0
+    # AI智能体定时任务检查间隔（小时），0为不启用，默认24小时
+    AI_AGENT_JOB_INTERVAL: int = 0
 
 
 class Settings(BaseSettings, ConfigModel, LogConfigModel):
@@ -496,15 +567,25 @@ class Settings(BaseSettings, ConfigModel, LogConfigModel):
         if not value or len(value) < 16:
             new_token = secrets.token_urlsafe(16)
             if not value:
-                logger.info(f"'API_TOKEN' 未设置，已随机生成新的【API_TOKEN】{new_token}")
+                logger.info(
+                    f"'API_TOKEN' 未设置，已随机生成新的【API_TOKEN】{new_token}"
+                )
             else:
-                logger.warning(f"'API_TOKEN' 长度不足 16 个字符，存在安全隐患，已随机生成新的【API_TOKEN】{new_token}")
+                logger.warning(
+                    f"'API_TOKEN' 长度不足 16 个字符，存在安全隐患，已随机生成新的【API_TOKEN】{new_token}"
+                )
             return new_token, True
         return value, str(value) != str(original_value)
 
     @staticmethod
-    def generic_type_converter(value: Any, original_value: Any, expected_type: Type, default: Any, field_name: str,
-                               raise_exception: bool = False) -> Tuple[Any, bool]:
+    def generic_type_converter(
+        value: Any,
+        original_value: Any,
+        expected_type: Type,
+        default: Any,
+        field_name: str,
+        raise_exception: bool = False,
+    ) -> Tuple[Any, bool]:
         """
         通用类型转换函数，根据预期类型转换值。如果转换失败，返回默认值
         :return: 元组 (转换后的值, 是否需要更新)
@@ -525,15 +606,25 @@ class Settings(BaseSettings, ConfigModel, LogConfigModel):
                 if isinstance(value, str):
                     value_clean = value.lower()
                     bool_map = {
-                        "false": False, "no": False, "0": False, "off": False,
-                        "true": True, "yes": True, "1": True, "on": True
+                        "false": False,
+                        "no": False,
+                        "0": False,
+                        "off": False,
+                        "true": True,
+                        "yes": True,
+                        "1": True,
+                        "on": True,
                     }
                     if value_clean in bool_map:
                         converted = bool_map[value_clean]
-                        return converted, str(converted).lower() != str(original_value).lower()
+                        return converted, str(converted).lower() != str(
+                            original_value
+                        ).lower()
                 elif isinstance(value, (int, float)):
                     converted = bool(value)
-                    return converted, str(converted).lower() != str(original_value).lower()
+                    return converted, str(converted).lower() != str(
+                        original_value
+                    ).lower()
                 return default, True
             elif expected_type is int:
                 if isinstance(value, int):
@@ -563,12 +654,15 @@ class Settings(BaseSettings, ConfigModel, LogConfigModel):
                 return value, str(value) != str(original_value)
         except (ValueError, TypeError) as e:
             if raise_exception:
-                raise ValueError(f"配置项 '{field_name}' 的值 '{value}' 无法转换成正确的类型") from e
+                raise ValueError(
+                    f"配置项 '{field_name}' 的值 '{value}' 无法转换成正确的类型"
+                ) from e
             logger.error(
-                f"配置项 '{field_name}' 的值 '{value}' 无法转换成正确的类型，使用默认值 '{default}'，错误信息: {e}")
+                f"配置项 '{field_name}' 的值 '{value}' 无法转换成正确的类型，使用默认值 '{default}'，错误信息: {e}"
+            )
         return default, True
 
-    @model_validator(mode='before')
+    @model_validator(mode="before")
     @classmethod
     def generic_type_validator(cls, data: Any):  # noqa
         """
@@ -578,11 +672,13 @@ class Settings(BaseSettings, ConfigModel, LogConfigModel):
             return data
 
         # 处理 API_TOKEN 特殊验证
-        if 'API_TOKEN' in data:
-            converted_value, needs_update = cls.validate_api_token(data['API_TOKEN'], data['API_TOKEN'])
+        if "API_TOKEN" in data:
+            converted_value, needs_update = cls.validate_api_token(
+                data["API_TOKEN"], data["API_TOKEN"]
+            )
             if needs_update:
                 cls.update_env_config("API_TOKEN", data["API_TOKEN"], converted_value)
-                data['API_TOKEN'] = converted_value
+                data["API_TOKEN"] = converted_value
 
         # 对其他字段进行类型转换
         for field_name, field_info in cls.model_fields.items():
@@ -604,18 +700,24 @@ class Settings(BaseSettings, ConfigModel, LogConfigModel):
         return data
 
     @staticmethod
-    def update_env_config(field_name: str, original_value: Any, converted_value: Any) -> Tuple[bool, str]:
+    def update_env_config(
+        field_name: str, original_value: Any, converted_value: Any
+    ) -> Tuple[bool, str]:
         """
         更新 env 配置
         """
         message = None
-        is_converted = original_value is not None and str(original_value) != str(converted_value)
+        is_converted = original_value is not None and str(original_value) != str(
+            converted_value
+        )
         if is_converted:
             message = f"配置项 '{field_name}' 的值 '{original_value}' 无效，已替换为 '{converted_value}'"
             logger.warning(message)
 
         if field_name in os.environ:
-            message = f"配置项 '{field_name}' 已在环境变量中设置，请手动更新以保持一致性"
+            message = (
+                f"配置项 '{field_name}' 已在环境变量中设置，请手动更新以保持一致性"
+            )
             logger.warning(message)
             return False, message
         else:
@@ -623,10 +725,16 @@ class Settings(BaseSettings, ConfigModel, LogConfigModel):
             if isinstance(converted_value, (list, dict, set)):
                 value_to_write = json.dumps(converted_value)
             else:
-                value_to_write = str(converted_value) if converted_value is not None else ""
+                value_to_write = (
+                    str(converted_value) if converted_value is not None else ""
+                )
 
-            set_key(dotenv_path=SystemUtils.get_env_path(), key_to_set=field_name, value_to_set=value_to_write,
-                    quote_mode="always")
+            set_key(
+                dotenv_path=SystemUtils.get_env_path(),
+                key_to_set=field_name,
+                value_to_set=value_to_write,
+                quote_mode="always",
+            )
             if is_converted:
                 logger.info(f"配置项 '{field_name}' 已自动修正并写入到 'app.env' 文件")
         return True, message
@@ -645,7 +753,9 @@ class Settings(BaseSettings, ConfigModel, LogConfigModel):
             field = Settings.model_fields[key]
             original_value = getattr(self, key)
             if key == "API_TOKEN":
-                converted_value, needs_update = self.validate_api_token(value, original_value)
+                converted_value, needs_update = self.validate_api_token(
+                    value, original_value
+                )
             else:
                 converted_value, needs_update = self.generic_type_converter(
                     value, original_value, field.annotation, field.default, key
@@ -663,7 +773,9 @@ class Settings(BaseSettings, ConfigModel, LogConfigModel):
         except Exception as e:
             return False, str(e)
 
-    def update_settings(self, env: Dict[str, Any]) -> Dict[str, Tuple[Optional[bool], str]]:
+    def update_settings(
+        self, env: Dict[str, Any]
+    ) -> Dict[str, Tuple[Optional[bool], str]]:
         """
         更新多个配置项
         """
@@ -746,7 +858,7 @@ class Settings(BaseSettings, ConfigModel, LogConfigModel):
                 fanart=512,
                 meta=(self.META_CACHE_EXPIRE or 72) * 3600,
                 scheduler=100,
-                threadpool=100
+                threadpool=100,
             )
         return SystemConfModel(
             torrents=100,
@@ -757,7 +869,7 @@ class Settings(BaseSettings, ConfigModel, LogConfigModel):
             fanart=128,
             meta=(self.META_CACHE_EXPIRE or 24) * 3600,
             scheduler=50,
-            threadpool=50
+            threadpool=50,
         )
 
     @property
@@ -839,7 +951,7 @@ class Settings(BaseSettings, ConfigModel, LogConfigModel):
         return {
             "subject": f"mailto:{self.SUPERUSER}@movie-pilot.org",
             "publicKey": "BH3w49sZA6jXUnE-yt4jO6VKh73lsdsvwoJ6Hx7fmPIDKoqGiUl2GEoZzy-iJfn4SfQQcx7yQdHf9RknwrL_lSM",
-            "privateKey": "JTixnYY0vEw97t9uukfO3UWKfHKJdT5kCQDiv3gu894"
+            "privateKey": "JTixnYY0vEw97t9uukfO3UWKfHKJdT5kCQDiv3gu894",
         }
 
     def MP_DOMAIN(self, url: str = None):
@@ -861,7 +973,7 @@ class Settings(BaseSettings, ConfigModel, LogConfigModel):
         )
         # 规范重命名格式
         rename_format = rename_format.replace("\\", "/")
-        rename_format = re.sub(r'/+', '/', rename_format)
+        rename_format = re.sub(r"/+", "/", rename_format)
         return rename_format.strip("/")
 
     def TMDB_IMAGE_URL(
@@ -876,9 +988,7 @@ class Settings(BaseSettings, ConfigModel, LogConfigModel):
         """
         if not file_path:
             return None
-        return (
-            f"https://{self.TMDB_IMAGE_DOMAIN}/t/p/{file_size}/{file_path.removeprefix('/')}"
-        )
+        return f"https://{self.TMDB_IMAGE_DOMAIN}/t/p/{file_size}/{file_path.removeprefix('/')}"
 
 
 # 实例化配置
@@ -889,6 +999,7 @@ class GlobalVar(object):
     """
     全局标识
     """
+
     # 系统停止事件
     STOP_EVENT: threading.Event = threading.Event()
     # webpush订阅

app/core/meta/infopath.py

@@ -0,0 +1,41 @@
+import regex as re
+
+from app.core.meta.metabase import MetaBase
+from app.utils.string import StringUtils
+
+AUXILIARY_CN_STEM_FULLMATCH_RE = re.compile(
+    r"^(双语|字幕|特效|内封|外挂|官译|简体|繁体|繁中|简中|中英|简英|多语|"
+    r"国英|台粤|音轨|评论|国配|台配|粤语|韩语|日语|杜比|全景声|无损|中字|"
+    r"国语|原声)+$"
+)
+
+
+def should_use_parent_title_for_file_stem(
+    stem: str, parent_dir_name: str, file_meta: MetaBase
+) -> bool:
+    """
+    文件名（无后缀）是否仅为简繁体/字幕/特效等辅助说明，应改用父目录标题识别。
+    要求：
+    - stem 纯中文且能被辅助关键词完全覆盖（无残留有意义汉字）
+    - 父目录含拉丁字母，避免纯中文资源目录误把正片中文名当标签清空
+    """
+    if not file_meta.isfile or not stem or not parent_dir_name:
+        return False
+    if file_meta.tmdbid or file_meta.doubanid:
+        return False
+    if not re.search(r"[A-Za-z]{2,}", parent_dir_name):
+        return False
+    if not StringUtils.is_all_chinese(stem):
+        return False
+    if len(stem) > 16:
+        return False
+    if not AUXILIARY_CN_STEM_FULLMATCH_RE.match(stem):
+        return False
+    if re.search(r"[第共]\s*[0-9一二三四五六七八九十百零]+\s*[季集话話]", stem):
+        return False
+    return True
+
+
+def clear_parsed_title_for_parent_merge(meta: MetaBase) -> None:
+    meta.cn_name = None
+    meta.en_name = None

app/core/meta/metaanime.py

@@ -17,6 +17,7 @@ class MetaAnime(MetaBase):
     """
     _anime_no_words = ['CHS&CHT', 'MP4', 'GB MP4', 'WEB-DL']
     _name_nostring_re = r"S\d{2}\s*-\s*S\d{2}|S\d{2}|\s+S\d{1,2}|EP?\d{2,4}\s*-\s*EP?\d{2,4}|EP?\d{2,4}|\s+EP?\d{1,4}|\s+GB"
+    _fps_re = r"(\d{2,3})(?=FPS)"
 
     def __init__(self, title: str, subtitle: str = None, isfile: bool = False):
         super().__init__(title, subtitle, isfile)
@@ -173,6 +174,8 @@ class MetaAnime(MetaBase):
                 self.audio_encode = anitopy_info.get("audio_term")
                 if isinstance(self.audio_encode, list):
                     self.audio_encode = self.audio_encode[0]
+                # 帧率信息
+                self.__init_anime_fps(anitopy_info, original_title)
                 # 解析副标题，只要季和集
                 self.init_subtitle(self.org_string)
                 if not self._subtitle_flag and self.subtitle:
@@ -182,6 +185,20 @@ class MetaAnime(MetaBase):
         except Exception as e:
             logger.error(f"解析动漫信息失败：{str(e)} - {traceback.format_exc()}")
 
+    def __init_anime_fps(self, anitopy_info: dict, original_title: str):
+        """
+        从原始标题中提取帧率信息，与MetaVideo保持完全一致的实现
+        """
+        re_res = re.search(rf"({self._fps_re})", original_title, re.IGNORECASE)
+        if re_res:
+            fps_value = None
+            if re_res.group(1):  # FPS格式
+                fps_value = re_res.group(1)
+                    
+            if fps_value and fps_value.isdigit():
+                # 只存储纯数值
+                self.fps = int(fps_value)
+
     @staticmethod
     def __prepare_title(title: str):
         """

app/core/meta/metabase.py

@@ -66,6 +66,9 @@ class MetaBase(object):
     # 附加信息
     tmdbid: int = None
     doubanid: str = None
+    # 帧率信息（纯数值）
+    fps: Optional[int] = None
+
 
     # 副标题解析
     _subtitle_flag = False
@@ -448,6 +451,13 @@ class MetaBase(object):
         """
         return self.audio_encode or ""
 
+    @property
+    def frame_rate(self) -> int:
+        """
+        返回帧率信息
+        """
+        return self.fps or None
+
     def is_in_season(self, season: Union[list, int, str]) -> bool:
         """
         是否包含季
@@ -581,6 +591,9 @@ class MetaBase(object):
         # 音频编码
         if not self.audio_encode:
             self.audio_encode = meta.audio_encode
+        # 帧率信息
+        if not self.fps:
+            self.fps = meta.fps
         # Part
         if not self.part:
             self.part = meta.part

app/core/meta/metavideo.py

@@ -53,7 +53,7 @@ class MetaVideo(MetaBase):
     _resources_pix_re2 = r"(^[248]+K)"
     _video_encode_re = r"^(H26[45])$|^(x26[45])$|^AVC$|^HEVC$|^VC\d?$|^MPEG\d?$|^Xvid$|^DivX$|^AV1$|^HDR\d*$|^AVS(\+|[23])$"
     _audio_encode_re = r"^DTS\d?$|^DTSHD$|^DTSHDMA$|^Atmos$|^TrueHD\d?$|^AC3$|^\dAudios?$|^DDP\d?$|^DD\+\d?$|^DD\d?$|^LPCM\d?$|^AAC\d?$|^FLAC\d?$|^HD\d?$|^MA\d?$|^HR\d?$|^Opus\d?$|^Vorbis\d?$|^AV[3S]A$"
-
+    _fps_re = r"(\d{2,3})(?=FPS)"
     def __init__(self, title: str, subtitle: str = None, isfile: bool = False):
         """
         初始化
@@ -76,7 +76,7 @@ class MetaVideo(MetaBase):
             self.type = MediaType.TV
             return
         # 全名为Season xx 及 Sxx 直接返回
-        season_full_res = re.search(r"^Season\s+(\d{1,3})$|^S(\d{1,3})$", title)
+        season_full_res = re.search(r"^(?:Season\s+|S)(\d{1,3})$", title, re.IGNORECASE)
         if season_full_res:
             self.type = MediaType.TV
             season = season_full_res.group(1)
@@ -129,6 +129,9 @@ class MetaVideo(MetaBase):
             # 音频编码
             if self._continue_flag:
                 self.__init_audio_encode(token)
+            # 帧率
+            if self._continue_flag:
+                self.__init_fps(token)
             # 取下一个，直到没有为卡
             token = tokens.get_next()
             self._continue_flag = True
@@ -716,3 +719,25 @@ class MetaVideo(MetaBase):
                 else:
                     self.audio_encode = "%s %s" % (self.audio_encode, token)
             self._last_token = token
+
+    def __init_fps(self, token: str):
+        """
+        识别帧率
+        """
+        if not self.name:
+            return
+
+        re_res = re.search(rf"({self._fps_re})", token, re.IGNORECASE)
+        if re_res:
+            self._continue_flag = False
+            self._stop_name_flag = True
+            self._last_token_type = "fps"
+            # 提取帧率数值
+            fps_value = None
+            if re_res.group(1):  # FPS格式
+                fps_value = re_res.group(1)
+            
+            if fps_value and fps_value.isdigit():
+                # 只存储纯数值
+                self.fps = int(fps_value)
+                self._last_token = f"{self.fps}FPS"

app/core/meta/releasegroup.py

@@ -52,6 +52,7 @@ class ReleaseGroupsMatcher(metaclass=Singleton):
         "nicept": [],
         "oshen": [],
         "ourbits": ['Our(?:Bits|TV)', 'FLTTH', 'Ao', 'PbK', 'MGs', 'iLove(?:HD|TV)'],
+        "panda": ['Panda', 'AilMWeb'],
         "piggo": ['PiGo(?:NF|(?:H|WE)B)'],
         "ptchina": [],
         "pterclub": ['PTer(?:DIY|Game|(?:M|T)V|WEB|)'],
@@ -105,7 +106,7 @@ class ReleaseGroupsMatcher(metaclass=Singleton):
             else:
                 groups = self.__release_groups
         title = f"{title} "
-        groups_re = re.compile(r"(?<=[-@\[￡【&])(?:(?:%s))(?=[@.\s\S\]\[】&])" % groups, re.I)
+        groups_re = re.compile(r"(?<=[-@\[￡【&])(?:(?:%s))(?=$|[@.\s\]\[】&])" % groups, re.I)
         unique_groups = []
         for item in re.findall(groups_re, title):
             item_str = item[0] if isinstance(item, tuple) else item

app/core/metainfo.py

@@ -5,6 +5,10 @@ import regex as re
 
 from app.core.config import settings
 from app.core.meta import MetaAnime, MetaVideo, MetaBase
+from app.core.meta.infopath import (
+    clear_parsed_title_for_parent_merge,
+    should_use_parent_title_for_file_stem,
+)
 from app.core.meta.words import WordsMatcher
 from app.log import logger
 from app.schemas.types import MediaType
@@ -71,6 +75,8 @@ def MetaInfoPath(path: Path, custom_words: List[str] = None) -> MetaBase:
     """
     # 文件元数据，不包含后缀
     file_meta = MetaInfo(title=path.name, custom_words=custom_words)
+    if should_use_parent_title_for_file_stem(path.stem, path.parent.name, file_meta):
+        clear_parsed_title_for_parent_merge(file_meta)
     # 上级目录元数据
     dir_meta = MetaInfo(title=path.parent.name, custom_words=custom_words)
     if file_meta.type == MediaType.TV or dir_meta.type != MediaType.TV:

app/core/plugin.py

@@ -5,6 +5,7 @@ import concurrent.futures
 import importlib.util
 import inspect
 import os
+import posixpath
 import sys
 import threading
 import time
@@ -775,11 +776,17 @@ class PluginManager(ConfigReloadMixin, metaclass=Singleton):
         :param dist_path: 插件的分发路径
         :return: 远程入口地址
         """
-        if dist_path.startswith("/"):
-            dist_path = dist_path[1:]
-        if dist_path.endswith("/"):
-            dist_path = dist_path[:-1]
-        return f"/plugin/file/{plugin_id.lower()}/{dist_path}/remoteEntry.js"
+        dist_path = dist_path.strip("/")
+        path = posixpath.join(
+            "plugin",
+            "file",
+            plugin_id.lower(),
+            dist_path,
+            "remoteEntry.js",
+        )
+        if not path.startswith("/"):
+            path = "/" + path
+        return path
 
     def get_plugin_remotes(self, pid: Optional[str] = None) -> List[Dict[str, Any]]:
         """

app/db/models/downloadhistory.py

@@ -12,6 +12,7 @@ class DownloadHistory(Base):
     """
     下载历史记录
     """
+
     id = get_id_column()
     # 保存路径
     path = Column(String, nullable=False, index=True)
@@ -61,32 +62,73 @@ class DownloadHistory(Base):
     @classmethod
     @db_query
     def get_by_hash(cls, db: Session, download_hash: str):
-        return db.query(DownloadHistory).filter(DownloadHistory.download_hash == download_hash).order_by(
-            DownloadHistory.date.desc()
-        ).first()
+        return (
+            db.query(DownloadHistory)
+            .filter(DownloadHistory.download_hash == download_hash)
+            .order_by(DownloadHistory.date.desc())
+            .first()
+        )
 
     @classmethod
     @db_query
     def get_by_mediaid(cls, db: Session, tmdbid: int, doubanid: str):
         if tmdbid:
-            return db.query(DownloadHistory).filter(DownloadHistory.tmdbid == tmdbid).all()
+            return (
+                db.query(DownloadHistory).filter(DownloadHistory.tmdbid == tmdbid).all()
+            )
         elif doubanid:
-            return db.query(DownloadHistory).filter(DownloadHistory.doubanid == doubanid).all()
+            return (
+                db.query(DownloadHistory)
+                .filter(DownloadHistory.doubanid == doubanid)
+                .all()
+            )
         return []
 
     @classmethod
     @db_query
-    def list_by_page(cls, db: Session, page: Optional[int] = 1, count: Optional[int] = 30):
+    def list_by_page(
+        cls, db: Session, page: Optional[int] = 1, count: Optional[int] = 30
+    ):
         return db.query(DownloadHistory).offset((page - 1) * count).limit(count).all()
 
     @classmethod
     @async_db_query
-    async def async_list_by_page(cls, db: AsyncSession, page: Optional[int] = 1, count: Optional[int] = 30):
-        result = await db.execute(
-            select(cls).offset((page - 1) * count).limit(count)
-        )
+    async def async_list_by_page(
+        cls, db: AsyncSession, page: Optional[int] = 1, count: Optional[int] = 30
+    ):
+        result = await db.execute(select(cls).offset((page - 1) * count).limit(count))
         return result.scalars().all()
 
+    @classmethod
+    @async_db_query
+    async def async_list_by_title(
+        cls,
+        db: AsyncSession,
+        title: str,
+        page: Optional[int] = 1,
+        count: Optional[int] = 30,
+    ):
+        query = (
+            select(cls).filter(cls.title.like(f"%{title}%")).order_by(cls.date.desc())
+        )
+        query = query.offset((page - 1) * count).limit(count)
+        result = await db.execute(query)
+        return result.scalars().all()
+
+    @classmethod
+    @async_db_query
+    async def async_count(cls, db: AsyncSession):
+        result = await db.execute(select(func.count(cls.id)))
+        return result.scalar()
+
+    @classmethod
+    @async_db_query
+    async def async_count_by_title(cls, db: AsyncSession, title: str):
+        result = await db.execute(
+            select(func.count(cls.id)).filter(cls.title.like(f"%{title}%"))
+        )
+        return result.scalar()
+
     @classmethod
     @db_query
     def get_by_path(cls, db: Session, path: str):
@@ -94,9 +136,16 @@ class DownloadHistory(Base):
 
     @classmethod
     @db_query
-    def get_last_by(cls, db: Session, mtype: Optional[str] = None, title: Optional[str] = None,
-                    year: Optional[str] = None, season: Optional[str] = None,
-                    episode: Optional[str] = None, tmdbid: Optional[int] = None):
+    def get_last_by(
+        cls,
+        db: Session,
+        mtype: Optional[str] = None,
+        title: Optional[str] = None,
+        year: Optional[str] = None,
+        season: Optional[str] = None,
+        episode: Optional[str] = None,
+        tmdbid: Optional[int] = None,
+    ):
         """
         据tmdbid、season、season_episode查询下载记录
         tmdbid + mtype 或 title + year
@@ -105,42 +154,76 @@ class DownloadHistory(Base):
         if tmdbid and mtype:
             # 电视剧某季某集
             if season is not None and episode:
-                return db.query(DownloadHistory).filter(DownloadHistory.tmdbid == tmdbid,
-                                                        DownloadHistory.type == mtype,
-                                                        DownloadHistory.seasons == season,
-                                                        DownloadHistory.episodes == episode).order_by(
-                    DownloadHistory.id.desc()).all()
+                return (
+                    db.query(DownloadHistory)
+                    .filter(
+                        DownloadHistory.tmdbid == tmdbid,
+                        DownloadHistory.type == mtype,
+                        DownloadHistory.seasons == season,
+                        DownloadHistory.episodes == episode,
+                    )
+                    .order_by(DownloadHistory.id.desc())
+                    .all()
+                )
             # 电视剧某季
             elif season is not None:
-                return db.query(DownloadHistory).filter(DownloadHistory.tmdbid == tmdbid,
-                                                        DownloadHistory.type == mtype,
-                                                        DownloadHistory.seasons == season).order_by(
-                    DownloadHistory.id.desc()).all()
+                return (
+                    db.query(DownloadHistory)
+                    .filter(
+                        DownloadHistory.tmdbid == tmdbid,
+                        DownloadHistory.type == mtype,
+                        DownloadHistory.seasons == season,
+                    )
+                    .order_by(DownloadHistory.id.desc())
+                    .all()
+                )
             else:
                 # 电视剧所有季集/电影
-                return db.query(DownloadHistory).filter(DownloadHistory.tmdbid == tmdbid,
-                                                        DownloadHistory.type == mtype).order_by(
-                    DownloadHistory.id.desc()).all()
+                return (
+                    db.query(DownloadHistory)
+                    .filter(
+                        DownloadHistory.tmdbid == tmdbid, DownloadHistory.type == mtype
+                    )
+                    .order_by(DownloadHistory.id.desc())
+                    .all()
+                )
         # 标题 + 年份
         elif title and year:
             # 电视剧某季某集
             if season is not None and episode:
-                return db.query(DownloadHistory).filter(DownloadHistory.title == title,
-                                                        DownloadHistory.year == year,
-                                                        DownloadHistory.seasons == season,
-                                                        DownloadHistory.episodes == episode).order_by(
-                    DownloadHistory.id.desc()).all()
+                return (
+                    db.query(DownloadHistory)
+                    .filter(
+                        DownloadHistory.title == title,
+                        DownloadHistory.year == year,
+                        DownloadHistory.seasons == season,
+                        DownloadHistory.episodes == episode,
+                    )
+                    .order_by(DownloadHistory.id.desc())
+                    .all()
+                )
             # 电视剧某季
             elif season is not None:
-                return db.query(DownloadHistory).filter(DownloadHistory.title == title,
-                                                        DownloadHistory.year == year,
-                                                        DownloadHistory.seasons == season).order_by(
-                    DownloadHistory.id.desc()).all()
+                return (
+                    db.query(DownloadHistory)
+                    .filter(
+                        DownloadHistory.title == title,
+                        DownloadHistory.year == year,
+                        DownloadHistory.seasons == season,
+                    )
+                    .order_by(DownloadHistory.id.desc())
+                    .all()
+                )
             else:
                 # 电视剧所有季集/电影
-                return db.query(DownloadHistory).filter(DownloadHistory.title == title,
-                                                        DownloadHistory.year == year).order_by(
-                    DownloadHistory.id.desc()).all()
+                return (
+                    db.query(DownloadHistory)
+                    .filter(
+                        DownloadHistory.title == title, DownloadHistory.year == year
+                    )
+                    .order_by(DownloadHistory.id.desc())
+                    .all()
+                )
 
         return []
 
@@ -151,45 +234,80 @@ class DownloadHistory(Base):
         查询某用户某时间之后的下载历史
         """
         if username:
-            return db.query(DownloadHistory).filter(DownloadHistory.date < date,
-                                                    DownloadHistory.username == username).order_by(
-                DownloadHistory.id.desc()).all()
+            return (
+                db.query(DownloadHistory)
+                .filter(
+                    DownloadHistory.date < date, DownloadHistory.username == username
+                )
+                .order_by(DownloadHistory.id.desc())
+                .all()
+            )
         else:
-            return db.query(DownloadHistory).filter(DownloadHistory.date < date).order_by(
-                DownloadHistory.id.desc()).all()
+            return (
+                db.query(DownloadHistory)
+                .filter(DownloadHistory.date < date)
+                .order_by(DownloadHistory.id.desc())
+                .all()
+            )
 
     @classmethod
     @db_query
-    def list_by_date(cls, db: Session, date: str, type: str, tmdbid: str, seasons: Optional[str] = None):
+    def list_by_date(
+        cls,
+        db: Session,
+        date: str,
+        type: str,
+        tmdbid: str,
+        seasons: Optional[str] = None,
+    ):
         """
         查询某时间之后的下载历史
         """
         if seasons:
-            return db.query(DownloadHistory).filter(DownloadHistory.date > date,
-                                                    DownloadHistory.type == type,
-                                                    DownloadHistory.tmdbid == tmdbid,
-                                                    DownloadHistory.seasons == seasons).order_by(
-                DownloadHistory.id.desc()).all()
+            return (
+                db.query(DownloadHistory)
+                .filter(
+                    DownloadHistory.date > date,
+                    DownloadHistory.type == type,
+                    DownloadHistory.tmdbid == tmdbid,
+                    DownloadHistory.seasons == seasons,
+                )
+                .order_by(DownloadHistory.id.desc())
+                .all()
+            )
         else:
-            return db.query(DownloadHistory).filter(DownloadHistory.date > date,
-                                                    DownloadHistory.type == type,
-                                                    DownloadHistory.tmdbid == tmdbid).order_by(
-                DownloadHistory.id.desc()).all()
+            return (
+                db.query(DownloadHistory)
+                .filter(
+                    DownloadHistory.date > date,
+                    DownloadHistory.type == type,
+                    DownloadHistory.tmdbid == tmdbid,
+                )
+                .order_by(DownloadHistory.id.desc())
+                .all()
+            )
 
     @classmethod
     @db_query
     def list_by_type(cls, db: Session, mtype: str, days: int):
-        return db.query(DownloadHistory) \
-            .filter(DownloadHistory.type == mtype,
-                    DownloadHistory.date >= time.strftime("%Y-%m-%d %H:%M:%S",
-                                                          time.localtime(time.time() - 86400 * int(days)))
-                    ).all()
+        return (
+            db.query(DownloadHistory)
+            .filter(
+                DownloadHistory.type == mtype,
+                DownloadHistory.date
+                >= time.strftime(
+                    "%Y-%m-%d %H:%M:%S", time.localtime(time.time() - 86400 * int(days))
+                ),
+            )
+            .all()
+        )
 
 
 class DownloadFiles(Base):
     """
     下载文件记录
     """
+
     id = get_id_column()
     # 下载器
     downloader = Column(String)
@@ -210,8 +328,11 @@ class DownloadFiles(Base):
     @db_query
     def get_by_hash(cls, db: Session, download_hash: str, state: Optional[int] = None):
         if state is not None:
-            return db.query(cls).filter(cls.download_hash == download_hash,
-                                        cls.state == state).all()
+            return (
+                db.query(cls)
+                .filter(cls.download_hash == download_hash, cls.state == state)
+                .all()
+            )
         else:
             return db.query(cls).filter(cls.download_hash == download_hash).all()
 
@@ -219,11 +340,19 @@ class DownloadFiles(Base):
     @db_query
     def get_by_fullpath(cls, db: Session, fullpath: str, all_files: bool = False):
         if not all_files:
-            return db.query(cls).filter(cls.fullpath == fullpath).order_by(
-                cls.id.desc()).first()
+            return (
+                db.query(cls)
+                .filter(cls.fullpath == fullpath)
+                .order_by(cls.id.desc())
+                .first()
+            )
         else:
-            return db.query(cls).filter(cls.fullpath == fullpath).order_by(
-                cls.id.desc()).all()
+            return (
+                db.query(cls)
+                .filter(cls.fullpath == fullpath)
+                .order_by(cls.id.desc())
+                .all()
+            )
 
     @classmethod
     @db_query
@@ -233,9 +362,6 @@ class DownloadFiles(Base):
     @classmethod
     @db_update
     def delete_by_fullpath(cls, db: Session, fullpath: str):
-        db.query(cls).filter(cls.fullpath == fullpath,
-                             cls.state == 1).update(
-            {
-                "state": 0
-            }
+        db.query(cls).filter(cls.fullpath == fullpath, cls.state == 1).update(
+            {"state": 0}
         )

app/helper/directory.py

@@ -151,8 +151,9 @@ class DirectoryHelper:
             if not matchs:
                 continue
             # 处理特例，有的人重命名的第一层是年份、分辨率
-            if any("title" in m for m in matchs):
-                # 找出最后一层含有标题参数的目录作为媒体根目录
+            if (any("title" in m for m in matchs)
+                and not any("season" in m for m in matchs)):
+                # 找出最后一层含有标题且不含季参数的目录作为媒体根目录
                 rename_format_level = level
                 break
         else:

app/helper/llm.py

@@ -1,5 +1,6 @@
 """LLM模型相关辅助功能"""
-from typing import List, Optional
+
+from typing import List
 
 from app.core.config import settings
 from app.log import logger
@@ -9,11 +10,10 @@ class LLMHelper:
     """LLM模型相关辅助功能"""
 
     @staticmethod
-    def get_llm(streaming: bool = False, callbacks: Optional[list] = None):
+    def get_llm(streaming: bool = False):
         """
         获取LLM实例
         :param streaming: 是否启用流式输出
-        :param callbacks: 回调处理器列表
         :return: LLM实例
         """
         provider = settings.LLM_PROVIDER.lower()
@@ -24,54 +24,68 @@ class LLMHelper:
 
         if provider == "google":
             if settings.PROXY_HOST:
+                # 通过代理使用 Google 的 OpenAI 兼容接口
                 from langchain_openai import ChatOpenAI
-                return ChatOpenAI(
+
+                model = ChatOpenAI(
                     model=settings.LLM_MODEL,
                     api_key=api_key,
                     max_retries=3,
                     base_url="https://generativelanguage.googleapis.com/v1beta/openai",
                     temperature=settings.LLM_TEMPERATURE,
                     streaming=streaming,
-                    callbacks=callbacks,
                     stream_usage=True,
-                    openai_proxy=settings.PROXY_HOST
+                    openai_proxy=settings.PROXY_HOST,
                 )
             else:
+                # 使用 langchain-google-genai 原生接口（v4 API 变更：google_api_key → api_key，max_retries → retries）
                 from langchain_google_genai import ChatGoogleGenerativeAI
-                return ChatGoogleGenerativeAI(
+
+                model = ChatGoogleGenerativeAI(
                     model=settings.LLM_MODEL,
-                    google_api_key=api_key,
-                    max_retries=3,
+                    api_key=api_key,
+                    retries=3,
                     temperature=settings.LLM_TEMPERATURE,
-                    streaming=streaming,
-                    callbacks=callbacks
+                    streaming=streaming
                 )
         elif provider == "deepseek":
             from langchain_deepseek import ChatDeepSeek
-            return ChatDeepSeek(
+
+            model = ChatDeepSeek(
                 model=settings.LLM_MODEL,
                 api_key=api_key,
                 max_retries=3,
                 temperature=settings.LLM_TEMPERATURE,
                 streaming=streaming,
-                callbacks=callbacks,
-                stream_usage=True
+                stream_usage=True,
             )
         else:
             from langchain_openai import ChatOpenAI
-            return ChatOpenAI(
+
+            model = ChatOpenAI(
                 model=settings.LLM_MODEL,
                 api_key=api_key,
                 max_retries=3,
                 base_url=settings.LLM_BASE_URL,
                 temperature=settings.LLM_TEMPERATURE,
                 streaming=streaming,
-                callbacks=callbacks,
                 stream_usage=True,
-                openai_proxy=settings.PROXY_HOST
+                openai_proxy=settings.PROXY_HOST,
             )
 
-    def get_models(self, provider: str, api_key: str, base_url: str = None) -> List[str]:
+        # 检查是否有profile
+        if hasattr(model, "profile") and model.profile:
+            logger.info(f"使用LLM模型: {model.model}，Profile: {model.profile}")
+        else:
+            model.profile = {
+                "max_input_tokens": settings.LLM_MAX_CONTEXT_TOKENS * 1000,  # 转换为token单位
+            }
+
+        return model
+
+    def get_models(
+            self, provider: str, api_key: str, base_url: str = None
+    ) -> List[str]:
         """获取模型列表"""
         logger.info(f"获取 {provider} 模型列表...")
         if provider == "google":
@@ -81,18 +95,25 @@ class LLMHelper:
 
     @staticmethod
     def _get_google_models(api_key: str) -> List[str]:
-        """获取Google模型列表"""
+        """获取Google模型列表（使用 google-genai SDK v1）"""
         try:
-            import google.generativeai as genai
-            genai.configure(api_key=api_key)
-            models = genai.list_models()
-            return [m.name for m in models if 'generateContent' in m.supported_generation_methods]
+            from google import genai
+
+            client = genai.Client(api_key=api_key)
+            models = client.models.list()
+            return [
+                m.name
+                for m in models
+                if m.supported_actions and "generateContent" in m.supported_actions
+            ]
         except Exception as e:
             logger.error(f"获取Google模型列表失败：{e}")
             raise e
 
     @staticmethod
-    def _get_openai_compatible_models(provider: str, api_key: str, base_url: str = None) -> List[str]:
+    def _get_openai_compatible_models(
+            provider: str, api_key: str, base_url: str = None
+    ) -> List[str]:
         """获取OpenAI兼容模型列表"""
         try:
             from openai import OpenAI

app/helper/message.py

@@ -164,6 +164,8 @@ class TemplateContextBuilder:
             "part": meta.part,
             # 自定义占位符
             "customization": meta.customization,
+            # fps
+            "fps": meta.fps,
         }
 
         tech_metadata = {

app/helper/passkey.py

@@ -22,7 +22,6 @@ from webauthn.helpers.structs import (
     PublicKeyCredentialDescriptor,
     AuthenticatorTransport,
     UserVerificationRequirement,
-    AuthenticatorAttachment,
     ResidentKeyRequirement,
     AuthenticatorSelectionCriteria
 )

app/helper/plugin.py

@@ -13,9 +13,10 @@ import aiofiles
 import aioshutil
 import httpx
 from anyio import Path as AsyncPath
+from packaging.requirements import Requirement
 from packaging.specifiers import SpecifierSet, InvalidSpecifier
 from packaging.version import Version, InvalidVersion
-from pkg_resources import Requirement, working_set
+from importlib.metadata import distributions
 from requests import Response
 
 from app.core.cache import cached
@@ -729,18 +730,26 @@ class PluginHelper(metaclass=WeakSingleton):
     def __get_installed_packages(self) -> Dict[str, Version]:
         """
         获取已安装的包及其版本
-        使用 pkg_resources 获取当前环境中已安装的包，标准化包名并转换版本信息
+        使用 importlib.metadata 获取当前环境中已安装的包，标准化包名并转换版本信息
         对于无法解析的版本，记录警告日志并跳过
         :return: 已安装包的字典，格式为 {package_name: Version}
         """
         installed_packages = {}
         try:
-            for dist in working_set:
-                pkg_name = self.__standardize_pkg_name(dist.project_name)
+            for dist in distributions():
+                name = dist.metadata.get("Name")
+                if not name:
+                    continue
+                pkg_name = self.__standardize_pkg_name(name)
+                version_str = dist.metadata.get("Version") or getattr(dist, "version", None)
+                if not version_str:
+                    continue
                 try:
-                    installed_packages[pkg_name] = Version(dist.version)
+                    v = Version(version_str)
+                    if pkg_name not in installed_packages or v > installed_packages[pkg_name]:
+                        installed_packages[pkg_name] = v
                 except InvalidVersion:
-                    logger.debug(f"无法解析已安装包 '{pkg_name}' 的版本：{dist.version}")
+                    logger.debug(f"无法解析已安装包 '{pkg_name}' 的版本：{version_str}")
                     continue
             return installed_packages
         except Exception as e:
@@ -844,12 +853,14 @@ class PluginHelper(metaclass=WeakSingleton):
     @staticmethod
     def __standardize_pkg_name(name: str) -> str:
         """
-        标准化包名，将包名转换为小写并将连字符替换为下划线
+        标准化包名，将包名转换为小写，连字符与点替换为下划线（与 PEP 503 归一化风格一致）
 
         :param name: 原始包名
         :return: 标准化后的包名
         """
-        return name.lower().replace("-", "_") if name else name
+        if not name:
+            return name
+        return name.lower().replace("-", "_").replace(".", "_")
 
     async def async_get_plugin_package_version(self, pid: str, repo_url: str,
                                                package_version: Optional[str] = None) -> Optional[str]:

app/helper/progress.py

@@ -3,10 +3,9 @@ from typing import Union, Optional
 
 from app.core.cache import TTLCache
 from app.schemas.types import ProgressKey
-from app.utils.singleton import WeakSingleton
 
 
-class ProgressHelper(metaclass=WeakSingleton):
+class ProgressHelper:
     """
     处理进度辅助类
     """

app/modules/discord/__init__.py

@@ -4,7 +4,7 @@ from typing import Optional, Union, List, Tuple, Any
 from app.core.context import MediaInfo, Context
 from app.log import logger
 from app.modules import _ModuleBase, _MessageBase
-from app.schemas import MessageChannel, CommingMessage, Notification
+from app.schemas import MessageChannel, CommingMessage, Notification, MessageResponse
 from app.schemas.types import ModuleType
 
 try:
@@ -15,7 +15,6 @@ except Exception as err:  # ImportError or other load issues
 
 
 class DiscordModule(_ModuleBase, _MessageBase[Discord]):
-
     def init_module(self) -> None:
         """
         初始化模块
@@ -24,8 +23,9 @@ class DiscordModule(_ModuleBase, _MessageBase[Discord]):
             logger.error("Discord 依赖未就绪（需要安装 discord.py==2.6.4），模块未启动")
             return
         self.stop()
-        super().init_service(service_name=Discord.__name__.lower(),
-                             service_type=Discord)
+        super().init_service(
+            service_name=Discord.__name__.lower(), service_type=Discord
+        )
         self._channel = MessageChannel.Discord
 
     @staticmethod
@@ -75,7 +75,9 @@ class DiscordModule(_ModuleBase, _MessageBase[Discord]):
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         pass
 
-    def message_parser(self, source: str, body: Any, form: Any, args: Any) -> Optional[CommingMessage]:
+    def message_parser(
+        self, source: str, body: Any, form: Any, args: Any
+    ) -> Optional[CommingMessage]:
         """
         解析消息内容，返回字典，注意以下约定值：
         userid: 用户ID
@@ -108,8 +110,10 @@ class DiscordModule(_ModuleBase, _MessageBase[Discord]):
             message_id = msg_json.get("message_id")
             chat_id = msg_json.get("chat_id")
             if callback_data and userid:
-                logger.info(f"收到来自 {client_config.name} 的 Discord 按钮回调："
-                            f"userid={userid}, username={username}, callback_data={callback_data}")
+                logger.info(
+                    f"收到来自 {client_config.name} 的 Discord 按钮回调："
+                    f"userid={userid}, username={username}, callback_data={callback_data}"
+                )
                 return CommingMessage(
                     channel=MessageChannel.Discord,
                     source=client_config.name,
@@ -119,7 +123,7 @@ class DiscordModule(_ModuleBase, _MessageBase[Discord]):
                     is_callback=True,
                     callback_data=callback_data,
                     message_id=message_id,
-                    chat_id=str(chat_id) if chat_id else None
+                    chat_id=str(chat_id) if chat_id else None,
                 )
             return None
 
@@ -127,11 +131,18 @@ class DiscordModule(_ModuleBase, _MessageBase[Discord]):
             text = msg_json.get("text")
             chat_id = msg_json.get("chat_id")
             if text and userid:
-                logger.info(f"收到来自 {client_config.name} 的 Discord 消息："
-                            f"userid={userid}, username={username}, text={text}")
-                return CommingMessage(channel=MessageChannel.Discord, source=client_config.name,
-                                      userid=userid, username=username, text=text,
-                                      chat_id=str(chat_id) if chat_id else None)
+                logger.info(
+                    f"收到来自 {client_config.name} 的 Discord 消息："
+                    f"userid={userid}, username={username}, text={text}"
+                )
+                return CommingMessage(
+                    channel=MessageChannel.Discord,
+                    source=client_config.name,
+                    userid=userid,
+                    username=username,
+                    text=text,
+                    chat_id=str(chat_id) if chat_id else None,
+                )
         return None
 
     def post_message(self, message: Notification, **kwargs) -> None:
@@ -141,43 +152,66 @@ class DiscordModule(_ModuleBase, _MessageBase[Discord]):
         """
         # DEBUG: Log entry and configs
         configs = self.get_configs()
-        logger.debug(f"[Discord] post_message 被调用，message.source={message.source}, "
-                     f"message.userid={message.userid}, message.channel={message.channel}")
-        logger.debug(f"[Discord] 当前配置数量: {len(configs)}, 配置名称: {list(configs.keys())}")
-        logger.debug(f"[Discord] 当前实例数量: {len(self.get_instances())}, 实例名称: {list(self.get_instances().keys())}")
+        logger.debug(
+            f"[Discord] post_message 被调用，message.source={message.source}, "
+            f"message.userid={message.userid}, message.channel={message.channel}"
+        )
+        logger.debug(
+            f"[Discord] 当前配置数量: {len(configs)}, 配置名称: {list(configs.keys())}"
+        )
+        logger.debug(
+            f"[Discord] 当前实例数量: {len(self.get_instances())}, 实例名称: {list(self.get_instances().keys())}"
+        )
 
         if not configs:
             logger.warning("[Discord] get_configs() 返回空，没有可用的 Discord 配置")
             return
 
         for conf in configs.values():
-            logger.debug(f"[Discord] 检查配置: name={conf.name}, type={conf.type}, enabled={conf.enabled}")
+            logger.debug(
+                f"[Discord] 检查配置: name={conf.name}, type={conf.type}, enabled={conf.enabled}"
+            )
             if not self.check_message(message, conf.name):
-                logger.debug(f"[Discord] check_message 返回 False，跳过配置: {conf.name}")
+                logger.debug(
+                    f"[Discord] check_message 返回 False，跳过配置: {conf.name}"
+                )
                 continue
             logger.debug(f"[Discord] check_message 通过，准备发送到: {conf.name}")
             targets = message.targets
             userid = message.userid
             if not userid and targets is not None:
-                userid = targets.get('discord_userid')
+                userid = targets.get("discord_userid")
                 if not userid:
                     logger.warn("用户没有指定 Discord 用户ID，消息无法发送")
                     return
             client: Discord = self.get_instance(conf.name)
-            logger.debug(f"[Discord] get_instance('{conf.name}') 返回: {client is not None}")
+            logger.debug(
+                f"[Discord] get_instance('{conf.name}') 返回: {client is not None}"
+            )
             if client:
-                logger.debug(f"[Discord] 调用 client.send_msg, userid={userid}, title={message.title[:50] if message.title else None}...")
-                result = client.send_msg(title=message.title, text=message.text,
-                                image=message.image, userid=userid, link=message.link,
-                                buttons=message.buttons,
-                                original_message_id=message.original_message_id,
-                                original_chat_id=message.original_chat_id,
-                                mtype=message.mtype)
+                logger.debug(
+                    f"[Discord] 调用 client.send_msg, userid={userid}, title={message.title[:50] if message.title else None}..."
+                )
+                result = client.send_msg(
+                    title=message.title,
+                    text=message.text,
+                    image=message.image,
+                    userid=userid,
+                    link=message.link,
+                    buttons=message.buttons,
+                    original_message_id=message.original_message_id,
+                    original_chat_id=message.original_chat_id,
+                    mtype=message.mtype,
+                )
                 logger.debug(f"[Discord] send_msg 返回结果: {result}")
             else:
-                logger.warning(f"[Discord] 未找到配置 '{conf.name}' 对应的 Discord 客户端实例")
+                logger.warning(
+                    f"[Discord] 未找到配置 '{conf.name}' 对应的 Discord 客户端实例"
+                )
 
-    def post_medias_message(self, message: Notification, medias: List[MediaInfo]) -> None:
+    def post_medias_message(
+        self, message: Notification, medias: List[MediaInfo]
+    ) -> None:
         """
         发送媒体信息选择列表
         :param message: 消息体
@@ -189,12 +223,18 @@ class DiscordModule(_ModuleBase, _MessageBase[Discord]):
                 continue
             client: Discord = self.get_instance(conf.name)
             if client:
-                client.send_medias_msg(title=message.title, medias=medias, userid=message.userid,
-                                       buttons=message.buttons,
-                                       original_message_id=message.original_message_id,
-                                       original_chat_id=message.original_chat_id)
+                client.send_medias_msg(
+                    title=message.title,
+                    medias=medias,
+                    userid=message.userid,
+                    buttons=message.buttons,
+                    original_message_id=message.original_message_id,
+                    original_chat_id=message.original_chat_id,
+                )
 
-    def post_torrents_message(self, message: Notification, torrents: List[Context]) -> None:
+    def post_torrents_message(
+        self, message: Notification, torrents: List[Context]
+    ) -> None:
         """
         发送种子信息选择列表
         :param message: 消息体
@@ -206,13 +246,22 @@ class DiscordModule(_ModuleBase, _MessageBase[Discord]):
                 continue
             client: Discord = self.get_instance(conf.name)
             if client:
-                client.send_torrents_msg(title=message.title, torrents=torrents,
-                                         userid=message.userid, buttons=message.buttons,
-                                         original_message_id=message.original_message_id,
-                                         original_chat_id=message.original_chat_id)
+                client.send_torrents_msg(
+                    title=message.title,
+                    torrents=torrents,
+                    userid=message.userid,
+                    buttons=message.buttons,
+                    original_message_id=message.original_message_id,
+                    original_chat_id=message.original_chat_id,
+                )
 
-    def delete_message(self, channel: MessageChannel, source: str,
-                       message_id: str, chat_id: Optional[str] = None) -> bool:
+    def delete_message(
+        self,
+        channel: MessageChannel,
+        source: str,
+        message_id: str,
+        chat_id: Optional[str] = None,
+    ) -> bool:
         """
         删除消息
         :param channel: 消息渠道
@@ -233,3 +282,80 @@ class DiscordModule(_ModuleBase, _MessageBase[Discord]):
                 if result:
                     success = True
         return success
+
+    def edit_message(
+        self,
+        channel: MessageChannel,
+        source: str,
+        message_id: Union[str, int],
+        chat_id: Union[str, int],
+        text: str,
+        title: Optional[str] = None,
+    ) -> bool:
+        """
+        编辑消息
+        :param channel: 消息渠道
+        :param source: 指定的消息源
+        :param message_id: 消息ID
+        :param chat_id: 聊天ID
+        :param text: 新的消息内容
+        :param title: 消息标题
+        :return: 编辑是否成功
+        """
+        if channel != self._channel:
+            return False
+        for conf in self.get_configs().values():
+            if source != conf.name:
+                continue
+            client: Discord = self.get_instance(conf.name)
+            if client:
+                result = client.send_msg(
+                    title=title or "",
+                    text=text,
+                    original_message_id=message_id,
+                    original_chat_id=str(chat_id),
+                )
+                if result and isinstance(result, tuple) and result[0]:
+                    return True
+                elif result:
+                    return True
+        return False
+
+    def send_direct_message(self, message: Notification) -> Optional[MessageResponse]:
+        """
+        直接发送消息并返回消息ID等信息
+        :param message: 消息体
+        :return: 消息响应（包含message_id, chat_id等）
+        """
+        for conf in self.get_configs().values():
+            if not self.check_message(message, conf.name):
+                continue
+            targets = message.targets
+            userid = message.userid
+            if not userid and targets is not None:
+                userid = targets.get("discord_userid")
+                if not userid:
+                    logger.warn("用户没有指定 Discord 用户ID，消息无法发送")
+                    return None
+            client: Discord = self.get_instance(conf.name)
+            if client:
+                result = client.send_msg(
+                    title=message.title or "",
+                    text=message.text,
+                    userid=userid,
+                )
+                if result:
+                    success, message_id = (
+                        (result[0], result[1])
+                        if isinstance(result, tuple)
+                        else (result, None)
+                    )
+                    if success:
+                        return MessageResponse(
+                            message_id=str(message_id) if message_id else None,
+                            chat_id=None,
+                            channel=MessageChannel.Discord,
+                            source=conf.name,
+                            success=True,
+                        )
+        return None

app/modules/discord/discord.py

@@ -18,10 +18,10 @@ from app.utils.string import StringUtils
 # Discord embed 字段解析白名单
 # 只有这些消息类型会使用复杂的字段解析逻辑
 PARSE_FIELD_TYPES = {
-    NotificationType.Download,      # 资源下载
-    NotificationType.Organize,      # 整理入库
-    NotificationType.Subscribe,     # 订阅
-    NotificationType.Manual,        # 手动处理
+    NotificationType.Download,  # 资源下载
+    NotificationType.Organize,  # 整理入库
+    NotificationType.Subscribe,  # 订阅
+    NotificationType.Manual,  # 手动处理
 }
 
 
@@ -30,13 +30,18 @@ class Discord:
     Discord Bot 通知与交互实现（基于 discord.py 2.6.4）
     """
 
-    def __init__(self, DISCORD_BOT_TOKEN: Optional[str] = None,
-                 DISCORD_GUILD_ID: Optional[Union[str, int]] = None,
-                 DISCORD_CHANNEL_ID: Optional[Union[str, int]] = None,
-                 **kwargs):
-        logger.debug(f"[Discord] 初始化 Discord 实例: name={kwargs.get('name')}, "
-                     f"GUILD_ID={DISCORD_GUILD_ID}, CHANNEL_ID={DISCORD_CHANNEL_ID}, "
-                     f"TOKEN={'已配置' if DISCORD_BOT_TOKEN else '未配置'}")
+    def __init__(
+        self,
+        DISCORD_BOT_TOKEN: Optional[str] = None,
+        DISCORD_GUILD_ID: Optional[Union[str, int]] = None,
+        DISCORD_CHANNEL_ID: Optional[Union[str, int]] = None,
+        **kwargs,
+    ):
+        logger.debug(
+            f"[Discord] 初始化 Discord 实例: name={kwargs.get('name')}, "
+            f"GUILD_ID={DISCORD_GUILD_ID}, CHANNEL_ID={DISCORD_CHANNEL_ID}, "
+            f"TOKEN={'已配置' if DISCORD_BOT_TOKEN else '未配置'}"
+        )
         if not DISCORD_BOT_TOKEN:
             logger.error("Discord Bot Token 未配置！")
             return
@@ -44,12 +49,14 @@ class Discord:
         self._token = DISCORD_BOT_TOKEN
         self._guild_id = self._to_int(DISCORD_GUILD_ID)
         self._channel_id = self._to_int(DISCORD_CHANNEL_ID)
-        logger.debug(f"[Discord] 解析后的 ID: _guild_id={self._guild_id}, _channel_id={self._channel_id}")
+        logger.debug(
+            f"[Discord] 解析后的 ID: _guild_id={self._guild_id}, _channel_id={self._channel_id}"
+        )
         base_ds_url = f"http://127.0.0.1:{settings.PORT}/api/v1/message/"
         self._ds_url = f"{base_ds_url}?token={settings.API_TOKEN}"
         if kwargs.get("name"):
             # URL encode the source name to handle special characters in config names
-            encoded_name = quote(kwargs.get('name'), safe='')
+            encoded_name = quote(kwargs.get("name"), safe="")
             self._ds_url = f"{self._ds_url}&source={encoded_name}"
         logger.debug(f"[Discord] 消息回调 URL: {self._ds_url}")
 
@@ -59,15 +66,16 @@ class Discord:
         intents.guilds = True
 
         self._client: Optional[discord.Client] = discord.Client(
-            intents=intents,
-            proxy=settings.PROXY_HOST
+            intents=intents, proxy=settings.PROXY_HOST
         )
         self._tree: Optional[app_commands.CommandTree] = None
         self._loop: asyncio.AbstractEventLoop = asyncio.new_event_loop()
         self._thread: Optional[threading.Thread] = None
         self._ready_event = threading.Event()
         self._user_dm_cache: Dict[str, discord.DMChannel] = {}
-        self._user_chat_mapping: Dict[str, str] = {}  # userid -> chat_id mapping for reply targeting
+        self._user_chat_mapping: Dict[
+            str, str
+        ] = {}  # userid -> chat_id mapping for reply targeting
         self._broadcast_channel = None
         self._bot_user_id: Optional[int] = None
 
@@ -96,10 +104,16 @@ class Discord:
                 return
 
             # Update user-chat mapping for reply targeting
-            self._update_user_chat_mapping(str(message.author.id), str(message.channel.id))
+            self._update_user_chat_mapping(
+                str(message.author.id), str(message.channel.id)
+            )
 
             cleaned_text = self._clean_bot_mention(message.content or "")
-            username = message.author.display_name or message.author.global_name or message.author.name
+            username = (
+                message.author.display_name
+                or message.author.global_name
+                or message.author.name
+            )
             payload = {
                 "type": "message",
                 "userid": str(message.author.id),
@@ -108,7 +122,9 @@ class Discord:
                 "text": cleaned_text,
                 "message_id": str(message.id),
                 "chat_id": str(message.channel.id),
-                "channel_type": "dm" if isinstance(message.channel, discord.DMChannel) else "guild"
+                "channel_type": "dm"
+                if isinstance(message.channel, discord.DMChannel)
+                else "guild",
             }
             await self._post_to_ds(payload)
 
@@ -126,18 +142,31 @@ class Discord:
 
                 # Update user-chat mapping for reply targeting
                 if interaction.user and interaction.channel:
-                    self._update_user_chat_mapping(str(interaction.user.id), str(interaction.channel.id))
+                    self._update_user_chat_mapping(
+                        str(interaction.user.id), str(interaction.channel.id)
+                    )
 
-                username = (interaction.user.display_name or interaction.user.global_name or interaction.user.name) \
-                    if interaction.user else None
+                username = (
+                    (
+                        interaction.user.display_name
+                        or interaction.user.global_name
+                        or interaction.user.name
+                    )
+                    if interaction.user
+                    else None
+                )
                 payload = {
                     "type": "interaction",
                     "userid": str(interaction.user.id) if interaction.user else None,
                     "username": username,
                     "user_tag": str(interaction.user) if interaction.user else None,
                     "callback_data": callback_data,
-                    "message_id": str(interaction.message.id) if interaction.message else None,
-                    "chat_id": str(interaction.channel.id) if interaction.channel else None
+                    "message_id": str(interaction.message.id)
+                    if interaction.message
+                    else None,
+                    "chat_id": str(interaction.channel.id)
+                    if interaction.channel
+                    else None,
                 }
                 await self._post_to_ds(payload)
 
@@ -165,7 +194,9 @@ class Discord:
         if not self._client or not self._loop or not self._thread:
             return
         try:
-            asyncio.run_coroutine_threadsafe(self._client.close(), self._loop).result(timeout=10)
+            asyncio.run_coroutine_threadsafe(self._client.close(), self._loop).result(
+                timeout=10
+            )
         except Exception as err:
             logger.error(f"关闭 Discord Bot 失败：{err}")
         finally:
@@ -178,16 +209,26 @@ class Discord:
     def get_state(self) -> bool:
         return self._ready_event.is_set() and self._client is not None
 
-    def send_msg(self, title: str, text: Optional[str] = None, image: Optional[str] = None,
-                 userid: Optional[str] = None, link: Optional[str] = None,
-                 buttons: Optional[List[List[dict]]] = None,
-                 original_message_id: Optional[Union[int, str]] = None,
-                 original_chat_id: Optional[str] = None,
-                 mtype: Optional['NotificationType'] = None) -> Optional[bool]:
-        logger.debug(f"[Discord] send_msg 被调用: userid={userid}, title={title[:50] if title else None}...")
-        logger.debug(f"[Discord] get_state() = {self.get_state()}, "
-                     f"_ready_event.is_set() = {self._ready_event.is_set()}, "
-                     f"_client = {self._client is not None}")
+    def send_msg(
+        self,
+        title: str,
+        text: Optional[str] = None,
+        image: Optional[str] = None,
+        userid: Optional[str] = None,
+        link: Optional[str] = None,
+        buttons: Optional[List[List[dict]]] = None,
+        original_message_id: Optional[Union[int, str]] = None,
+        original_chat_id: Optional[str] = None,
+        mtype: Optional["NotificationType"] = None,
+    ) -> Optional[bool]:
+        logger.debug(
+            f"[Discord] send_msg 被调用: userid={userid}, title={title[:50] if title else None}..."
+        )
+        logger.debug(
+            f"[Discord] get_state() = {self.get_state()}, "
+            f"_ready_event.is_set() = {self._ready_event.is_set()}, "
+            f"_client = {self._client is not None}"
+        )
         if not self.get_state():
             logger.warning("[Discord] get_state() 返回 False，Bot 未就绪，无法发送消息")
             return False
@@ -198,12 +239,19 @@ class Discord:
         try:
             logger.debug(f"[Discord] 准备异步发送消息...")
             future = asyncio.run_coroutine_threadsafe(
-                self._send_message(title=title, text=text, image=image, userid=userid,
-                                   link=link, buttons=buttons,
-                                   original_message_id=original_message_id,
-                                   original_chat_id=original_chat_id,
-                                   mtype=mtype),
-                self._loop)
+                self._send_message(
+                    title=title,
+                    text=text,
+                    image=image,
+                    userid=userid,
+                    link=link,
+                    buttons=buttons,
+                    original_message_id=original_message_id,
+                    original_chat_id=original_chat_id,
+                    mtype=mtype,
+                ),
+                self._loop,
+            )
             result = future.result(timeout=30)
             logger.debug(f"[Discord] 异步发送完成，结果: {result}")
             return result
@@ -211,10 +259,15 @@ class Discord:
             logger.error(f"发送 Discord 消息失败：{err}")
             return False
 
-    def send_medias_msg(self, medias: List[MediaInfo], userid: Optional[str] = None, title: Optional[str] = None,
-                        buttons: Optional[List[List[dict]]] = None,
-                        original_message_id: Optional[Union[int, str]] = None,
-                        original_chat_id: Optional[str] = None) -> Optional[bool]:
+    def send_medias_msg(
+        self,
+        medias: List[MediaInfo],
+        userid: Optional[str] = None,
+        title: Optional[str] = None,
+        buttons: Optional[List[List[dict]]] = None,
+        original_message_id: Optional[Union[int, str]] = None,
+        original_chat_id: Optional[str] = None,
+    ) -> Optional[bool]:
         if not self.get_state() or not medias:
             return False
         title = title or "媒体列表"
@@ -223,22 +276,29 @@ class Discord:
                 self._send_list_message(
                     embeds=self._build_media_embeds(medias, title),
                     userid=userid,
-                    buttons=self._build_default_buttons(len(medias)) if not buttons else buttons,
+                    buttons=self._build_default_buttons(len(medias))
+                    if not buttons
+                    else buttons,
                     fallback_buttons=buttons,
                     original_message_id=original_message_id,
-                    original_chat_id=original_chat_id
+                    original_chat_id=original_chat_id,
                 ),
-                self._loop
+                self._loop,
             )
             return future.result(timeout=30)
         except Exception as err:
             logger.error(f"发送 Discord 媒体列表失败：{err}")
             return False
 
-    def send_torrents_msg(self, torrents: List[Context], userid: Optional[str] = None, title: Optional[str] = None,
-                          buttons: Optional[List[List[dict]]] = None,
-                          original_message_id: Optional[Union[int, str]] = None,
-                          original_chat_id: Optional[str] = None) -> Optional[bool]:
+    def send_torrents_msg(
+        self,
+        torrents: List[Context],
+        userid: Optional[str] = None,
+        title: Optional[str] = None,
+        buttons: Optional[List[List[dict]]] = None,
+        original_message_id: Optional[Union[int, str]] = None,
+        original_chat_id: Optional[str] = None,
+    ) -> Optional[bool]:
         if not self.get_state() or not torrents:
             return False
         title = title or "种子列表"
@@ -247,68 +307,92 @@ class Discord:
                 self._send_list_message(
                     embeds=self._build_torrent_embeds(torrents, title),
                     userid=userid,
-                    buttons=self._build_default_buttons(len(torrents)) if not buttons else buttons,
+                    buttons=self._build_default_buttons(len(torrents))
+                    if not buttons
+                    else buttons,
                     fallback_buttons=buttons,
                     original_message_id=original_message_id,
-                    original_chat_id=original_chat_id
+                    original_chat_id=original_chat_id,
                 ),
-                self._loop
+                self._loop,
             )
             return future.result(timeout=30)
         except Exception as err:
             logger.error(f"发送 Discord 种子列表失败：{err}")
             return False
 
-    def delete_msg(self, message_id: Union[str, int], chat_id: Optional[str] = None) -> Optional[bool]:
+    def delete_msg(
+        self, message_id: Union[str, int], chat_id: Optional[str] = None
+    ) -> Optional[bool]:
         if not self.get_state():
             return False
         try:
             future = asyncio.run_coroutine_threadsafe(
-                self._delete_message(message_id=message_id, chat_id=chat_id),
-                self._loop
+                self._delete_message(message_id=message_id, chat_id=chat_id), self._loop
             )
             return future.result(timeout=15)
         except Exception as err:
             logger.error(f"删除 Discord 消息失败：{err}")
             return False
 
-    async def _send_message(self, title: str, text: Optional[str], image: Optional[str],
-                            userid: Optional[str], link: Optional[str],
-                            buttons: Optional[List[List[dict]]],
-                            original_message_id: Optional[Union[int, str]],
-                            original_chat_id: Optional[str],
-                            mtype: Optional['NotificationType'] = None) -> bool:
-        logger.debug(f"[Discord] _send_message: userid={userid}, original_chat_id={original_chat_id}")
+    async def _send_message(
+        self,
+        title: str,
+        text: Optional[str],
+        image: Optional[str],
+        userid: Optional[str],
+        link: Optional[str],
+        buttons: Optional[List[List[dict]]],
+        original_message_id: Optional[Union[int, str]],
+        original_chat_id: Optional[str],
+        mtype: Optional["NotificationType"] = None,
+    ) -> Tuple[bool, Optional[int]]:
+        logger.debug(
+            f"[Discord] _send_message: userid={userid}, original_chat_id={original_chat_id}"
+        )
         channel = await self._resolve_channel(userid=userid, chat_id=original_chat_id)
-        logger.debug(f"[Discord] _resolve_channel 返回: {channel}, type={type(channel)}")
+        logger.debug(
+            f"[Discord] _resolve_channel 返回: {channel}, type={type(channel)}"
+        )
         if not channel:
             logger.error("未找到可用的 Discord 频道或私聊")
-            return False
+            return False, None
 
-        embed = self._build_embed(title=title, text=text, image=image, link=link, mtype=mtype)
+        embed = self._build_embed(
+            title=title, text=text, image=image, link=link, mtype=mtype
+        )
         view = self._build_view(buttons=buttons, link=link)
         content = None
 
         if original_message_id and original_chat_id:
             logger.debug(f"[Discord] 编辑现有消息: message_id={original_message_id}")
-            return await self._edit_message(chat_id=original_chat_id, message_id=original_message_id,
-                                            content=content, embed=embed, view=view)
+            success = await self._edit_message(
+                chat_id=original_chat_id,
+                message_id=original_message_id,
+                content=content,
+                embed=embed,
+                view=view,
+            )
+            return success, int(original_message_id) if original_message_id else None
 
         logger.debug(f"[Discord] 发送新消息到频道: {channel}")
         try:
-            await channel.send(content=content, embed=embed, view=view)
+            sent_message = await channel.send(content=content, embed=embed, view=view)
             logger.debug("[Discord] 消息发送成功")
-            return True
+            return True, sent_message.id if sent_message else None
         except Exception as e:
             logger.error(f"[Discord] 发送消息到频道失败: {e}")
-            return False
+            return False, None
 
-    async def _send_list_message(self, embeds: List[discord.Embed],
-                                 userid: Optional[str],
-                                 buttons: Optional[List[List[dict]]],
-                                 fallback_buttons: Optional[List[List[dict]]],
-                                 original_message_id: Optional[Union[int, str]],
-                                 original_chat_id: Optional[str]) -> bool:
+    async def _send_list_message(
+        self,
+        embeds: List[discord.Embed],
+        userid: Optional[str],
+        buttons: Optional[List[List[dict]]],
+        fallback_buttons: Optional[List[List[dict]]],
+        original_message_id: Optional[Union[int, str]],
+        original_chat_id: Optional[str],
+    ) -> bool:
         channel = await self._resolve_channel(userid=userid, chat_id=original_chat_id)
         if not channel:
             logger.error("未找到可用的 Discord 频道或私聊")
@@ -318,17 +402,31 @@ class Discord:
         embeds = embeds[:10] if embeds else []  # Discord 单条消息最多 10 个 embed
 
         if original_message_id and original_chat_id:
-            return await self._edit_message(chat_id=original_chat_id, message_id=original_message_id,
-                                            content=None, embed=None, view=view, embeds=embeds)
+            return await self._edit_message(
+                chat_id=original_chat_id,
+                message_id=original_message_id,
+                content=None,
+                embed=None,
+                view=view,
+                embeds=embeds,
+            )
 
-        await channel.send(embed=embeds[0] if len(embeds) == 1 else None,
-                           embeds=embeds if len(embeds) > 1 else None,
-                           view=view)
+        await channel.send(
+            embed=embeds[0] if len(embeds) == 1 else None,
+            embeds=embeds if len(embeds) > 1 else None,
+            view=view,
+        )
         return True
 
-    async def _edit_message(self, chat_id: Union[str, int], message_id: Union[str, int],
-                            content: Optional[str], embed: Optional[discord.Embed],
-                            view: Optional[discord.ui.View], embeds: Optional[List[discord.Embed]] = None) -> bool:
+    async def _edit_message(
+        self,
+        chat_id: Union[str, int],
+        message_id: Union[str, int],
+        content: Optional[str],
+        embed: Optional[discord.Embed],
+        view: Optional[discord.ui.View],
+        embeds: Optional[List[discord.Embed]] = None,
+    ) -> bool:
         channel = await self._resolve_channel(chat_id=str(chat_id))
         if not channel:
             logger.error(f"未找到要编辑的 Discord 频道：{chat_id}")
@@ -349,7 +447,9 @@ class Discord:
             logger.error(f"编辑 Discord 消息失败：{err}")
             return False
 
-    async def _delete_message(self, message_id: Union[str, int], chat_id: Optional[str]) -> bool:
+    async def _delete_message(
+        self, message_id: Union[str, int], chat_id: Optional[str]
+    ) -> bool:
         channel = await self._resolve_channel(chat_id=chat_id)
         if not channel:
             logger.error("删除 Discord 消息时未找到频道")
@@ -363,11 +463,17 @@ class Discord:
             return False
 
     @staticmethod
-    def _build_embed(title: str, text: Optional[str], image: Optional[str],
-                     link: Optional[str], mtype: Optional['NotificationType'] = None) -> discord.Embed:
+    def _build_embed(
+        title: str,
+        text: Optional[str],
+        image: Optional[str],
+        link: Optional[str],
+        mtype: Optional["NotificationType"] = None,
+    ) -> discord.Embed:
         fields: List[Dict[str, str]] = []
         desc_lines: List[str] = []
         should_parse_fields = mtype in PARSE_FIELD_TYPES if mtype else False
+
         def _collect_spans(s: str, left: str, right: str) -> List[Tuple[int, int]]:
             spans: List[Tuple[int, int]] = []
             start = 0
@@ -383,7 +489,7 @@ class Discord:
             return spans
 
         def _find_colon_index(s: str, m: re.Match) -> Optional[int]:
-            segment = s[m.start():m.end()]
+            segment = s[m.start() : m.end()]
             for i, ch in enumerate(segment):
                 if ch in (":", "："):
                     return m.start() + i
@@ -392,7 +498,11 @@ class Discord:
         if text:
             # 处理上游未反序列化的 "\n" 等转义换行，避免被当成普通字符
             if "\\n" in text or "\\r" in text:
-                text = text.replace("\\r\\n", "\n").replace("\\n", "\n").replace("\\r", "\n")
+                text = (
+                    text.replace("\\r\\n", "\n")
+                    .replace("\\n", "\n")
+                    .replace("\\r", "\n")
+                )
             if not should_parse_fields:
                 desc_lines.append(text.strip())
             else:
@@ -410,12 +520,16 @@ class Discord:
                         continue
                     matches = list(pair_pattern.finditer(line))
                     if matches:
-                        book_spans = _collect_spans(line, "《", "》") + _collect_spans(line, "【", "】")
+                        book_spans = _collect_spans(line, "《", "》") + _collect_spans(
+                            line, "【", "】"
+                        )
                         if book_spans:
                             has_book_colon = False
                             for m in matches:
                                 colon_idx = _find_colon_index(line, m)
-                                if colon_idx is not None and any(l < colon_idx < r for l, r in book_spans):
+                                if colon_idx is not None and any(
+                                    l < colon_idx < r for l, r in book_spans
+                                ):
                                     has_book_colon = True
                                     break
                             if has_book_colon:
@@ -423,20 +537,25 @@ class Discord:
                                 continue
                         # 若整行只是 URL/时间等自然包含":"的内容，则不当作字段
                         url_like_names = {"http", "https", "ftp", "ftps", "magnet"}
-                        if all(m.group(1).lower() in url_like_names or m.group(1).isdigit() for m in matches):
+                        if all(
+                            m.group(1).lower() in url_like_names or m.group(1).isdigit()
+                            for m in matches
+                        ):
                             desc_lines.append(line)
                             continue
                         last_end = 0
                         for m in matches:
                             # 追加匹配前的非空文本到描述
-                            prefix = line[last_end:m.start()].strip(" ，,;；。、")
+                            prefix = line[last_end : m.start()].strip(" ，,;；。、")
                             # 仅当前缀不全是分隔符/空白时才记录
                             if prefix and prefix.strip(" ，,;；。、"):
                                 desc_lines.append(prefix)
                             name = m.group(1).strip()
                             value = m.group(2).strip(" ，,;；。、\t") or "-"
                             if name:
-                                fields.append({"name": name, "value": value, "inline": False})
+                                fields.append(
+                                    {"name": name, "value": value, "inline": False}
+                                )
                             last_end = m.end()
                         # 匹配末尾后的文本
                         suffix = line[last_end:].strip(" ，,;；。、")
@@ -451,7 +570,7 @@ class Discord:
             title=title,
             url=link or "https://github.com/jxxghp/MoviePilot",
             description=description if description else None,
-            color=0xE67E22
+            color=0xE67E22,
         )
         for field in fields:
             embed.add_field(name=field["name"], value=field["value"], inline=False)
@@ -465,14 +584,16 @@ class Discord:
         for index, media in enumerate(medias[:10], start=1):
             overview = media.get_overview_string(80)
             desc_parts = [
-                f"{media.type.value} | {media.vote_star}" if media.vote_star else media.type.value,
-                overview
+                f"{media.type.value} | {media.vote_star}"
+                if media.vote_star
+                else media.type.value,
+                overview,
             ]
             embed = discord.Embed(
                 title=f"{index}. {media.title_year}",
                 url=media.detail_link or discord.Embed.Empty,
                 description="\n".join([p for p in desc_parts if p]),
-                color=0x5865F2
+                color=0x5865F2,
             )
             if media.get_poster_image():
                 embed.set_thumbnail(url=media.get_poster_image())
@@ -482,7 +603,9 @@ class Discord:
         return embeds
 
     @staticmethod
-    def _build_torrent_embeds(torrents: List[Context], title: str) -> List[discord.Embed]:
+    def _build_torrent_embeds(
+        torrents: List[Context], title: str
+    ) -> List[discord.Embed]:
         embeds: List[discord.Embed] = []
         for index, context in enumerate(torrents[:10], start=1):
             torrent = context.torrent_info
@@ -492,13 +615,13 @@ class Discord:
             detail = [
                 f"{torrent.site_name} | {StringUtils.str_filesize(torrent.size)} | {torrent.volume_factor} | {torrent.seeders}↑",
                 meta.resource_term,
-                meta.video_term
+                meta.video_term,
             ]
             embed = discord.Embed(
                 title=f"{index}. {title_text or torrent.title}",
                 url=torrent.page_url or discord.Embed.Empty,
                 description="\n".join([d for d in detail if d]),
-                color=0x00A86B
+                color=0x00A86B,
             )
             poster = getattr(torrent, "poster", None)
             if poster:
@@ -524,7 +647,9 @@ class Discord:
         return buttons
 
     @staticmethod
-    def _build_view(buttons: Optional[List[List[dict]]], link: Optional[str] = None) -> Optional[discord.ui.View]:
+    def _build_view(
+        buttons: Optional[List[List[dict]]], link: Optional[str] = None
+    ) -> Optional[discord.ui.View]:
         has_buttons = buttons and any(buttons)
         if not has_buttons and not link:
             return None
@@ -534,20 +659,34 @@ class Discord:
             for row_index, button_row in enumerate(buttons[:5]):
                 for button in button_row[:5]:
                     if "url" in button:
-                        btn = discord.ui.Button(label=button.get("text", "链接"),
-                                                url=button["url"],
-                                                style=discord.ButtonStyle.link)
+                        btn = discord.ui.Button(
+                            label=button.get("text", "链接"),
+                            url=button["url"],
+                            style=discord.ButtonStyle.link,
+                        )
                     else:
-                        custom_id = (button.get("callback_data") or button.get("text") or f"btn-{row_index}")[:99]
-                        btn = discord.ui.Button(label=button.get("text", "选择")[:80],
-                                                custom_id=custom_id,
-                                                style=discord.ButtonStyle.primary)
+                        custom_id = (
+                            button.get("callback_data")
+                            or button.get("text")
+                            or f"btn-{row_index}"
+                        )[:99]
+                        btn = discord.ui.Button(
+                            label=button.get("text", "选择")[:80],
+                            custom_id=custom_id,
+                            style=discord.ButtonStyle.primary,
+                        )
                     view.add_item(btn)
         elif link:
-            view.add_item(discord.ui.Button(label="查看详情", url=link, style=discord.ButtonStyle.link))
+            view.add_item(
+                discord.ui.Button(
+                    label="查看详情", url=link, style=discord.ButtonStyle.link
+                )
+            )
         return view
 
-    async def _resolve_channel(self, userid: Optional[str] = None, chat_id: Optional[str] = None):
+    async def _resolve_channel(
+        self, userid: Optional[str] = None, chat_id: Optional[str] = None
+    ):
         """
         Resolve the channel to send messages to.
         Priority order:
@@ -557,8 +696,10 @@ class Discord:
         4. Any available text channel in configured guild - fallback
         5. `userid` (DM) - for private conversations as a final fallback
         """
-        logger.debug(f"[Discord] _resolve_channel: userid={userid}, chat_id={chat_id}, "
-                     f"_channel_id={self._channel_id}, _guild_id={self._guild_id}")
+        logger.debug(
+            f"[Discord] _resolve_channel: userid={userid}, chat_id={chat_id}, "
+            f"_channel_id={self._channel_id}, _guild_id={self._guild_id}"
+        )
 
         # Priority 1: Use explicit chat_id (reply to the same channel where user sent message)
         if chat_id:
@@ -585,7 +726,9 @@ class Discord:
                     return channel
                 try:
                     channel = await self._client.fetch_channel(int(mapped_chat_id))
-                    logger.debug(f"[Discord] 通过 fetch_channel 找到映射频道: {channel}")
+                    logger.debug(
+                        f"[Discord] 通过 fetch_channel 找到映射频道: {channel}"
+                    )
                     return channel
                 except Exception as err:
                     logger.warn(f"通过映射的 chat_id 获取 Discord 频道失败：{err}")
@@ -595,7 +738,9 @@ class Discord:
             logger.debug(f"[Discord] 使用缓存的广播频道: {self._broadcast_channel}")
             return self._broadcast_channel
         if self._channel_id:
-            logger.debug(f"[Discord] 尝试通过配置的 _channel_id={self._channel_id} 获取频道")
+            logger.debug(
+                f"[Discord] 尝试通过配置的 _channel_id={self._channel_id} 获取频道"
+            )
             channel = self._client.get_channel(self._channel_id)
             if not channel:
                 try:
@@ -641,7 +786,9 @@ class Discord:
     async def _get_dm_channel(self, userid: str) -> Optional[discord.DMChannel]:
         logger.debug(f"[Discord] _get_dm_channel: userid={userid}")
         if userid in self._user_dm_cache:
-            logger.debug(f"[Discord] 从缓存获取私聊频道: {self._user_dm_cache.get(userid)}")
+            logger.debug(
+                f"[Discord] 从缓存获取私聊频道: {self._user_dm_cache.get(userid)}"
+            )
             return self._user_dm_cache.get(userid)
         try:
             logger.debug(f"[Discord] 尝试获取/创建用户 {userid} 的私聊频道")
@@ -674,7 +821,9 @@ class Discord:
         """
         if userid and chat_id:
             self._user_chat_mapping[userid] = chat_id
-            logger.debug(f"[Discord] 更新用户频道映射: userid={userid} -> chat_id={chat_id}")
+            logger.debug(
+                f"[Discord] 更新用户频道映射: userid={userid} -> chat_id={chat_id}"
+            )
 
     def _get_user_chat_id(self, userid: str) -> Optional[str]:
         """
@@ -708,7 +857,9 @@ class Discord:
             proxy = None
             if settings.PROXY:
                 proxy = settings.PROXY.get("https") or settings.PROXY.get("http")
-            async with httpx.AsyncClient(timeout=10, verify=False, proxy=proxy) as client:
+            async with httpx.AsyncClient(
+                timeout=10, verify=False, proxy=proxy
+            ) as client:
                 await client.post(self._ds_url, json=payload)
         except Exception as err:
             logger.error(f"转发 Discord 消息失败：{err}")

app/modules/emby/emby.py

@@ -714,7 +714,7 @@ class Emby:
             logger.error(f"连接Users/Items出错：" + str(e))
         return None
 
-    def get_webhook_message(self, form: any, args: dict) -> Optional[schemas.WebhookEventInfo]:
+    def get_webhook_message(self, form: Any, args: dict) -> Optional[schemas.WebhookEventInfo]:
         """
         解析Emby Webhook报文
         电影：

app/modules/filemanager/__init__.py

@@ -81,18 +81,19 @@ class FileManagerModule(_ModuleBase):
                 return False, f"{d.name} 的下载目录未设置"
             if d.storage == "local" and not Path(download_path).exists():
                 return False, f"{d.name} 的下载目录 {download_path} 不存在"
-            # 媒体库目录
+            # 仅在启用整理时检查媒体库目录
             library_path = d.library_path
-            if not library_path:
-                return False, f"{d.name} 的媒体库目录未设置"
-            if d.library_storage == "local" and not Path(library_path).exists():
-                return False, f"{d.name} 的媒体库目录 {library_path} 不存在"
-            # 硬链接
-            if d.transfer_type == "link" \
-                    and d.storage == "local" \
-                    and d.library_storage == "local" \
-                    and not SystemUtils.is_same_disk(Path(download_path), Path(library_path)):
-                return False, f"{d.name} 的下载目录 {download_path} 与媒体库目录 {library_path} 不在同一磁盘，无法硬链接"
+            if d.transfer_type:
+                if not library_path:
+                    return False, f"{d.name} 的媒体库目录未设置"
+                if d.library_storage == "local" and not Path(library_path).exists():
+                    return False, f"{d.name} 的媒体库目录 {library_path} 不存在"
+                # 硬链接
+                if d.transfer_type == "link" \
+                        and d.storage == "local" \
+                        and d.library_storage == "local" \
+                        and not SystemUtils.is_same_disk(Path(download_path), Path(library_path)):
+                    return False, f"{d.name} 的下载目录 {download_path} 与媒体库目录 {library_path} 不在同一磁盘，无法硬链接"
             # 存储
             storage_oper = self.__get_storage_oper(d.storage)
             if storage_oper:

app/modules/filemanager/storages/__init__.py

@@ -261,13 +261,12 @@ class StorageBase(metaclass=ABCMeta):
                     for sub_file in sub_files:
                         __snapshot_file(sub_file, current_depth + 1)
                 else:
-                    # 记录文件的完整信息用于比对
-                    if getattr(_fileitm, 'modify_time', 0) > last_snapshot_time:
-                        files_info[_fileitm.path] = {
-                            'size': _fileitm.size or 0,
-                            'modify_time': getattr(_fileitm, 'modify_time', 0),
-                            'type': _fileitm.type
-                        }
+                    # 记录文件的完整信息用于比对（始终包含所有文件，由 compare_snapshots 负责检测变化）
+                    files_info[_fileitm.path] = {
+                        'size': _fileitm.size or 0,
+                        'modify_time': getattr(_fileitm, 'modify_time', 0),
+                        'type': _fileitm.type
+                    }
 
             except Exception as e:
                 logger.debug(f"Snapshot error for {_fileitm.path}: {e}")

app/modules/filemanager/storages/alipan.py

@@ -43,6 +43,9 @@ class AliPan(StorageBase, metaclass=WeakSingleton):
     # 基础url
     base_url = "https://openapi.alipan.com"
 
+    # 阿里云盘目录时间不随子文件变更而更新，默认关闭目录修改时间检查
+    snapshot_check_folder_modtime = settings.ALIPAN_SNAPSHOT_CHECK_FOLDER_MODTIME
+
     # 文件块大小，默认10MB
     chunk_size = 10 * 1024 * 1024
 
@@ -555,7 +558,7 @@ class AliPan(StorageBase, metaclass=WeakSingleton):
         """
         上传单个分片
         """
-        return requests.put(upload_url, data=data)
+        return requests.put(upload_url, data=data, timeout=60.0)
 
     def _list_uploaded_parts(self, drive_id: str, file_id: str, upload_id: str) -> dict:
         """

app/modules/filemanager/storages/alist.py

@@ -9,6 +9,7 @@ from app.core.cache import cached
 from app.core.config import settings, global_vars
 from app.log import logger
 from app.modules.filemanager.storages import StorageBase, transfer_process
+from app.schemas.exception import OperationInterrupted
 from app.schemas.types import StorageSchema
 from app.utils.http import RequestUtils
 from app.utils.singleton import WeakSingleton
@@ -672,7 +673,7 @@ class Alist(StorageBase, metaclass=WeakSingleton):
                 def read(self, size=-1):
                     if global_vars.is_transfer_stopped(path.as_posix()):
                         logger.info(f"【OpenList】{path} 上传已取消！")
-                        return None
+                        raise OperationInterrupted(f"Upload cancelled: {path}")
                     chunk = self.file.read(size)
                     if chunk:
                         self.uploaded_size += len(chunk)
@@ -691,6 +692,8 @@ class Alist(StorageBase, metaclass=WeakSingleton):
                     self.__get_api_url("/api/fs/put"),
                     data=progress_reader,
                 )
+            except OperationInterrupted:
+                return None
             finally:
                 progress_reader.close()
 

app/modules/indexer/parser/bitpt.py

@@ -111,7 +111,7 @@ class BitptSiteUserInfo(SiteParserBase):
     def _parse_message_content(self, html_text) -> Tuple[Optional[str], Optional[str], Optional[str]]:
         pass
 
-    def _parse_user_torrent_seeding_info(self, html_text: str):
+    def _parse_user_torrent_seeding_info(self, html_text: str, **kwargs):
         pass
 
     def parse(self):

app/modules/indexer/parser/nexus_hhanclub.py

@@ -50,15 +50,15 @@ class NexusHhanclubSiteUserInfo(NexusPhpSiteUserInfo):
             if not StringUtils.is_valid_html_element(html):
                 return
             # 加入时间
-            join_at_text = html.xpath('//*[@id="mainContent"]/div/div[2]/div[4]/div[3]/span[2]/text()[1]')
+            join_at_text = html.xpath('//span[contains(text(), "加入日期")]/following-sibling::span/span/@title')
             if join_at_text:
-                self.join_at = StringUtils.unify_datetime_str(join_at_text[0].split(' (')[0].strip())
+                self.join_at = StringUtils.unify_datetime_str(join_at_text[0].strip())
         finally:
             if html is not None:
                 del html
 
     def _get_user_level(self, html):
         super()._get_user_level(html)
-        user_level_path = html.xpath('//*[@id="mainContent"]/div/div[2]/div[2]/div[4]/span[2]/img/@title')
+        user_level_path = html.xpath('//b[contains(@class, "_Name")]/text()')
         if user_level_path:
             self.user_level = user_level_path[0]

app/modules/indexer/parser/tnode.py

@@ -3,6 +3,7 @@ import json
 import re
 from typing import Optional
 
+from app.log import logger
 from app.modules.indexer.parser import SiteParserBase, SiteSchema
 from app.utils.string import StringUtils
 
@@ -63,7 +64,16 @@ class TNodeSiteUserInfo(SiteParserBase):
         """
         解析用户做种信息
         """
-        seeding_info = json.loads(html_text)
+        try:
+            seeding_info = json.loads(html_text)
+        except json.JSONDecodeError as e:
+            logger.warning(f"{self._site_name}: Failed to decode seeding info JSON: {e}")
+            return None
+
+        if not isinstance(seeding_info, dict):
+            logger.warning(f"{self._site_name}: Seeding info payload is not a dictionary")
+            return None
+
         if seeding_info.get("status") != 200:
             return None
 

app/modules/indexer/parser/zhixing.py

@@ -117,7 +117,7 @@ class ZhixingSiteUserInfo(SiteParserBase):
     def _parse_message_content(self, html_text) -> Tuple[Optional[str], Optional[str], Optional[str]]:
         pass
 
-    def _parse_user_torrent_seeding_info(self, html_text: str):
+    def _parse_user_torrent_seeding_info(self, html_text: str, multi_page: bool = False):
         """
         占位，避免抽象类报错
         """

app/modules/jellyfin/jellyfin.py

@@ -569,7 +569,7 @@ class Jellyfin:
             logger.error(f"连接Library/Refresh出错：" + str(e))
             return False
 
-    def get_webhook_message(self, body: any) -> Optional[schemas.WebhookEventInfo]:
+    def get_webhook_message(self, body: Any) -> Optional[schemas.WebhookEventInfo]:
         """
         解析Jellyfin报文
         {

app/modules/plex/plex.py

@@ -549,7 +549,7 @@ class Plex:
             logger.error(f"获取媒体库列表出错：{str(err)}")
         return None
 
-    def get_webhook_message(self, form: any) -> Optional[schemas.WebhookEventInfo]:
+    def get_webhook_message(self, form: Any) -> Optional[schemas.WebhookEventInfo]:
         """
         解析Plex报文
         eventItem  字段的含义

app/modules/qbittorrent/__init__.py

@@ -318,6 +318,7 @@ class QbittorrentModule(_ModuleBase, _DownloaderBase[Qbittorrent]):
                             state="paused" if torrent.get('state') in ("paused", "pausedDL") else "downloading",
                             dlspeed=StringUtils.str_filesize(torrent.get('dlspeed')),
                             upspeed=StringUtils.str_filesize(torrent.get('upspeed')),
+                            tags=torrent.get('tags'),
                             left_time=StringUtils.str_secends(
                                 (torrent.get('total_size') - torrent.get('completed')) / torrent.get(
                                     'dlspeed')) if torrent.get(
@@ -356,6 +357,21 @@ class QbittorrentModule(_ModuleBase, _DownloaderBase[Qbittorrent]):
             return None
         return server.delete_torrents(delete_file=delete_file, ids=hashs)
 
+    def set_torrents_tag(self, hashs: Union[str, list], tags: list,
+                        downloader: Optional[str] = None) -> Optional[bool]:
+        """
+        设置种子标签
+        :param hashs:  种子Hash
+        :param tags:  标签列表
+        :param downloader:  下载器
+        :return: bool
+        """
+        server: Qbittorrent = self.get_instance(downloader)
+        if not server:
+            return None
+        server.set_torrents_tag(ids=hashs, tags=tags)
+        return True
+
     def start_torrents(self, hashs: Union[list, str],
                        downloader: Optional[str] = None) -> Optional[bool]:
         """

app/modules/qqbot/__init__.py

@@ -0,0 +1,180 @@
+"""
+QQ Bot 通知模块
+基于 QQ 开放平台，支持主动消息推送和 Gateway 接收消息
+注意：用户/群需曾与机器人交互过才能收到主动消息，且每月有配额限制
+"""
+
+import json
+from typing import Optional, List, Tuple, Union, Any
+
+from app.core.context import MediaInfo, Context
+from app.log import logger
+from app.modules import _ModuleBase, _MessageBase
+from app.modules.qqbot.qqbot import QQBot
+from app.schemas import CommingMessage, MessageChannel, Notification
+from app.schemas.types import ModuleType
+
+
+class QQBotModule(_ModuleBase, _MessageBase[QQBot]):
+    """QQ Bot 通知模块"""
+
+    def init_module(self) -> None:
+        super().init_service(service_name=QQBot.__name__.lower(), service_type=QQBot)
+        self._channel = MessageChannel.QQ
+
+    @staticmethod
+    def get_name() -> str:
+        return "QQ"
+
+    @staticmethod
+    def get_type() -> ModuleType:
+        return ModuleType.Notification
+
+    @staticmethod
+    def get_subtype() -> MessageChannel:
+        return MessageChannel.QQ
+
+    @staticmethod
+    def get_priority() -> int:
+        return 10
+
+    def stop(self) -> None:
+        for client in self.get_instances().values():
+            if hasattr(client, "stop"):
+                client.stop()
+
+    def test(self) -> Optional[Tuple[bool, str]]:
+        if not self.get_instances():
+            return None
+        for name, client in self.get_instances().items():
+            if not client.get_state():
+                return False, f"QQ Bot {name} 未就绪"
+        return True, ""
+
+    def init_setting(self) -> Tuple[str, Union[str, bool]]:
+        pass
+
+    def message_parser(
+        self, source: str, body: Any, form: Any, args: Any
+    ) -> Optional[CommingMessage]:
+        """
+        解析 Gateway 转发的 QQ 消息
+        body 格式: {"type": "C2C_MESSAGE_CREATE"|"GROUP_AT_MESSAGE_CREATE", "content": "...", "author": {...}, "id": "...", ...}
+        """
+        client_config = self.get_config(source)
+        if not client_config:
+            return None
+        try:
+            if isinstance(body, bytes):
+                msg_body = json.loads(body)
+            elif isinstance(body, dict):
+                msg_body = body
+            else:
+                return None
+        except (json.JSONDecodeError, TypeError) as err:
+            logger.debug(f"解析 QQ 消息失败: {err}")
+            return None
+
+        msg_type = msg_body.get("type")
+        content = (msg_body.get("content") or "").strip()
+        if not content:
+            return None
+
+        if msg_type == "C2C_MESSAGE_CREATE":
+            author = msg_body.get("author", {})
+            user_openid = author.get("user_openid", "")
+            if not user_openid:
+                return None
+            logger.info(f"收到 QQ 私聊消息: userid={user_openid}, text={content[:50]}...")
+            return CommingMessage(
+                channel=MessageChannel.QQ,
+                source=client_config.name,
+                userid=user_openid,
+                username=user_openid,
+                text=content,
+            )
+        elif msg_type == "GROUP_AT_MESSAGE_CREATE":
+            author = msg_body.get("author", {})
+            member_openid = author.get("member_openid", "")
+            group_openid = msg_body.get("group_openid", "")
+            # 群聊用 group:group_openid 作为 userid，便于回复时识别
+            userid = f"group:{group_openid}" if group_openid else member_openid
+            logger.info(f"收到 QQ 群消息: group={group_openid}, userid={member_openid}, text={content[:50]}...")
+            return CommingMessage(
+                channel=MessageChannel.QQ,
+                source=client_config.name,
+                userid=userid,
+                username=member_openid or group_openid,
+                text=content,
+            )
+        return None
+
+    def post_message(self, message: Notification, **kwargs) -> None:
+        for conf in self.get_configs().values():
+            if not self.check_message(message, conf.name):
+                continue
+            targets = message.targets
+            userid = message.userid
+            if not userid and targets:
+                userid = targets.get("qq_userid") or targets.get("qq_openid")
+                if not userid:
+                    userid = targets.get("qq_group_openid") or targets.get("qq_group")
+                    if userid:
+                        userid = f"group:{userid}"
+            # 无 userid 且无默认配置时，由 client 向曾发过消息的用户/群广播
+            client: QQBot = self.get_instance(conf.name)
+            if client:
+                client.send_msg(
+                    title=message.title,
+                    text=message.text,
+                    image=message.image,
+                    link=message.link,
+                    userid=userid,
+                    targets=targets,
+                )
+
+    def post_medias_message(self, message: Notification, medias: List[MediaInfo]) -> None:
+        for conf in self.get_configs().values():
+            if not self.check_message(message, conf.name):
+                continue
+            targets = message.targets
+            userid = message.userid
+            if not userid and targets:
+                userid = targets.get("qq_userid") or targets.get("qq_openid")
+                if not userid:
+                    g = targets.get("qq_group_openid") or targets.get("qq_group")
+                    if g:
+                        userid = f"group:{g}"
+            client: QQBot = self.get_instance(conf.name)
+            if client:
+                client.send_medias_msg(
+                    medias=medias,
+                    userid=userid,
+                    title=message.title,
+                    link=message.link,
+                    targets=targets,
+                )
+
+    def post_torrents_message(
+        self, message: Notification, torrents: List[Context]
+    ) -> None:
+        for conf in self.get_configs().values():
+            if not self.check_message(message, conf.name):
+                continue
+            targets = message.targets
+            userid = message.userid
+            if not userid and targets:
+                userid = targets.get("qq_userid") or targets.get("qq_openid")
+                if not userid:
+                    g = targets.get("qq_group_openid") or targets.get("qq_group")
+                    if g:
+                        userid = f"group:{g}"
+            client: QQBot = self.get_instance(conf.name)
+            if client:
+                client.send_torrents_msg(
+                    torrents=torrents,
+                    userid=userid,
+                    title=message.title,
+                    link=message.link,
+                    targets=targets,
+                )

app/modules/qqbot/api.py

@@ -0,0 +1,206 @@
+"""
+QQ Bot API - Python 实现
+参考 QQ 开放平台官方 API: https://bot.q.qq.com/wiki/develop/api/
+"""
+
+import time
+from typing import Optional, Literal
+
+from app.log import logger
+from app.utils.http import RequestUtils
+
+API_BASE = "https://api.sgroup.qq.com"
+TOKEN_URL = "https://bots.qq.com/app/getAppAccessToken"
+
+# Token 缓存
+_cached_token: Optional[dict] = None
+
+
+def get_access_token(app_id: str, client_secret: str) -> str:
+    """
+    获取 AccessToken（带缓存，提前 5 分钟刷新）
+    """
+    global _cached_token
+    now_ms = int(time.time() * 1000)
+    if _cached_token and now_ms < _cached_token["expires_at"] - 5 * 60 * 1000 and _cached_token["app_id"] == app_id:
+        return _cached_token["token"]
+
+    if _cached_token and _cached_token["app_id"] != app_id:
+        _cached_token = None
+
+    try:
+        resp = RequestUtils(timeout=30).post_res(
+            TOKEN_URL,
+            json={"appId": app_id, "clientSecret": client_secret},  # QQ API 使用 camelCase
+            headers={"Content-Type": "application/json"},
+        )
+        if not resp or not resp.json():
+            raise ValueError("Failed to get access_token: empty response")
+        data = resp.json()
+        token = data.get("access_token")
+        expires_in = data.get("expires_in", 7200)
+        if not token:
+            raise ValueError(f"Failed to get access_token: {data}")
+
+        # expires_in 可能为字符串，统一转为 int
+        expires_in = int(expires_in) if expires_in is not None else 7200
+
+        _cached_token = {
+            "token": token,
+            "expires_at": now_ms + expires_in * 1000,
+            "app_id": app_id,
+        }
+        logger.debug(f"QQ API: Token cached for app_id={app_id}")
+        return token
+    except Exception as e:
+        logger.error(f"QQ API: get_access_token failed: {e}")
+        raise
+
+
+def clear_token_cache() -> None:
+    """清除 Token 缓存"""
+    global _cached_token
+    _cached_token = None
+
+
+def _api_request(
+    access_token: str,
+    method: str,
+    path: str,
+    body: Optional[dict] = None,
+    timeout: int = 30,
+) -> dict:
+    """通用 API 请求"""
+    url = f"{API_BASE}{path}"
+    headers = {
+        "Authorization": f"QQBot {access_token}",
+        "Content-Type": "application/json",
+    }
+    try:
+        if method.upper() == "GET":
+            resp = RequestUtils(timeout=timeout).get_res(url, headers=headers)
+        else:
+            resp = RequestUtils(timeout=timeout).post_res(
+                url, json=body or {}, headers=headers
+            )
+        if not resp:
+            raise ValueError("Empty response")
+        data = resp.json()
+        status = getattr(resp, "status_code", 0)
+        if status and status >= 400:
+            raise ValueError(f"API Error [{path}]: {data.get('message', data)}")
+        return data
+    except Exception as e:
+        logger.error(f"QQ API: {method} {path} failed: {e}")
+        raise
+
+
+def send_proactive_c2c_message(
+    access_token: str,
+    openid: str,
+    content: str,
+    use_markdown: bool = False,
+) -> dict:
+    """
+    主动发送 C2C 单聊消息（不需要 msg_id）
+    注意：每月限 4 条/用户，且用户必须曾与机器人交互过
+    :param access_token: 访问令牌
+    :param openid: 用户 openid
+    :param content: 消息内容
+    :param use_markdown: 是否使用 Markdown 格式（需机器人开通 Markdown 能力）
+    """
+    if not content or not content.strip():
+        raise ValueError("主动消息内容不能为空")
+    content = content.strip()
+    body = {"markdown": {"content": content}, "msg_type": 2} if use_markdown else {"content": content, "msg_type": 0}
+    return _api_request(
+        access_token, "POST", f"/v2/users/{openid}/messages", body
+    )
+
+
+def send_proactive_group_message(
+    access_token: str,
+    group_openid: str,
+    content: str,
+    use_markdown: bool = False,
+) -> dict:
+    """
+    主动发送群聊消息（不需要 msg_id）
+    注意：每月限 4 条/群，且群必须曾与机器人交互过
+    :param access_token: 访问令牌
+    :param group_openid: 群聊 openid
+    :param content: 消息内容
+    :param use_markdown: 是否使用 Markdown 格式（需机器人开通 Markdown 能力）
+    """
+    if not content or not content.strip():
+        raise ValueError("主动消息内容不能为空")
+    content = content.strip()
+    body = {"markdown": {"content": content}, "msg_type": 2} if use_markdown else {"content": content, "msg_type": 0}
+    return _api_request(
+        access_token, "POST", f"/v2/groups/{group_openid}/messages", body
+    )
+
+
+def send_c2c_message(
+    access_token: str,
+    openid: str,
+    content: str,
+    msg_id: Optional[str] = None,
+) -> dict:
+    """被动回复 C2C 单聊消息（1 小时内最多 4 次）"""
+    body = {"content": content, "msg_type": 0, "msg_seq": 1}
+    if msg_id:
+        body["msg_id"] = msg_id
+    return _api_request(
+        access_token, "POST", f"/v2/users/{openid}/messages", body
+    )
+
+
+def send_group_message(
+    access_token: str,
+    group_openid: str,
+    content: str,
+    msg_id: Optional[str] = None,
+) -> dict:
+    """被动回复群聊消息（1 小时内最多 4 次）"""
+    body = {"content": content, "msg_type": 0, "msg_seq": 1}
+    if msg_id:
+        body["msg_id"] = msg_id
+    return _api_request(
+        access_token, "POST", f"/v2/groups/{group_openid}/messages", body
+    )
+
+
+def get_gateway_url(access_token: str) -> str:
+    """
+    获取 WebSocket Gateway URL
+    """
+    data = _api_request(access_token, "GET", "/gateway")
+    url = data.get("url")
+    if not url:
+        raise ValueError("Gateway URL not found in response")
+    return url
+
+
+def send_message(
+    access_token: str,
+    target: str,
+    content: str,
+    msg_type: Literal["c2c", "group"] = "c2c",
+    msg_id: Optional[str] = None,
+) -> dict:
+    """
+    统一发送接口
+    :param access_token: 访问令牌
+    :param target: openid（c2c）或 group_openid（group）
+    :param content: 消息内容
+    :param msg_type: c2c 单聊 / group 群聊
+    :param msg_id: 可选，被动回复时传入原消息 id
+    """
+    if msg_id:
+        if msg_type == "c2c":
+            return send_c2c_message(access_token, target, content, msg_id)
+        return send_group_message(access_token, target, content, msg_id)
+    if msg_type == "c2c":
+        return send_proactive_c2c_message(access_token, target, content)
+    return send_proactive_group_message(access_token, target, content)